古法编程

Appearance

openclaw policy 命令检查当前 OpenClaw 工作区配置是否满足 policy.jsonc 中编写的合规规则。合规检查结果可以通过 openclaw policy check 查看，也会出现在 doctor --lint 中。Policy 不增加第二套配置系统，而是对现有设置做验证，目前支持渠道、MCP 服务器、模型提供商、网络 SSRF 姿势和受管工具声明。启用 Policy 插件后即可使用，默认只读，workspaceRepairs 可选开启自动修复。

OpenClaw policy 合规检查：配置、命令与故障排查 ​

openclaw policy 由 OpenClaw 自带的 Policy 插件提供。Policy 是一个企业级合规层，直接叠加在已有的 OpenClaw 设置之上，不会引入第二套配置系统。policy.jsonc 定义了你要求遵守的规则，OpenClaw 以当前工作区的实际状态作为证据，合规健康检查通过 doctor --lint 报告偏差。最终的合规信号就是一次干净的 doctor --lint 运行；Policy 的检查结果会合入同一个 lint 输出面，不会单独创建健康检查门禁。

目前 Policy 可以管理已配置的渠道、MCP 服务器、模型提供商、网络 SSRF 配置和受管工具声明。例如，IT 或工作区运维人员可以记录 Telegram 不是批准的渠道提供商，限制 MCP 服务器和模型引用到批准的列表，要求私有网络 fetch/browser 访问保持禁用，要求受管工具携带风险与敏感性元数据，然后使用 doctor --lint 作为统一的合规门禁。

什么时候用 Policy？ 当你需要一个持久的声明，比如“这些渠道不能启用”或“受管工具必须声明批准元数据”，并且还需要可重复的方式证明 OpenClaw 仍然符合该声明时，使用 Policy。如果你只需要本地行为，不需要 Policy 的检查结果或证明输出，那么直接使用常规配置和工作区文档即可。

快速开始 ​

首次使用前启用 Policy 插件：

bash
openclaw plugins enable policy

Policy 启用后，doctor 可以加载合规健康检查，而不需要激活任意插件。即使 policy.jsonc 文件缺失，插件仍然保持启用，这样 doctor 就可以报告缺失的文件。

Policy 文件是手写的，不是从用户当前设置自动生成的。一个最小化的 policy 示例（覆盖渠道、MCP 服务器、模型提供商、网络姿势和工具元数据）如下：

jsonc
{
  "channels": {
    "denyRules": [
      {
        "id": "no-telegram",
        "when": { "provider": "telegram" },
        "reason": "Telegram 未获批准用于此工作区。",
      },
    ],
  },
  "mcp": {
    "servers": {
      "allow": ["docs"],
      "deny": ["untrusted"],
    },
  },
  "models": {
    "providers": {
      "allow": ["openai", "anthropic"],
      "deny": ["openrouter"],
    },
  },
  "network": {
    "privateNetwork": {
      "allow": false,
    },
  },
  "tools": {
    "requireMetadata": ["risk", "sensitivity", "owner"],
  },
}

规则本身是权威。每个分类块只是一个命名空间；只有存在具体的规则时，对应的检查才会运行。OpenClaw 读取当前 channels.* 设置、mcp.servers.*、models.providers.*、选中的智能体模型引用、网络 SSRF 设置以及 TOOLS.md 中的声明作为证据，然后报告与规则不符的观察状态。

在编写 policy 时，可以只运行 policy 的检查：

bash
openclaw policy check
openclaw policy check --json
openclaw policy check --severity-min error

policy check 只运行 policy 检查集，输出证据、发现和证明哈希。同样的发现也会出现在 openclaw doctor --lint 中（当 Policy 插件启用时）。

干净的 JSON 输出示例，包含可以被运维人员或主管记录的稳定哈希：

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

配置 policy ​

Policy 配置位于 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 文件不存在时也启用 policy 检查。
workspaceRepairs允许 doctor --fix 编辑受 policy 管理的工作区设置。
expectedHash可选的哈希锁定，用于指定已批准的 policy 文件。
expectedAttestationHash可选的哈希锁定，用于上一次接受的干净 policy 检查结果。
pathpolicy 文件相对工作区的位置。

将 plugins.entries.policy.config.enabled 设为 false 可以禁用某个工作区的 policy 检查，同时保留插件已安装的状态。

工具元数据要求在 policy.jsonc 中通过 tools.requireMetadata 定义，例如 ["risk", "sensitivity", "owner"]。

接受 policy 状态 ​

以下是一个完整的 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
      }
    ],
    "tools": [
      {
        "id": "deploy",
        "source": "oc://TOOLS.md/tools/deploy",
        "line": 12,
        "risk": "critical",
        "sensitivity": "restricted",
        "capabilities": ["IRREVERSIBLE_EXTERNAL"]
      }
    ]
  },
  "checksRun": 15,
  "checksSkipped": 0,
  "findings": []
}
  • policy.hash 标识手写的规则文件。
  • evidence 块记录了 policy 检查所观察到的 OpenClaw 状态。
  • workspace.hash 标识该检查范围内的证据载荷。
  • findingsHash 标识本次检查返回的精确发现集。
  • checkedAt 记录评估运行的时间。
  • attestationHash 标识一个稳定声明：policy 哈希、证据哈希、发现哈希以及结果是否干净。它有意不包含 checkedAt，因此相同的 policy 状态在重复检查中会产生相同的证明哈希。这些元素共同构成了本次 policy 检查的审计元组。

