OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

政策

openclaw policy

openclaw policy 由隨附的 Policy 外掛提供。它是在現有 OpenClaw 設定之上的企業合規層，而不是第二套設定系統。你在 policy.jsonc 中撰寫需求；OpenClaw 會觀察作用中的工作區作為證據；policy 透過 doctor --lint 回報漂移。Policy 不會在請求時強制執行工具呼叫或改寫執行階段行為，也不會證明每個代理的憑證存放區，例如 auth-profiles.json。

Policy 會檢查已設定的通道、MCP 伺服器、模型供應商、網路 SSRF 態勢、入口/通道存取、閘道暴露與節點命令態勢、代理工作區存取、沙箱態勢、資料處理態勢、密鑰供應商/驗證設定檔態勢，以及受治理的工具中繼資料 (TOOLS.md)。當工作區需要持久且可檢查的聲明時使用它，例如「Telegram 不得啟用」或「受治理的工具必須宣告風險與擁有者中繼資料」。如果你只需要本機行為，且不需要證明或漂移偵測，單純設定就足夠。

快速開始

bash
openclaw plugins enable policy

即使缺少 policy.jsonc，外掛也會保持啟用，因此 doctor 可以回報缺少該成品，而不是默默略過檢查。

請手動撰寫 policy.jsonc；它不是從目前設定產生的。每個頂層區段都是規則命名空間：只有在其下存在具體規則時，檢查才會執行（不支援的區段或鍵會以 policy/policy-jsonc-invalid 失敗，而不是被默默忽略）。涵蓋每個支援區段的最小範例：

jsonc
{  "channels": {    "denyRules": [      {        "id": "no-telegram",        "when": { "provider": "telegram" },        "reason": "Telegram is not approved for this workspace.",      },    ],  },  "mcp": {    "servers": {      "allow": ["docs"],      "deny": ["untrusted"],    },  },  "models": {    "providers": {      "allow": ["openai", "anthropic"],      "deny": ["openrouter"],    },  },  "network": {    "privateNetwork": {      "allow": false,    },  },  "ingress": {    "session": {      "requireDmScope": "per-channel-peer",    },    "channels": {      "allowDmPolicies": ["pairing", "allowlist", "disabled"],      "denyOpenGroups": true,      "requireMentionInGroups": true,    },  },  "gateway": {    "exposure": {      "allowNonLoopbackBind": false,      "allowTailscaleFunnel": false,    },    "auth": {      "requireAuth": true,      "requireExplicitRateLimit": true,    },    "controlUi": {      "allowInsecure": false,    },    "remote": {      "allow": false,    },    "http": {      "denyEndpoints": ["chatCompletions", "responses"],      "requireUrlAllowlists": true,    },    "nodes": {      "denyCommands": ["system.run"],    },  },  "agents": {    "workspace": {      "allowedAccess": ["none", "ro"],      "denyTools": ["exec", "process", "write", "edit", "apply_patch"],    },  },  "dataHandling": {    "sensitiveLogging": {      "requireRedaction": true,    },    "telemetry": {      "denyContentCapture": true,    },    "retention": {      "requireSessionMaintenance": true,    },    "memory": {      "denySessionTranscriptIndexing": true,    },  },  "secrets": {    "requireManagedProviders": true,    "denySources": ["exec"],    "allowInsecureProviders": false,  },  "auth": {    "profiles": {      "requireMetadata": ["provider", "mode"],      "allowModes": ["api_key", "token"],    },  },  "execApprovals": {    "requireFile": true,    "defaults": { "allowSecurity": ["deny"] },    "agents": {      "allowSecurity": ["deny", "allowlist"],      "allowAutoAllowSkills": false,      "allowlist": { "expected": ["deploy", "status"] },    },  },  "tools": {    "requireMetadata": ["risk", "sensitivity", "owner"],    "profiles": {      "allow": ["messaging", "minimal"],    },    "fs": {      "requireWorkspaceOnly": true,    },    "exec": {      "allowSecurity": ["deny", "allowlist"],      "requireAsk": ["always"],      "allowHosts": ["sandbox"],    },    "elevated": {      "allow": false,    },    "denyTools": ["group:runtime", "group:fs"],  },}

以下是從下方規則表不容易看出的跨領域注意事項：

  • 在拒絕非 local loopback 繫結時省略 gateway.bind，代表你接受執行階段預設值；若要嚴格合規，請設定 gateway.bind: "loopback"。
  • 對於唯讀代理，請在適用的預設值/代理上將沙箱 mode 設為 all 或 non-main，並將 workspaceAccess 設為 none 或 ro。缺少沙箱模式或 off 沙箱模式不符合唯讀 policy。
  • agents.workspace.denyTools 接受 exec、process、write、edit、apply_patch。設定工具拒絕群組 group:fs（檔案變更）與 group:runtime（shell/程序）可滿足等效態勢。
  • 只有在存在 execApprovals 規則時，Exec-approvals 檢查才會讀取即時的 exec-approvals.json 成品；缺少或無效的成品是無法觀察的證據，不是合成通過。
  • 密鑰與驗證設定檔證據只會記錄供應商/來源態勢與 SecretRef 中繼資料，絕不記錄原始值。Policy 不會讀取或證明每個代理的憑證存放區，例如 auth-profiles.json。
  • 資料處理證據只是設定層級態勢（遮罩模式、遙測擷取切換、工作階段維護模式、逐字稿索引設定）。它不會檢查記錄、遙測匯出、逐字稿或記憶體檔案，且乾淨的結果不代表其中不存在個人資料或密鑰。

