mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 05:10:44 +00:00
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:
@@ -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
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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>
|
||||
|
||||
Reference in New Issue
Block a user