コマンド実行ツールと承認

学習後の目標

3つの実行モード（sandbox/gateway/node）でexecツールを設定する
セキュリティ承認仕組み（deny/allowlist/full）を理解して設定する
許可リスト（Allowlist）とセキュアなbinsを管理する
UIまたはチャットチャネル経由でexecリクエストを承認する
execツールの一般的な問題とセキュリティエラーをトラブルシューティングする

現在の課題

execツールはAIアシスタントがシェルコマンドを実行できるようにしますが、これは強力でありながら危険でもあります：

AIがシステム上の重要なファイルを削除するのではないか？
AIが安全なコマンドのみを実行するように制限するには？
さまざまな実行モードの違いは何か？
承認フローはどのように動作するのか？
許可リストはどのように設定すればよいのか？

いつ使用すべきか

AIにシステム操作（ファイル管理、コードビルドなど）を実行させたい場合
AIにカスタムスクリプトやツールを呼び出させたい場合
AIの実行権限を細かく制御する必要がある場合
特定のコマンドを安全に許可する必要がある場合

🎒 開始前の準備

前提条件

このチュートリアルは、Gatewayの起動が完了しており、Gatewayデーモンが実行中であることを前提としています。

Node ≥22 がインストールされていることを確認
Gatewayデーモンが実行中であること
基本的なシェルコマンドとLinux/Unixファイルシステムの知識

コアコンセプト

Execツールの3層セキュリティ保護

execツールは、粗粒度から細粒度までの3層のセキュリティ仕組みを採用し、AIの実行権限を制御します：

ツールポリシー（Tool Policy）：tools.policyでexecツールの許可を制御
実行ホスト（Host）：コマンドはsandbox/gateway/nodeの3つの環境で実行
承認仕組み（Approvals）：gateway/nodeモードでは、allowlistと承認プロンプトでさらに制限可能

なぜ多層保護が必要なのか？

単層の保護はバイパスや設定ミスを引き起こしやすいです。多層保護により、ある層が機能しなくても他の層が保護を提供します。

3つの実行モードの比較

実行モード	実行場所	セキュリティレベル	典型的なユースケース	承認が必要
sandbox	コンテナ内（Dockerなど）	高	分離環境、テスト	いいえ
gateway	Gatewayデーモンが動作するマシン	中	ローカル開発、統合	はい（allowlist + 承認）
node	ペアリングされたデバイスノード（macOS/iOS/Android）	中	デバイスローカル操作	はい（allowlist + 承認）

重要な違い：

sandboxモードはデフォルトで承認が不要（ただしSandboxの制限を受ける可能性あり）
gatewayとnodeモードはデフォルトで承認が必要（fullに設定しない限り）

さあ、やってみよう

ステップ1：execツールのパラメータを理解する

なぜ execツールのパラメータを理解することは、セキュリティ設定の基礎です。

execツールは以下のパラメータをサポートします：

json

{
  "tool": "exec",
  "command": "ls -la",
  "workdir": "/path/to/dir",
  "env": { "NODE_ENV": "production" },
  "yieldMs": 10000,
  "background": false,
  "timeout": 1800,
  "pty": false,
  "host": "sandbox",
  "security": "allowlist",
  "ask": "on-miss",
  "node": "mac-1"
}

パラメータ説明：

パラメータ	タイプ	デフォルト値	説明
`command`	string	必須	実行するシェルコマンド
`workdir`	string	現在の作業ディレクトリ	実行ディレクトリ
`env`	object	環境を継承	環境変数の上書き
`yieldMs`	number	10000	タイムアウト後に自動的にバックグラウンドへ（ミリ秒）
`background`	boolean	false	即座にバックグラウンド実行
`timeout`	number	1800	実行タイムアウト（秒）
`pty`	boolean	false	擬似端末で実行（TTYサポート）
`host`	string	sandbox	実行ホスト：`sandbox` \| `gateway` \| `node`
`security`	string	deny/allowlist	セキュリティポリシー：`deny` \| `allowlist` \| `full`
`ask`	string	on-miss	承認ポリシー：`off` \| `on-miss` \| `always`
`node`	string	-	nodeモードのターゲットノードIDまたは名前

確認すべき点：パラメータリストは各実行モードの制御方法を明確に説明しています。

ステップ2：デフォルトの実行モードを設定する

なぜ設定ファイルでグローバルデフォルト値を設定することで、exec呼び出しごとにパラメータを指定する必要がなくなります。

~/.clawdbot/clawdbot.jsonを編集：

json

