跳轉到主要內容

​
Exec 工具

在工作區中執行 shell 指令。 在工作區中執行 shell 指令。 Supports foreground + background execution via process. 若 process 被拒絕，exec 會同步執行並忽略 yieldMs/background。 49. 背景工作階段以代理為範圍；process 只能看到同一代理的工作階段。

​
參數

  • command（必要）
  • workdir（預設為 cwd）
  • env（鍵／值覆寫）
  • yieldMs（預設 10000）：延遲後自動轉為背景
  • background（bool）：立即在背景執行
  • timeout（秒，預設 1800）：到期時終止
  • pty（bool）：可用時在虛擬終端中執行（僅限 TTY 的 CLI、編碼代理程式、終端介面）
  • 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 閘道器主機）；只有當提升解析為 full 時，security=full 才會被強制
注意事項：
  • 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_*）， 以防止二進位檔劫持或注入程式碼。
    1. 重要：沙箱化預設為關閉。 重要：沙箱化預設為關閉。 If sandboxing is off, host=sandbox runs directly on the gateway host (no container) and does not require approvals. To require approvals, run with host=gateway and configure exec approvals (or enable sandboxing).

​
設定

  • tools.exec.notifyOnExit（預設：true）：為 true 時，背景執行的 exec 工作階段會排入系統事件，並在結束時請求心跳。
  • tools.exec.approvalRunningNoticeMs（預設：10000）：當需核准的 exec 執行時間超過此值時，發出單一的「執行中」通知（0 表示停用）。
  • tools.exec.host（預設：sandbox）
  • tools.exec.security（預設：沙箱為 deny；Gateway 閘道器 + 節點在未設定時為 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 環境中。主機執行時會拒絕 env.PATH 覆寫。 守護程式本身仍以最小化的 PATH 執行： env.PATH overrides are rejected for host execution. env.PATH overrides are rejected for host execution. The daemon itself still runs with a minimal 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 亦適用於此。 OpenClaw prepends env.PATH after profile sourcing via an internal env var (no shell interpolation); tools.exec.pathPrepend applies here too. OpenClaw prepends env.PATH after profile sourcing via an internal env var (no shell interpolation); tools.exec.pathPrepend applies here too.
  • host=node：只會將你傳入且未被封鎖的環境變數覆寫送至節點。主機執行時會拒絕 env.PATH 覆寫。 無介面節點主機僅在其前置節點主機 PATH（不取代）時才接受 PATH。 macOS 節點會完全捨棄 PATH 覆寫。 host=node：只會將你傳入且未被封鎖的環境變數覆寫送至節點。主機執行時會拒絕 env.PATH 覆寫。 無介面節點主機僅在其前置節點主機 PATH（不取代）時才接受 PATH。 macOS 節點會完全捨棄 PATH 覆寫。 env.PATH overrides are rejected for host execution. 若你需要在某個節點上新增 PATH 項目， 請設定該節點主機服務的環境（systemd/launchd），或將工具安裝於標準位置。
每個代理程式的節點綁定（在設定中使用代理程式清單索引）： 
openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
控制 UI：Nodes 分頁包含一個小型的「Exec 節點綁定」面板，提供相同的設定。

​
Session overrides (/exec)

使用 /exec 設定每個工作階段的 host、security、ask 與 node 預設值。 Send /exec with no arguments to show the current values. Send /exec with no arguments to show the current values. 範例： 
/exec host=gateway security=allowlist ask=on-miss node=mac-1

​
授權模型

/exec 僅對已授權的寄件者生效（頻道允許清單／配對加上 commands.useAccessGroups）。 它只會更新工作階段狀態，不會寫入設定。若要硬性停用 exec，請透過工具 政策（tools.deny: ["exec"] 或每個代理程式）來拒絕。除非你明確設定 security=full 與 ask=off，否則主機核准仍然適用。 It updates session state only and does not write config. To hard-disable exec, deny it via tool policy (tools.deny: ["exec"] or per-agent). Host approvals still apply unless you explicitly set security=full and ask=off.

​
Exec approvals (companion app / node host)

Sandboxed agents can require per-request approval before exec runs on the gateway or node host. See Exec approvals for the policy, allowlist, and UI flow.
  1. 當需要核准時，exec 工具會立即回傳 status: "approval-pending" 與一個核准 ID。 當需要核准時，exec 工具會立即回傳 status: "approval-pending" 與一個核准 ID。 Once approved (or denied / timed out), the Gateway emits system events (Exec finished / Exec denied). If the command is still running after tools.exec.approvalRunningNoticeMs, a single Exec running notice is emitted.

​
允許清單 + 安全二進位檔

Allowlist enforcement matches resolved binary paths only (no basename matches). When security=allowlist, shell commands are auto-allowed only if every pipeline segment is allowlisted or a safe bin. 在 allowlist 模式下，會拒絕使用鏈式指令（;、&&、||）與重新導向， 除非每個最上層片段都符合 allowlist（包含安全 bins）。 不支援重新導向。

​
範例

前景： 
{ "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>" }
Paste (bracketed by default): 
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​
apply_patch（實驗性）

apply_patch 是 exec 的子工具，用於結構化的多檔案編輯。 請明確啟用： 32. 請明確啟用它： 
{
  tools: {
    exec: {
      applyPatch: { enabled: true, allowModels: ["gpt-5.2"] },
    },
  },
}
注意事項：
  • 僅適用於 OpenAI／OpenAI Codex 模型。
  • 工具政策仍然適用；allow: ["exec"] 會隱含允許 apply_patch。
  • 設定位於 tools.exec.applyPatch 之下。
  • tools.exec.applyPatch.workspaceOnly 預設為 true（僅限於 workspace 內）。 僅在你有意讓 apply_patch 在 workspace 目錄之外進行寫入/刪除時，才將其設為 false。