> ## Documentation Index
> Fetch the complete documentation index at: https://openclawdoc.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Exec Approvals

> Exec の承認は、サンドボックス エージェントを実行するための コンパニオン アプリ/ノード ホストのガードレールです 実ホスト上のコマンド (gateway または node)。これを安全インターロックのように考えてください。

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

コンパニオン アプリ UI が **利用できない**場合、プロンプトが必要なリクエストはすべて
**ask フォールバック** (デフォルト: 拒否) によって解決されます。

## 適用される場所

実行の承認は、実行ホスト上でローカルに適用されます。

* **ゲートウェイ ホスト** → ゲートウェイ マシン上の `openclaw` プロセス
* **ノード ホスト** → ノード ランナー (macOS コンパニオン アプリまたはヘッドレス ノード ホスト)

信頼モデルのメモ:- ゲートウェイで認証された呼び出し元は、そのゲートウェイの信頼できるオペレーターです。

* ペアになったノードは、信頼できるオペレーターの機能をノード ホストに拡張します。
* 実行承認は偶発的な実行のリスクを軽減しますが、ユーザーごとの認証境界ではありません。
* 承認されたノードホストの実行は、正規の実行コンテキストもバインドします: 正規の cwd、ピン留めされた実行可能ファイル
  パス (該当する場合)、およびインタープリター スタイルのスクリプト オペランド。バインドされたスクリプトが後で変更された場合
  承認されますが、実行前に、ドリフトされたコンテンツは実行されずに実行が拒否されます。

macOS の分割:

* **ノード ホスト サービス**は、ローカル IPC 経由で `system.run` を **macOS アプリ**に転送します。
* **macOS アプリ** は承認を強制し、UI コンテキストでコマンドを実行します。

## 設定とストレージ

承認は、実行ホスト上のローカル JSON ファイルに保存されます。

`~/.openclaw/exec-approvals.json`

