Claude Media
Claude Codeのsandbox.ignoreViolationsで違反レポートを抑える
Claude CodeTips

Claude Codeのsandbox.ignoreViolationsで違反レポートを抑える

sandbox.ignoreViolationsは、想定内の拒否を違反レポートから外す設定です。アクセスはブロックされたまま、報告だけが消えます。部分一致キーの意味と書き方を扱います。

読了目安 約9分

sandbox.ignoreViolationsは、sandboxが拒否した操作のうち「拒否されて当然のもの」を違反レポートから外す設定です。起動時に/etc/hostsを覗きにいくツールがあり、毎回その拒否が報告に出て邪魔になる、という場面で使います。

ここで押さえる点は1つです。この設定は許可ではありません。sandboxは引き続きアクセスをブロックし、消えるのは報告だけです。

ignoreViolationsは何を静かにする設定か

sandboxを有効にすると、BashコマンドはOSレベルで隔離され、許可されていないファイルやネットワークへのアクセスは拒否されます。拒否が起きると、その内容は違反として報告され、Claudeも「どのアクセスが何の理由で拒否されたか」を知ります。

ignoreViolationsに書いた項目は、この報告から除かれます。設定リファレンスの説明では、利用者の画面に出る違反としても、Claudeが見る内容としても現れなくなります。

観点ignoreViolationsに書いたとき
アクセスそのものignoreViolationsに書いたとき引き続きブロックされる
違反レポートignoreViolationsに書いたとき該当分が出なくなる
Claudeが受け取る拒否の情報ignoreViolationsに書いたとき該当分が含まれなくなる
既定ignoreViolationsに書いたとき未設定。すべての違反が報告される

sandbox全般の考え方はsandbox.enabledの解説にまとめています。ここでは違反レポートの抑制だけを扱います。

書き方 — キーはコマンド、値は違反の一部

型は、コマンドの部分文字列から、無視したい違反の部分文字列の配列へのオブジェクトです。最小の例は次のとおりです。

{
  "sandbox": {
    "ignoreViolations": {
      "*": ["/etc/hosts"]
    }
  }
}

設定リファレンスの例は、このとおり*と/etc/hostsの組み合わせです。

  • キー: 実行されたコマンドと照合する部分文字列。*は全コマンドに一致する
  • 値: そのコマンドで無視する違反に含まれる部分文字列。典型はファイルパス

キーの照合は完全一致ではなく部分一致です。npmのように短く書けば、その語を含むコマンドが対象になります。

全コマンドか、特定のコマンドだけか

次の形は、*で全コマンド共通の項目を持ちつつ、特定のコマンドにだけ別の項目を足す例です。

{
  "sandbox": {
    "ignoreViolations": {
      "*": ["/etc/hosts"],
      "some-tool": ["/etc/resolv.conf"]
    }
  }
}

これは公式の例を元にした書き方の一例です。some-toolは説明用の仮名で、実在のコマンド名ではありません。キーが複数あるとき、一致したキーの値がどう合わさるかは、設定リファレンスに記載がありません。意図した結果になっているかは、実際にコマンドを流して確かめるのが確実です。

使いどころと、使わないほうがよい場面

向いているのは、拒否が想定内で、しかも毎回同じ場所に出るケースです。

  • 起動時に/etc/hostsのような固定のパスを確認するCLIツール
  • 診断のためにあえて許可されていないパスを探るスクリプト
  • 拒否のたびに報告が増え、本当に見たい違反が埋もれてしまう環境

逆に、広く*を指定して広いパスを静かにするのは避けたほうがよい使い方です。違反レポートは、sandboxの設定が実態に合っていないことを知らせる手がかりでもあります。たとえば書き込み先が足りずに失敗しているなら、報告を消すのではなくallowWriteとdenyWriteで範囲を調整するほうが、根本の解決になります。

値には、できるだけ具体的なパスを書くのが無難です。/etc/hostsのように1ファイルを指す書き方なら、他のパスへの想定外のアクセスは引き続き報告されます。

許可したいのか、報告を消したいのかを分ける

目的によって、触る設定が違います。

やりたいこと触る設定
アクセス自体を許したい触る設定filesystem.allowWrite、network.allowedDomains など
コマンドをsandboxの外で動かしたい触る設定excludedCommands
拒否は維持したまま報告だけ消したい触る設定ignoreViolations

excludedCommandsは効かないケースが知られているため、挙動を疑うときはsandbox.excludedCommandsが効かない3つの原因も参照してください。

どの設定ファイルに書けるか

設定リファレンスでは、この設定のスコープは任意の設定ファイルです。ただし、プロジェクト設定とローカル設定には制限があります。

管理者がsandboxを必須にしている環境では、その制限が効きます。sandboxがadmin-requiredになる条件は次の2つのどちらかです。

  • 管理設定、または--settingsフラグでallowUnsandboxedCommandsをfalseにしている(管理設定がtrueにしている場合を除く)
  • 管理設定でnetwork.allowManagedDomainsOnlyをtrueにしている

この状態では、リポジトリの.claude/settings.jsonと.claude/settings.local.jsonにあるignoreViolationsは、すべての項目が無視されます。excludedCommandsやnetwork.allowedDomainsなど、sandboxを緩める側の設定と同じ扱いです。有効になるのは、管理設定、--settings、各開発者の~/.claude/settings.jsonに書いた分です。

この無視はv2.1.285以降の挙動です。公式は、v2.1.282からv2.1.284では同じ条件でリポジトリのexcludedCommandsだけが無視された、と書いています。古いバージョンを使っているチームでは、ignoreViolationsの効き方が違う可能性があります。

