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

View File

@@ -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
<CardGroup cols={2}>
<Card title="Agent CLI reference" href="/cli/agent" icon="terminal">
Full `openclaw agent` flag and option reference.
</Card>
<Card title="Sub-agents" href="/tools/subagents" icon="users">
Background sub-agent spawning.
</Card>
<Card title="Sessions" href="/concepts/session" icon="comments">
How session keys work and how `--to`, `--agent`, and `--session-id` resolve them.
</Card>
<Card title="Slash commands" href="/tools/slash-commands" icon="slash">
Native command catalog used inside agent sessions.
</Card>
</CardGroup>

View File

@@ -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)
<CardGroup cols={2}>
<Card title="Slash commands" href="/tools/slash-commands" icon="terminal">
Native command catalog and chat directives.
</Card>
<Card title="Thinking levels" href="/tools/thinking" icon="brain">
Reasoning effort levels for the side-question model call.
</Card>
<Card title="Session" href="/concepts/session" icon="comments">
Session keys, history, and persistence semantics.
</Card>
<Card title="Steer command" href="/tools/steer" icon="arrow-right">
Inject a steering message into the active run without ending it.
</Card>
</CardGroup>