如果后续的网关或监管者使用 policy 来阻止、批准或注释某个运行时动作，它应当记录上一次干净 policy 检查的证明哈希。checkedAt 保留在 JSON 输出中用于审计日志，但不参与稳定证明哈希。

接受 policy 状态的推荐生命周期：

  1. 编写或审查 policy.jsonc。
  2. 运行 openclaw policy check --json。
  3. 如果结果干净，记录 attestation.policy.hash 作为 expectedHash。
  4. 记录 attestation.attestationHash 作为 expectedAttestationHash。
  5. 在 CI 或发布门禁中重新运行 openclaw doctor --lint。

如果 policy 规则有意图的变更，从一次干净检查中更新两个接受哈希。如果工作区设置有意变更但 policy 不变，通常只需要更新 expectedAttestationHash。

openclaw policy watch 会重复运行同样的检查，并在当前证据不再匹配 expectedAttestationHash 时报告：

bash
openclaw policy watch --json

在 CI 或脚本中如果只需要一次漂移评估，请使用 --once。不带 --once 时，命令默认每两秒轮询一次；使用 --interval-ms 可以指定不同的间隔。

发现（Findings） ​

Policy 当前验证以下检查项：

检查 ID发现描述
policy/policy-jsonc-missingPolicy 已启用但 policy.jsonc 缺失。
policy/policy-jsonc-invalidPolicy 文件无法解析或包含格式错误的规则条目。
policy/policy-hash-mismatchPolicy 文件与配置的 expectedHash 不匹配。
policy/attestation-hash-mismatch当前 policy 证据不再匹配已接受的证明哈希。
policy/channels-denied-provider一个已启用的渠道匹配了渠道拒绝规则。
policy/mcp-denied-server配置的 MCP 服务器被 policy 拒绝。
policy/mcp-unapproved-server配置的 MCP 服务器不在 allowlist 中。
policy/models-denied-provider配置的模型提供商或模型引用使用了被拒绝的提供商。
policy/models-unapproved-provider配置的模型提供商或模型引用不在 allowlist 中。
policy/network-private-access-enabled私有网络 SSRF 逃生出口已启用，但 policy 要求其为禁用状态。
policy/tools-missing-risk-level受管工具声明缺少风险元数据。
policy/tools-unknown-risk-level受管工具声明使用了未知的风险值。
policy/tools-missing-sensitivity-token受管工具声明缺少敏感性元数据。
policy/tools-missing-owner受管工具声明缺少所有者元数据。
policy/tools-unknown-sensitivity-token受管工具声明使用了未知的敏感性值。

Policy 的发现可以同时包含 target 和 requirement。target 是不符合规则的观察到的工件；requirement 是导致该发现的 policy 规则。这两个值目前是地址形式（通常是 oc:// 路径），但字段名描述的是它们在 policy 中的角色，而不是地址格式。

示例 JSON 发现（渠道）：

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 未获批准用于此工作区。"
}

示例 JSON 发现（工具）：

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 发现（MCP）：

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 发现（模型提供商）：

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 发现（网络）：

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

修复（Repair） ​

doctor --lint 和 policy check 都是只读操作。

doctor --fix 只有在 workspaceRepairs 显式启用时才会编辑受 policy 管理的工作区设置。没有这个 opt-in，policy 只报告它会修复的内容但不会改动设置。

当前版本中，修复可以禁用那些在 OpenClaw 配置中已启用但被 channels.denyRules 拒绝的渠道。请只在 policy 文件经过审查后才启用 workspaceRepairs，因为一条有效的拒绝规则可以关闭一个已配置的渠道：

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

退出码 ​

命令012
policy check未发现达到阈值的发现。至少一个发现达到阈值。参数或运行时错误。
policy watch无发现且接受的哈希是最新的。存在发现或接受的证明已过期。参数或运行时错误。

相关文档 ​

常见问题 ​

如何启用或禁用 OpenClaw Policy 插件？ ​

启用：运行 openclaw plugins enable policy。禁用：在配置中将 plugins.entries.policy.config.enabled 设为 false。即使 policy.jsonc 缺失，只要插件启用，policy 检查就能运行。

openclaw policy check 和 doctor --lint 有什么区别？ ​

policy check 只运行 policy 相关的检查，并输出包含证明哈希的详细 JSON。doctor --lint 运行所有 lint 检查（包括 policy），但输出格式不同。两者在 Policy 插件启用时共用同一套发现结果。如果你需要干净的证明哈希用于审计，应使用 policy check --json。

Policy 检查失败怎么办？如何接受新的状态？ ​

先修复违规项（比如禁用被拒绝的渠道、添加缺失的元数据），然后重新运行 openclaw policy check --json。如果结果干净，记录输出的 attestation.policy.hash 和 attestation.attestationHash，并写入配置中的 expectedHash 和 expectedAttestationHash。之后再运行 doctor --lint 确认无发现。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策