Exec ツール

ワークスペースでシェルコマンドを実行します。process 経由のフォアグラウンド + バックグラウンド実行をサポートします。 process が許可されていない場合、exec は同期的に実行され、yieldMs/background を無視します。 バックグラウンドセッションはエージェントごとにスコープされます。process は同じエージェントからのセッションのみを表示します。

パラメータ

  • command（必須）
  • workdir（デフォルトは cwd）
  • env（キー/値のオーバーライド）
  • yieldMs（デフォルト 10000）：遅延後に自動バックグラウンド化
  • background（bool）：即座にバックグラウンド化
  • timeout（秒、デフォルト 1800）：期限切れで強制終了
  • 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）：エレベーテッドモードを要求（gateway ホスト）；security=full は elevated が full に解決される場合のみ強制されます

注意点：

  • host のデフォルトは sandbox です。
  • elevated はサンドボックスがオフの場合は無視されます（exec はすでにホストで実行されています）。
  • gateway/node の承認は ~/.openclaw/exec-approvals.json によって制御されます。
  • node にはペアリングされたノード（コンパニオンアプリまたはヘッドレスノードホスト）が必要です。
  • 複数のノードが利用可能な場合、exec.node または tools.exec.node を設定して 1 つを選択します。
  • Windows 以外のホストでは、exec は設定されている場合 SHELL を使用します。SHELL が fish の場合、fish と互換性のないスクリプトを避けるために PATH から bash（または sh）を優先し、どちらも存在しない場合は SHELL にフォールバックします。
  • 重要：サンドボックスは デフォルトでオフ です。サンドボックスがオフの場合、host=sandbox は Gateway ホストで直接実行され（コンテナなし）、承認を必要としません。承認を要求するには、host=gateway で実行し、exec 承認を設定します（またはサンドボックスを有効化）。

設定

  • tools.exec.notifyOnExit（デフォルト：true）：true の場合、バックグラウンド化された exec セッションは終了時にシステムイベントをキューに入れ、ハートビートを要求します。
  • tools.exec.approvalRunningNoticeMs（デフォルト：10000）：承認ゲートされた exec がこれより長く実行される場合、単一の「実行中」通知を発行します（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 にプリペンドするディレクトリのリスト。
  • tools.exec.safeBins: 明示的な許可リストエントリなしで実行できる stdin のみの安全なバイナリ。

例：

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

PATH の処理

  • host=gateway: ログインシェルの PATH を exec 環境にマージします（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 オーバーライドのみがノードに送信されます。tools.exec.pathPrepend は exec 呼び出しがすでに env.PATH を設定している場合のみ適用されます。ヘッドレスノードホストは、ノードホスト PATH をプリペンドする場合のみ PATH を受け入れます（置き換えなし）。macOS ノードは PATH オーバーライドを完全にドロップします。

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

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 approvals を参照してください。

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

許可リスト + 安全なバイナリ

許可リスト強制は 解決されたバイナリパスのみ と一致します（ベース名の一致なし）。 security=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>"}

ペースト（デフォルトでブラケット）：

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

apply_patch（実験的）

apply_patch は構造化されたマルチファイル編集のための exec のサブツールです。 明示的に有効化します：

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

注意点：

  • OpenAI/OpenAI Codex モデルのみで利用可能です。
  • ツールポリシーは引き続き適用されます。allow: ["exec"] は暗黙的に apply_patch を許可します。
  • 設定は tools.exec.applyPatch の下にあります。
← ドキュメントに戻る