質問と回答(Q&A)

ログインシェルが zsh で sandbox.enabled が true の場合に報告されている現象です。回避策は 1 行で済みます。

SHELL=/bin/bash claude

報告されている症状は「every sandboxed Bash tool call fails with Exit code 126 and zero bytes of stdout/stderr, in ~1.3s — including shell builtins (true, type echo)」です。true のようなシェル組み込みコマンドまで失敗するのが特徴で、これが「自分の設定が悪いのではない」と判断する手がかりになります。

報告者によれば、サンドボックスの内側で動くスクリプトが exec 3<&- || exit 126 という bash 固有の記法を使っており、すでに閉じているファイルディスクリプタを閉じる操作を bash は許容する一方 zsh は失敗させるため、実際のコマンドを評価する前に 126 で終了する、という流れです。これは報告者の調査で、公式ドキュメントに記載のある挙動ではありません。

項目	内容
条件	Linux、ログインシェルが zsh、sandbox.enabled: true
症状	すべての Bash ツール呼び出しが約 1.3 秒で Exit code 126、出力ゼロ
動作するバージョン	報告者は 2.1.270 / 2.1.286 / 2.1.289 / 2.1.291 で動作を確認
失敗するバージョン	報告者は 2.1.302 と 2.1.309 で再現
回避策	SHELL=/bin/bash claude で起動する

