Claude Code ネイティブ Sandbox 入門：/sandbox コマンド・設定・プラットフォーム別手順

Claude Code を使っていると「このコマンドを実行してもいいですか？」という承認ダイアログが頻繁に表示されます。最初はセキュリティのためと理解できても、毎回ダイアログを確認して「承認」をクリックし続けるうちに、次第に内容をちゃんと読まなくなっていきます。これが「承認疲れ（Approval Fatigue）」と呼ばれる問題です。

Claude Code のネイティブ Sandbox 機能はこの問題に対処するために設計されています。事前に「許可する範囲」を設定しておけば、その範囲内でのコマンドは承認なしに自動実行できます。承認ダイアログの数を大幅に削減しながら、定義された境界の外へのアクセスはしっかりブロックされます。

しかし実際に設定しようとすると、詰まるポイントが複数あります。「macOS と Linux で手順が違うらしいが、自分の環境ではどう進めればいいのか」「settings.json に何を書けばいいか・どこにファイルを置けばいいか分からない」「有効にしたら一部のコマンドが動かなくなった」といった声をよく聞きます。

この記事では、Claude Code のネイティブ Sandbox（/sandbox コマンドで有効化する機能）について、macOS は3ステップ・Linux/WSL2 は5ステップで有効化できる手順から、settings.json の基本設定・応用設定、よくあるトラブルの対処法までを解説します。

なお、この記事は「ネイティブ Sandbox」に特化した内容です。Docker を使った別のサンドボックス方式（Docker Sandbox）との詳細な比較は、Claude Code Docker Sandbox 入門を参照してください。

Claude Code ネイティブ Sandbox とは

Claude Code ネイティブ Sandbox は、OS レベルのセキュリティ機構を使って、Claude Code が実行する Bash コマンドとそのすべての子プロセスを隔離する機能です。ここでの「ネイティブ」とは、Docker コンテナを使わず、OS 標準の仕組みで分離を実現することを意味します。

2つの分離層（ファイルシステム + ネットワーク）

ネイティブ Sandbox の分離は、以下の2つの層で構成されています。

ファイルシステム分離

デフォルトでは、サンドボックス化されたコマンドは「現在の作業ディレクトリ（プロジェクトルート）とそのサブディレクトリ」にのみ書き込めます。~/Documents や ~/.bashrc など、プロジェクト外のファイルを変更しようとしてもブロックされます。

読み取りは、デフォルトで一部の機密ディレクトリ（~/.ssh、~/.aws など）を除きコンピュータ全体が許可されていますが、denyRead 設定で制限を追加できます。

ネットワーク分離

サンドボックス外で動作するプロキシサーバーを通じて、アクセスできるドメインが制御されます。許可されていないドメインへの通信は即座にブロックされます。新しいドメインへのアクセスが必要な場合は許可プロンプトが表示され、ユーザーが都度判断できます。

この2層の分離は、OS レベルで実施されるため、Claude のファイル操作ツール（Read、Edit、Write）だけでなく、kubectl、terraform、npm といったサブプロセスのコマンドにも同様に適用されます。

macOS と Linux でどう実現されているか（Seatbelt / bubblewrap）

OS レベルの分離を実現するために、プラットフォームごとに異なる仕組みが使われています。

Seatbelt は macOS が元々持つアクセス制御の仕組みで、Claude Code はこれを活用してファイルシステムの書き込み制限を実施します。Linux では同等の機能を bubblewrap（コンテナ化ライブラリ）と socat（ネットワークプロキシ）の組み合わせで実現しています。

セットアップ手順

macOS の場合（3ステップ）

macOS では追加のパッケージインストールは不要です。Seatbelt が標準搭載されているため、すぐに有効化できます。

ステップ 1: Claude Code を起動する

claude

ステップ 2: /sandbox コマンドを実行する

Claude Code のプロンプト上で以下を入力します。

/sandbox

ステップ 3: モードを選択する

メニューが表示されます。次のセクション「/sandbox コマンドで有効化する」で詳しく説明しますが、まずは「Sandbox BashTool, with auto-allow（自動許可モード）」を選ぶとスムーズに始められます。

これだけで macOS でのセットアップは完了です。

Linux / WSL2 の場合（5ステップ）

Linux と WSL2 では、bubblewrap と socat のインストールが先に必要です。

注意: WSL1 は非対応です。WSL のバージョンを確認するには wsl --list --verbose を実行してください。バージョンが「1」の場合は WSL2 へのアップグレードが必要です。

ステップ 1: bubblewrap と socat をインストールする

Ubuntu / Debian の場合：

