--settings（セッティングス）

~/.claude/settings.json などの設定ファイルを書き換えずに、その場限りで設定を上書きしたい人向け

--settings は、Claude Code を起動するときに「今回だけ設定値を差し替えたい」を1行で実現する起動スイッチです。ホームフォルダの ~/.claude/settings.json や、プロジェクト直下の .claude/settings.json を編集して保存…という手順を踏まずに、起動コマンドのうしろにファイル位置を書き足すか、その場で JSON 文字列を渡すだけで済みます。

毎回同じ書き換えを繰り返してるなら別ファイルに切り出すべきですが、「この案件のときだけ少し挙動を変えたい」みたいな一時的な差し替えに強い手段です。

噛み砕くと

会議室のホワイトボードに普段は「禁煙」「撮影禁止」と書いてあるけど、今日の打ち合わせだけ「撮影OK」に上書きする付箋を貼るイメージです。元の文字を消すわけじゃなく、貼った付箋の内容だけが今日のルールとして優先される。会議が終わって付箋を剥がせば、元の「撮影禁止」がそのまま残っています。

--settings も同じで、起動時に貼った付箋＝差し替え値はそのセッション中だけ効きます。ファイル本体は無傷なまま。指定しなかった項目は元のファイルの値がそのまま使われます。

大事な前提：差し替わるのは「指定したキーだけ」

ここを誤解してる人が多いです。--settings で渡したファイルや JSON が、元の設定を全部上書きするわけではありません。

公式は "Keys you omit keep their file-based values" と明記しています。日本語で言うと「書かなかった項目は元のファイルの値を使う」。

つまり {"permissions": {...}} だけ書いた JSON を渡したら、permissions だけが差し替わって、model や env はファイル側の元の値が残ります。差し替えたい項目だけ書けばよくて、設定ファイル全体をコピーしてくる必要はありません。

「料理ブログの新規プロジェクトで permissions だけ厳しくして起動する」を例に手順を見る

普段は ~/.claude/settings.json で許可されているコマンドが、料理ブログのプロジェクトでは少し怖いので一時的に絞りたい、という想定です。

ステップ1: プロジェクトフォルダに入る

まずプロジェクトのフォルダに移動します。

$ cd ~/projects/cooking-blog

ステップ2: 差し替え用の JSON ファイルを作る

このプロジェクト専用の差し替え値を、別ファイルに切り出して作っておきます。プロジェクト共有用の .claude/settings.json ではなく、テスト用に .claude/strict.json という名前で置いてみます。

{
  "permissions": {
    "allow": ["Read(./recipes/**)", "Glob(*)"],
    "deny": ["Write(./**)", "Bash(*)"]
  }
}

これは「recipes/ 配下の読み取りとファイル検索だけ許す。書き込みとコマンド実行は全部止める」という強めの内容です。

ステップ3: そのファイルを指して Claude Code を起動する

$ claude --settings .claude/strict.json

これだけ。普段使っている個人設定 ~/.claude/settings.json は触っていません。このセッション中だけ、permissions が strict.json の内容で上書きされた状態で立ち上がります。

ステップ4: 起動後に「ちゃんと厳しくなってるか」確認する

セッション内で /permissions を叩くと、いま効いてる権限ルールが見えます。deny 側に Write と Bash が並んでいたら成功です。

ステップ5: ファイルを使わず、その場で JSON を直書きする方法

ファイルを作るほどでもない、1回限りの差し替えなら、起動コマンドの後ろに JSON 文字列をそのまま渡せます。

$ claude --settings '{"permissions":{"deny":["Bash(*)"]}}'

シングルクォート '...' で囲むのが安全です。ダブルクォートで囲むと、ターミナルが中の " をエスケープ処理してしまって JSON が壊れます。ここで初心者がやりがちな勘違いがあって、" の中身を \" で逃がそうとして結局ターミナル側との戦いになります。素直にシングルクォートで包むのが事故りません。

ステップ6: 終了すると差し替えは消える

セッションを終わって claude を素のまま叩き直せば、元の ~/.claude/settings.json の内容に戻ります。差し替えは1セッション限定です。

つまり --settings は何をしてくれるのか

• やってくれる: 起動するこの1回だけ、settings.json の特定の項目を別の値に差し替える
• やってくれる: ファイル経由でも、その場の JSON 直書きでも受け付ける
• やってくれない: 元の settings.json を書き換えること。ファイルは無傷のまま
• やってくれない: 指定しなかった項目をリセットすること。書かなかった項目は元の値が引き継がれる
• 意味が薄い場面: 毎回同じ値で起動するなら、最初から settings.json に書いておくべき

名前が似てる --setting-sources とはまったく別物

ここはほぼ全員が一度ハマるところです。

--settings は「値を差し替える」。--setting-sources は「どの設定ファイルを読み込むかを絞る」。やってることが違います。

例えば --setting-sources user,project と書くと、Local の .claude/settings.local.json を無視して、User と Project の設定だけ読み込むようになります。値の差し替えではなく、読み込むファイルの選別です。