Policy 規則參考

以下每個規則都是選用；只有在規則存在時才會執行檢查。觀察到的狀態是現有 OpenClaw 設定或工作區中繼資料。

範圍化覆蓋

當特定代理或通道需要比頂層基準更嚴格的 policy 時，請使用 scopes.<scopeName>。範圍名稱只是一個標籤；比對使用範圍內的選擇器。覆蓋是加成的：全域規則仍會執行，而範圍化規則可以針對同一證據新增自己的發現。

選擇器 支援的區段 使用時機
agentIds tools, agents.workspace, sandbox, dataHandling.memory, execApprovals 一個或多個執行階段代理需要更嚴格的規則。
channelIds ingress.channels 一個或多個通道需要更嚴格的入口規則。

如果 agentIds 項目不存在於 agents.list[]，OpenClaw 會針對該執行階段代理 ID 以繼承的全域/預設態勢評估範圍化規則，而不是略過它。

jsonc
{  "tools": {    "exec": {      "allowHosts": ["sandbox", "node"],    },  },  "sandbox": {    "requireMode": ["all", "non-main"],  },  "scopes": {    "release-workspace": {      "agentIds": ["release-agent", "review-agent"],      "agents": {        "workspace": {          "allowedAccess": ["none", "ro"],        },      },    },    "release-lockdown": {      "agentIds": ["release-agent"],      "tools": {        "exec": {          "allowHosts": ["sandbox"],          "allowSecurity": ["deny", "allowlist"],          "requireAsk": ["always"],        },        "denyTools": ["exec", "process", "write", "edit", "apply_patch"],      },      "sandbox": {        "requireMode": ["all"],        "allowBackends": ["docker"],      },      "dataHandling": {        "memory": {          "denySessionTranscriptIndexing": true,        },      },    },    "shell-sandbox": {      "agentIds": ["shell-agent"],      "sandbox": {        "allowBackends": ["openshell"],        "containers": {          "requireReadOnlyMounts": false,        },      },    },    "telegram-ingress": {      "channelIds": ["telegram"],      "ingress": {        "channels": {          "allowDmPolicies": ["pairing"],          "denyOpenGroups": true,          "requireMentionInGroups": true,        },      },    },  },}

同一代理可以出現在多個範圍中，只要每個範圍治理不同欄位，如上所示。同一代理的重複範圍化欄位必須同等或更嚴格；較弱的重複聲明會被拒絕（允許清單是子集、拒絕清單是超集、必要布林值是固定值）。

容器態勢規則 (sandbox.containers.*) 只會針對相符代理的沙箱後端可暴露的證據進行檢查。如果後端無法觀察你為其啟用的規則，policy 會回報 policy/sandbox-container-posture-unobservable，而不是通過；請將容器規則範圍化到使用可暴露它們之後端的代理群組。

頂層 ingress.session.requireDmScope 維持全域；session.dmScope 不是可歸屬於通道的證據，因此不能透過 channelIds 範圍化。

policy.jsonc 中存在的每個範圍都必須有效且可強制執行。

通道

Policy 欄位 觀察到的狀態 使用時機
channels.denyRules[].when.provider channels.* 供應商與啟用狀態 拒絕來自供應商的已設定通道，例如 telegram。
channels.denyRules[].reason 發現訊息與修復提示內容 說明為何拒絕該供應商。

MCP 伺服器

Policy 欄位 觀察到的狀態 使用時機
mcp.servers.allow mcp.servers.* ID 要求每個已設定的 MCP 伺服器都在允許清單中。
mcp.servers.deny mcp.servers.* ID 拒絕特定已設定的 MCP 伺服器 ID。

模型供應商

Policy 欄位 觀察到的狀態 使用時機
models.providers.allow models.providers.* ID 與選取的模型參照 要求已設定供應商與選取的模型參照使用核准的供應商。
models.providers.deny models.providers.* ID 與選取的模型參照 依供應商 ID 拒絕已設定供應商與選取的模型參照。

網路

Policy 欄位 觀察到的狀態 使用時機
network.privateNetwork.allow 私有網路 SSRF 逃逸開關 設為 false，要求私有網路存取保持停用。

入口與通道存取

政策欄位 觀察到的狀態 使用時機
ingress.session.requireDmScope session.dmScope 要求經審查的直接訊息隔離範圍。
ingress.channels.allowDmPolicies channels.*.dmPolicy 和舊版頻道 DM 政策欄位 只允許經審查的直接訊息頻道政策。
ingress.channels.denyOpenGroups 頻道、帳號和群組入口政策 對已設定的頻道和帳號拒絕開放群組入口。
ingress.channels.requireMentionInGroups 頻道、帳號、群組、guild 和巢狀提及閘門設定 在群組入口開放或受提及閘門控管時要求提及閘門。

