💡 ヒント：最適な体験を得るために、Web UIコンソールを通じてビジュアルに認証管理を行うことを推奨します。

🌐 Web UI クイック認証 (推奨)

Web UI管理インターフェースでは、極めて迅速に認証設定を完了できます：

1. 認証の生成：「プロバイダープール」 ページまたは 「設定管理」 ページで、対応するプロバイダー（Codexなど）の右上にある 「認証生成」 ボタンをクリックします。
2. スキャン/ログイン：認証ダイアログが表示されるので、「ブラウザで開く」 をクリックしてログイン検証を行います。Antigravityの場合はGoogleアカウントの認証を完了させます。
3. 自動保存：認証成功後、システムは自動的に資格情報を取得し、configs/ の対応するディレクトリに保存します。「設定ファイル」 ページで新しく生成された資格情報を確認できます。
4. ビジュアル管理：Web UIでいつでも資格情報のアップロードや削除、または 「クイック関連付け」 機能を使用して既存の資格情報ファイルをワンクリックでプロバイダーにバインドできます。

Antigravity OAuth設定

1. 個人アカウント：個人アカウントは個別に認証が必要ですが、申請チャンネルは閉鎖されています。
2. Pro会員：Antigravity は一時的に Pro 会員に開放されています。まず Pro 会員を購入する必要があります。
3. 組織アカウント：組織アカウントは個別に認証が必要です。管理者に連絡して認証を取得してください。

Kiro API設定

1. 環境準備：Kiroクライアントをダウンロードしてインストール
2. 認証完了：クライアントでアカウントにログインし、kiro-auth-token.json認証情報ファイルを生成
3. ベストプラクティス：Claude Codeとの併用を推奨、最適な体験を得られる
4. 重要なお知らせ：Kiroサービス使用ポリシーが更新されました、最新の使用制限と条件については公式ウェブサイトをご確認ください。

Kiro 拡張思考 (Claude モデル)

AIClient2API は、claude-kiro-oauth にルーティングされた Claude 互換リクエスト (/v1/messages) または OpenAI 互換リクエスト (/v1/chat/completions) を使用する場合、Kiro 拡張思考をサポートします。

Claude 互換インターフェース (/v1/messages):

curl http://localhost:3000/claude-kiro-oauth/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "thinking": { "type": "enabled", "budget_tokens": 10000 },
    "messages": [{ "role": "user", "content": "この問題をステップバイステップで解決してください。" }]
  }'

OpenAI 互換インターフェース (/v1/chat/completions):

curl http://localhost:3000/claude-kiro-oauth/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{ "role": "user", "content": "この問題をステップバイステップで解決してください。" }],
    "extra_body": {
      "anthropic": {
        "thinking": { "type": "enabled", "budget_tokens": 10000 }
      }
    }
  }'

アダプティブモード:

• Claude: "thinking": { "type": "adaptive", "effort": "high" }
• OpenAI: "extra_body.anthropic.thinking": { "type": "adaptive", "effort": "high" }

注意：

• budget_tokens は [1024, 24576] の範囲に制限されます（省略または無効な場合はデフォルトの 20000 が適用されます）。
• トークンの取得/リフレッシュ/プールローテーションメカニズムは変更されません。

Codex OAuth設定

1. 認証の生成：Web UIの「プロバイダープール」または「設定管理」ページで、Codexの「認証生成」ボタンをクリック
2. ブラウザログイン：システムがOpenAI Codex認証ページを開き、OAuthログインを完了
3. 自動保存：認証成功後、システムがCodexのOAuth認証情報ファイルを自動保存
4. コールバックポート：OAuthコールバックポート 1455 が占有されていないことを確認
5. 画像 Helper モデル：gpt-image-2 / gpt-image-2-fast は、image_generation ツールをサポートする Codex メインモデルを通じて画像を生成します。configs/config.json に "CODEX_IMAGE_HELPER_MODEL": "gpt-5.6-sol" を設定するとグローバルに指定でき、configs/provider_pools.json の各 Codex ノードに同じフィールドを設定すると上書きできます（ノード設定が優先）。アカウントで利用可能かつ image_generation 対応のメインモデルを指定してください。gpt-image-* は指定できず、空白または文字列以外の値は gpt-5.6-sol にフォールバックします。

