Claude Codeの--permission-modeで起動モードを指定する
claude --permission-mode planのように起動コマンド1つで権限モードを固定する方法と、設定ファイルとの優先順位、CI・エージェント運用でのつまずきをまとめました。
Claude Codeの起動時に--permission-modeフラグを渡すと、Shift+Tabで手動切り替えするはずの権限モードを、コマンド1本で最初から固定できます。値はdefault(表示名はManual)・acceptEdits・plan・auto・dontAsk・bypassPermissionsの6つで、manualはdefaultのエイリアスとして扱われます。CI・スクリプト・サブエージェントの一括起動など、人が都度Shift+Tabを押せない場面で使う前提の設定です。
--permission-modeで指定できる値
まず何が選べるかを一覧で押さえます。値ごとに「何が確認なしで実行されるか」がまったく違うため、用途に合わない値を選ぶと確認だらけで止まるか、逆に危険な操作まで素通りするかのどちらかになります。
| 値 | 確認なしで動く範囲 | 向いている用途 |
|---|---|---|
default(manual) | 確認なしで動く範囲読み取りのみ | 向いている用途機密性の高い作業を1つずつレビューする |
acceptEdits | 確認なしで動く範囲読み取り・ファイル編集・mkdir/touch/mv/cp等 | 向いている用途レビュー済みコードの反復編集 |
plan | 確認なしで動く範囲読み取りに加え、auto modeが使えれば分類器承認済みのコマンド | 向いている用途変更前にコードベースを調査する |
auto | 確認なしで動く範囲ほぼすべて(分類器がバックグラウンドで判定) | 向いている用途長時間タスク、確認疲れの解消 |
dontAsk | 確認なしで動く範囲読み取りと事前承認済みツールのみ、それ以外は自動拒否 | 向いている用途ロックダウンされたCIやスクリプト |
bypassPermissions | 確認なしで動く範囲すべて | 向いている用途隔離されたコンテナ・VM限定 |
manualはdefaultの別名で、CLIの値としても"defaultMode": "manual"としても書けます。ただしこのエイリアスと「Manual」というUI表示名は、Claude Code v2.1.200以降でしか有効になりません。それより前のバージョンではdefaultとだけ書く必要があります。
現在のモードはターミナルのステータスバーでも確認できます。defaultは灰色の⏸ manual mode on、acceptEditsは⏵⏵ accept edits on、planは⏸ plan mode on、autoは⏵⏵ auto mode on、dontAskは⏵⏵ don't ask on、bypassPermissionsは⏵⏵ bypass permissions onという表示になります。スクリプトのログにこの文字列が混ざっていたら、意図したモードで起動できているかをそこで確認できます。
claude --permission-mode plan
claude --permission-mode acceptEdits
claude --permission-mode dontAsk
claude --permission-mode bypassPermissionsbypassPermissionsは--dangerously-skip-permissionsと等価です。どちらもファイル保護パスへの書き込みを含めて確認を一切挟まないため、公式ドキュメントもコンテナやネットワーク遮断されたVM以外での使用を明確に警告しています。この違いと安全な使い分けはClaude Code dontAskモードの記事で扱ったdontAskとの比較がそのまま参考になります。
CI・スクリプトから使うときの実例
-p(非対話モード)と組み合わせるのが典型的な使い方です。dontAskはデフォルトで拒否に倒れるため、実行させたいツールを--allowedToolsで明示しないと何も動きません。
claude -p "テストスイートを実行して結果を要約して" \
--permission-mode dontAsk \
--allowedTools "Bash(npm test)" "Read"コンテナやサンドボックス実行環境で確認そのものを不要にしたい場合はbypassPermissionsを使います。ホストのroot権限やsudo経由で起動した場合、Claude CodeはLinux/macOSでこのモードの起動自体を拒否します(サンドボックス内であれば自動的にスキップされます)。
claude -p "デプロイスクリプトを実行" --dangerously-skip-permissions非対話実行で「誰も答えられないので確認自体を止めたい」場合は--permission-modeとは別のフラグ、--permission-prompts noneをv2.1.259以降で併用できます。逆に承認をAgent SDKのホストやMCPツールに委ねたいときは--permission-prompt-toolを指定します。このフラグを渡すと、Claude Codeは最初のターンを実行する前に、指定したMCPツールのサーバーが接続を確立するまで待機します。待機時間の上限は環境変数MCP_TIMEOUTが決め、既定値は30秒です。この時間内にMCPサーバーが立ち上がらない構成だと、権限プロンプトを処理する仕組みそのものが間に合わずセッションが止まるので、CIでMCPサーバーをサイドカーとして起動する場合はこの30秒を意識しておく必要があります。この2つのフラグとheadless実行の全体像はClaude Code -pモードでスクリプトやパイプラインを自動化する基本にまとめてあります。
claude auto-mode defaultsを実行すると、auto modeの分類器が採用しているルールをJSONで確認できます。--labelで絞り込みも可能です(v2.1.208以降)。
claude auto-mode defaults --label 'Git Destructive'設定ファイルとの優先順位
--permission-modeフラグは、セッション起動時にどの権限モードから始まるかを決める判定の中で最優先です。判定順は次のとおりです。
--permission-modeフラグ、または--dangerously-skip-permissions- 設定ファイルの
permissions.defaultMode - 組み込みのデフォルト値
ここには落とし穴があります。.claude/settings.jsonや.claude/settings.local.jsonに"defaultMode": "auto"と書いても効きません。この2つのファイルからはautoが反映されず、~/.claude/settings.jsonのdefaultModeもない場合は組み込みのデフォルトにフォールバックします。同様に"bypassPermissions"もこの2ファイルからは効かず、セッションはManualモードで始まります。autoとbypassPermissions以外の値は、どの設定ファイルに書いても適用されます。
組み込みのデフォルト自体も一様ではありません。Pro・Max・TeamプランでターミナルまたはVS Code拡張から起動した場合はauto modeが既定になりますが(macOS/Linux/WSLはv2.1.228以降、Windowsネイティブはv2.1.233以降が必要)、claude -pやAgent SDK経由、Enterpriseプラン、Claude Console APIキーを使う場合はdefaultが既定です。管理者がpermissions.disableAutoModeを"disable"に設定している組織では、フラグで--permission-mode autoを渡してもManualモードで起動します。
ターミナル以外ではこのフラグの効きが変わる
--permission-modeはCLIの起動フラグなので、ターミナルとJetBrainsプラグイン(内部でターミナルのClaude Codeを起動)には常に効きます。一方、VS Code拡張とClaude Code on the web(クラウドセッション)は起動経路が別なので、事情が異なります。
VS Code拡張は会話ごとにモードを持ちますが、起動時の既定値はclaudeCode.initialPermissionModeというVS Code側の設定で決めます。この設定はdefault/manual/acceptEdits/plan/bypassPermissionsは受け付けますがautoは指定できません。Autoで始めたい場合は、この設定を空のままにして、会話開始後にモードインジケーターから一度Autoを選ぶ操作が必要です。
Claude Code on the webのクラウドセッションはさらに制限が強く、設定ファイルのdefaultMode: "dontAsk"やdefaultMode: "bypassPermissions"を読みません。これらの値は無視され、モードのドロップダウンに表示されている権限モードでセッションが始まります。リポジトリにチェックインした設定ファイルだけでクラウドセッションをbypassPermissionsやdontAskで走らせることはできない、という点は把握しておく必要があります。
claude agentsでバックグラウンド起動する場合
claude agentsコマンドは並列で動くバックグラウンドセッションを管理するビューを開きますが、ここにも--permission-modeを渡せます。この場合はagent viewを開くのではなく、そこから新たにディスパッチするセッションの既定値を設定する働きをします。--modelや--effort、--agentも同様にディスパッチ先の既定値として機能します。
claude agents --permission-mode plan --model sonnetセッション再開時にモードは引き継がれるか
claude --continueやclaude --resume <session-id>のように-pを付けずターミナルから再開する場合、Claude Codeは終了時点の権限モードを条件付きで復元します。復元されるのはAuto(要件を満たす場合)と、設定ファイルのdefaultModeが無効な場合のManualのみで、終了時点がplanまたはbypassPermissionsだったセッションは復元されず、新規セッションと同じ既定モードで始まります。ここへ--permission-modeを追加で渡せば、復元される値を上書きできます。
一方、次の再開経路では保存されていたモードは復元されません。
- セッションピッカーから選んだ場合(
claude --resumeを引数なしで実行、claude --from-pr、名前が複数セッションに一致する場合)。この場合は同じコマンドラインで新規セッションを起動したときと同じモードで始まります - セッション内で
/resumeを実行した場合。切り替え先の会話は、切り替え元のセッションが今いる権限モードを引き継ぎます claude -p --resumeやclaude -p --continue。新規のclaude -p実行と同じ既定モードで始まります(セッションがplanモードで終了していた場合はv2.1.246以降でplanモードのまま復元される例外があります)
--mcp-config・--settings・--plugin-dir・--fallback-model・--add-dirで渡した設定は再開時に引き継がれないため、これらに依存するセッションを再開するときは毎回渡し直す必要があります。
よくあるつまずき
manualエイリアスが効かない: Claude Code v2.1.200より前のバージョンではmanualという値自体が存在しません。claude --versionでバージョンを確認し、古い場合はdefaultと書きます--allow-dangerously-skip-permissionsと--dangerously-skip-permissionsを混同する: 前者はbypassPermissionsをShift+Tabのモード切り替えサイクルに追加するだけで、起動直後にそのモードへ入るわけではありません。planなどで始めて後からbypassPermissionsへ切り替えたい場合に使うフラグです。即座にbypassPermissionsへ入りたいなら--dangerously-skip-permissions、または--permission-mode bypassPermissionsを使いますdontAskにしたのに何も実行されない:dontAskは事前承認されたツール以外をすべて自動拒否します。--allowedToolsやpermissions.allowルールで明示的に許可していないコマンドは、確認待ちにならず黙って拒否されるだけなので、スクリプトが早期終了しているように見えたらまずここを疑います- root/sudoで
bypassPermissionsが起動しない: LinuxとmacOSでは、root権限またはsudo経由で--dangerously-skip-permissionsを使おうとすると起動そのものが拒否されます。認識済みのサンドボックス内やdev container設定を使えばこのチェックは自動的にスキップされます - プロジェクト設定の
autoが効かない: 前述のとおり.claude/settings.jsonと.claude/settings.local.jsonのdefaultMode: "auto"は無視されます。チーム全体でauto modeを既定にしたいなら~/.claude/settings.jsonか管理者設定(managed settings)に置く必要があります
権限モードそのものの経緯や、各モードが何を審査しているかの詳しい仕組みはClaude Code権限モデルの変遷、UIラベルが「Manual」に変わった経緯はv2.1.200のリリースノート(Claude Code v2.1.200)で扱っています。
まとめ
--permission-modeは、Shift+Tabでの手動切り替えを起動コマンド1本に圧縮するためのフラグです。値はdefault/acceptEdits/plan/auto/dontAsk/bypassPermissionsの6種類(manualはdefaultのエイリアス、v2.1.200以降)。優先順位はフラグが最上位で、次に設定ファイルのpermissions.defaultMode、最後に組み込みのデフォルトという順です。ただしautoとbypassPermissionsはプロジェクト単位の設定ファイルからは反映されない点、dontAskは許可リストと必ずセットで使う点、rootやsudoではbypassPermissionsが起動できない点の3つが、スクリプトを組むときに最初につまずきやすいポイントです。