閘道

政策欄位 觀察到的狀態 使用時機
gateway.exposure.allowNonLoopbackBind gateway.bind 設為 false 以要求 local loopback 閘道繫結。
gateway.exposure.allowTailscaleFunnel Tailscale serve/funnel 閘道態勢 設為 false 以拒絕 Tailscale Funnel 暴露。
gateway.auth.requireAuth gateway.auth.mode 設為 true 以拒絕停用的閘道驗證。
gateway.auth.requireExplicitRateLimit gateway.auth.rateLimit 設為 true 以要求明確的驗證速率限制設定。
gateway.controlUi.allowInsecure Control UI 不安全的驗證/裝置/來源切換 設為 false 以拒絕不安全的 Control UI 暴露切換。
gateway.remote.allow 遠端閘道模式/設定 設為 false 以拒絕遠端閘道模式。
gateway.http.denyEndpoints 閘道 HTTP API 端點 拒絕端點 ID，例如 chatCompletions 或 responses。
gateway.http.requireUrlAllowlists 閘道 HTTP URL 擷取輸入 設為 true 以要求 URL 擷取輸入具備 URL 允許清單。
gateway.nodes.denyCommands gateway.nodes.denyCommands 要求在 OpenClaw 設定中拒絕精確的節點命令 ID，例如 system.run。

gateway.nodes.denyCommands 是精確、區分大小寫的拒絕超集合規則。 當政策必須證明 OpenClaw 設定已明確拒絕具特權的節點命令時，請使用它。 若部署有意允許具特權的節點命令，應在審查後更新 policy.jsonc，而不是只依賴 gateway.nodes.allowCommands。

Agent 工作區

政策欄位 觀察到的狀態 使用時機
agents.workspace.allowedAccess agents.defaults.sandbox.workspaceAccess 和 agents.list[].sandbox.workspaceAccess 只允許沙箱工作區存取值，例如 none 或 ro。
agents.workspace.denyTools 全域和每個 Agent 的工具拒絕設定 要求拒絕變更工具（exec、process、write、edit、apply_patch）。

沙箱態勢

政策欄位 觀察到的狀態 使用時機
sandbox.requireMode agents.defaults.sandbox.mode 和每個 Agent 的模式 只允許經審查的沙箱模式，例如 all 或 non-main。
sandbox.allowBackends agents.defaults.sandbox.backend 和每個 Agent 的後端 只允許經審查的沙箱後端，例如 docker。
sandbox.containers.denyHostNetwork 容器支援的沙箱/瀏覽器網路模式 拒絕主機網路模式。
sandbox.containers.denyContainerNamespaceJoin 容器支援的沙箱/瀏覽器網路模式 拒絕加入另一個容器網路命名空間。
sandbox.containers.requireReadOnlyMounts 容器支援的沙箱/瀏覽器掛載模式 要求掛載為唯讀。
sandbox.containers.denyContainerRuntimeSocketMounts 容器支援的沙箱/瀏覽器掛載目標 拒絕容器執行階段 socket 掛載。
sandbox.containers.denyUnconfinedProfiles 容器安全性設定檔態勢 拒絕無限制的容器安全性設定檔。
sandbox.browser.requireCdpSourceRange 沙箱瀏覽器 CDP 來源範圍 要求瀏覽器 CDP 暴露宣告來源範圍。

政策會將缺少的 sandbox.mode 視為其隱含預設值 off，因此 sandbox.requireMode 會將全新或未設定的沙箱回報為不在 允許清單（例如 ["all"]）內。

資料處理

政策欄位 觀察到的狀態 使用時機
dataHandling.sensitiveLogging.requireRedaction logging.redactSensitive 設為 true 以拒絕 logging.redactSensitive: "off"。
dataHandling.telemetry.denyContentCapture diagnostics.otel.captureContent 設為 true 以拒絕遙測內容擷取。
dataHandling.retention.requireSessionMaintenance session.maintenance.mode 設為 true 以要求有效的工作階段維護模式為 enforce。
dataHandling.memory.denySessionTranscriptIndexing memory.qmd.sessions.enabled 和 agents.*.memorySearch.experimental.sessionMemory 設為 true 以拒絕將工作階段逐字稿索引到記憶體中。

秘密

政策欄位 觀察到的狀態 使用時機
secrets.requireManagedProviders Config SecretRefs 和 secrets.providers.* 宣告 設為 true 以要求 SecretRefs 指向已宣告的提供者。
secrets.denySources 秘密提供者來源和 SecretRef 來源 拒絕來源，例如 exec、file 或另一個已設定的來源名稱。
secrets.allowInsecureProviders 不安全秘密提供者態勢旗標 設為 false 以拒絕選擇不安全態勢的提供者。

Exec 核准