一方、開発者本人の~/.claude/settings.jsonや--settingsに書いた分は有効なままです。allowManagedDomainsOnlyのような管理設定専用のロックが対象にしている項目を除き、表にある設定はこの2か所から引き続き使えます。ignoreViolationsについて、管理設定だけに限るロックの記載はありません。

また、リポジトリ側の設定が無視されている状態は、sandboxの既知のトラブルの原因にもなります。公式のトラブルシューティングも、admin-requiredの環境では、対処で触る設定はprojectの設定ファイルでは無視されるので~/.claude/settings.jsonに保存するよう案内しています。それでも効かないときは、管理設定が同じキーを持っている可能性があります。

つまり、チームのリポジトリにignoreViolationsをコミットしても、管理者がadmin-requiredにしている組織では効きません。個人で静かにしたいなら、~/.claude/settings.jsonに書きます。

{
  "sandbox": {
    "enabled": true,
    "ignoreViolations": {
      "*": ["/etc/hosts"]
    }
  }
}

enabledを含めているのは、ignoreViolations自体がsandboxを有効にする設定ではないからです。sandboxが無効のままなら、そもそも違反は発生しません。

拒否はどこに現れ、どこまで静かになるのか

違反の報告が現れる場所を知っておくと、何が静かになるのかを判断しやすくなります。

公式のchangelogには、sandboxの違反の詳細がBashツールの結果に出ていなかった不具合の修正が載っています。修正後は、Claudeは「どのファイルやネットワークへのアクセスが、なぜ拒否されたか」を見られます。ignoreViolationsの説明にある「Claudeが見る内容」とは、このBashの結果に添えられる拒否の情報を指すと考えるのが自然です。ただし、changelogの文と設定リファレンスの説明を結び付ける記述は、公式には見当たりません。

ネットワークについては、別の記述があります。sandboxがネットワーク接続を拒否すると、Claude Codeはコマンドの結果に拒否されたホスト名を載せます。許可リストにないホストへの接続は、権限モードによっては確認プロンプトが出たり、そのまま拒否されたりします。ignoreViolationsの例も説明も、書いてあるのはファイルパスの場合です。ホスト名の拒否を静かにできるかどうかは、公式に記載がないため、必要なら手元で試して確かめることになります。

静かになってもブロックは続く

報告が消えても、保護が外れるわけではありません。sandboxは、書き込みを許した範囲の内側でも、次のような設定ファイルへの書き込みは拒否し続けます。

  • 作業ディレクトリとその上位にある.claudeの設定ファイル、.mcp.json
  • 作業ディレクトリ直下の.bashrcや.zshrcなどのシェル起動ファイル、.gitconfig、.git内のhooksとconfig
  • ~/.claudeの中身の大半と~/.claude.json

これらの保護はallowWriteでも外せません。外す方法はfilesystem.disabledで、これはすべてのパスのファイル隔離を止める設定です。報告を静かにする目的で選ぶ手段ではありません。

効かない相手もある

sandboxが包むのはシェルコマンドと、その子プロセスです。Read・Edit・Write・WebFetchなどの組み込みツールは、sandboxではなく権限ルールで制御されます。hooks、ローカルのMCPサーバー、ステータスラインのコマンドもsandboxの外で動きます。これらが何かを拒否された場合の通知は、sandboxの違反ではないので、ignoreViolationsの対象として説明されているものではありません。

動作の確かめ方

公式は、sandboxが働いているかを確かめる方法として、Claudeに次の2つを実行させる手順を示しています。自分で打つと!プロンプト経由でsandboxの外で動くことが多いので、必ずClaudeに実行させます。

コマンドsandbox内での結果
touch ~/sandbox-probesandbox内での結果macOSではOperation not permitted、LinuxとWSL2ではRead-only file systemで失敗する
curl --noproxy '*' https://example.comsandbox内での結果Could not resolve hostで失敗する

ignoreViolationsを足したあとも、同じコマンドが失敗することを確かめれば、「静かになっただけでブロックは続いている」ことを自分の環境で見られます。もしtouchが成功したら、ホームが書き込み許可に入っているので、~/sandbox-probeを消したうえで/sandboxで状態を確認します。Claudeが失敗したコマンドをsandboxの外で再試行したいと尋ねてきたら、この確認では断ります。

報告が消えたかどうかは、次の順で見ます。

  1. 先に設定なしで、拒否が出るコマンドを流し、Bashの結果に拒否の内容が出ることを見ておく
  2. ignoreViolationsを足し、同じコマンドを流して、該当する分が出なくなったかを比べる
  3. 無視していない別のパスへのアクセスを流し、こちらは変わらず報告されることを確かめる

報告が消えたときの表示の形は、公式に記載がありません。前後の比較で見るのが確実です。3つ目は、指定が広すぎて他の違反まで消えていないかを見分ける手順にもなります。

Agent SDKで使うときの型の違い

Agent SDKのsandbox設定にもignoreViolationsがあります。TypeScript版はRecord<string, string[]>で、この記事のsettings.jsonと同じ形です。Python版は別の型になるため、設定をそのまま移植すると型が合いません。詳しい違いはAgent SDKのsandbox設定にあります。

まとめ

ignoreViolationsは、想定内の拒否が生む報告ノイズを減らすための設定です。保護の強さは変わりません。キーはコマンドの部分文字列、*は全コマンドで、値は具体的なパスにするほど、消える報告が少なくなります。管理者がsandboxを必須にしている環境ではリポジトリ側の設定が無視されるため、個人の~/.claude/settings.jsonに置くのが確実です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →