* docs: fix one-way and absolute links across cli, tools, gateway, and channels
Closes the open `link`-kind audit findings filed against docs/cli/,
docs/tools/, docs/gateway/ and docs/channels/.
- Convert 21 absolute `https://docs.openclaw.ai/...` links to root-relative
paths on protocol, clients, external-apps, embedding, protocol/transport,
and zaloclawbot so local previews and versioned builds resolve them.
- Add the missing reverse link for one-way Related entries, using the house
bullet or `<Card>` shape each page already uses.
- Link terms that were named but not linked: SecretRef and
`gateway.trustedProxies` on sms, the meeting providers on transcripts,
`openclaw models`/`openclaw agent` on infer, Talk on tts, `/tools/invoke`
on the gateway index.
- Give distinct link text to the two "macOS platform notes" links on
gateway/troubleshooting.
- Point the IRC workspace `.env` link at the section anchor rather than the
Security index.
- Add Related sections to pages that had none (sms, transcripts, promos,
progress-card, onboard, access-groups, concepts/memory, operator-scopes).
- Add the 28 zh-CN glossary sources the new list-item link labels require,
each inserted beside a related existing term.
No anchor targets change. `pnpm check:docs` is green.
* docs: link devices and doctor inline on pairing, and trusted proxy auth from the security index
Completes two findings that were only half-applied: r3-1324 asked for the
sibling commands to be linked inline on /cli/pairing, and r3-1579 lists the
security index among the four pages that should link back to
/gateway/trusted-proxy-auth.
* docs: match each Related list's existing separator style
The added bullets used an em dash in lists whose existing entries separate
the label and gloss with a hyphen. Normalized 11 files so each list stays
internally consistent.
* docs: correct four inaccurate Related-link descriptions from review
ClawSweeper found that several glosses I wrote misdescribed their targets.
Verified each against the destination page and corrected:
- ask_user is for non-secret questions; its own reference says never to answer
it with a credential, so the secrets-page gloss now points credential entry
at the masked secrets tool (P1).
- OpenClaw sandbox policy does not wrap ACP harness execution
(tools/acp-agents/delivery.md), so the ACP backlink now names the separate
boundary instead of implying coverage (P2).
- Code Mode is a QuickJS-WASI JavaScript/TypeScript orchestration surface, not
something built on the xAI code_execution tool documented on that page (P2).
- openclaw qr emits a mobile-node bootstrap payload, not a channel DM pairing
code, on both the pairing and devices pages (P2).
Audited the other 100 descriptions for the same class of error and fixed six
more: OpenShell is a managed sandbox backend rather than a surface the sandbox
bounds (3 pages); a Cloud Workers gloss claimed sandbox settings apply when its
managed workspace is explicitly not an OS sandbox; openclaw promos lists and
claims promotional offers; the 1Password gloss overstated the plugin relation;
and the progress-card bullets no longer assert undocumented dashboard rendering.
* docs: correct three more link descriptions and audit every remaining gloss
Addresses the second review round, and then re-checks the whole set rather
than only the three reported.
Reported:
- openclaw attach launches Claude Code with a scoped Gateway MCP grant
(cli/attach.md:2); it does not attach a terminal to a running session.
Fixed on cli/mcp.md and cli/tui.md.
- Bare openclaw setup opens an interactive system-agent chat and falls
through to guided onboarding on a fresh system (cli/setup.md:12), so
calling it 'the non-interactive setup command' was wrong.
- Access groups have no pairing prerequisite: a group 'grants nothing by
itself' and only matters where an allowlist references it. Dropped the
invented sequencing claim.
Found by auditing the remaining descriptions against each target's own
summary:
- openclaw worker is explicitly 'not a general-purpose command for manual
worker registration' (cli/worker.md:13); reworded on cloud-workers and
protocol/handshake.
- /reference/rpc documents RPC adapters for external CLIs, not worker RPC
method shapes; repointed to /gateway/protocol/rpc-methods.
- stable-https-url gives a tailnet-only URL via Tailscale Serve, which the
iOS and Android glosses omitted.
- Tightened health, logs, sandbox, resume, infer, dashboard, diffs,
prometheus, music-generation, subagents, pairing, audit, tools-invoke,
configuration-reference, and the three goal glosses to match their pages
instead of asserting relationships no page documents.
One glossary source added for the new label.
* docs: attribute goal reads and updates to the dedicated goal tools
The session-tool page documents session discovery, messaging, lifecycle, and
orchestration tools; goal operations use get_goal, create_goal, and
update_goal instead (docs/tools/goal.md:132-149). I corrected the other three
goal glosses last round and missed this one.
---------
Co-authored-by: Vincent Koc <vincent@openclaw.org>
* docs: correct verified accuracy defects in CLI, tools, and automation pages
Resolve the open `accuracy` audit findings for docs/cli/, docs/tools/ and
docs/automation/. Every claim was checked against the implementation before
the prose was touched; findings the source contradicted are left unchanged and
rebutted in the PR body.
Factual corrections (docs disagreed with code):
- onboard: Z.AI defaults are glm-5.3 (coding) and glm-5.2 (general), not
glm-5.2/glm-5.1 (extensions/zai/model-definitions.ts, openclaw.plugin.json).
- sessions: the cleanup --json example printed a sessions.json store path, but
both JSON exits map storePath through resolveSqliteTargetFromSessionStorePath
(src/commands/sessions-cleanup.ts, src/config/sessions/cleanup-result.ts).
- diffs: `plugins install diffs` resolved to an unrelated npm package; the
plugin is external, not bundled (extensions/diffs/package.json).
- ollama-search: a bare "OLLAMA_API_KEY" string is a literal key, not env
indirection (src/config/types.secrets.ts).
- minimax-search: the region list contradicted its own opening condition and
merged two tiers (extensions/minimax/src/minimax-web-search-provider.runtime.ts).
- imap: addressTokens is a per-account key (extensions/imap/src/config.ts).
- thinking: GLM-5.3 is a second Z.AI exception (extensions/zai/provider-policy-api.ts).
- video-generation: buffer-backed videoToVideo also covers fal reference-to-video
(src/video-generation/live-test-helpers.ts).
- slash-commands: the missing third source is skill commands
(src/auto-reply/commands-registry-list.ts).
- cron: `cron` is the registered command and `automations` its alias
(src/cli/cron-cli/register.ts).
- setup: add the real --classic and --agent-name flags to the Options table
(src/cli/program/register.setup.ts).
- path: file-slot wildcard rejection exits 2 (extensions/oc-path/src/cli.ts).
Version scope added only where a release could be cited: 2026.8.1 (heartbeat
task migration, inferred commitments, artifact-area staging), 2026.4.29 (owner
bootstrap), 2026.4.26 (Hunter Alpha), 2026.3.31 (nodes.run). Elsewhere the
time-relative wording is replaced with the verified current behaviour rather
than a guessed version.
* docs(swarm): keep the limits-and-roadmap anchor after the heading rename
docs/AGENTS.md requires existing published heading ids to stay stable. The
rename from 'Limits and roadmap' to 'Limits' changed the generated fragment,
so add an explicit <a id="limits-and-roadmap" /> stub above the heading.
parseDocsDocument now reports both ids with no collisions.
* docs: close reciprocal-link gaps in concepts, nodes, and platforms
Link-only fixes from the docs link audit. Every change adds or retargets a
link; no surrounding prose was rewritten.
- Replace the redirect-only /plugins target with the real /tools/plugin page
in the memory-architecture config table.
- Add missing back-links so pages listed under Related link back: model
providers, context engines, agent runtimes, session tools, streaming,
node troubleshooting, computer use, and the nodes hub.
- Give Related sections to three pages that had none: session search,
the personal agent benchmark pack, and EasyRunner.
- Link the macOS Skills detail page from the macOS hub task table.
- Link each workspace template from its entry in the workspace file map.
The memory-architecture table is re-aligned by scripts/format-docs.mts
because one cell changed width; no cell content changed but that one link.
* docs: point the workspace tools template at the live AGENTS.md section
TOOLS.md is a retirement notice, not a template; the local tool
conventions template is the `## Tools` section of the AGENTS.md
template. Addresses the ClawSweeper P3 finding.
---------
Co-authored-by: Vincent Koc <vincent@openclaw.org>
Docs governance and publish-hygiene pass over docs/AGENTS.md and the
pages its rules cover.
- Replace every `~/Projects` operator path in docs/ with a neutral
placeholder. 38 occurrences across 13 pages, including the private
repo path `~/Projects/manager/skills`. `docs/AGENTS.md` forbids local
paths, and its own Internal Docs bullet named one.
- Record the placeholder convention in the Published Link Rules bullet
that bans local paths.
- Document the ClawHub docs source in Source Ownership: this repo holds
no `/clawhub/**` page sources even though `docs/docs.json` lists them,
so a local preview and `pnpm docs:check-links` report those routes as
missing until `OPENCLAW_DOCS_SYNC_CLAWHUB_REPO` points at a ClawHub
checkout.
- Drop the Strict-STE hard violation rate on `docs/AGENTS.md` from 18
hard (3.4 per 100 words) to 0 by splitting semicolon sentences and
sentences over 20 words, and by naming the actor in passive
sentences. No rule changes meaning.
- Convert the Maturity Scorecard paragraph to a bulleted list, matching
every other section.
- `docs/prose.md`: name v2026.8.1 as the release that removed OpenProse,
and explain the `--agent codex` flag and the third-party skills CLI.
- Link `/prose` from `tools/skills` and `tools/slash-commands`.
- `docs/docs_map.md`: correct the summary to describe the stub, and drop
the H1 that repeated the frontmatter title.
Closes audit findings: r3-0734, r3-0736, r3-0907, r3-0910, r3-2277,
r3-2278, r3-2285, r3-2286, r3-2287, r3-2288, r4-clawhub-0001
Partially addresses r3-0906 (private path removed; publish-tree
exclusion left as a follow-up). Not addressed: r3-0909 (generator
change).
* fix(plugins): trace trust refusals and repair legacy provenance
* fix: keep trust diagnostics within their owner boundaries
Keep remote Gateway failures independent of local service inspection and contain best-effort diagnostic errors. Remove ambient registry-path inference from the trust formatter so unavailable provenance remains unknown. Cover ordered recovery, remote tunnels, and portable diagnostic paths.
* fix(daemon): distinguish unavailable service facts from absence
Decode LaunchAgent definitions with the native parser and preserve recorded command and environment bytes. Strict service inspection now rejects unknown definitions and requires native absence evidence before reporting no installed service; non-strict environment-path recovery remains available.
* test(daemon): decode generated LaunchAgents on all CI hosts
Use the existing native decoder fixture seam for the real install-plan regeneration test, preserving its environment and SecretRef assertions. Group strict multiline parsing under one condition to satisfy lint without changing reader behavior.
* fix(daemon): reject unresolved Windows service assignments
Require literal, case-insensitive Windows environment facts for strict service inspection, preserving whitespace and escaped percent values. Keep unresolved expansion and unsupported shell syntax unknown without exposing raw service failures. Preserve lenient recovery and adapt real LaunchAgent update fixtures to the native decoder boundary on Linux.
* docs(gateway): document native service definition recovery
Closes#136710
## Problem
`config.schema.lookup` reported `reloadKind: "hot"` for `plugins.entries.*.enabled`, but its schema help said a restart was required. Several plugin docs repeated the stale restart guidance.
## Product path
```bash
openclaw gateway call config.schema.lookup \
--params '{"path":"plugins.entries.<plugin>.enabled"}' \
--json
```
## Root cause
Plugin enablement moved to the in-process plugin reload path, but the older help and lifecycle docs did not move with it. The generic plugin reload rule is hot. An active plugin can still declare a restart-triggering prefix, and `gateway.reload.mode: "off"` still disables config reload.
## Fix
- Describe the default hybrid reload mode and plugin-specific restart exception in schema help.
- Align the generic plugin lifecycle docs with the existing runtime behavior.
- Move the regression from a copy-quality test into the real Gateway WebSocket lookup boundary.
- Keep reload planning, configuration defaults, schemas, and protocol behavior unchanged.
## Compatibility
This is a wording and regression-test repair. It does not change configuration, defaults, reload planning, stored data, or the Gateway protocol.
## Proof
- Current-main red: [Blacksmith run 33714053532](https://github.com/openclaw/openclaw/actions/runs/33714053532) returned `reloadKind: "hot"` beside help containing `(restart required)` for two wildcard plugin paths.
- Regression red: [Blacksmith run 33714561306](https://github.com/openclaw/openclaw/actions/runs/33714561306) failed the new WebSocket lookup test on the stale help.
- Exact-tree green: formatter, `pnpm docs:list --headings`, the WebSocket regression, 24 help-quality tests, and three plugin reload sibling tests passed in [Blacksmith run 33715965706](https://github.com/openclaw/openclaw/actions/runs/33715965706).
- Live green: [Blacksmith run 33716204027](https://github.com/openclaw/openclaw/actions/runs/33716204027) returned matching `hot` metadata and hybrid-mode help for the reported path and a second wildcard path.
- Exact-head Autoreview passed with no P0 findings.
## Credit
This repair preserves @LiuwqGit's original commit and intent.
Co-authored-by: Ayaan Zaidi <hi@obviy.us>
* feat(plugins): support the Agent Plugins bundle format
* docs(plugins): document the Agent Plugins bundle format
* test(agents): preserve agent bundle runtime discovery
* fix(plugins): isolate Agent Plugins data-dir failures and align MCP support reporting
* docs(plugins): list Agent Plugins in the canonical plugin-format guides
* fix(plugins): gate Agent Plugins detection on schema, pure inspection, root-relative cwd
* fix(plugins): record Agent Plugins data-dir ownership explicitly
* docs(plugins): cover Agent Plugins in the CLI install detection guide
* fix(plugins): carry Agent Plugins data-dir and transport contracts through external MCP projections
* fix(plugins): make empty-allowlist warning actionable for first-time users
* fix(plugins): make empty-allowlist warnings actionable
* fix(plugins): make empty-allowlist warnings actionable
* fix(plugins): make empty-allowlist actionable for new users
---------
Co-authored-by: openclaw-clownfish[bot] <280122609+openclaw-clownfish[bot]@users.noreply.github.com>
Refactor OpenAI provider identity so OpenAI remains the canonical provider for API-key and OAuth-backed flows while legacy openai-codex state is doctor/migration-only.
Keeps OpenAI Codex Responses as an API/transport class rather than a provider identity, moves auth aliases through providerAuthAliases, updates doctor repair sequencing for old auth/profile state, and refreshes tests/docs around the canonical OpenAI behavior.
Summary:
- The PR adds a `before_agent_run` plugin hook with pass/block decisions, redacted blocked-turn persistence, diagnostics/docs/changelog updates, and focused runner, gateway, session, and plugin tests.
- Reproducibility: not applicable. as a feature PR rather than a current-main bug report. Current main lacks ` ... un`, while the PR head adds source coverage and copied live Gateway/WebChat log proof for the new behavior.
Automerge notes:
- PR branch already contained follow-up commit before automerge: fix: trim before agent hook PR scope
- PR branch already contained follow-up commit before automerge: fix: keep before-agent blocks redacted
- PR branch already contained follow-up commit before automerge: fix: keep runtime context out of model prompt
- PR branch already contained follow-up commit before automerge: docs: refresh config baseline after rebase
- PR branch already contained follow-up commit before automerge: fix: align blocked turn clients with redacted content
- PR branch already contained follow-up commit before automerge: fix: remove out-of-scope client block UI changes
Validation:
- ClawSweeper review passed for head 767e46fde8.
- Required merge gates passed before the squash merge.
Prepared head SHA: 767e46fde8
Review: https://github.com/openclaw/openclaw/pull/75035#issuecomment-4351843275
Co-authored-by: Jesse Merhi <jessejmerhi@gmail.com>
Co-authored-by: jesse-merhi <79823012+jesse-merhi@users.noreply.github.com>
Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com>