Exec 核准檢查會讀取執行階段 exec-approvals.json 成品： 預設為 ~/.openclaw/exec-approvals.json，或在設定 OPENCLAW_STATE_DIR 時為 $OPENCLAW_STATE_DIR/exec-approvals.json。 execApprovals.defaults.* 或 execApprovals.agents.* 下的態勢規則要求可讀的成品證據；缺少或無效的成品會回報為 不可觀察的證據，而不是盡力通過。可讀後，省略的 欄位會繼承執行階段預設值：缺少的 defaults.security 為 full，而 缺少的 Agent security 會繼承該預設值。證據包含 defaults、 agents.*、agents.*.allowlist[].pattern、選用的 argPattern、有效的 autoAllowSkills 態勢，以及項目來源；絕不包含 socket path/token、 commandText、lastUsedCommand、已解析路徑或時間戳記。

政策欄位 觀察到的狀態 使用時機
execApprovals.requireFile 作用中執行階段 exec-approvals.json 路徑 設為 true 以要求核准成品存在且可剖析。
execApprovals.defaults.allowSecurity defaults.security，預設為 full 只允許已核准的預設核准安全模式。
execApprovals.agents.allowSecurity agents.*.security，繼承預設值 只允許已核准的每個 Agent 有效核准安全模式。
execApprovals.agents.allowAutoAllowSkills defaults.autoAllowSkills 和 agents.*.autoAllowSkills，繼承執行階段預設值 設為 false 以要求嚴格的手動允許清單，不含隱含的 skill 命令列介面核准。
execApprovals.agents.allowlist.expected 彙總的 agents.*.allowlist[] pattern 和選用 argPattern 項目 要求核准允許清單符合經審查的 pattern 集合。

範例：要求核准成品、拒絕寬鬆的預設值，並只允許 所選 Agent 使用經審查的 exec 核准態勢。

