執行工具

在工作區中執行 shell 命令。exec 是可變更內容的 shell 操作介面：只要所選主機或沙箱檔案系統允許，命令就能在任何位置建立、編輯或刪除檔案。停用 OpenClaw 檔案系統工具（例如 write、edit 或 apply_patch）不會讓 exec 變成唯讀。

透過 process 支援前景與背景執行。如果不允許使用 process，exec 會同步執行，並忽略 yieldMs/background。背景工作階段的範圍以個別代理程式為限；process 只能看到同一代理程式的工作階段。

參數

注意事項：

• host 僅接受 auto、sandbox、gateway 或 node。它不是主機名稱選擇器；類似主機名稱的值會在命令執行前遭到拒絕。
• 從 auto 可允許每次呼叫指定 host=node；只有在沒有啟用沙箱執行環境時，才允許每次呼叫指定 host=gateway。
• 不需額外設定，host=auto 仍可「直接運作」：沒有沙箱時解析為 gateway；有運作中的沙箱時則留在沙箱內。
• elevated 會逸出沙箱，進入已設定的主機路徑：預設為 gateway；當 tools.exec.host=node（或工作階段預設值為 host=node）時則為 node。只有目前工作階段/提供者已啟用提升權限存取時才能使用。
• gateway/node 核准由主機核准檔案控制。
• node 需要已配對的節點（伴隨應用程式或無介面節點主機）。如果有多個節點可用，請設定 exec.node 或 tools.exec.node 來選擇其中一個。
• exec host=node 是節點唯一的 shell 執行路徑；舊版 nodes.run 包裝器已移除。
• 在非 Windows 主機上，exec 會在已設定時使用 SHELL；如果 SHELL 是 fish，會優先從 PATH 使用 bash（或 sh），以避免與 fish 不相容的 bash 語法，兩者都不存在時才退回使用 SHELL。
• 在 Windows 主機上，exec 會優先探索 PowerShell 7（pwsh）（依序搜尋 Program Files、ProgramW6432，然後是 PATH），再退回使用 Windows PowerShell 5.1。
• 在非 Windows 閘道主機上，bash 和 zsh exec 命令會使用啟動快照。OpenClaw 會從 shell 啟動檔案中擷取可載入的別名/函式及一小組安全環境設定，存入 $OPENCLAW_STATE_DIR/cache/shell-snapshots/，然後在每次 exec 命令前載入該快照。看似機密的變數會被排除；沙箱與節點 exec 不使用此快照。若要停用此快照路徑，請在閘道程序環境中設定 OPENCLAW_EXEC_SHELL_SNAPSHOT=0。
• 主機執行（gateway/node）會拒絕 env.PATH 和載入器覆寫（LD_*/DYLD_*），以防止二進位檔劫持或程式碼注入。
• OpenClaw 會在產生的命令環境中（包括 PTY 和沙箱執行）設定 OPENCLAW_SHELL=exec，讓 shell/設定檔規則能偵測 exec 工具情境。
• 對於源自頻道的執行，如果頻道有提供這些 ID，OpenClaw 也會在 OPENCLAW_CHANNEL_CONTEXT 中公開範圍受限的傳送者/聊天身分 JSON 承載資料。
• exec 無法執行 openclaw channels login 或 /approve shell 命令：openclaw channels login 是互動式頻道驗證流程，而 /approve 必須經由核准命令處理常式執行，不能透過 shell。請在閘道主機的終端機中執行頻道登入，或使用頻道專屬的登入代理程式工具（如果有，例如 whatsapp_login）。
• 重要：沙箱功能預設為關閉。如果沙箱功能關閉，隱含的 host=auto 會解析為 gateway。明確指定 host=sandbox 時仍會以失敗關閉，而不會靜默改在閘道主機上執行。請啟用沙箱功能，或搭配核准使用 host=gateway。
• 指令碼預檢（用於常見的 Python/Node shell 語法錯誤）只會檢查有效 workdir 邊界內的檔案。如果指令碼路徑解析到 workdir 之外，就會略過該檔案的預檢。當 host=gateway 且有效原則為 security=full 搭配 ask=off 時，也會完全略過預檢。
• 對於現在開始的長時間工作，只需啟動一次，並在已啟用自動完成喚醒，且命令產生輸出或失敗時，依賴自動完成喚醒。使用 process 取得記錄、狀態、輸入或進行介入；不要使用睡眠迴圈、逾時迴圈或重複輪詢來模擬排程。
• 對於應稍後或依排程執行的工作，請使用排程，而不是 exec 睡眠/延遲模式。

