Exec approvals でエージェントのコマンド実行を安全に制御する

エージェントにローカルマシンの操作を任せるとき、意図しないコマンドが実行されないか不安になることはありませんか？サンドボックス化されたエージェントが実際のホスト環境にアクセスする場合、利便性と安全性のバランスを取ることが重要です。

Exec approvals は、安全装置（インターロック）のようなものだと考えてください。ポリシー、ホワイトリスト、ユーザーの承認がすべて一致したときのみ、コマンドの実行が許可されます。

必要なもの

Gateway ホスト（openclaw プロセスが動作しているマシン）
Node ホスト（macOS companion app または headless node host）

クイックスタート

Exec approvals は、実行ホスト上のローカル JSON ファイル（~/.openclaw/exec-approvals.json）で管理されます。設定は以下のステップで完了します。

設定ファイルを作成、または編集します。
デフォルトのセキュリティ挙動（defaults）を定義します。
必要に応じて、特定のエージェント（agents）に対して個別のルールやホワイトリストを設定します。
有効なポリシーは、tools.exec.* と approvals のデフォルト設定のうち、より制限の厳しい方が適用されます。

{
  "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"
        }
      ]
    }
  }
}

トラブルシューティング

Companion app の UI が利用できない: プロンプトが必要なリクエストが発生しても UI が表示できない場合は、ask fallback の設定に従って解決されます。デフォルトは deny（拒否）です。
承認後に実行内容が変わってしまった: 承認から実行までの間にスクリプトの内容が変更された場合、実行は拒否されます。これは、承認時と異なる内容が実行される「ドリフト」を防ぐための仕組みです。

セットアップに関する具体的な質問がある場合は、AI Setup Assistant を活用してください。

次のステップ

Gateway configuration
Node setup guide
Tool policy reference
Security trust model

---
title: "Policy knobs で実行権限をスマートに管理する"
description: "セキュリティと利便性のバランスを調整するための Policy knobs 設定ガイド"
---

開発をしていると、スクリプトやバイナリの実行権限をどう扱うか迷う場面があります。セキュリティをガチガチに固めると作業の手が止まってしまい、逆に緩すぎると予期せぬ実行が不安になります。

このバランスをうまく調整して、自分の環境に合わせた最適な実行ルールを作るための設定を見ていきましょう。

## 必要なもの

- macOS app
- Gateway
- 設定対象となる Agent
- 実行したいバイナリのパス

## クイックスタート

最短で設定を完了させるための 4 つのステップです。

1. **セキュリティレベルの選択**: `exec.security` を `allowlist` に設定します。
2. **確認プロンプトの設定**: `exec.ask` を `on-miss` に設定して、リストにない時だけ確認するようにします。
3. **Allowlist の編集**: macOS app で対象の Agent を選び、許可するバイナリのパスを登録します。
4. **フォールバックの決定**: UI が表示できない場合の挙動を `askFallback` で指定します。

## Policy knobs の詳細

設定の核となる 3 つの項目について説明します。

### Security (`exec.security`)

実行リクエストをどのように扱うかを決めます。

- **deny**: すべてのホスト実行リクエストをブロックします。
- **allowlist**: Allowlist に登録されたコマンドのみを許可します。
- **full**: すべてを許可します（elevated と同等です）。

### Ask (`exec.ask`)

ユーザーへの確認プロンプトを出すタイミングを制御します。

- **off**: プロンプトを表示しません。
- **on-miss**: Allowlist に一致しない場合のみプロンプトを表示します。
- **always**: すべてのコマンド実行時にプロンプトを表示します。

### Ask fallback (`askFallback`)

プロンプトが必要なのに UI に接続できない（ headless 環境など）場合の挙動を決めます。

- **deny**: ブロックします。
- **allowlist**: Allowlist に一致する場合のみ許可します。
- **full**: 許可します。

## Allowlist の管理

Allowlist は **Agent ごと**に設定されます。複数の Agent がある場合は、macOS app 内で編集する Agent を切り替えてください。

パターン指定には、**ケースインセンシティブ（大文字小文字を区別しない）な glob マッチ**が使用されます。注意点として、エントリは必ず**バイナリのパス**である必要があります（ファイル名のみの basename エントリは無視されます）。

また、古い `agents.default` のエントリは、ロード時に `agents.main` へ自動的に移行されます。

**設定例:**

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

各エントリでは以下の情報を保持しています。

- **id**: UI 識別用の固定 UUID（オプション）
- **last used**: 最終使用タイムスタンプ
- **last used command**: 最後に実行されたコマンド
- **last resolved path**: 最後に解決されたパス

## Auto-allow skill CLIs

