@@ -0,0 +1,194 @@
1+---
2+summary: "CLI reference for `openclaw policy` channel conformance checks"
3+read_when:
4+ - You want to check OpenClaw settings against an authored policy.jsonc
5+ - You want policy findings in doctor lint
6+ - You need a policy attestation hash for audit evidence
7+title: "Policy"
8+---
9+10+# `openclaw policy`
11+12+`openclaw policy` is provided by the bundled Policy plugin. Policy is an
13+enterprise conformance layer over existing OpenClaw settings: `policy.jsonc`
14+defines authored requirements, OpenClaw observes the active workspace as
15+evidence, and policy health checks report drift through `doctor --lint`.
16+17+This first policy slice manages configured channels. For example, IT can record
18+that Telegram is not approved, then `doctor --lint` reports any enabled Telegram
19+channel and `doctor --fix` can turn it off when workspace repairs are explicitly
20+enabled.
21+22+## Quick start
23+24+Enable the bundled Policy plugin before first use:
25+26+```bash
27+openclaw plugins enable policy
28+```
29+30+When policy is enabled, doctor can load policy health checks without activating
31+arbitrary plugins. The plugin remains enabled if `policy.jsonc` is missing, so
32+doctor can report the missing artifact.
33+34+Policy is authored, not generated from the user's current settings. A minimal
35+channel policy looks like this:
36+37+```jsonc
38+{
39+"channels": {
40+"denyRules": [
41+ {
42+"id": "no-telegram",
43+"when": { "provider": "telegram" },
44+"reason": "Telegram is not approved for this workspace.",
45+ },
46+ ],
47+ },
48+}
49+```
50+51+The rules are the authority. A category block is only a namespace; checks run
52+when a concrete rule is present. OpenClaw reads current `channels.*` settings
53+and reports settings that do not conform.
54+55+Run policy-only checks during authoring:
56+57+```bash
58+openclaw policy check
59+openclaw policy check --json
60+openclaw policy check --severity-min error
61+```
62+63+`policy check` runs only the policy check set and emits evidence, findings, and
64+attestation hashes. The same findings also appear in `openclaw doctor --lint`
65+when the Policy plugin is enabled.
66+67+Example clean JSON output includes stable hashes that can be recorded by an
68+operator or supervisor:
69+70+```json
71+{
72+"ok": true,
73+"attestation": {
74+"policy": {
75+"path": "policy.jsonc",
76+"hash": "sha256:..."
77+ },
78+"workspace": {
79+"scope": "policy",
80+"hash": "sha256:..."
81+ },
82+"findingsHash": "sha256:...",
83+"attestationHash": "sha256:..."
84+ },
85+"checksRun": 5,
86+"checksSkipped": 0,
87+"findings": []
88+}
89+```
90+91+## Configure policy
92+93+Policy config lives under `plugins.entries.policy.config`.
94+95+```jsonc
96+{
97+"plugins": {
98+"entries": {
99+"policy": {
100+"enabled": true,
101+"config": {
102+"enabled": true,
103+"path": "policy.jsonc",
104+"workspaceRepairs": false,
105+"expectedHash": "sha256:...",
106+"expectedAttestationHash": "sha256:...",
107+ },
108+ },
109+ },
110+ },
111+}
112+```
113+114+| Setting | Purpose |
115+| ------------------------- | --------------------------------------------------------------- |
116+| `enabled` | Enable policy checks even before `policy.jsonc` exists. |
117+| `workspaceRepairs` | Allow `doctor --fix` to edit policy-managed workspace settings. |
118+| `expectedHash` | Optional hash-lock for the approved policy artifact. |
119+| `expectedAttestationHash` | Optional hash-lock for the last accepted clean policy check. |
120+| `path` | Workspace-relative location of the policy artifact. |
121+122+Set `plugins.entries.policy.config.enabled` to `false` to disable policy checks
123+for a workspace while leaving the plugin installed.
124+125+## Accept policy state
126+127+The attestation hash identifies the stable claim: policy hash, evidence hash,
128+findings hash, and whether the result was clean. It intentionally does not
129+include `checkedAt`, so the same policy state produces the same attestation
130+across repeated checks.
131+132+If a later gateway or supervisor uses policy to block, approve, or annotate a
133+runtime action, it should record the attestation hash from the last clean policy
134+check. `checkedAt` stays in JSON output for audit logs, but is not part of the
135+stable attestation hash.
136+137+Use this lifecycle when accepting policy state:
138+139+1. Author or review `policy.jsonc`.
140+2. Run `openclaw policy check --json`.
141+3. If the result is clean, record `attestation.policy.hash` as `expectedHash`.
142+4. Record `attestation.attestationHash` as `expectedAttestationHash`.
143+5. Re-run `openclaw doctor --lint` in CI or release gates.
144+145+If policy rules change intentionally, update both accepted hashes from a clean
146+check. If workspace settings change intentionally but policy stays the same,
147+only `expectedAttestationHash` usually changes.
148+149+## Findings
150+151+Policy currently verifies:
152+153+| Check id | Finding |
154+| ---------------------------------- | ------------------------------------------------------------------- |
155+| `policy/policy-jsonc-missing` | Policy is enabled but `policy.jsonc` is missing. |
156+| `policy/policy-jsonc-invalid` | Policy cannot be parsed or has malformed rules. |
157+| `policy/policy-hash-mismatch` | Policy does not match configured `expectedHash`. |
158+| `policy/attestation-hash-mismatch` | Current policy evidence no longer matches the accepted attestation. |
159+| `policy/channels-denied-provider` | An enabled channel matches a channel deny rule. |
160+161+Policy findings can include `target` and `requirement`: the observed workspace
162+thing that does not conform, and the authored rule that made it a finding.
163+164+## Repair
165+166+`doctor --lint` and `policy check` are read-only.
167+168+`doctor --fix` only edits policy-managed workspace settings when
169+`workspaceRepairs` is explicitly enabled. Without that opt-in, policy checks
170+report what they would repair and leave settings unchanged.
171+172+In this version, repair can disable channels that are enabled in OpenClaw config
173+but denied by `channels.denyRules`. Enable `workspaceRepairs` only after the
174+policy file has been reviewed, because a valid deny rule can turn off a
175+configured channel:
176+177+```jsonc
178+{
179+"plugins": {
180+"entries": {
181+"policy": {
182+"config": {
183+"workspaceRepairs": true,
184+ },
185+ },
186+ },
187+ },
188+}
189+```
190+191+## Exit codes
192+193+`policy check` exits `0` when there are no findings at the threshold, `1` when
194+findings are present, and `2` for argument or runtime failures.
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。