スキーマの例:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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`)

* **拒否**: すべてのホスト実行リクエストをブロックします。
* **allowlist**: 許可リストに登録されたコマンドのみを許可します。
* **full**: すべてを許可します (昇格と同等)。

### 質問してください (`exec.ask`)

* **オフ**: プロンプトを表示しません。
* **on-miss**: ホワイトリストが一致しない場合にのみプロンプトを表示します。
* **常に**: すべてのコマンドでプロンプトを表示します。

### フォールバックを要求する (`askFallback`)

プロンプトが必要であるが、UI にアクセスできない場合、フォールバックは次のように決定します。

* **拒否**: ブロックします。
* **許可リスト**: 許可リストが一致する場合にのみ許可します。
* **フル**: 許可します。

## 許可リスト (エージェントごと)許可リストは**エージェントごと**です。複数のエージェントが存在する場合は、どのエージェントを切り替えるか

macOS アプリで編集します。パターンは **大文字と小文字を区別しないグロブ一致** です。
パターンは **バイナリ パス**に解決される必要があります (ベース名のみのエントリは無視されます)。
レガシー `agents.default` エントリは、ロード時に `agents.main` に移行されます。

例:

* `~/Projects/**/bin/peekaboo`
* `~/.local/bin/*`
* `/opt/homebrew/bin/rg`

各ホワイトリスト エントリは以下を追跡します。

* **id** UI ID に使用される安定した UUID (オプション)
* **最後に使用された**タイムスタンプ
* **最後に使用したコマンド**
* **最後に解決されたパス**

## スキル CLI の自動許可

**スキル CLI の自動許可** が有効になっている場合、既知のスキルによって参照される実行可能ファイル
ノード (macOS ノードまたはヘッドレス ノード ホスト) 上で許可リストに登録されているものとして扱われます。これは、
`skills.bins` をゲートウェイ RPC 経由で呼び出して、スキル ビン リストを取得します。厳密な手動許可リストが必要な場合は、これを無効にします。

信頼に関する重要な注意事項:

* これは、手動のパス ホワイトリスト エントリとは別の **暗黙的な便利なホワイトリスト** です。
* ゲートウェイとノードが同じ信頼境界内にある信頼できるオペレーター環境を対象としています。
* 厳密な明示的信頼が必要な場合は、`autoAllowSkills: false` を保持し、手動パス許可リスト エントリのみを使用してください。

## 金庫 (標準入力のみ)`tools.exec.safeBins` は **stdin のみ** バイナリの小さなリストを定義します (例: `jq`)

**明示的なホワイトリスト エントリなし**でホワイトリスト モードで実行できます。金庫が拒否される
位置ファイル引数とパスのようなトークンなので、受信ストリームでのみ操作できます。
これを一般的な信頼リストではなく、ストリーム フィルターの狭い高速パスとして扱います。
インタプリタまたはランタイム バイナリ (`python3`、`node`、`ruby`、`bash`、`sh`、`zsh` など) を追加しないでください\*\* `safeBins`。
設計上、コマンドがコードの評価、サブコマンドの実行、またはファイルの読み取りを実行できる場合は、明示的なホワイトリスト エントリを優先し、承認プロンプトを有効のままにしてください。
カスタム金庫は、`tools.exec.safeBinProfiles.<bin>` で明示的なプロファイルを定義する必要があります。
検証は argv の形状のみから決定的です (ホスト ファイルシステムの存在チェックは行われません)。
ファイルの存在に関する Oracle の動作が相違を許可/拒否しないようにします。
ファイル指向のオプションは、デフォルトの安全なビン (`sort -o`、`sort --output`、
`sort --files0-from`、`sort --compress-program`、`sort --random-source`、
`sort --temporary-directory`/`-T`、`wc --files0-from`、`jq -f/--from-file`、
`grep -f/--file`)。
セーフ ビンでは、stdin のみを破るオプションに対して明示的なバイナリごとのフラグ ポリシーも適用されます。
動作 (`sort -o/--output/--compress-program` や grep 再帰フラグなど)。長いオプションはセーフビン モードでフェイルクローズされて検証されます: 未知のフラグと曖昧な
略語は拒否されます。
セーフビン プロファイルによる拒否フラグ:

{/_SAFE_BIN_DENIED_FLAGS:START _/}

* `grep`: `--dereference-recursive`、`--directories`、`--exclude-from`、`--file`、`--recursive`、`-R`、 `-d`、`-f`、`-r`
* `jq`: `--argfile`、`--from-file`、`--library-path`、`--rawfile`、`--slurpfile`、`-L`、 `-f`
* `sort`: `--compress-program`、`--files0-from`、`--output`、`--random-source`、`--temporary-directory`、`-T`、 `-o`
* `wc`: `--files0-from`
  {/_SAFE_BIN_DENIED_FLAGS:END _/}セーフ ビンは、実行時に argv トークンを **リテラル テキスト**として強制的に処理します (グロビングは行われません)。
  `$VARS` 拡張なし) は標準入力専用セグメントの場合、`*` や `$HOME/...` のようなパターンは使用できません。
  ファイルの読み取りを密かに行うために使用されます。
  セーフ ビンは、信頼できるバイナリ ディレクトリ (システムのデフォルトとオプション) からも解決される必要があります。
  `tools.exec.safeBinTrustedDirs`)。 `PATH` エントリは自動信頼されません。
  デフォルトの信頼できるセーフ ビン ディレクトリは意図的に最小限になっています: `/bin`、`/usr/bin`。
  セーフ ビンの実行可能ファイルがパッケージ マネージャー/ユーザー パスに存在する場合 (たとえば、
  `/opt/homebrew/bin`、`/usr/local/bin`、`/opt/local/bin`、`/snap/bin`)、明示的に追加します。
  `tools.exec.safeBinTrustedDirs` まで。
  ホワイトリスト モードでは、シェル チェーンとリダイレクトは自動的に許可されません。すべての最上位セグメントが許可リストを満たす場合、シェル チェーン (`&&`、`||`、`;`) が許可されます。
  (金庫やスキルの自動許可を含む)。ホワイトリスト モードでは、リダイレクトは引き続きサポートされません。
  コマンド置換 (`$()` / バッククォート) は、内部を含むホワイトリストの解析中に拒否されます。
  二重引用符。リテラルの `$()` テキストが必要な場合は一重引用符を使用してください。
  macOS コンパニオン アプリの承認では、シェル コントロールまたは拡張構文を含む生のシェル テキスト
  (`&&`、`||`、`;`、`|`、` ` \`\`, `$`, `<**OC_I18N_0096**>`, `(`, `)`) は、次の場合を除き、ホワイトリスト ミスとして扱われます。
  シェル バイナリ自体はホワイトリストに登録されています。
  シェル ラッパー (`bash|sh|zsh ... -c/-lc`) の場合、リクエスト スコープの環境オーバーライドは、
  小規模な明示的な許可リスト (`TERM`、`LANG`、`LC\_\*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`)。
  ホワイトリスト モードでの常に許可の決定については、既知のディスパッチ ラッパー
  (`env`、`nice`、`nohup`、`stdbuf`、`timeout`) ラッパーの代わりに内部実行可能パスを保持します
  パス。シェル マルチプレクサ (`busybox`、`toybox`) もシェル アプレット (`sh`、`ash`、など）そのため、マルチプレクサーバイナリの代わりに内部実行可能ファイルが永続化されます。ラッパーや
  マルチプレクサを安全にラップ解除することはできず、許可リストのエントリは自動的に保持されません。

デフォルトの金庫: `jq`、`cut`、`uniq`、`head`、`tail`、`tr`、`wc`。

`grep` および `sort` はデフォルトのリストにありません。オプトインする場合は、明示的な許可リストのエントリを保持します。
非標準入力ワークフロー。
セーフビン モードの `grep` の場合は、パターンに `-e`/`--regexp` を指定します。位置パターンの形式は
ファイルオペランドがあいまいな位置指定として密輸できないように拒否される。

### 安全なビンと許可リスト|トピック | `tools.exec.safeBins` |許可リスト (`exec-approvals.json`) |

\| ---------------- | -------------------------------------------------------- | -------------------------------------------------------------- |
|目標 |狭い標準入力フィルターを自動的に許可する |特定の実行可能ファイルを明示的に信頼する |
|一致タイプ |実行可能ファイル名 + セーフビン argv ポリシー |解決された実行可能パスのグロブ パターン |
|引数の範囲 |セーフビン プロファイルとリテラル トークン ルールによる制限 |パス一致のみ。それ以外の場合、引数はあなたの責任です。
|代表的な例 | `jq`、`head`、`tail`、`wc` | `python3`、`node`、`ffmpeg`、カスタム CLI |
|ベストユース |パイプラインでの低リスクのテキスト変換 |より広範な動作または副作用を伴うツール |

設定場所:- `safeBins` は構成 (`tools.exec.safeBins` またはエージェントごとの `agents.list[].tools.exec.safeBins`) から取得されます。

* `safeBinTrustedDirs` は構成 (`tools.exec.safeBinTrustedDirs` またはエージェントごとの `agents.list[].tools.exec.safeBinTrustedDirs`) から取得されます。
* `safeBinProfiles` は構成 (`tools.exec.safeBinProfiles` またはエージェントごとの `agents.list[].tools.exec.safeBinProfiles`) から取得されます。エージェントごとのプロファイル キーはグローバル キーをオーバーライドします。
* ホワイトリスト エントリは、ホストローカルの `agents.<id>.allowlist` の下の `~/.openclaw/exec-approvals.json` (またはコントロール UI / `openclaw approvals allowlist ...` 経由) に存在します。
* `openclaw security audit` は、明示的なプロファイルなしでインタープリター/ランタイム ビンが `safeBins` に表示される場合、`tools.exec.safe_bins_interpreter_unprofiled` で警告します。
* `openclaw doctor --fix` は、欠落しているカスタム `safeBinProfiles.<bin>` エントリを `{}` としてスキャフォールディングできます (後で確認して修正します)。インタプリタ/ランタイム ビンは自動スキャフォールディングされません。

カスタムプロファイルの例:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    exec: {
      safeBins: ["jq", "myfilter"],
      safeBinProfiles: {
        myfilter: {
          minPositional: 0,
          maxPositional: 0,
          allowedValueFlags: ["-n", "--limit"],
          deniedFlags: ["-f", "--file", "-c", "--command"],
        },
      },
    },
  },
}
```

## コントロール UI の編集

**コントロール UI → ノード → 実行承認** カードを使用して、エージェントごとにデフォルトを編集します
オーバーライドと許可リスト。スコープ (デフォルトまたはエージェント) を選択し、ポリシーを微調整します。
ホワイトリスト パターンを追加/削除し、**保存**します。 UI には **最後に使用した** メタデータが表示されます
パターンごとに作成できるため、リストを整理しておくことができます。

ターゲット セレクターは、**ゲートウェイ** (ローカル承認) または **ノード** を選択します。ノード
`system.execApprovals.get/set` (macOS アプリまたはヘッドレス ノード ホスト) をアドバタイズする必要があります。
ノードが実行承認をまだアドバタイズしていない場合は、そのローカルを編集します
`~/.openclaw/exec-approvals.json` を直接。CLI: `openclaw approvals` は、ゲートウェイまたはノードの編集をサポートします ([承認 CLI](/cli/approvals) を参照)。

## 承認フロー

プロンプトが必要な場合、ゲートウェイはオペレーター クライアントに `exec.approval.requested` をブロードキャストします。
コントロール UI と macOS アプリは `exec.approval.resolve` 経由で問題を解決し、ゲートウェイは
ノードホストへの承認されたリクエスト。

`host=node` の場合、承認リクエストには正規の `systemRunPlan` ペイロードが含まれます。ゲートウェイが使用するのは、
承認された `system.run` を転送するときに権限のあるコマンド/cwd/セッション コンテキストとして計画する
リクエスト。

承認が必要な場合、実行ツールは承認 ID を即座に返します。その ID を使用して、
後のシステム イベント (`Exec finished` / `Exec denied`) を関連付けます。期限までに決定が下されない場合は、
タイムアウトになると、リクエストは承認タイムアウトとして扱われ、拒否理由として表示されます。

確認ダイアログには次の内容が含まれます。

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

アクション:

* **一度許可** → 今すぐ実行
* **常に許可** → 許可リストに追加して実行
* **拒否** → ブロック

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

実行承認プロンプトを任意のチャット チャネル (プラグイン チャネルを含む) に転送して承認できます。
`/approve` となります。これには、通常の送信配信パイプラインが使用されます。

構成:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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ピアチェック。
* チャレンジ/レスポンス (ノンス + HMAC トークン + リクエスト ハッシュ) + 短い TTL。

## システムイベント

Exec ライフサイクルはシステム メッセージとして表示されます。

* `Exec running` (コマンドが実行通知しきい値を超えた場合のみ)
* `Exec finished`
* `Exec denied`

これらは、ノードがイベントを報告した後、エージェントのセッションにポストされます。
ゲートウェイ ホストの実行承認は、コマンドの終了時 (およびオプションでしきい値を超えて実行されているとき) に同じライフサイクル イベントを発行します。
承認ゲート型幹部は、関連付けを容易にするために、これらのメッセージ内で承認 ID を `runId` として再利用します。

## 影響

* **フル**は強力です。可能であればホワイトリストを優先します。
* **ask** により、迅速な承認を可能にしながら、最新情報を常に把握できます。
* エージェントごとの許可リストにより、あるエージェントの承認が他のエージェントに漏洩するのを防ぎます。
* 承認は、**承認された送信者**からのホスト実行リクエストにのみ適用されます。不正な送信者は `/exec` を発行できません。
* `/exec security=full` は、承認されたオペレーターにとってセッションレベルの利便性を提供し、設計により承認をスキップします。
  ホスト実行をハードブロックするには、承認セキュリティを `deny` に設定するか、ツール ポリシーで `exec` ツールを拒否します。

関連:

* [実行ツール](/tools/exec)
* [昇格モード](/tools/elevated)
* [スキル](/tools/skills)