Claude Code の Bash サンドボックス設定:/sandbox の使い方

Claude Code エンジニアリング 7分で読めます

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 を明示的に設定します。

次のものはサンドボックスの外で動きます。

なお、権限ルールは「ツールを実行してよいか」を決め、サンドボックスは「実行中のコマンドが何に届くか」を制限します。/sandbox は権限モードではなく、両者は併用されます。

有効化と動作確認

有効にする方法は2つあります。セッション内で /sandbox を実行するか、~/.claude/settings.json で sandbox.enabled を true にします。1回の起動だけ試すなら --settings でも渡せます。

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

/sandbox のパネルには次のタブがあります。

パネルでモードを選ぶと、現在のプロジェクトの .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 に次のコマンドを実行してもらいます。

2つのモードと非サンドボックス再試行

どちらのモードでも、ファイルシステムとネットワークの制限は同じです。違うのは確認の出し方だけです。

モード動き
auto-allowサンドボックス内のコマンドは確認なしで実行される。サンドボックスの外に出るコマンド(excludedCommands や再試行)は通常の権限フローを通る
通常の権限確認サンドボックス内であっても、すべての Bash コマンドが権限フローを通る

auto-allow でも、次はそのまま効きます。

一方、対象を限定しない 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 *"]
  }
}

組織での強制とよくあるつまずき

保護されるパス: 書き込み可能な場所の中でも、次は常に書き込み不可です。リポジトリ内の設定を書き換えて次回以降の動作を変える、といった経路を塞ぐためのものです。

組織で強制する: 前の節の 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)。設定項目は更新される可能性があるため、利用前に公式ドキュメントをご確認ください。