実行ツール

ワークスペースでシェルコマンドを実行します。exec は変更を伴うシェルサーフェスです。選択されたホストまたはサンドボックスのファイルシステムが許可する場所であれば、コマンドはファイルを作成、編集、削除できます。write、edit、apply_patch などの OpenClaw ファイルシステムツールを無効にしても、exec は読み取り専用になりません。

process によるフォアグラウンド実行とバックグラウンド実行に対応しています。process が許可されていない場合、exec は同期的に実行され、yieldMs/background を無視します。 バックグラウンドセッションはエージェントごとにスコープされます。process は同じエージェントのセッションのみを参照します。

パラメーター

注:

• host のデフォルトは auto です。セッションでサンドボックスランタイムがアクティブな場合は sandbox、それ以外の場合は gateway になります。
• host が受け付けるのは auto、sandbox、gateway、node のみです。ホスト名セレクターではありません。ホスト名のような値は、コマンド実行前に拒否されます。
• auto はデフォルトのルーティング戦略であり、ワイルドカードではありません。auto から呼び出しごとに host=node を指定することは許可されます。呼び出しごとの host=gateway は、サンドボックスランタイムがアクティブでない場合のみ許可されます。
• 追加設定がなくても、host=auto はそのまま動作します。サンドボックスがなければ gateway に解決され、稼働中のサンドボックスがあればサンドボックス内に留まります。
• elevated は、サンドボックスを抜けて設定済みホストパスへ移動します。デフォルトでは gateway、tools.exec.host=node の場合（またはセッションのデフォルトが host=node の場合）は node です。これは、現在のセッション/プロバイダーで昇格アクセスが有効な場合のみ利用できます。
• gateway/node の承認は ~/.openclaw/exec-approvals.json によって制御されます。
• node にはペアリング済み Node（コンパニオンアプリまたはヘッドレス Node ホスト）が必要です。
• 複数の Node が利用可能な場合は、exec.node または tools.exec.node を設定して 1 つを選択します。
• exec host=node は Node に対する唯一のシェル実行パスです。従来の nodes.run ラッパーは削除されました。
• timeout は、フォアグラウンド、バックグラウンド、yieldMs、gateway、sandbox、Node の system.run 実行に適用されます。省略した場合、OpenClaw は tools.exec.timeoutSec を使用します。明示的な timeout: 0 は、その呼び出しの exec プロセスタイムアウトを無効にします。
• Windows 以外のホストでは、exec は SHELL が設定されている場合それを使用します。SHELL が fish の場合、fish と互換性のないスクリプトを避けるため、PATH から bash（または sh）を優先し、どちらも存在しない場合は SHELL にフォールバックします。
• Windows ホストでは、exec は PowerShell 7（pwsh）の検出（Program Files、ProgramW6432、次に PATH）を優先し、その後 Windows PowerShell 5.1 にフォールバックします。
• ホスト実行（gateway/node）では、バイナリの乗っ取りや注入コードを防ぐため、env.PATH とローダーオーバーライド（LD_*/DYLD_*）を拒否します。
• OpenClaw は、シェル/プロファイルルールが exec ツールコンテキストを検出できるように、起動されるコマンド環境（PTY とサンドボックス実行を含む）で OPENCLAW_SHELL=exec を設定します。
• openclaw channels login は対話型のチャンネル認証フローであるため、exec からはブロックされます。Gateway ホスト上のターミナルで実行するか、存在する場合はチャットからチャンネルネイティブのログインツールを使用してください。
• 重要: サンドボックス化はデフォルトでオフです。サンドボックス化がオフの場合、暗黙の host=auto は gateway に解決されます。明示的な host=sandbox は、Gateway ホストで黙って実行されるのではなく、クローズドに失敗します。サンドボックス化を有効にするか、承認付きで host=gateway を使用してください。
• スクリプトの事前チェック（一般的な Python/Node のシェル構文ミス向け）は、有効な workdir 境界内のファイルのみを検査します。スクリプトパスが workdir の外に解決される場合、そのファイルの事前チェックはスキップされます。
• 今すぐ開始する長時間実行の作業では、一度だけ開始し、自動完了ウェイクが有効で、コマンドが出力するか失敗したときの自動完了ウェイクに依存してください。ログ、状態、入力、介入には process を使用します。sleep ループ、timeout ループ、反復ポーリングでスケジューリングを模倣しないでください。
• 後で実行する作業やスケジュール実行する作業には、exec の sleep/遅延パターンではなく cron を使用してください。

設定

