Exec 工具

在工作區中執行 shell 指令。支援透過 process 進行前景和背景執行。如果 process 被禁止，exec 會同步執行並忽略 yieldMs/background。背景工作階段以代理為範圍；process 只能看到同一代理的工作階段。

參數

command（必填）
workdir（預設為 cwd）
env（key/value 覆寫）
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/name
elevated（bool）：請求提權模式（Gateway 主機）；僅在提權解析為 full 時才強制 security=full

注意事項：

host 預設為 sandbox。
沙箱化關閉時 elevated 會被忽略（執行本來就在主機上進行）。
gateway/node 的核准由 ~/.openclaw/exec-approvals.json 控制。
node 需要已配對的節點（配套應用程式或無頭節點主機）。
有多個節點時，設定 exec.node 或 tools.exec.node 選擇一個。
在非 Windows 主機上，exec 使用已設定的 SHELL；如果 SHELL 是 fish，會優先從 PATH 尋找 bash（或 sh）以避免 fish 不相容的腳本，如果兩者都不存在才後備到 SHELL。
在 Windows 主機上，exec 優先探索 PowerShell 7（pwsh，依序檢查 Program Files、ProgramW6432、PATH），然後後備到 Windows PowerShell 5.1。
主機執行（gateway/node）會拒絕 env.PATH 和載入器覆寫（LD_*/DYLD_*），以防止二進位檔劫持或注入程式碼。
OpenClaw 會在啟動的指令環境中設定 OPENCLAW_SHELL=exec（包括 PTY 和沙箱執行），讓 shell/profile 規則可以偵測 exec 工具的上下文。
重要：沙箱化預設為關閉。如果沙箱化已關閉且明確設定 / 請求了 host=sandbox，exec 現在會以失敗關閉的方式處理，而非靜默地在 Gateway 主機上執行。請啟用沙箱化或使用 host=gateway 搭配核准。
腳本預檢查（針對常見的 Python/Node shell 語法錯誤）僅檢查有效 workdir 邊界內的檔案。如果腳本路徑解析到 workdir 之外，該檔案的預檢查會被跳過。

設定

tools.exec.notifyOnExit（預設：true）：啟用時，背景化的 exec 工作階段在退出時會排入系統事件並請求心跳。
tools.exec.approvalRunningNoticeMs（預設：10000）：核准閘控的 exec 執行超過此毫秒數時發出一次「running」通知（0 停用）。
tools.exec.host（預設：sandbox）
tools.exec.security（預設：沙箱為 deny，未設定時 gateway + node 為 allowlist）
tools.exec.ask（預設：on-miss）
tools.exec.node（預設：未設定）
tools.exec.pathPrepend：要前置到 PATH 的目錄清單，供 exec 執行使用（僅 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：將你的登入 shell 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（登入 shell），所以 /etc/profile 可能會重設 PATH。OpenClaw 在 profile 載入後透過內部環境變數前置 env.PATH（無 shell 內插）；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 或節點主機上執行前進行逐次核准。策略、允許清單和 UI 流程請參閱執行核准。

需要核准時，exec 工具會立即回傳 status: "approval-pending" 和一個核准 id。核准（或拒絕 / 逾時）後，Gateway 會發出系統事件（Exec finished / Exec denied）。如果指令在 tools.exec.approvalRunningNoticeMs 之後仍在執行，會發出一次 Exec running 通知。

允許清單 + 安全二進位檔

手動允許清單比對僅限解析後的二進位檔路徑（不比對基本名稱）。security=allowlist 時，shell 指令僅在管線中的每個區段都已列入允許清單或是安全二進位檔時才自動允許。串聯（;、&&、||）和重導向在 allowlist 模式下會被拒絕，除非每個頂層區段都滿足允許清單（包括安全二進位檔）。重導向仍不支援。

autoAllowSkills 是執行核准中的獨立便利路徑，與手動路徑允許清單條目不同。需要嚴格明確信任時，請保持 autoAllowSkills 停用。

將兩種控制用於不同的工作：

tools.exec.safeBins：小型、僅限 stdin 的串流篩選器。
tools.exec.safeBinTrustedDirs：安全二進位檔可執行檔路徑的額外明確受信任目錄。
tools.exec.safeBinProfiles：自訂安全二進位檔的明確 argv 策略。
允許清單：可執行檔路徑的明確信任。

不要把 safeBins 當成通用允許清單使用，也不要加入直譯器 / 執行環境二進位檔（例如 python3、node、ruby、bash）。如果需要使用這些，請用明確的允許清單條目並保持核准提示啟用。openclaw security audit 會在直譯器 / 執行環境 safeBins 條目缺少明確設定檔時發出警告，openclaw doctor --fix 可以建立遺失的自訂 safeBinProfiles 條目骨架。

完整的策略細節和範例請參閱執行核准和安全二進位檔與允許清單的比較。

範例

前景執行：

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

貼上（預設使用 bracketed paste）：

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