Claude Code の settings.json の env キーで環境変数を固定する:シェルより優先される仕組みと書き方

ANTHROPIC_MODEL や BASH_DEFAULT_TIMEOUT_MS のような Claude Code の環境変数を、.bashrc や .zshrc に書くと、IDE 拡張やデスクトップアプリから起動したときに効かないことがあります。起動経路によってシェルの初期化が走らないためです。

結論として、settings.json の env キーに書けば、Claude Code がファイルから直接読むため 起動方法に関係なく すべてのセッションとサブプロセスに適用され、シェルで設定した同名の変数より優先されます。

env キーの書き方

env はオブジェクトで、変数名をキー、値を文字列で書きます。

{
  "env": {
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

書いた変数は、Claude Code 本体だけでなく、Bash ツールが起動するコマンドや hooks などの サブプロセスにも 渡されます。プロジェクトで必要な環境変数(例: テスト用のデータベース URL)を Claude が実行するコマンドに確実に渡したい場合にも使えます。

どのファイルに書くかで適用範囲が変わります。

ファイル	適用範囲
~/.claude/settings.json	自分、すべてのプロジェクト
.claude/settings.json	そのプロジェクトで作業する全員(リポジトリにコミット)
.claude/settings.local.json	自分、そのプロジェクトだけ(Claude Code が書き込むときは gitignore される。手で作った場合は自分で gitignore に追加)
管理設定	組織の全員(管理者が配布)

シェルの環境変数との優先関係

同じ変数をシェルと settings の env の両方で設定した場合、settings の値が使われます。Claude Code は env の各エントリをプロセス環境に書き込み、シェルから継承した値を置き換えます。「シェルで一時的に上書きしたい」用途には向かないので、その場合は settings から該当の変数を外すか、一時的なフラグで済む機能(--autocompact など)を使います。

実行中のセッションへの反映

settings.json を保存すると、実行中のセッションは 追加と変更 を環境に反映します。ただし次の 2 点に注意が必要です。

• 起動時に一度だけ変数を読む機能(OpenTelemetry の監視設定など)は、再起動するまで起動時の値のままです
• ファイルから変数を 削除 しても、実行中のセッションでは unset されません。削除は次回の claude 起動から効きます

よく使う組み合わせ

env に書いて効果が分かりやすい変数の例です。それぞれの意味は個別の記事で扱っています。

変数	用途	関連記事
BASH_DEFAULT_TIMEOUT_MS	長いテストやビルドのタイムアウト延長	Bash のタイムアウトと出力上限
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE	自動コンパクトを早める	自動コンパクトのしきい値
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD	追加ディレクトリの CLAUDE.md を読む	--add-dir の CLAUDE.md
CLAUDE_CODE_DISABLE_AUTO_MEMORY	auto memory の停止	auto memory の無効化

settings.json 全体の構造は permissions の設計 と settings.local.json の使い分け で扱っています。

まとめ

• env に書いた変数は起動方法に関係なく、すべてのセッションとサブプロセスに適用される
• シェルの同名変数より settings の値が優先される。settings ファイル間は通常の優先順位に従う
• 保存後、追加と変更は実行中のセッションに反映されるが、起動時にだけ読む機能と削除は再起動まで反映されない
• 共有される .claude/settings.json に秘密情報を書かない
• 値は文字列で書く