Exec Approvals
Exec 承認、許可リスト、サンドボックス脱出プロンプト
Exec approvals are the companion app / node host guardrail for letting a sandboxed agent run
commands on a real host (''gateway'' or ''node''). Think of it like a safety interlock:
commands are allowed only when policy + allowlist + (optional) user approval all agree.
Exec approvals are ''in addition'' to tool policy and elevated gating (unless elevated is set to ''full'', which skips approvals).
Effective policy is the ''stricter'' of ''tools.exec.*'' and approvals defaults; if an approvals field is omitted, the ''tools.exec'' value is used.
ask fallback によって解決されます（デフォルト：拒否）。
Where it applies
Exec 承認は実行ホスト上でローカルに強制されます：
- ''ゲートウェイホスト'' → ゲートウェイマシン上の ''openclaw'' プロセス
- ノードホスト → ノードランナー（macOS コンパニオンアプリまたはヘッドレスノードホスト）
macOS split:
- ''ノードホストサービス'' はローカル IPC 経由で ''system.run'' を ''macOS アプリ'' に転送します。
- macOS アプリ は承認を強制し、UI コンテキストでコマンドを実行します。
設定とストレージ
承認は実行ホスト上のローカル JSON ファイルに保存されます：
''~/.openclaw/exec-approvals.json''
スキーマ例：
{
"version": 1,
"socket": {
"path": "~/.openclaw/exec-approvals.sock",
"token": "base64url-token"
},
"defaults": {
"security": "deny",
"ask": "on-miss",
"askFallback": "deny",
"autoAllowSkills": false
},
"agents": {
"main": {
"security": "allowlist",
"ask": "on-miss",
"askFallback": "deny",
"autoAllowSkills": true,
"allowlist": [
{
"id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
"pattern": "~/Projects/**/bin/rg",
"lastUsedAt": 1737150000000,
"lastUsedCommand": "rg -n TODO",
"lastResolvedPath": "/Users/user/Projects/.../bin/rg"
}
]
}
}
}ポリシー設定
#
セキュリティ（`exec.security`）
- deny：すべてのホスト exec リクエストをブロックします。
- allowlist：許可リストにあるコマンドのみを許可します。
- full：すべてを許可します（elevated と同等）。
#
Ask（`exec.ask`）
- off：プロンプトを表示しません。
- on-miss：許可リストが一致しない場合のみプロンプトを表示します。
- always：すべてのコマンドでプロンプトを表示します。
#
Ask フォールバック（`askFallback`）
プロンプトが必要だが UI にアクセスできない場合、フォールバックが決定します：
- deny：ブロックします。
- allowlist：許可リストが一致する場合のみ許可します。
- full：許可します。
許可リスト（エージェントごと）
許可リストはエージェントごとです。複数のエージェントが存在する場合、macOS アプリで編集するエージェントを切り替えます。
パターンは大文字小文字を区別しない glob マッチです。
パターンはバイナリパスに解決される必要があります（ベース名のみのエントリは無視されます）。
従来の ''agents.default'' エントリは読み込み時に ''agents.main'' に移行されます。
Examples:
- ''~/Projects/**/bin/bird''
- ''~/.local/bin/*''
- ''/opt/homebrew/bin/rg''
各許可リストエントリは以下を追跡します：
- id UI アイデンティティ用の安定した UUID（オプション）
- 最終使用 タイムスタンプ
- 最終使用コマンド
- 最終解決パス
スキル CLI の自動許可
スキル CLI の自動許可が有効な場合、既知のスキルで参照される実行可能ファイルは
ノード上で許可リスト済みとして扱われます（macOS ノードまたはヘッドレスノードホスト）。これは
''skills.bins'' を Gateway RPC 経由で使用してスキル bin リストを取得します。厳格な手動許可リストが必要な場合は無効にしてください。
セーフバイナリ（stdin のみ）
''tools.exec.safeBins'' は''stdin のみ''のバイナリ（例：''jq''）の小さなリストを定義し、
許可リストモードで明示的な許可リストエントリなしで実行できます。セーフバイナリは
位置引数ファイルとパスのようなトークンを拒否するため、受信ストリームのみを操作できます。
シェルチェーンとリダイレクトは許可リストモードでは自動許可されません。
すべてのトップレベルセグメントが許可リストを満たす場合、シェルチェーン（''&&''、''||''、'';''）は許可されます
（セーフバイナリまたはスキル自動許可を含む）。リダイレクトは許可リストモードでは引き続きサポートされません。
デフォルトのセーフバイナリ：''jq''、''grep''、''cut''、''sort''、''uniq''、''head''、''tail''、''tr''、''wc''。
コントロール UI 編集
コントロール UI → ノード → Exec 承認 カードを使用して、デフォルト、エージェントごとの
オーバーライド、許可リストを編集します。スコープ（デフォルトまたはエージェント）を選択し、ポリシーを調整し、
許可リストパターンを追加/削除してから保存します。UI は各パターンの最終使用メタデータを表示し、
リストを整理しておくことができます。
ターゲットセレクターはゲートウェイ（ローカル承認）またはノードを選択します。ノードは
''system.execApprovals.get/set'' をアドバタイズする必要があります（macOS アプリまたはヘッドレスノードホスト）。
ノードがまだ exec 承認をアドバタイズしていない場合、そのローカル
''~/.openclaw/exec-approvals.json'' を直接編集してください。
CLI：''openclaw approvals'' はゲートウェイまたはノード編集をサポートします（''承認 CLI'' を参照）。
承認フロー
プロンプトが必要な場合、ゲートウェイは ''exec.approval.requested'' をオペレータークライアントにブロードキャストします。
コントロール UI と macOS アプリは ''exec.approval.resolve'' 経由で解決し、ゲートウェイは
承認されたリクエストをノードホストに転送します。
承認が必要な場合、exec ツールは承認 ID を即座に返します。その ID を使用して
後続のシステムイベント（''Exec finished'' / ''Exec denied''）を関連付けます。タイムアウト前に決定が届かない場合、
リクエストは承認タイムアウトとして扱われ、拒否理由として表示されます。
確認ダイアログには以下が含まれます：
- コマンド + 引数
- cwd
- エージェント ID
- 解決された実行可能パス
- ホスト + ポリシーメタデータ
アクション：
- 一度だけ許可 → 今すぐ実行
- 常に許可 → 許可リストに追加 + 実行
- 拒否 → ブロック
チャットチャネルへの承認転送
exec 承認プロンプトを任意のチャットチャネル（プラグインチャネルを含む）に転送し、
''/approve'' で承認できます。これは通常のアウトバウンド配信パイプラインを使用します。
Config:
{
approvals: {
exec: {
enabled: true,
mode: "session", // "session" | "targets" | "both"
agentFilter: ["main"],
sessionFilter: ["discord"], // substring or regex
targets: [
{ channel: "slack", to: "U12345678" },
{ channel: "telegram", to: "123456789" },
],
},
},
}チャットで返信：
/approve <id> allow-once /approve <id> allow-always /approve <id> deny
#
macOS IPC フロー
Gateway -> Node Service (WS)
| IPC (UDS + token + HMAC + TTL)
v
Mac App (UI + approvals + system.run)セキュリティノート：
- Unix ソケットモード ''0600''、トークンは ''exec-approvals.json'' に保存されます。
- 同一 UID ピアチェック。
- チャレンジ/レスポンス（nonce + HMAC トークン + リクエストハッシュ）+ 短い TTL。
システムイベント
Exec ライフサイクルはシステムメッセージとして表示されます：
- ''Exec running''（コマンドが実行通知しきい値を超えた場合のみ）
- ''Exec finished''
- ''Exec denied''
これらはノードがイベントを報告した後、エージェントのセッションに投稿されます。
ゲートウェイホスト exec 承認は、コマンド完了時に同じライフサイクルイベントを発行します（およびオプションでしきい値より長く実行されている場合）。
承認が必要な exec は、これらのメッセージで承認 ID を ''runId'' として再利用し、簡単に関連付けできます。
Implications
- full は強力です；可能な限り許可リストを使用してください。
- ask は迅速な承認を許可しながら、あなたをループに保ちます。
- エージェントごとの許可リストは、あるエージェントの承認が他のエージェントに漏れるのを防ぎます。
- 承認は''認可された送信者''からのホスト exec リクエストにのみ適用されます。認可されていない送信者は ''/exec'' を発行できません。
- ''/exec security=full'' は認可されたオペレーターのためのセッションレベルの利便性であり、設計上承認をスキップします。
ホスト exec を完全にブロックするには、承認セキュリティを ''deny'' に設定するか、ツールポリシーで ''exec'' ツールを拒否してください。
Related:
- ''Exec ツール''
- ''昇格モード''
- ''スキル''