なお macOS の Seatbelt でも同種の報告(#77466)があります。サンドボックスを切って作業を続けるなら、何が自動承認されるかが変わる点に注意してください。モードごとの違いは Claude Code の bypassPermissions と危険な操作の扱い にまとめてあります。

commandPrefix の deny ルールが止めているのは コマンドの名前 であって、操作の結果ではありません。公式ドキュメントは commandPrefix を「A string or array of strings that a shell command must start with」と定義しています。前方一致の名前フィルタです。

つまり commandPrefix = "rm" の deny は、rm で始まるコマンドには一致しますが、次のものには一致しません。

• /bin/rm(絶対パスで始まる)
• xargs rm(別のコマンドで始まる)
• eval "rm ..."(別のコマンドで始まる)
• unlink(同じ結果になる別のコマンド)

報告者は、禁止したはずのコマンドの書き換えを 45 通り試し、6 コマンド分の deny ルールのうち 38 件(84%)がすり抜けたと書いています。一方で true; rm file や echo $(cat secret) のような形は止まっており、ポリシーエンジンは文書どおりに動いています。ずれているのは挙動ではなく、「deny ルールが何を保証してくれるか」という読み手の期待のほうです。

無人実行では、禁止するものを列挙するのではなく、許可するものを列挙してください。 残りが deny か ask_user に落ちる形にします。非対話モードでは ask_user は deny として扱われるため、これが安全側に倒れます。

[[rule]]
toolName = "run_shell_command"
commandPrefix = ["npm test", "npm run lint", "git status"]
decision = "allow"
priority = 100

[[rule]]
toolName = "run_shell_command"
decision = "ask_user"
priority = 10

キー	内容
commandPrefix	コマンドの先頭に一致する文字列、または文字列の配列
commandRegex	コマンド全体に対する正規表現。commandPrefix とは併用できない
decision	allow / deny / ask_user
priority	0 から 999。大きいほど優先される

argsPattern を持たないグローバルな deny ルールには別の効果もあります。対象のツールが モデルのコンテキストから完全に除外される ため、モデルはその選択肢自体を見ません。確実に使わせたくないツールがあるなら、こちらのほうが強い手段です。

公式ドキュメントが OAuth ログインの手順として挙げているのは CLI のコマンドです。「For a server that supports OAuth, run codex mcp login <server-name>」と書かれています。デスクトップアプリのボタンについての記載はありません。CLI で通るなら、まずそちらを正規の手順として扱ってください。

設定は 3 つのクライアント(ChatGPT デスクトップアプリ、Codex CLI、IDE 拡張)で共有されます。既定の保存先は ~/.codex/config.toml です。つまり CLI でログインした結果は、同じ設定を読む他のクライアントからも使えます。

事前登録済みのクライアントを使う場合、クライアント ID はサーバーの追加時に渡します。

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

機密クライアントなら、シークレットも渡します。環境変数から読む形にしてください。

codex mcp add example --url https://mcp.example.com \
  --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

クライアント ID とコールバックは、次の形で config.toml に保存されます。

[mcp_servers.example]
url = "https://mcp.example.com"

[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"

コールバックの既定は http://127.0.0.1/callback です。ポートや URL を変える必要があれば、mcp_oauth_callback_port と mcp_oauth_callback_url で上書きできます。登録方式を 1 回のログインだけ指定したい場合は codex mcp login <server-name> --oauth-client-registration cimd(または dcr)を使います。既定は auto で、この指定は config.toml には保存されません。

設定済みのサーバーの一覧は codex mcp list、対話中の状態は /mcp で確認できます。サーバーの追加方法は Codex CLI に MCP サーバーを追加する config.toml の書き方 にまとめてあります。

エラーメッセージが実際の原因と違うため、ワークスペースの設定をいじっても直りません。

表示されるのは次のメッセージです。

Path not in workspace: Attempted path "/home/you/node_modules" resolves outside
the allowed workspace directories

文面は「ワークスペースの外にある」と言っていますが、報告されているのは プロジェクトの中にある node_modules です。報告者がソースを追ったところ、node_modules・.git・.env というパスの区切りを含むパスは無条件にブロックされ、そのあとワークスペース内かどうかの判定が false を返すため、「外にある」というメッセージに落ちる、という流れでした。これは報告者の調査で、公式ドキュメントに記載のある挙動ではありません。

ワークスペースにディレクトリを足しても解決しません。 原因が別だからです。公式に文書化されているディレクトリの追加方法は次のもので、これはワークスペースの外にあるディレクトリを対象に含めるための機能です。

gemini --include-directories ../lib,../docs

依存関係の中身を読ませたい場合、現時点でできるのは次のどちらかです。

方法	内容
パスを直接渡さない	「この依存の実装を確認して」と伝え、モデル側に探させる
読みたいファイルをコピーする	対象ファイルを作業ディレクトリに写してから渡す

なお v0.65.0 では、無視ファイルのフィルタリングが最適化されてサブツリーの枝刈りが有効になりました(PR #29582)。これは探索の速度の改善で、このエラーの修正ではありません。v0.65.0 の変更点は Gemini CLI v0.65 で未信頼フォルダの設定が読み取り専用に強制 にまとめてあります。

許可の範囲は ツールの種類で変わります。公式ドキュメントの表がそのまま答えになっています。

ツールの種類	「Yes, and don't ask again」の効果
読み取り専用(ファイル読み取り、Grep)	該当なし(そもそも確認されない)
Bash コマンド	リポジトリごと・コマンドごとに恒久的
ファイル編集(Edit / Write)	セッション終了まで
WebFetch	リポジトリごと・ドメインごとに恒久的
WebSearch	リポジトリごとに恒久的

恒久的に保存される場合の保存先は、git リポジトリのルートの .claude/settings.local.json です。worktree から実行した場合もメインのチェックアウトに解決されます。ファイル編集の承認はファイルに保存されません。 表のとおりセッション終了までの効果です。

セッションの権限モードについては、公式ドキュメントに「don't ask again を選ぶとモードが変わる」という記述はありません。モードを変える選択肢は別に用意されていて、プロンプトの 3 番目に出る 「Yes, and switch to auto mode」 がそれです。これはすべてのプロンプトに出るわけではない、とドキュメントに明記されています。

現在のモードは Shift+Tab で切り替えられ、ルールの一覧は /permissions で確認できます。意図せず変わっていないか確かめたいときは、この 2 つで確認してください。

複合コマンドを承認したときの挙動も知っておくと役立ちます。git status && npm test を承認すると、承認が必要なサブコマンドごとに別々のルールが保存されます。この例では npm test のルールが保存されるため、&& の前に何が来ても認識されます。1 つの複合コマンドから保存されるルールは最大 5 件です。

ファイルパスを承認した場合は、[、]、* などの gitignore のパターン文字がエスケープされ、承認したパスだけに一致するルールになります。自分で書いたルールはエスケープされません。

ルールの書き方と優先順位は Claude Code の settings.json で権限を設定する方法 にまとめてあります。

まず「何に使われたか」を推測ではなく数字で見てください。/usage に、そのための内訳が出ます。

画面上部の Session ブロックには、現在のセッションのトークン統計が出ます。金額はトークン数からローカルで定価換算した推定値です(組織が modelPricing を設定している場合は契約レートになり、Total cost の行に at your organization's configured rates の注記が付きます)。請求の確定値は Claude Console の Usage ページで確認します。

Pro・Max・Team・Enterprise のプランでは、同じ /usage にプラン上限に対する内訳も出ます。

項目	内容
Attribution	直近の使用量を、スキル・サブエージェント・プラグイン・個々の MCP サーバーごとに割合で表示する
Behavior flags	long context やキャッシュミスなど、直近の使用量の 10% 以上を占める挙動を表示する
Loops	直近に走った /loop などのセッション内スケジュールタスクを、合計トークンの多い順に表示する

出力が長いことそのものが問題なら、Behavior flags に long context が出ていないか、Attribution で特定の MCP サーバーやサブエージェントが突出していないかを先に見ます。MCP サーバーのツール定義は接続しているだけでコンテキストを使うため、ここが大きいことは珍しくありません。

CLAUDE.md はセッション開始時とコンパクション後にディスクから読み直されます。長すぎると効きが落ちるため、分量の目安は CLAUDE.md はどのくらいの長さが適切か を参照してください。

実際の削減手段とプラン別の上限の考え方は Claude Code の料金と使用量を /cost と /usage で確認する方法 にまとめてあります。

公式ドキュメントの範囲では、対話セッションでバックグラウンドコマンドに制限時間を設ける設定はありません。これは不具合ではなく、文書化された仕様です。

ツールリファレンスは「In a session that runs unattended, such as a run with the -p flag, an Agent SDK application, a CI job, or a cloud session, background Bash and PowerShell commands have a time limit. A local session you work in from a terminal, the desktop app, or the VS Code extension has no time limit on background commands」と書いています。

セッション	バックグラウンドコマンドの制限時間
-p 実行、Agent SDK、CI、クラウドセッション	あり(既定 30 分、最大 2 時間)
ターミナル、デスクトップアプリ、VS Code 拡張	なし

この区別は Claude Code v2.1.288 で入りました。v2.1.285 から v2.1.287 までは、すべてのセッションに制限時間が適用されていました。古い挙動を覚えている場合はこの変更が原因です。

無人セッション側の制限時間は環境変数で延ばせますが、どちらも短縮はできません。

# 30 分の既定を 1 時間に(無人セッションのみ)
export BASH_DEFAULT_TIMEOUT_MS=3600000
# 2 時間の上限を 4 時間に
export BASH_MAX_TIMEOUT_MS=14400000

対話セッションで無限に走るのを防ぐ手段として公式に文書化されているのは、バックグラウンド化そのものを止める次の変数です。

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

この変数は run_in_background パラメータ、タイムアウト時の自動バックグラウンド化、Ctrl+B のショートカットをまとめて無効にします。フォアグラウンドのコマンドはタイムアウトで裏に回らず、その場で停止します。副作用は大きいので、長時間ジョブを扱う作業では使いにくい点に注意してください。

フォアグラウンドのタイムアウトは BASH_DEFAULT_TIMEOUT_MS(既定 2 分)と BASH_MAX_TIMEOUT_MS(既定 10 分)で制御します。詳しくは Bash コマンドのタイムアウトを環境変数で延ばす方法 を参照してください。

アイドル時の自動コンパクトは、公式の設定リファレンスが 5 つの条件をすべて満たす会話 に限って既定で有効としています。トークン数と放置時間はそのうちの 2 つなので、両方を満たしていても他の条件で外れることがあります。

条件	内容
セッション	対話的な ターミナルセッション であること
プロンプトキャッシュ	会話が 1 時間の TTL に乗っていること
機能フラグ	Claude Code が Anthropic から機能フラグを取得できること
サイズ	コンテキストがしきい値(既定 20 万トークン)に達していること
アイドル時間	最後のリクエストから約 54 分が経過し、その時点でコンピューターが起動している こと

デスクトップアプリの Code タブで効かないのは、1 つ目の条件のためです。公式ドキュメントが挙げているのは「interactive terminal session」で、それ以外のセッション種別については書かれていません。

見落としやすいのが最後の条件です。54 分の間にマシンがスリープしていると、起きた時点では走りません。

コンパクトが実際に走った会話には Compacted while idle, before the prompt cache expired と表示されるので、走ったかどうかはこの表示で判別できます。

しきい値と停止は次のとおりです。

{
  "idleCompaction": false
}

# しきい値を 15 万トークンに下げる
export CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS=150000

CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS は正の整数のみを受け付け、それ以外は無視されます。100000 を下回る値は下限の 100000 に引き上げられます。idleCompaction と環境変数はどちらも Claude Code v2.1.290 以降が必要です。それより前のバージョンでは autoCompactEnabled を false にすると止まります。自動コンパクト自体を切ると、アイドル時のコンパクトも一緒に切れます。

v2.1.302 以降は /config に Idle compaction の行が追加され、画面から切り替えられます。

自動コンパクトの窓そのものを変える設定は auto-compact が走る位置を /autocompact と環境変数で変える方法 にまとめてあります。

Codex の PreToolUse フックには、ブロックを伝える方法が 2 つ 公式に用意されています。終了コードに頼らないほうを使えば、シェルが終了コードを書き換えても影響を受けません。

方法 1(終了コード): 公式ドキュメントは「You can also use exit code 2 and write the blocking reason to stderr」と書いています。also という語が示すとおり、これは補助的な書き方です。

方法 2(stdout の JSON): hookSpecificOutput を stdout に出す方法です。こちらは終了コード 0 で動きます。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "本番の設定ファイルは変更できません"
  }
}

公式ドキュメントは、トップレベルに decision を "block" にして reason を添える旧形式も受け付けると書いています。なお PreToolUse では stdout のプレーンテキストは無視されます(「Plain text on stdout is ignored」)ので、JSON として出す必要があります。

Windows 専用のコマンドを指定する手もあります。 フックの設定には commandWindows(TOML では command_windows)があり、公式ドキュメントは「an optional Windows-only command override」と説明しています。管理フックの例では Windows 側のコマンドとして py -3 にスクリプトのパスを渡す形が示されています。シェルの差で終了コードが変わるなら、ここに終了コードを保つ呼び出し方を書くのが筋のよい対処です。

なお、フックを使うには設定で有効にする必要があります。設定リファレンスの features.hooks は「Enable lifecycle hooks loaded from hooks.json or inline [hooks] config」と説明されています。

config.toml の全体像は Codex の config.toml でできる設定 にまとめてあります。

「読み直される部分」と「読み直されない部分」が分かれています。公式ドキュメントはリクエストを 3 層で説明していて、コンパクションの影響はこの層ごとに違います。

層	内容	変わるとき
システムプロンプト	中核の指示、ツール定義	読み込まれるツール定義が変わったとき
プロジェクトコンテキスト	CLAUDE.md、オートメモリ、スコープなしのルール	セッション開始時、/clear または /compact の後
会話	ユーザーのメッセージ、Claude の応答、ツールの結果	毎ターン

CLAUDE.md 自体は読み直されます。 プロンプトキャッシュのドキュメントはコンパクションについて「It reloads project context from disk, which cache-hits only if CLAUDE.md and memory are unchanged since the session started」と書いています。ディスクから読み直す、と明記されています。

読み直されないのは、CLAUDE.md が「読め」と指示しているファイルのほうです。それらは Read ツールで読んだ結果なので会話層にあり、コンパクションは会話層を要約で置き換えます。公式の説明も「Compaction replaces your message history with a summary」です。つまり「指示は残るが、指示に従って読んだ中身は要約に畳まれる」という状態になります。

コンパクション後に残るもの:  CLAUDE.md の「最初に memory index を読め」という指示
コンパクション後に消えるもの: 実際に読んだ memory index と protocol ファイルの中身

サブディレクトリの CLAUDE.md と paths: 付きのルールも会話層です。公式ドキュメントは「After it loads, the content is part of the conversation history」と書いています。

実務的には、コンパクションの直後に「memory index を読み直してから続けて」と 1 回指示するのが確実です。/compact は作業の切れ目で自分のタイミングで実行するほうが、作業中に自動で走るより扱いやすくなります。

なお Claude Code v2.1.293 で「コンパクション前の自分の操作を、コンパクション後に完了済みとして扱ってしまう」不具合が修正されています。古いバージョンを使っている場合は先に更新してください。

コンパクションで何が残り何が消えるかは コンテキスト管理と /compact・/clear の使い分け にまとめてあります。

公式ドキュメントの「How the classifier evaluates actions」には、auto モードでの判定が先に一致したものが勝つ 4 段階として書かれています。読み取りが止まる原因は、この順序のどこに当たっているかで切り分けられます。

段階 2 が基本の挙動です。「Read-only actions and file edits in your working directory are auto-approved」とあり、作業ディレクトリ内の読み取りは分類器に行かずに自動承認されます。つまり、それでもブロックされているなら例外のどれかに当たっています。

考えられる原因を、起きやすい順に挙げます。

1. サーバー側の分類器レビューが効いている: 同じ段階 2 の例外として「In a session with server-side classifier review, read-only and sandboxed shell commands wait for that review and are blocked if it flags them」と書かれています。読み取り専用のコマンドが待たされ、フラグが立てばブロックされる、というのはここだけに書かれた挙動です
2. 作業ディレクトリの外にある: 「the first read outside the working directories」は確認のプロンプトが出ます。コンテキストファイルがリポジトリの外にあると該当します。/add-dir か設定の additionalDirectories で作業ディレクトリに加えると変わります
3. deny ルールに一致している: 段階 1 で即座に解決します。deny はどのモードでもブロックします
4. ネットワークパス(UNC)からの読み取り: allow ルールがあっても確認のプロンプトが出ます

ブロックされた理由の見方も決まっています。「If the classifier blocks, Claude receives the reason. In most sessions the reason names the rule the classifier matched, such as [Data Exfiltration], rather than giving a written explanation」とあり、多くの場合は文章ではなく一致したルール名が返ります。

モードごとの違いは Claude Code の権限モード にまとめてあります。

公式ドキュメントには「Why usage climbs in a long session」という節があり、活動量の割に消費が大きくなる理由が整理されています。コードレビューはその条件に当てはまりやすい作業です。

いちばん効くのはコンテキストの長さです。「Claude Code sends your full conversation with every request, and each time Claude uses tools it sends another request carrying that batch of tool results」とあります。レビューはファイルを次々に読むため、ツール呼び出しのたびにリクエストが発生し、そのリクエストはそれまでに読んだ全ファイルを含む会話全体を運びます。読む量が増えるほど 1 リクエストあたりの入力が増えるので、消費は読んだファイル数に対して線形ではなく、より速く伸びます。

次にキャッシュミスです。プロンプトキャッシュのライフタイムはサブスクリプションで 1 時間、使用量クレジットを使い始めると 5 分に下がります。それを超える中断のあとの最初のメッセージは、コンテキスト全体を再処理します。

サブエージェントを使っていた場合、それぞれが独自のリクエストを送ります。エージェントチームはさらに重く、teammate が plan モードで動くチームは通常のセッションの約 7 倍のトークンを使うと明記されています。

実際に何が効いたかは /usage で確認できます。Pro・Max・Team・Enterprise では、直近の利用のうち 10% 以上を占める挙動(長いコンテキスト、キャッシュミスなど)が behavior flags として表示されます。d と w で 24 時間と 7 日を切り替えられます。

次回に向けて公式ドキュメントが挙げている手は次のとおりです。

1. 無関係な作業に移るときに /clear する。/compact は要約対象の会話を読むため、それ自体が大きなリクエストになる
2. 長い出力を伴う作業をサブエージェントに委譲し、要約だけをメインの会話に返す
3. /effort または /model で effort を下げる。thinking トークンは出力トークンとして課金される
4. モデルを使い分ける。Sonnet はほとんどのコーディング作業をこなし、Opus より安価

詳しい手順は Claude Code の利用状況とコストを確認する にまとめてあります。

「Untrusted Command Flags」という警告そのものは、2026 年 10 月 12 日時点の公式の設定リファレンスとコマンドリファレンスでは確認できませんでした。この名前のチェックを無効にするキーも見つかりません。したがって以下は、MCP ツールの確認そのものを減らすために公式に用意されている手段です。

1. サーバー単位で信頼する(設定ファイル)

mcpServers.<サーバー名>.trust は、公式ドキュメントで「trusts the server and bypasses tool call confirmations」と説明されています。そのサーバーのツール呼び出しの確認を飛ばします。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "trust": true
    }
  }
}

