From f505c84285d6e020c95135eb14139e614c229d29 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Tue, 5 May 2026 22:16:00 -0700 Subject: [PATCH] docs: typography hygiene across 7 high-traffic pages --- docs/channels/channel-routing.md | 12 ++++++------ docs/channels/group-messages.md | 10 +++++----- docs/nodes/index.md | 8 ++++---- docs/platforms/mac/bundled-gateway.md | 10 +++++----- docs/platforms/mac/canvas.md | 8 ++++---- docs/platforms/mac/peekaboo.md | 8 ++++---- docs/start/onboarding.md | 8 ++++---- 7 files changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/channels/channel-routing.md b/docs/channels/channel-routing.md index b7beff35c3e..e0b26838790 100644 --- a/docs/channels/channel-routing.md +++ b/docs/channels/channel-routing.md @@ -14,11 +14,11 @@ host configuration. ## Key terms - **Channel**: `telegram`, `whatsapp`, `discord`, `irc`, `googlechat`, `slack`, `signal`, `imessage`, `line`, plus plugin channels. `webchat` is the internal WebChat UI channel and is not a configurable outbound channel. -- **AccountId**: per‑channel account instance (when supported). +- **AccountId**: per-channel account instance (when supported). - Optional channel default account: `channels..defaultAccount` chooses which account is used when an outbound path does not specify `accountId`. - In multi-account setups, set an explicit default (`defaultAccount` or `accounts.default`) when two or more accounts are configured. Without it, fallback routing may pick the first normalized account ID. -- **AgentId**: an isolated workspace + session store (“brain”). +- **AgentId**: an isolated workspace + session store ("brain"). - **SessionKey**: the bucket key used to store context and control concurrency. ## Outbound target prefixes @@ -29,7 +29,7 @@ Target-kind and service prefixes such as `channel:`, `user:`, `room: ## Session key shapes (examples) -Direct messages collapse to the agent’s **main** session by default: +Direct messages collapse to the agent's **main** session by default: - `agent::` (default: `agent:main:main`) @@ -55,7 +55,7 @@ Examples: ## Main DM route pinning When `session.dmScope` is `main`, direct messages may share one main session. -To prevent the session’s `lastRoute` from being overwritten by non-owner DMs, +To prevent the session's `lastRoute` from being overwritten by non-owner DMs, OpenClaw infers a pinned owner from `allowFrom` when all of these are true: - `allowFrom` has exactly one non-wildcard entry. @@ -142,8 +142,8 @@ stores must stay inside that resolved agent root and use a regular ## WebChat behavior -WebChat attaches to the **selected agent** and defaults to the agent’s main -session. Because of this, WebChat lets you see cross‑channel context for that +WebChat attaches to the **selected agent** and defaults to the agent's main +session. Because of this, WebChat lets you see cross-channel context for that agent in one place. ## Reply context diff --git a/docs/channels/group-messages.md b/docs/channels/group-messages.md index 280ceba64b4..e6ac005b4a3 100644 --- a/docs/channels/group-messages.md +++ b/docs/channels/group-messages.md @@ -18,13 +18,13 @@ Goal: let OpenClaw sit in WhatsApp groups, wake up only when pinged, and keep th ## Behavior -- Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, safe regex patterns, or the bot’s E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the exact silent token `NO_REPLY` / `no_reply`. Defaults can be set in config (`channels.whatsapp.groups`) and overridden per group via `/activation`. When `channels.whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all). +- Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, safe regex patterns, or the bot's E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the exact silent token `NO_REPLY` / `no_reply`. Defaults can be set in config (`channels.whatsapp.groups`) and overridden per group via `/activation`. When `channels.whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all). - Group policy: `channels.whatsapp.groupPolicy` controls whether group messages are accepted (`open|disabled|allowlist`). `allowlist` uses `channels.whatsapp.groupAllowFrom` (fallback: explicit `channels.whatsapp.allowFrom`). Default is `allowlist` (blocked until you add senders). - Per-group sessions: session keys look like `agent::whatsapp:group:` so commands such as `/verbose on`, `/trace on`, or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads. - Context injection: **pending-only** group messages (default 50) that _did not_ trigger a run are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`. Messages already in the session are not re-injected. - Sender surfacing: every group batch now ends with `[from: Sender Name (+E164)]` so Pi knows who is speaking. - Ephemeral/view-once: we unwrap those before extracting text/mentions, so pings inside them still trigger. -- Group system prompt: on the first turn of a group session (and whenever `/activation` changes the mode) we inject a short blurb into the system prompt like `You are replying inside the WhatsApp group "". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` If metadata isn’t available we still tell the agent it’s a group chat. +- Group system prompt: on the first turn of a group session (and whenever `/activation` changes the mode) we inject a short blurb into the system prompt like `You are replying inside the WhatsApp group "". Group members: Alice (+44...), Bob (+43...), ... Activation: trigger-only ... Address the specific sender noted in the message context.` If metadata isn't available we still tell the agent it's a group chat. ## Config example (WhatsApp) @@ -65,14 +65,14 @@ Use the group chat command: - `/activation mention` - `/activation always` -Only the owner number (from `channels.whatsapp.allowFrom`, or the bot’s own E.164 when unset) can change this. Send `/status` as a standalone message in the group to see the current activation mode. +Only the owner number (from `channels.whatsapp.allowFrom`, or the bot's own E.164 when unset) can change this. Send `/status` as a standalone message in the group to see the current activation mode. ## How to use 1. Add your WhatsApp account (the one running OpenClaw) to the group. 2. Say `@openclaw …` (or include the number). Only allowlisted senders can trigger it unless you set `groupPolicy: "open"`. 3. The agent prompt will include recent group context plus the trailing `[from: …]` marker so it can address the right person. -4. Session-level directives (`/verbose on`, `/trace on`, `/think high`, `/new` or `/reset`, `/compact`) apply only to that group’s session; send them as standalone messages so they register. Your personal DM session remains independent. +4. Session-level directives (`/verbose on`, `/trace on`, `/think high`, `/new` or `/reset`, `/compact`) apply only to that group's session; send them as standalone messages so they register. Your personal DM session remains independent. ## Testing / verification @@ -85,7 +85,7 @@ Only the owner number (from `channels.whatsapp.allowFrom`, or the bot’s own E. - Heartbeats are intentionally skipped for groups to avoid noisy broadcasts. - Echo suppression uses the combined batch string; if you send identical text twice without mentions, only the first will get a response. -- Session store entries will appear as `agent::whatsapp:group:` in the session store (`~/.openclaw/agents//sessions/sessions.json` by default); a missing entry just means the group hasn’t triggered a run yet. +- Session store entries will appear as `agent::whatsapp:group:` in the session store (`~/.openclaw/agents//sessions/sessions.json` by default); a missing entry just means the group hasn't triggered a run yet. - Typing indicators in groups follow `agents.defaults.typingMode`. When visible replies use the default message-tool-only mode, typing starts immediately by default so group members can see the agent is working even if no automatic final reply is posted. Explicit typing-mode config still wins. ## Related diff --git a/docs/nodes/index.md b/docs/nodes/index.md index 20f4a754051..7f2460502a8 100644 --- a/docs/nodes/index.md +++ b/docs/nodes/index.md @@ -12,7 +12,7 @@ A **node** is a companion device (macOS/iOS/Android/headless) that connects to t Legacy transport: [Bridge protocol](/gateway/bridge-protocol) (TCP JSONL; historical only for current nodes). -macOS can also run in **node mode**: the menubar app connects to the Gateway’s +macOS can also run in **node mode**: the menubar app connects to the Gateway's WS server and exposes its local canvas/camera commands as a node (so `openclaw nodes …` works against this Mac). In remote gateway mode, browser automation is handled by the CLI node host (`openclaw node run` or the @@ -20,7 +20,7 @@ installed node service), not by the native app node. Notes: -- Nodes are **peripherals**, not gateways. They don’t run the gateway service. +- Nodes are **peripherals**, not gateways. They don't run the gateway service. - Telegram/WhatsApp/etc. messages land on the **gateway**, not on nodes. - Troubleshooting runbook: [/nodes/troubleshooting](/nodes/troubleshooting) @@ -186,7 +186,7 @@ Low-level (raw RPC): openclaw nodes invoke --node --command canvas.eval --params '{"javaScript":"location.href"}' ``` -Higher-level helpers exist for the common “give the agent a MEDIA attachment” workflows. +Higher-level helpers exist for the common "give the agent a MEDIA attachment" workflows. ## Command policy @@ -304,7 +304,7 @@ openclaw nodes location get --node --accuracy precise --max-age 1 Notes: - Location is **off by default**. -- “Always” requires system permission; background fetch is best-effort. +- "Always" requires system permission; background fetch is best-effort. - The response includes lat/lon, accuracy (meters), and timestamp. ## SMS (Android nodes) diff --git a/docs/platforms/mac/bundled-gateway.md b/docs/platforms/mac/bundled-gateway.md index 1f73a55e0ad..2a9b58b6475 100644 --- a/docs/platforms/mac/bundled-gateway.md +++ b/docs/platforms/mac/bundled-gateway.md @@ -9,7 +9,7 @@ title: "Gateway on macOS" OpenClaw.app no longer bundles Node/Bun or the Gateway runtime. The macOS app expects an **external** `openclaw` CLI install, does not spawn the Gateway as a -child process, and manages a per‑user launchd service to keep the Gateway +child process, and manages a per-user launchd service to keep the Gateway running (or attaches to an existing local Gateway if one is already running). ## Install the CLI (required for local mode) @@ -20,7 +20,7 @@ Node 24 is the default runtime on the Mac. Node 22 LTS, currently `22.14+`, stil npm install -g openclaw@ ``` -The macOS app’s **Install CLI** button runs the same global install flow the app +The macOS app's **Install CLI** button runs the same global install flow the app uses internally: it prefers npm first, then pnpm, then bun if that is the only detected package manager. Node remains the recommended Gateway runtime. @@ -30,7 +30,7 @@ Label: - `ai.openclaw.gateway` (or `ai.openclaw.`; legacy `com.openclaw.*` may remain) -Plist location (per‑user): +Plist location (per-user): - `~/Library/LaunchAgents/ai.openclaw.gateway.plist` (or `~/Library/LaunchAgents/ai.openclaw..plist`) @@ -42,7 +42,7 @@ Manager: Behavior: -- “OpenClaw Active” enables/disables the LaunchAgent. +- "OpenClaw Active" enables/disables the LaunchAgent. - App quit does **not** stop the gateway (launchd keeps it alive). - If a Gateway is already running on the configured port, the app attaches to it instead of starting a new one. @@ -53,7 +53,7 @@ Logging: ## Version compatibility -The macOS app checks the gateway version against its own version. If they’re +The macOS app checks the gateway version against its own version. If they're incompatible, update the global CLI to match the app version. ## Smoke check diff --git a/docs/platforms/mac/canvas.md b/docs/platforms/mac/canvas.md index 828472c916d..d8404bd9262 100644 --- a/docs/platforms/mac/canvas.md +++ b/docs/platforms/mac/canvas.md @@ -7,7 +7,7 @@ read_when: title: "Canvas" --- -The macOS app embeds an agent‑controlled **Canvas panel** using `WKWebView`. It +The macOS app embeds an agent-controlled **Canvas panel** using `WKWebView`. It is a lightweight visual workspace for HTML/CSS/JS, A2UI, and small interactive UI surfaces. @@ -27,13 +27,13 @@ Examples: - `openclaw-canvas://main/assets/app.css` → `/main/assets/app.css` - `openclaw-canvas://main/widgets/todo/` → `/main/widgets/todo/index.html` -If no `index.html` exists at the root, the app shows a **built‑in scaffold page**. +If no `index.html` exists at the root, the app shows a **built-in scaffold page**. ## Panel behavior - Borderless, resizable panel anchored near the menu bar (or mouse cursor). - Remembers size/position per session. -- Auto‑reloads when local canvas files change. +- Auto-reloads when local canvas files change. - Only one Canvas panel is visible at a time (session is switched as needed). Canvas can be disabled from Settings → **Allow Canvas**. When disabled, canvas @@ -65,7 +65,7 @@ Notes: ## A2UI in Canvas A2UI is hosted by the Gateway canvas host and rendered inside the Canvas panel. -When the Gateway advertises a Canvas host, the macOS app auto‑navigates to the +When the Gateway advertises a Canvas host, the macOS app auto-navigates to the A2UI host page on first open. Default A2UI host URL: diff --git a/docs/platforms/mac/peekaboo.md b/docs/platforms/mac/peekaboo.md index 933b13c9118..f16704b6004 100644 --- a/docs/platforms/mac/peekaboo.md +++ b/docs/platforms/mac/peekaboo.md @@ -8,9 +8,9 @@ read_when: title: "Peekaboo bridge" --- -OpenClaw can host **PeekabooBridge** as a local, permission‑aware UI automation +OpenClaw can host **PeekabooBridge** as a local, permission-aware UI automation broker. This lets the `peekaboo` CLI drive UI automation while reusing the -macOS app’s TCC permissions. +macOS app's TCC permissions. ## What this is (and is not) @@ -76,11 +76,11 @@ export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock ## Snapshot behavior (automation) Snapshots are stored in memory and expire automatically after a short window. -If you need longer retention, re‑capture from the client. +If you need longer retention, re-capture from the client. ## Troubleshooting -- If `peekaboo` reports “bridge client is not authorized”, ensure the client is +- If `peekaboo` reports "bridge client is not authorized", ensure the client is properly signed or run the host with `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` in **debug** mode only. - If no hosts are found, open one of the host apps (Peekaboo.app or OpenClaw.app) diff --git a/docs/start/onboarding.md b/docs/start/onboarding.md index db1871a38a4..c60a85737b6 100644 --- a/docs/start/onboarding.md +++ b/docs/start/onboarding.md @@ -7,8 +7,8 @@ title: "Onboarding (macOS app)" sidebarTitle: "Onboarding: macOS App" --- -This doc describes the **current** first‑run setup flow. The goal is a -smooth “day 0” experience: pick where the Gateway runs, connect auth, run the +This doc describes the **current** first-run setup flow. The goal is a +smooth "day 0" experience: pick where the Gateway runs, connect auth, run the wizard, and let the agent bootstrap itself. For a general overview of onboarding paths, see [Onboarding Overview](/start/onboarding-overview). @@ -54,7 +54,7 @@ Where does the **Gateway** run? - The wizard now generates a **token** even for loopback, so local WS clients must authenticate. - If you disable auth, any local process can connect; use that only on fully trusted machines. -- Use a **token** for multi‑machine access or non‑loopback binds. +- Use a **token** for multi-machine access or non-loopback binds. @@ -83,7 +83,7 @@ Onboarding requests TCC permissions needed for: After setup, the app opens a dedicated onboarding chat session so the agent can - introduce itself and guide next steps. This keeps first‑run guidance separate + introduce itself and guide next steps. This keeps first-run guidance separate from your normal conversation. See [Bootstrapping](/start/bootstrapping) for what happens on the gateway host during the first agent run.