執行核准

Exec 核准是配套 App / Node 主機防護機制，用於讓沙盒化代理在真實主機（gateway 或 node）上執行命令。一個安全聯鎖機制：只有在政策 + 允許清單 +（選用）使用者核准全都一致同意時，才允許命令執行。Exec 核准會疊加在工具政策與提升權限閘控之上（除非 elevated 設為 full，這會略過核准）。

# 檢查有效政策

當本機範圍要求 host=node 時，exec-policy show 會將該範圍回報為執行階段由 Node 管理，而不是假裝本機核准檔案就是事實來源。

如果配套 App UI 不可用，任何通常會提示的要求都會由 ask 後援解析（預設：deny）。

# 適用位置

Exec 核准會在執行主機本機強制執行：

• Gateway 主機 → Gateway 機器上的 openclaw 程序。
• Node 主機 → Node 執行器（macOS 配套 App 或無頭 Node 主機）。

# 信任模型

• Gateway 驗證的呼叫者是該 Gateway 的受信任操作者。
• 已配對的 Node 會將該受信任操作者能力延伸到 Node 主機。
• Exec 核准可降低意外執行風險，但不是每位使用者的驗證邊界。
• 已核准的 Node 主機執行會綁定標準執行內容：標準 cwd、精確 argv、存在時的 env 綁定，以及適用時釘選的可執行檔路徑。
• 對於 shell 指令碼與直接的直譯器/執行階段檔案呼叫，OpenClaw 也會嘗試綁定一個具體的本機檔案運算元。如果該綁定檔案在核准後、執行前發生變更，該次執行會被拒絕，而不是執行已漂移的內容。
• 檔案綁定刻意採取最佳努力，不是每個直譯器/執行階段載入器路徑的完整語意模型。如果核准模式無法識別出剛好一個要綁定的具體本機檔案，它會拒絕簽發由核准支援的執行，而不是假裝有完整涵蓋。

# macOS 分流

• Node 主機服務會透過本機 IPC 將 system.run 轉送到 macOS App。
• macOS App會強制執行核准，並在 UI 內容中執行命令。

# 設定與儲存

核准資料位於執行主機上的本機 JSON 檔案：

~/.openclaw/exec-approvals.json

結構範例：