設定

閘道與節點預設會在不需核准的情況下執行主機 exec（security=full、ask=off）——這來自主機原則預設值，而不是 host=auto。如果你希望使用核准/允許清單行為，請同時收緊 tools.exec.* 與主機核准檔案；請參閱 Exec 核准。若要無論沙箱狀態為何都強制路由至閘道或節點，請設定 tools.exec.host 或使用 /exec host=...。

範例：

{  tools: {    exec: {      pathPrepend: ["~/bin", "/opt/oss/bin"],    },  },}

模式

tools.exec.mode 是正規化原則控制項。設定後會衍生 security/ask，且不能與明確的 tools.exec.security/tools.exec.ask 搭配使用。

無論模式為何，ask／ask=always 仍會每次都詢問人工。

自動審查核准僅供單次使用。在閘道上，OpenClaw 會將解析後的可執行檔路徑提供給審查器，並將執行鎖定於同一路徑。無法簡化為單一且可強制執行之計畫的命令（例如 heredoc、shell 展開或不支援的包裝程式引號），即使模型原本會允許，仍會改由人工核准。

尚未由明確執行階段或原生原則決定的 Codex app-server 命令核准，會使用人工核准流程。OpenClaw 不會針對這些要求執行其設定的 exec 審查器，因為 Codex 不會公開可強制執行的已解析可執行檔，因而無法將審查決定繫結至 Codex 實際執行的命令。

行內求值（strictInlineEval）

當 tools.exec.strictInlineEval 為 true 時，行內直譯器求值形式需要審查器或明確核准：python -c、node -e、ruby -e、perl -e、php -r、lua -e、osascript -e，以及其他受支援直譯器和命令載體（awk、find -exec、make、sed、xargs 等）的類似形式。在 mode=auto 中，一般 exec 核准流程可讓原生自動審查器允許明顯低風險的單次命令；直接呼叫節點主機的 system.run 仍需要明確核准，因為它們無法將命令交給人工核准流程。如果審查器要求，請求會轉交人工。allow-always 仍可永久允許無害的直譯器／指令碼呼叫，但行內求值形式不會成為持久的允許規則。

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
  • 為避免使用者 shell 設定（例如 ~/.zshenv 或 /etc/zshenv）在啟動時覆寫優先路徑，tools.exec.pathPrepend 項目會在執行前，安全地前置於 shell 命令內的最終 PATH。
• host=sandbox：在容器內執行 sh -lc（登入 shell），因此 /etc/profile 可能會重設 PATH。OpenClaw 會在載入 profile 後，透過內部環境變數前置 env.PATH（不進行 shell 插值）；tools.exec.pathPrepend 也適用於此處。
• host=node：只會將你傳入且未被封鎖的環境覆寫傳送至節點。主機執行會拒絕 env.PATH 覆寫，節點主機也會忽略它們。若需要在節點新增 PATH 項目，請設定節點主機服務環境（systemd／launchd），或將工具安裝於標準位置。

每個代理程式的節點繫結（在設定中使用代理程式清單索引）：

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

控制介面：裝置頁面包含一個小型的「Exec 節點繫結」面板，可設定相同項目。

工作階段覆寫（/exec）