{
  "tools": {
    "exec": {
      "host": "sandbox",
      "security": "allowlist",
      "ask": "on-miss",
      "node": "mac-1",
      "notifyOnExit": true,
      "approvalRunningNoticeMs": 10000,
      "pathPrepend": ["~/bin", "/opt/homebrew/bin"],
      "safeBins": ["jq", "grep", "cut"]
    }
  }
}

設定項目の説明：

設定項目	タイプ	デフォルト値	説明
`host`	string	sandbox	デフォルトの実行ホスト
`security`	string	deny (sandbox) / allowlist (gateway, node)	デフォルトのセキュリティポリシー
`ask`	string	on-miss	デフォルトの承認ポリシー
`node`	string	-	nodeモードのデフォルトノード
`notifyOnExit`	boolean	true	バックグラウンドタスク終了時にシステムイベントを送信
`approvalRunningNoticeMs`	number	10000	タイムアウト後に「実行中」通知を送信（0で無効）
`pathPrepend`	string[]	-	PATHに追加するディレクトリリスト
`safeBins`	string[]	[デフォルトリスト]	セキュアなバイナリリスト（stdin操作のみ）

確認すべき点：設定を保存すると、execツールはこれらのデフォルト値を使用します。

ステップ3：`/exec`セッションオーバーライドを使用する

なぜセッションオーバーライドにより、設定ファイルを編集せずに一時的に実行パラメータを調整できます。

チャットで送信：

/exec host=gateway security=allowlist ask=on-miss node=mac-1

現在のオーバーライド値を確認：

/exec

確認すべき点：現在のセッションのexecパラメータ設定が表示されます。

ステップ4：許可リスト（Allowlist）を設定する

なぜ allowlistはgateway/nodeモードの中核となるセキュリティ仕組みであり、特定のコマンドのみを許可します。

allowlistを編集する

UIで編集：

Control UIを開く
Nodesタブに移動
Exec approvalsカードを見つける
ターゲット（GatewayまたはNode）を選択
Agentを選択（例：main）
Add patternをクリックしてコマンドパターンを追加
Saveをクリックして保存

CLIで編集：

bash

clawdbot approvals

JSONファイルで編集：

~/.clawdbot/exec-approvals.jsonを編集：

json

{
  "version": 1,
  "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/*",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/bin/rg"
        },
        {
          "id": "C1D9D1C4-3D3E-5F9B-0B4D-6B5C4D3E2F1G",
          "pattern": "/opt/homebrew/bin/rg",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg test",
          "lastResolvedPath": "/opt/homebrew/bin/rg"
        }
      ]
    }
  }
}

Allowlistモードの説明：

allowlistはglobパターンマッチング（大文字小文字を区別しない）を使用します：

パターン	マッチ	説明
`~/Projects/*/bin/`	`/Users/user/Projects/any/bin/rg`	すべてのサブディレクトリにマッチ
`~/.local/bin/*`	`/Users/user/.local/bin/jq`	ローカルbinにマッチ
`/opt/homebrew/bin/rg`	`/opt/homebrew/bin/rg`	絶対パスにマッチ

重要なルール

解決されたバイナリパスのみマッチ、basenameマッチ（rgなど）はサポートされません
シェル連結（&&、||、;）は各セグメントがallowlistを満たす必要があります
リダイレクト（>、<）はallowlistモードではサポートされていません

確認すべき点：allowlistを設定すると、マッチするコマンドのみを実行できます。

ステップ5：セキュアなbins（Safe Bins）を理解する

なぜセキュアなbinsはstdin操作のみをサポートする安全なバイナリのセットであり、allowlistモードで明示的なallowlistなしで使用できます。

デフォルトのセキュアなbins：

jq、grep、cut、sort、uniq、head、tail、tr、wc

セキュアなbinのセキュリティ特性：

位置ファイル引数を拒否
パスライクフラグを拒否
入力ストリーム（stdin）のみ操作可能

カスタムセキュアなbinsを設定：

json

{
  "tools": {
    "exec": {
      "safeBins": ["jq", "grep", "my-safe-tool"]
    }
  }
}

確認すべき点：セキュアなbinsのコマンドはallowlistモードで直接実行できます。

ステップ6：チャットチャネル経由でexecリクエストを承認する

なぜ UIが利用できない場合、任意のチャットチャネル（WhatsApp、Telegram、Slackなど）経由でexecリクエストを承認できます。

承認転送を有効にする

~/.clawdbot/clawdbot.jsonを編集：

json