Grok CLI OAuth設定

1. 認証の生成：Web UIの「プロバイダープール」または「設定管理」ページで、Grok CLIの「認証生成」ボタンをクリック
2. ブラウザログイン：システムがxAI認証ページを開き、OAuthログインを完了
3. 自動保存：認証成功後、システムがGrok CLI OAuth認証情報ファイルを configs/grok-cli/ に自動保存
4. コールバックポート：OAuthコールバックポート 56121 が占有されていないことを確認

Grok Cookie/SSO 設定

1. SSOトークンの取得: Grok公式サイトにログインし、ブラウザの開発者ツールの Application -> Cookies から sso の値をコピーします。
2. 設定の入力: Web UIの「設定管理」ページ、または設定ファイルを直接編集して、トークンを GROK_COOKIE_TOKEN に入力します。
3. サポート機能:
   • チャットおよび思考モデル (Grok Thinking)
   • 画像生成 (Grok Imagine)
   • 動画生成 (Grok Video)
4. 注意事項: ブロックを避けるため、GROK_USER_AGENT がCookie取得時と同じブラウザのものであることを確認してください。

アカウントプール管理設定

1. プール設定ファイルの作成：provider_pools.json.example を参考に設定ファイルを作成します
2. プールパラメータの設定：config.json で PROVIDER_POOLS_FILE_PATH を設定し、プール設定ファイルを指定します
3. 起動パラメータ設定：--provider-pools-file <path> パラメータを使用してプール設定ファイルのパスを指定します
4. ヘルスチェック：システムは定期的にヘルスチェックを自動実行し、健全でないプロバイダーを使用しません

各サービスの認証情報ファイルのデフォルト保存場所：

説明：~はユーザーホームディレクトリを表します（Windows: C:\Users\ユーザー名、Linux/macOS: /home/ユーザー名または/Users/ユーザー名）

カスタムパス：設定ファイルの関連パラメータまたは環境変数でカスタム保存場所を指定可能

1. プロキシ設定

本プロジェクトは柔軟なプロキシ設定をサポートしており、異なるプロバイダーに統一プロキシを設定したり、プロバイダー独自のプロキシ済みエンドポイントを使用したりできます。

設定方法：

1. Web UI設定（推奨）：便利な設定管理

Web UIの「設定管理」ページで、すべてのプロキシオプションを視覚的に設定できます：

• 統一プロキシ：「プロキシ設定」エリアにプロキシアドレスを入力し、プロキシを使用するプロバイダーにチェックを入れます
• プロバイダーエンドポイント：各プロバイダーの設定エリアで、Base URLをプロキシ済みエンドポイントに直接変更します
• 「設定を保存」をクリック：サービスを再起動せずに即座に有効になります

1. 統一プロキシ設定：グローバルプロキシを設定し、どのプロバイダーがそれを使用するかを指定します

   • Web UI設定：「設定管理」ページの「プロキシ設定」エリアにプロキシアドレスを入力し、プロキシを使用するプロバイダーにチェックを入れます
   • 設定ファイル：configs/config.jsonで設定

   {
     "PROXY_URL": "http://127.0.0.1:7890",
      "PROXY_ENABLED_PROVIDERS": [
        "gemini-antigravity",
        "claude-kiro-oauth",
        "grok-web"
      ]
    }
   

2. プロバイダー独自のプロキシ済みエンドポイント：一部のプロバイダー（OpenAI、Claudeなど）はプロキシ済みAPIエンドポイントの設定をサポートしています

   • Web UI設定：「設定管理」ページの各プロバイダー設定エリアで、対応するBase URLを変更します
   • 設定ファイル：configs/config.jsonで設定

   {
     "OPENAI_BASE_URL": "https://your-proxy-endpoint.com/v1",
     "CLAUDE_BASE_URL": "https://your-proxy-endpoint.com/v1"
   }
   

