執行工具

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

透過 process 支援前景與背景執行。如果不允許 process，exec 會同步執行，並忽略 yieldMs/background。背景工作階段依代理程式劃分範圍；process 只能看到來自同一代理程式的工作階段。

參數

注意事項：

• host 僅接受 auto、sandbox、gateway 或 node。它不是主機名稱選擇器；命令執行前會拒絕類似主機名稱的值。
• 每次呼叫的 host=node 可從 auto 使用；只有在未啟用沙箱執行階段時，才允許每次呼叫的 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 會在衍生的命令環境中設定 OPENCLAW_SHELL=exec（包括 PTY 與沙箱執行），讓 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 且有效原則為具備 ask=off 的 security=full 時，也會完全略過預檢。
• 對於現在開始的長時間工作，請只啟動一次；若已啟用自動完成喚醒，且命令產生輸出或失敗，便交由該機制處理。使用 process 查看日誌、狀態、輸入或進行介入；不要使用 sleep 迴圈、逾時迴圈或重複輪詢來模擬排程。
• 代理程式啟動的背景命令在完成前，會顯示於 Web、iOS 與 Android 的背景工作檢視中。工作帳本會在完成心跳偵測再次喚醒代理程式前完成最終處理。
• 對於應於稍後或依排程執行的工作，請使用排程，而非 exec sleep/延遲模式。

設定

閘道與節點（mode=full）預設會在不需核准的情況下執行主機 exec——這來自主機原則預設值，而非 host=auto。若要使用核准/允許清單行為，請設定 tools.exec.mode 並收緊主機核准檔案；請參閱 Exec 核准。若要無視沙箱狀態，強制路由至閘道或節點，請設定 tools.exec.host 或使用 /exec host=...。

範例：

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

模式

tools.exec.mode 是標準的持久化原則調整項目。執行階段安全性與核准行為皆衍生自此設定。

無論持久化模式為何，每個工作階段的 /exec ask=always 仍會每次都詢問人工。

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

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

行內 eval（strictInlineEval）

當 tools.exec.strictInlineEval 為 true 時，行內直譯器 eval 形式需要審查器或明確核准：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 仍可持久化無害的直譯器／指令碼叫用，但行內 eval 形式不會成為持久允許規則。

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

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

openclaw config get agents.entriesopenclaw config set 'agents.entries.main.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

只有透過頻道允許清單／配對和存取群組的已授權傳送者，其 /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 項目缺少明確設定檔時，openclaw security audit 會發出警告，而 openclaw doctor --fix 可建立缺少的自訂 safeBinProfiles 項目架構。當你明確將 jq 等行為廣泛的二進位檔重新加入 safeBins 時，openclaw security audit 和 openclaw doctor 也會發出警告（jq 可以讀取環境資料，並從模組或啟動檔案載入 jq 程式碼，因此應改用明確允許清單項目或受核准閘門控管的執行）。即使明確列出，jq 仍會遭拒作為安全二進位檔。如果明確將直譯器加入允許清單，請啟用 tools.exec.strictInlineEval，讓行內程式碼 eval 形式仍須經審查器或明確核准。

如需完整原則詳細資料與範例，請參閱 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 與程序工具
• 安全性 — 工具原則與提高權限存取