Exec Tool

​

パラメータ

• command (必須)
• workdir (デフォルトは cwd)
• env (キー/値の上書き)
• yieldMs (デフォルト 10000): 遅延後の自動背景
• background (ブール値): すぐにバックグラウンドにします
• timeout (秒、デフォルトは 1800): 期限切れで強制終了
• pty (ブール値): 利用可能な場合は疑似端末で実行します (TTY のみの CLI、コーディング エージェント、端末 UI)
• host (sandbox | gateway | node): 実行場所
• security (deny | allowlist | full): gateway/node の強制モード
• ask (off | on-miss | always): gateway/node の承認プロンプト
• node (文字列): host=node のノード ID/名前
• elevated (ブール値): 昇格モードを要求します (ゲートウェイ ホスト)。 security=full は、昇格が full に解決される場合にのみ強制されます。

• サンドボックスがオフの場合 (ホスト上で実行がすでに実行されている場合)、elevated は無視されます。
• gateway/node の承認は ~/.openclaw/exec-approvals.json によって制御されます。
• node にはペアリングされたノード (コンパニオン アプリまたはヘッドレス ノード ホスト) が必要です。
• 複数のノードが使用可能な場合は、exec.node または tools.exec.node を設定して 1 つを選択します。
• Windows 以外のホストでは、exec は設定時に SHELL を使用します。 SHELL が fish の場合、bash (または sh) が優先されます。 PATH から、fish と互換性のないスクリプトを回避し、どちらも存在しない場合は SHELL に戻ります。
• Windows ホストでは、exec は PowerShell 7 (pwsh) 検出を優先します (Program Files、ProgramW6432、PATH)。 その後、Windows PowerShell 5.1 に戻ります。
• ホストの実行 (gateway/node) は env.PATH を拒否し、ローダーはオーバーライド (LD_*/DYLD_*) を実行します。 バイナリのハイジャックやコードの挿入を防ぎます。
• OpenClaw は、生成されたコマンド環境 (PTY およびサンドボックス実行を含む) に OPENCLAW_SHELL=exec を設定するため、シェル/プロファイル ルールは実行ツール コンテキストを検出できます。
• 重要: サンドボックスは デフォルトではオフになっています。サンドボックスがオフで、host=sandbox が明示的に設定されている場合 構成/要求された場合、exec はゲートウェイ ホスト上でサイレントに実行されるのではなく、フェール クローズされるようになりました。サンドボックスを有効にするか、承認付きの host=gateway を使用します。
• スクリプトのプリフライト チェック (一般的な Python/Node シェル構文の間違い) は、ファイル内のファイルのみを検査します。 有効な workdir 境界。スクリプト パスが workdir の外側で解決される場合、プリフライトはスキップされます。 そのファイル。

​

構成- tools.exec.notifyOnExit (デフォルト: true): true の場合、バックグラウンド実行セッションはシステム イベントをキューに入れ、終了時にハートビートを要求します

• tools.exec.approvalRunningNoticeMs (デフォルト: 10000): 承認ゲート型 exec がこれより長く実行される場合、単一の「実行中」通知を発行します (0 は無効になります)。
• tools.exec.host (デフォルト: sandbox)
• tools.exec.security (デフォルト: サンドボックスの場合は deny、未設定の場合はゲートウェイ + ノードの場合は allowlist)
• tools.exec.ask (デフォルト: on-miss)
• tools.exec.node (デフォルト: 未設定)
• tools.exec.pathPrepend: 実行実行のために PATH の前に追加するディレクトリのリスト (ゲートウェイ + サンドボックスのみ)。
• tools.exec.safeBins: 明示的なホワイトリスト エントリなしで実行できる標準入力のみの安全なバイナリ。動作の詳細については、金庫 を参照してください。
• tools.exec.safeBinTrustedDirs: safeBins パス チェックで信頼される追加の明示的なディレクトリ。 PATH エントリは自動信頼されません。組み込みのデフォルトは /bin および /usr/bin です。
• tools.exec.safeBinProfiles: 金庫ごとのオプションのカスタム argv ポリシー (minPositional、maxPositional、allowedValueFlags、deniedFlags)。

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

​

PATH の処理- host=gateway: ログインシェル PATH を実行環境にマージします。 env.PATH オーバーライドは