sudo apt-get install bubblewrap socat

Fedora の場合：

sudo dnf install bubblewrap socat

ステップ 2: インストールを確認する

bwrap --version && socat -V

正常にバージョンが表示されれば OK です。表示されない場合はインストールが正常に完了していない可能性があります。

ステップ 3: Claude Code を起動する

claude

ステップ 4: /sandbox コマンドを実行する

/sandbox

必要なパッケージが揃っていれば、モード選択メニューが表示されます。依存関係に不足がある場合はインストール手順がメニュー上に表示されます。

ステップ 5: モードを選択する

macOS と同様に、「Sandbox BashTool, with auto-allow（自動許可モード）」を選択します。

/sandbox コマンドで有効化する

/sandbox コマンドを実行すると、以下のメニューが表示されます。

> Sandbox mode:
  ○ No sandbox
  ● Sandbox BashTool, with auto-allow
  ○ Sandbox BashTool, with regular permissions

2つのモードの違いと選び方

自動許可モード（auto-allow）

サンドボックス内で実行できるコマンドは、承認なしに自動的に許可されます。サンドボックス外へのアクセスが必要なコマンド（許可されていないドメインへのネットワーク接続など）のみ通常の許可フローに戻ります。

「承認疲れを解消して、作業をスムーズに進めたい」という目的にはこのモードが最適です。多くのケースでは自動許可モードから始めるのをお勧めします。

通常の許可モード（regular permissions）

すべての Bash コマンドが、サンドボックス化されている場合でも通常の許可フローを経ます。承認ダイアログの数は減りませんが、サンドボックスによるファイルシステム・ネットワーク分離は有効です。「承認ダイアログは残しつつ、ファイルシステムの保護だけ強化したい」というケースに向いています。

sandbox の状態確認方法

Claude Code のステータスバーまたはヘッダー部分に現在の sandbox の状態が表示されます。

• sandbox: on（auto-allow） — 自動許可モードで有効
• sandbox: on（regular） — 通常許可モードで有効
• ⚠ sandbox disabled — 無効化されているか、依存パッケージが不足している

settings.json で sandbox を設定する

/sandbox コマンドでセッションごとに設定するほか、settings.json ファイルに記述することで設定を永続化・カスタマイズできます。

基本設定（最小 settings.json 例）

最もシンプルな設定は以下の1フィールドだけです。

{
  "sandbox": {
    "enabled": true
  }
}

これだけで、Claude Code 起動時に自動でサンドボックスが有効になります。デフォルトでは「通常の許可モード」で起動します。自動許可モードをデフォルトにしたい場合は autoAllowBashIfSandboxed を追加します。

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true
  }
}

ファイルシステムアクセスの制御（allowWrite / denyRead / allowRead）

allowWrite — 書き込み許可パスの追加

デフォルトでは、作業ディレクトリ外への書き込みはブロックされます。kubectl や terraform のように、設定ファイルをホームディレクトリ配下に書き込む CLI ツールを使う場合は、allowWrite で追加の書き込み先を許可します。

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "~/.terraform", "/tmp/build"]
    }
  }
}

パスの書き方のルール：

denyRead — 読み取り拒否パスの追加

機密ファイルへの読み取りをブロックしたい場合は denyRead を使います。

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/.ssh", "~/.aws", ".env"]
    }
  }
}

allowRead — denyRead で拒否した範囲の一部を再許可

ホームディレクトリ全体を拒否しつつ、プロジェクトルートだけ読み取りを許可する場合は allowRead を使います（denyRead より優先されます）。

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

ネットワークアクセスの制御（allowedDomains）

外部 API を呼び出すスクリプトを実行する場合、許可するドメインを事前に設定しておくと承認プロンプトなしにアクセスできます。

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["api.github.com", "registry.npmjs.org"]
    }
  }
}

許可されていないドメインへのアクセスが発生すると、その場で許可を求めるプロンプトが表示されます。1回だけ許可するか、設定に永続追加するかを選択できます。

設定スコープの使い分け（グローバル / プロジェクト / ローカル）

settings.json は保存場所によって「スコープ」が決まります。

推奨の使い方

• 「sandbox を常に有効にしたい」 → グローバル設定（~/.claude/settings.json）に enabled: true を書く
• 「このプロジェクトでは ~/.kube への書き込みを許可したい」 → プロジェクト設定（.claude/settings.json）に allowWrite を書く。チームメンバーも同じ設定を使える
• 「自分のマシンだけの個別設定」 → ローカル設定（.claude/settings.local.json）に書く

