Claude Codeのサンドボックス化Bashツール──ファイルと通信をOSレベルで閉じ込める

Claude CodeのBashツールは、許可を求める代わりにOSの機能で行動範囲そのものを閉じ込めることができる。/sandbox を有効にすると、macOSは組み込みのSeatbelt、Linux/WSL2はbubblewrapという、それぞれのOSが元から持つサンドボックス機構を使って、Bashコマンドとその子プロセスが書き込めるパス・接続できるネットワークドメインを制限する。これは「Claudeが賢く判断して確認プロンプトを出す」仕組みではなく、「OSが物理的に塞ぐ」仕組みだ。以前確認したallow/ask/denyの権限ルールが「実行前にコマンド文字列を見て判定する」レイヤーなのに対し、サンドボックスは「実行された後に、プロセスが実際に何に触れられるか」を制限するレイヤーになる。

既定では無効になっている機能で、有効化には /sandbox コマンドか settings.json への明示的な設定が要る。2026年8月27日時点でCLI本体の最新版は2.1.247（8月26日付）。以下で参照する設定項目はv2.1.187〜v2.1.229の間に追加されたものだが、いずれも2.1.247には含まれている。

3行まとめ

1. 既定の書き込み範囲は作業ディレクトリとセッション一時ディレクトリのみ。だが読み取りは既定でPC全体が対象で、~/.aws/credentials や ~/.ssh/ も普通に読める。読み取りを絞るには sandbox.credentials を自分で書く必要がある（公式が明記）
2. サンドボックス内で失敗したコマンドは、dangerouslyDisableSandbox パラメータでサンドボックス外に自動的に抜け出して再実行されうる。この抜け道自体は allowUnsandboxedCommands: false で無効化できる
3. 日本語版公式ドキュメント（2026-08-27時点）は、英語版にある filesystem.disabled・Protected paths の全容・strictAllowlist・AWS認証情報の再署名・JWTマスキングなどの記載を欠いている。日本語だけを読むと機能の全体像を取りこぼす

有効化の手順と、有効にした場所がどこに書かれるか

/sandbox を実行するとMode／Overrides／Configの3タブ（Linuxで依存パッケージが足りない場合はDependenciesタブのみ）が開く。macOSは追加インストール不要（Seatbeltが組み込み）。Linux/WSL2は次の2パッケージが要る。

"On Linux and WSL2, the sandbox relies on two packages:"（公式ドキュメント原文。続けて bubblewrap＝filesystem isolationを実施するツール、socat＝ネットワークトラフィックをサンドボックスプロキシ経由に中継するリレー、と箇条書きが続く）

Ubuntu/Debianなら sudo apt-get install bubblewrap socat。Ubuntu 24.04以降はAppArmorのデフォルトポリシーがbubblewrapのユーザー名前空間作成を妨げるため、sysctl kernel.apparmor_restrict_unprivileged_userns の戻り値が1ならAppArmorプロファイルの追加が要る、と手順まで具体的に書かれている。

パネルでモードを選ぶと、その設定はプロジェクトローカルの .claude/settings.local.json（gitにコミットされない）に書き込まれる。全プロジェクトで有効にするには ~/.claude/settings.json に sandbox.enabled: true を書く必要がある——ここは/sandboxで選んだだけでは他プロジェクトに反映されない、という順序の落とし穴になる。

依存関係が足りない、あるいはプラットフォーム非対応でサンドボックスが起動できない場合、既定は「警告を出してサンドボックス化せずに実行」というフェイルオープンだ。これをハード失敗にするには sandbox.failIfUnavailable: true が要る。

既定でどこまで書けて、どこまで読めるか

書き込みは作業ディレクトリとサブディレクトリ、それに $TMPDIR が指すセッション一時ディレクトリのみ。これらを跨いで一時ファイルを渡したい場合、サンドボックス化コマンドと非サンドボックス化コマンドは別の $TMPDIR を解決するため（前者はセッション用ディレクトリ、後者はシェル本来の$TMPDIRを継承）、作業ディレクトリ配下に置く必要がある。

読み取りは逆に緩い。

"Default read behavior: read access to the entire computer, except certain denied directories. Note that this default still allows reading credential files such as ~/.aws/credentials and ~/.ssh/."（公式ドキュメント原文）

