Claude Code環境変数リファレンス — 用途別の一覧と、効かないときの切り分け

Claude Codeの環境変数は、使うモデル・自律実行の上限・接続先のプロバイダー・一時エラーへの粘り方といった挙動を、設定ファイルを書き換えずにその場で切り替えるための仕組みです。数は90種を超え、リリースのたびに増えたり役目を終えたりします。ここでは用途別に主要なものを引ける形でまとめ、値をどこに書くか、書いたのに効かないときにどこを見るかまでを扱います。

Claude Codeの環境変数は何を変えるのか

Claude Codeの環境変数とは、起動時にプロセスへ渡すことで動作を上書きできるキーと値の組です。同じ挙動の多くはsettings.jsonでも指定できます。ただし環境変数には、秘密情報をファイルに残さない、そのセッションだけ切り替える、コンテナやCIの実行時に注入する、といった向き不向きがあります。

変えられる範囲はおおむね4つの層に分かれます。1つ目が接続先で、どのAPIエンドポイントに、どの資格情報でつなぐかを決めます。2つ目がモデルで、エイリアスの解決先や思考の深さ、出力トークンの上限を扱います。3つ目が自律実行の範囲で、サブエージェントの本数や検索回数といった「勝手に広がる経路」に天井を置きます。4つ目がその他の挙動調整で、リトライ・タイムアウト・表示・テレメトリーなどが入ります。

やりたいことから引く早見表

まず入口として、目的から変数を引ける形で並べます。詳細は後続の節でそれぞれ扱います。

モデルと出力量を決める変数

モデル系は環境変数のなかでも触る機会が多く、名前が似ているものが並ぶため取り違えやすい領域です。セッションで使うモデルそのものを決めるのがANTHROPIC_MODELで、エイリアスが指す先を決めるのがANTHROPIC_DEFAULT_*_MODELの系列という切り分けになります。

エイリアス側の変数は4つで一組になっていて、指定した文字列がそのままモデルIDとして使われます。とくにAmazon BedrockやMicrosoft Foundry経由で配布する場合、提供元ごとにIDの形が変わるため、固定しないままだと利用者の手元で意図しないモデルに解決されることがあります。この系列の詳しい挙動と派生変数は、ANTHROPIC_DEFAULT_FABLE_MODELの解説で扱いました。表示名や対応機能を補う_NAME・_DESCRIPTION・_SUPPORTED_CAPABILITIESの接尾辞も、そちらにまとめてあります。

コンテキストウィンドウ側にも変数があります。CLAUDE_CODE_MAX_CONTEXT_TOKENSはウィンドウサイズを上書きしますが、DISABLE_COMPACTとの併用が前提になります。1Mコンテキストを使わせたくないときはCLAUDE_CODE_DISABLE_1M_CONTEXTが対応します。なおANTHROPIC_SMALL_FAST_MODELは非推奨扱いになっているため、新しく組むならANTHROPIC_DEFAULT_HAIKU_MODEL側で指定する形になります。

自律実行の範囲に上限をかける変数

2026年の後半にかけて増えたのが、自律実行が際限なく広がる経路に天井を置く変数群です。サブエージェントやWeb検索は便利な反面、指示ひとつから枝分かれが止まらなくなることがあり、既定値と調整用の変数がリリースを追って整えられてきました。

入れ子の段数だけは経緯が入り組んでいます。v2.1.217で入れ子起動がいったん既定で無効になり、v2.1.219で既定が深さ3まで許可する向きへ変わりました。従来の入れ子なしに戻したい場合はCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1を指定します。既定値だけを頼りに設計すると、更新のたびに前提がずれる領域です。

権限まわりではCLAUDE_CODE_ENABLE_AUTO_MODEがよく検索されますが、こちらは役目が変わった変数です。Bedrock・Vertex AI・Foundry経由でauto modeを使うためのオプトインとして入り、v2.1.207以降は指定なしで使えるようになりました。経緯と現在の見どころはCLAUDE_CODE_ENABLE_AUTO_MODEとはで扱っています。設定が原因で挙動がおかしいときはCLAUDE_CODE_SAFE_MODE=1が使えて、CLAUDE.md・プラグイン・skills・hooks・MCPサーバーを読まないまま立ち上がります。

Bedrock・Vertex AIへつなぐ変数

