執行工具

Documentation Index

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

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

​

參數

• host 預設為 auto：當沙盒執行環境在此工作階段中處於作用中時使用沙盒，否則使用 Gateway。
• host 只接受 auto、sandbox、gateway 或 node。它不是主機名稱選擇器；類似主機名稱的值會在命令執行前被拒絕。
• auto 是預設路由策略，不是萬用字元。從 auto 允許逐次呼叫指定 host=node；只有在沒有作用中的沙盒執行環境時，才允許逐次呼叫指定 host=gateway。
• 沒有額外設定時，host=auto 仍然「可直接運作」：沒有沙盒時會解析為 gateway；有即時沙盒時則留在沙盒中。
• elevated 會逃出沙盒並進入設定的主機路徑：預設為 gateway，或當 tools.exec.host=node（或工作階段預設為 host=node）時使用 node。它只有在目前工作階段/提供者啟用提升存取權時才可用。
• gateway/node 核准由 ~/.openclaw/exec-approvals.json 控制。
• node 需要已配對的 Node（配套應用程式或無頭 Node 主機）。
• 如果有多個 Node 可用，請設定 exec.node 或 tools.exec.node 來選取其中一個。
• exec host=node 是 Node 的唯一 shell 執行路徑；舊版 nodes.run 包裝器已移除。
• timeout 適用於前景、背景、yieldMs、Gateway、沙盒與 Node system.run 執行。如果省略，OpenClaw 會使用 tools.exec.timeoutSec；明確指定 timeout: 0 會停用該次呼叫的 exec 程序逾時。
• 在非 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 會在產生的命令環境（包含 PTY 和沙盒執行）中設定 OPENCLAW_SHELL=exec，讓 shell/profile 規則可偵測 exec 工具情境。
• openclaw channels login 會被 exec 封鎖，因為它是互動式 channel 驗證流程；請在 Gateway 主機的終端機中執行，或在存在 channel 原生登入工具時從聊天使用該工具。
• 重要：沙盒預設為關閉。如果沙盒關閉，隱含的 host=auto 會解析為 gateway。明確指定 host=sandbox 仍會安全失敗，而不是靜默地 在 Gateway 主機上執行。請啟用沙盒，或搭配核准使用 host=gateway。
• 指令碼預先檢查（針對常見的 Python/Node shell 語法錯誤）只會檢查有效 workdir 邊界內的檔案。如果指令碼路徑解析到 workdir 外部，該檔案會略過預先檢查。
• 對於現在開始的長時間工作，請只啟動一次，並在啟用時依賴命令輸出或失敗所觸發的自動 完成喚醒。 使用 process 取得記錄、狀態、輸入或進行介入；不要用睡眠迴圈、逾時迴圈或重複輪詢來模擬排程。
• 對於應在稍後或依排程發生的工作，請使用 cron，而不是 exec 睡眠/延遲模式。

​

設定

• 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，否則解析為 gateway）
• tools.exec.security（預設：沙盒為 deny，未設定時 Gateway + Node 為 full）
• tools.exec.ask（預設：off）
• 無需核准的主機 exec 是 Gateway + Node 的預設值。如果你想要核准/允許清單行為，請同時收緊 tools.exec.* 和主機 ~/.openclaw/exec-approvals.json；請參閱 Exec 核准。
• YOLO 來自主機政策預設值（security=full、ask=off），不是來自 host=auto。如果你想強制 Gateway 或 Node 路由，請設定 tools.exec.host 或使用 /exec host=...。
• 在 security=full 加上 ask=off 模式中，主機 exec 會直接遵循已設定的政策；沒有額外的啟發式命令混淆預先篩選，也沒有指令碼預先檢查拒絕層。
• 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 仍可持久保存良性的直譯器/指令碼呼叫，但行內 eval 形式每次仍會提示。
• tools.exec.commandHighlighting（預設：false）：為 true 時，核准提示可在命令文字中醒目顯示由剖析器衍生的命令範圍。全域或針對每個 agent 設定為 true，即可在不變更 exec 核准政策的情況下啟用命令文字醒目提示。
• tools.exec.pathPrepend：要前置到 exec 執行 PATH 的目錄清單（僅 Gateway + 沙盒）。
• 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：只會將你傳入且未被封鎖的環境覆寫傳送到 Node。主機執行會拒絕 env.PATH 覆寫，Node 主機也會忽略它們。如果你需要在 Node 上新增 PATH 項目， 請設定 Node 主機服務環境（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 核准（配套應用程式 / Node 主機）

​

允許清單 + 安全二進位

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

​

範例

{ "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。
• deny: ["write"] 不會拒絕 apply_patch；請明確拒絕 apply_patch，或在也應封鎖修補寫入時使用 deny: ["group:fs"]。
• 設定位於 tools.exec.applyPatch 底下。
• tools.exec.applyPatch.enabled 預設為 true；將它設為 false 可對 OpenAI 模型停用此工具。
• tools.exec.applyPatch.workspaceOnly 預設為 true（限制在工作區內）。只有在你有意讓 apply_patch 寫入/刪除工作區目錄外部時，才將它設為 false。

​

相關

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