つまり「サンドボックス化した」だけでは認証情報ファイルの読み取りは止まらない。ブロックするには sandbox.credentials.files に { "path": "~/.aws/credentials", "mode": "deny" } のようなエントリを自分で足す必要があり、組み込みの拒否リストは存在しない（"There is no built-in credential deny list, so only the files and variables you list are restricted."）。

書き込み側にはさらに「例外を許さない」層がある。作業ディレクトリの中であっても、.claude/settings*・.claude/hooks・.mcp.json・~/.claude 配下の大半・.credentials.json などはサンドボックスが常に書き込み拒否する。公式は「allowWrite エントリや Edit allowルールでこの保護は解除できない」と明記しており、外す唯一の方法はファイルシステム分離そのものを丸ごとオフにする filesystem.disabled（後述）だけだ。理由は単純で、これらを書き換えられるとコマンドが自分自身に権限を付与したり、サンドボックス外で動くhookを仕込んだりできてしまうため。

ネットワークは事前許可ドメインがゼロからスタートする。新しいドメインへの接続が発生した時点でプロンプト（自動モードでは分類器が判定）が出て、「Yes」ならセッション中だけ、「Yes, and don't ask again」なら WebFetch(domain:...) の許可ルールとしてローカル設定に永続化される。

自動許可モードでも素通りしない4つのケース

Mode タブで自動許可を選ぶと、サンドボックス化できたコマンドはプロンプトなしで実行される。ただし公式が明記する例外がある。

• 明示的なdenyルールは常に効く
• / やホームディレクトリなど重要パスを対象にした rm/rmdir は通常の許可フローに戻る
• Bash(git push *) のような内容限定のaskルールは、サンドボックス化されていてもプロンプトを強制する
• 単純な Bash askルールや Bash(*) は、サンドボックス化されて実行されるコマンドではスキップされる。ただしプランモードでは違う——プランモード中は読み取り専用のコマンドも含めてプロンプトが出る（v2.1.212より前はプランモードでもスキップされていた、というバージョン差がある）

自動許可モード（sandbox mode）と、権限プロンプト全般を分類器で自動処理する自動モード（permission mode）は別物で、名前が紛らわしいが独立して組み合わせられる、と公式が注意書きしている。ファイル編集ツールなら手動確認モードでも止まるはずの変更が、サンドボックス境界内へのBash経由の書き込みだと自動許可モードでは無警告で通る、という非対称も明記されている。

失敗したらどうなるか——dangerouslyDisableSandbox という抜け道

サンドボックス内で権限不足によりコマンドが失敗すると、失敗理由（どのパス・どのホストが拒否されたか）がコマンド出力に追記される。そのうえでClaude Codeには「タスクを失敗させる代わりに、dangerouslyDisableSandbox パラメータでサンドボックス外に再試行する」という組み込みの抜け道がある。再試行はサンドボックス外で走るため通常の許可フローに戻り、手動確認モードならプロンプトが出るが、自動モードでは分類器が判定するだけでプロンプトは出ない。毎回プロンプトを出したければ Bash(dangerouslyDisableSandbox:true) のaskルールを自分で足す必要がある。

この抜け道自体を封じるのが allowUnsandboxedCommands: false。設定すると /sandbox のOverridesタブに「Strict sandbox mode」と表示され、dangerouslyDisableSandbox は完全に無視される。組織で強制する際に使う設定として後述する。

トラブルシューティング項目として公式が挙げている具体例:

• jest がハングする→watchman がサンドボックスと非互換。jest --no-watchman で回避
• docker コマンドは非互換。excludedCommands に docker * を追加してサンドボックス外で実行
• macOSでSeatbelt配下だと gh/gcloud/terraform などGo製CLIがTLS検証に失敗することがある
• git merge/git checkout が unable to unlink old で失敗する場合、保護パス配下のファイルを置き換えようとしている。Linux/WSL2では末尾が Read-only file system になる
• --dangerously-skip-permissions はLinux/macOSでrootまたはsudo実行時にブロックされる（root権限＋無確認の組み合わせを避けるため）。認識されたサンドボックス内ではこのチェック自体が自動的にスキップされる

認証情報を守る2段階——denyとmask

