Claude Code の Bash サンドボックスは、Claude が実行するシェルコマンドと、そこから起動されるプロセスの周りに OS レベルの境界を置く機能です。どのファイルに書き込めるか、どのドメインと通信できるかを利用者が決め、その範囲の外にはコマンドが届かなくなります。この記事では、公式ドキュメント「Configure the sandboxed Bash tool」をもとに、サンドボックスが制限するもの、有効化と動作確認、2つのモード、設定例、組織での強制とよくあるつまずきを整理します。コンテナや VM など実行環境そのものの選び方はサンドボックス環境の選び方の記事を参照してください。
サンドボックスが制限するもの
サンドボックスは Bash、PowerShell、Monitor のコマンドに適用されます。対応プラットフォームは macOS、Linux、WSL2 で、既定ではオフです。ネイティブの Windows ではコマンドはサンドボックスなしで動くため、Windows で使う場合は WSL2 のディストリビューション内で Claude Code を動かします。強制の仕組みは macOS が Seatbelt、Linux と WSL2 が bubblewrap です。
| 対象 | 既定の扱い | 変更する設定 |
|---|---|---|
| 書き込み | 作業ディレクトリ、ユーザーごとの一時ディレクトリ、--add-dir・/add-dir・permissions.additionalDirectories で追加したディレクトリ。保護対象のパスは書き込み不可のまま | filesystem.allowWrite、filesystem.denyWrite |
| 読み取り | マシンのほとんど(~/.ssh や ~/.aws/credentials も含む) | filesystem.denyRead、credentials |
| ネットワーク | 直接の経路はなく、ローカルのプロキシが接続先を allowedDomains と照合する。allowedDomains は最初は空 | network.allowedDomains、network.deniedDomains |
| 環境変数 | Claude Code から引き継ぐ | credentials、CLAUDE_CODE_SUBPROCESS_ENV_SCRUB |
既定では読み取りはほぼ制限されない点に注意してください。認証情報のファイルを守りたい場合は、後述の denyRead や credentials を明示的に設定します。
次のものはサンドボックスの外で動きます。
- Claude のファイルツール(Read、Edit、Write)、WebFetch、WebSearch、MCP サーバー、フック、LSP サーバー、ステータスラインのコマンド、
apiKeyHelper、mod - 利用者が
!のシェルモードで打ったコマンド(ほとんどのセッション) excludedCommandsに一致するコマンド- Claude が要求したサンドボックスなしの再試行
なお、権限ルールは「ツールを実行してよいか」を決め、サンドボックスは「実行中のコマンドが何に届くか」を制限します。/sandbox は権限モードではなく、両者は併用されます。
有効化と動作確認
有効にする方法は2つあります。セッション内で /sandbox を実行するか、~/.claude/settings.json で sandbox.enabled を true にします。1回の起動だけ試すなら --settings でも渡せます。
claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'
/sandbox のパネルには次のタブがあります。
- Mode: auto-allow と通常の権限確認のどちらで動かすかを選ぶ
- Overrides:
allowUnsandboxedCommandsを切り替える - Config: 解決後の設定を表示する
- Dependencies: Linux で必要なものが足りないときに表示される
パネルでモードを選ぶと、現在のプロジェクトの .claude/settings.local.json に保存されます。このファイルは Claude Code がグローバルの gitignore に追加します。
Linux と WSL2 の準備: ファイルシステムの隔離に bubblewrap、通信の中継に socat が必要です。インストール後は Claude Code を再起動します。ripgrep はネイティブバイナリに同梱されています。
# Ubuntu / Debian
sudo apt-get install bubblewrap socat
# Fedora
sudo dnf install bubblewrap socat
Unix ドメインソケットの遮断を追加する seccomp フィルタは任意で、npm install -g @anthropic-ai/sandbox-runtime で入ります。Sandboxing requires WSL2 と出る場合は WSL1 なので、WSL2 に上げます。
起動できないときの既定: プラットフォームや依存関係のチェックに失敗すると、既定ではコマンドはサンドボックスなしで実行されます。その場合に起動をやめさせたいときは sandbox.failIfUnavailable を true にします。
動作確認: ! で打つとサンドボックスの外で動くことが多いため、Claude に次のコマンドを実行してもらいます。
touch ~/sandbox-probe: macOS ではOperation not permitted、Linux と WSL2 ではRead-only file systemで失敗すれば有効curl --noproxy '*' https://example.com:Could not resolve hostで失敗すれば通信の隔離が有効
2つのモードと非サンドボックス再試行
どちらのモードでも、ファイルシステムとネットワークの制限は同じです。違うのは確認の出し方だけです。
| モード | 動き |
|---|---|
| auto-allow | サンドボックス内のコマンドは確認なしで実行される。サンドボックスの外に出るコマンド(excludedCommands や再試行)は通常の権限フローを通る |
| 通常の権限確認 | サンドボックス内であっても、すべての Bash コマンドが権限フローを通る |
auto-allow でも、次はそのまま効きます。
Bashの deny ルール- 重要なパスに対する
rm・rmdirの確認 Bash(git push *)のような内容を限定した ask ルール
一方、対象を限定しない Bash の ask ルールは、プランモードを除きサンドボックス内のコマンドでは飛ばされます。Monitor のコマンドは自動承認されません。
サンドボックスなしの再試行: コマンドがサンドボックス内で失敗すると、Claude は dangerouslyDisableSandbox を付けて再試行することがあります。承認の扱いは権限モードで変わります。
| 権限モード | 再試行の扱い |
|---|---|
bypassPermissions | 確認なし |
手動、acceptEdits | 「Bash command (unsandboxed)」という確認が出る |
| auto モード | 分類器が審査する |
dontAsk | 拒否 |
再試行そのものを禁止するには allowUnsandboxedCommands を false にします。ユーザー設定、--settings、マネージド設定で false にした場合、プロジェクト側で true にしても false が保たれます。
{
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"allowUnsandboxedCommands": false
}
}
書き込み先・読み取り・通信の設定
書き込み先を足す: 作業ディレクトリ以外にも書き込ませたい場合は filesystem.allowWrite に並べます。サンドボックスのパスは通常の書き方(/tmp/build は絶対パス、~/.kube はホーム基準)で、絶対パスを //path と書く Read・Edit の権限ルールとは書き方が違います。
{
"sandbox": {
"enabled": true,
"filesystem": {
"allowWrite": ["~/.kube", "/tmp/build"]
}
}
}
ホームの読み取りを塞ぐ: 次の設定はホームディレクトリの読み取りを禁止し、プロジェクトだけ許可します。. は設定ファイルの場所を基準に解決されるため、プロジェクトの設定に置きます。読み取りルールが重なった場合は、より狭いルールが優先されます。
{
"sandbox": {
"enabled": true,
"filesystem": {
"denyRead": ["~/"],
"allowRead": ["."]
}
}
}
パスを書かずに済ませたい場合は、permissions.blockReadsOutsideWorkingDirectories でホームなどのユーザーファイルのディレクトリに対するサンドボックス内の読み取りを拒否できます。
認証情報を隠す: credentials では、ファイルと環境変数ごとに扱いを決めます。mode: "deny" はファイルの読み取りを塞ぎ、環境変数を未設定にします。
{
"sandbox": {
"enabled": true,
"credentials": {
"files": [
{ "path": "~/.aws/credentials", "mode": "deny" },
{ "path": "~/.ssh", "mode": "deny" }
],
"envVars": [
{ "name": "GITHUB_TOKEN", "mode": "deny" },
{ "name": "NPM_TOKEN", "mode": "deny" }
]
}
}
}
mode: "mask" にするとコマンドには代わりの値が渡り、許可されたホストへのリクエストでだけプロキシが本物の値に差し替えます。mask には network.tlsTerminate が必要で、mask と TLS の設定はユーザー設定、マネージド設定、--settings からしか有効になりません(リポジトリ内のファイルでは無視されます)。
通信先を許可する: network.allowedDomains に許可するホストを並べます。ポートを書かなければ全ポートが対象で、*.npmjs.org のようなワイルドカードも使えます。deniedDomains に書いたホストは常に遮断されます。curl、npm、HTTPS の git のようにプロキシ用の環境変数に従うツールは、ホストを許可すれば動きます。素の ssh やほとんどのデータベースドライバのようにプロキシ変数を無視するツールは失敗し、UDP・QUIC・ICMP も通りません。
許可リストにないホストへの接続は、bypassPermissions では確認なしで許可、手動と acceptEdits では確認、auto モードではコマンドがホストを明示し分類器が承認した場合を除き拒否、dontAsk では拒否されます。確認を出さずに拒否させたい場合は strictAllowlist を使います。
特定のコマンドを外す: excludedCommands に一致したコマンドは、ファイルシステムとプロキシの制限なしで実行されます。パターンは Bash(...) ルールと同じ書き方で、連結したコマンドはすべてが一致する必要があります。公式ドキュメントは、allowWrite や allowedDomains で足りるならそちらを使い、これは控えめに使うよう勧めています。
{
"sandbox": {
"enabled": true,
"excludedCommands": ["docker compose *"]
}
}
組織での強制とよくあるつまずき
保護されるパス: 書き込み可能な場所の中でも、次は常に書き込み不可です。リポジトリ内の設定を書き換えて次回以降の動作を変える、といった経路を塞ぐためのものです。
.claudeの設定、.claude/skills、.claude/agents、.claude/commands、.claude/hooks、.mcp.json- 作業ディレクトリ内の
.bashrc、.zshrc、.gitconfig、.vscode、.idea、.git/hooks、.git/config ~/.claudeの大部分、~/.claude.json、.credentials.json
組織で強制する: 前の節の enabled・failIfUnavailable・allowUnsandboxedCommands: false の組み合わせをマネージド設定に置くと、リポジトリの設定から excludedCommands、allowWrite、ソケットの項目を追加できなくなります。承認済みの項目はマネージド設定に書きます。通信先をマネージド設定の値だけに固定するには allowManagedDomainsOnly、allowRead を固定するには allowManagedReadPathsOnly を使います。ネイティブ Windows の端末は failIfUnavailable で起動に失敗するため、OS ごとに設定を配るか WSL2 に移行させます。
よくあるつまずき: 公式ドキュメントのトラブルシューティングから、主なものを抜き出します。
| 症状 | 対処 |
|---|---|
jest が止まる | jest --no-watchman で実行する |
docker が失敗する | excludedCommands に入れる |
| localhost のサーバーに接続できない(macOS) | allowLocalBinding を使う |
macOS で SSH 経由の git が失敗する | HTTPS のリモートに切り替える |
クリップボード(pbcopy、xclip、wl-copy)が使えない | /copy を使う |
| コンテナ内で bubblewrap が失敗する | enableWeakerNestedSandbox(隔離が弱まる点に注意) |
Ubuntu で bwrap: setting up uid map: Permission denied | /usr/bin/bwrap 用の AppArmor プロファイルを用意する |
本記事は Claude Code 公式ドキュメント「Configure the sandboxed Bash tool」を元に、Anthropic が公開する sandbox-runtime の README で bubblewrap・Seatbelt による強制と allowedDomains・deniedDomains の考え方を照合した非公式の日本語解説です(確認日 2026-11-16)。設定項目は更新される可能性があるため、利用前に公式ドキュメントをご確認ください。