Exec ツール

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

パラメータ

  • command（必須）
  • workdir（デフォルトは cwd）
  • env（キー/値オーバーライド）
  • yieldMs（デフォルト 10000）: 遅延後に自動バックグラウンド化
  • background（bool）: 即座にバックグラウンド化
  • timeout（秒、デフォルト 1800）: 期限切れで kill
  • pty（bool）: 利用可能な場合に擬似端末で実行（TTY 専用 CLI、コーディングエージェント、ターミナル UI 向け）
  • host（sandbox | gateway | node）: 実行場所
  • security（deny | allowlist | full）: gateway/node の実施モード
  • ask（off | on-miss | always）: gateway/node の承認プロンプト
  • node（string）: host=node 用のノード ID/名前
  • elevated（bool）: elevated モードを要求（Gateway ホスト）。security=full は elevated が full に解決された場合にのみ強制

補足:

  • host のデフォルトは sandbox。
  • サンドボックスが無効の場合、elevated は無視されます（exec は既にホスト上で実行）。
  • gateway/node の承認は ~/.openclaw/exec-approvals.json で制御。
  • node にはペアリング済みノード（コンパニオンアプリまたはヘッドレスノードホスト）が必要。
  • 複数ノードが利用可能な場合は、exec.node または tools.exec.node で選択。
  • 非 Windows ホストでは、SHELL が設定されている場合はそれを使用。SHELL が fish の場合は PATH から bash（または sh）を優先し、見つからなければ SHELL にフォールバック。
  • Windows ホストでは、PowerShell 7（pwsh）の検出を優先（Program Files、ProgramW6432、PATH の順）、見つからなければ Windows PowerShell 5.1 にフォールバック。
  • ホスト実行（gateway/node）はバイナリハイジャックやコードインジェクション防止のため、env.PATH とローダーオーバーライド（LD_*/DYLD_*）を拒否。
  • OpenClaw は exec ツールのコンテキストを検出できるよう、生成されたコマンド環境（PTY とサンドボックス実行を含む）に OPENCLAW_SHELL=exec を設定。
  • 重要: サンドボックスはデフォルトで無効です。サンドボックスが無効で host=sandbox が明示的に設定/要求されている場合、exec はサイレントに Gateway ホスト上で実行する代わりに安全側に倒れて失敗します。サンドボックスを有効にするか、承認付きの host=gateway を使用してください。
  • スクリプトのプリフライトチェック（一般的な Python/Node のシェル構文ミス向け）は、有効な workdir 境界内のファイルのみ検査します。スクリプトパスが workdir の外に解決される場合、そのファイルのプリフライトはスキップされます。

設定

  • tools.exec.notifyOnExit（デフォルト: true）: true の場合、バックグラウンド化された exec セッションは終了時にシステムイベントをエンキューし、ハートビートを要求。
  • tools.exec.approvalRunningNoticeMs（デフォルト: 10000）: 承認ゲート付き exec がこの時間より長く実行された場合に「実行中」通知を 1 回発行（0 で無効）。
  • tools.exec.host（デフォルト: sandbox）
  • tools.exec.security（デフォルト: sandbox は deny、未設定時の gateway + node は allowlist）
  • tools.exec.ask（デフォルト: on-miss）
  • tools.exec.node（デフォルト: 未設定）
  • tools.exec.pathPrepend: exec 実行時に PATH の先頭に追加するディレクトリリスト（gateway + sandbox のみ）。
  • tools.exec.safeBins: 明示的なアローリストエントリなしで実行できる stdin 専用の安全バイナリ。詳細は 安全バイナリ を参照。
  • 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: ブロックされていない env オーバーライドのみノードに送信。ホスト実行では env.PATH オーバーライドは拒否され、ノードホストでも無視。ノードで追加の PATH エントリが必要な場合は、ノードホストサービス環境（systemd/launchd）を設定するか、標準の場所にツールをインストール。

エージェント単位のノードバインディング（設定でエージェントリストインデックスを使用）:

openclaw config get agents.list
openclaw 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=gateway security=allowlist ask=on-miss node=mac-1

認可モデル

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

Exec 承認（コンパニオンアプリ / ノードホスト）

サンドボックス化されたエージェントは、Gateway またはノードホスト上で exec を実行する前にリクエストごとの承認を要求できます。ポリシー、アローリスト、UI フローの詳細は Exec 承認 を参照。

承認が必要な場合、exec ツールは status: "approval-pending" と承認 ID を即座に返します。承認（または拒否/タイムアウト）後、Gateway がシステムイベント（Exec finished / Exec denied）を発行します。コマンドが tools.exec.approvalRunningNoticeMs より長く実行されている場合、Exec running 通知が 1 回発行されます。

アローリスト + 安全バイナリ

手動アローリストは解決済みバイナリパスのみに一致します（basename マッチなし）。security=allowlist の場合、すべてのパイプラインセグメントがアローリストまたは安全バイナリに該当する場合にのみシェルコマンドが自動許可されます。チェイン（;、&&、||）とリダイレクトは、すべてのトップレベルセグメントがアローリスト（安全バイナリを含む）を満たす場合を除き、アローリストモードで拒否されます。リダイレクトは未サポート。

autoAllowSkills は exec 承認内の別の便利なパスです。手動パスアローリストエントリとは異なります。厳密な明示的信頼には、autoAllowSkills を無効にしてください。

2 つのコントロールを異なる用途に使い分けてください:

  • tools.exec.safeBins: 小さな stdin 専用ストリームフィルタ。
  • tools.exec.safeBinTrustedDirs: 安全バイナリの実行パス用の追加信頼ディレクトリ。
  • tools.exec.safeBinProfiles: カスタム安全バイナリの明示的な argv ポリシー。
  • アローリスト: 実行パスの明示的な信頼。

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

完全なポリシーの詳細と例は Exec 承認 と 安全バイナリ vs アローリスト を参照。

使用例

フォアグラウンド:

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

ペースト（デフォルトでブラケット付き）:

{ "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 に設定。
arrow_back
前へ
Elevated
次へ
Exec Approvals
arrow_forward