設定は書いたとおりに効くとは限らない——Claude Code 2.1.277が示した4つの経路と点検手順

【重複購入のご注意】この記事は「AI開発者の手帖」がTipsで販売している同名記事（設定は書いたとおりに効くとは限らない——Claude Code 2.1.277が示した4つの経路と点検手順）と同じ内容です。すでにTipsで購入・閲覧できる方は重複購入にご注意ください。

Claude Code の設定ファイルを自分で書き換えている方に向けて、2026年9月18日の 2.1.277 で入った修正の読み方を整理します。この版の一覧には、壊れた設定値が原因の不具合の修正がまとまって入りました。落ちるものもあれば、落ちないまま効かなくなるものもあります。直ったこと自体より、同じ形の設定を自分が持っていないかのほうが後で効きます。

本稿は筆者が公式の changelog とドキュメントを照合して作った判断資料です。手元の実測は macOS・Claude Code 2.1.278 の1台分です。実測／公式の記述／筆者の整理は、本文でそのつど区別します。公式changelog（2026-09-21取得）

「直った」で終わらせると1つ取りこぼす

2.1.277 の一覧には、壊れた設定値にまつわる修正が並んでいます。起動時に落ちる、パネルを開くと落ちる。版を上げれば、落ちること自体は止まります。

ただし注意が要ります。落ちなくなっただけで、壊れた値はそのまま残ります。 落ちないので気づく機会も無くなります。この種のキーについては、版を上げたあとに「いまどんな形で入っているか」を控える作業が残ります（後述の経路3）。

そしてもう1つ、1項目だけ性質が違います。

サンドボックスの除外リストの話です。これまでは、A && B のような複合コマンドのうち一方だけが除外指定に当たれば、コマンド全体がサンドボックスの外で走っていました。2.1.277 以降は、全部が当たらないと除外されません。

これは不具合の修正であると同時に、既存の設定の効き方が変わる変更です。除外リストを持っている人は、版を上げた時点で、これまで外で走っていた複合コマンドがサンドボックスの中に入ります。いままで通っていた操作が急に失敗することも、逆に「意図せず外に出ていた」ことに初めて気づくこともあります。

ここで公式ドキュメントどうしが食い違っています。 設定リファレンスの sandbox.excludedCommands の節は、2026-09-21 に取得した時点で「When any part of a compound command matches an entry, Claude Code runs the whole command unsandboxed」——つまり 2.1.277 より前の挙動——を書いたままです。一方、同じ節がリンクしている権限ページの複合コマンドの項は「A rule must match each subcommand independently」と書いていて、changelog 側と一致します。設定リファレンスの1文が更新されていない、と筆者は読みました（この読みは筆者の整理で、公式の表明ではありません）。版を上げたあとの挙動を確かめるときは、権限ページのほうを見てください。

除外リストそのものについて、公式は条件付きで別のやり方を勧めています。ツールが特定の場所への書き込みを必要としている場合には、サンドボックスから丸ごと外すより書き込み先を足すほうがよい、という書き方です。

出典は公式サンドボックス文書（2026-09-21取得）です。

自分が関係するかは4問で分かれます

問い1：sandbox の除外リストを書いているか。 書いていなければ、いちばん影響の大きい変更は関係ありません。書いているなら、1行ずつ見る対象です。

問い2：プラグインの marketplace 方針を配っているか。 配っている側だけが対象です。2.1.277 より前は、リストの1件が壊れていると方針そのものが黙って無効になっていました。無効になったことは画面に出ません。

問い3：~/.claude.json を手で触ったことがあるか。 触っていなくても、このファイルは Claude Code 自身が書きます。2.1.277 が名指ししたキーが3つあり、うち2つは正しい形を判定できません（後述）。

問い4：同じマシンに古い Claude Code のビルドがあるか。 IDE 拡張が同梱している CLI などです。混在していると、予期しないログアウトが起きていました（2.1.277で修正）。

