From 61481eb34fa4f4b9e513cabe97ba809a3b9cf8c0 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Tue, 5 May 2026 18:13:16 -0700 Subject: [PATCH] docs: tighten architecture, btw, agent-send hygiene MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/concepts/architecture.md: replaced 8 non-breaking hyphen characters (U+2011) with regular hyphens. Non-breaking hyphens defeat copy-paste from rendered HTML, break grep on the raw markdown, and make Mintlify search miss otherwise-correct queries. Affected words: 'long-lived', 'server-push', 'device-based'. docs/tools/btw.md: converted the 3-bullet Related list into a CardGroup. Renamed 'Thinking Levels' to sentence-case 'Thinking levels' and added a Steer-command card so readers comparing ephemeral vs in-run intervention paths see both options. docs/tools/agent-send.md: converted the 3-bullet Related list into a CardGroup. Removed two em-dash characters in the bullet copy ('Sub-agents — background sub-agent spawning', 'Sessions — how session keys work') and added a Slash-commands card. Verified /cli/agent, /tools/subagents, /concepts/session, and /tools/slash-commands targets all exist. --- docs/concepts/architecture.md | 16 ++++++++-------- docs/tools/agent-send.md | 17 ++++++++++++++--- docs/tools/btw.md | 17 ++++++++++++++--- 3 files changed, 36 insertions(+), 14 deletions(-) diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md index 12eb20573e6..68785235b04 100644 --- a/docs/concepts/architecture.md +++ b/docs/concepts/architecture.md @@ -7,7 +7,7 @@ title: "Gateway architecture" ## Overview -- A single long‑lived **Gateway** owns all messaging surfaces (WhatsApp via +- A single long-lived **Gateway** owns all messaging surfaces (WhatsApp via Baileys, Telegram via grammY, Slack, Discord, Signal, iMessage, WebChat). - Control-plane clients (macOS app, CLI, web UI, automations) connect to the Gateway over **WebSocket** on the configured bind host (default @@ -25,7 +25,7 @@ title: "Gateway architecture" ### Gateway (daemon) - Maintains provider connections. -- Exposes a typed WS API (requests, responses, server‑push events). +- Exposes a typed WS API (requests, responses, server-push events). - Validates inbound frames against JSON Schema. - Emits events like `agent`, `chat`, `presence`, `health`, `heartbeat`, `cron`. @@ -38,7 +38,7 @@ title: "Gateway architecture" ### Nodes (macOS / iOS / Android / headless) - Connect to the **same WS server** with `role: node`. -- Provide a device identity in `connect`; pairing is **device‑based** (role `node`) and +- Provide a device identity in `connect`; pairing is **device-based** (role `node`) and approval lives in the device pairing store. - Expose commands like `canvas.*`, `camera.*`, `screen.record`, `location.get`. @@ -90,8 +90,8 @@ sequenceDiagram instead of `connect.params.auth.*`. - Private-ingress `gateway.auth.mode: "none"` disables shared-secret auth entirely; keep that mode off public/untrusted ingress. -- Idempotency keys are required for side‑effecting methods (`send`, `agent`) to - safely retry; the server keeps a short‑lived dedupe cache. +- Idempotency keys are required for side-effecting methods (`send`, `agent`) to + safely retry; the server keeps a short-lived dedupe cache. - Nodes must include `role: "node"` plus caps/commands/permissions in `connect`. ## Pairing + local trust @@ -109,7 +109,7 @@ sequenceDiagram - Signature payload `v3` also binds `platform` + `deviceFamily`; the gateway pins paired metadata on reconnect and requires repair pairing for metadata changes. -- **Non‑local** connects still require explicit approval. +- **Non-local** connects still require explicit approval. - Gateway auth (`gateway.auth.*`) still applies to **all** connections, local or remote. @@ -138,12 +138,12 @@ Details: [Gateway protocol](/gateway/protocol), [Pairing](/channels/pairing), - Start: `openclaw gateway` (foreground, logs to stdout). - Health: `health` over WS (also included in `hello-ok`). -- Supervision: launchd/systemd for auto‑restart. +- Supervision: launchd/systemd for auto-restart. ## Invariants - Exactly one Gateway controls a single Baileys session per host. -- Handshake is mandatory; any non‑JSON or non‑connect first frame is a hard close. +- Handshake is mandatory; any non-JSON or non-connect first frame is a hard close. - Events are not replayed; clients must refresh on gaps. ## Related diff --git a/docs/tools/agent-send.md b/docs/tools/agent-send.md index 152726dbc89..daf53324897 100644 --- a/docs/tools/agent-send.md +++ b/docs/tools/agent-send.md @@ -93,6 +93,17 @@ openclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram ## Related -- [Agent CLI reference](/cli/agent) -- [Sub-agents](/tools/subagents) — background sub-agent spawning -- [Sessions](/concepts/session) — how session keys work + + + Full `openclaw agent` flag and option reference. + + + Background sub-agent spawning. + + + How session keys work and how `--to`, `--agent`, and `--session-id` resolve them. + + + Native command catalog used inside agent sessions. + + diff --git a/docs/tools/btw.md b/docs/tools/btw.md index ccf73c996f9..f7b07b4b0e1 100644 --- a/docs/tools/btw.md +++ b/docs/tools/btw.md @@ -136,6 +136,17 @@ In that case, ask normally in the main session instead of using BTW. ## Related -- [Slash commands](/tools/slash-commands) -- [Thinking Levels](/tools/thinking) -- [Session](/concepts/session) + + + Native command catalog and chat directives. + + + Reasoning effort levels for the side-question model call. + + + Session keys, history, and persistence semantics. + + + Inject a steering message into the active run without ending it. + +