openclaw
diff --git a/‎CHANGELOG.md‎
Lines changed: 4 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎docs/cli/policy.md‎
Lines changed: 149 additions & 26 deletions b/‎docs/cli/policy.md‎
Lines changed: 149 additions & 26 deletions
diff --git a/‎docs/cli/skills.md‎
Lines changed: 29 additions & 12 deletions b/‎docs/cli/skills.md‎
Lines changed: 29 additions & 12 deletions
diff --git a/‎docs/gateway/config-tools.md‎
Lines changed: 32 additions & 0 deletions b/‎docs/gateway/config-tools.md‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎docs/gateway/sandbox-vs-tool-policy-vs-elevated.md‎
Lines changed: 5 additions & 0 deletions b/‎docs/gateway/sandbox-vs-tool-policy-vs-elevated.md‎
Lines changed: 5 additions & 0 deletions
@@ -10,7 +10,10 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Media/audio: skip empty structured sherpa-onnx transcripts instead of treating the raw JSON payload as spoken text. (#84667) Thanks @TurboTheTurtle.
+- Memory-core/dreaming: reuse stable narrative subagent session keys per workspace and phase while keeping per-run idempotency and bounded cleanup, so stale `dreaming-narrative-*` sessions do not accumulate. Fixes #68252, #69187, and #70402. (#70464) Thanks @chiyouYCH.
 - CLI/perf: keep `setup --help`, `onboard --help`, and `configure --help` out of the full wizard runtime while preserving the existing help output. (#84488) Thanks @frankekn.
+- CLI/perf: keep `agents --help` out of agents action/runtime imports so help, completion, and command discovery paths avoid loading the full agents runtime. (#84483) Thanks @frankekn.
 
 ## 2026.5.20
 
@@ -30,6 +33,7 @@ Docs: https://docs.openclaw.ai
 - CLI/tasks: include stale-running task maintenance decisions in `openclaw tasks maintenance --json` so retained and reconcile candidates explain backing-session, cron, CLI, and wedged-subagent state. (#84691) Thanks @efpiva.
 - Codex app-server: keep system-prompt reports working when bootstrap hooks provide workspace files with only a path and content, so hook-supplied SOUL/IDENTITY/TOOLS/USER context still reports injected characters correctly. (#84736) Thanks @JARVIS-Glasses.
 - Providers/MiniMax music: stop advertising `durationSeconds` control and remove prompt-injected duration hints, so `music_generate` reports MiniMax duration as an unsupported override instead of suggesting MiniMax can enforce track length. Fixes #84508. Thanks @neeravmakwana.
+- Doctor: warn when sandbox tool policy hides configured MCP server tools before provider requests. (#84699) Thanks @nxmxbbd.
 - WhatsApp: update Baileys to `7.0.0-rc12`.
 - Build: suppress per-locale `rolldown-plugin-dts:fake-js` CommonJS dts warnings emitted while bundling the intentionally-inlined `zod/v4/locales/*.d.cts` files, so `pnpm build` output stays readable after the 0.25.1 plugin bump. Thanks @romneyda.
 - CLI/nodes: route lazy plugin-registration logs to stderr for JSON-mode `openclaw nodes` commands so stdout stays parseable. (#84684) Thanks @TurboTheTurtle.
 
@@ -1,5 +1,5 @@
 ---
-summary: "CLI reference for `openclaw policy` channel conformance checks"
+summary: "CLI reference for `openclaw policy` conformance checks"
 read_when:
   - You want to check OpenClaw settings against an authored policy.jsonc
   - You want policy findings in doctor lint
@@ -10,14 +10,23 @@ title: "Policy"
 # `openclaw policy`
 
 `openclaw policy` is provided by the bundled Policy plugin. Policy is an
-enterprise conformance layer over existing OpenClaw settings: `policy.jsonc`
-defines authored requirements, OpenClaw observes the active workspace as
-evidence, and policy health checks report drift through `doctor --lint`.
-
-This first policy slice manages configured channels. For example, IT can record
-that Telegram is not approved, then `doctor --lint` reports any enabled Telegram
-channel and `doctor --fix` can turn it off when workspace repairs are explicitly
-enabled.
+enterprise conformance layer over existing OpenClaw settings. It does not add a
+second configuration system. `policy.jsonc` defines authored requirements,
+OpenClaw observes the active workspace as evidence, and policy health checks
+report drift through `doctor --lint`. The final conformance signal is a clean
+`doctor --lint` run; policy contributes findings to that shared lint surface
+instead of creating a separate health gate.
+
+Policy currently manages configured channels and governed tool declarations.
+For example, IT or a workspace operator can record that Telegram is not an
+approved channel provider, require governed tools to carry risk and sensitivity
+metadata, then use `doctor --lint` as the shared conformance gate.
+
+Use policy when a workspace needs a durable statement such as "these channels
+must not be enabled" or "governed tools must declare approval metadata" and a
+repeatable way to prove that OpenClaw still conforms to that statement. Use
+regular config and workspace docs alone when you only need local behavior and
+do not need policy findings or attestation output.
 
 ## Quick start
 
@@ -32,7 +41,7 @@ arbitrary plugins. The plugin remains enabled if `policy.jsonc` is missing, so
 doctor can report the missing artifact.
 
 Policy is authored, not generated from the user's current settings. A minimal
-channel policy looks like this:
+policy for channels and tool metadata looks like this:
 
 ```jsonc
 {
@@ -45,12 +54,16 @@ channel policy looks like this:
       },
     ],
   },
+  "tools": {
+    "requireMetadata": ["risk", "sensitivity", "owner"],
+  },
 }
 ```
 
 The rules are the authority. A category block is only a namespace; checks run
 when a concrete rule is present. OpenClaw reads current `channels.*` settings
-and reports settings that do not conform.
+and `TOOLS.md` declarations as evidence, then reports observed state that does
+not conform.
 
 Run policy-only checks during authoring:
 
@@ -122,12 +135,64 @@ Policy config lives under `plugins.entries.policy.config`.
 Set `plugins.entries.policy.config.enabled` to `false` to disable policy checks
 for a workspace while leaving the plugin installed.
 
+Tool metadata requirements are authored in `policy.jsonc` with
+`tools.requireMetadata`, for example `["risk", "sensitivity", "owner"]`.
+
 ## Accept policy state
 
-The attestation hash identifies the stable claim: policy hash, evidence hash,
-findings hash, and whether the result was clean. It intentionally does not
-include `checkedAt`, so the same policy state produces the same attestation
-across repeated checks.
+Example JSON output:
+
+```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
+      }
+    ],
+    "tools": [
+      {
+        "id": "deploy",
+        "source": "oc://TOOLS.md/tools/deploy",
+        "line": 12,
+        "risk": "critical",
+        "sensitivity": "restricted",
+        "capabilities": ["IRREVERSIBLE_EXTERNAL"]
+      }
+    ]
+  },
+  "checksRun": 6,
+  "checksSkipped": 0,
+  "findings": []
+}
+```
+
+The policy hash identifies the authored rule artifact. The evidence block
+records the observed OpenClaw state used by the policy checks. The
+`workspace.hash` value identifies that evidence payload for the checked scope.
+The findings hash identifies the exact finding set returned by the check.
+`checkedAt` records when the evaluation ran. The attestation hash identifies
+the stable claim: policy hash, evidence hash, findings hash, and whether the
+result was clean. It intentionally does not include `checkedAt`, so the same
+policy state produces the same attestation across repeated checks. Together,
+these form the audit tuple for this policy check.
 
 If a later gateway or supervisor uses policy to block, approve, or annotate a
 runtime action, it should record the attestation hash from the last clean policy
@@ -146,20 +211,71 @@ If policy rules change intentionally, update both accepted hashes from a clean
 check. If workspace settings change intentionally but policy stays the same,
 only `expectedAttestationHash` usually changes.
 
+`openclaw policy watch` runs the same check repeatedly and reports when the
+current evidence no longer matches `expectedAttestationHash`:
+
+```bash
+openclaw policy watch --json
+```
+
+Use `--once` in CI or scripts that only need one drift evaluation. Without
+`--once`, the command polls every two seconds by default; use `--interval-ms` to
+choose a different interval.
+
 ## Findings
 
 Policy currently verifies:
 
-| Check id                           | Finding                                                             |
-| ---------------------------------- | ------------------------------------------------------------------- |
-| `policy/policy-jsonc-missing`      | Policy is enabled but `policy.jsonc` is missing.                    |
-| `policy/policy-jsonc-invalid`      | Policy cannot be parsed or has malformed rules.                     |
-| `policy/policy-hash-mismatch`      | Policy does not match configured `expectedHash`.                    |
-| `policy/attestation-hash-mismatch` | Current policy evidence no longer matches the accepted attestation. |
-| `policy/channels-denied-provider`  | An enabled channel matches a channel deny rule.                     |
+| Check id                                 | Finding                                                             |
+| ---------------------------------------- | ------------------------------------------------------------------- |
+| `policy/policy-jsonc-missing`            | Policy is enabled but `policy.jsonc` is missing.                    |
+| `policy/policy-jsonc-invalid`            | Policy cannot be parsed or has malformed rules.                     |
+| `policy/policy-hash-mismatch`            | Policy does not match configured `expectedHash`.                    |
+| `policy/attestation-hash-mismatch`       | Current policy evidence no longer matches the accepted attestation. |
+| `policy/channels-denied-provider`        | An enabled channel matches a channel deny rule.                     |
+| `policy/tools-missing-owner`             | A governed tool declaration is missing owner metadata.              |
+| `policy/tools-missing-risk-level`        | A governed tool declaration is missing risk metadata.               |
+| `policy/tools-missing-sensitivity-token` | A governed tool declaration is missing sensitivity metadata.        |
+| `policy/tools-unknown-risk-level`        | A governed tool declaration uses an unknown risk value.             |
+| `policy/tools-unknown-sensitivity-token` | A governed tool declaration uses an unknown sensitivity value.      |
+
+Policy findings can include both `target` and `requirement`. `target` is the
+observed workspace thing that does not conform. `requirement` is the authored
+policy rule that made it a finding. Both values are addresses today, usually
+`oc://` paths, but the field names describe their policy role rather than the
+address format.
+
+Example JSON finding:
+
+```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."
+}
+```
 
-Policy findings can include `target` and `requirement`: the observed workspace
-thing that does not conform, and the authored rule that made it a finding.
+Example tool finding:
+
+```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"
+}
+```
 
 ## Repair
 
@@ -190,5 +306,12 @@ configured channel:
 
 ## Exit codes
 
-`policy check` exits `0` when there are no findings at the threshold, `1` when
-findings are present, and `2` for argument or runtime failures.
+| Command        | `0`                                       | `1`                                              | `2`                          |
+| -------------- | ----------------------------------------- | ------------------------------------------------ | ---------------------------- |
+| `policy check` | No findings at the threshold.             | One or more findings met the threshold.          | Argument or runtime failure. |
+| `policy watch` | No findings and accepted hash is current. | Findings exist or accepted attestation is stale. | Argument or runtime failure. |
+
+## Related
+
+- [Doctor lint mode](/cli/doctor#lint-mode)
+- [Path CLI](/cli/path)
@@ -2,14 +2,15 @@
 summary: "CLI reference for `openclaw skills` (search/install/update/list/info/check)"
 read_when:
   - You want to see which skills are available and ready to run
-  - You want to search, install, or update skills from ClawHub
+  - You want to search ClawHub or install skills from ClawHub, Git, or local directories
   - You want to debug missing binaries/env/config for skills
 title: "Skills"
 ---
 
 # `openclaw skills`
 
-Inspect local skills and install/update skills from ClawHub.
+Inspect local skills, search ClawHub, install skills from ClawHub/Git/local directories, and update
+ClawHub-tracked installs.
 
 Related:
 
@@ -24,6 +25,9 @@ openclaw skills search "calendar"
 openclaw skills search --limit 20 --json
 openclaw skills install <slug>
 openclaw skills install <slug> --version <version>
+openclaw skills install git:owner/repo
+openclaw skills install git:owner/repo@main
+openclaw skills install ./path/to/skill --as custom-name
 openclaw skills install <slug> --force
 openclaw skills install <slug> --agent <id>
 openclaw skills install <slug> --global
@@ -45,23 +49,36 @@ openclaw skills check --agent <id>
 openclaw skills check --json
 ```
 
-`search`/`install`/`update` use ClawHub directly. By default, `install` and
-`update` target the active workspace `skills/` directory; with `--global`, they
-target the shared managed skills directory. `list`/`info`/`check` still inspect
-the local skills visible to the current workspace and config. Workspace-backed
-commands resolve the target workspace from `--agent <id>`, then the current
-working directory when it is inside a configured agent workspace, then the
-default agent.
+`search` and `update` use ClawHub directly. `install <slug>` installs a ClawHub
+skill, `install git:owner/repo[@ref]` clones a Git skill, and `install ./path`
+copies a local skill directory. By default, `install` and `update` target the
+active workspace `skills/` directory; with `--global`, they target the shared
+managed skills directory. `list`/`info`/`check` still inspect the local skills
+visible to the current workspace and config. Workspace-backed commands resolve
+the target workspace from `--agent <id>`, then the current working directory
+when it is inside a configured agent workspace, then the default agent.
 
-This CLI `install` command downloads skill folders from ClawHub. Gateway-backed
-skill dependency installs triggered from onboarding or Skills settings use the
-separate `skills.install` request path instead.
+Git and local directory installs expect `SKILL.md` at the source root. The
+install slug comes from `SKILL.md` frontmatter `name` when it is valid, then the
+source directory or repository name; use `--as <slug>` to override it. `--version`
+is ClawHub-only. Skill installs do not support npm package specs or zip/archive
+paths, and `openclaw skills update` updates ClawHub-tracked installs only.
+
+Gateway-backed skill dependency installs triggered from onboarding or Skills
+settings use the separate `skills.install` request path instead.
 
 Notes:
 
 - `search [query...]` accepts an optional query; omit it to browse the default
   ClawHub search feed.
 - `search --limit <n>` caps returned results.
+- `install git:owner/repo[@ref]` installs a Git skill. Branch refs may contain
+  slashes, such as `git:owner/repo@feature/foo`.
+- `install ./path/to/skill` installs a local directory whose root contains
+  `SKILL.md`.
+- `install --as <slug>` overrides the inferred slug for Git and local directory
+  installs.
+- `install --version <version>` applies only to ClawHub skill slugs.
 - `install --force` overwrites an existing workspace skill folder for the same
   slug.
 - `--global` targets the shared managed skills directory and cannot be combined
 
@@ -43,6 +43,38 @@ Local onboarding defaults new local configs to `tools.profile: "coding"` when un
 | `group:agents`     | `agents_list`, `update_plan`                                                                                            |
 | `group:media`      | `image`, `image_generate`, `music_generate`, `video_generate`, `tts`                                                    |
 | `group:openclaw`   | All built-in tools (excludes provider plugins)                                                                          |
+| `group:plugins`    | Tools owned by loaded plugins, including configured MCP servers exposed through `bundle-mcp`                            |
+
+### MCP and plugin tools inside sandbox tool policy
+
+Configured MCP servers are exposed as plugin-owned tools under the `bundle-mcp` plugin id. Normal tool profiles can allow them, but `tools.sandbox.tools` is an additional gate for sandboxed sessions. If sandbox mode is `"all"` or `"non-main"`, include one of these entries in the sandbox tool allowlist when MCP/plugin tools should be visible:
+
+- `bundle-mcp` for OpenClaw-managed MCP servers from `mcp.servers`
+- the plugin id for a specific native plugin
+- `group:plugins` for all loaded plugin-owned tools
+- exact MCP server tool names or server globs such as `outlook__send_mail` or `outlook__*` when you only want one server
+
+Server globs use the provider-safe MCP server prefix, not necessarily the raw `mcp.servers` key. Non-`[A-Za-z0-9_-]` characters become `-`, names that do not start with a letter get an `mcp-` prefix, and long or duplicate prefixes may be truncated or suffixed; for example, `mcp.servers["Outlook Graph"]` uses a glob like `outlook-graph__*`.
+
+```json5
+{
+  agents: { defaults: { sandbox: { mode: "all" } } },
+  mcp: {
+    servers: {
+      outlook: { command: "node", args: ["./outlook-mcp.js"] },
+    },
+  },
+  tools: {
+    sandbox: {
+      tools: {
+        alsoAllow: ["web_search", "web_fetch", "memory_search", "memory_get", "bundle-mcp"],
+      },
+    },
+  },
+}
+```
+
+Without that sandbox-layer entry, the MCP server can still load successfully while its tools are filtered before the provider request. Use `openclaw doctor` to catch this shape for OpenClaw-managed servers in `mcp.servers`. MCP servers loaded from bundled plugin manifests or Claude `.mcp.json` use the same sandbox gate, but this diagnostic does not enumerate those sources yet; use the same allowlist entries if their tools disappear in sandboxed turns.
 
 ### `tools.allow` / `tools.deny`
 
 
@@ -100,6 +100,11 @@ Available groups:
 - `group:agents`: `agents_list`, `update_plan`
 - `group:media`: `image`, `image_generate`, `music_generate`, `video_generate`, `tts`
 - `group:openclaw`: all built-in OpenClaw tools (excludes provider plugins)
+- `group:plugins`: all loaded plugin-owned tools, including configured MCP servers exposed through `bundle-mcp`
+
+For sandboxed MCP servers, the sandbox tool policy is a second allow gate. If `mcp.servers` is configured but sandboxed turns only show built-in tools, add `bundle-mcp`, `group:plugins`, or a server-prefixed MCP tool name/glob such as `outlook__send_mail` or `outlook__*` to `tools.sandbox.tools.alsoAllow`, then restart/reload the gateway and recapture the tool list. Server globs use the provider-safe MCP server prefix: non-`[A-Za-z0-9_-]` characters become `-`, names that do not start with a letter get an `mcp-` prefix, and long or duplicate prefixes may be truncated or suffixed.
+
+`openclaw doctor` currently checks this shape for OpenClaw-managed servers in `mcp.servers`. MCP servers loaded from bundled plugin manifests or Claude `.mcp.json` use the same sandbox gate, but this diagnostic does not enumerate those sources yet; use the same allowlist entries if their tools disappear in sandboxed turns.
 
 ## Elevated: exec-only "run on host"