サポートされるプロキシタイプ：

• HTTPプロキシ：http://127.0.0.1:7890
• HTTPSプロキシ：https://127.0.0.1:7890
• SOCKS5プロキシ：socks5://127.0.0.1:1080

使用シナリオ：

• ネットワーク制限環境：Google、OpenAIなどのサービスに直接アクセスできないネットワーク環境で使用
• ハイブリッド設定：一部のプロバイダーは統一プロキシを使用し、他はプロバイダー独自のプロキシ済みエンドポイントを使用
• 柔軟な切り替え：Web UIでいつでも特定のプロバイダーのプロキシを有効化/無効化できます

注意事項：

• プロキシ設定の優先順位：統一プロキシ設定 > プロバイダー独自エンドポイント > 直接接続
• プロキシサービスが安定して利用可能であることを確認してください。そうでない場合、サービス品質に影響する可能性があります
• SOCKS5プロキシは通常、HTTPプロキシよりもパフォーマンスが優れています

2. モデルフィルタリング設定

notSupportedModels 設定を通じてサポートされていないモデルを除外でき、システムは自動的にこれらのプロバイダーをスキップします。

設定方法：provider_pools.json でプロバイダーに notSupportedModels フィールドを追加：

{
  "gemini-antigravity": [
    {
      "uuid": "provider-1",
      "notSupportedModels": ["gemini-3.0-pro", "gemini-3.5-flash"],
      "checkHealth": true
    }
  ]
}

動作原理：

• 特定のモデルをリクエストする際、システムは自動的にそのモデルをサポートしていないと設定されたプロバイダーをフィルタリングします
• そのモデルをサポートするプロバイダーのみがリクエストを処理するために選択されます

使用シナリオ：

• 一部のアカウントは割り当てまたは権限の制限により特定のモデルにアクセスできない
• 異なるアカウントに異なるモデルアクセス権限を割り当てる必要がある

3. クロスタイプフォールバック設定

あるProvider Type（例：claude-kiro-oauth）のすべてのアカウントが429割り当て制限により枯渇したり、unhealthyとマークされた場合、システムは直接エラーを返すのではなく、互換性のある別のProvider Type（例：claude-custom）に自動的にフォールバックできます。

設定方法：configs/config.json に providerFallbackChain 設定を追加：

{
  "providerFallbackChain": {
    "claude-kiro-oauth": ["claude-custom"],
    "claude-custom": ["claude-kiro-oauth"]
  }
}

動作原理：

1. メインのProvider Typeプールからhealthyなアカウントを選択しようとします
2. そのタイプのすべてのアカウントがunhealthyまたは429を返す場合：
   • 設定されたフォールバックタイプを検索
   • フォールバックタイプがリクエストされたモデルをサポートしているか確認（プロトコル互換性チェック）
   • フォールバックタイプのプールからhealthyなアカウントを選択
3. 多段階降格チェーンをサポート：claude-kiro-oauth → claude-custom → openai-custom
4. すべてのフォールバックタイプも利用できない場合のみエラーを返します

使用シナリオ：

• バッチタスクシナリオでは、単一のProvider Typeの無料RPD割り当てが短時間で簡単に枯渇する可能性があります
• クロスタイプフォールバックを通じて、複数のProviderの独立した割り当てを十分に活用し、全体的な可用性とスループットを向上させることができます

注意事項：

• フォールバックはプロトコル互換タイプ間でのみ発生します（例：gemini-* 間、claude-* 間）
• システムは自動的にターゲットProvider Typeがリクエストされたモデルをサポートしているか確認します

4. TLS Sidecar (Bypass 403/Cloudflare)

