使用 OpenClaw Exec Tool：高效執行工作區 Shell 指令

在開發過程中，頻繁切換終端機執行指令真的很耗神，特別是當你希望 AI 能幫你處理一些瑣碎的 shell 任務時。如何安全、高效地在工作區執行指令，同時還能管理好背景程序，是每個開發者都會遇到的挑戰。

如果你也遇過背景執行程序斷掉，或是權限控管搞得頭大，這篇關於 Exec tool 的介紹能幫你解決這些煩惱。

Exec tool

在工作區中執行 shell 指令。支援透過 process 進行前景與背景執行。 如果 process 被禁用，exec 會以同步方式執行，並忽略 yieldMs 或 background 參數。 背景會話的範圍限定在每個 agent；process 只能看到來自同一個 agent 的會話。

參數

• command (必要)
• workdir (預設為當前工作目錄)
• env (key/value 覆寫)
• yieldMs (預設 10000): 延遲後自動轉入背景
• background (bool): 立即轉入背景
• timeout (秒，預設 1800): 到期時刪除
• pty (bool): 在可用的情況下於虛擬終端執行（適用於僅限 TTY 的 CLI、編碼 agent、終端 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 host)；只有當提升權限解析為 full 時，才會強制執行 security=full

備註：

• host 預設為 auto：當會話的 sandbox runtime 處於活動狀態時為 sandbox，否則為 gateway。
• elevated 會強制設定 host=gateway；僅在當前會話或提供者啟用提升存取權時才可用。
• gateway 與 node 的審核由 ~/.openclaw/exec-approvals.json 控制。
• node 需要配對的 node（隨附應用程式或 headless node 主機）。
• 如果有多個 node 可用，請設定 exec.node 或 tools.exec.node 來選擇。
• exec host=node 是 node 唯一的 shell 執行路徑；舊有的 nodes.run 包裝已被移除。
• 在非 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 和 sandbox 執行），以便 shell 或設定檔規則可以偵測 exec-tool 上下文。
• 重要：沙盒功能 預設為關閉。如果沙盒關閉，隱含的 host=auto 會解析為 gateway。顯式的 host=sandbox 仍會失敗關閉，而不是默默地在 gateway 主機上執行。請啟用沙盒功能或搭配審核機制使用 host=gateway。
• 腳本預檢（針對常見的 Python/Node shell 語法錯誤）僅檢查有效 workdir 邊界內的檔案。如果腳本路徑解析到 workdir 之外，則會跳過該檔案的預檢。

設定

• tools.exec.notifyOnExit (預設: true): 設為 true 時，背景執行的 exec 會話在結束時會排入系統事件並請求 heartbeat。
• tools.exec.approvalRunningNoticeMs (預設: 10000): 當受審核限制的 exec 執行時間超過此值時，發出單次「執行中」通知（0 為禁用）。
• tools.exec.host (預設: auto；當 sandbox runtime 活動時解析為 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: 僅限 stdin 的安全二進位檔，無需顯式白名單條目即可執行。詳細行為請參閱 Safe bins (僅限 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 覆寫。守護進程 (daemon) 本身仍以最小化 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 會在載入設定檔後透過內部環境變數（無 shell 插值）在前端加上 env.PATH；tools.exec.pathPrepend 也適用於此。
• host=node: 只有你傳遞的非封鎖環境覆寫會被發送到 node。主機執行會拒絕 env.PATH 覆寫，且 node 主機會忽略它。如果你需要在 node 上增加 PATH 條目，請設定 node 主機服務環境 (systemd/launchd) 或將工具安裝在標準位置。

每個 agent 的 node 綁定（在設定中使用 agent 列表索引）：

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"] 或針對每個 agent）來拒絕。除非你顯式設定 security=full 且 ask=off，否則主機審核仍然適用。

Exec 審核 (隨附應用程式 / node 主機)

受沙盒保護的 agent 在 exec 於 gateway 或 node 主機執行前，可能需要逐次請求審核。 請參閱 Exec 審核 以了解策略、白名單和 UI 流程。

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

白名單與安全二進位檔 (Safe bins)

手動白名單強制執行僅比對 解析後的二進位檔路徑（不比對基本名稱）。當 security=allowlist 時，只有當每個管線片段都在白名單中或是安全二進位檔時，shell 指令才會被自動允許。除非每個頂層片段都符合白名單（包括安全二進位檔），否則在白名單模式下會拒絕鏈接（;, &&, ||）和重定向。重定向目前仍不支援。 持久的 allow-always 信任不會繞過此規則：鏈接指令仍然需要每個頂層片段都符合。

autoAllowSkills 是 exec 審核中一個獨立的便利路徑。它與手動路徑白名單條目不同。若要進行嚴格的顯式信任，請保持 autoAllowSkills 禁用。

針對不同工作使用這兩種控制項：

• tools.exec.safeBins: 小型的、僅限 stdin 的串流過濾器。
• tools.exec.safeBinTrustedDirs: 用於安全二進位檔執行路徑的顯式額外信任目錄。
• tools.exec.safeBinProfiles: 用於自定義安全二進位檔的顯式 argv 策略。
• 白名單: 對執行檔路徑的顯式信任。

不要將 safeBins 視為通用的白名單，也不要添加直譯器或運行時二進位檔（例如 python3, node, ruby, bash）。如果你需要這些，請使用顯式白名單條目並保持審核提示開啟。 當直譯器或運行時的 safeBins 條目缺少顯式 profile 時，openclaw security audit 會發出警告，而 openclaw doctor --fix 可以自動產生缺少的自定義 safeBinProfiles 條目。 如果你將行為廣泛的二進位檔（如 jq）加回 safeBins 時，openclaw security audit 和 openclaw doctor 也會發出警告。 如果你顯式將直譯器列入白名單，請啟用 tools.exec.strictInlineEval，這樣內嵌程式碼求值形式仍然需要新的審核。

如需完整的策略細節與範例，請參閱 Exec 審核 以及 安全二進位檔 vs 白名單。

範例

前景執行：

{ "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 模式）：

{ "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；將其設為 false 可為 OpenAI 模型禁用此工具。
• tools.exec.applyPatch.workspaceOnly 預設為 true（限制在工作區內）。只有當你刻意希望 apply_patch 在工作區目錄外進行寫入或刪除時，才將其設為 false。

相關文件

• Exec 審核 — shell 指令的審核關卡
• 沙盒功能 — 在沙盒環境中執行指令
• 背景程序 — 長時間執行的 exec 與 process 工具
• 安全性 — 工具策略與提升存取權

下一步

• 了解如何設定 Exec 審核 以強化安全性。
• 探索 沙盒環境 的配置方式。

AI Setup Assistant