T-CREATOR

<div />

Claude Code の settings.json の優先順位: シェルの値が効かないのは、settings.local.json が強いから

2026年11月2日
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 です。

.claude/settings.json に TCR_LEVEL を project、.claude/settings.local.json に local と書いて、上下に並べて開いた画面

--settings が一番強く、settings.local.json が次に強い

同じ名前の値 TCR_LEVEL を置き場所ごとに変えて、Claude Code から見えた値を比べました。

置いた設定見えた値
.claude​/​settings.json に projectproject
上に加えて .claude​/​settings.local.json に locallocal
上に加えて --settings flag.json に flagflag
settings.json と settings.local.json があり、シェルで TCR_LEVEL=shelllocal
settings.json だけがあり、シェルで TCR_LEVEL=shellproject
  • --settings で渡したファイル(起動するときに --settings ファイル名 で指定する設定ファイル)が一番強い。
  • .claude​/​settings.local.json は .claude​/​settings.json より強い。
  • 設定ファイルの env は、シェルの環境変数を上書きする。シェルで export しても、設定ファイルに同じ名前があれば設定ファイルの値になる。

公式との違い

公式の設定のページには、設定ファイルの優先順位(管理者の設定、コマンドラインの引数、settings.local.json、settings.json、ユーザーの設定の順)が書かれています。手元の結果もこの順と同じでした。設定ファイルの env がシェルの環境変数より先に効くことは、はっきりとは書かれていません。

公式のドキュメントの Settings のページの「Settings precedence」の節に、設定の効く順が図になっています。

公式のドキュメントの Settings のページの Settings precedence の節

Claude Code の中で ​/​config を開くと、今の設定が一覧で見られます。

Claude Code の /config の画面。Settings、Status、Config、Usage、Stats のタブと、設定の一覧が出ている

ユーザーの設定(~​/​.claude​/​settings.json)は、普段の設定を変えないように、今回は試していません。

対処

注意点

まとめ

同じ値を設定ファイルとシェルの環境変数に書くと、効くのは設定ファイルのほうでした。設定ファイルどうしでは、--settings で渡したもの、settings.local.json、settings.json の順に強くなります。

シェルで値を変えたのに効かないときは、設定ファイルの env に同じ名前が書かれていないかを見てみてください。

参考文献

著書

とあるクリエイター

フロントエンドエンジニア Next.js / React / TypeScript / Node.js / Docker / AI Coding

とあるクリエイターのプロフィール