Grok などの TLS 指紋（JA3/JA4）を厳密に検証するサービスに対して、本プロジェクトは Go uTLS ベースの Sidecar プロキシを統合しています。これにより、ブラウザの TLS 特徴をシミュレートし、403 Forbidden エラーを効果的に解決します。

設定手順:

1. バイナリのビルド: TLS シミュレーションには Go 言語のサポートが必要です。まず sidecar をビルドする必要があります：

   cd tls-sidecar
   go build -o tls-sidecar
   

   Windows ユーザーは、ビルド後、生成された tls-sidecar.exe が tls-sidecar/ またはルートディレクトリにあることを確認してください。

2. 設定の有効化: Web UI の「設定管理」ページで TLS Sidecar を有効にするか、configs/config.json を編集します：

   {
     "TLS_SIDECAR_ENABLED": true,
     "TLS_SIDECAR_PORT": 9090
   }
   

3. 動作原理:

   • 有効にすると、システムは自動的に Go プロセスを起動し管理します。
   • 特定のプロバイダー（Grok など）へのリクエストは、自動的に Sidecar にルーティングされます。
   • Sidecar は最新の Chrome 指紋を使用して TLS ハンドシェイクを行い、HTTP/2 の自動ネゴシエーションをサポートします。

注意事項:

• ローカル実行には Go 環境 (1.20+) が必要です。
• Docker ユーザー: イメージには既にプリビルド済みのバイナリが含まれています。設定で有効にするだけでよく、手動でのビルドは不要です。

1. OAuth認証失敗

問題の説明：「認証生成」をクリックした後、ブラウザで認証ページが開きますが、認証が失敗するか完了できません。

解決策：

• ネットワーク接続を確認：Google、アリババクラウドなどのサービスに正常にアクセスできることを確認
• ポート占有を確認：OAuthコールバックには特定のポートが必要です（Antigravity: 8086, Codex: 1455, Grok CLI: 56121, Kiro: 19876-19880）、これらのポートが占有されていないことを確認
• ブラウザキャッシュをクリア：シークレットモードを使用するか、ブラウザキャッシュをクリアして再試行
• ファイアウォール設定を確認：ファイアウォールがローカルコールバックポートへのアクセスを許可していることを確認
• Dockerユーザー：すべてのOAuthコールバックポートが正しくマッピングされていることを確認

2. ポートが使用中

問題の説明：サービス起動時にポートが既に使用中と表示されます（例：EADDRINUSE）。

解決策：

# Windows - ポートを占有しているプロセスを検索
netstat -ano | findstr :3000
# タスクマネージャーで対応するPIDのプロセスを終了

# Linux/macOS - ポートを占有しているプロセスを検索して終了
lsof -i :3000
kill -9 <PID>

または configs/config.json のポート設定を変更して別のポートを使用します。

3. Dockerコンテナが起動しない

問題の説明：Dockerコンテナの起動に失敗するか、すぐに終了します。

解決策：

• ログを確認：docker logs aiclient2api でエラーメッセージを確認
• マウントパスを確認：-v パラメータのローカルパスが存在し、読み書き権限があることを確認
• ポート競合を確認：マッピングされたすべてのポートがホストで占有されていないことを確認
• イメージを再取得：docker pull justlikemaki/aiclient-2-api:latest

4. 認証情報ファイルが認識されない

問題の説明：認証情報ファイルをアップロードまたは設定した後、システムが認識できないかフォーマットエラーと表示されます。

解決策：

• ファイル形式を確認：認証情報ファイルが有効なJSON形式であることを確認
• ファイルパスを確認：ファイルパスが正しいことを確認、Dockerユーザーはファイルがマウントディレクトリ内にあることを確認
• ファイル権限を確認：サービスが認証情報ファイルを読み取る権限があることを確認
• 認証情報を再生成：認証情報が期限切れの場合、OAuth認証を再度実行

5. リクエストが429エラーを返す

問題の説明：APIリクエストが頻繁に429 Too Many Requestsエラーを返します。

解決策：