{
  "approvals": {
    "exec": {
      "enabled": true,
      "mode": "session",
      "agentFilter": ["main"],
      "sessionFilter": ["discord"],
      "targets": [
        { "channel": "slack", "to": "U12345678" },
        { "channel": "telegram", "to": "123456789" }
      ]
    }
  }
}

設定項目の説明：

設定項目	説明
`enabled`	exec承認転送を有効にするかどうか
`mode`	`"session"` \| `"targets"` \| `"both"` - 承認ターゲットモード
`agentFilter`	特定のエージェントの承認リクエストのみ処理
`sessionFilter`	セッションフィルタ（substringまたはregex）
`targets`	ターゲットチャネルリスト（`channel` + `to`）

リクエストを承認する

execツールが承認を必要とする場合、以下の情報を含むメッセージが届きます：

Exec approval request (id: abc-123)
Command: ls -la
CWD: /home/user
Agent: main
Resolved: /usr/bin/ls
Host: gateway
Security: allowlist

承認オプション：

/approve abc-123 allow-once     # 1回のみ許可
/approve abc-123 allow-always    # 常に許可（allowlistに追加）
/approve abc-123 deny           # 拒否

確認すべき点：承認後、コマンドが実行されるか拒否されます。

チェックポイント ✅

[ ] 3つの実行モード（sandbox/gateway/node）の違いを理解している
[ ] グローバルなexecデフォルトパラメータを設定した
[ ] /execコマンドのセッションオーバーライドを使用できる
[ ] allowlistを設定した（少なくとも1つのパターン）
[ ] セキュアなbinsのセキュリティ特性を理解している
[ ] チャットチャネル経由でexecリクエストを承認できる

よくある落とし穴

一般的なエラー

エラー	原因	解決方法
`Command not allowed by exec policy`	`security=deny`またはallowlistが一致しない	`tools.exec.security`とallowlist設定を確認
`Approval timeout`	UIが利用不可、`askFallback=deny`	`askFallback=allowlist`を設定またはUIを有効化
`Pattern does not resolve to binary`	allowlistモードでbasenameを使用	完全パスを使用（例：`/opt/homebrew/bin/rg`）
`Unsupported shell token`	allowlistモードで`>`または`&&`を使用	コマンドを分割または`security=full`を使用
`Node not found`	nodeモードでノードがペアリングされていない	まずノードペアリングを完了

シェル連結とリダイレクト

警告

security=allowlistモードでは、以下のシェル機能はサポートされません：

パイプ：|（ただし||はサポート）
リダイレクト：>、<、>>
コマンド置換：$()、` `
バックグラウンド：&、;

解決方法：

security=fullを使用（慎重に）
複数のexec呼び出しに分割
ラッパースクリプトを作成し、スクリプトパスをallowlistに追加

PATH環境変数

実行モードによってPATHの処理方法が異なります：

実行モード	PATH処理	説明
`sandbox`	シェルログインを継承、`/etc/profile`でリセットされる可能性	`pathPrepend`はprofileの後に適用
`gateway`	ログインシェルPATHをexec環境にマージ	デーモンは最小PATHを保持、execはユーザーPATHを継承
`node`	渡された環境変数オーバーライドのみ使用	macOSノードは`PATH`オーバーライドを破棄、headlessノードはprependをサポート

確認すべき点：PATHの設定が正しくコマンド検索に影響します。

まとめ

execツールは3層の保護仕組み（ツールポリシー、実行ホスト、承認）により、AIアシスタントがシェルコマンドを安全に実行できるようにします：

実行モード：sandbox（コンテナ分離）、gateway（ローカル実行）、node（デバイス操作）
セキュリティポリシー：deny（完全禁止）、allowlist（許可リスト）、full（完全許可）
承認仕組み：off（プロンプトなし）、on-miss（未一致時プロンプト）、always（常にプロンプト）
許可リスト：globパターンで解決されたバイナリパスをマッチ
セキュアなbins：stdin操作のみのバイナリはallowlistモードで承認不要

次のレッスン予告

次のレッスンでは、**Web検索とスクレイピングツール**を学習します
学ぶ内容：
web_searchツールを使用してWeb検索を行う方法
web_fetchツールを使用してWebページコンテンツをスクレイピングする方法
検索エンジンプロバイダー（Brave、Perplexity）を設定する方法
検索結果とWebスクレイピングエラーを処理する方法

付録：ソースコード参照

クリックしてソースコードの場所を展開

更新日：2026-01-27

