Claude Code の settings.json の優先順位: シェルの値が効かないのは、settings.local.json が強いから
同じ名前の値を、設定ファイルとシェルの環境変数の両方に書いたら、どちらが効くのでしょうか?
試してみると、効いたのは設定ファイルのほうでした。
そこで、値を変えながら、設定の効く順を確かめてみました。
環境
- macOS 26.6
- Claude Code 2.1.309
- 2026年11月1日に確認
動き
新しいリポジトリを作り、設定ファイルの env に TCR_LEVEL という値を書きました。Claude Code に printenv TCR_LEVEL を実行させて、どの値が見えるかを確かめます。実行は claude -p(対話の画面を開かずに、1回の指示を実行して結果を受け取る使い方)で行いました。対話画面や VS Code の拡張機能も、同じ設定ファイルを読みます(公式の VS Code のページによる)。
terminal$ claude -p 'Run the shell command `printenv TCR_LEVEL` and reply with only its exact output.' --allowedTools "Bash(printenv:*)"
.claude/settings.json には、次のように書きました。
json{
"env": {
"TCR_LEVEL": "project"
}
}
.claude/settings.local.json には、同じ名前で local を書きました。上が settings.json、下が settings.local.json です。
--settings が一番強く、settings.local.json が次に強い
同じ名前の値 TCR_LEVEL を置き場所ごとに変えて、Claude Code から見えた値を比べました。
| 置いた設定 | 見えた値 |
|---|---|
.claude/settings.json に project | project |
上に加えて .claude/settings.local.json に local | local |
上に加えて --settings flag.json に flag | flag |
settings.json と settings.local.json があり、シェルで TCR_LEVEL=shell | local |
settings.json だけがあり、シェルで TCR_LEVEL=shell | project |
--settingsで渡したファイル(起動するときに--settings ファイル名で指定する設定ファイル)が一番強い。.claude/settings.local.jsonは.claude/settings.jsonより強い。- 設定ファイルの
envは、シェルの環境変数を上書きする。シェルでexportしても、設定ファイルに同じ名前があれば設定ファイルの値になる。
公式との違い
公式の設定のページには、設定ファイルの優先順位(管理者の設定、コマンドラインの引数、settings.local.json、settings.json、ユーザーの設定の順)が書かれています。手元の結果もこの順と同じでした。設定ファイルの env がシェルの環境変数より先に効くことは、はっきりとは書かれていません。
公式のドキュメントの Settings のページの「Settings precedence」の節に、設定の効く順が図になっています。
Claude Code の中で /config を開くと、今の設定が一覧で見られます。
ユーザーの設定(~/.claude/settings.json)は、普段の設定を変えないように、今回は試していません。
対処
注意点
まとめ
同じ値を設定ファイルとシェルの環境変数に書くと、効くのは設定ファイルのほうでした。設定ファイルどうしでは、--settings で渡したもの、settings.local.json、settings.json の順に強くなります。
シェルで値を変えたのに効かないときは、設定ファイルの env に同じ名前が書かれていないかを見てみてください。
参考文献
著書
挙動Codex 画面を閉じても実は動いてた?常駐プロセスの動きについて検証してみた
挙動Homebrew で入れた Claude Code。更新しているつもりが、古いまま使ってませんか?
使い方Claude Code の拡張機能 2.1.312、2.1.313 は偽物。皆さんの Cursor は大丈夫ですか?
使い方知らぬ間に追加された大量のプラグインやフックが、毎回実行され続けていない? 皆さんの Claude Code は大丈夫ですか?
使い方npm のマルウェアが18日で1,753件! 気づいたら、あなたの GitHub に鍵の一覧が公開されているかも
使い方パスワードが GitHub で丸見えに? 原因は、Claude Code の確認で選んだ「Yes, and don't ask again」
使い方その OpenCode、脆弱性の告知がないからと安心してない? 今のままだと乗っ取られるかも
挙動Codex 画面を閉じても実は動いてた?常駐プロセスの動きについて検証してみた
挙動Homebrew で入れた Claude Code。更新しているつもりが、古いまま使ってませんか?
使い方Claude Code の拡張機能 2.1.312、2.1.313 は偽物。皆さんの Cursor は大丈夫ですか?
使い方知らぬ間に追加された大量のプラグインやフックが、毎回実行され続けていない? 皆さんの Claude Code は大丈夫ですか?
使い方npm のマルウェアが18日で1,753件! 気づいたら、あなたの GitHub に鍵の一覧が公開されているかも



