OpenClawSkills
GitHub
ツール & スキル • 5分で読める

Exec ツール

Exec ツールの使用法、stdin モード、TTY サポート

ワークスペースでシェルコマンドを実行します。''process'' によるフォアグラウンド + バックグラウンド実行をサポートします。

''process'' が許可されていない場合、''exec'' は同期的に実行され、''yieldMs''/''background'' を無視します。

バックグラウンドセッションはエージェントごとにスコープされます；''process'' は同じエージェントからのセッションのみを表示します。

Tutorial.step

パラメータ

- ''command'' (required)

- ''workdir''（デフォルトは cwd）

- ''env''（キー/値のオーバーライド）

- ''yieldMs''（デフォルト 10000）：遅延後に自動バックグラウンド

- ''background''（ブール）：即座にバックグラウンド

- ''timeout''（秒、デフォルト 1800）：期限切れで強制終了

- ''pty''（ブール）：利用可能な場合に疑似端末で実行（TTY のみの CLI、コーディングエージェント、ターミナル UI）

- ''host'' (''sandbox | gateway | node''): where to execute

- ''security''（''deny | allowlist | full''）：''gateway''/''node'' の強制モード

- ''ask''（''off | on-miss | always''）：''gateway''/''node'' の承認プロンプト

- ''node''（文字列）：''host=node'' のノード id/名前

- ''elevated''（ブール）：昇格モードを要求（ゲートウェイホスト）；''security=full'' は elevated が ''full'' に解決された場合にのみ強制されます

Notes:

- ''host'' のデフォルトは ''sandbox'' です。

- サンドボックスがオフの場合、''elevated'' は無視されます（exec は既にホストで実行されています）。

- ''gateway''/''node'' の承認は ''~/.openclaw/exec-approvals.json'' によって制御されます。

- ''node'' はペアのノード（コンパニオンアプリまたはヘッドレスノードホスト）が必要です。

- 複数のノードが利用可能な場合、''exec.node'' または ''tools.exec.node'' を設定して選択します。

- Windows 以外のホストでは、exec は設定されている場合 ''SHELL'' を使用します；''SHELL'' が ''fish'' の場合、''bash''（または ''sh''）を

''PATH'' から優先し、fish 互換性のないスクリプトを回避し、どちらも存在しない場合は ''SHELL'' にフォールバックします。

- ホスト実行（''gateway''/''node''）は ''env.PATH'' とローダーオーバーライド（''LD_*''/''DYLD_*''）を拒否し、

バイナリハイジャックやコード注入を防ぎます。

- 重要：サンドボックスは''デフォルトでオフ''です。サンドボックスがオフの場合、''host=sandbox'' は

ゲートウェイホストで直接実行され（コンテナなし）、承認を必要としません。承認を要求するには、

''host=gateway'' で実行し、exec 承認を設定します（またはサンドボックスを有効にします）。

Tutorial.step

Config

- ''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 のみのセーフバイナリ。

Example:

Json5
{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}
Tutorial.step

PATH handling

- ''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.PATH'' オーバーライドは

ホスト実行では拒否されます。ヘッドレスノードホストは ''PATH'' をノードホスト PATH に

追加する場合のみ受け入れます（置換なし）。macOS ノードは ''PATH'' オーバーライドを完全にドロップします。

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

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

コントロール UI：ノードタブには同じ設定用の小さな「Exec ノードバインディング」パネルが含まれています。

Tutorial.step

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

''/exec'' を使用して、''host''、''security''、''ask''、''node'' の''セッションごとの''デフォルトを設定します。

引数なしで ''/exec'' を送信して現在の値を表示します。

Example:

Terminal
/exec host=gateway security=allowlist ask=on-miss node=mac-1
Tutorial.step

認可モデル

''/exec'' は''認可された送信者''に対してのみ有効です（チャンネル許可リスト/ペアリング + ''commands.useAccessGroups''）。

セッション状態のみを更新し、設定には書き込みません。exec を完全に無効にするには、ツール

ポリシーで拒否します（''tools.deny: ["exec"]'' またはエージェントごと）。明示的に

''security=full'' と ''ask=off'' を設定しない限り、ホスト承認は引き続き適用されます。

Tutorial.step

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

サンドボックス化されたエージェントは、''exec'' がゲートウェイまたはノードホストで実行される前にリクエストごとの承認を要求できます。

ポリシー、許可リスト、UI フローについては ''Exec 承認'' を参照してください。

承認が必要な場合、exec ツールは即座に

''status: "approval-pending"'' と承認 id を返します。承認（または拒否/タイムアウト）されると、

ゲートウェイはシステムイベント（''Exec finished'' / ''Exec denied''）を発行します。コマンドが

''tools.exec.approvalRunningNoticeMs'' 以降も実行されている場合、単一の ''Exec running'' 通知が発行されます。

Tutorial.step

許可リスト + セーフバイナリ

許可リストの強制は解決されたバイナリパスのみに一致します（ベース名の一致はありません）。

''security=allowlist'' の場合、シェルコマンドはすべてのパイプラインセグメントが

許可リストにあるかセーフバイナリである場合にのみ自動許可されます。チェーン（'';''、''&&''、''||''）とリダイレクトは

許可リストモードでは拒否されます。

Tutorial.step

Examples

フォアグラウンド：

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

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

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

キー送信（tmux スタイル）：

Json
{"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 のみ送信）：

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

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

Json
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1
line2
" }
Tutorial.step

apply_patch (experimental)

''apply_patch'' は ''exec'' のサブツールで、構造化されたマルチファイル編集を行います。

明示的に有効にします：

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

Notes:

- OpenAI/OpenAI Codex モデルでのみ利用可能です。