mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 11:20:43 +00:00
docs: typography hygiene across 7 high-traffic pages
This commit is contained in:
Vincent Koc
@@ -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.<channel>.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:<id>`, `user:<id>`, `room:<id>
|
||||
|
||||
## 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:<agentId>:<mainKey>` (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
|
||||
|
||||
@@ -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:<agentId>:whatsapp:group:<jid>` 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 "<subject>". 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 "<subject>". 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:<agentId>:whatsapp:group:<jid>` in the session store (`~/.openclaw/agents/<agentId>/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:<agentId>:whatsapp:group:<jid>` in the session store (`~/.openclaw/agents/<agentId>/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
|
||||
|
||||
@@ -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 <idOrNameOrIp> --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 <idOrNameOrIp> --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)
|
||||
|
||||
@@ -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@<version>
|
||||
```
|
||||
|
||||
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.<profile>`; legacy `com.openclaw.*` may remain)
|
||||
|
||||
Plist location (per‑user):
|
||||
Plist location (per-user):
|
||||
|
||||
- `~/Library/LaunchAgents/ai.openclaw.gateway.plist`
|
||||
(or `~/Library/LaunchAgents/ai.openclaw.<profile>.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
|
||||
|
||||
@@ -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` → `<canvasRoot>/main/assets/app.css`
|
||||
- `openclaw-canvas://main/widgets/todo/` → `<canvasRoot>/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:
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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.
|
||||
|
||||
</Tip>
|
||||
</Step>
|
||||
@@ -83,7 +83,7 @@ Onboarding requests TCC permissions needed for:
|
||||
</Step>
|
||||
<Step title="Onboarding Chat (dedicated session)">
|
||||
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.
|
||||
</Step>
|
||||
|
||||
Reference in New Issue
Block a user