| 症状 | 原因 / 対処 |
|---|---|
ChatGPT auth not found; run codex login |
shunt が ~/.codex/auth.json を読めない。codex login を実行。 |
マッピングされたモデルで authentication_error |
プロバイダー認証情報が期限切れ／不在 — codex login を再実行するか OPENAI_API_KEY をエクスポート。shunt はバックエンドの本当の detail メッセージを表面化します。 |
| Code Assist がストリームを閉じたとき Gemini が完了ではなく失敗する | Gemini の成功レスポンスには、サポートされる明示的な provider finish と正常な transport closure の両方が必要です。その finish のない EOF または [DONE]、不正な UTF-8、malformed JSON またはサポート対象外フィールド、oversized data、複数 candidate、terminal 後の data、truncated response は明示的に失敗します。Streaming と unary mode は同じ terminal および provider-error の意味を適用し、embedded provider error を synthetic success に変換しません。 |
| Gemini tool history が dispatch 前に拒否される | Client に見える tool_use ID は真正な Code Assist call pairing と、Gemini 3 では thoughtSignature を保持します。対応する ID を tool_result で返してください。Malformed、duplicate、orphaned な metadata は repair せず拒否されます。別の provider から持ち込まれた tool call（例: failover 後）には Gemini の signature がないため、Gemini 3 ではそのターンの最初の call を拒否せず、Google が文書化した placeholder signature を付けて送信します。有効な result は次のリクエストの functionResponse になります。shunt はこの metadata を persist したり write back したりしません。 |
| Gemini の transient status が同じ upstream に再試行されない | Gemini generation は non-idempotent です。レスポンス header より前に発生したことが証明された transient connection または timeout failure だけが、同じ選択済み token、project、payload で再試行できます。返された status とすべての body-time failure は、同じ upstream に再試行せずそのまま表面化します。例外として、単一 credential の auth = "antigravity_oauth" provider は、返された 429/502/503/504/529 status を provider の retry policy に従って引き続き再試行します。pool された Antigravity account は再試行しません。 |
400 … model is not supported when using Codex with a ChatGPT account |
-codex スラッグ（またはアカウントが entitle されていないもの）を使った。models.json の entitle されたスラッグ（例 gpt-5.6-sol、gpt-5.5）を使うか upstream_model を設定。 |
ゲートウェイログ upstream refused the account; skipping it until the window ends（または You have reached your specified API usage limits、Your credit balance is too low と書かれた 400/402） |
Anthropic プロトコルのアップストリーム（こうした拒否をそのまま中継する kimi_oauth プールは除く）がアカウント全体を拒否した。API 使用上限、クレジット残高の枯渇、または 402 billing_error。shunt はチェーンの次のアップストリームへ進み、refusal フィールドがどのケースかを示す。クライアントに 400/402 が見えるのは、他のアップストリームがリクエストを処理できなかった場合だけ。passthrough 以外のアップストリームは以後、You will regain access on … UTC の時刻まで、なければ 1 時間、新しいリクエストでスキップされ、スキップは再起動でのみ消え、設定のリロードでは消えない。原因を解消するには、使用上限なら上限を引き上げ、クレジット残高ならチャージし、billing_error なら Anthropic Console で請求・支払い情報を修正する。ただし進行中の期間が早く終わるわけではない。スキップは期間の終わりまで続き、チェーンのすべてのエントリがスキップ対象なら設定どおりにチェーンを試行する。プランに含まれる Max API クレジットは Claude Code のトラフィックを拒否すると報告されているため、それを使う共有アップストリームは、その 1 時間のあいだ他のクライアントでもスキップされることがある。Claude OAuth プールでは、拒否したアカウントがその期間クールダウンされ、リクエストは次のアカウントへ回る。プールのアップストリーム自体は、プールの最後の応答が拒否のときだけ、最も早いアカウントが再び処理できるようになるまでスキップされる。 |
/model にモデルが表示されない |
gpt-* id には ANTHROPIC_CUSTOM_MODEL_OPTION を使う。discovery は claude/anthropic プレフィックスの id のみを表面化します。 |
opus で Opus 4.7／sonnet で Sonnet 4.6 が選択される |
Claude Code の組み込みエイリアステーブルでは、gateway セッション用にこれらの tier が固定されています。ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5 を使ってクライアント側で tier を固定するか、shunt で id をリマップしてください — モデルエイリアスを参照。 |
| Opus／Fable のコンテキストウィンドウが 200K と表示される | Claude Code は base URL が api.anthropic.com の場合にのみ、モデルのネイティブ 1M ウィンドウを信頼します。opus[1m]／fable[1m] を選択してください — モデルエイリアスを参照。 |
/model に Fable が表示されない、または claude-fable-5 が Opus にフォールバックする |
単純な ANTHROPIC_BASE_URL の背後では Fable が除外されます。ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5 を設定するか、gateway login を使ってください — モデルエイリアスを参照。 |
| Discovery が発火しない | ゲートウェイ認証情報（ANTHROPIC_AUTH_TOKEN、API キー、または apiKeyHelper）に加え CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 にゲートされています。claude --debug → [gatewayDiscovery] の行でデバッグ。 |
config check failed |
正確な理由（バインドアドレス、ルート内の未知のプロバイダー、誤ったアダプター/認証）は shunt check を実行。 |
| Claude Code がログインを求めてくる | shunt がマッピングされていないモデル向けに転送できる Anthropic 認証情報（ANTHROPIC_AUTH_TOKEN / ログイン）を設定。base URL だけでは認証情報になりません。 |
マッピングされたモデルでエフォートが medium に固定される |
CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1 を設定 — Effort & Context を参照。 |
マッピングされたモデルで 400 Invalid schema for function '…': '…' is not a 'regex' |
OpenAI バックエンドはツールスキーマの各 pattern を Python の re でコンパイルするため、JavaScript 専用の正規表現（\p{Cc}、(?<name>…)、\u{…}）を拒否します。Claude Code の Artifact ツールがそのようなパターンを含みます。shunt は転送するスキーマからこれらのパターンを取り除きます。strict モード外では pattern は助言的なのでヒントが失われるだけですが、description が常にその制約を書き直しているわけではありません。まだ表示される場合は更新してください。 |
| マッピングされたモデルでツール呼び出しがすべてのオプションパラメータ埋めで届く | バックエンドは明示的な strict のない function ツールを strict モードへ正規化し、そのモードでは閉じたパラメータオブジェクト(additionalProperties:false)がすべてのプロパティを必須のように扱うため、呼び出し元が設定していない値までモデルが埋めます。shunt は転送する function ツールと tool_search_output 内で再生されるスペックに strict:false を固定してオプションをオプションのまま保ちます; xAI/Grok ルートでは未検証のためフィールドを送らず、ネイティブ tool_search はスキーマにオプションプロパティがないため省略します。まだ表示される場合は更新してください。 |
| マッピングされたモデルでツール検索が無効(毎ターン全ツールのスキーマが送られる) | ENABLE_TOOL_SEARCH=true を設定。Claude Code はファーストパーティでない base URL の背後で楽観的なツール検索を自動で無効化します。shunt は tool_reference ブロックを転送し、遅延スキーマを必要なときに明らかにします — ChatGPT / Codex → ツール検索 を参照。 |
400 Deferred custom tools are only supported on Anthropic models… Received stealth/ox-alpha（または別の非 Claude スラッグ） |
Claude Code が非 Anthropic の Messages モデルへ defer_loading / tool_search_tool_* を送った。shunt は claude* / anthropic/* 以外の上流 id からこれらのフィールドを取り除いて転送する。OpenRouter 上の Anthropic スラッグはプロトコルを維持する。 |
| ツール検索は動くがコンテキストを削減しない（テキストシムのキャッシュ無効化コストを払ったまま） | ネイティブな tool_search はデフォルト（「auto」）では、すでにサポートが確認されているホスト — ChatGPT/Codex バックエンドと api.openai.com — でのみ有効になり、さらにフレーバー / モデルのゲート（標準 OpenAI/ChatGPT-Codex フレーバー、gpt-5.4 以降のモデル）も満たす必要があります。カスタムの OpenAI 互換エンドポイント（LiteLLM、vLLM、OpenRouter、自己ホスト）は自動的には有効化されないため、tool_search 項目の実装を確認したうえで tool_search = true を設定してください。既知のホストでネイティブを期待しているのに依然としてシムのままの場合は、tool_search = false を設定していないか確認してください — ChatGPT / Codex → ツール検索 → ネイティブプロトコル を参照。 |
| マッピングされたモデルでコンテキスト長エラーの後にセッションが立ち往生 | shunt は上流のオーバーフローエラーを prompt is too long … へ書き換えるため Claude Code は自動コンパクトして再試行します — コンテキストオーバーフローの回復 を参照。数ターンごとに再発する場合は CLAUDE_CODE_MAX_CONTEXT_TOKENS をモデルの実ウィンドウへ下げてください。 |
| Cloudflare の背後でストリームが切れる（524） | sse_keepalive_seconds を 0 ではなくデフォルト（30）のままにする。 |
| 共有ゲートウェイでマッピングされたモデルに 401 | クライアントトークンが欠落／無効 — ANTHROPIC_AUTH_TOKEN=<token>（Authorization: Bearer として受理、プール専用ゲートウェイ）または ANTHROPIC_CUSTOM_HEADERS="x-shunt-token: <token>"（パススルーモデルが混在する場合に推奨 — 各呼び出し元の実際の認証情報が専用のスロットを確保できるように。Authorization / x-api-key に載って届いたクライアントトークンは転送されず、そのスロットから除去されます）を設定。ゲートウェイの共有 を参照。 |
| Anthropic アダプターモデルで 429 | ゲートウェイログの rate_limit_kind を確認してください。quota（retry-after／anthropic-ratelimit-* ヘッダーあり）は実際のレート制限です。待機するか、並列負荷を減らしてください。client-shape-rejection（OAuth リクエスト、どちらのヘッダーもなく、body が単なる "Error"）は、Claude Code らしくない subscription OAuth リクエストを api.anthropic.com が拒否したことを意味します。Claude Code 以外のクライアントは OAuth トークンではなく API キーを使う必要があります。一部の Claude Code リクエストは、アップストリームが確認する identity ブロックを持たずに届きます。auto モード権限分類器と、CLAUDE_CODE_ATTRIBUTION_HEADER=0 のときの mod の $.model.complete のようなサイドクエリです。shunt は auto モード分類器と、受け入れられるマーカーを持たないすべての Claude Code リクエスト（x-claude-code-session-id、claude-cli/ の user agent、または x-app: cli で識別）に identity を復元します。この復元は送信する bearer がサブスクリプション OAuth トークンのときだけ適用され、アップストリームが確認しない count_tokens には適用されず、空の x-claude-code-session-id は Claude Code とみなしません。これにより、auto モードが「model temporarily unavailable」で fail-closed になることや、サイドクエリがこのヘッダーなしの 429 で拒否されることを防ぎます。quota の 429 はそのままクライアントに届きます。他のクライアントとそれ以外のリクエストは、Anthropic プロバイダーページで説明している thinking signature の除去を除き、byte-for-byte のパススルーを維持します。これらのチェックを高価なモデルから外すには、classifier_model で固定してください。no-ratelimit-headers（非 OAuth 認証情報）は、レート制限メタデータのないプロバイダー 429 です。quota として扱ってください。 |
| このセッションは auto モードの無課金分類器リクエストの対象外だと Claude Code が表示する | auto モードは各ツール使用の分類を API に依頼しますが、これに応答するのは api.anthropic.com だけです。Anthropic ルートでは、shunt がそのリクエストと応答をそのまま中継します。別のアップストリームが処理するルート（Codex/Responses、Cursor、Gemini、Antigravity）には中継すべきサーバー判定がないため、shunt は何も返さない代わりに、アクションごとに「評価不能」と応答します。こうすると Claude Code はそのアクションだけをローカルで分類し、次のターンで再びサーバーに問い合わせるので、セッションの残り全体でサーバー分類器を諦めて自前の課金分類器に切り替えることはありません。Anthropic プロトコルのサードパーティ（Kimi、OpenRouter、DeepSeek など）へは、送信前に safeguards フィールドと dangerous-tool-use-* beta トークンも取り除きます。このフィールドを受け付けると確認できたところはなく、フィールドを名指しする 400 が返ると Claude Code は /clear まで auto モードのツール使用をすべて拒否する一方、フィールドを取り除けば失うのはそのターンのサーバー判定だけだからです。機能自体を無効にして分類をクライアント側に留めるには、CLAUDE_CODE_AUTO_MODE_SERVER=0 を設定してください。 |
共有ゲートウェイで 503 overloaded_error |
ゲートウェイがインバウンド同時実行数の上限に達し、リクエストをキューに入れずに拒否しました（body メッセージは too many requests are already in flight、Retry-After: 1 付き）。これは上流の 503 ではなく shunt 自身の admission control です。上流の 503 はプロバイダー自身のメッセージのまま中継されます。指定時間後に再試行するか、並列負荷を減らすか、max_concurrent_requests を上げて再起動してください（上限は起動時に固定されます）。 |
shunt run が store … エラーで起動時に終了する |
オプションの [store] を開けませんでした。接続・オープンのエラーにはストアの接続先が表示されます（パスワードは表示されません）。後述のスナップショットのインポートエラーには、代わりにサブシステム、スナップショットのパス、原因が表示されます。is held by another shunt instance (<host>:<pid>): 別の shunt プロセスがストアを使用中です。そのプロセスを止めるか、クラッシュ後であれば、ホールドが stale になる（hold_stale_seconds、デフォルト 30 秒）まで最大その時間待ってください。起動時の store statement failed: … lock timeout（PostgreSQL）: 別のセッションがインスタンスホールドの行を 5 秒間ロックしていました。多くはクライアントが消えたバックエンドです。pg_stat_activity で見つけて pg_terminate_backend で終了させるか、サーバーが回収するまで待ってから再起動してください。is at schema version N, newer than the M this binary supports: データベースはより新しい shunt でマイグレーション済みで、変更されていません。shunt をアップグレードしてください。importing the <subsystem> state snapshot <path> into the store failed: そのサブシステムは何もインポートされていません。ただし原因がコミットの失敗であれば、インポートはすでに反映されている可能性があり、その場合は次回の起動でインポート済みとして扱われます。コロンの後の原因を確認してください。JSON スナップショットの形式が不正か未対応のバージョンであれば、エラーに示されたファイルを修正または削除し、ファイルを読み取れなければ権限やパスを直し、ストアのトランザクション失敗であればストア自体を点検します。そのうえで再起動してください。is unreachable: データベースに接続または作成できません。shunt check は起動せずに同じ原因を表示します。requires a build with the store-postgres feature: リリースバイナリを使うか、--features store-postgres でビルドしてください。 |
ゲートウェイの /oauth/token が 503 temporarily_unavailable を返す |
[store] がある場合に、トークンを書き込めなかったため発行せず、変更をロールバックしました。refresh token のローテーションであれば、ストアに書き込めるようになった後のクライアントの再試行は成功します。device flow のログインであれば、承認済みの grant はすでに使われているため、再試行した poll は expired_token を受け取り、ログインのやり直しが必要です。どちらの場合も、shunt.store.write_failures{subsystem="gateway"} カウンターと、ストアのディスクや接続を確認してください。警告ログの理由が postgres … did not complete within 15s であれば、PostgreSQL との往復が 15 秒以内に応答を得られませんでした。接続が応答しなくなったか、サーバーが遅すぎたためです。shunt はデータベースとの往復ごとに 15 秒で打ち切るため、止まった書き込みの後ろで待っているトークンリクエストは、無期限ではなく限られた時間だけ待ちます。打ち切ったのが COMMIT であれば shunt はストアを読み直し、書き込みが反映されていればリクエストは成功し、警告だけが残ります。 |
完全なゲートウェイのトラブルシューティング表については、Connect Claude Code to an LLM gateway を参照してください。