ANTHROPIC_CUSTOM_HEADERSとは — リクエストにヘッダーを追加する環境変数

ANTHROPIC_CUSTOM_HEADERSは、Claude Codeが送るすべてのリクエストに独自のHTTPヘッダーを追加する環境変数です。社内のLLMゲートウェイが認証ヘッダーを要求する構成や、リクエストに部署名などの印を付けたい構成で使います。

Claude Codeは、ゲートウェイ向けのヘッダーをすでにいくつか自動で付けています。自分で足すのは、それでは足りない分だけです。設定を配る側では、ヘッダーの中身によって承認ダイアログが出る点も見ておく必要があります。ヘッダー値の事前検証はv2.1.227以降で動きます。

ANTHROPIC_CUSTOM_HEADERSが変えるもの

指定したName: Valueのペアが、Claude CodeからAPIへ送るすべてのリクエストに追加されます。複数のヘッダーは改行区切りで並べます。

export ANTHROPIC_CUSTOM_HEADERS="X-Gateway-Auth: internal-token-value
X-Team-Id: platform"
claude

ANTHROPIC_API_KEYやANTHROPIC_AUTH_TOKENのような認証本体を置き換える変数ではありません。その横に、ヘッダーを足すだけです。ただしモデル一覧の取得(ディスカバリ)では、値が空でないカスタムヘッダーが同名の組み込みヘッダーの代わりに送られます。

社内ゲートウェイの認証ヘッダーを付ける

Claude CodeをAnthropic APIへ直接つながず、社内のLLMゲートウェイやリバースプロキシ経由で運用するチームでは、ゲートウェイ側が独自のヘッダーを要求することがあります。ANTHROPIC_BASE_URLで向き先を変え、ANTHROPIC_CUSTOM_HEADERSで必要なヘッダーを足す組み合わせが典型です。

export ANTHROPIC_BASE_URL="https://gateway.internal.example.com"
export ANTHROPIC_CUSTOM_HEADERS="X-Internal-Gateway-Key: <ゲートウェイが発行したキー>"

ゲートウェイの運用側にとって、ANTHROPIC_CUSTOM_HEADERSで足されたヘッダーは、Claude Codeが自動で付けるヘッダーと並んで届きます。ゲートウェイ向けの公式仕様にも、開発者が設定したヘッダーはリクエストに載る、と明記されています。

自動で付くヘッダーと自分で足すヘッダー

コスト按分やログの突き合わせが目的なら、先に確認したいのはClaude Codeが標準で付けるヘッダーです。ゲートウェイ向けの公式仕様(llm-gateway-protocol)には、次の区分が載っています。

エージェントIDは、人や端末を特定する識別子ではありません。サブエージェントを起動するたびに新しい値が作られるためです。ユーザー単位の集計には、x-claude-code-agent-idではなく自前のヘッダーを使うことになります。

さらに、Claude Codeにはゲートウェイ向けのヒントヘッダー(x-claude-code-request-classなど)があります。直接のAnthropic API接続では既定で送られます。カスタムベースURLでは既定でオフなので、CLAUDE_CODE_GATEWAY_HINT_HEADERS=1を設定して受け取ります。バージョンごとの追加は次のとおりです。

チーム全体のコストをどう可視化し抑えるかは、Claude Codeのコスト管理で扱っています。

配布したヘッダーで承認ダイアログが出る条件

管理設定(server-managed settings)でヘッダーを配る場合、値によってはユーザーへの承認ダイアログが出ます。線引きは、ヘッダー名に含まれる語で決まります。

無害に見える名前でも、社内ヘッダーが承認ダイアログを呼ぶことがあります。ヘッダー名を決めるときは、名前にclientやversionを含めないほうが、承認待ちで止まらずに済みます。名前が有効なHTTPヘッダーのトークンでない行や、値に運べない文字を含む行も承認の対象です。

承認が必要な値を配ると、ダイアログには対象の変数名が表示され、ユーザーは何が設定されようとしているかを確認できます。ユーザーが拒否するとClaude Codeは終了します。

承認は毎回求められるわけではありません。claude.aiのログインなら組織ごとに1回、APIキーやCLAUDE_CODE_OAUTH_TOKENのような別の認証なら、配られた設定ごとに1回です。配る側が承認が必要な行を書き換えると、ダイアログはもう一度出ます。/logoutやclaude auth logoutでも、保存済みの設定が消えるため、次の起動で再び出ます。

claude.aiのログインでは、承認を保持するのは直近に承認したアカウントです。同じ組織に別のアカウントでサインインし直すと、設定が変わっていなくてもダイアログがもう一度出ます。元のアカウントに戻ったときも、もう一度出ます。Claude appsゲートウェイ経由のサインインでは、承認はゲートウェイごとに1回です。サインアウトして同じゲートウェイへ入り直しても、承認が必要な設定が変わらない限り出ません。別のゲートウェイへ入ったときや、同じゲートウェイで新しい証明書を受け入れたときは、また出ます。平文HTTPで接続するループバックの開発用ゲートウェイでは承認が保存されず、サインインのたびに出ます。

ダイアログを出せない場面もあります。対話セッションでも出せないときは、配られた設定を適用せず、最後に承認された設定のまま動きます。claude installとclaude updateも、最後に承認された設定で動き、ダイアログは次の対話セッションで出ます。