sandbox.credentials（v2.1.187以降）でファイルパスや環境変数ごとに保護を宣言できる。mode: "deny" はファイル読み取りを拒否し環境変数を実行前にunsetする、単純だが確実な方法。一方 mode: "mask"（環境変数はv2.1.199以降、ファイルはv2.1.221以降）は、コマンドにはセッションごとのダミー値（センチネル）だけを見せ、許可済みホストへの通信時にサンドボックスプロキシが本物の値に差し替える——gh や npm のように認証情報そのものを必要とするツールを壊さずに済む方式だ。ただし mask を機能させるには実験的機能の network.tlsTerminate でプロキシ自身にTLSを終端させる必要があり、これを設定し忘れると「コマンドはダミー値しか見ないが、ダミー値がそのままサーバーに届いて認証が失敗する」という安全な失敗になる、と明記されている。AWSのSigV4署名再計算（credentials.awsPairs）やJWTのクレーム単位マスキング（decode: "jwt"）はv2.1.224以降の追加機能。

実務上の注意点は、mask エントリと network.tlsTerminate はリポジトリの .claude/settings.json や .claude/settings.local.json からは無視されること。ユーザー設定・管理設定・CLIの --settings フラグからしか効かない。つまりチームでgit経由でこの設定を共有する運用は成立しない。

組織で強制する側の落とし穴

管理設定（managed settings）で sandbox.enabled / failIfUnavailable のようなbool値キーを配ると、開発者側のローカル設定は無視され管理値が勝つ。しかし excludedCommands や filesystem.allowRead のような配列キーは全スコープがマージされるため、開発者はエントリを追加して制限を広げられてしまう。読み取りパスを管理設定だけに固定するには allowManagedReadPathsOnly: true、ネットワークドメインを固定するには allowManagedDomainsOnly が要る。excludedCommands には管理専用ロックの仕組みがなく、公式も「開発者は常にここへ追加してサンドボックス外実行コマンドを増やせる。管理リストは狭く保つこと」と述べている。サンドボックスはネイティブWindowsでは動かないため、Windows端末を含む場合はmacOS/Linuxにスコープを絞るかWSL2・コンテナ利用を求める必要がある。

ファイルシステム分離だけを丸ごとオフにする sandbox.filesystem.disabled（v2.1.216以降、ネットワーク分離は維持したまま）は、プロジェクト設定からは設定不可（ユーザー・管理・--settingsのみ）で、管理設定が sandbox.filesystem や credentials.files の deny エントリを1つでも配布している場合は管理設定でしか変更できないよう固定される。公式は「オフにするとサンドボックス化コマンドがシェル起動ファイルや $PATH 上の実行ファイル、~/.claude/settings.json 自体を書き換えて次回実行時に自分の権限を広げられる」と警告している。

公式ドキュメントで確認できなかったこと

• サンドボックス化によるパフォーマンスへの影響は「minimal, but some filesystem operations may be slightly slower」としか書かれておらず、具体的な数値（レイテンシ増加率など）は見つけられなかった。
• 自動モードの「分類器」がコマンドの安全性をどう判定しているか（ルールベースかモデル判定か、判定基準の詳細)は、このサンドボックスのページには記載がなく、確認できなかった。
• Docker DesktopやWindows Sandbox等、サードパーティの仮想化製品との組み合わせ時の挙動は、公式ドキュメントに具体的な記述を見つけられなかった（docker コマンド自体がサンドボックスと非互換、という記述はある）。
• 日本語版ドキュメントの機能面の遅れは推測ではなく確認済みの事実として書く。2026年8月27日時点で https://code.claude.com/docs/ja/settings-reference.md は404を返す（英語版 /docs/en/settings-reference に相当するページが日本語版には独立して存在しない）。また https://code.claude.com/docs/ja/sandboxing.md の本文には、英語版にある「Disable filesystem isolation」節、「Protected paths」の全4分類、network.strictAllowlist、credentials.files の mask モード、AWS認証情報の自動連結・再署名（awsPairs/sigv4）、JWTの decode、IPv6アドレスの角括弧表記ルールの記載が見当たらなかった。日本語版だけを読んで設定した場合、これらの機能自体が存在しないと誤解する可能性がある。

---

出典

• Configure the sandboxed Bash tool（英語版）
• サンドボックス化された Bash ツールを設定する（日本語版）
• Settings reference（英語版）
• Claude Code の設定（日本語版）
• Claude Code changelog

関連: Claude Codeの確認プロンプトを減らす設定──allow / ask / deny をどこで線引きするか、AIエージェントが情報を漏らす3条件──リーサルトライフェクタとは、Claude Codeとは