Skip to content

Commit 4e09b06

Browse files
steipetesteipete
committed
docs: polish policy plugin docs
1 parent 4ee7132 commit 4e09b06

7 files changed

Lines changed: 134 additions & 22 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Docs: https://docs.openclaw.ai
77
### Changes
88

99
- Dependencies: bump the bundled Codex harness to `@openai/codex` `0.132.0` and refresh the app-server model-list docs for the new catalog.
10+
- CLI/policy: add the bundled Policy plugin for policy-backed channel conformance checks, doctor lint findings, and opt-in workspace repair. (#80407) Thanks @giodl73-repo.
1011
- Agents/config: allow `agents.list[].experimental.localModelLean` so lean local-model mode can be enabled for one configured agent instead of globally.
1112
- Providers/xAI: add device-code OAuth login so remote and headless setups can authorize xAI without a localhost browser callback. (#84005) Thanks @fuller-stack-dev.
1213

‎docs/cli/policy.md‎

Lines changed: 105 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -9,25 +9,27 @@ title: "Policy"
99

1010
# `openclaw policy`
1111

12-
`openclaw policy` is provided by the bundled `policy` extension. Policy is an
12+
`openclaw policy` is provided by the bundled Policy plugin. Policy is an
1313
enterprise conformance layer over existing OpenClaw settings: `policy.jsonc`
14-
defines authored requirements, OpenClaw observes current settings as evidence,
15-
and policy registers health checks that report drift through `doctor --lint`.
14+
defines authored requirements, OpenClaw observes the active workspace as
15+
evidence, and policy health checks report drift through `doctor --lint`.
1616

1717
This first policy slice manages configured channels. For example, IT can record
1818
that Telegram is not approved, then `doctor --lint` reports any enabled Telegram
1919
channel and `doctor --fix` can turn it off when workspace repairs are explicitly
2020
enabled.
2121

22-
Enable the bundled policy extension before first use:
22+
## Quick start
23+
24+
Enable the bundled Policy plugin before first use:
2325

2426
```bash
2527
openclaw plugins enable policy
2628
```
2729

2830
When policy is enabled, doctor can load policy health checks without activating
29-
arbitrary plugins. The extension remains enabled if `policy.jsonc` is missing,
30-
so doctor can report the missing artifact.
31+
arbitrary plugins. The plugin remains enabled if `policy.jsonc` is missing, so
32+
doctor can report the missing artifact.
3133

3234
Policy is authored, not generated from the user's current settings. A minimal
3335
channel policy looks like this:
@@ -50,6 +52,8 @@ The rules are the authority. A category block is only a namespace; checks run
5052
when a concrete rule is present. OpenClaw reads current `channels.*` settings
5153
and reports settings that do not conform.
5254

55+
Run policy-only checks during authoring:
56+
5357
```bash
5458
openclaw policy check
5559
openclaw policy check --json
@@ -58,23 +62,55 @@ openclaw policy check --severity-min error
5862

5963
`policy check` runs only the policy check set and emits evidence, findings, and
6064
attestation hashes. The same findings also appear in `openclaw doctor --lint`
61-
when the policy extension is enabled.
65+
when the Policy plugin is enabled.
6266

63-
The attestation hash identifies the stable claim: policy hash, evidence hash,
64-
findings hash, and whether the result was clean. It intentionally does not
65-
include `checkedAt`, so the same policy state produces the same attestation
66-
across repeated checks.
67+
Example clean JSON output includes stable hashes that can be recorded by an
68+
operator or supervisor:
6769

68-
If a later gateway or supervisor uses policy to block, approve, or annotate a
69-
runtime action, it should record the attestation hash from the last clean policy
70-
check. `checkedAt` stays in JSON output for audit logs, but is not part of the
71-
stable attestation hash.
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+
```
7290

73-
Policy findings can include `target` and `requirement`: the observed workspace
74-
thing that does not conform, and the authored rule that made it a finding.
91+
## Configure policy
7592

7693
Policy config lives under `plugins.entries.policy.config`.
7794

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+
78114
| Setting | Purpose |
79115
| ------------------------- | --------------------------------------------------------------- |
80116
| `enabled` | Enable policy checks even before `policy.jsonc` exists. |
@@ -83,8 +119,34 @@ Policy config lives under `plugins.entries.policy.config`.
83119
| `expectedAttestationHash` | Optional hash-lock for the last accepted clean policy check. |
84120
| `path` | Workspace-relative location of the policy artifact. |
85121

86-
Set `plugins.entries.policy.config.enabled` to `false` to disable policy
87-
checks for a workspace.
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
88150

89151
Policy currently verifies:
90152

@@ -96,14 +158,37 @@ Policy currently verifies:
96158
| `policy/attestation-hash-mismatch` | Current policy evidence no longer matches the accepted attestation. |
97159
| `policy/channels-denied-provider` | An enabled channel matches a channel deny rule. |
98160

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+
99166
`doctor --lint` and `policy check` are read-only.
100167

101168
`doctor --fix` only edits policy-managed workspace settings when
102169
`workspaceRepairs` is explicitly enabled. Without that opt-in, policy checks
103170
report what they would repair and leave settings unchanged.
104171

105172
In this version, repair can disable channels that are enabled in OpenClaw config
106-
but denied by `channels.denyRules`.
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
107192

108193
`policy check` exits `0` when there are no findings at the threshold, `1` when
109194
findings are present, and `2` for argument or runtime failures.

‎docs/plugins/plugin-inventory.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,7 @@ commands.
109109
| [opencode-go](/plugins/reference/opencode-go) | Adds OpenCode Go model provider support to OpenClaw. | `@openclaw/opencode-go-provider`<br />included in OpenClaw | providers: opencode-go; contracts: mediaUnderstandingProviders |
110110
| [openrouter](/plugins/reference/openrouter) | Adds OpenRouter model provider support to OpenClaw. | `@openclaw/openrouter-provider`<br />included in OpenClaw | providers: openrouter; contracts: imageGenerationProviders, mediaUnderstandingProviders, musicGenerationProviders, speechProviders, videoGenerationProviders |
111111
| [perplexity](/plugins/reference/perplexity) | Adds web search provider support. | `@openclaw/perplexity-plugin`<br />included in OpenClaw | contracts: webSearchProviders |
112+
| [policy](/plugins/reference/policy) | Adds policy-backed doctor checks for workspace conformance. | `@openclaw/policy`<br />included in OpenClaw | plugin |
112113
| [qianfan](/plugins/reference/qianfan) | Adds Qianfan model provider support to OpenClaw. | `@openclaw/qianfan-provider`<br />included in OpenClaw | providers: qianfan |
113114
| [qwen](/plugins/reference/qwen) | Adds Qwen, Qwen Cloud, Model Studio, DashScope model provider support to OpenClaw. | `@openclaw/qwen-provider`<br />included in OpenClaw | providers: qwen, qwencloud, modelstudio, dashscope; contracts: mediaUnderstandingProviders, videoGenerationProviders |
114115
| [runway](/plugins/reference/runway) | Adds video generation provider support. | `@openclaw/runway-provider`<br />included in OpenClaw | contracts: videoGenerationProviders |

‎docs/plugins/reference.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ pnpm plugins:inventory:gen
9696
| [openrouter](/plugins/reference/openrouter) | Adds OpenRouter model provider support to OpenClaw. | `@openclaw/openrouter-provider`<br />included in OpenClaw | providers: openrouter; contracts: imageGenerationProviders, mediaUnderstandingProviders, musicGenerationProviders, speechProviders, videoGenerationProviders |
9797
| [openshell](/plugins/reference/openshell) | Sandbox backend powered by OpenShell with mirrored local workspaces and SSH-based command execution. | `@openclaw/openshell-sandbox`<br />npm; ClawHub | plugin |
9898
| [perplexity](/plugins/reference/perplexity) | Adds web search provider support. | `@openclaw/perplexity-plugin`<br />included in OpenClaw | contracts: webSearchProviders |
99+
| [policy](/plugins/reference/policy) | Adds policy-backed doctor checks for workspace conformance. | `@openclaw/policy`<br />included in OpenClaw | plugin |
99100
| [qa-channel](/plugins/reference/qa-channel) | Adds the QA Channel surface for sending and receiving OpenClaw messages. | `@openclaw/qa-channel`<br />source checkout only | channels: qa-channel |
100101
| [qa-lab](/plugins/reference/qa-lab) | OpenClaw QA lab plugin with private debugger UI and scenario runner. | `@openclaw/qa-lab`<br />source checkout only | plugin |
101102
| [qa-matrix](/plugins/reference/qa-matrix) | Matrix QA transport runner and substrate. | `@openclaw/qa-matrix`<br />source checkout only | plugin |

‎docs/plugins/reference/policy.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
summary: "Adds policy-backed doctor checks for workspace conformance."
3+
read_when:
4+
- You are installing, configuring, or auditing the policy plugin
5+
title: "Policy plugin"
6+
---
7+
8+
# Policy plugin
9+
10+
Adds policy-backed doctor checks for workspace conformance.
11+
12+
## Distribution
13+
14+
- Package: `@openclaw/policy`
15+
- Install route: included in OpenClaw
16+
17+
## Surface
18+
19+
plugin
20+
21+
## Related docs
22+
23+
- [policy](/cli/policy)

‎extensions/policy/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@openclaw/policy",
3-
"version": "2026.5.17",
3+
"version": "2026.5.19",
44
"private": true,
55
"description": "OpenClaw policy doctor checks for workspace conformance",
66
"type": "module",
@@ -12,7 +12,7 @@
1212
"openclaw": "workspace:*"
1313
},
1414
"peerDependencies": {
15-
"openclaw": ">=2026.5.17"
15+
"openclaw": ">=2026.5.19"
1616
},
1717
"peerDependenciesMeta": {
1818
"openclaw": {

‎scripts/generate-plugin-inventory-doc.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ const PLUGIN_DOC_ALIASES = new Map([
2525
["exa", "/tools/exa-search"],
2626
["firecrawl", "/tools/firecrawl"],
2727
["perplexity", "/tools/perplexity-search"],
28+
["policy", "/cli/policy"],
2829
["tavily", "/tools/tavily"],
2930
["tokenjuice", "/tools/tokenjuice"],
3031
]);

0 commit comments

Comments
 (0)