使用 /exec 設定 host、security、ask 和 node 的每個工作階段預設值。不帶引數傳送 /exec 即可顯示目前值。

範例：

/exec host=auto security=allowlist ask=on-miss node=mac-1

只有已授權的傳送者（頻道允許清單／配對，加上 commands.useAccessGroups）可使用 /exec。它只會更新工作階段狀態，不會寫入設定。已授權的外部頻道傳送者可設定這些工作階段預設值。內部閘道／網頁聊天用戶端需要 operator.admin 才能永久保存這些值。

若要強制停用 exec，請透過工具原則拒絕它（tools.deny: ["exec"] 或每個代理程式的設定）。除非你明確設定 security=full 和 ask=off，否則主機核准仍然適用。

Exec 核准（伴隨應用程式／節點主機）

沙箱化代理程式可要求在閘道或節點主機上執行 exec 前，逐次核准每個請求。如需原則、允許清單及介面流程，請參閱 Exec 核准。

需要人工核准時，節點主機和非原生閘道流程會立即傳回 status: "approval-pending" 和核准 ID。原生聊天和網頁介面閘道流程則可改為在行內等待，並於核准後傳回最終命令結果。approval-pending 結果表示命令尚未開始，因此只有已核准的命令實際在行內執行時，才會出現前景備援警告。已核准的非同步執行會發出命令進度與完成系統事件（Exec running／Exec finished）；遭拒絕或逾時的核准為終止狀態，不會以拒絕系統事件喚醒代理程式工作階段。

在具有原生核准卡片／按鈕的頻道上，代理程式應優先使用該原生介面；只有工具結果明確指出無法使用聊天核准，或手動核准是唯一途徑時，才應包含手動 /approve 命令。

允許清單與安全執行檔

手動允許清單強制執行會比對已解析二進位檔路徑 glob 和裸命令名稱 glob。裸名稱只會比對透過 PATH 呼叫的命令，因此當命令為 rg 時，rg 可比對 /opt/homebrew/bin/rg，但不會比對 ./rg 或 /tmp/rg。

當 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 也會發出警告（jq 可讀取環境資料，並從模組或啟動檔案載入 jq 程式碼，因此應改用明確的允許清單項目或由核准控管的執行）。即使明確列出，jq 仍會被拒絕作為安全執行檔。若你明確允許列出直譯器，請啟用 tools.exec.strictInlineEval，以確保行內程式碼求值形式仍需要審查器或明確核准。

如需完整原則詳情與範例，請參閱 Exec 核准及安全執行檔與允許清單的比較。

範例

前景：

{ "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 的子工具，用於結構化的多檔案編輯。預設啟用，且任何模型供應商皆可使用；allowModels 可限制其使用。只有在你想停用它或限制特定模型使用時，才需使用設定：

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

注意事項：

• 工具原則仍然適用；allow: ["write"] 會隱含允許 apply_patch。
• deny: ["write"] 不會拒絕 apply_patch；若也應封鎖修補寫入，請明確拒絕 apply_patch，或使用 deny: ["group:fs"]。
• 設定位於 tools.exec.applyPatch 下。
• tools.exec.applyPatch.enabled 預設為 true；將其設為 false 即可停用工具。
• tools.exec.applyPatch.workspaceOnly 預設為 true（限制於工作區內）。只有在你確實想讓 apply_patch 在工作區目錄之外寫入／刪除時，才將其設為 false。
• tools.exec.applyPatch.allowModels 是可選的模型 ID 允許清單（原始格式，例如 gpt-5.4；或完整格式，例如 openai/gpt-5.4）。設定後，只有相符的模型能取得此工具；未設定時，所有模型皆可取得。

相關內容

• Exec 核准 — shell 命令的核准閘門
• 沙箱化 — 在沙箱化環境中執行命令
• 背景程序 — 長時間執行的 exec 與 process 工具
• 安全性 — 工具原則與提升權限存取