jsonc
{  "execApprovals": {    "requireFile": true,    "defaults": {      // Security modes: "deny", "allowlist", or "full".      // This default permits only the locked-down deny posture.      "allowSecurity": ["deny"],    },  },  "scopes": {    "restricted-shell": {      "agentIds": ["family-agent", "groups-agent"],      "execApprovals": {        "agents": {          // Selected agents may use reviewed allowlist posture, but not "full".          "allowSecurity": ["allowlist"],          // false means skill CLIs must appear in the reviewed allowlist instead of          // being implicitly approved by autoAllowSkills.          "allowAutoAllowSkills": false,          "allowlist": {            "expected": [              // Simple entry: exact reviewed executable pattern with no argPattern.              "travel-hub",              // Constrained entry: pattern plus reviewed argument regex.              { "pattern": "calendar-cli", "argPattern": "^sync\\b" },              "/bin/date",            ],          },        },      },    },  },}

驗證設定檔

政策欄位 觀察到的狀態 使用時機
auth.profiles.requireMetadata auth.profiles.* provider 和 mode metadata 要求設定驗證設定檔上有 provider 和 mode 等 metadata key。
auth.profiles.allowModes auth.profiles.*.mode 僅允許支援的驗證設定檔模式，例如 api_key、aws-sdk、oauth 或 token。

工具 metadata

政策欄位 觀察到的狀態 使用時機
tools.requireMetadata 受治理的 TOOLS.md declarations 要求受治理的工具宣告 risk、sensitivity 或 owner 等 metadata key。

工具姿態

政策欄位 觀察到的狀態 使用時機
tools.profiles.allow tools.profile 和 agents.list[].tools.profile 僅允許工具設定檔 id，例如 minimal、messaging 或 coding。
tools.fs.requireWorkspaceOnly tools.fs.workspaceOnly 和每個 agent 的 tools.fs 覆寫 設為 true 以要求僅限工作區的檔案系統工具姿態。
tools.exec.allowSecurity tools.exec.security 和每個 agent 的 exec security 僅允許 exec security 模式，例如 deny 或 allowlist。
tools.exec.requireAsk tools.exec.ask 和每個 agent 的 exec ask mode 要求核准姿態，例如 always。
tools.exec.allowHosts tools.exec.host 和每個 agent 的 exec host routing 僅允許 exec host routing 模式，例如 sandbox。
tools.elevated.allow tools.elevated.enabled 和每個 agent 的 elevated posture 設為 false 以要求 elevated tool mode 保持停用。
tools.alsoAllow.expected tools.alsoAllow 和每個 agent 的 tools.alsoAllow 要求精確的 alsoAllow 項目，並回報缺少或非預期新增的工具授權。
tools.denyTools tools.deny 和 agents.list[].tools.deny 要求已設定的工具拒絕清單包含工具 id 或群組，例如 group:runtime 和 group:fs。

執行檢查

撰寫期間執行僅限政策的檢查：

bash
openclaw policy checkopenclaw policy check --jsonopenclaw policy check --severity-min error

policy check 只會執行政策檢查集，並輸出證據、發現項目 和 attestation hashes。啟用 Policy 外掛時，相同的發現項目也會出現在 openclaw doctor --lint 中。

將 operator 政策檔與已撰寫的基準進行比較：

bash
openclaw policy compare --baseline official.policy.jsoncopenclaw policy compare --baseline official.policy.jsonc --policy policy.jsonc --json

policy compare 會檢查政策檔語法與政策檔語法；它不會 檢查執行階段狀態、證據、認證資料或 secret。它使用與 scoped overlays 相同的 規則 metadata：allowlist 必須保持相等或更窄， denylist 必須保持相等或更廣，必要布林值必須保持 其值，有序字串只能往設定順序中更嚴格的一端移動， 而精確清單必須相符。基準可以是 組織撰寫的政策；被檢查的政策可以加入更嚴格的值或 額外規則。當 top-level 被檢查規則同樣嚴格或更嚴格時， 可以滿足 scoped baseline rule。檔案之間的 scope 名稱不需要相符； 比較會依 selector（agentIds/channelIds）和欄位 keyed。

乾淨比較（--json）：

json
{  "ok": true,  "baselinePath": "official.policy.jsonc",  "policyPath": "policy.jsonc",  "rulesChecked": 3,  "findings": []}

乾淨的 policy check --json 輸出包含 operator 或 supervisor 可記錄的穩定 hash：

json
{  "ok": true,  "attestation": {    "policy": {      "path": "policy.jsonc",      "hash": "sha256:..."    },    "workspace": {      "scope": "policy",      "hash": "sha256:..."    },    "findingsHash": "sha256:...",    "attestationHash": "sha256:..."  },  "checksRun": 5,  "checksSkipped": 0,  "findings": []}

設定政策

政策設定位於 plugins.entries.policy.config 下。

jsonc
{  "plugins": {    "entries": {      "policy": {        "enabled": true,        "config": {          "enabled": true,          "path": "policy.jsonc",          "workspaceRepairs": false,          "expectedHash": "sha256:...",          "expectedAttestationHash": "sha256:...",        },      },    },  },}
設定 用途
enabled 即使 policy.jsonc 尚不存在，也啟用政策檢查。
workspaceRepairs 允許 doctor --fix 編輯由政策管理的工作區設定。
expectedHash 已核准政策 artifact 的選用 hash-lock。
expectedAttestationHash 上一次已接受乾淨政策檢查的選用 hash-lock。
path 政策 artifact 的工作區相對位置。

將 plugins.entries.policy.config.enabled 設為 false 可停用某個工作區的政策 檢查，同時保留外掛安裝。

接受政策狀態

JSON 輸出範例：

json
{  "ok": true,  "attestation": {    "checkedAt": "2026-05-10T20:00:00.000Z",    "policy": {      "path": "policy.jsonc",      "hash": "sha256:..."    },    "workspace": {      "scope": "policy",      "hash": "sha256:..."    },    "findingsHash": "sha256:...",    "attestationHash": "sha256:..."  },  "evidence": {    "channels": [      {        "id": "telegram",        "provider": "telegram",        "source": "oc://openclaw.config/channels/telegram",        "enabled": false      }    ],    "mcpServers": [      {        "id": "docs",        "transport": "stdio",        "source": "oc://openclaw.config/mcp/servers/docs",        "command": "npx"      }    ],    "modelProviders": [      {        "id": "openai",        "source": "oc://openclaw.config/models/providers/openai"      }    ],    "modelRefs": [      {        "ref": "openai/gpt-5.5",        "provider": "openai",        "model": "gpt-5.5",        "source": "oc://openclaw.config/agents/defaults/model"      }    ],    "network": [      {        "id": "browser-private-network",        "source": "oc://openclaw.config/browser/ssrfPolicy/dangerouslyAllowPrivateNetwork",        "value": false      }    ],    "gatewayExposure": [      {        "id": "gateway-bind",        "kind": "bind",        "source": "oc://openclaw.config/gateway/bind",        "value": "loopback",        "nonLoopback": false,        "explicit": true      }    ],    "agentWorkspace": [      {        "id": "agents-defaults-workspace-access",        "kind": "workspaceAccess",        "source": "oc://openclaw.config/agents/defaults/sandbox/workspaceAccess",        "scope": "defaults",        "value": "ro",        "sandboxMode": "all",        "sandboxModeSource": "oc://openclaw.config/agents/defaults/sandbox/mode",        "sandboxEnabled": true,        "explicit": true      },      {        "id": "agents-defaults-tool-exec",        "kind": "toolDeny",        "source": "oc://openclaw.config/tools/deny",        "scope": "defaults",        "tool": "exec",        "denied": true,        "explicit": true      }    ],    "secrets": [      {        "id": "vault",        "kind": "provider",        "source": "oc://openclaw.config/secrets/providers/vault",        "providerSource": "env"      },      {        "id": "oc://openclaw.config/models/providers/openai/apiKey",        "kind": "input",        "source": "oc://openclaw.config/models/providers/openai/apiKey",        "provenance": "secretRef",        "refSource": "env",        "refProvider": "vault"      }    ],    "authProfiles": [      {        "id": "github",        "source": "oc://openclaw.config/auth/profiles/github",        "validMetadata": true,        "provider": "github",        "mode": "token"      }    ],    "tools": [      {        "id": "deploy",        "source": "oc://TOOLS.md/tools/deploy",        "line": 12,        "risk": "critical",        "sensitivity": "restricted",        "capabilities": ["IRREVERSIBLE_EXTERNAL"]      }    ]  },  "checksRun": 30,  "checksSkipped": 0,  "findings": []}

attestation.policy.hash 會識別已撰寫的規則 artifact。evidence 會記錄檢查所使用的已觀察 OpenClaw 狀態，而 workspace.hash 會識別該證據 payload。findingsHash 會識別 精確的發現項目集。checkedAt 會記錄檢查執行時間。 attestationHash 會識別穩定 claim（policy hash、evidence hash、 findings hash，以及 clean/dirty state），並刻意排除 checkedAt， 因此相同的政策狀態永遠會產生相同的 attestation hash。這四個值 共同構成一次政策檢查的 audit tuple。

如果閘道或 supervisor 使用政策來封鎖、核准或註記 執行階段動作，它應該記錄上一次乾淨檢查的 attestation hash。 checkedAt 會保留在 JSON 輸出中供 audit log 使用，但不是 stable hash 的一部分。

接受政策狀態的生命週期：

  1. 撰寫或檢閱 policy.jsonc。
  2. 執行 openclaw policy check --json。
  3. 如果乾淨，將 attestation.policy.hash 記錄為 expectedHash。
  4. 將 attestation.attestationHash 記錄為 expectedAttestationHash。
  5. 在 CI 或 release gates 中重新執行 openclaw doctor --lint。

如果政策規則是刻意變更，請從乾淨檢查更新兩個已接受的雜湊。如果只有工作區設定變更（政策維持相同），通常只會變更 expectedAttestationHash。

啟用或升級 agents.workspace 規則會將 agentWorkspace 證據加入工作區雜湊與證明雜湊；啟用後請審查新的證據，並重新整理已接受的證明雜湊。啟用或升級工具姿態規則，也會以相同方式加入 toolPosture 證據。

openclaw policy watch 會重新執行檢查，並在目前證據不再符合 expectedAttestationHash 時回報：

bash
openclaw policy watch --json

在 CI 或需要單次漂移評估的指令碼中使用 --once。若沒有 --once，預設每兩秒輪詢一次；使用 --interval-ms 可變更間隔。

發現項目

檢查 ID 發現項目
policy/policy-jsonc-missing 政策已啟用，但缺少 policy.jsonc。
policy/policy-jsonc-invalid 政策無法剖析，或包含格式錯誤的規則項目。
policy/policy-hash-mismatch 政策不符合設定的 expectedHash。
policy/attestation-hash-mismatch 目前政策證據不再符合已接受的證明。
policy/policy-conformance-invalid 基準或受檢查的政策檔案含有無效的比較語法。
policy/policy-conformance-missing 受檢查的政策檔案缺少基準政策檔案要求的規則。
policy/policy-conformance-weaker 受檢查的政策檔案值比基準政策檔案更弱。
policy/channels-denied-provider 已啟用的頻道符合頻道拒絕規則。
policy/mcp-denied-server 已設定的 MCP 伺服器遭政策拒絕。
policy/mcp-unapproved-server 已設定的 MCP 伺服器位於允許清單之外。
policy/models-denied-provider 已設定的模型供應商或模型參照使用遭拒絕的供應商。
policy/models-unapproved-provider 已設定的模型供應商或模型參照位於允許清單之外。
policy/network-private-access-enabled 政策拒絕時，卻啟用了私人網路 SSRF 逃生出口。
policy/ingress-dm-policy-unapproved 頻道 DM 政策位於政策允許清單之外。
policy/ingress-dm-scope-unapproved session.dmScope 不符合政策要求的 DM 隔離範圍。
policy/ingress-open-groups-denied 政策拒絕開放群組入口時，頻道群組政策為 open。
policy/ingress-group-mention-required 政策要求提及閘門時，頻道或群組項目卻停用提及閘門。
policy/gateway-non-loopback-bind 政策拒絕時，Gateway 綁定姿態卻允許非 loopback 暴露。
policy/gateway-auth-disabled 政策要求驗證時，Gateway 驗證卻已停用。
policy/gateway-rate-limit-missing 政策要求時，Gateway 驗證速率限制姿態未明確設定。
policy/gateway-control-ui-insecure Gateway Control UI 的不安全暴露切換已啟用。
policy/gateway-tailscale-funnel 政策拒絕時，Gateway Tailscale Funnel 暴露卻已啟用。
policy/gateway-remote-enabled 政策拒絕時，Gateway 遠端模式卻處於啟用狀態。
policy/gateway-http-endpoint-enabled 政策拒絕時，Gateway HTTP API 端點卻已啟用。
policy/gateway-http-url-fetch-unrestricted Gateway HTTP URL 擷取輸入缺少必要的 URL 允許清單。
policy/gateway-node-command-denied 政策拒絕的節點命令未被 OpenClaw 設定拒絕。
policy/agents-workspace-access-denied Agent 沙盒模式或工作區存取位於政策允許清單之外。
policy/agents-tool-not-denied Agent 或預設設定未拒絕政策要求拒絕的工具。
policy/tools-profile-unapproved 已設定的全域或個別 Agent 工具設定檔位於允許清單之外。
policy/tools-fs-workspace-only-required 檔案系統工具未設定為僅限工作區路徑姿態。
policy/tools-exec-security-unapproved 執行安全模式位於政策允許清單之外。
policy/tools-exec-ask-unapproved 執行詢問模式位於政策允許清單之外。
policy/tools-exec-host-unapproved 執行主機路由位於政策允許清單之外。
policy/tools-elevated-enabled 政策拒絕時，提升權限工具模式卻已啟用。
policy/tools-also-allow-missing 已設定的 alsoAllow 清單缺少政策要求的項目。
policy/tools-also-allow-unexpected 已設定的 alsoAllow 清單包含政策未預期的項目。
policy/tools-required-deny-missing 全域或個別 Agent 工具拒絕清單未包含必要的遭拒絕工具。
policy/sandbox-mode-unapproved 沙盒模式位於政策允許清單之外。
policy/sandbox-backend-unapproved 沙盒後端位於政策允許清單之外。
policy/sandbox-container-posture-unobservable 已為無法觀察容器姿態的後端啟用容器姿態規則。
policy/sandbox-container-host-network-denied 容器支援的沙盒或瀏覽器使用主機網路模式。
policy/sandbox-container-namespace-join-denied 容器支援的沙盒或瀏覽器加入另一個容器命名空間。
policy/sandbox-container-mount-mode-required 容器支援的沙盒或瀏覽器掛載不是唯讀。
policy/sandbox-container-runtime-socket-mount 容器支援的沙盒或瀏覽器掛載暴露容器執行階段通訊端。
policy/sandbox-container-unconfined-profile 政策拒絕時，容器沙盒設定檔卻為不受限制。
policy/sandbox-browser-cdp-source-range-missing 政策要求時，沙盒瀏覽器 CDP 來源範圍缺失。
policy/data-handling-redaction-disabled 政策要求時，敏感記錄遮罩卻已停用。
policy/data-handling-telemetry-content-capture 政策拒絕時，遙測內容擷取卻已啟用。
policy/data-handling-session-retention-not-enforced 政策要求時，工作階段保留維護未強制執行。
policy/data-handling-session-transcript-memory-enabled 政策拒絕時，工作階段轉錄記憶索引卻已啟用。
policy/secrets-unmanaged-provider 設定 SecretRef 參照未在 secrets.providers 下宣告的供應商。
policy/secrets-denied-provider-source 設定秘密供應商或 SecretRef 使用政策拒絕的來源。
policy/secrets-insecure-provider 政策拒絕時，秘密供應商卻選擇使用不安全姿態。
policy/auth-profile-invalid-metadata 設定驗證設定檔缺少有效的供應商或模式中繼資料。
policy/auth-profile-unapproved-mode 設定驗證設定檔模式位於政策允許清單之外。
policy/exec-approvals-missing 政策要求 exec-approvals.json，但缺少該成品。
policy/exec-approvals-invalid 已設定的執行核准成品無法剖析。
policy/exec-approvals-default-security-unapproved 執行核准預設值使用位於政策允許清單之外的安全模式。
policy/exec-approvals-agent-security-unapproved 個別 Agent 的有效執行核准安全模式位於允許清單之外。
policy/exec-approvals-auto-allow-skills-enabled 政策拒絕時，執行核准 Agent 卻隱含自動允許 Skills 命令列介面。
policy/exec-approvals-allowlist-missing 核准允許清單缺少政策要求的模式。
policy/exec-approvals-allowlist-unexpected 核准允許清單包含政策未預期的模式。
policy/tools-missing-risk-level 受治理的工具宣告缺少風險中繼資料。
policy/tools-unknown-risk-level 受治理的工具宣告使用未知的風險值。
policy/tools-missing-sensitivity-token 受治理的工具宣告缺少敏感度中繼資料。
policy/tools-missing-owner 受治理的工具宣告缺少擁有者中繼資料。
policy/tools-unknown-sensitivity-token 受治理的工具宣告使用未知的敏感度值。

發現項目可以同時包含 target（觀察到不符合的工作區項目）與 requirement（使其成為發現項目的作者規則）。兩者目前都是 oc:// 位址字串，但欄位名稱描述的是政策角色，而不是位址格式。

發現項目範例：

json
{  "checkId": "policy/channels-denied-provider",  "severity": "error",  "message": "Channel 'telegram' uses denied provider 'telegram'.",  "source": "policy",  "path": "openclaw config",  "ocPath": "oc://openclaw.config/channels/telegram",  "target": "oc://openclaw.config/channels/telegram",  "requirement": "oc://policy.jsonc/channels/denyRules/#0",  "fixHint": "Telegram is not approved for this workspace."}
json
{  "checkId": "policy/tools-missing-risk-level",  "severity": "error",  "message": "TOOLS.md tool 'deploy' has no explicit risk classification.",  "source": "policy",  "path": "TOOLS.md",  "line": 12,  "ocPath": "oc://TOOLS.md/tools/deploy",  "target": "oc://TOOLS.md/tools/deploy",  "requirement": "oc://policy.jsonc/tools/requireMetadata"}
json
{  "checkId": "policy/mcp-unapproved-server",  "severity": "error",  "message": "MCP server 'remote' is not in the policy allowlist.",  "source": "policy",  "path": "openclaw config",  "ocPath": "oc://openclaw.config/mcp/servers/remote",  "target": "oc://openclaw.config/mcp/servers/remote",  "requirement": "oc://policy.jsonc/mcp/servers/allow"}
json
{  "checkId": "policy/models-unapproved-provider",  "severity": "error",  "message": "Model ref 'anthropic/claude-sonnet-4.7' uses unapproved provider 'anthropic'.",  "source": "policy",  "path": "openclaw config",  "ocPath": "oc://openclaw.config/agents/defaults/model/fallbacks/#0",  "target": "oc://openclaw.config/agents/defaults/model/fallbacks/#0",  "requirement": "oc://policy.jsonc/models/providers/allow"}
json
{  "checkId": "policy/network-private-access-enabled",  "severity": "error",  "message": "Network setting 'browser-private-network' allows private-network access.",  "source": "policy",  "path": "openclaw config",  "ocPath": "oc://openclaw.config/browser/ssrfPolicy/dangerouslyAllowPrivateNetwork",  "target": "oc://openclaw.config/browser/ssrfPolicy/dangerouslyAllowPrivateNetwork",  "requirement": "oc://policy.jsonc/network/privateNetwork/allow"}
json
{  "checkId": "policy/gateway-non-loopback-bind",  "severity": "error",  "message": "Gateway bind setting 'gateway-bind' permits non-loopback exposure.",  "source": "policy",  "path": "openclaw config",  "ocPath": "oc://openclaw.config/gateway/bind",  "target": "oc://openclaw.config/gateway/bind",  "requirement": "oc://policy.jsonc/gateway/exposure/allowNonLoopbackBind"}
json
{  "checkId": "policy/gateway-node-command-denied",  "severity": "error",  "message": "Gateway node command 'system.run' is denied by policy but not denied by OpenClaw config.",  "source": "policy",  "path": "openclaw config",  "ocPath": "oc://openclaw.config/gateway/nodes/denyCommands",  "target": "oc://openclaw.config/gateway/nodes/denyCommands",  "requirement": "oc://policy.jsonc/gateway/nodes/denyCommands",  "fixHint": "Add 'system.run' to gateway.nodes.denyCommands or update policy after review."}
json
{  "checkId": "policy/agents-workspace-access-denied",  "severity": "error",  "message": "agents.defaults sandbox workspaceAccess 'rw' is not allowed by policy.",  "source": "policy",  "path": "openclaw config",  "ocPath": "oc://openclaw.config/agents/defaults/sandbox/workspaceAccess",  "target": "oc://openclaw.config/agents/defaults/sandbox/workspaceAccess",  "requirement": "oc://policy.jsonc/agents/workspace/allowedAccess"}

修復

doctor --lint 和 policy check 為唯讀。

只有在明確啟用 workspaceRepairs 時，doctor --fix 才會編輯由政策管理的工作區設定；否則檢查只會回報它們會修復的內容，並保持設定不變。

在此版本中，修復可以停用被 channels.denyRules 拒絕的頻道，並套用下列自動縮窄修復。只有在政策檔已完成審查後，才啟用 workspaceRepairs，因為有效規則可能會變更工作區設定：

  • 當全域政策禁止提升權限工具時，設定 tools.elevated.enabled=false
  • 當政策要求拒絕這些工具時，將缺少的必要拒絕工具 ID 新增至 tools.deny 或 agents.list[].tools.deny
  • 將不安全的 gateway.controlUi.* 開關設定為 false
  • 當政策拒絕遠端閘道模式時，設定 gateway.mode=local
  • 當政策要求遮蔽敏感記錄時，設定 logging.redactSensitive=tools
  • 當政策拒絕擷取遙測內容時，設定 diagnostics.otel.captureContent=false，或針對物件形式的遙測 擷取設定，設定 diagnostics.otel.captureContent.enabled=false

作用域提升權限工具修復僅會偵測。當發現項目回報共用記錄或遙測設定時，也會略過作用域資料處理修復， 因為變更共用設定會影響超出作用域政策目標的範圍。

當發現項目回報繼承自根層級的 tools.deny 時，會略過作用域必要拒絕修復，因為將必要工具新增至根設定 會影響超出作用域政策目標的範圍。代理程式本機的必要拒絕修復可以更新回報的 agents.list[].tools.deny 路徑。

jsonc
{  "plugins": {    "entries": {      "policy": {        "config": {          "workspaceRepairs": true,        },      },    },  },}

退出代碼

Command 0 1 2
policy check 在門檻值下沒有發現項目。 一個或多個發現項目符合門檻值。 引數或執行階段失敗。
policy compare 政策檔至少與基準一樣嚴格。 政策檔無效、缺少，或比基準規則更寬鬆。 引數或執行階段失敗。
policy watch 沒有發現項目，且已接受的雜湊為最新。 存在發現項目，或已接受的證明已過期。 引數或執行階段失敗。

相關

Was this useful?
On this page

On this page