• アカウントプールを設定：provider_pools.json に複数のアカウントを追加し、ポーリングメカニズムを有効化
• フォールバックを設定：config.json で providerFallbackChain を設定し、クロスタイプ降格を実現
• 429クールダウンを有効化：RATE_LIMIT_COOLDOWN_ENABLED を true にし、RATE_LIMIT_COOLDOWN_MS で既定の冷却時間を設定すると、レート制限されたアカウントは一時的にプールから外れ、自動的に復帰します
• リクエスト頻度を下げる：リクエスト間隔を適切に増やし、レート制限のトリガーを回避
• 割り当てリセットを待つ：無料割り当ては通常、毎日または毎分リセットされます

6. モデルが利用できないかエラーを返す

問題の説明：特定のモデルをリクエストするとエラーが返されるか、モデルが利用できないと表示されます。

解決策：

• モデル名を確認：正しいモデル名を使用していることを確認（大文字小文字を区別）
• プロバイダーサポートを確認：現在設定されているプロバイダーがそのモデルをサポートしていることを確認
• アカウント権限を確認：一部の高度なモデルは特定のアカウント権限が必要な場合があります
• モデルフィルタリングを設定：notSupportedModels を使用してサポートされていないモデルを除外

7. Web UIにアクセスできない

問題の説明：ブラウザで http://localhost:3000 を開けません。

解決策：

• サービス状態を確認：サービスが正常に起動したことを確認、ターミナル出力を確認
• ポートマッピングを確認：Dockerユーザーは -p 3000:3000 パラメータが正しいことを確認
• 別のアドレスを試す：http://127.0.0.1:3000 へのアクセスを試す
• ファイアウォールを確認：ファイアウォールがポート3000へのアクセスを許可していることを確認

8. ストリーミングレスポンスが中断される

問題の説明：ストリーミング出力を使用すると、レスポンスが途中で中断されるか不完全になります。

解決策：

• ネットワーク安定性を確認：ネットワーク接続が安定していることを確認
• タイムアウトを増やす：クライアント設定でリクエストタイムアウトを増やす
• プロキシ設定を確認：プロキシを使用している場合、プロキシが長時間接続をサポートしていることを確認
• サービスログを確認：エラーメッセージがないか確認

9. 設定変更が反映されない

問題の説明：Web UIで設定を変更した後、サービスの動作が変わりません。

解決策：

• ページを更新：変更後にWeb UIページを更新
• 保存状態を確認：設定が正常に保存されたことを確認（プロンプトメッセージを確認）
• サービスを再起動：一部の設定はサービスの再起動が必要な場合があります
• 設定ファイルを確認：configs/config.json を直接確認して変更が書き込まれていることを確認

10. APIが404を返す

解決策：

• エンドポイントパスを確認：/v1/chat/completions などの正しいエンドポイントパスを使用していることを確認
• クライアントの自動補完を確認：一部のクライアント（Cherry-Studio、NextChatなど）はBase URLの後にパス（/v1/chat/completions など）を自動的に追加し、パスの重複を引き起こします。コンソールで実際のリクエストURLを確認し、冗长なパス部分を削除してください
• サービス状態を確認：サービスが正常に起動していることを確認、http://localhost:3000 にアクセスしてWeb UIを確認
• ポート設定を確認：リクエストが正しいポート（デフォルト3000）に送信されていることを確認
• 利用可能なルートを確認：Web UIダッシュボードページの「インタラクティブルーティング例」ですべての利用可能なエンドポイントを確認

11. Unauthorized: API key is invalid or missing

問題の説明：APIエンドポイントを呼び出すと Unauthorized: API key is invalid or missing. エラーが返されます。

解決策：

• API Key設定を確認：configs/config.json またはWeb UIでAPI Keyが正しく設定されていることを確認
• リクエストヘッダー形式を確認：リクエストに正しい形式のAuthorizationヘッダーが含まれていることを確認、例：Authorization: Bearer your-api-key
• サービスログを確認：Web UIの「リアルタイムログ」ページで詳細なエラーメッセージを確認し、具体的な原因を特定