機能	ファイルパス	行番号
execツール定義	`src/agents/bash-tools.exec.ts`	1-500+
exec承認ロジック	`src/infra/exec-approvals.ts`	1-1268
シェルコマンド分析	`src/infra/exec-approvals.ts`	500-1100
Allowlistマッチ	`src/infra/exec-approvals.ts`	507-521
Safe bins検証	`src/infra/exec-approvals.ts`	836-873
承認Socket通信	`src/infra/exec-approvals.ts`	1210-1267
プロセス実行	`src/process/exec.ts`	1-125
ツール設定Schema	`src/config/zod-schema.core.ts`	-

重要なタイプ：

ExecHost: "sandbox" \| "gateway" \| "node" - 実行ホストタイプ
ExecSecurity: "deny" \| "allowlist" \| "full" - セキュリティポリシー
ExecAsk: "off" \| "on-miss" \| "always" - 承認ポリシー
ExecAllowlistEntry: allowlistエントリタイプ（pattern、lastUsedAtなどを含む）

重要な定数：

DEFAULT_SECURITY = "deny" - デフォルトのセキュリティポリシー
DEFAULT_ASK = "on-miss" - デフォルトの承認ポリシー
DEFAULT_SAFE_BINS = ["jq", "grep", "cut", "sort", "uniq", "head", "tail", "tr", "wc"] - デフォルトのセキュアなbins

重要な関数：

resolveExecApprovals(): exec-approvals.json設定を解析
evaluateShellAllowlist(): シェルコマンドがallowlistを満たすか評価
matchAllowlist(): コマンドパスがallowlistパターンとマッチするか確認
isSafeBinUsage(): コマンドがセキュアなbinの使用か検証
requestExecApprovalViaSocket(): Unixソケット経由で承認をリクエスト

ゼロから始める

一般的なチャットツールへの接続

AI の超能力をアンロック

問題が発生したら

コマンド実行ツールと承認

学習後の目標

現在の課題

いつ使用すべきか

🎒 開始前の準備

コアコンセプト

Execツールの3層セキュリティ保護

3つの実行モードの比較

さあ、やってみよう

ステップ1：execツールのパラメータを理解する

ステップ2：デフォルトの実行モードを設定する

ステップ3：`/exec`セッションオーバーライドを使用する

ステップ4：許可リスト（Allowlist）を設定する

allowlistを編集する

ステップ5：セキュアなbins（Safe Bins）を理解する

ステップ6：チャットチャネル経由でexecリクエストを承認する

承認転送を有効にする

リクエストを承認する

チェックポイント ✅

よくある落とし穴

一般的なエラー

シェル連結とリダイレクト

PATH環境変数

まとめ

次のレッスン予告

付録：ソースコード参照

コマンド実行ツールと承認 ​

学習後の目標 ​

現在の課題 ​

いつ使用すべきか ​

🎒 開始前の準備 ​

コアコンセプト ​

Execツールの3層セキュリティ保護 ​

3つの実行モードの比較 ​

さあ、やってみよう ​

ステップ1：execツールのパラメータを理解する ​

ステップ2：デフォルトの実行モードを設定する ​

ステップ3：/execセッションオーバーライドを使用する ​

ステップ4：許可リスト（Allowlist）を設定する ​

allowlistを編集する ​

ステップ5：セキュアなbins（Safe Bins）を理解する ​

ステップ6：チャットチャネル経由でexecリクエストを承認する ​

承認転送を有効にする ​

リクエストを承認する ​

チェックポイント ✅ ​

よくある落とし穴 ​

一般的なエラー ​

シェル連結とリダイレクト ​

PATH環境変数 ​

まとめ ​

次のレッスン予告 ​

付録：ソースコード参照 ​

コマンド実行ツールと承認

学習後の目標

現在の課題

いつ使用すべきか

🎒 開始前の準備

コアコンセプト

Execツールの3層セキュリティ保護

3つの実行モードの比較

さあ、やってみよう

ステップ1：execツールのパラメータを理解する

ステップ2：デフォルトの実行モードを設定する

ステップ3：`/exec`セッションオーバーライドを使用する

ステップ4：許可リスト（Allowlist）を設定する

allowlistを編集する

ステップ5：セキュアなbins（Safe Bins）を理解する

ステップ6：チャットチャネル経由でexecリクエストを承認する

承認転送を有効にする

リクエストを承認する

チェックポイント ✅

よくある落とし穴

一般的なエラー

シェル連結とリダイレクト

PATH環境変数

まとめ

次のレッスン予告

付録：ソースコード参照