Claude Codeを社内のLLM gateway経由で使っていると、「遅い」「急に高くなった」「コンパクションの後だけ挙動が違う」という問題が起きます。
モデルを変えたのか、サブエージェントが増えたのか、コンテキストが圧縮されたのか。gateway側からは、リクエストの中身だけ見ても切り分けにくいことがあります。
v2.1.273で、Claude Codeがgateway向けのヒントヘッダーを送れるようになりました。既定で全部の環境に送られるわけではなく、必要な環境でオプトインする機能です。
まずは普通のgateway構成を確認します
Claude Codeをgatewayに向ける設定は、まずエンドポイントと認証情報です。公式ドキュメントの考え方は次のようになります。
export ANTHROPIC_BASE_URL=https://gateway.example.com
export ANTHROPIC_AUTH_TOKEN=your-gateway-token
claude
ここで注意してください。上の値は説明用です。実際の認証トークンを記事やログに書いてはいけません。
gatewayを置くと、開発者ごとの利用量を集計したり、組織側で予算やレートを管理したりできます。プロバイダーを切り替える時に、開発者の端末設定を毎回変えなくてよいのも便利です。
ただし、Claude Codeの新機能が増えるたびに、gatewayが必要なヘッダーやリクエストを正しく通せるか確認する仕事も増えます。gatewayを置いたら終わり、ではありません。
どのリクエストなのかをヘッダーで分けます
v2.1.273では、次のようなヒントヘッダーが追加されました。
x-claude-code-request-class:メインのターン、サブエージェント、workflow、compaction、補助リクエストなどの種類x-claude-code-agent-type:エージェント種別x-claude-code-prev-tool-durations:直前のツール実行時間に関する情報x-claude-code-compaction:コンテキスト圧縮に関する情報x-claude-code-context-compacted:コンテキスト圧縮後かどうか
これでgatewayのログを、「全部のリクエスト」という一つの箱で見る必要がなくなります。
たとえば遅いリクエストがあったとします。メインの会話だけ遅いのか、サブエージェントだけ遅いのか、compactionの直後だけ遅いのかを分けて集計できます。原因を探す時に、これはかなり助かります。
逆に、これだけで原因が自動的にわかるわけではありません。ヘッダーは分類の手がかりです。モデルの応答時間、gatewayのキュー、上流APIのエラーなどと組み合わせて見てください。
有効にする方法
ヘッダーを送るには、環境変数を1にします。
export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1
claude
管理設定に入れる場合は、各端末に同じ設定を配布する方法もあります。無人実行で端末ごとの差を減らしたいなら、個人が手入力するより管理設定で揃えた方が安全です。
ただし、gatewayによっては未知のヘッダーを拒否することがあります。公式ドキュメントでも、カスタムのエンドポイントでは既定でオフになっている理由として、その互換性問題が説明されています。
設定を有効にしたあと、いきなり本番の全セッションへ広げないでください。まず検証用のセッションを1つだけ流し、gatewayのアクセスログでヘッダーが届くことを確認しましょう。
# gateway側で確認する項目の例
request_class
agent_type
context_compacted
upstream_status
duration_ms
実際のログ形式はgateway製品によって変わります。上の項目がそのまま自動で出るという意味ではありません。受け取ったヘッダーを、社内のログ形式に合わせて保存してください。
ログに残してよい情報を決めます
分類ヘッダーは便利ですが、何でも長期保存してよいわけではありません。
リクエスト種別やツール実行時間を保存する場合でも、誰の作業か、どのプロジェクトか、どのモデルかを組み合わせると、開発者の行動履歴に近い情報になります。保存期間と閲覧できる人を決めてください。
プロンプト本文やファイル内容を一緒に保存する必要があるかも、別に判断しましょう。障害調査に必要な情報と、保存しない情報を分けるのが先です。
私なら最初は、リクエスト種別、処理時間、HTTPステータス、モデル名を短期間だけ保存します。改善の手がかりが足りなければ、その時に項目を増やします。最初から全部取るのは、あとで整理できなくなるやーつです。
Gatewayヒントヘッダーを使う時の切り分け
設定したのにログに出てこない場合は、次の順で確認してみてください。
- Claude Codeがv2.1.273以降か確認する。
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1が実際のプロセスに渡っているか確認する。ANTHROPIC_BASE_URLが想定したgatewayを指しているか確認する。- gatewayや途中のプロキシが未知のヘッダーを削除していないか確認する。
- ベッドロックやVertexなど、接続先による送信条件の違いを確認する。
最後の項目は特に注意です。接続先によっては、ヒントヘッダーが既定で送られず、オプトイン時だけ送られます。
「設定したのに出ない」と思ったら、Claude Code側、gateway側、上流側のどこで消えたかを分けて見てください。クライアントの設定だけを何度も書き換えても直りません。
無人実行との相性は良いのですが、監視の代わりではありません
無人実行では、失敗したセッションをあとから調べることになります。メイン処理だったのか、サブエージェントだったのか、コンテキスト圧縮直後だったのかが分かるだけで、調査の入口はかなり狭くなります。
一方で、ヒントヘッダーは「なぜ遅いのか」「なぜ失敗したのか」を答えてくれる機能ではありません。gatewayのキューや上流プロバイダーの状態が原因なら、別のメトリクスが必要です。
ここを取り違えると、ヘッダーを追加しただけで監視が完成した気分になってしまいます。実際には、分類、計測、アラート、ログの保管ルールを分けて設計する必要があります。
Claude CodeのGatewayヒントヘッダーは、gateway運用の観測性を一段上げる小さな機能です。まずは1つの検証セッションで受信を確認し、必要な項目だけを短期間保存してみてください。
これで「何が遅いのか分からない」という状態からは抜け出しやすくなります。gatewayを使っている方は、まずログの分類だけでも試してみてください。
出典:Claude Code v2.1.273、Claude Code Docs: Other LLM gateways(2026年11月20日確認)

コメント