整理するとこうです。

• --settings ./foo.json → 値の差し替え。指定したキーが優先される
• --setting-sources user,project → 読み込むファイルの選別。指定したスコープしか読まない

名前が紛らわしいですが、混ぜると挙動が読めなくなります。

優先順位の中での --settings の位置

Claude Code は複数の設定ファイルを重ねて読みます。同じ項目が複数箇所に書かれていたら、強い方が勝ちます。公式の優先順位はこうです。

1. Managed（管理者配布の設定で一番強い）
2. --settings など起動時の差し替え ← ここ
3. Local .claude/settings.local.json ← 個人用
4. Project .claude/settings.json ← チーム共有
5. User ~/.claude/settings.json ← 自分の全体設定

--settings は2番目に強い位置にいます。Managed には勝てないけど、Local・Project・User の値は全部踏み潰せる。これがあるおかげで、プロジェクト側で固定されてる .claude/settings.json の内容を、自分のセッションだけ無視できます。

使いどころ3シナリオ（具体題材で再現）

シナリオ1: 料理ブログプロジェクトだけ書き込み禁止で起動したいとき

料理ブログのプロジェクトは、原稿の本文を Claude にうっかり書き換えられたくない。でも普段は他の案件で Write を許可している。こういうとき .claude/strict.json を1個作って {"permissions":{"deny":["Write(./**)"]}} と書いておいて、料理ブログのときだけ claude --settings .claude/strict.json で立ち上げる。普段の作業に戻るときは何もつけずに claude。設定ファイルを書き換える往復が要らないのが効きます。

シナリオ2: 「家計簿アプリの試作」で別モデルを試したいとき

普段は速くて安いモデルで作業してるけど、家計簿アプリの設計フェーズだけ重めのモデルで議論したい。claude --settings '{"model":"claude-opus-4-7"}' でその場でモデルだけ差し替えて起動。終わったら次回からは元の軽いモデルに戻ります。~/.claude/settings.json を開いて書き換えて、終わったら戻して…という手間が消える。

シナリオ3: 既存 OSS を持ってきた直後、初見で読み込みだけしたいとき

知らない OSS の中身を Claude Code に読んでもらいたいけど、その OSS に同梱されている .claude/settings.json が何を許可してるか分からなくて怖い。こういうとき claude --settings '{"permissions":{"allow":["Read(./**)","Glob(*)","Grep(*)"],"deny":["Write(./**)","Bash(*)"]}}' と渡せば、読み取り系だけ許可した状態で起動できます。プロジェクト側に同梱されている .claude/settings.json の内容より --settings が強いので、ダウンロードしたフォルダ側で何が書かれていても自分の差し替えが優先されます。

初心者が踏みやすい落とし穴

• JSON のクォート戦争。ダブルクォートで JSON を囲むとターミナルが中の " を処理してしまって壊れる。シングルクォート '...' で包むのが事故らない
• 「全部上書きされる」と思い込む。実際は書いた項目だけが差し替えで、書かなかった項目は元のファイルの値が残る。設定ファイル全体をコピーする必要はない
• 名前が似てる --setting-sources と混同する。あちらは読み込むファイルの選別、こちらは値の差し替え。役割が全然違う
• JSON にミスがあると起動失敗する。カンマ忘れや閉じカッコ抜けで JSON が壊れていると Claude Code がエラーで立ち上がらない。ただし元の settings.json は無傷なので、JSON を直して再起動すればいいだけ
• autoMemoryDirectory のようにここでしか差し替えられない設定がある。Project や Local の settings.json では受け付けてもらえず、--settings か User 設定からしか書けない。これはセキュリティ上の理由で意図的にそうなっている。プロジェクトのファイル一式に悪意ある記憶先を仕込めないように、という配慮
• 毎回同じ値で起動するなら settings.json に書け。--settings は一時差し替え用なので、常用するなら最初からファイルに書いて Project や Local の .claude/settings.json に置くべき
• claude agents など他のサブコマンドにも効く。公式 changelog v2.1.142 該当行に「Added new claude agents flags: --add-dir, --settings, --mcp-config, --plugin-dir, --permission-mode, --model, --effort, and --dangerously-skip-permissions to configure dispatched background sessions」とあり、v2.1.142 から claude agents --settings ... も同じ差し替えが効く。それより古い版で「効かない」と踏むことがあるので、claude --version で先に確認しておく

書き方

claude --settings <ファイルの場所、または JSON 文字列>

やってみるとこうなる

入力

claude --settings .claude/strict.json

出力例

起動後にこのセッション内で /permissions を叩くと、strict.json で指定した内容で permissions が差し替わっていることが確認できる。ホーム配下の ~/.claude/settings.json は書き換わっていない。

関連項目

• --setting-sources（セッティングソーセス）
• settings.json（セッティングス・ジェイソン）
• --add-dir（アドディレクトリ）
• --mcp-config（エムシーピー・コンフィグ）
• --bare（ベア）

公式ドキュメント

https://code.claude.com/docs/en/cli-reference