実行ツール

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

パラメーター

• 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）を設定するか、標準の場所にツールをインストールしてください。

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

​

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

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

​

認可モデル

​

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

​

Allowlist + safe bins

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

​

例

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

{
  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 ツール
• セキュリティ — ツールポリシーと昇格アクセス