複数のスコープで同じ設定が定義されている場合、配列はマージされます（置き換えではなく結合）。グローバルで ~/.kube を許可し、プロジェクトで ./output を追加すれば、両方が有効になります。優先順位はローカル > プロジェクト > グローバルの順です。

よくあるトラブルと対処法

sandbox 有効後に docker / npm が失敗する

症状

sandbox を有効にしてから docker build や npm install などのコマンドが失敗するようになった。エラーメッセージに permission denied や network unreachable が含まれる。

原因と対処法

docker の場合: docker はサンドボックス内での動作が非対応です（Docker デーモンへのアクセスに Unix ソケット /var/run/docker.sock が必要なため）。excludedCommands に設定して、サンドボックス外で実行されるようにします。

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker", "docker-compose"]
  }
}

npm の場合: npm は外部レジストリ（registry.npmjs.org）に接続する必要があります。allowedDomains にドメインを追加します。

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["registry.npmjs.org"]
    }
  }
}

watchman の場合: Facebook の watchman（ファイル監視ツール）はサンドボックスと互換性がありません。Jest を使っている場合は jest --no-watchman オプションで回避できます。あるいは excludedCommands に watchman を追加してください。

Linux で bubblewrap インストール後も sandbox が有効にならない

症状

bubblewrap をインストールして /sandbox コマンドを実行したが、ステータスバーに ⚠ sandbox disabled と表示される。または /sandbox コマンドが「Unknown slash command: sandbox」というエラーになる。

確認手順

1. socat が入っているか確認する

bubblewrap だけでなく、socat も必要です。インストール済みか確認します。

which socat
# または
socat -V

インストールされていない場合：

# Ubuntu / Debian
sudo apt-get install socat

# Fedora
sudo dnf install socat

2. WSL1 ではないか確認する

WSL1 は非対応です。以下のコマンドで WSL バージョンを確認します。

wsl --list --verbose

「VERSION」列が「1」の場合は WSL2 へのアップグレードが必要です。

3. bubblewrap のバージョンを確認する

古すぎるバージョンでは動作しないことがあります。

bwrap --version

バージョンが古い場合は sudo apt-get upgrade bubblewrap でアップグレードします。

4. settings.json の enabled を確認する

~/.claude/settings.json または .claude/settings.json に以下が記載されているか確認します。

{
  "sandbox": {
    "enabled": true
  }
}

failIfUnavailable を true に設定すると、sandbox が起動できない場合にコマンドが失敗するため、エラーの原因が明確になります（通常時はサンドボックスなしで継続されるため、有効になっていないことに気づきにくいことがあります）。

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true
  }
}

特定のコマンドをサンドボックス外で実行したい

sandbox が有効な状態で、特定のコマンドだけサンドボックス外で動かしたい場合は excludedCommands を使います。

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker", "kubectl", "git"]
  }
}

excludedCommands に指定したコマンドは、通常の許可フロー（承認ダイアログ）を経て実行されます。

注意: allowUnsandboxedCommands: false を設定している場合、excludedCommands はサンドボックス外での実行を「通常の許可フローで」実行させるための設定であって、無条件に実行を許可するわけではありません。

Docker Sandbox との違いと使い分け

Claude Code には「ネイティブ Sandbox」の他に、「Docker Sandbox」という方式もあります。簡単に違いをまとめます。

「まず手軽に使い始めたい」「承認疲れを解消したい」という場合はネイティブ Sandbox から始めるのがお勧めです。「完全に隔離された環境で実行したい」「CI/CD パイプラインに組み込みたい」という場合は Docker Sandbox が向いています。

まとめ

この記事で解説した内容をまとめます。

• Claude Code ネイティブ Sandbox は、ファイルシステムとネットワークの2層でコマンドを隔離し、承認疲れを解消しながらセキュリティを維持する機能
• macOS は追加インストール不要で /sandbox コマンドのみで有効化（3ステップ）
• Linux / WSL2 は bubblewrap と socat をインストール後に /sandbox で有効化（5ステップ）。WSL1 は非対応
• settings.json の sandbox.enabled: true で永続化。allowWrite、denyRead、allowedDomains で細かい制御が可能
• 設定スコープ はグローバル（~/.claude/settings.json）・プロジェクト（.claude/settings.json）・ローカル（.claude/settings.local.json）の3段階
• docker / watchman はサンドボックス非対応のため excludedCommands で除外する。npm のネットワークエラーは allowedDomains に追加する
• Linux でsandboxが有効にならない場合 は、socat の有無・WSL バージョン・bubblewrap のバージョンを順に確認する

より強固な隔離が必要な場合は、Claude Code Docker Sandbox 入門も参照してください。