この4つは、有料部の経路1から経路4と同じ順番です。 問い1・2・4が全部「いいえ」でも、問い3の2キーについては落ちていない今の形を控える作業が残ります（版を上げると落ちなくなる分、壊れていても気づけなくなるため）。1つでも「はい」なら、版を上げる前後で自分の設定を見ておく価値があります。

手元で当てた結果

筆者は上の観点を点検する小さなスクリプトを書いて、自分の環境（macOS・2.1.278）に当てました。判定の核になる部分は有料部に載せています。 結果は要確認0件でした。

この0件は「問題がない」ではありません。 出力には、除外リストと marketplace 方針の行が1つも出ていませんでした。筆者はどちらも設定していないので、検査する対象が空だっただけです。経路1と経路2について、この出力は何も示していません。

自分の環境の出力そのものは載せません。設定の値や件数からでも中身が読めてしまうためです。代わりに、わざと壊した設定に同じ基準を当てた結果を見てください。基準が何を拾うのかは、こちらでないと分かりません。

6か所を壊した設定（managed / user / project の3スコープと ~/.claude.json）に当てると、こう出ます。

壊れている設定は、読めたスコープの中に混ざって出ます。 「読めた」と表示された user スコープの中に、当たらない除外リストの行と、置き場所を間違えたキーが並んでいました。読めるかどうかと、効いているかどうかは別です。

有料部では、この実行結果を6件すべて、省略なしの全文で載せます。

この点検には、合否を出せない部分も残ります。

2.1.277 が名指しした ~/.claude.json のキーは3つです。このうち theme は公式の設定リファレンス（2026-09-21取得）に型が載っていて、文字列で7つの候補か custom: で始まる名前のどれかだと書かれています。だから合否を出せます。

残る customApiKeyResponses と claudeAiMcpEverConnected は、同じ設定リファレンスの全文を検索しても項目がありません。 changelog は「malformed（壊れた値）」としか書きません。この2つは Claude Code が自分で書くキーで、手で編集する前提の設定として文書化されていない、と筆者は読んでいます（この読みは筆者の整理で、公式の記述ではありません）。

したがってこの2つには合否を出せません。できるのは落ちていない今の形を控えておくことだけです。上の出力の最後の行がそれで、あとでクラッシュが出たときに「形が変わったのか」を切り分ける材料になります。

有料部で渡すもの

有料部では、点検スクリプトの判定部分と、除外リスト・marketplace 方針・~/.claude.json に当てる判定基準と、版の混在まわりの確認場所、6か所を壊した設定に当てた実行結果を渡します。内訳はこうです。

• 点検スクリプトの判定部分（Python 3、標準ライブラリだけ。区切りの判定・marketplace の9種類の source・4スコープの読み方の3か所）

• 除外リストの1行ずつに当てる判定基準と、区切りを含む項目がなぜ当たらないのかの読み分け

• marketplace 方針の項目が「正しい形」かを判定する基準（公式が挙げる9種類の source と、それぞれの必須の欄）。このキーは managed settings 以外に書いても効かないので、置き場所の判定も含みます

• 型が公開されているキーの判定基準と、公開されていないキーの控え方・切り分け順序

• 版の混在まわりの確認場所（ここには判定基準がありません。見る場所だけです）

• 上の観点をまとめた点検手順と、6か所を壊した設定に当てた実行結果

対象外：Windows ネイティブ（サンドボックスは非対応）。企業が managed settings を配る運用の実地検証。他のプラットフォームでの挙動。

本稿の実測は macOS の1台分です。複合コマンドの除外が 2.1.277 の前後でどう分かれるかは、公式の changelog 本文と権限ページの記述によります。本稿の記述は、公式の changelog 本文・サンドボックス文書・マーケットプレイス文書・設定リファレンス・権限ページからの整理です。

除外リストを書いている人にとって、いちばん先に知りたいのは「自分のこの行は、版を上げたあと当たるのか当たらないのか」だと思います。そこから始めます。