• macOS: /opt/homebrew/bin、/usr/local/bin、/usr/bin、/bin
• Linux: /usr/local/bin、/usr/bin、/bin
• host=sandbox: コンテナ内で sh -lc (ログイン シェル) を実行するため、/etc/profile は PATH をリセットする可能性があります。 OpenClaw は、内部環境変数 (シェル補間なし) によるプロファイル ソースの後に env.PATH を付加します。 tools.exec.pathPrepend はここにも当てはまります。
• host=node: 渡したブロックされていない環境オーバーライドのみがノードに送信されます。 env.PATH オーバーライドは ホストの実行が拒否され、ノード ホストによって無視されます。ノード上に追加の PATH エントリが必要な場合は、 ノードホストサービス環境 (systemd/launchd) を構成するか、標準の場所にツールをインストールします。

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

​

セッションの上書き (/exec)

/exec host=gateway security=allowlist ask=on-miss node=mac-1
```## 認可モデル

`/exec` は、**承認された送信者** (チャネル許可リスト/ペアリングと `commands.useAccessGroups`) に対してのみ受け入れられます。
**セッション状態のみ**を更新し、構成は書き込みません。実行をハード的に無効にするには、ツールを使用して実行を拒否します
ポリシー (`tools.deny: ["exec"]` またはエージェントごと)。明示的に設定しない限り、ホストの承認は引き続き適用されます。
`security=full` および `ask=off`。

## 実行承認 (コンパニオン アプリ/ノード ホスト)

サンドボックス エージェントは、ゲートウェイまたはノード ホストで `exec` を実行する前に、リクエストごとの承認を必要とする場合があります。
ポリシー、許可リスト、UI フローについては、[実行の承認](/tools/exec-approvals) を参照してください。

承認が必要な場合、実行ツールはすぐに次のコマンドを返します。
`status: "approval-pending"` と承認 ID。承認（または拒否/タイムアウト）されると、
ゲートウェイはシステム イベント (`Exec finished` / `Exec denied`) を発行します。コマンドがまだ残っている場合
`tools.exec.approvalRunningNoticeMs` の後に実行すると、単一の `Exec running` 通知が発行されます。

## ホワイトリスト + 金庫

手動による許可リストの適用は、**解決されたバイナリ パスのみ**と一致します (ベース名は一致しません)。いつ
`security=allowlist`、シェル コマンドは、すべてのパイプライン セグメントが
ホワイトリストまたは安全な箱に登録されています。チェーン (`;`、`&&`、`||`) とリダイレクトは拒否されます。
すべての最上位セグメントが許可リスト (セーフ ビンを含む) を満たす場合を除き、許可リスト モード。
リダイレクトは引き続きサポートされません。`autoAllowSkills` は、幹部の承認における別の便利なパスです。それは同じではありません
手動パスのホワイトリスト エントリ。厳密な明示的信頼を得るには、`autoAllowSkills` を無効にしておきます。

さまざまなジョブに 2 つのコントロールを使用します。

- `tools.exec.safeBins`: 小型の標準入力のみのストリーム フィルター。
- `tools.exec.safeBinTrustedDirs`: セーフビンの実行可能パス用の明示的な追加の信頼できるディレクトリ。
- `tools.exec.safeBinProfiles`: カスタム金庫の明示的な argv ポリシー。
- ホワイトリスト: 実行可能パスに対する明示的な信頼。

`safeBins` を汎用の許可リストとして扱わず、インタープリター/ランタイム バイナリ (`python3`、`node`、`ruby`、`bash` など) を追加しないでください。これらが必要な場合は、明示的な許可リスト エントリを使用し、承認プロンプトを有効のままにしてください。
`openclaw security audit` は、インタープリター/ランタイム `safeBins` エントリに明示的なプロファイルが欠落している場合に警告し、`openclaw doctor --fix` は欠落しているカスタム `safeBinProfiles` エントリをスキャフォールディングできます。

ポリシーの完全な詳細と例については、[Exec の承認](/tools/exec-approvals#safe-bins-stdin-only) および [安全な箱と許可リスト](/tools/exec-approvals#safe-bins-versus-allowlist) を参照してください。

## 例

前景:

```json
{ "tool": "exec", "command": "ls -la" }

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​

apply_patch (実験的)apply_patch は、構造化された複数ファイル編集のための exec のサブツールです

{
  tools: {
    exec: {
      applyPatch: { enabled: true, workspaceOnly: true, allowModels: ["gpt-5.2"] },
    },
  },
}

• OpenAI/OpenAI Codex モデルでのみ利用可能です。
• ツール ポリシーは引き続き適用されます。 allow: ["exec"] は apply_patch を暗黙的に許可します。
• 構成は tools.exec.applyPatch の下にあります。
• tools.exec.applyPatch.workspaceOnly のデフォルトは true (ワークスペースを含む) です。意図的に apply_patch をワークスペース ディレクトリの外に書き込み/削除する場合にのみ、これを false に設定します。