{
  "version": 1,
  "socket": {
    "path": "~/.openclaw/exec-approvals.sock",
    "token": "base64url-token"
  },
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
          "pattern": "~/Projects/**/bin/rg",
          "source": "allow-always",
          "commandText": "rg -n TODO",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

# 政策旋鈕

# exec.security

# exec.ask

# askFallback

# tools.exec.strictInlineEval

strict 模式會攔截的範例：

• python -c
• node -e, node --eval, node -p
• ruby -e
• perl -e, perl -E
• php -r
• lua -e
• osascript -e

在 strict 模式中，這些命令仍需要明確核准，而且 allow-always 不會自動為它們保留新的允許清單項目。

# YOLO 模式（無需核准）

如果你想讓主機 exec 不經核准提示即可執行，必須開放兩個政策層 - OpenClaw 設定中的要求 exec 政策（tools.exec.*）以及 ~/.openclaw/exec-approvals.json 中的主機本機核准政策。

除非你明確收緊，否則 YOLO 是預設主機行為：

公開自身非互動式權限模式的 CLI 後端提供者可以遵循此政策。當 OpenClaw 要求的 exec 政策為 YOLO 時，Claude CLI 會加入 --permission-mode bypassPermissions。可在 agents.defaults.cliBackends.claude-cli.args / resumeArgs 下使用明確的 Claude 引數覆寫該後端行為 - 例如 --permission-mode default、acceptEdits 或 bypassPermissions。

如果你想要更保守的設定，請將任一層收緊回 allowlist / on-miss 或 deny。

# 持久 Gateway 主機「永不提示」設定

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart

openclaw approvals set --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

# 本機捷徑

openclaw exec-policy preset yolo

該本機捷徑會同時更新：

• 本機 tools.exec.host/security/ask。
• 本機 ~/.openclaw/exec-approvals.json 預設值。

它刻意僅限本機。若要遠端變更 Gateway 主機或 Node 主機核准，請使用 openclaw approvals set --gateway 或 openclaw approvals set --node <id|name|ip>。

# Node 主機

對於 Node 主機，請改為在該 Node 上套用相同的核准檔案：

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

# 僅限工作階段的捷徑

• /exec security=full ask=off 只會變更目前工作階段。
• /elevated full 是一個緊急捷徑，也會在該工作階段略過 exec 核准。

如果主機核准檔案仍比設定更嚴格，較嚴格的主機政策仍會勝出。

# 允許清單（每個代理）

允許清單是每個代理各自獨立的。如果存在多個代理，請在 macOS App 中切換你正在編輯的代理。模式是 glob 比對。

模式可以是解析後的二進位檔路徑 glob，也可以是不含路徑的命令名稱 glob。不含路徑的名稱只會比對透過 PATH 呼叫的命令，因此當命令是 rg 時，rg 可以比對 /opt/homebrew/bin/rg，但不會比對 ./rg 或 /tmp/rg。當你想信任某個特定二進位檔位置時，請使用路徑 glob。

舊版 agents.default 項目會在載入時遷移到 agents.main。像 echo ok && pwd 這類 shell 鏈仍需要每個頂層區段都符合允許清單規則。

範例：

• rg
• ~/Projects/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

# 使用 argPattern 限制引數

當允許清單項目應比對二進位檔與特定引數形狀時，請加入 argPattern。OpenClaw 會針對剖析後的命令引數評估規則運算式，但排除可執行檔 token（argv[0]）。對於手寫項目，引數會以單一空格串接，因此需要精確比對時請錨定模式。

{
  "version": 1,
  "agents": {
    "main": {
      "allowlist": [
        {
          "pattern": "python3",
          "argPattern": "^safe\\.py$"
        }
      ]
    }
  }
}

該項目允許 python3 safe.py；python3 other.py 會是允許清單未命中。如果同一個二進位檔也存在只含路徑的項目，未相符的引數仍可退回到該只含路徑的項目。當目標是將二進位檔限制為宣告的引數時，請省略只含路徑的項目。

核准流程儲存的項目可以使用內部分隔符格式進行精確 argv 比對。請優先使用 UI 或核准流程重新產生這些項目，而不是手動編輯編碼值。如果 OpenClaw 無法剖析某個命令區段的 argv，含有 argPattern 的項目不會相符。

每個允許清單項目支援：

# 自動允許 Skills CLI

啟用 自動允許 Skills CLI 時，已知 Skills 參照的可執行檔會在節點（macOS 節點或無介面節點主機）上被視為列入允許清單。這會透過 Gateway RPC 使用 skills.bins 來擷取 Skills bin 清單。如果你想使用嚴格的手動允許清單，請停用此選項。

# 安全 bin 與核准轉發

如需安全 bin（僅 stdin 快速路徑）、直譯器繫結詳細資訊，以及如何將核准提示轉發到 Slack/Discord/Telegram（或將它們作為原生核准用戶端執行），請參閱Exec 核准 - 進階。

# Control UI 編輯

使用 Control UI → 節點 → Exec 核准 卡片來編輯預設值、個別代理覆寫和允許清單。選擇範圍（預設值或某個代理）、調整政策、新增/移除允許清單模式，然後按 儲存。UI 會顯示每個模式的上次使用中繼資料，方便你保持清單整潔。

目標選擇器會選擇 Gateway（本機核准）或 Node。節點必須公告 system.execApprovals.get/set（macOS app 或無介面節點主機）。如果某個節點尚未公告 exec 核准，請直接編輯其本機 ~/.openclaw/exec-approvals.json。

CLI：openclaw approvals 支援 Gateway 或節點編輯 - 請參閱核准 CLI。

# 核准流程

需要提示時，Gateway 會向操作員用戶端廣播 exec.approval.requested。Control UI 和 macOS app 會透過 exec.approval.resolve 解析它，然後 Gateway 會將已核准的請求轉發給節點主機。

對於 host=node，核准請求會包含標準 systemRunPlan 酬載。Gateway 會在轉發已核准的 system.run 請求時，使用該計畫作為權威的 command/cwd/session 情境。

這對非同步核准延遲很重要：

• 節點 exec 路徑會預先準備一個標準計畫。
• 核准記錄會儲存該計畫及其繫結中繼資料。
• 一旦核准，最終轉發的 system.run 呼叫會重用已儲存的計畫，而不是信任後續呼叫端的編輯。
• 如果呼叫端在核准請求建立後變更 command、rawCommand、cwd、agentId 或 sessionKey，Gateway 會因核准不相符而拒絕轉發的執行。

# 系統事件

Exec 生命週期會顯示為系統訊息：

• Exec running（僅在命令超過執行中通知閾值時）。
• Exec finished。
• Exec denied。

這些會在節點回報事件後發布到代理的工作階段。Gateway 主機 exec 核准會在命令完成時（以及選擇性地在執行時間超過閾值時）發出相同的生命週期事件。受核准控管的 exec 會在這些訊息中重用核准 ID 作為 runId，方便關聯追蹤。

# 核准遭拒的行為

非同步 exec 核准遭拒時，OpenClaw 會防止代理重用同一工作階段中相同命令先前任何執行的輸出。拒絕原因會搭配明確指引傳遞，說明沒有可用的命令輸出，這會阻止代理聲稱有新輸出，或以先前成功執行的舊結果重複遭拒的命令。

# 影響

• full 功能強大；可行時請優先使用允許清單。
• ask 讓你仍在流程中，同時仍允許快速核准。
• 個別代理允許清單會防止某個代理的核准外洩到其他代理。
• 核准只套用於來自已授權傳送者的主機 exec 請求。未授權的傳送者無法發出 /exec。
• /exec security=full 是授權操作員的工作階段層級便利功能，依設計會略過核准。若要硬性封鎖主機 exec，請將核准安全性設為 deny，或透過工具政策拒絕 exec 工具。

# 相關