12. No available and healthy providers for type

問題の説明：APIを呼び出すと No available and healthy providers for type xxx エラーが返されます。

解決策：

• プロバイダー状態を確認：Web UIの「プロバイダープール」ページで対応するタイプのプロバイダーが健全な状態にあるか確認
• 認証情報の有効性を確認：OAuth認証情報が期限切れでないことを確認、期限切れの場合は認証を再生成
• 割り当て制限を確認：一部のプロバイダーは無料割り当て上限に達している可能性があります。割り当てリセットを待つか、より多くのアカウントを追加
• フォールバックを有効化：config.json で providerFallbackChain を設定し、主プロバイダーが利用できない場合に自動的にバックアッププロバイダーに切り替え
• 詳細ログを確認：Web UIの「リアルタイムログ」ページで具体的なヘルスチェック失敗の原因を確認

13. リクエストが403 Forbiddenエラーを返す

問題の説明：APIリクエストが403 Forbiddenエラーを返します。

解決策：

• TLS Sidecar の有効化：Grok などのサービスにおいて、403 エラーは TLS 指紋のブロックが原因であることが多いです。高度な設定 - TLS Sidecar を参照して Sidecar を有効にし、ビルドしてください。
• ノード状態を確認：Web UIの「プロバイダープール」ページでノード状態が正常（ヘルスチェック合格）であれば、このエラーは無視できます。システムが自動的に処理します
• アカウント権限を確認：使用しているアカウントがリクエストされたモデルまたはサービスにアクセスする権限があることを確認
• API Key権限を確認：一部のプロバイダーのAPI Keyにはアクセス範囲の制限がある場合があります。Keyに十分な権限があることを確認
• 地域制限を確認：一部のサービスには地域アクセス制限がある場合があります。プロキシまたはVPNの使用を試してください
• 認証情報の状態を確認：OAuth認証情報が取り消されたり期限切れになっている可能性があります。認証の再生成を試してください
• リクエスト頻度を確認：一部のプロバイダーはリクエスト頻度に厳しい制限があります。リクエスト頻度を下げて再試行
• プロバイダードキュメントを確認：対応するプロバイダーの公式ドキュメントにアクセスして、具体的なアクセス制限と要件を理解

14. なぜ「OAuthトークンの自動更新」を有効にする必要があるのですか？

問題の説明：トークンの自動更新機能が必要かどうかがわからない。

解決策： OAuthトークン（Gemini、Antigravity、Codexなど）には通常、有効期限（例：1時間）があります。

• 有効な場合：システムはバックグラウンドで期限が切れる前にトークンを自動的にチェックして更新します。これにより、24時間365日の安定したAPIサービスが保証され、トークンの期限切れによる 401 Unauthorized や 403 Forbidden エラーを回避できます。
• 無効な場合：トークンが期限切れになると、システムは新しいトークンを自動的に取得できず、手動で再度OAuth認証を行うまでAPIリクエストが失敗します。

15. 「モデルプロバイダーのプリロード」が未有効の場合、トークンの維持にどのような影響がありますか？

問題の説明：「モデルプロバイダーのプリロード」設定の役割と、それがトークンの更新にどう影響するかがわからない。

解決策： システムは、アクティブなプールにロードされているプロバイダーに対してのみ自動更新タスクを実行します。

• 影響：設定で特定のプロバイダーを「モデルプロバイダーのプリロード」として選択していない場合、システム起動時にそのプロバイダーは初期化されません。プールに含まれていないため、バックグラウンド更新タスクはそのプロバイダーのトークンを処理しません。
• 結果：そのプロバイダーを長時間使用しない場合、トークンはバックグラウンドで静かに期限切れになります。たまに特定のルートを介して呼び出すと、トークン切れによりリクエストが失敗します。
• 推奨事項：頻繁に使用し、アクティブな状態を維持する必要があるプロバイダーは、必ず「モデルプロバイダーのプリロード」で選択してください。