~/.gemini/settings.json(ユーザー)または .gemini/settings.json(プロジェクト)に書きます。

2. ツール名を指定して飛ばす(起動時)

--allowed-tools は「A comma-separated list of tool names that will bypass the confirmation dialog」と説明されています。サーバー全体ではなく、ツール単位で絞れます。

3. 承認モードを見直す

general.defaultApprovalMode の値は default、auto_edit、plan の 3 つです。YOLO モードは設定ファイルからは有効にできず、コマンドラインの --yolo または --approval-mode=yolo だけです。--approval-mode と --yolo は併用できません。また security.disableYoloMode を true にしている環境では、フラグで指定しても YOLO は無効になります(再起動が必要)。組織の管理端末でこれが設定されている可能性があるので、意図せず無効化されていないかを確認してください。

MCP サーバーの設定の書き方は Gemini CLI に MCP サーバーを追加する にまとめてあります。

まず仕様として確認できる部分と、確認できない部分を分けます。

確認できる部分: ツール単位の承認は公式に設定できます。サーバー全体の既定が default_tools_approval_mode、個別のツールの上書きが tools.<tool>.approval_mode です。公式ドキュメントの記述は「Default approval behavior for tools from this server. Supported values are auto, prompt, writes, and approve」と「Per-tool approval behavior override」です。

