Exec承認

Exec承認は、サンドボックス化されたエージェントが実際のホスト（gateway または node）でコマンドを実行できるようにするための コンパニオンアプリ/ノードホストガードレール です。安全インターロックのように考えてください: コマンドは、ポリシー + 許可リスト + （オプションの）ユーザー承認がすべて同意した場合にのみ許可されます。 Exec承認は、ツールポリシーとelevatedゲートに 追加 されます（elevatedが full に設定されている場合を除き、承認をスキップします）。 有効なポリシーは tools.exec.* と承認デフォルトの より厳格な ものです。承認フィールドが省略されている場合、tools.exec の値が使用されます。

コンパニオンアプリUIが 利用できない 場合、プロンプトを必要とする要求は askフォールバック（デフォルト: deny）によって解決されます。

適用場所

Exec承認は実行ホストでローカルに適用されます:

  • gatewayホスト → gatewayマシンの openclaw プロセス
  • nodeホスト → nodeランナー（macOSコンパニオンアプリまたはヘッドレスノードホスト）

macOS分割:

  • nodeホストサービス はローカル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マッチ です。 パターンは バイナリパス に解決される必要があります（basename のみのエントリは無視されます）。 レガシーの agents.default エントリは、ロード時に agents.main に移行されます。

例:

  • ~/Projects/**/bin/bird
  • ~/.local/bin/*
  • /opt/homebrew/bin/rg

各許可リストエントリは以下を追跡します:

  • id UI識別に使用される安定したUUID（オプション）
  • last used タイムスタンプ
  • last used command
  • last resolved path

スキルCLIの自動許可

Auto-allow skill CLIs が有効な場合、既知のスキルが参照する実行可能ファイルはノード（macOSノードまたはヘッドレスノードホスト）で許可リストに載っているものとして扱われます。これはGateway RPC経由で skills.bins を使用してスキルbinリストを取得します。厳格な手動許可リストが必要な場合はこれを無効にします。

セーフバイナリ（stdinのみ）

tools.exec.safeBins は、明示的な許可リストエントリなしで許可リストモードで実行できる stdinのみ のバイナリ（例: jq）の小さなリストを定義します。セーフバイナリは位置ファイル引数とパスのようなトークンを拒否するため、入ってくるストリームでのみ動作できます。 シェルチェーンとリダイレクトは許可リストモードで自動許可されません。

シェルチェーン（&&、||、;）は、すべてのトップレベルセグメントが許可リストを満たす場合（セーフバイナリまたはスキル自動許可を含む）に許可されます。リダイレクトは許可リストモードでサポートされていません。

デフォルトのセーフバイナリ: jq、grep、cut、sort、uniq、head、tail、tr、wc。

Control UIでの編集

Control UI → Nodes → Exec approvals カードを使用して、デフォルト、エージェントごとのオーバーライド、許可リストを編集します。スコープ（デフォルトまたはエージェント）を選択し、ポリシーを調整し、許可リストパターンを追加/削除してから、保存 します。UIはパターンごとの last used メタデータを表示するため、リストを整理できます。

ターゲットセレクターは Gateway（ローカル承認）または Node を選択します。ノードは system.execApprovals.get/set を宣伝する必要があります（macOSアプリまたはヘッドレスノードホスト）。 ノードがまだexec承認を宣伝していない場合は、ローカルの ~/.openclaw/exec-approvals.json を直接編集します。

CLI: openclaw approvals はgatewayまたはノード編集をサポートします（Approvals CLI参照）。

承認フロー

プロンプトが必要な場合、gatewayは exec.approval.requested をオペレータークライアントにブロードキャストします。 Control UIとmacOSアプリは exec.approval.resolve 経由で解決し、gatewayは承認された要求をノードホストに転送します。

承認が必要な場合、execツールは承認IDで即座に返します。そのIDを使用して、後のシステムイベント（Exec finished / Exec denied）を関連付けます。タイムアウト前に決定が到着しない場合、要求は承認タイムアウトとして扱われ、拒否理由として表示されます。

確認ダイアログには以下が含まれます:

  • コマンド + 引数
  • cwd
  • エージェントID
  • 解決された実行可能パス
  • ホスト + ポリシーメタデータ

アクション:

  • Allow once → 今すぐ実行
  • Always allow → 許可リストに追加 + 実行
  • Deny → ブロック

チャットチャネルへの承認転送

exec承認プロンプトを任意のチャットチャネル（プラグインチャネルを含む）に転送し、/approve で承認できます。これは通常のアウトバウンド配信パイプラインを使用します。

設定:

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session", // "session" | "targets" | "both"
      agentFilter: ["main"],
      sessionFilter: ["discord"], // 部分文字列または正規表現
      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

これらはノードがイベントを報告した後、エージェントのセッションに投稿されます。 Gatewayホストexec承認は、コマンドが終了したとき（およびオプションでしきい値より長く実行されているとき）に同じライフサイクルイベントを発行します。 承認ゲートされたexecは、これらのメッセージでの簡単な相関のために、承認IDを runId として再利用します。

影響

  • full は強力です。可能であれば許可リストを優先してください。
  • ask は高速承認を許可しながらループに保ちます。
  • エージェントごとの許可リストは、あるエージェントの承認が他のエージェントに漏れるのを防ぎます。
  • 承認は 承認された送信者 からのホストexec要求にのみ適用されます。承認されていない送信者は /exec を発行できません。
  • /exec security=full は承認されたオペレーター向けのセッションレベルの便利機能で、設計により承認をスキップします。 ホストexecをハードブロックするには、承認セキュリティを deny に設定するか、ツールポリシー経由で exec ツールを拒否します。

関連:

← ドキュメントに戻る