CIで使うclaude -p、Agent SDKのセッション、VS Code拡張のチャット欄、デスクトップアプリのCodeタブは、ダイアログを出せない実行です。承認が必要な設定が配られていても、その実行に限って適用します。承認済みとしては記録せず、ローカルのキャッシュにも書かないので、次の対話セッションでダイアログが出ます。承認されるまでは、非対話の実行が起動のたびに設定を取り直します。v2.1.207より前は、非対話の実行が設定を承認済みとして保存していたため、後の対話セッションでダイアログが一度も出ませんでした。

プロジェクトやローカルの設定に書いたANTHROPIC_CUSTOM_HEADERSは、この承認ダイアログとは別の規則で反映されます。承認ダイアログが対象にするのは管理設定で配られた値だけです。プロジェクト設定とローカル設定のenvは、ワークスペースを信頼した後に反映されます。claude -pでは信頼ダイアログが出ないため、起動時に反映されます。

MCPサーバーのheadersHelperとは別の仕組み

混同しやすいものに、MCPサーバー接続で使うheadersHelperがあります。送信先が違います。

社内ゲートウェイの認証は前者、外部MCPサーバーごとの認証は後者です。headersHelperは接続のたびに(セッション開始時と再接続時に)コマンドを実行してヘッダーを作るので、短命なトークンに向きます。ANTHROPIC_CUSTOM_HEADERSは環境変数の固定値です。

書き方のルールと、値が壊れたときの症状

名前や値に、HTTPヘッダーが運べない文字(NULバイト・改行・カーリークォートのようなU+00FF超のコードポイント)が混ざると、Claude Codeはリクエストを送る前に止まります。エラーはInvalid ANTHROPIC_CUSTOM_HEADERS · Fix the environment variableで始まり、どのペアが原因かを位置で示します。値そのものは表示されません。

この検証は、Claude API直接またはLLMゲートウェイ経由の送信で動きます。Amazon Bedrockのようなサードパーティのクラウドプロバイダー経由では、送信前のチェックは動きません。原因の読み方と直し方は「Invalid request header value」エラーの原因と対処にあります。

Bedrock・Foundryで認証ヘッダーを扱うとき

Amazon Bedrockは認証にSigV4署名を使うため、v2.1.101より前はAuthorizationヘッダーを差し込むと403で失敗する不具合がありました(v2.1.101で修正)。認証方式が複数絡むときは、どの経路(直接API・ゲートウェイ・Bedrock)でヘッダーを扱っているかを先に切り分けると早く済みます。

Microsoft FoundryにはCLAUDE_CODE_SKIP_FOUNDRY_AUTHがあります。Azureの認証を省き、ゲートウェイが注入するAuthorizationヘッダーと衝突しないようにする変数です。ANTHROPIC_CUSTOM_HEADERSで自前のAuthorizationを渡す場合も、そのヘッダーがそのまま保たれます。ANTHROPIC_FOUNDRY_API_KEYかANTHROPIC_FOUNDRY_AUTH_TOKENを設定していると、この変数は無視されます。v2.1.203より前は、APIキーも設定しないとFoundryのクライアントがリクエストを送れませんでした。

チームへ配る — settings.jsonのenvブロック

メンバーごとにシェルへexportさせるより、settings.jsonに書いて配るほうが設定漏れを防げます。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.internal.example.com",
    "ANTHROPIC_CUSTOM_HEADERS": "X-Internal-Gateway-Key: <ゲートウェイが発行したキー>"
  }
}

チームで共通の値は.claude/settings.jsonに、メンバーごとに違う認証キーは.claude/settings.local.jsonに分けると、キーをリポジトリへコミットせずに済みます。個人アカウントと会社アカウントを1台で使い分けるなら、CLAUDE_CONFIG_DIRで設定ディレクトリごと分ける方法もあります。ただしCLAUDE_CONFIG_DIRはプロジェクトやローカルのenvでは設定できず、シェルかユーザー設定・管理設定に書く必要があります。設定ファイルの階層と優先順位はClaude Code settings.json完全ガイドにあります。

envに書いた値は、同じ変数をシェルでexportしていても上書きします。複数の設定ファイルが同じ変数を持つときは、優先順位の高いほうが勝ちます。シェルのexportを打ち消したいときは、値を空文字列""にします。空の値は未設定として扱われ、子プロセスにも空のまま渡ります。

注意点が2つあります。1つ目は、設定ファイルの値が平文で残り、Claude Codeが起動するすべてのサブプロセスに届くことです。ローテーションするトークンやAPIの認証情報は、envに固定値で書くのでなく、apiKeyHelperで渡す設計が向いています。2つ目は、Claude Desktopアプリやセルフホスト環境のランナーがセッションを始める場合です。起動側が組み立てた環境が優先され、すでに設定済みの変数について、設定ファイルのenvは無視されます。無視された変数は、デバッグログで確認できます。

ANTHROPIC_CUSTOM_HEADERSは認証本体の置き換えではないので、認証方式の選び方はClaude Codeログイン方法3種の使い分けを参照してください。

まとめ

ヘッダーで集計したいだけなら、まず標準のx-claude-code-session-idとヒントヘッダーで足りるかを見ます。足りない社内の区分だけをANTHROPIC_CUSTOM_HEADERSに載せ、管理設定で配るなら、認証系の名前で承認ダイアログが出る点を織り込んでおくと止まりません。