執行工具

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

參數

• host 預設為 auto：工作階段的 sandbox runtime 啟用時使用 sandbox，否則使用 gateway。
• host 只接受 auto、sandbox、gateway 或 node。它不是主機名稱選擇器；類似主機名稱的值會在命令執行前被拒絕。
• auto 是預設路由策略，不是萬用字元。允許從 auto 逐次呼叫使用 host=node；只有在沒有 sandbox runtime 啟用時，才允許逐次呼叫使用 host=gateway。
• 沒有額外設定時，host=auto 仍然「直接可用」：沒有 sandbox 時解析為 gateway；有即時 sandbox 時則留在 sandbox 中。
• elevated 會逃逸 sandbox 到設定的主機路徑：預設為 gateway，或在 tools.exec.host=node（或工作階段預設為 host=node）時為 node。只有目前工作階段/提供者啟用 elevated access 時才可用。
• gateway/node 核准由 ~/.openclaw/exec-approvals.json 控制。
• node 需要已配對的 node（companion app 或 headless node host）。
• 如果有多個 nodes 可用，請設定 exec.node 或 tools.exec.node 以選取其中一個。
• exec host=node 是 nodes 唯一的 shell 執行路徑；舊版 nodes.run 包裝器已移除。
• timeout 套用於前景、背景、yieldMs、gateway、sandbox 和 node system.run 執行。若省略，OpenClaw 會使用 tools.exec.timeoutSec；明確的 timeout: 0 會停用該次呼叫的 exec 處理程序逾時。
• 在非 Windows 主機上，exec 會在設定時使用 SHELL；如果 SHELL 是 fish，它會優先使用 PATH 中的 bash（或 sh） 以避免 fish 不相容的 scripts，若兩者都不存在，才回退到 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/profile 規則可以偵測 exec 工具情境。
• openclaw channels login 會被 exec 阻擋，因為它是互動式 channel-auth 流程；請在 gateway 主機上的終端機中執行，或在可用時從聊天使用 channel 原生登入工具。
• 重要：sandboxing 預設關閉。如果 sandboxing 關閉，隱含的 host=auto 會解析為 gateway。明確的 host=sandbox 仍會以失敗關閉，而不是悄悄 在 gateway 主機上執行。請啟用 sandboxing，或使用需要核准的 host=gateway。
• Script 預檢查（針對常見 Python/Node shell 語法錯誤）只會檢查有效 workdir 邊界內的檔案。 如果 script 路徑解析到 workdir 之外，該檔案會略過預檢。
• 對於現在開始的長時間執行工作，請只啟動一次，並在啟用時依賴自動 完成喚醒，以及命令輸出或失敗。 使用 process 查看日誌、狀態、輸入或介入；不要用 sleep 迴圈、timeout 迴圈或重複輪詢來模擬 排程。
• 對於稍後或按排程執行的工作，請使用 Cron，而不是 exec sleep/delay 模式。

​

設定

• tools.exec.notifyOnExit（預設：true）：為 true 時，移至背景的 exec 工作階段會在結束時排入系統事件並要求 Heartbeat。
• tools.exec.approvalRunningNoticeMs（預設：10000）：當受核准閘控的 exec 執行時間超過此值時，發出單一「running」通知（0 停用）。
• tools.exec.timeoutSec（預設：1800）：每個命令的預設 exec 逾時秒數。逐次呼叫的 timeout 會覆寫它；逐次呼叫的 timeout: 0 會停用 exec 處理程序逾時。
• tools.exec.host（預設：auto；sandbox runtime 啟用時解析為 sandbox，否則解析為 gateway）
• tools.exec.security（預設：sandbox 為 deny，未設定時 gateway + node 為 full）
• tools.exec.ask（預設：off）
• 無核准主機 exec 是 gateway + node 的預設值。如果你想要核准/allowlist 行為，請同時收緊 tools.exec.* 和主機 ~/.openclaw/exec-approvals.json；請參閱 Exec approvals。
• YOLO 來自主機政策預設值（security=full、ask=off），不是來自 host=auto。如果你想強制 gateway 或 node 路由，請設定 tools.exec.host 或使用 /exec host=...。
• 在 security=full 加上 ask=off 模式中，主機 exec 會直接遵循設定的政策；沒有額外的啟發式命令混淆預篩選或 script 預檢拒絕層。
• tools.exec.node（預設：未設定）
• tools.exec.strictInlineEval（預設：false）：為 true 時，內嵌直譯器 eval 形式，例如 python -c、node -e、ruby -e、perl -e、php -r、lua -e 和 osascript -e 一律需要明確核准。allow-always 仍可持久化良性的直譯器/script 呼叫，但 inline-eval 形式每次仍會提示。
• tools.exec.pathPrepend：要為 exec 執行前置到 PATH 的目錄清單（僅限 gateway + sandbox）。
• tools.exec.safeBins：僅 stdin 的安全二進位檔，可在沒有明確 allowlist 項目的情況下執行。行為詳細資訊請參閱 Safe bins。
• tools.exec.safeBinTrustedDirs：受信任以進行 safeBins 路徑檢查的其他明確目錄。PATH 項目永遠不會自動受信任。內建預設值為 /bin 和 /usr/bin。
• tools.exec.safeBinProfiles：每個 safe bin 的選用自訂 argv 政策（minPositional、maxPositional、allowedValueFlags、deniedFlags）。

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

​

PATH 處理

• host=gateway：將你的 login-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（login shell），因此 /etc/profile 可能會重設 PATH。 OpenClaw 會透過內部 env var 在 profile sourcing 後前置 env.PATH（無 shell interpolation）； tools.exec.pathPrepend 也會套用於此。
• host=node：只有你傳入且未被阻擋的 env 覆寫會傳送至 node。主機執行會拒絕 env.PATH 覆寫，node hosts 也會忽略它們。如果你需要在 node 上增加 PATH 項目， 請設定 node host 服務環境（systemd/launchd），或將工具安裝到標準位置。

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

​

工作階段覆寫（/exec）

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

​

授權模型

​

Exec approvals（companion app / node host）

​

Allowlist + safe bins

• tools.exec.safeBins：小型、僅 stdin 的串流篩選器。
• tools.exec.safeBinTrustedDirs：safe-bin 可執行檔路徑的明確額外受信任目錄。
• tools.exec.safeBinProfiles：自訂 safe bins 的明確 argv 政策。
• allowlist：可執行檔路徑的明確信任。

​

範例

{ "tool": "exec", "command": "ls -la" }

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

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

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​

apply_patch

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

• 僅適用於 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 工具
• 安全性 — 工具政策與提升權限存取