クラウド経由でClaude Codeを使う構成では、プロバイダーの切り替え・認証・エンドポイントの3種類を組で指定します。切り替えだけを立てて認証側を忘れる、という取りこぼしが起きやすいところです。

企業のプロキシ配下では、ヘッダーやボディを差し込んで通す構成がよく取られます。CLAUDE_CODE_EXTRA_BODYはその差し込みに使う変数で、v2.1.206より前はclaude agentsや--bgのバックグラウンドワーカーがこの値をエラーも出さずに無視していました。対話セッションでは通るのにバックグラウンド側だけ通らない、という症状に心当たりがあるなら、まず更新で解消するかを見る形になります。

証明書まわりではCLAUDE_CODE_CERT_STOREでCA証明書のソースを選べます。TLSを検査するプロキシの内側では、証明書の取り回しが原因の失敗が起きやすく、v2.1.199以降はSSL証明書エラーをリトライで浪費せず即座に失敗として返し、修正のヒントを添えるようになりました。

一時エラーへの粘りとタイムアウトを決める変数

長時間の自動実行では、一時的なネットワーク断やレート制限をどう受け流すかが成否を分けます。ここに効くのがリトライ系とタイムアウト系の変数です。

この2つのリトライ変数は組で理解すると迷いません。CLAUDE_CODE_MAX_RETRIESはv2.1.186で上限が15回にキャップされ、それより粘りたい無人セッション向けの経路としてCLAUDE_CODE_RETRY_WATCHDOGが案内されました。v2.1.199でこの関係が明確になり、ウォッチドッグを有効にすると既定リトライが300へ上がり、あわせて15回のキャップも外れます。ローカルの対話利用で300回粘っても待たされるだけなので、効き目が出るのは夜間バッチやCIのような無人の経路に限られます。

レート制限そのものへの対処は変数だけで完結しません。使用量上限と無関係な一時的な429は自動リトライの対象ですが、サブスクリプションの枠を使い切ったときの429は待つか枠を足すかしか道がありません。エラー文面ごとの見分け方はClaude rate limitエラーの対処にまとめています。

環境変数をどこに書くか

書き方は3通りあり、共有したい範囲で選ぶ形になります。もっとも手軽なのはシェルでその場に渡す方法です。

export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=8
claude

1回だけ試したいなら、コマンドの前に置いて渡すこともできます。

CLAUDE_CODE_SAFE_MODE=1 claude

チームや端末をまたいで揃えたい値は、settings.jsonのenvキーに書きます。この形にすると、Claude Codeが起動する全セッションとその子プロセスへ同じ値が配られます。

{
  "env": {
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "8",
    "MCP_TOOL_TIMEOUT": "300000"
  }
}

envキーは配置するスコープによって届く範囲が変わり、管理設定に置けば個人設定から上書きできなくなります。スコープの階層と解決順はClaude Code設定ガイドで扱っています。なお、Bashツールが起動する子プロセスへ環境を持ち込みたいときはCLAUDE_ENV_FILEで事前実行するスクリプトを指定できます。逆に、子プロセスへ認証情報を渡したくない場合はCLAUDE_CODE_SUBPROCESS_ENV_SCRUBで除去できます。

書いたのに効かないときに見る4か所

設定したはずの値が反映されない、という状態が環境変数でもっとも起きやすい詰まり方です。原因は次の4つのどれかに収まることが多くなります。

1つ目は、シェルに値が入っていないケースです。別のターミナルタブでexportした、あるいは.zshrcに書いたが再読込していない、といった取り違えが典型になります。env | grep CLAUDEで実際に渡っているかを確かめると早く済みます。

2つ目が、値の書式です。数値を科学的記数法で書くと解釈が崩れる不具合があり、CLAUDE_CODE_MAX_OUTPUT_TOKENSなどで1e6が1として扱われていました。v2.1.208で修正されていますが、10進でそのまま書くのが安全です。真偽値を取る変数は1やtrueなど受け取る形が変数ごとに違うため、値を勝手に推測しないほうが確実です。

3つ目が、上位の設定に負けているケースです。管理設定は個人の設定やコマンドライン引数でも覆せません。availableModelsでモデルを絞っている組織では、v2.1.176以降ANTHROPIC_DEFAULT_*_MODEL経由で許可リスト外のモデルへ振り替える経路が塞がれています。組織の統制を環境変数で迂回する使い方は成立しない、と考えておくのが実態に合います。

