docs: tighten architecture, btw, agent-send hygiene

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.
This commit is contained in:
Vincent Koc
2026-05-05 18:13:16 -07:00
parent c744b2c236
commit 61481eb34f
3 changed files with 36 additions and 14 deletions

View File

@@ -7,7 +7,7 @@ title: "Gateway architecture"
## Overview
- A single longlived **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, serverpush 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 **devicebased** (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 sideeffecting methods (`send`, `agent`) to
safely retry; the server keeps a shortlived 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.
- **Nonlocal** 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 autorestart.
- Supervision: launchd/systemd for auto-restart.
## Invariants
- Exactly one Gateway controls a single Baileys session per host.
- Handshake is mandatory; any nonJSON or nonconnect 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