OpenClaw Execツール：ワークスペースでシェルコマンドを効率化

開発中にターミナルとエディタを行ったり来たりするのは、集中力が削がれる原因になりますよね。エージェントが直接コマンドを実行できれば便利ですが、勝手に危険な操作をされないか心配になることもあるはずです。

OpenClaw の exec ツールを使えば、ワークスペース内で安全かつ柔軟にシェルコマンドを実行できます。フォアグラウンド実行はもちろん、process を介したバックグラウンド実行にも対応しており、開発ワークフローを強力にサポートします。

Exec ツール

ワークスペース内でシェルコマンドを実行します。process を介したフォアグラウンドおよびバックグラウンド実行をサポートしています。 process が許可されていない場合、exec は同期的に実行され、yieldMs や background 設定は無視されます。 バックグラウンドセッションのスコープはエージェントごとに設定されます。process は同じエージェントからのセッションのみを認識します。

パラメータ

• command (必須)
• workdir (デフォルトは cwd)
• env (キー/値による上書き)
• yieldMs (デフォルト 10000): 指定した遅延の後に自動的にバックグラウンドへ移行
• background (bool): 即座にバックグラウンドで実行
• timeout (秒、デフォルト 1800): 期限切れ時にプロセスを終了
• pty (bool): 利用可能な場合に擬似ターミナルで実行（TTY 専用の CLI、コーディングエージェント、ターミナル UI など）
• host (auto | sandbox | gateway | node): 実行場所
• security (deny | allowlist | full): gateway または node での強制モード
• ask (off | on-miss | always): gateway または node での承認プロンプト設定
• node (string): host=node の場合の Node ID または名前
• elevated (bool): 特権モードをリクエスト（Gateway ホスト）。security=full は、特権アクセスが full として解決された場合にのみ強制されます。

注意点:

• host のデフォルトは auto です。セッションで Sandbox ランタイムがアクティブな場合は Sandbox、それ以外の場合は Gateway になります。
• elevated を指定すると host=gateway が強制されます。これは、現在のセッションまたはプロバイダーで特権アクセスが有効な場合にのみ利用可能です。
• gateway および node の承認は ~/.openclaw/exec-approvals.json で管理されます。
• node には、ペアリングされた Node（コンパニオンアプリまたはヘッドレス Node ホスト）が必要です。
• 複数の Node が利用可能な場合は、exec.node または tools.exec.node を設定して選択してください。
• exec host=node は、Node における唯一のシェル実行パスです。レガシーな nodes.run ラッパーは削除されました。
• 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 は、生成されたコマンド環境（PTY および Sandbox 実行を含む）に OPENCLAW_SHELL=exec を設定します。これにより、シェルやプロファイルルールで exec ツールのコンテキストを検出できます。
• 重要: Sandboxing はデフォルトでオフです。Sandboxing がオフの場合、暗黙的な host=auto は gateway として解決されます。明示的な host=sandbox は、Gateway ホストでサイレントに実行されるのではなく、エラーとして終了します。Sandboxing を有効にするか、承認設定を伴う host=gateway を使用してください。
• スクリプトのプリフライトチェック（Python や Node の一般的なシェル構文ミスの確認）は、有効な workdir 境界内のファイルのみを検査します。スクリプトパスが workdir 外になる場合、そのファイルのプリフライトはスキップされます。

設定