[mcp_servers.google-ads]
command = "..."
default_tools_approval_mode = "prompt"

[mcp_servers.google-ads.tools.list_accounts]
approval_mode = "approve"

確認できない部分: 4 つの値のうち、公式ドキュメントが意味を説明しているのは writes だけです(「The writes mode prompts for tools that aren't marked read-only」)。auto、prompt、approve が具体的に何をするかは、設定リファレンスにも MCP のページにも書かれていません。

ただし公式の設定例は、サーバーの既定を prompt にしたうえで、特定のツールだけ approval_mode = "approve" にする形になっています。この並びからは approve の方が緩い(プロンプトを出さない)側として使われていると読めますが、ドキュメントがそう明言しているわけではありません。

「Always allow」の持続範囲: UI で選ぶ「Always allow」がチャットをまたいで残るかどうかは、公式ドキュメントでは確認できませんでした。Codex のドキュメントで「Always allow」の持続について書かれているのは Browser Use と Windows の Computer Use の項目で、MCP ツールについての記述はありません。

承認を出さずに済ませる別の手として、enabled_tools(公開するツールの許可リスト)と disabled_tools(その後に適用される拒否リスト)があります。ただしこれはツールを出すかどうかの制御で、承認の挙動を変えるものではありません。

MCP サーバーの設定の全体像は Codex に MCP サーバーを追加する にまとめてあります。

まず切り分けのポイントが 1 つあります。claude mcp add が出す Added ... は、設定が書けたことを示すだけです。公式ドキュメントにも「claude mcp add confirms a successful add by printing an Added ... line, which means the configuration was written」とあり、接続できたかの確認は別で「To check that Claude Code connected, run claude mcp get <name>」と案内されています。まず claude mcp get <name> を見てください。

プロジェクトスコープ(.mcp.json)に追加した場合は、承認が終わるまで使えません。/mcp の表示は ⏸ Pending approval (run claude to approve) になり、ドキュメントは「Run claude interactively to review and approve it」と書いています。ここで止まっているケースは「再起動したら直った」に見えやすい挙動です。

セッション中に読み込ませる手段として公式に書かれているのは次のとおりです。

手段	対象	注意
/mcp のサーバーメニューから Reconnect	個別のサーバー	接続済み・失敗済みのサーバーではキャッシュエントリも破棄する
/mcp reconnect all	失敗・認証待ちのサーバーすべて	対話ターミナルでは v2.1.284 以降が必要。それ以前は MCP server "all" not found と表示される
/reload-plugins	プラグイン提供のサーバー	対話ターミナルのないセッションでは接続・切断を行わず、次のセッションから反映される
/cd でセッションを移動	移動先の設定で有効なプラグインのサーバー	v2.1.246 以降。移動後に /reload-plugins は不要

なお /mcp でサーバーをオフにしても設定は消えません(「Toggle a server off in the /mcp panel to stop Claude Code from connecting to it without losing its configuration」)。削除は claude mcp remove で行い、リモートサーバーを削除すると保存済みの OAuth トークンとクライアント登録も消えます。

スコープごとの違いは Claude Code の MCP サーバーのスコープ にまとめてあります。

omitClaudeMd は 起動時に積む初期コンテキストから外す設定で、セッション中に後から読み込まれるものには効きません。公式ドキュメントの該当箇所は「What loads at startup」という見出しの下にあり、そこが適用範囲です。

frontmatter リファレンスの記述はこうです。「Set to true to launch this subagent without the user, project, and local CLAUDE.md files; managed policy files still load, except for managed subagents」。外れるのはユーザー・プロジェクト・ローカルの CLAUDE.md の 3 つで、管理ポリシーのファイルは残ります。

一方、メモリのドキュメントは、プロジェクト指示を最も強く外す managed-only の設定についても「A subdirectory's CLAUDE.md and .claude/rules/ files, and path-scoped rules, still load on demand」と書いています。サブディレクトリの CLAUDE.md とパススコープのルールは、そのディレクトリのファイルを読んだ時点でオンデマンドに読み込まれます。起動時の除外設定でこれを止める手段は、公式ドキュメントには書かれていません。

--agent で起動した場合はさらに単純です。omitClaudeMd の行には「Ignored when the agent runs as the main session agent via --agent or the agent setting」とあり、「Run the whole session as a subagent」の節にも「CLAUDE.md files and project memory still load through the normal message flow, even when the agent's definition sets omitClaudeMd」と明記されています。無視されるのが仕様です。

---
name: doc-writer
omitClaudeMd: true
---
この文書作成エージェントは、委譲プロンプトに書かれた内容だけで作業します。

この設定は、claude --agent doc-writer では効きません。サブエージェントとして呼ばれたときだけ効きます。

守らせたいルールがある場合、公式ドキュメントが案内しているのは委譲プロンプトに書き直す方法です。「If a rule must, such as "ignore the vendor/ directory," restate it in the prompt you give Claude when delegating」。あわせて「The main conversation still has your full CLAUDE.md when it reads these subagents' results, so most rules don't need to reach the subagent itself」とも書かれており、ルールを親会話側に置く設計が前提になっています。

パススコープのルールの仕組みは Claude Code のパススコープルール にまとめてあります。

「週の上限に達した」というメッセージは、モデルをまたいで共有されるプラン側の利用枠です。公式ドキュメントには「a seat-based usage window on a subscription plan, shared across all models, so the developer can't restore access by switching models with /model」と書かれており、/model でモデルを変えても枠は戻りません。モデル別の「You've hit your Opus limit」「You've hit your Sonnet limit」というメッセージだけは、別系列のモデルに切り替えれば作業を続けられます。

その枠の大きさが契約どおりかは、公式ドキュメントでは判断できません。プラン別の上限値はドキュメントに載っておらず、料金ページとヘルプセンターに案内されています。不具合を疑う場合は claude.ai にサインインして左下のイニシャルから Get help を使うのが公式の窓口です。

ただし「活動量の割に枠を消費する」理由は公式に整理されています。長時間開いたセッションでは、会話全体が毎リクエストに付くため、1 行の質問でも 1 日分の会話に対して枠が引かれます。キャッシュのライフタイムはサブスクリプションで 1 時間で、それを超える中断のあとの最初のメッセージはキャッシュを外して全文を再処理します。

継続して使うために公式ドキュメントが挙げている手段は次のとおりです。

1. /usage を開く。Pro・Max・Team・Enterprise では、直近の利用のうち 10% 以上を占める挙動(長いコンテキスト、キャッシュミスなど)が behavior flags として表示されます。d と w で 24 時間と 7 日を切り替えられます。
2. /effort または /model の画面で effort を下げる。thinking トークンは出力トークンとして課金されます。なお Opus 5.5・Sonnet 5.5・Haiku 5.5・Fable 系では thinking 自体をオフにはできません。
3. モデルを使い分ける。Sonnet はほとんどのコーディング作業をこなし、Opus より安価です。Opus は複雑な設計判断や多段の推論に限定します。
4. 無関係な作業に移るときは /clear する。/compact は要約対象の会話を読むため、それ自体が大きなリクエストになります。
5. エージェントチームを使っているなら減らす。teammate が plan モードで動くチームは、通常のセッションの約 7 倍のトークンを使うと明記されています。

上限に達したあとは、/usage-credits で追加の枠を申請できます(API キー認証では使えません)。Claude Code v2.1.234 以降は、リセットを待って中断した作業を自動で続ける選択肢もあり、/rate-limit-options から選べます。

詳しい手順は Claude Code の利用状況とコストを確認する にまとめてあります。

このエラー文が出ている時点で、granular 形式の approval policy が実際に効いています。approval_policy は on-request、never、または { granular = { ... } } の 3 形態で、granular 形式では承認プロンプトの種類ごとに「出すか、自動で拒否するか」を決めます。公式の設定リファレンスに載っているフィールドは次の 5 つです。

フィールド	true のときの意味
sandbox_approval	サンドボックスのエスカレーション承認プロンプトを出す
rules	execpolicy の prompt ルールによる承認を出す
mcp_elicitations	MCP の elicitation プロンプトを自動拒否せず出す
request_permissions	request_permissions ツールからのプロンプトを出す
skill_approval	スキルスクリプトの承認プロンプトを出す

sandbox_approval が false だと、サンドボックスのエスカレーション承認はプロンプトを出さずに拒否されます。エラー文はその状態をそのまま述べたものです。対話的に承認したいなら、~/.codex/config.toml に次のどちらかを書きます。

# 承認プロンプトをすべて出す(対話実行の推奨値)
approval_policy = "on-request"

# 種類を選んで出す
[approval_policy.granular]
sandbox_approval = true
rules = true
mcp_elicitations = true
request_permissions = true
skill_approval = true

untrusted は未サポート、on-failure は非推奨で、対話実行では on-request を使うよう公式に案内されています。

ユーザーの config.toml に approval_policy を書いていないのにこのエラーが出る場合、値はそれ以外の経路から来ています。公式ドキュメントには、Agent Security UI で管理者が「Allowed approval policies」を指定する managed requirements の仕組みが載っており、これは管理者側の設定でユーザー設定ではありません。もう 1 つ関係するキーが approvals_reviewer で、「on-request または granular の承認ポリシーで、対象の承認プロンプトを誰がレビューするか」を決め、既定は user です。この設定はサンドボックス自体や、サンドボックス内で既に許可されている動作を変えません。

設定の全体像は Codex の承認ポリシーとサンドボックスの設定 にまとめてあります。

このメッセージは「その操作は承認を求める必要があるが、承認ポリシーが never なので誰にも聞けない」という状態を指しています。承認を出せないので、そのまま拒否されます。

2026 年 10 月 6 日時点の公式設定リファレンスでは、approval_policy に指定できる形は 3 つです。

値	挙動
on-request	対話的な実行向け。必要なときに確認を出す
never	非対話的な実行向け。確認を出さない
{ granular = { ... } }	確認の種類ごとに、出すか自動で拒否するかを決める

ドキュメントにはこう書かれています。

untrusted is unsupported, and on-failure is deprecated; use on-request for interactive runs or never for non-interactive runs.

(untrusted はサポートされず、on-failure は非推奨です。対話的な実行には on-request、非対話的な実行には never を使ってください。)

手元で操作しながら使っているなら、never ではなく on-request が想定された値です。

approval_policy = "on-request"

一部の確認だけ出したい場合は granular を使います。true にした種類だけ確認が表に出て、false の種類は自動的に拒否されます。

[approval_policy.granular]
sandbox_approval = true      # サンドボックスのエスカレーション確認
rules = true                 # execpolicy の prompt ルールによる確認
mcp_elicitations = true      # MCP の elicitation
request_permissions = true   # request_permissions ツールからの確認
skill_approval = true        # スキルスクリプトの承認確認

外部サービスの操作が止まる場合は mcp_elicitations が関係します。never のままだと、MCP サーバーからの確認要求が自動で拒否されるため、サインインや許可を求める操作が進みません。

なお、引用元の報告は「同じ操作が Web では成功し、デスクトップアプリでは失敗する」という内容で、bug ラベルが付いています。プラットフォーム間で有効な承認ポリシーが食い違う原因そのものは、公式ドキュメントでは確認できませんでした。 設定を直しても解消しない場合は、その報告の経過を追ってください。

承認ポリシーとサンドボックスの組み合わせは Codex の承認モードとサンドボックスを使い分ける にまとめています。

設定が足りないわけではありません。.git は 保護パス(protected paths) で、permissions.allow では通せない仕組みになっています。公式ドキュメントに明記されています。

permissions.allow rules in settings files do not pre-approve protected-path writes. The safety check runs before Claude Code evaluates allow rules from settings.

(設定ファイルの permissions.allow ルールは、保護パスへの書き込みを事前承認しません。この安全性チェックは、Claude Code が設定ファイルの allow ルールを評価する 前 に動きます。)

順序が逆なので、Edit(.git/**) のような allow ルールを足しても結果は変わりません。--add-dir も作業範囲を広げるだけで、保護パスの判定には効きません。

モードごとの挙動は次のとおりです。

モード	保護パスへの書き込み
default、acceptEdits	確認プロンプトが出る
plan	対話的なターミナルで bypass permissions が使える場合は許可。それ以外は auto モードが使えるなら分類器へ、使えないなら確認
auto	分類器へ回される
dontAsk	拒否される
bypassPermissions	許可される

acceptEdits では「自動承認されない」のであって「禁止」ではありません。確認プロンプトに答えれば書き込めます。プロンプトを表示できない経路(dontAsk や、確認を出せない実行環境)では拒否として見えます。

保護ディレクトリは .git だけではありません。

.git  .config/git  .vscode  .idea  .husky  .cargo
.devcontainer  .yarn  .mvn  .claude(一部例外あり)

保護ファイルも指定されており、.gitconfig、.gitmodules、シェルの設定(.bashrc、.zshrc、.envrc など)、パッケージマネージャの設定(.npmrc、.yarnrc、bunfig.toml など)、.pre-commit-config.yaml、.mcp.json、.claude.json が含まれます。

どうしても自動で書き込みたい場合、公式に用意されているのは bypassPermissions モードだけです。ただしこのモードは保護パスの確認ごと飛ばすため、ドキュメントはコンテナや VM のような隔離環境に限って使うよう求めています。.git を書き換える作業は、Claude に任せず git コマンド経由で行うほうが安全です。

ルールの書き方と評価順序は Claude Code の settings.json で権限を設定する にまとめています。

理由は 2 つあります。

1. Sonnet 5.5 では拡張思考そのものを止められません。 公式のモデル設定ドキュメントに明記されています。

You can't turn thinking off on Opus 5.5, Sonnet 5.5, or the Fable models.

(Opus 5.5、Sonnet 5.5、Fable のモデルでは、思考をオフにできません。)

同じ箇所に、これらのモデルではセッションの切り替えと /config の行が Thinking can't be turned off と表示され、保存済みの alwaysThinkingEnabled: false や MAX_THINKING_TOKENS=0 も 効果がない と書かれています。Sonnet 5.5 は適応的推論(adaptive reasoning)を常に使うモデルで、思考の量を動かす主たる操作は effort レベルです。

モデル	指定できる effort
Opus 5.5、Sonnet 5.5、Opus 5、Sonnet 5、Opus 4.8、Opus 4.7	low / medium / high / xhigh / max
Opus 4.6、Sonnet 4.6	low / medium / high / max

/effort を引数なしで実行するとスライダーが開き、/effort low のように直接指定もできます。/effort auto で、そのモデルに保存した値を消せます。

2. 長いセッションでは、消費の主因が思考ではなくコンテキストです。 Claude Code は毎回のリクエストで会話全体を送ります。ツールを使うたびに、その結果を載せた別のリクエストがもう 1 往復します。公式ドキュメントの「Why usage climbs in a long session」には、主な原因として長いコンテキスト、キャッシュミス、スケジュールされたタスク、サブエージェント、コンパクションが挙げられています。

a one-line question in a session that has been open all day still draws usage for the whole conversation

(一日中開いたままのセッションでの一行の質問でも、会話全体分の使用量を引きます。)

effort を下げても、この部分は減りません。効くのは次の操作です。

やること	効果
作業の区切りで /clear	以後のリクエストから会話履歴が消える
長くなったら /compact	履歴を要約して 1 リクエストあたりのトークンを減らす
読ませる範囲を絞る	「ログ全体」ではなく「エラー行の前後 20 行」と指示する
モデルを使い分ける	定型作業は軽いモデルに回す

Pro・Max・Team・Enterprise のプランでは、/usage が直近の使用量の 10% 以上を占める挙動(長いコンテキスト、キャッシュミスなど)を指摘してくれます。まずそこを見ると、どれが効いているか分かります。詳しい手順は Claude Code の料金と使用量の確認方法 にまとめています。

応答の言葉づかいを毎回そろえる仕組みは 出力スタイル(output style) です。公式ドキュメントはこう説明しています。

An output style is a set of instructions that sets Claude's role, tone, and response format for every response in a session.

(出力スタイルは、セッション中のすべての応答について、Claude の役割・口調・応答形式を決める指示のまとまりです。)

CLAUDE.md に「日本語で答えて」と書く方法もありますが、そちらはプロジェクトについて知っておくべき内容を置く場所で、守られる保証はありません。ドキュメントの対応表でも、「すべての応答を特定の声・長さ・形式にしたい」場合は出力スタイルを使う、と整理されています。

「元に戻る」原因として多いのは保存先です。 /output-style コマンドと 2 つのメニューは、選択を プロジェクトローカルの .claude/settings.local.json に保存します。別のプロジェクトでセッションを開くと、その設定は効きません。全プロジェクトで既定にするには、~/.claude/settings.json に書きます。

{
  "outputStyle": "Concise"
}

値は 大文字小文字を区別します。組み込みのスタイル名は Proactive、Concise、Explanatory、Learning です。explanatory のように一致しない値を書くと Default になります(/output-style コマンドのほうは大小を無視します)。プロジェクト側の設定ファイルはユーザー設定より優先されます。

言語を指定する独自のスタイルは、Markdown ファイルとして作ります。保存先は ~/.claude/output-styles(ユーザー)、.claude/output-styles(プロジェクト)、管理ポリシーのいずれかです。

---
name: Japanese
description: 常に日本語で応答する
keep-coding-instructions: true
---

ユーザーへの応答は常に日本語で書いてください。コード、コマンド、ファイルパス、エラーメッセージの原文はそのまま残します。

keep-coding-instructions: true を付けないと、Claude Code 組み込みのソフトウェア開発向けの指示が外れます。応答の言語だけ変えたい場合は必ず付けてください。

ターミナルではスタイルファイルを起動時に読むため、セッション中に作成・編集した場合は再起動が要ります。設定ファイルの優先順位は .claude/settings.local.json の使い分け を参照してください。

まず押さえるべきは、Claude Code の支払い経路が 2 つあり、クレジットの種類が経路ごとに別物だという点です。どちらで動いているかは /status で確認できます。

経路	課金	使えるクレジット
claude.ai のサブスクリプション(Pro / Max / Team / Enterprise)	月額。上限はシートごとの割り当て	「使用クレジット(usage credits)」で上限を超えて続行できる
Claude Console の API キー	トークン従量課金	Console のアカウント残高

サブスクリプション側の仕組みが 使用クレジット です。公式ドキュメントによると、管理するには /login で claude.ai のサブスクリプションにサインインしてから /usage-credits を実行します。重要なのは次の一文です。

the command isn't available with API key authentication

(このコマンドは API キー認証では使えません。)

つまり、API キーで動かしているセッションからは使用クレジットの画面に入れません。逆に、サブスクリプションでサインインしているセッションは Console の残高を消費しません。「クレジットがあるのに使われない」ように見える場合、クレジットの置き場所と、セッションの認証経路が食い違っている可能性があります。

役割ごとに /usage-credits が開く先も違います。

立場	/usage-credits の動作
Pro / Max	claude.ai の Settings > Usage を開く。オン・オフ、残高、今月の支出、月の上限を確認できる
Team / Enterprise(請求権限あり)	組織の Organization settings > Usage を開く
Team / Enterprise(請求権限なし)	確認のうえ、組織の管理者に申請を送る

なお、「プロモーションクレジット」という語は公式ドキュメントでは確認できませんでした。キャンペーンで付与された残高が Claude Code のどの経路に充当されるかは、配布元の条件によります。アカウント固有の請求の疑問は、公式ドキュメントがサポートへの導線を案内しています。サブスクリプションなら claude.ai にサインインして左下のイニシャルから「Get help」、Console の請求なら platform.claude.com で同じ手順です。

支払い方式の違いと使用量の見方は Claude Code の料金と使用量の確認方法 にまとめています。

文章で「このフォルダだけ」と伝えても、それは境界になりません。Claude Code の作業範囲を決めるのは、起動したディレクトリと、そこに追加したディレクトリです。公式ドキュメントにはこうあります。

By default, Claude has access to files in the directory where you launched it.

(既定では、Claude は起動したディレクトリの中のファイルにアクセスできます。)

プロジェクトの中で起動していれば、その配下すべてが対象です。プロンプトでサブフォルダ名を挙げても、対象が狭まるわけではありません。~/.claude/settings.json のようにホーム配下のファイルが編集された場合は、別の経路(ホームディレクトリで起動した、--add-dir で追加した、additionalDirectories に入っている)で範囲に入っていたと考えられます。現在の範囲は /status で確認できます。

本当に止めたい場合は、設定で縛ります。

{
  "permissions": {
    "deny": [
      "Edit(~/.claude/**)",
      "Edit(//**)"
    ],
    "ask": [
      "Edit"
    ],
    "blockReadsOutsideWorkingDirectories": true
  }
}

評価の順序は deny → ask → allow で、最初に一致したものが結果を決めます。ルールの具体性は順序を変えないので、広い deny は狭い allow より優先されます。

permissions.blockReadsOutsideWorkingDirectories を true にすると、囲った範囲の外のパスをすべての権限モードでファイルツールが拒否します。auto モードでは、作業ディレクトリ外を最初に読もうとしたときに Claude Code 側から有効化を提案します。

作業範囲そのものを狭めたいなら、対象のフォルダで起動するか、/cd <パス> でセッションごと移動します。設定全体の組み立ては Claude Code の settings.json で権限を設定する を参照してください。

承認する方法はあります。公式の auto モード設定ドキュメントに 4 通り載っています。

まず、チャットで「はい」と答えても通らない理由です。ドキュメントによると、分類器の soft_deny を上書きできる「明示的な意図」とは、ユーザーのメッセージが、Claude がこれから取る操作そのものを直接かつ具体的に述べている場合です。一般的な依頼は該当しません。「リポジトリを整理して」は force push を許可しませんが、「このブランチを force push して」は許可します。単なる「はい」は、操作を具体的に述べていないので意図として扱われません。

手段は次のとおりです。

やりたいこと	方法
今後この種の操作を確認なしで通す	autoMode.allow に散文でルールを追加する(soft_deny の例外として働く)
今回だけ通す	次のメッセージで操作を具体的に書いて再試行させる
拒否された呼び出しを拾い直す	/permissions の Recently denied タブで対象を選び r を押す。ダイアログを閉じると再試行が許可される
設定ファイルを開かずに追加する	/permissions の Auto mode タブ(v2.1.246 以降)

autoMode.allow は ~/.claude/settings.json に書きます。プロジェクトの .claude/settings.json と .claude/settings.local.json からは読まれません。リポジトリに置いたファイルが自前の許可ルールを注入できないようにするためです。既定のルールを残したまま追加するには、配列に "$defaults" を含めます。

{
  "autoMode": {
    "allow": [
      "$defaults",
      "未 push のコミットに対する git commit --amend --reset-author は許可する: 著者情報の修正のみで、公開済み履歴は書き換えない"
    ]
  }
}

拒否された Git Destructive ルールの全文は claude auto-mode defaults --label 'Git Destructive' で読めます(v2.1.208 以降)。このルールには「ユーザーが amend / reword / fixup を依頼した場合は解除される」という条件も含まれているため、依頼の書き方だけで通ることもあります。

前提が公式ドキュメントと異なります。CLAUDE.md は システムプロンプトには入っていません。公式のメモリのドキュメントにこう書かれています。

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions.

(CLAUDE.md の内容は、システムプロンプトの一部ではなく、システムプロンプトの 後ろに置かれるユーザーメッセージ として渡されます。Claude はそれを読んで従おうとしますが、厳密な遵守は保証されません。曖昧な指示や矛盾する指示では特にそうです。)

つまり「システムプロンプトに入っているのだから必ず適用されるはず」という期待が、設計と合っていません。読み込まれていること自体は /context の Memory files で確認できます。そこに出ていれば、Claude は見えています。

遵守率を上げる方法として、ドキュメントは次を挙げています。

• 指示を具体的にする。「コードを整形する」ではなく「2 スペースのインデントを使う」のように検証できる書き方にする
• CLAUDE.md 同士、サブディレクトリの CLAUDE.md、.claude/rules/ の間で矛盾していないか見直す。矛盾があると Claude はどちらかを任意に選びます
• 1 ファイル 200 行未満に収める。長いファイルはコンテキストを多く消費し、遵守率を下げると明記されています

特定の時点で必ず実行されなければならない指示(コミット前、ファイル編集後など)は、文章ではなくフックとして書きます。フックはライフサイクルの決まった時点でシェルコマンドとして実行され、Claude の判断に関係なく適用されます。

本当にシステムプロンプトのレベルに置きたい場合は、起動時に --append-system-prompt を渡します。対話利用よりスクリプトや自動化に向いた方法です。

CLAUDE.md にできるのは「Claude が何をしようとするか」を変えることまでで、「何が許されるか」を決める仕組みではありません。公式の権限ドキュメントにこう明記されています。

Permission rules are enforced by Claude Code, not by the model. Instructions in your prompt or CLAUDE.md shape what Claude tries to do, but they don't change what Claude Code allows.

(権限ルールを強制するのは Claude Code であって、モデルではありません。プロンプトや CLAUDE.md の指示は Claude が何をしようとするかを左右しますが、Claude Code が何を許すかは変えません。)

つまり「明示的な合図がないかぎり実行しない」のようなルールは、CLAUDE.md に書いただけでは保証されません。読み込まれてはいるが、守るかどうかはモデルの判断に委ねられます。同じドキュメントは、実際に強制する手段として /permissions、権限ルール、権限モード、PreToolUse フックの 4 つを挙げています。

確実に止めたい操作があるなら、settings.json の permissions に書きます。評価の順序は deny → ask → allow で、最初に一致したルールが結果を決めます。ルールの具体性は順序を変えないので、広い deny は狭い allow より優先されます。

{
  "permissions": {
    "ask": [
      "Bash",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  }
}

条件がもっと複雑な場合は PreToolUse フックを使います。公式ドキュメントによると、PreToolUse フックはツール呼び出しのたびに、権限の確認プロンプトより前に実行され、その出力で呼び出しを拒否する・確認を強制する・確認を飛ばすのいずれかを選べます。終了コード 2 で終わると、権限ルールの評価より前にツール呼び出しが止まります。

なお、フックの判断は権限ルールを飛び越えません。deny ルールと ask ルールはフックの戻り値に関係なく評価され、一致する deny があれば呼び出しは止まり、一致する ask はフックが "allow" を返しても確認を出します。

セッションをまたいで挙動が揺れる点についても、CLAUDE.md は毎回読み込まれますが、過去の文脈の要約をどう扱うかはモデル側の判断です。ここを固定したい場合も、文章ではなく permissions かフックで縛るのが確実です。

詳しい手順は Claude Code の settings.json で権限を設定する を参照してください。

再読み込みはできます。コマンドは /reload-plugins で、プラグイン・スキル・エージェント・フック・プラグインの MCP サーバー・LSP サーバーをまとめて読み直します。新しくプロジェクトを開き直す必要はありません。

それでもスラッシュコマンドが出てこない場合、公式ドキュメントに記載のある原因は次の 3 つです。

1. プロンプトキャッシュの都合で保留されている

/plugin のメニューを閉じると Claude Code が自動で /reload-plugins を実行しますが、プロンプトキャッシュが無効になる変更の場合は警告を出して保留します。この場合は強制的に適用します。

/reload-plugins --force

インストール時のサマリーが Run /reload-plugins to activate. と表示していた場合も同じです。

2. セッションに直接入力していない

/reload-plugins はデスクトップアプリや Agent SDK、-p の非対話セッションでも動きますが(v2.1.260 以降)、そのセッションに直接入力したときだけ実行されます。Remote Control や中継されたチャットメッセージのようにリモート経由で送った場合は、何も読み込まずに拒否されます。デスクトップアプリならプロンプト入力欄に自分で打ち込んでください。

3. キャッシュが壊れている

公式のトラブルシューティングは、プラグインのスキルが出てこないときにキャッシュの削除を案内しています。

rm -rf ~/.claude/plugins/cache

削除後に Claude Code を再起動し、プラグインを入れ直します。

なお、プラグインの MCP サーバーの接続・切断だけは、対話端末のないセッションでは /reload-plugins では反映されず、次回のセッションからになります。claude.ai アカウント側で有効にしたプラグインがターミナルのセッションに同期されるのは v2.1.273 以降です。

rootless podman は既定でユーザー名前空間を使うため、コンテナ内の UID がホストの UID に直接対応しません。その結果、バインドマウントしたファイルへの書き込みが拒否され、node-gyp のようにビルドディレクトリを作り直すツールが EACCES で失敗します。

Gemini CLI には、コンテナランタイムへ任意のフラグを渡す受け皿が用意されています。公式ドキュメントは「コンテナ型のサンドボックスでは、SANDBOX_FLAGS 環境変数で docker または podman コマンドにカスタムフラグを注入できる」と説明しています。複数指定は空白区切りです。

podman 側で UID を対応させるフラグは --userns=keep-id です。これを渡します。

export GEMINI_SANDBOX=podman
export SANDBOX_FLAGS="--userns=keep-id"
gemini --sandbox

SELinux が有効な環境(Fedora 系など)でマウントの権限エラーも出る場合は、公式ドキュメントが例示している --security-opt label=disable を併せて渡します。

export SANDBOX_FLAGS="--userns=keep-id --security-opt label=disable"

なお --userns=keep-id は podman 側のフラグで、Gemini CLI の公式ドキュメントが例として挙げているのは --security-opt label=disable です。--userns=keep-id 自体は公式ドキュメントには記載がありません。SANDBOX_FLAGS でランタイムのフラグを渡せる、という仕組みが公式に案内されている部分です。

GEMINI_SANDBOX に指定できる値は true、docker、podman、sandbox-exec、runsc、lxc です。--security-opt label=disable は SELinux のラベル付けを無効にするため、必要な環境だけで使ってください。

ありません。deny はどのスコープ(ユーザー / プロジェクト / ローカル)に書かれていても allow より優先されます。プロジェクトの .claude/settings.json に次を書いておけば、個人の settings.local.json で Read を広く許可していても .env は読まれません。

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

ただし deny は Claude Code のツール呼び出しに対する制御で、cat .env のようなシェルコマンド経由の読み取りは別ルールです。Bash(cat .env:*) のような前方一致は回避されやすいので、確実に守りたい値は .env をワークスペースの外に置くか、シークレットマネージャーから実行時に注入してください。

次の順で確認してください。

1. /hooks を実行し、登録した hook が一覧に出るか見る。出なければ JSON の構文(末尾カンマ、引用符)か、置き場所(.claude/settings.json か ~/.claude/settings.json)が原因です
2. matcher はツール名の正規表現です。ファイル編集に反応させるなら Edit|Write|MultiEdit、コマンドなら Bash です。イベント名(PreToolUse / PostToolUse)の綴りも確認します
3. スクリプトに実行権限があるか(chmod +x)、シェバン行があるか、jq が入っているかを確認します。bash .claude/hooks/format.sh のように bash 経由で呼べば実行権限は不要です
4. claude --debug で起動すると、hook の実行と終了コード、標準エラー出力が表示されます

設定を編集したあとはセッションを再起動すると確実に反映されます。

ほとんどの場合、サーバー自体の起動に失敗しています。Claude Code の外で同じコマンドを直接実行してエラーを見るのが最短です。

npx @playwright/mcp@latest

よくある原因は次の 3 つです。

• 初回の npx がタイムアウト: パッケージのダウンロードに時間がかかっています。一度手動で起動してキャッシュさせてから再接続してください
• 環境変数が渡っていない: --env KEY=value で渡した値、または .mcp.json の ${VAR} が、Claude Code を起動したシェルに存在するか echo $VAR で確認します
• Node.js のバージョン不足: サーバーの要求バージョン(多くは 18 以上)を満たしているか node -v で確認します

公式ドキュメントが注意している順序の問題もあります。--env の直後にサーバー名を置くと、CLI がサーバー名をもう 1 組の KEY=value として読んで拒否します。--env とサーバー名の間に --transport stdio のような別のオプションを 1 つ挟んでください。

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

-- より後ろはそのままサーバーに渡されます。これがないと、サーバー側の --port のようなフラグを Claude Code が自分のオプションとして解釈しようとします。

直ったら claude mcp list で状態を確認し、対話中は /mcp を再実行してください。

はい。workspace-write サンドボックスは既定でネットワークを遮断するため、パッケージのダウンロードが失敗します。承認ポリシーが on-failure なら「サンドボックス外で再実行してよいか」を聞かれるので許可すれば通ります。毎回聞かれたくない場合は ~/.codex/config.toml でネットワークだけ許可します。

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

ネットワークを許可すると外部へのデータ送信も可能になるので、信頼できるリポジトリでだけ有効にしてください。調査だけの作業は read-only のままで問題ありません。

個人の Google アカウントでの無料利用には、1 分あたりと 1 日あたりのリクエスト上限があります。1 回の指示でもファイル読み取りやコマンド実行のたびにモデルを呼ぶため、体感では「指示 1 回 = リクエスト数回」です。長いタスクを続けると午後には日次上限に達することがあります。

対処は 2 つです。

• リセットまで待つ(分単位・日単位で回復します)
• GEMINI_API_KEY を設定して有料枠に切り替える(その時点から従量課金)

export GEMINI_API_KEY="your-key"
gemini

上限の具体的な数値は改定されるので、公式ドキュメントで最新値を確認してください。業務のコードを扱う場合は、データ利用条件の違いからも API キーか Vertex AI を勧めます。

送信済みのデータを取り消す方法はないので、そのキーを失効させて再発行するのが唯一の確実な対処です。順番は次のとおりです。

1. 発行元のサービスでキーを失効(revoke)し、新しいキーを発行する
2. 失効までの間に不正利用がなかったか、サービス側の利用ログを確認する
3. 読まれた経路を特定し、再発防止の設定を入れる(Claude Code なら Read(./.env) の deny、Codex はファイルをワークスペース外へ、Gemini CLI は .geminiignore)
4. Git 履歴にも含まれていた場合は、失効に加えて履歴からの除去を検討する

「自分しか見ていないから」と失効を省略しないでください。データの保持期間中の扱いはプランと契約に依存します。