Claude Code サンドボックス チュートリアル：/sandbox の設定ガイド
/sandbox を実行し、auto-allow を選び、すべての bash コマンドを OS 強制の境界内に収めます——噂話ではなく、実際の settings キーで。公式ドキュメント照合済みの 12 ステップ。
要点まとめ
- /sandbox コマンドで Mode・Overrides・Config の 3 タブからなるパネルが開きます。auto-allow モードならサンドボックス化された bash コマンドが許可プロンプトなしで走り、regular permissions ではすべてのプロンプトが残ります。
- 境界を強制するのはプロンプトではなくカーネルです。macOS は Seatbelt、Linux と WSL2 は bubblewrap。ネイティブ Windows と WSL1 は非対応。
- サンドボックス化されたコマンドが書き込めるのは、作業ディレクトリ・ユーザーごとの一時ディレクトリ・--add-dir で追加したパスだけ。ネットワーク通信はドメインを何も事前許可しないプロキシ経由です。
- 読み取りはデフォルトではブロックされません。sandbox.credentials ルールを追加するまで ~/.ssh や ~/.aws は読め放題です。VS Code の Sandbox ダイアログは v2.1.280 で登場しました。
Claude Code Sandbox Explained
動画:The Art of Vibe Coding4:29
How auto mode works with Claude Code
動画:Claude5:42
Configure the sandboxed Bash tool (official docs)
ドキュメント:code.claude.com
1 本目の動画はモーショングラフィックス解説で、本ページのフレームは様式化されたイラストでありスクリーンショットではありません。一部の主張は以下のステップで訂正されています（認証情報はデフォルトで読める。紹介される settings キーは実物と一致しない）。2 本目は Anthropic の公式録画で、実際のターミナルと設定 UI のみを使用しています。
事実確認は code.claude.com/docs/en/sandboxing と anthropics/claude-code の CHANGELOG（v2.1.280–2.1.283）による。静止画は解説のため録画のごく一部を引用しています。
12 ステップで設定する Claude Code サンドボックス
境界を理解する
- 1
承認疲れという問題を認識する
サンドボックスなしでは、提案されたコマンドごとに y/n で止まります。npm install、git status、そして次のコマンド。Anthropic の測定では Claude Code の権限リクエストの 97% が承認されており、だからこそサンドボックスはチェックを個々のコマンドから、一度設定すれば済む境界へ移動したのです。
サンドボックスが置き換えるコマンドごとの y/n ループの再現 — Enter を 47 回押す頃には読むのをやめる。0:22 を視聴 - 2
対応プラットフォームで Claude Code を起動
プロジェクトでセッションを開きます。macOS ではサンドボックス化が内蔵され、Seatbelt は OS に同梱、インストールは不要です。Linux と WSL2 では先にパッケージマネージャーで bubblewrap と socat を入れてください。ネイティブ Windows と WSL1 は非対応。Windows ユーザーは WSL2 ディストロの中で Claude Code を動かします。
~/Documents/code/acme でのセッション — この作業ディレクトリがサンドボックスの書き込み可能領域になる。0:35 を視聴 - 3
/sandbox を実行しパネルを読む
セッションで /sandbox と入力します。パネルには 3 つのタブがあります。Mode（サンドボックス化コマンドの承認方法）、Overrides（失敗したコマンドがサンドボックス外で再試行できるか — allowUnsandboxedCommands 設定）、Config（解決済みのサンドボックス設定一式）。Linux には不足を一覧する Dependencies タブ（bubblewrap、socat、オプションの seccomp フィルタなど）が加わります。v2.1.281 からは矢印キーでタブを切り替えられ、VS Code にも v2.1.280 で同じ設定の Sandbox ダイアログが付きました。
有効にする
- 4
auto-allow か regular permissions かを選ぶ
Mode タブで、auto-allow はサンドボックス化コマンドをプロンプトなしで実行し、regular permissions はサンドボックス化コマンドでもプロンプトを残します。選択はプロジェクトの .claude/settings.local.json に保存され、Claude Code が gitignore してくれます。全プロジェクトをカバーするには ~/.claude/settings.json に "sandbox": undefined を。単一セッションなら --settings で渡します。
2 ステップのクイックスタート：/sandbox でモードを選び、settings.json に恒久設定を預ける。4:00 を視聴 - 5
auto-allow でも許可を求められるものを知る
auto-allow はミュートボタンではありません。明示的な deny ルールは常に勝ち、重要なパスを狙う rm や rmdir は依然プロンプトを出し、Bash(git push *) のような内容スコープの ask ルールも確認を強制します。サンドボックスで実行できないコマンドは「Bash command (unsandboxed)」というタイトルのプロンプト付きで通常フローにフォールバックします。auto-allow は権限モードとも独立して働き、Manual モードでもサンドボックス化 bash はプロンプトなしで走ります。
shift+tab は権限モードを循環 — サンドボックスの auto-allow とは別の操作。0:28 を視聴 - 6
OS がどう境界を引くかを見る
制限はカーネル強制であり、丁寧なお願いではありません。macOS は Seatbelt、Linux と WSL2 は bubblewrap。~/.ssh を読もうとしたり外部に通信しようとしたりするプロンプトインジェクション済みコマンドも同じ壁にぶつかります。ルールは実行中のプロセスとその子プロセスすべてに結びつくため、モデルは口先でカーネルを通過できません。
アプリ層の権限チェックは迂回できても、カーネル層は迂回できない。2:07 を視聴
ファイルシステム・認証情報・ネットワーク
- 7
ファイルシステムのデフォルトと読み取りの注意点
サンドボックス化コマンドが書き込めるのは、作業ディレクトリとそのサブディレクトリ、ユーザーごとの一時ディレクトリ、--add-dir や permissions.additionalDirectories で追加したフォルダです。読み取りはデフォルトで開放されています。ディスク全体 — ~/.aws/credentials や ~/.ssh を含む — が、自分でブロックするまで読めます。解説動画は認証情報が「見えなくなる」と言いがちですが、ドキュメントは率直に、sandbox.credentials か denyRead ルールで守るのはあなたの仕事だと述べています。
書き込みはサンドボックスの壁で止まる。読み取りは次のステップで閉じるまで開いたまま。1:30 を視聴 - 8
自律実行の前に認証情報を守る
sandbox.credentials ブロックを追加します。~/.ssh や ~/.aws/credentials のようなファイルを "mode": "deny" で列挙し、GITHUB_TOKEN のような秘密の環境変数も指定すれば、サンドボックス化されたすべてのコマンド内で unset されます。mask モードはさらに進んで、コマンドにはセンチネル値が見え、サンドボックスのプロキシは許可したホストでのみ実値に差し替えます。ファイルツールには permissions.deny の Read ルールが上から掛かります。
curl と .env 読み取りの deny ルール — 同じ settings ファイルが sandbox ブロックも運ぶ。4:35 を視聴 - 9
スタックに必要なネットワークドメインを許可
サンドボックス化されたトラフィックはすべてプロキシを通り、事前許可ドメインはゼロです。コマンドが初めてホストを必要とすると Claude Code がプロンプトを出し、「Yes, and don't ask again」と答えると WebFetch(domain:...) の allow ルールを今後のセッションのために保存します。sandbox.network.allowedDomains でレジストリを事前許可し、deniedDomains で特定ホストをブロックし、strictAllowlist を設定すればリストがプロンプト候補ではなく上限になります。
レジストリ取得はプロキシを通過。evil.com に通信する postinstall スクリプトは通らない。1:51 を視聴 - 10
設定のスコープ：プロジェクト・ユーザー・管理
.claude/settings.json のプロジェクト設定は書き込み可能パスとドメインを追加できますが、ファイルシステム分離の無効化や Apple Events の有効化はできません。それらのキーはユーザー設定・管理設定・--settings フラグからのみ尊重されるため、チェックアウトしたリポジトリがサンドボックスを弱体化することはありません。チームは管理設定で enabled、failIfUnavailable、allowUnsandboxedCommands を true/false/false にしてサンドボックスを強制します。
管理設定ファイルは組織の信頼済み環境を記述する。管理者が置き、開発者は継承する。4:10 を視聴
検証と修正
- 11
実際のタスクで検証する
ビルドやテスト実行を頼んでみます。サンドボックス化コマンドはプロンプトなしで実行され、何かがブロックされたときは違反がコマンド結果にパスやホスト名を明示するので Claude が適応できます。/sandbox の Config タブを開けば、どの設定も上書きできない保護パスを含む解決済みルールがすべて読めます。一回限りの厳格トライアルには claude --settings 'undefined}' で起動します。
タスクを 1 つ入力するだけ、コマンドごとのプロンプトなし — 境界はあなたがいなくても保たれる。0:32 を視聴 - 12
よくある失敗のトラブルシューティング
jest が固まる — watchman が非互換なので jest --no-watchman で。docker が失敗 — サンドボックス化は不可能なので excludedCommands に "docker *" を追加。macOS で open や osascript がエラー -600 — allowAppleEvents が true でない限り Apple Events はブロックされます。git merge や checkout が "unable to unlink old" で失敗 — 保護パスか denyWrite ルールが邪魔なので、サンドボックス外再試行を承認するか自分でコマンドを実行。コンテナ内で bwrap が Operation not permitted — enableWeakerNestedSandbox を設定。クリップボードへのパイプが空 — pbcopy の代わりに /copy を。
知っておくべきサンドボックス設定
/sandbox パネルは基本を書いてくれますが、本当のレバーは settings.json にあります。以下は公式サンドボックスリファレンスが記載するキーです。すべて "sandbox" ブロックの下に置かれます（最後の 1 つだけ "permissions" の下）。
- 1sandbox.enabled — 自分で裏返すまでオフ。~/.claude/settings.json で true にすれば全プロジェクトが対象。/sandbox パネルはプロジェクトローカルのコピーを .claude/settings.local.json に書きます。
- 2sandbox.autoAllowBashIfSandboxed — auto-allow のスイッチでデフォルトは true。false にするとサンドボックス内で走るコマンドでも権限プロンプトが残ります。
- 3sandbox.allowUnsandboxedCommands と sandbox.failIfUnavailable — 1 つ目を false にすると dangerouslyDisableSandbox 再試行が死に（Overrides タブでは Strict sandbox mode と表示）、2 つ目を true にすると依存の欠落が警告ではなくハードな起動失敗になります。
- 4sandbox.filesystem — ツールがプロジェクト外で必要とするパスの allowWrite（"~/.kube"、"/tmp/build"）、機密の場所の denyRead と allowRead、そしてネットワーク分離を保ったままファイルシステム層を外す disabled（v2.1.216+）。
- 5sandbox.network — allowedDomains と deniedDomains、列挙外すべてを禁じる strictAllowlist（v2.1.219+）、dev サーバーにポートを bind させる allowLocalBinding、プロキシでの認証情報マスキングの tlsTerminate。
- 6sandbox.credentials — deny か mask モードのファイルと envVars エントリ。mask は tlsTerminate を要求し、ユーザー・管理・--settings ソースからのみ尊重されます。permissions.blockReadsOutsideWorkingDirectories と組み合わせれば、作業ディレクトリ外のすべての読み取りを断てます。
Seatbelt vs bubblewrap：プラットフォームの違い
macOS は Seatbelt を使います。OS 内蔵なのでインストールは不要です。荒い部分は具体的で、gh・gcloud・terraform のような Go 製 CLI は Seatbelt 下で TLS 検証に失敗することがあるので excludedCommands に並べてください。open・osascript・ブラウザ認証フローは allowAppleEvents を設定するまでエラー -600 で失敗し、これは分離を弱め、プロジェクト設定では無視されます。
Linux と WSL2 は bubblewrap と socat を使い、パッケージマネージャーで入れます。オプションの seccomp フィルタ（npm install -g @anthropic-ai/sandbox-runtime）は Unix ドメインソケットのブロックを追加し、WSL2 が Windows バイナリを締め出す仕組みでもあります。Ubuntu 24.04 以降は bubblewrap がユーザーネームスペースを作れない AppArmor ポリシーを同梱するので、ドキュメントの bwrap プロファイルを追加し AppArmor をリロードしてください。非特権コンテナ内では enableWeakerNestedSandbox を設定すれば bubblewrap が既存の /proc を bind マウントします。
WSL1 はまったく非対応です。bubblewrap は WSL2 だけが持つカーネル機能を必要とします。パフォーマンスのオーバーヘッドは最小限ですが、一部のファイルシステム操作はわずかに遅くなります。サブエージェントは親セッションと同じプロセスで動き、そのサンドボックス設定を引き継ぐため、エージェント内のバックグラウンド bash もサンドボックス化されます。
サンドボックス扱いはリリース間でまだ動いています。v2.1.280 は VS Code の Sandbox ダイアログ、v2.1.281 は /sandbox のタブ操作と dev サーバー向け allowLocalBinding ヒント、v2.1.282–2.1.283 は excludedCommands のマッチング、TMPDIR への書き込み、管理設定のパースを修正しました。エッジケースの挙動に頼る前に CHANGELOG に目を通してください。