• tools.exec.notifyOnExit (デフォルト: true): true の場合、バックグラウンドの exec セッション終了時にシステムイベントをエンキューし、ハートビートをリクエストします。
• tools.exec.approvalRunningNoticeMs (デフォルト: 10000): 承認が必要な exec がこれより長く実行されている場合、単一の「実行中」通知を発行します（0 で無効）。
• tools.exec.host (デフォルト: auto。Sandbox ランタイムがアクティブな場合は sandbox、それ以外は gateway に解決)
• tools.exec.security (デフォルト: Sandbox の場合は deny、未設定時の Gateway および Node の場合は allowlist)
• tools.exec.ask (デフォルト: on-miss)
• tools.exec.node (デフォルト: 未設定)
• tools.exec.strictInlineEval (デフォルト: false): true の場合、python -c, node -e, ruby -e, perl -e, php -r, lua -e, osascript -e などのインラインインタープリタ評価形式には常に明示的な承認が必要になります。allow-always で通常のスクリプト呼び出しを許可していても、インライン評価形式は毎回プロンプトを表示します。
• tools.exec.pathPrepend: exec 実行時に PATH の先頭に追加するディレクトリのリスト（Gateway および Sandbox のみ）。
• tools.exec.safeBins: 明示的なホワイトリスト登録なしで実行できる、標準入力のみを使用する安全なバイナリ。詳細は Safe bins を参照してください。
• tools.exec.safeBinTrustedDirs: safeBins のパスチェックで信頼される追加のディレクトリ。PATH エントリは自動的には信頼されません。組み込みのデフォルトは /bin と /usr/bin です。
• tools.exec.safeBinProfiles: セーフバイナリごとのオプションのカスタム引数ポリシー（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.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=auto security=allowlist ask=on-miss node=mac-1

認証モデル

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

実行の承認 (コンパニオンアプリ / Node ホスト)

Sandbox 化されたエージェントが Gateway または Node ホストで exec を実行する前に、リクエストごとの承認を要求するように設定できます。 ポリシー、ホワイトリスト、および UI フローについては、Exec approvals を参照してください。

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

ホワイトリストとセーフバイナリ

手動のホワイトリスト強制は、解決されたバイナリパスのみに一致します（ベース名のみの一致は行いません）。security=allowlist の場合、パイプラインのすべてのセグメントがホワイトリストに登録されているか、セーフバイナリである場合にのみ、シェルコマンドが自動的に許可されます。チェーン（;, &&, ||）やリダイレクトは、すべてのトップレベルセグメントがホワイトリスト（セーフバイナリを含む）を満たさない限り、ホワイトリストモードでは拒否されます。リダイレクトは引き続きサポートされていません。 永続的な allow-always の信頼はこのルールをバイパスしません。チェーンされたコマンドでも、すべてのトップレベルセグメントが一致する必要があります。

autoAllowSkills は実行承認における別の便利なパスですが、手動のパスホワイトリストエントリとは異なります。厳格で明示的な信頼が必要な場合は、autoAllowSkills を無効にしたままにしてください。

用途に応じて 2 つのコントロールを使い分けてください：

• tools.exec.safeBins: 標準入力のみを扱う小さなストリームフィルタ。
• tools.exec.safeBinTrustedDirs: セーフバイナリの実行パスとして信頼する明示的な追加ディレクトリ。
• tools.exec.safeBinProfiles: カスタムセーフバイナリ用の明示的な引数（argv）ポリシー。
• ホワイトリスト: 実行パスに対する明示的な信頼。

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

ポリシーの詳細と例については、Exec approvals および Safe bins versus 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 のサブツールです。 OpenAI および OpenAI Codex モデルではデフォルトで有効になっています。無効にしたい場合や、特定のモデルに制限したい場合にのみ設定を使用してください。

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

注意点:

• OpenAI/OpenAI Codex モデルでのみ利用可能です。
• ツールポリシーは引き続き適用されます。allow: ["write"] は暗黙的に apply_patch を許可します。
• 設定は tools.exec.applyPatch の下にあります。
• tools.exec.applyPatch.enabled はデフォルトで true です。OpenAI モデルでツールを無効にするには false に設定してください。
• tools.exec.applyPatch.workspaceOnly はデフォルトで true（ワークスペース内に限定）です。意図的にワークスペースディレクトリ外への書き込み/削除を許可したい場合にのみ false に設定してください。

関連ドキュメント

• Exec Approvals — シェルコマンドの承認ゲート
• Sandboxing — サンドボックス環境でのコマンド実行
• Background Process — 長時間実行される exec と process ツール
• Security — ツールポリシーと特権アクセス

次のステップ

設定やセキュリティについてさらに詳しく知りたい方は、上記の関連ドキュメントをチェックしてみてください。不明な点があれば、いつでも AI Setup Assistant に聞いてくださいね。