ANTHROPIC_CUSTOM_HEADERSとは — リクエストにヘッダーを追加する環境変数
ANTHROPIC_CUSTOM_HEADERSは、Claude CodeのAPIリクエストに独自ヘッダーを追加する環境変数です。書式・社内ゲートウェイ認証での使い方・関連変数との違いをまとめます。
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: <ゲートウェイが発行したキー>"ゲートウェイ側は、リクエストに付いたこのヘッダーを見て許可・拒否を判断したり、部署やプロジェクト単位で利用量を集計したりできます。Claude Code自体はヘッダーの中身を解釈せず、そのまま転送するだけです。
MCPサーバーのheadersHelperとは別の仕組み
ANTHROPIC_CUSTOM_HEADERSと混同しやすいものに、MCPサーバー接続で使うheadersHelperがあります。両者は送信先のリクエストが違います。
| 仕組み | 対象のリクエスト | 設定場所 |
|---|---|---|
ANTHROPIC_CUSTOM_HEADERS | 対象のリクエストClaude CodeからAnthropic APIへのリクエスト | 設定場所環境変数 |
headersHelper | 対象のリクエストClaude Codeから個別のMCPサーバーへのリクエスト | 設定場所MCPサーバーの設定(.mcp.jsonなど) |
前者はモデルを呼び出す通信そのものに、後者は接続したMCPサーバーとの通信に付くヘッダーです。社内ゲートウェイの認証は前者、GitHubやNotionのような外部MCPサーバーごとの認証は後者、という使い分けになります。両方を同時に使う構成も珍しくありません。
監査ログ・コスト按分用のヘッダーを付ける
ゲートウェイ経由でClaude Codeを運用している組織では、認証以外の用途でANTHROPIC_CUSTOM_HEADERSを使うこともあります。たとえば、リクエストの発生元を示すクライアント識別子や、内部の監査ログと突き合わせるためのトレースIDをヘッダーに含めておくと、ゲートウェイ側のログとの相関が取りやすくなります。同じ仕組みは利用量の按分にも使えます。部署・プロジェクト・環境(開発 / ステージング / 本番)ごとにヘッダーの値を変えてリクエストへ付与し、ゲートウェイ側のログでその値を集計すれば、チーム単位のトークン消費や費用を分解できます。
いずれの用途でも、Claude Code自体はヘッダーの値を解釈せず、そのまま転送するだけなので、値の設計と集計の仕組みはゲートウェイ側で用意しておく必要がある前提になります。認証情報のような機密性が高い値と混在させず、用途ごとにヘッダー名を分けておくと、ログを見る側も意図を読み取りやすくなります。チーム全体のコストをどう可視化し抑えるかはClaude Codeのコスト管理で扱っています。
環境ごとにヘッダーを切り替える
開発・ステージング・本番のように複数の環境でゲートウェイを使い分けているチームでは、ANTHROPIC_CUSTOM_HEADERSの値も環境ごとに変える必要があります。個人アカウントと会社アカウントを1台で並行運用する構成と同じく、CLAUDE_CONFIG_DIRで設定ディレクトリごと分けてしまえば、ディレクトリを切り替えるだけで有効なヘッダーも切り替わります。プロジェクトごとに固定したいだけなら、各プロジェクトの.claude/settings.jsonにenvブロックとして書いておく方法もあります。どちらを選ぶかは、環境の切り替えを「ディレクトリ単位」で行うか「プロジェクト単位」で行うかで決まります。
書き方のルール
名前や値に、HTTPヘッダーが運べない文字(改行そのもの・NULバイト・カーリークォートのようなU+00FF超のコードポイント)が混ざっていると、Claude Codeはリクエストを送る前に止まり、どのペアが原因かをエラーメッセージで示します。文書やチャットからコピーした値を貼り付けたときに起きやすい症状で、原因の特定方法と直し方は「Invalid request header value」エラーの原因と対処にまとめています。
Amazon Bedrock経由での注意点
Amazon Bedrock経由でClaude Codeを使う構成では、認証にSigV4署名を使うため、ANTHROPIC_CUSTOM_HEADERSでAuthorizationヘッダーを直接指定すると衝突することがあります。実際にv2.1.101より前のバージョンでは、ANTHROPIC_AUTH_TOKEN・apiKeyHelper・ANTHROPIC_CUSTOM_HEADERSのいずれかでAuthorizationヘッダーを設定すると、BedrockのSigV4認証が403エラーで失敗する不具合がありました。この問題はv2.1.101で修正済みですが、認証方式が複数絡む構成では「どの面(直接API・ゲートウェイ・Bedrock)でヘッダーを扱っているか」を意識しておくと、似た症状に遭遇したときの切り分けが早くなります。
CLAUDE_CODE_SKIP_FOUNDRY_AUTHとの関係
Microsoft Foundry経由でClaude Codeを使う構成では、CLAUDE_CODE_SKIP_FOUNDRY_AUTHというやや特殊な変数がANTHROPIC_CUSTOM_HEADERSと組み合わさります。これはAzureの認証を省略し、代わりに自前で用意したAuthorizationヘッダーをそのまま尊重させる設定です。ゲートウェイやプロキシが独自のAuthorizationヘッダーを注入する構成で、Claude Code側のAzure認証と衝突するのを避けたいときに使います。ANTHROPIC_FOUNDRY_API_KEYやANTHROPIC_FOUNDRY_AUTH_TOKENが設定されている場合、この変数は無視されます。
チームで固定する — 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に分けておくと、認証キーのようなメンバーごとに異なる値をリポジトリへコミットせずに済みます。設定ファイルの階層と優先順位の全体像はClaude Code settings.json完全ガイドにまとめています。
よくある質問
認証情報そのものはこの変数で置き換えられますか
置き換えられません。ANTHROPIC_API_KEYやANTHROPIC_AUTH_TOKENとは別枠で、既存のリクエストに追加のヘッダーを載せるための変数です。認証方式の選び方はClaude Codeログイン方法3種の使い分けで扱っています。
ヘッダー名や値に日本語は使えますか
HTTPヘッダーはASCII文字が前提のため、日本語のようなU+00FFを超える文字は避けます。含めるとリクエスト送信前にエラーで止まります。
Amazon Bedrock経由でも効きますか
ANTHROPIC_CUSTOM_HEADERSの値検証(不正な文字のチェック)はClaude API直接またはLLMゲートウェイ経由の送信で動きます。Amazon Bedrockのようなサードパーティのクラウドプロバイダー経由では、この事前チェックは実行されません。
設定したヘッダーが反映されているか確認する方法はありますか
/statusで現在有効な設定のソースを確認できます。値そのものを確かめたいときはenv | grep ANTHROPIC(PowerShellならGet-ChildItem Env:ANTHROPIC*)でシェル側の値を洗い出せます。
1つのヘッダーに複数の値をカンマ区切りで書けますか
ANTHROPIC_CUSTOM_HEADERSが複数ペアを区切るのは改行であって、カンマではありません。HTTPの仕様上、1つのヘッダー名に複数の値をカンマ区切りで持たせること自体は可能な場合がありますが、この変数の書式としては「1行に1つのName: Valueペア」を基本にしておくのが安全です。ゲートウェイ側が特定の書式のヘッダー値を期待している場合は、そちらの仕様に従います。
CLAUDE_CONFIG_DIRとの併用に注意点はありますか
CLAUDE_CONFIG_DIRで設定ディレクトリを分けている場合、ANTHROPIC_CUSTOM_HEADERSはディレクトリ側のsettings.jsonに書くか、そのディレクトリを使うシェルセッションでexportするかのどちらかになります。ディレクトリを切り替え忘れると、意図しない環境向けのヘッダーが使われたまま気づかないことがあるため、切り替え後は/statusで確認する習慣をつけておくと安全です。
MCPサーバーへの認証ヘッダーもこの変数で設定できますか
できません。MCPサーバーごとの認証はheadersHelperなど、MCPサーバーの設定側にある別の仕組みを使います。ANTHROPIC_CUSTOM_HEADERSが対象にするのはClaude Code本体からAnthropic APIへ向かうリクエストだけです。
まとめ
ANTHROPIC_CUSTOM_HEADERSは、Claude CodeのすべてのAPIリクエストにName: Value形式のヘッダーを追加する環境変数です。社内ゲートウェイの認証やトラッキング用途で使い、複数ヘッダーは改行区切りで書きます。認証情報そのものの置き換えではなく追加のヘッダーである点、値にHTTPヘッダーが運べない文字を含めるとリクエスト前に止まる点を押さえておくと、設定時の失敗を減らせます。