**Auto-allow skill CLIs** を有効にすると、既知の Skill が参照する実行ファイルが、ノード（macOS ノードまたは headless ノード）上で自動的に許可されます。これは Gateway RPC を介して `skills.bins` を取得し、リストを構築する仕組みです。

手動での管理を徹底したい場合は、この機能を無効にしてください。

**信頼に関する注意点:**

- これは利便性のための**暗黙的な許可リスト**であり、手動のパス指定リストとは別に管理されます。
- Gateway とノードが同じ信頼境界内にある運用環境を想定しています。
- 厳格な明示的信頼が必要な場合は、`autoAllowSkills: false` に設定し、手動の Allowlist のみを使用してください。

## トラブルシューティング

- **Allowlist に追加したのに実行されない**: 指定したパスがフルパス（または glob）になっているか確認してください。ファイル名（basename）だけの指定は無視されます。
- **UI がない環境で実行が拒否される**: `askFallback` が `deny` になっていないか確認してください。UI が表示できない状況では、この設定が優先されます。

困ったときは [AI Setup Assistant](/docs/#docs-chat) も活用してみてください。

## 次のステップ

- [Security 設定の詳細](/docs/#security)
- [Agent の構成ガイド](/docs/#agents)
- [Gateway RPC リファレンス](/docs/#gateway-rpc)
- [Skill のバイナリ管理](/docs/#skill-bins)

---
title: "Safe bins (stdin-only): 標準入力専用バイナリでセキュリティと効率を両立する"
description: "セキュリティを損なうことなく、jqやwcなどのテキスト処理ツールをスムーズに実行するためのSafe bins設定ガイドです。"
---

開発ツールやエージェントにコマンド実行を許可する際、すべての操作に対して手動で承認ボタンを押すのは、作業のフローを止めてしまう原因になります。かといって、すべてのコマンドを無条件に許可するのはセキュリティ上のリスクが大きすぎます。特に `jq` で JSON を整形したり、`wc` で行数を数えたりするだけの単純なパイプライン処理において、このバランスをどう取るべきか悩んでいる方は多いのではないでしょうか。

## 必要なもの
設定を始める前に、以下の環境が整っていることを確認してください。

- `tools.exec.safeBins` の設定が可能な設定ファイル（グローバルまたはエージェント単位）
- `~/.openclaw/exec-approvals.json`（明示的な allowlist 用）
- `/bin` または `/usr/bin` にインストールされた標準的なバイナリ

## クイックスタート
5分で Safe bins を有効化し、標準入力（stdin）専用のフィルタとして利用する方法を説明します。

1. **デフォルトの Safe bins を確認する**
   デフォルトでは `jq`, `cut`, `uniq`, `head`, `tail`, `tr`, `wc` が Safe bins として定義されています。これらは allowlist に個別のエントリを追加しなくても、標準入力のみを扱う場合に限り自動で実行が許可されます。

2. **カスタム Safe bin を追加する**
   独自のリスクの低いフィルタを追加したい場合は、設定ファイルに記述します。

```json
{
  tools: {
    exec: {
      // 既存のリストに "myfilter" を追加
      safeBins: ["jq", "myfilter"],
      safeBinProfiles: {
        myfilter: {
          minPositional: 0,
          maxPositional: 0,
          allowedValueFlags: ["-n", "--limit"],
          deniedFlags: ["-f", "--file", "-c", "--command"],
        },
      },
    },
  },
}

実行を確認する Safe bins はファイルパスを引数に取ることを禁止しています。必ずパイプ経由などで標準入力を渡してください。

Safe bins の仕組みと制限事項

Safe bins は「標準入力のみを受け付ける」バイナリに限定された高速パスです。これを一般的な信頼リスト（Trust list）として扱わないでください。

重要なセキュリティルール

インタプリタの禁止: python3, node, ruby, bash, sh, zsh などのランタイムを safeBins に追加しないでください。コードを評価したり、サブコマンドを実行したりできるツールは、明示的な allowlist で管理する必要があります。
ファイル引数の拒否: 位置引数としてのファイルパスや、パスのようなトークンは拒否されます。
リテラルテキストの強制: * によるグロブ展開や $VARS による環境変数展開は行われません。これらは実行時にリテラル（そのままの文字）として扱われます。
信頼されたディレクトリ: バイナリは /bin または /usr/bin から解決される必要があります。PATH 環境変数のエントリが自動的に信頼されることはありません。他のパス（/opt/homebrew/bin など）を使用する場合は、tools.exec.safeBinTrustedDirs に追加してください。

Safe bins と Allowlist の違い

項目	`tools.exec.safeBins`	Allowlist (`exec-approvals.json`)
目的	標準入力フィルタの自動許可	特定の実行ファイルの明示的な信頼
一致タイプ	実行ファイル名 + argv ポリシー	解決された実行ファイルパスのグロブ
引数の範囲	プロファイルとリテラル規則で制限	パスの一致のみ（引数はユーザー責任）
具体例	`jq`, `head`, `tail`, `wc`	`python3`, `node`, `ffmpeg`, カスタム CLI

使用が禁止されているフラグ

Safe bins モードでは、ファイル読み込みや副作用を誘発する以下のフラグは拒否されます。

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

トラブルシューティング

`grep` や `sort` が動作しない

grep と sort はデフォルトの Safe bins リストに含まれていません。これらを使用する場合は、明示的に opt-in する必要があります。また、grep を Safe bins モードで使う際は、パターンを -e または --regexp で指定してください。位置引数でパターンを指定すると、ファイル引数と区別がつかないため拒否されます。

信頼されていないディレクトリというエラーが出る

バイナリが /usr/local/bin や Homebrew のパスにある場合、デフォルトでは拒否されます。設定ファイルで以下のようにパスを追加してください。 tools.exec.safeBinTrustedDirs: ["/opt/homebrew/bin", "/usr/local/bin"]

設定が正しいか確認したい

openclaw security audit を実行してください。インタプリタがプロファイルなしで safeBins に含まれている場合に警告を表示します。また、openclaw doctor --fix を使うと、不足している safeBinProfiles の雛形を生成できます。

さらに詳しい設定方法やトラブルシューティングについては、AI Setup Assistant で質問してください。

次のステップ

```mdx
---
title: Control UIで実行承認（Exec Approvals）を管理する
description: エージェントの実行承認ポリシーやホワイトリストをControl UIから直接編集し、安全な実行環境を構築する方法を解説します。
---

エージェントにコマンドを実行させる際、何でも許可するのは不安ですし、かといって毎回手動で設定ファイルを書き換えるのも面倒ですよね。セキュリティを確保しながら、開発のフローを止めないように設定を管理するのは、多くの開発者が直面する課題です。

Control UIを使えば、実行承認のポリシーを直感的に管理できます。どのコマンドを自動で許可し、どの操作に確認が必要かを一箇所でコントロールできるため、安全で効率的な環境を整えることができます。

### What You'll Need

設定を始める前に、ソースドキュメントに記載されている以下の条件を確認してください。

- Control UIへのアクセス権限
- `system.execApprovals.get/set` をアドバタイズしている Node（macOS app または headless node host）
- 必要に応じて `~/.openclaw/exec-approvals.json` ファイルへの直接アクセス（Nodeがアドバタイズしていない場合）

### Quick Start

5分で実行承認の設定を更新する手順は以下の通りです。

1. **Control UI → Nodes → Exec approvals** カードを開きます。
2. 編集したいスコープ（Defaults または特定の agent）を選択します。
3. ポリシーを調整し、allowlist（ホワイトリスト）のパターンを追加または削除します。
4. **Save** をクリックして変更を適用します。

UIにはパターンごとの **last used**（最終使用日）メタデータが表示されるため、使われていない古いパターンを特定してリストを整理するのに役立ちます。

ターゲットセレクターでは、**Gateway**（ローカル承認）または **Node** を選択して編集できます。もし Node がまだ exec approvals をアドバタイズしていない場合は、その Node の `~/.openclaw/exec-approvals.json` を直接編集してください。

CLIで操作したい場合は、`openclaw approvals` コマンドを使用することで Gateway または Node の編集が可能です。詳細は [Approvals CLI](/docs/cli/approvals) を確認してください。

### 承認フローの仕組み

承認が必要なプロンプトが発生すると、Gateway は `exec.approval.requested` をオペレータークライアントにブロードキャストします。Control UI や macOS app が `exec.approval.resolve` を通じてこれを解決すると、Gateway は承認されたリクエストを Node ホストに転送します。

`host=node` の場合、承認リクエストには `systemRunPlan` ペイロードが含まれます。Gateway は、承認された `system.run` リクエストを転送する際、このプランをコマンド、cwd（カレントディレクトリ）、セッションコンテキストの正式な情報として使用します。

承認が必要な場合、exec tool はすぐに approval id を返します。この ID を使用して、後続のシステムイベント（`Exec finished` または `Exec denied`）を紐付けることができます。タイムアウトまでに決定が行われない場合は、承認タイムアウトとして処理され、拒否（denial）として扱われます。

確認ダイアログには、判断に必要な以下の情報が表示されます。

- command + args
- cwd
- agent id
- 解決された実行ファイルのパス
- host + policy メタデータ

選択できるアクションは以下の通りです。

- **Allow once**: 今回のみ実行を許可します。
- **Always allow**: allowlist に追加し、今回および今後の実行を許可します。
- **Deny**: 実行をブロックします。

### Troubleshooting

**Node が exec approvals をアドバタイズしていない**
Node が `system.execApprovals.get/set` をアドバタイズしていない場合、UIから設定を変更できません。この場合は、対象 Node の `~/.openclaw/exec-approvals.json` を直接編集して対応してください。

**リクエストがタイムアウトして拒否される**
設定されたタイムアウト時間内に承認または拒否の判断が行われなかった場合、リクエストは自動的に拒否されます。approval id を使用して、イベントログで `Exec denied` の詳細を確認してください。

不明な点がある場合は、[AI Setup Assistant](/docs/#docs-chat) に質問してみてください。

### What's Next
- [Approvals CLI](/docs/cli/approvals)

開発の作業中に承認プロンプトが表示され、そのたびに作業画面を切り替えるのは、集中力が削がれる原因になりますよね。わざわざ特定の UI を開かなくても、普段使っているチャットツールからサクッと承認できれば、開発の流れを止めずに作業を続けられます。

今回は、exec の承認プロンプトをチャットチャネルに転送し、チャット上で直接コマンドを実行・承認する方法を紹介します。

必要なもの

この機能を設定するには、以下のコンポーネントと環境が必要です。

Gateway
Node Service
Mac App (macOS を使用する場合)
Slack, Telegram, Discord などのチャットツールのアカウント

クイックスタート

設定はシンプルです。5 分ほどで完了します。

1. 設定ファイルの編集

approvals セクションを以下のように設定します。mode や targets を環境に合わせて書き換えてください。

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session", // "session" | "targets" | "both"
      agentFilter: ["main"],
      sessionFilter: ["discord"], // 部分一致または正規表現
      targets: [
        { channel: "slack", to: "U12345678" },
        { channel: "telegram", to: "123456789" },
      ],
    },
  },
}

2. チャットからの操作

プロンプトがチャットに届いたら、以下のコマンドを返信するだけで操作が可能です。

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

macOS での動作の仕組み

macOS では、以下のフローで IPC（プロセス間通信）が行われます。

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + approvals + system.run)

トラブルシューティング

設定や実行時に問題が発生した場合は、以下のセキュリティ要件を確認してください。

承認リクエストが届かない・失敗する:
- Unix socket のモードが 0600 になっているか確認してください。
- トークンが exec-approvals.json に正しく保存されている必要があります。
- 通信相手が同じ UID のピアであるかチェックが行われます。
- チャレンジ/レスポンス（nonce + HMAC トークン + リクエストハッシュ）と短い TTL が設定されているため、タイムアウトに注意してください。
/exec コマンドが反応しない:
- 承認は、許可された送信者からのリクエストにのみ適用されます。権限のない送信者は /exec を発行できません。

運用のポイント

この機能を安全に使うためのヒントです。

セキュリティ設定の選択: full 設定は非常に強力です。可能な限り allowlist（許可リスト）を使用することをおすすめします。
状況の把握: ask モードを使えば、作業の流れを止めずに素早く承認しつつ、何が起きているかを常に把握できます。
情報の分離: エージェントごとに allowlist を設定することで、あるエージェントの承認情報が他のエージェントに漏れるのを防げます。
実行のブロック: ホストでの実行を完全に禁止したい場合は、承認のセキュリティを deny に設定するか、ツールポリシーで exec ツール自体を拒否してください。なお、/exec security=full はオペレーター向けの利便性のため、承認をスキップするように設計されています。

システムイベントの通知

実行のライフサイクルは、システムメッセージとしてエージェントのセッションに投稿されます。

Exec running（実行時間がしきい値を超えた場合のみ）
Exec finished
Exec denied

承認が必要な実行では、承認 ID が runId として再利用されるため、ログの紐付けも簡単です。

設定の詳細や具体的なトラブルの相談は、AI Setup Assistant でいつでも質問してください。

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。

Exec approvals でエージェントのコマンド実行を安全に制御する

必要なもの

クイックスタート

トラブルシューティング

次のステップ

Safe bins の仕組みと制限事項

重要なセキュリティルール

Safe bins と Allowlist の違い

使用が禁止されているフラグ

トラブルシューティング

grep や sort が動作しない

信頼されていないディレクトリというエラーが出る

設定が正しいか確認したい

次のステップ

必要なもの

クイックスタート

1. 設定ファイルの編集

2. チャットからの操作

macOS での動作の仕組み

トラブルシューティング

運用のポイント

システムイベントの通知

次のステップ

まだ解決しませんか？

`grep` や `sort` が動作しない