Claude Codeの制限モード(--restricted)の使い方
--restricted(CLAUDE_CODE_RESTRICTED)は実行系ツールとWebFetchを外し、設定ファイルを読まずに起動する制限モードです。--tools・Bashサンドボックスとの組み合わせ方とつまずきをまとめます。
--restricted(またはCLAUDE_CODE_RESTRICTED=1)は、Claude Code v2.1.248で追加された起動フラグです。コマンドやコードを実行する組み込みツールとWebFetchを外し、ファイルツールを作業ディレクトリの内側に閉じ込め、ユーザー・プロジェクト・ローカルの設定ファイルを一切読まずに起動します。想定される使い方は、評価用のハーネスが共有マシン上でclaudeを動かし、そのマシンのユーザー設定やプロジェクト設定を読ませたくない場面です。
はじめに — 制限モードで何が変わるか
--restrictedが変えるのは主に4つです。
- コマンド・コードを実行する組み込みツールと
WebFetchが使えなくなる(--toolsで個別に名指しした場合を除く。defaultプリセット経由では戻らない) - ファイルツール(Read・Write・Edit)はworking directories(作業ディレクトリと
--add-dirで追加したディレクトリ)の内側に限定される - 読み込む設定はmanaged settingsと
--settingsだけになり、ユーザー・プロジェクト・ローカルの設定ファイルは無視される bypassPermissionsとクラウドセッションの新規作成が拒否される
claude --restricted -p "query"--restrictedはClaude Code v2.1.248以降で使えます。それより前のバージョンでは、このフラグ自体が未知のオプションとして拒否されます。
制限モードは、名前が似た2つの機能と混同しやすいので先に区別しておきます。--safe-modeはCLAUDE.md・skills・MCPサーバー・hooksといったカスタマイズを無効化して起動する診断用のモードで、ツールの利用可否やファイルアクセス範囲は変えません。切り分け手順はClaude Code safe modeで「壊れた」設定を1コマンドで切り分けるで扱っています。もう1つはBashサンドボックスによるOSレベルの分離で、こちらは後述します。
ステップ1 — --restrictedで起動する
もっとも単純な使い方は、フラグを付けて-p(非対話モード)で起動することです。
claude --restricted -p "リポジトリのテストを実行して結果を要約して"このコマンドを実行しても、コマンド実行系のツールが外れているためテストを実行できません。制限モードは既定でコマンドを一切実行させない状態から始まるためです。実行系ツールが必要な場面は、ステップ3の--toolsとの組み合わせで扱います。
bypassPermissionsを同時に指定しようとしても拒否されます。Claude Codeは--restrictedで始めたセッションでbypassPermissionsモードへの切り替えを許しません。制限モードは「何を読むか」「何を実行できるか」を狭める機能であり、bypassPermissionsは逆に確認をすべて飛ばす機能なので、両立させない設計です。
ステップ2 — 環境変数で有効にしてCIに組み込む
フラグの代わりにCLAUDE_CODE_RESTRICTED=1という環境変数でも同じ効果があります。CI側でフラグを渡しにくい構成のときに使います。
CLAUDE_CODE_RESTRICTED=1 claude -p "query"共有マシン上で評価ハーネスからclaudeを呼ぶ構成では、--settingsでmanaged settings相当のファイルを明示的に指定します。それ以外のローカル設定を読ませない形が基本パターンです。
CLAUDE_CODE_RESTRICTED=1 claude --settings ./harness-settings.json -p "query"この構成では、共有マシン側にどんな~/.claude/settings.jsonや.claude/settings.jsonがあっても読み込まれません。評価対象のリポジトリに紛れ込んだ.claude/settings.jsonが勝手に権限ルールを広げる、といった経路を塞げます。
ステップ3 — 特定のツールだけ再び使えるようにする
評価ハーネスがテストコマンドの実行を必要とする場合、--toolsで個別に名前を挙げれば実行系ツールを戻せます。--restrictedが外すのは「defaultプリセット経由」のツールなので、名指しした分だけ復活します。
claude --restricted --tools "Bash,Read" -p "テストスイートを実行して失敗したケースだけ報告して"この例ではBashとReadだけが使えます。WebFetchやファイル書き込み系のツールは--toolsに含めない限り使えないままです。ファイルツールが作業ディレクトリの外へ出られない制約や、設定ファイルを読まない制約は--toolsとは無関係にそのまま残ります。
--restrictedはBashの到達範囲までは狭めない
--restrictedでBashを--toolsに戻すと、そのBashはOSレベルでは隔離されません。--restrictedの説明には、ファイルツールを作業ディレクトリに閉じ込めるという記述はあります。一方、Bashサブプロセスがアクセスできるファイルシステムやネットワークの範囲そのものを狭める記述はありません。OSレベルでの隔離を担うのはBashサンドボックス(sandbox.enabled)という別の仕組みで、こちらはBashサブプロセスを対象にファイルシステム分離とネットワーク分離をかけます。
つまり--restricted --tools Bashだけでは、「Claude Codeのツールとしてどこまで動けるか」は狭まります。「復活させたBashが実際に何に触れられるか」までは狭まりません。評価ハーネスでテスト実行のためにBashを戻すなら、Bashサンドボックスも併用するのが安全側の構成です。サンドボックスの設計はClaude Codeのサンドボックス設計、DevContainerでの隔離運用はClaude CodeをDevContainerで安全に動かす完全実装で扱っています。
制限モードと他の権限系機能の使い分け
Claude Codeには権限まわりの機能がいくつも並んでおり、名前だけでは違いが分かりにくいので早見表にまとめます。
| 機能 | 何を狭めるか | 設定ファイルは読むか |
|---|---|---|
--restricted | 何を狭めるか実行系ツール・WebFetchの利用可否、ファイルアクセス範囲、設定ファイルの読み込み元 | 設定ファイルは読むかmanaged settingsと--settingsのみ |
dontAskモード | 何を狭めるか事前承認済みのツール呼び出し以外はすべて自動拒否(ツール自体は削除されない) | 設定ファイルは読むか通常どおり読む |
bypassPermissionsモード | 何を狭めるか確認プロンプトと安全チェックそのものをすべて省く | 設定ファイルは読むか通常どおり読む |
--safe-mode | 何を狭めるかCLAUDE.md・skills・MCPサーバー・hooksなどのカスタマイズ | 設定ファイルは読むかカスタマイズ以外は通常どおり |
| Bashサンドボックス | 何を狭めるかBashサブプロセスが到達できるファイルシステム・ネットワークの範囲 | 設定ファイルは読むか通常どおり読む |
dontAskモードはツールを削除せず、承認ルールに合わないものをその場で拒否するのに対し、--restrictedは該当ツールをセッションから取り除きます。両者は組み合わせられますが、性格が異なる制限です。
もう1点、.claudeディレクトリや.gitのような保護対象パスへの書き込みについても--restrictedは他モードより厳格です。通常のauto modeでは、保護対象パスへの書き込みであってもauto modeの分類器が内容を判定して承認できる場合があります。--restrictedセッションでは、この分類器による承認自体が働きません。実行系ツールをすべて外している以上、保護対象パスをすり抜ける経路も同時にふさぐという設計です。
よくあるつまずき
settings.jsonのenvブロックに書いて配布しようとする — CLAUDE_CODE_RESTRICTEDは前述のとおりenvブロックでは無視されます。実際のシェル環境変数として渡してください。
bypassPermissionsへ切り替えようとする — --restrictedセッションからの切り替えは拒否されます。制限モードで始めたセッションはこの切り替えを許しません。
クラウドセッションを作ろうとする — --restrictedセッションからは拒否されます。エラーメッセージはCloud sessions cannot be created from a --restricted session: they would not enforce it.です。制限モードの外で作られた新しいセッションは制限を引き継がないので、このガードが働きます。クラウドセッションが必要なら、タスクをローカルの制限セッション内で完結させるか、--restrictedなしの別セッションから作成します。
--tools "default"で復元しようとする — --restrictedが外したツールは復元されません。個別のツール名を--toolsに列挙する必要があります。
--safe-modeと同じ目的の機能だと思い込む — --restrictedと--safe-modeは別機能です。--safe-modeはCLAUDE.mdやhooksなどのカスタマイズを止める診断用、--restrictedはツールの利用可否とファイル・設定の読み込み範囲を締める用途です。
よくある質問
--restrictedはいつから使えますか
Claude Code v2.1.248以降です。それより前のバージョンではフラグ自体が未知のオプションとして拒否されます。
CLAUDE_CODE_RESTRICTEDをリポジトリのsettings.jsonに書けば有効になりますか
なりません。envブロックに書いても無視されるため、シェルの環境変数として渡すか、--restrictedフラグを使う必要があります。
--restrictedセッションからクラウドセッションを作れますか
作れません。クライアント側でサーバーに問い合わせる前に拒否され、クラウド側にセッションは作成されません。
--restrictedを使えばBashサンドボックスは不要になりますか
なりません。--restrictedはツールの利用可否と設定の読み込み範囲を狭める仕組みで、--toolsで復活させたBashが到達できるファイルシステムやネットワークの範囲までは狭めません。OSレベルの隔離が必要ならBashサンドボックスを別途有効にします。
まとめ
--restrictedは、評価ハーネスや共有マシンでClaude Codeを動かすときに、実行系ツール・WebFetch・ローカル設定ファイルという3つの経路をまとめて締めるフラグです。--toolsで個別に戻したツールは、制限モードの外側にあるBashサンドボックスのようなOSレベルの隔離とは別物である点を踏まえて組み合わせるのが安全です。同じv2.1.248では、この制限モードの詳細を含む49項目の更新が入りました。全体像はClaude Code v2.1.248で確認できます。モデル切り替えという別の切り口でClaude Codeの動作範囲を締める機能としては、PreModelSwitch hookとPostModelSwitch hookでモデル切り替えを制御するも同時期に追加されています。