• tools.exec.notifyOnExit（デフォルト: true）: true の場合、バックグラウンド化された exec セッションは終了時にシステムイベントをキューに入れ、Heartbeat を要求します。
• tools.exec.approvalRunningNoticeMs（デフォルト: 10000）: 承認ゲート付き exec がこの時間を超えて実行された場合、単一の「running」通知を出します（0 で無効）。
• tools.exec.timeoutSec（デフォルト: 1800）: コマンドごとのデフォルト exec タイムアウト秒数。呼び出しごとの timeout がこれを上書きします。呼び出しごとの timeout: 0 は exec プロセスタイムアウトを無効にします。
• tools.exec.host（デフォルト: auto; サンドボックスランタイムがアクティブな場合は sandbox、それ以外の場合は gateway に解決）
• tools.exec.security（デフォルト: sandbox では deny、未設定の場合 gateway + node では full）
• tools.exec.ask（デフォルト: off）
• 承認なしのホスト exec が gateway + node のデフォルトです。承認/allowlist 動作が必要な場合は、tools.exec.* とホストの ~/.openclaw/exec-approvals.json の両方を厳格化してください。Exec approvals を参照してください。
• YOLO はホストポリシーのデフォルト（security=full、ask=off）から来るものであり、host=auto から来るものではありません。gateway または node へのルーティングを強制したい場合は、tools.exec.host を設定するか /exec host=... を使用してください。
• security=full かつ ask=off モードでは、ホスト exec は設定済みポリシーに直接従います。追加のヒューリスティックなコマンド難読化プリフィルターや、スクリプト事前チェックの拒否レイヤーはありません。
• tools.exec.node（デフォルト: 未設定）
• tools.exec.strictInlineEval（デフォルト: false）: true の場合、python -c、node -e、ruby -e、perl -e、php -r、lua -e、osascript -e などのインラインインタープリター eval 形式は常に明示的な承認を必要とします。allow-always は無害なインタープリター/スクリプト呼び出しを引き続き永続化できますが、インライン eval 形式は毎回プロンプトを表示します。
• tools.exec.commandHighlighting（デフォルト: false）: true の場合、承認プロンプトはコマンドテキスト内のパーサー由来のコマンド範囲を強調表示できます。exec 承認ポリシーを変更せずにコマンドテキストの強調表示を有効にするには、グローバルまたはエージェントごとに true を設定します。
• tools.exec.pathPrepend: exec 実行時に PATH の先頭へ追加するディレクトリ一覧（gateway + sandbox のみ）。
• tools.exec.safeBins: 明示的な allowlist エントリーなしで実行できる stdin 専用の安全なバイナリ。動作の詳細は Safe bins を参照してください。
• 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 を exec 環境へマージします。ホスト実行では env.PATH オーバーライドは拒否されます。デーモン自体は引き続き最小限の 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: 渡したブロック対象外の環境オーバーライドのみが Node に送信されます。env.PATH オーバーライドはホスト実行では拒否され、Node ホストでは無視されます。Node 上で追加の PATH エントリーが必要な場合は、Node ホストサービス環境（systemd/launchd）を設定するか、標準の場所にツールをインストールしてください。

エージェントごとの Node バインディング（設定ではエージェントリストのインデックスを使用）:

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

コントロール UI: Nodes タブには、同じ設定用の小さな「Exec node binding」パネルがあります。

セッションオーバーライド（/exec）

/exec を使用して、host、security、ask、node のセッションごとのデフォルトを設定します。 現在の値を表示するには、引数なしで /exec を送信します。

例:

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

認可モデル

/exec は認可済み送信者（チャンネル allowlist/ペアリングと commands.useAccessGroups）に対してのみ有効です。 これはセッション状態のみを更新し、設定を書き込みません。exec を完全に無効化するには、ツールポリシー（tools.deny: ["exec"] またはエージェントごとの設定）で拒否してください。明示的に security=full と ask=off を設定しない限り、ホスト承認は引き続き適用されます。

Exec approvals（コンパニオンアプリ / Node ホスト）

サンドボックス化されたエージェントは、Gateway または Node ホストで exec が実行される前に、リクエストごとの承認を要求できます。 ポリシー、allowlist、UI フローについては Exec approvals を参照してください。

