From ae9f779e5ff431b804e9623347a1871d2920c4f7 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Tue, 5 May 2026 20:25:31 -0700 Subject: [PATCH] docs: typography hygiene + 1 in-body H1 removal across 6 pages Replaced 84 typography characters (curly quotes, apostrophes, em/en dashes, non-breaking hyphens) with ASCII equivalents per docs/CLAUDE.md heading and content hygiene rules. - docs/gateway/tools-invoke-http-api.md: 14 chars; removed the duplicate '# Tools Invoke (HTTP)' H1 (Mintlify renders title from frontmatter; the in-body H1 with parens produced a brittle anchor). - docs/tools/browser-control.md: 14 chars - docs/security/formal-verification.md: 14 chars - docs/gateway/configuration-reference.md: 14 chars - docs/concepts/agent.md: 14 chars - docs/channels/qa-channel.md: 14 chars --- docs/channels/qa-channel.md | 28 +++++++++++------------ docs/concepts/agent.md | 22 +++++++++--------- docs/gateway/configuration-reference.md | 28 +++++++++++------------ docs/gateway/tools-invoke-http-api.md | 30 ++++++++++++------------- docs/security/formal-verification.md | 16 ++++++------- docs/tools/browser-control.md | 14 ++++++------ 6 files changed, 68 insertions(+), 70 deletions(-) diff --git a/docs/channels/qa-channel.md b/docs/channels/qa-channel.md index bf649a279df..4f4f997748f 100644 --- a/docs/channels/qa-channel.md +++ b/docs/channels/qa-channel.md @@ -7,7 +7,7 @@ read_when: - You are iterating on end-to-end QA automation --- -`qa-channel` is a bundled synthetic message transport for automated OpenClaw QA. It is not a production channel — it exists to exercise the same channel plugin boundary used by real transports while keeping state deterministic and fully inspectable. +`qa-channel` is a bundled synthetic message transport for automated OpenClaw QA. It is not a production channel - it exists to exercise the same channel plugin boundary used by real transports while keeping state deterministic and fully inspectable. ## What it does @@ -38,20 +38,20 @@ read_when: Account keys: -- `enabled` — master toggle for this account. -- `name` — optional display label. -- `baseUrl` — synthetic bus URL. -- `botUserId` — Matrix-style bot user id used in target grammar. -- `botDisplayName` — display name for outbound messages. -- `pollTimeoutMs` — long-poll wait window. Integer between 100 and 30000. -- `allowFrom` — sender allowlist (user ids or `"*"`). -- `defaultTo` — fallback target when none is supplied. -- `actions.messages` / `actions.reactions` / `actions.search` / `actions.threads` — per-action tool gating. +- `enabled` - master toggle for this account. +- `name` - optional display label. +- `baseUrl` - synthetic bus URL. +- `botUserId` - Matrix-style bot user id used in target grammar. +- `botDisplayName` - display name for outbound messages. +- `pollTimeoutMs` - long-poll wait window. Integer between 100 and 30000. +- `allowFrom` - sender allowlist (user ids or `"*"`). +- `defaultTo` - fallback target when none is supplied. +- `actions.messages` / `actions.reactions` / `actions.search` / `actions.threads` - per-action tool gating. Multi-account keys at the top level: -- `accounts` — record of named per-account overrides keyed by account id. -- `defaultAccount` — preferred account id when multiple are configured. +- `accounts` - record of named per-account overrides keyed by account id. +- `defaultAccount` - preferred account id when multiple are configured. ## Runners @@ -81,8 +81,8 @@ Builds the QA site, starts the Docker-backed gateway + QA Lab stack, and prints ## Related -- [QA overview](/concepts/qa-e2e-automation) — overall stack, transport adapters, scenario authoring -- [Matrix QA](/concepts/qa-matrix) — example live-transport runner that drives a real channel +- [QA overview](/concepts/qa-e2e-automation) - overall stack, transport adapters, scenario authoring +- [Matrix QA](/concepts/qa-matrix) - example live-transport runner that drives a real channel - [Pairing](/channels/pairing) - [Groups](/channels/groups) - [Channels overview](/channels) diff --git a/docs/concepts/agent.md b/docs/concepts/agent.md index 9b9769cdcfc..b0a7e996a9e 100644 --- a/docs/concepts/agent.md +++ b/docs/concepts/agent.md @@ -5,14 +5,14 @@ read_when: title: "Agent runtime" --- -OpenClaw runs a **single embedded agent runtime** — one agent process per +OpenClaw runs a **single embedded agent runtime** - one agent process per Gateway, with its own workspace, bootstrap files, and session store. This page covers that runtime contract: what the workspace must contain, which files get injected, and how sessions bootstrap against it. ## Workspace (required) -OpenClaw uses a single agent workspace directory (`agents.defaults.workspace`) as the agent’s **only** working directory (`cwd`) for tools and context. +OpenClaw uses a single agent workspace directory (`agents.defaults.workspace`) as the agent's **only** working directory (`cwd`) for tools and context. Recommended: use `openclaw setup` to create `~/.openclaw/openclaw.json` if missing and initialize the workspace files. @@ -26,18 +26,18 @@ per-session workspaces under `agents.defaults.sandbox.workspaceRoot` (see Inside `agents.defaults.workspace`, OpenClaw expects these user-editable files: -- `AGENTS.md` — operating instructions + “memory” -- `SOUL.md` — persona, boundaries, tone -- `TOOLS.md` — user-maintained tool notes (e.g. `imsg`, `sag`, conventions) -- `BOOTSTRAP.md` — one-time first-run ritual (deleted after completion) -- `IDENTITY.md` — agent name/vibe/emoji -- `USER.md` — user profile + preferred address +- `AGENTS.md` - operating instructions + "memory" +- `SOUL.md` - persona, boundaries, tone +- `TOOLS.md` - user-maintained tool notes (e.g. `imsg`, `sag`, conventions) +- `BOOTSTRAP.md` - one-time first-run ritual (deleted after completion) +- `IDENTITY.md` - agent name/vibe/emoji +- `USER.md` - user profile + preferred address On the first turn of a new session, OpenClaw injects the contents of these files into the system prompt's Project Context. Blank files are skipped. Large files are trimmed and truncated with a marker so prompts stay lean (read the file for full content). -If a file is missing, OpenClaw injects a single “missing file” marker line (and `openclaw setup` will create a safe default template). +If a file is missing, OpenClaw injects a single "missing file" marker line (and `openclaw setup` will create a safe default template). `BOOTSTRAP.md` is only created for a **brand new workspace** (no other bootstrap files present). While it is pending, OpenClaw keeps it in Project Context and adds system-prompt bootstrap guidance for the initial ritual instead of copying it into the user message. If you delete it after completing the ritual, it should not be recreated on later restarts. @@ -51,7 +51,7 @@ To disable bootstrap file creation entirely (for pre-seeded workspaces), set: Core tools (read/exec/edit/write and related system tools) are always available, subject to tool policy. `apply_patch` is optional and gated by -`tools.exec.applyPatch`. `TOOLS.md` does **not** control which tools exist; it’s +`tools.exec.applyPatch`. `TOOLS.md` does **not** control which tools exist; it's guidance for how _you_ want them used. ## Skills @@ -100,7 +100,7 @@ Block streaming sends completed assistant blocks as soon as they finish; it is **off by default** (`agents.defaults.blockStreamingDefault: "off"`). Tune the boundary via `agents.defaults.blockStreamingBreak` (`text_end` vs `message_end`; defaults to text_end). Control soft block chunking with `agents.defaults.blockStreamingChunk` (defaults to -800–1200 chars; prefers paragraph breaks, then newlines; sentences last). +800-1200 chars; prefers paragraph breaks, then newlines; sentences last). Coalesce streamed chunks with `agents.defaults.blockStreamingCoalesce` to reduce single-line spam (idle-based merging before send). Non-Telegram channels require explicit `*.blockStreaming: true` to enable block replies. diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index ddb0c861e61..ab11b45c76e 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -27,21 +27,21 @@ Dedicated deep references: - [Slash commands](/tools/slash-commands) for the current built-in + bundled command catalog - owning channel/plugin pages for channel-specific command surfaces -Config format is **JSON5** (comments + trailing commas allowed). All fields are optional — OpenClaw uses safe defaults when omitted. +Config format is **JSON5** (comments + trailing commas allowed). All fields are optional - OpenClaw uses safe defaults when omitted. --- ## Channels -Per-channel config keys moved to a dedicated page — see -[Configuration — channels](/gateway/config-channels) for `channels.*`, +Per-channel config keys moved to a dedicated page - see +[Configuration - channels](/gateway/config-channels) for `channels.*`, including Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, and other bundled channels (auth, access control, multi-account, mention gating). ## Agent defaults, multi-agent, sessions, and messages -Moved to a dedicated page — see -[Configuration — agents](/gateway/config-agents) for: +Moved to a dedicated page - see +[Configuration - agents](/gateway/config-agents) for: - `agents.defaults.*` (workspace, model, thinking, heartbeat, memory, media, skills, sandbox) - `multiAgent.*` (multi-agent routing and bindings) @@ -54,13 +54,13 @@ Moved to a dedicated page — see ## Tools and custom providers Tool policy, experimental toggles, provider-backed tool config, and custom -provider / base-URL setup moved to a dedicated page — see -[Configuration — tools and custom providers](/gateway/config-tools). +provider / base-URL setup moved to a dedicated page - see +[Configuration - tools and custom providers](/gateway/config-tools). ## Models Provider definitions, model allowlists, and custom provider setup live in -[Configuration — tools and custom providers](/gateway/config-tools#custom-providers-and-base-urls). +[Configuration - tools and custom providers](/gateway/config-tools#custom-providers-and-base-urls). The `models` root also owns global model-catalog behavior. ```json5 @@ -968,7 +968,7 @@ Notes: - `otel.headers`: extra HTTP/gRPC metadata headers sent with OTel export requests. - `otel.serviceName`: service name for resource attributes. - `otel.traces` / `otel.metrics` / `otel.logs`: enable trace, metrics, or log export. -- `otel.sampleRate`: trace sampling rate `0`–`1`. +- `otel.sampleRate`: trace sampling rate `0`-`1`. - `otel.flushIntervalMs`: periodic telemetry flush interval in ms. - `otel.captureContent`: opt-in raw content capture for OTEL span attributes. Defaults to off. Boolean `true` captures non-system message/tool content; the object form lets you enable `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs`, and `systemPrompt` explicitly. - `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: environment toggle for latest experimental GenAI span provider attributes. By default spans keep the legacy `gen_ai.system` attribute for compatibility; GenAI metrics use bounded semantic attributes. @@ -998,7 +998,7 @@ Notes: } ``` -- `channel`: release channel for npm/git installs — `"stable"`, `"beta"`, or `"dev"`. +- `channel`: release channel for npm/git installs - `"stable"`, `"beta"`, or `"dev"`. - `checkOnStart`: check for npm updates when the gateway starts (default: `true`). - `auto.enabled`: enable background auto-update for package installs (default: `false`). - `auto.stableDelayHours`: minimum delay in hours before stable-channel auto-apply (default: `6`; max: `168`). @@ -1162,9 +1162,9 @@ Current builds no longer include the TCP bridge. Nodes connect over the Gateway } ``` -- `maxAttempts`: maximum retries for one-shot jobs on transient errors (default: `3`; range: `0`–`10`). -- `backoffMs`: array of backoff delays in ms for each retry attempt (default: `[30000, 60000, 300000]`; 1–10 entries). -- `retryOn`: error types that trigger retries — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omit to retry all transient types. +- `maxAttempts`: maximum retries for one-shot jobs on transient errors (default: `3`; range: `0`-`10`). +- `backoffMs`: array of backoff delays in ms for each retry attempt (default: `[30000, 60000, 300000]`; 1-10 entries). +- `retryOn`: error types that trigger retries - `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omit to retry all transient types. Applies only to one-shot cron jobs. Recurring jobs use separate failure handling. @@ -1189,7 +1189,7 @@ Applies only to one-shot cron jobs. Recurring jobs use separate failure handling - `after`: consecutive failures before an alert fires (positive integer, min: `1`). - `cooldownMs`: minimum milliseconds between repeated alerts for the same job (non-negative integer). - `includeSkipped`: count consecutive skipped runs toward the alert threshold (default: `false`). Skipped runs are tracked separately and do not affect execution-error backoff. -- `mode`: delivery mode — `"announce"` sends via a channel message; `"webhook"` posts to the configured webhook. +- `mode`: delivery mode - `"announce"` sends via a channel message; `"webhook"` posts to the configured webhook. - `accountId`: optional account or channel id to scope alert delivery. ### `cron.failureDestination` diff --git a/docs/gateway/tools-invoke-http-api.md b/docs/gateway/tools-invoke-http-api.md index b3a89f08e05..de4db35dc58 100644 --- a/docs/gateway/tools-invoke-http-api.md +++ b/docs/gateway/tools-invoke-http-api.md @@ -6,9 +6,7 @@ read_when: title: "Tools invoke API" --- -# Tools Invoke (HTTP) - -OpenClaw’s Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled and uses Gateway auth plus tool policy. Like the OpenAI-compatible `/v1/*` surface, shared-secret bearer auth is treated as trusted operator access for the whole gateway. +OpenClaw's Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled and uses Gateway auth plus tool policy. Like the OpenAI-compatible `/v1/*` surface, shared-secret bearer auth is treated as trusted operator access for the whole gateway. - `POST /tools/invoke` - Same port as the Gateway (WS + HTTP multiplex): `http://:/tools/invoke` @@ -103,19 +101,19 @@ Important boundary notes: Gateway HTTP also applies a hard deny list by default (even if session policy allows the tool): -- `exec` — direct command execution (RCE surface) -- `spawn` — arbitrary child process creation (RCE surface) -- `shell` — shell command execution (RCE surface) -- `fs_write` — arbitrary file mutation on the host -- `fs_delete` — arbitrary file deletion on the host -- `fs_move` — arbitrary file move/rename on the host -- `apply_patch` — patch application can rewrite arbitrary files -- `sessions_spawn` — session orchestration; spawning agents remotely is RCE -- `sessions_send` — cross-session message injection -- `cron` — persistent automation control plane -- `gateway` — gateway control plane; prevents reconfiguration via HTTP -- `nodes` — node command relay can reach system.run on paired hosts -- `whatsapp_login` — interactive setup requiring terminal QR scan; hangs on HTTP +- `exec` - direct command execution (RCE surface) +- `spawn` - arbitrary child process creation (RCE surface) +- `shell` - shell command execution (RCE surface) +- `fs_write` - arbitrary file mutation on the host +- `fs_delete` - arbitrary file deletion on the host +- `fs_move` - arbitrary file move/rename on the host +- `apply_patch` - patch application can rewrite arbitrary files +- `sessions_spawn` - session orchestration; spawning agents remotely is RCE +- `sessions_send` - cross-session message injection +- `cron` - persistent automation control plane +- `gateway` - gateway control plane; prevents reconfiguration via HTTP +- `nodes` - node command relay can reach system.run on paired hosts +- `whatsapp_login` - interactive setup requiring terminal QR scan; hangs on HTTP You can customize this deny list via `gateway.tools`: diff --git a/docs/security/formal-verification.md b/docs/security/formal-verification.md index bcd6fdda6b5..7913ae14b2e 100644 --- a/docs/security/formal-verification.md +++ b/docs/security/formal-verification.md @@ -1,5 +1,5 @@ --- -summary: Machine-checked security models for OpenClaw’s highest-risk paths. +summary: Machine-checked security models for OpenClaw's highest-risk paths. title: Formal verification (security models) read_when: - Reviewing formal security model guarantees or limits @@ -7,7 +7,7 @@ read_when: permalink: /security/formal-verification/ --- -This page tracks OpenClaw’s **formal security models** (TLA+/TLC today; more as needed). +This page tracks OpenClaw's **formal security models** (TLA+/TLC today; more as needed). > Note: some older links may refer to the previous project name. @@ -20,7 +20,7 @@ misconfiguration safety), under explicit assumptions. - Each claim has a runnable model-check over a finite state space. - Many claims have a paired **negative model** that produces a counterexample trace for a realistic bug class. -**What this is not (yet):** a proof that “OpenClaw is secure in all respects” or that the full TypeScript implementation is correct. +**What this is not (yet):** a proof that "OpenClaw is secure in all respects" or that the full TypeScript implementation is correct. ## Where the models live @@ -29,7 +29,7 @@ Models are maintained in a separate repo: [vignesh07/openclaw-formal-models](htt ## Important caveats - These are **models**, not the full TypeScript implementation. Drift between model and code is possible. -- Results are bounded by the state space explored by TLC; “green” does not imply security beyond the modeled assumptions and bounds. +- Results are bounded by the state space explored by TLC; "green" does not imply security beyond the modeled assumptions and bounds. - Some claims rely on explicit environmental assumptions (e.g., correct deployment, correct configuration inputs). ## Reproducing results @@ -37,7 +37,7 @@ Models are maintained in a separate repo: [vignesh07/openclaw-formal-models](htt Today, results are reproduced by cloning the models repo locally and running TLC (see below). A future iteration could offer: - CI-run models with public artifacts (counterexample traces, run logs) -- a hosted “run this model” workflow for small, bounded checks +- a hosted "run this model" workflow for small, bounded checks Getting started: @@ -87,7 +87,7 @@ See also: `docs/gateway-exposure-matrix.md` in the models repo. ### Ingress gating (mentions + control-command bypass) -**Claim:** in group contexts requiring mention, an unauthorized “control command” cannot bypass mention gating. +**Claim:** in group contexts requiring mention, an unauthorized "control command" cannot bypass mention gating. - Green: - `make ingress-gating` @@ -109,11 +109,11 @@ These are follow-on models that tighten fidelity around real-world failure modes ### Pairing store concurrency / idempotency -**Claim:** a pairing store should enforce `MaxPending` and idempotency even under interleavings (i.e., “check-then-write” must be atomic / locked; refresh shouldn’t create duplicates). +**Claim:** a pairing store should enforce `MaxPending` and idempotency even under interleavings (i.e., "check-then-write" must be atomic / locked; refresh shouldn't create duplicates). What it means: -- Under concurrent requests, you can’t exceed `MaxPending` for a channel. +- Under concurrent requests, you can't exceed `MaxPending` for a channel. - Repeated requests/refreshes for the same `(channel, sender)` should not create duplicate live pending rows. - Green runs: diff --git a/docs/tools/browser-control.md b/docs/tools/browser-control.md index 88e4fbc23f3..65dd0b0d423 100644 --- a/docs/tools/browser-control.md +++ b/docs/tools/browser-control.md @@ -70,7 +70,7 @@ Other runtime failures may still return `{ "error": "" }` without a ### Playwright requirement Some features (navigate/act/AI snapshot/role snapshot, element screenshots, -PDF) require Playwright. If Playwright isn’t installed, those endpoints return +PDF) require Playwright. If Playwright isn't installed, those endpoints return a clear 501 error. What still works without Playwright: @@ -242,12 +242,12 @@ Snapshot flags at a glance: ## Snapshots and refs -OpenClaw supports two “snapshot” styles: +OpenClaw supports two "snapshot" styles: - **AI snapshot (numeric refs)**: `openclaw browser snapshot` (default; `--format ai`) - Output: a text snapshot that includes numeric refs. - Actions: `openclaw browser click 12`, `openclaw browser type 23 "hello"`. - - Internally, the ref is resolved via Playwright’s `aria-ref`. + - Internally, the ref is resolved via Playwright's `aria-ref`. - **Role snapshot (role refs like `e12`)**: `openclaw browser snapshot --interactive` (or `--compact`, `--depth`, `--selector`, `--frame`) - Output: a role-based list/tree with `[ref=e12]` (and optional `[nth=1]`). @@ -304,7 +304,7 @@ openclaw browser wait "#main" \ ## Debug workflows -When an action fails (e.g. “not visible”, “strict mode violation”, “covered”): +When an action fails (e.g. "not visible", "strict mode violation", "covered"): 1. `openclaw browser snapshot --interactive` 2. Use `click ` / `type ` (prefer role refs in interactive mode) @@ -334,7 +334,7 @@ Role snapshots in JSON include `refs` plus a small `stats` block (lines/chars/re ## State and environment knobs -These are useful for “make the site behave like X” workflows: +These are useful for "make the site behave like X" workflows: - Cookies: `cookies`, `cookies set`, `cookies clear` - Storage: `storage local|session get|set|clear` @@ -374,7 +374,7 @@ Strict-mode example (block private/internal destinations by default): ## Related -- [Browser](/tools/browser) — overview, configuration, profiles, security -- [Browser login](/tools/browser-login) — signing in to sites +- [Browser](/tools/browser) - overview, configuration, profiles, security +- [Browser login](/tools/browser-login) - signing in to sites - [Browser Linux troubleshooting](/tools/browser-linux-troubleshooting) - [Browser WSL2 troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)