4つ目が、そもそも変数名が変わっている、あるいは役目を終えているケースです。CLAUDE_CODE_ENABLE_AUTO_MODEのように不要になったもの、DISABLE_BUG_COMMANDのように新しい名前と等価な旧名で残っているものがあります。セッション内で/statusを実行すると、どの管理設定が効いているかまで表示されるので、設定が読まれているかの一次判定はここが早道です。設定以外の原因も疑うならClaude Codeでよくあるエラー10選が対処の見取り図になります。

直近のリリースで入った主な変数

環境変数は静的な一覧ではなく、リリースごとに増えます。いつ何が入ったかを追うと、手元のバージョンで使えるかどうかの見当が付けやすくなります。

並べてみると、追加の重心が「できることを増やす変数」から「広がりすぎる経路を締める変数」へ移っているのが読み取れます。サブエージェントやWeb検索が既定で強力になったぶん、上限を明示的に持たせる方向で調整点が用意された形です。無人で長時間回す構成ほど、この系列を先に押さえておく価値があります。

よくある質問

環境変数と設定ファイルはどちらが優先されますか

Claude Codeの設定は管理設定・コマンドライン引数・プロジェクト設定・ユーザー設定・組み込み既定という階層で解決され、管理設定はどの手段でも覆せません。環境変数はこの階層の外側から挙動を上書きする位置付けで、項目ごとに効き方が違います。たとえばモデルの決定では、/modelとコマンドラインの--modelがANTHROPIC_MODELより優先され、ANTHROPIC_MODELが設定ファイルのmodelフィールドより優先されます。一律の順序として覚えるより、変数ごとに確かめるほうが取り違えが起きにくくなります。

手元で有効な環境変数の一覧を出す方法はありますか

現在のプロセスに渡っている値はenv | grep -E 'CLAUDE|ANTHROPIC'で確認できます。Claude Codeが認識している設定の状態はセッション内の/statusで見られ、どの管理設定が効いているかまで表示されます。設定ファイル側にJSONの誤りがある場合も/statusで検出できます。

環境変数はサブエージェントにも引き継がれますか

settings.jsonのenvキーに書いた値は、Claude Codeが起動する全セッションと子プロセスへ配られます。ただしバックグラウンドで動く経路では反映されないことがあり、CLAUDE_CODE_EXTRA_BODYはv2.1.206より前のバックグラウンドワーカーで無視されていました。バックグラウンド側だけ挙動が違うときは、この種の取りこぼしを疑う余地があります。

認証情報を環境変数に置くのは安全ですか

settings.jsonに直接書くとリポジトリへのコミットで流出する余地があるため、資格情報は環境変数側に置くほうが事故は減ります。そのうえで、direnvやOSのキーチェーン、apiKeyHelperのような動的発行と組み合わせると、平文で常駐させずに済みます。Claude Codeが起こす子プロセスへ認証情報を渡したくない場合はCLAUDE_CODE_SUBPROCESS_ENV_SCRUBで除去できます。

使われなくなった環境変数はどうなりますか

役目を終えた変数には、指定しなくてよくなったものと、旧名として等価に扱われ続けているものがあります。CLAUDE_CODE_ENABLE_AUTO_MODEは前者で、v2.1.207以降はBedrock・Vertex AI・Foundry経由でも立てずにauto modeが使えます。DISABLE_BUG_COMMANDは後者で、DISABLE_FEEDBACK_COMMANDと同じ意味で残っています。古い設定を引き継ぐときは、動いているから正しいとは限らない、という前提で見直す余地があります。

まとめ

Claude Codeの環境変数は、接続先・モデル・自律実行の範囲・挙動調整という4つの層に分けて眺めると、必要なときに引きやすくなります。全件を覚える対象ではなく、目的から入って該当する系列だけを確かめるのが実用的な使い方です。

書いたのに効かないときは、シェルに値が入っているか、書式が10進で正しいか、上位の管理設定に負けていないか、そもそも役目を終えた変数ではないか、という順で見ると原因に当たりやすくなります。既定値そのものがバージョンで変わる領域もあるため、更新のあとに前提を確かめ直す習慣が、無人で長く回す構成ほど効いてきます。Claude Code全体の組み立てから押さえたい場合はClaude Code完全ガイドもあわせて参照できます。