承認が必要な場合、exec ツールは status: "approval-pending" と承認 ID を返して即座に終了します。承認（または拒否 / タイムアウト）されると、 Gateway はシステムイベント（Exec finished / Exec denied）を発行します。コマンドが tools.exec.approvalRunningNoticeMs を過ぎてもまだ実行中の場合、単一の Exec running 通知が発行されます。 ネイティブの承認カード/ボタンを持つチャンネルでは、エージェントはまずそのネイティブ UI に依存し、ツール結果がチャット承認を利用できない、または手動承認が唯一の経路であると明示している場合にのみ、手動の /approve コマンドを含めるべきです。

Allowlist + safe bins

手動 allowlist の適用は、解決済みバイナリパスの glob とベアコマンド名の glob に一致します。ベア名は PATH 経由で呼び出されたコマンドのみに一致するため、コマンドが rg の場合、rg は /opt/homebrew/bin/rg に一致できますが、./rg や /tmp/rg には一致しません。 security=allowlist の場合、シェルコマンドは、すべてのパイプライン セグメントが allowlist 登録済みまたは安全なバイナリである場合のみ自動許可されます。チェーン（;、&&、||）とリダイレクトは、 すべてのトップレベルセグメントが allowlist（安全なバイナリを含む）を満たす場合を除き、allowlist モードでは拒否されます。リダイレクトは引き続き未対応です。 永続的な allow-always 信頼はそのルールをバイパスしません。チェーンされたコマンドでは、引き続きすべての トップレベルセグメントが一致する必要があります。

autoAllowSkills は exec 承認内の別の便利な経路です。これは 手動パス allowlist エントリーと同じではありません。厳密で明示的な信頼が必要な場合は、autoAllowSkills を無効のままにしてください。

用途に応じて 2 つの制御を使い分けます:

• tools.exec.safeBins: 小さな stdin 専用ストリームフィルター。
• tools.exec.safeBinTrustedDirs: safe-bin 実行可能パス用の明示的な追加の信頼済みディレクトリ。
• tools.exec.safeBinProfiles: カスタム safe bin 用の明示的な argv ポリシー。
• allowlist: 実行可能パスに対する明示的な信頼。

safeBins を汎用 allowlist として扱わず、インタープリター/ランタイムバイナリ（例: python3、node、ruby、bash）を追加しないでください。それらが必要な場合は、明示的な allowlist エントリを使用し、承認プロンプトを有効なままにしてください。 openclaw security audit は、インタープリター/ランタイムの safeBins エントリに明示的なプロファイルがない場合に警告し、openclaw doctor --fix は不足しているカスタム safeBinProfiles エントリのひな形を生成できます。 openclaw security audit と openclaw doctor は、jq のような広範な動作を持つ bin を safeBins に明示的に戻した場合にも警告します。 インタープリターを明示的に allowlist に追加する場合は、インラインコード評価形式が引き続き新しい承認を必要とするように、tools.exec.strictInlineEval を有効にしてください。

ポリシーの詳細と例については、Exec 承認 と Safe bins と allowlist を参照してください。

例

フォアグラウンド:

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

バックグラウンド + ポーリング:

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

ポーリングはオンデマンドの状態確認用であり、待機ループ用ではありません。自動完了ウェイクが有効な場合、コマンドは出力を生成したとき、または失敗したときにセッションをウェイクできます。

キー送信（tmux 形式）:

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

送信（CR のみ送信）:

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

貼り付け（デフォルトで bracketed）:

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

apply_patch

apply_patch は、構造化された複数ファイル編集のための exec のサブツールです。 OpenAI および OpenAI Codex モデルではデフォルトで有効です。無効化する場合、または特定のモデルに制限したい場合にのみ設定を使用してください。

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

注:

• OpenAI/OpenAI Codex モデルでのみ利用できます。
• ツールポリシーは引き続き適用されます。allow: ["write"] は暗黙的に apply_patch を許可します。
• deny: ["write"] は apply_patch を拒否しません。パッチ書き込みもブロックする必要がある場合は、apply_patch を明示的に拒否するか、deny: ["group:fs"] を使用してください。
• 設定は tools.exec.applyPatch の下にあります。
• tools.exec.applyPatch.enabled のデフォルトは true です。OpenAI モデルでツールを無効化するには false に設定してください。
• tools.exec.applyPatch.workspaceOnly のデフォルトは true（ワークスペース内）です。apply_patch がワークスペースディレクトリの外側に書き込み/削除することを意図している場合にのみ、false に設定してください。

関連

• Exec 承認 — シェルコマンドの承認ゲート
• サンドボックス化 — サンドボックス化された環境でコマンドを実行する
• バックグラウンドプロセス — 長時間実行される exec と process ツール
• セキュリティ — ツールポリシーと昇格アクセス