@captain-app/openclaw 2026.2.4

package/docs/concepts/multi-agent.md

@@ -0,0 +1,376 @@
+---
+summary: "Multi-agent routing: isolated agents, channel accounts, and bindings"
+title: Multi-Agent Routing
+read_when: "You want multiple isolated agents (workspaces + auth) in one gateway process."
+status: active
+---
+
+# Multi-Agent Routing
+
+Goal: multiple _isolated_ agents (separate workspace + `agentDir` + sessions), plus multiple channel accounts (e.g. two WhatsApps) in one running Gateway. Inbound is routed to an agent via bindings.
+
+## What is “one agent”?
+
+An **agent** is a fully scoped brain with its own:
+
+- **Workspace** (files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules).
+- **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config.
+- **Session store** (chat history + routing state) under `~/.openclaw/agents/<agentId>/sessions`.
+
+Auth profiles are **per-agent**. Each agent reads from its own:
+
+```
+~/.openclaw/agents/<agentId>/agent/auth-profiles.json
+```
+
+Main agent credentials are **not** shared automatically. Never reuse `agentDir`
+across agents (it causes auth/session collisions). If you want to share creds,
+copy `auth-profiles.json` into the other agent's `agentDir`.
+
+Skills are per-agent via each workspace’s `skills/` folder, with shared skills
+available from `~/.openclaw/skills`. See [Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills).
+
+The Gateway can host **one agent** (default) or **many agents** side-by-side.
+
+**Workspace note:** each agent’s workspace is the **default cwd**, not a hard
+sandbox. Relative paths resolve inside the workspace, but absolute paths can
+reach other host locations unless sandboxing is enabled. See
+[Sandboxing](/gateway/sandboxing).
+
+## Paths (quick map)
+
+- Config: `~/.openclaw/openclaw.json` (or `OPENCLAW_CONFIG_PATH`)
+- State dir: `~/.openclaw` (or `OPENCLAW_STATE_DIR`)
+- Workspace: `~/.openclaw/workspace` (or `~/.openclaw/workspace-<agentId>`)
+- Agent dir: `~/.openclaw/agents/<agentId>/agent` (or `agents.list[].agentDir`)
+- Sessions: `~/.openclaw/agents/<agentId>/sessions`
+
+### Single-agent mode (default)
+
+If you do nothing, OpenClaw runs a single agent:
+
+- `agentId` defaults to **`main`**.
+- Sessions are keyed as `agent:main:<mainKey>`.
+- Workspace defaults to `~/.openclaw/workspace` (or `~/.openclaw/workspace-<profile>` when `OPENCLAW_PROFILE` is set).
+- State defaults to `~/.openclaw/agents/main/agent`.
+
+## Agent helper
+
+Use the agent wizard to add a new isolated agent:
+
+```bash
+openclaw agents add work
+```
+
+Then add `bindings` (or let the wizard do it) to route inbound messages.
+
+Verify with:
+
+```bash
+openclaw agents list --bindings
+```
+
+## Multiple agents = multiple people, multiple personalities
+
+With **multiple agents**, each `agentId` becomes a **fully isolated persona**:
+
+- **Different phone numbers/accounts** (per channel `accountId`).
+- **Different personalities** (per-agent workspace files like `AGENTS.md` and `SOUL.md`).
+- **Separate auth + sessions** (no cross-talk unless explicitly enabled).
+
+This lets **multiple people** share one Gateway server while keeping their AI “brains” and data isolated.
+
+## One WhatsApp number, multiple people (DM split)
+
+You can route **different WhatsApp DMs** to different agents while staying on **one WhatsApp account**. Match on sender E.164 (like `+15551234567`) with `peer.kind: "dm"`. Replies still come from the same WhatsApp number (no per‑agent sender identity).
+
+Important detail: direct chats collapse to the agent’s **main session key**, so true isolation requires **one agent per person**.
+
+Example:
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
+      { id: "mia", workspace: "~/.openclaw/workspace-mia" },
+    ],
+  },
+  bindings: [
+    { agentId: "alex", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
+    { agentId: "mia", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } },
+  ],
+  channels: {
+    whatsapp: {
+      dmPolicy: "allowlist",
+      allowFrom: ["+15551230001", "+15551230002"],
+    },
+  },
+}
+```
+
+Notes:
+
+- DM access control is **global per WhatsApp account** (pairing/allowlist), not per agent.
+- For shared groups, bind the group to one agent or use [Broadcast groups](/broadcast-groups).
+
+## Routing rules (how messages pick an agent)
+
+Bindings are **deterministic** and **most-specific wins**:
+
+1. `peer` match (exact DM/group/channel id)
+2. `guildId` (Discord)
+3. `teamId` (Slack)
+4. `accountId` match for a channel
+5. channel-level match (`accountId: "*"`)
+6. fallback to default agent (`agents.list[].default`, else first list entry, default: `main`)
+
+## Multiple accounts / phone numbers
+
+Channels that support **multiple accounts** (e.g. WhatsApp) use `accountId` to identify
+each login. Each `accountId` can be routed to a different agent, so one server can host
+multiple phone numbers without mixing sessions.
+
+## Concepts
+
+- `agentId`: one “brain” (workspace, per-agent auth, per-agent session store).
+- `accountId`: one channel account instance (e.g. WhatsApp account `"personal"` vs `"biz"`).
+- `binding`: routes inbound messages to an `agentId` by `(channel, accountId, peer)` and optionally guild/team ids.
+- Direct chats collapse to `agent:<agentId>:<mainKey>` (per-agent “main”; `session.mainKey`).
+
+## Example: two WhatsApps → two agents
+
+`~/.openclaw/openclaw.json` (JSON5):
+
+```js
+{
+  agents: {
+    list: [
+      {
+        id: "home",
+        default: true,
+        name: "Home",
+        workspace: "~/.openclaw/workspace-home",
+        agentDir: "~/.openclaw/agents/home/agent",
+      },
+      {
+        id: "work",
+        name: "Work",
+        workspace: "~/.openclaw/workspace-work",
+        agentDir: "~/.openclaw/agents/work/agent",
+      },
+    ],
+  },
+
+  // Deterministic routing: first match wins (most-specific first).
+  bindings: [
+    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
+    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
+
+    // Optional per-peer override (example: send a specific group to work agent).
+    {
+      agentId: "work",
+      match: {
+        channel: "whatsapp",
+        accountId: "personal",
+        peer: { kind: "group", id: "1203630...@g.us" },
+      },
+    },
+  ],
+
+  // Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
+  tools: {
+    agentToAgent: {
+      enabled: false,
+      allow: ["home", "work"],
+    },
+  },
+
+  channels: {
+    whatsapp: {
+      accounts: {
+        personal: {
+          // Optional override. Default: ~/.openclaw/credentials/whatsapp/personal
+          // authDir: "~/.openclaw/credentials/whatsapp/personal",
+        },
+        biz: {
+          // Optional override. Default: ~/.openclaw/credentials/whatsapp/biz
+          // authDir: "~/.openclaw/credentials/whatsapp/biz",
+        },
+      },
+    },
+  },
+}
+```
+
+## Example: WhatsApp daily chat + Telegram deep work
+
+Split by channel: route WhatsApp to a fast everyday agent and Telegram to an Opus agent.
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "chat",
+        name: "Everyday",
+        workspace: "~/.openclaw/workspace-chat",
+        model: "anthropic/claude-sonnet-4-5",
+      },
+      {
+        id: "opus",
+        name: "Deep Work",
+        workspace: "~/.openclaw/workspace-opus",
+        model: "anthropic/claude-opus-4-5",
+      },
+    ],
+  },
+  bindings: [
+    { agentId: "chat", match: { channel: "whatsapp" } },
+    { agentId: "opus", match: { channel: "telegram" } },
+  ],
+}
+```
+
+Notes:
+
+- If you have multiple accounts for a channel, add `accountId` to the binding (for example `{ channel: "whatsapp", accountId: "personal" }`).
+- To route a single DM/group to Opus while keeping the rest on chat, add a `match.peer` binding for that peer; peer matches always win over channel-wide rules.
+
+## Example: same channel, one peer to Opus
+
+Keep WhatsApp on the fast agent, but route one DM to Opus:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "chat",
+        name: "Everyday",
+        workspace: "~/.openclaw/workspace-chat",
+        model: "anthropic/claude-sonnet-4-5",
+      },
+      {
+        id: "opus",
+        name: "Deep Work",
+        workspace: "~/.openclaw/workspace-opus",
+        model: "anthropic/claude-opus-4-5",
+      },
+    ],
+  },
+  bindings: [
+    { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
+    { agentId: "chat", match: { channel: "whatsapp" } },
+  ],
+}
+```
+
+Peer bindings always win, so keep them above the channel-wide rule.
+
+## Family agent bound to a WhatsApp group
+
+Bind a dedicated family agent to a single WhatsApp group, with mention gating
+and a tighter tool policy:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "family",
+        name: "Family",
+        workspace: "~/.openclaw/workspace-family",
+        identity: { name: "Family Bot" },
+        groupChat: {
+          mentionPatterns: ["@family", "@familybot", "@Family Bot"],
+        },
+        sandbox: {
+          mode: "all",
+          scope: "agent",
+        },
+        tools: {
+          allow: [
+            "exec",
+            "read",
+            "sessions_list",
+            "sessions_history",
+            "sessions_send",
+            "sessions_spawn",
+            "session_status",
+          ],
+          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],
+        },
+      },
+    ],
+  },
+  bindings: [
+    {
+      agentId: "family",
+      match: {
+        channel: "whatsapp",
+        peer: { kind: "group", id: "120363999999999999@g.us" },
+      },
+    },
+  ],
+}
+```
+
+Notes:
+
+- Tool allow/deny lists are **tools**, not skills. If a skill needs to run a
+  binary, ensure `exec` is allowed and the binary exists in the sandbox.
+- For stricter gating, set `agents.list[].groupChat.mentionPatterns` and keep
+  group allowlists enabled for the channel.
+
+## Per-Agent Sandbox and Tool Configuration
+
+Starting with v2026.1.6, each agent can have its own sandbox and tool restrictions:
+
+```js
+{
+  agents: {
+    list: [
+      {
+        id: "personal",
+        workspace: "~/.openclaw/workspace-personal",
+        sandbox: {
+          mode: "off",  // No sandbox for personal agent
+        },
+        // No tool restrictions - all tools available
+      },
+      {
+        id: "family",
+        workspace: "~/.openclaw/workspace-family",
+        sandbox: {
+          mode: "all",     // Always sandboxed
+          scope: "agent",  // One container per agent
+          docker: {
+            // Optional one-time setup after container creation
+            setupCommand: "apt-get update && apt-get install -y git curl",
+          },
+        },
+        tools: {
+          allow: ["read"],                    // Only read tool
+          deny: ["exec", "write", "edit", "apply_patch"],    // Deny others
+        },
+      },
+    ],
+  },
+}
+```
+
+Note: `setupCommand` lives under `sandbox.docker` and runs once on container creation.
+Per-agent `sandbox.docker.*` overrides are ignored when the resolved scope is `"shared"`.
+
+**Benefits:**
+
+- **Security isolation**: Restrict tools for untrusted agents
+- **Resource control**: Sandbox specific agents while keeping others on host
+- **Flexible policies**: Different permissions per agent
+
+Note: `tools.elevated` is **global** and sender-based; it is not configurable per agent.
+If you need per-agent boundaries, use `agents.list[].tools` to deny `exec`.
+For group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent.
+
+See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for detailed examples.

package/docs/concepts/oauth.md

@@ -0,0 +1,145 @@
+---
+summary: "OAuth in OpenClaw: token exchange, storage, and multi-account patterns"
+read_when:
+  - You want to understand OpenClaw OAuth end-to-end
+  - You hit token invalidation / logout issues
+  - You want setup-token or OAuth auth flows
+  - You want multiple accounts or profile routing
+title: "OAuth"
+---
+
+# OAuth
+
+OpenClaw supports “subscription auth” via OAuth for providers that offer it (notably **OpenAI Codex (ChatGPT OAuth)**). For Anthropic subscriptions, use the **setup-token** flow. This page explains:
+
+- how the OAuth **token exchange** works (PKCE)
+- where tokens are **stored** (and why)
+- how to handle **multiple accounts** (profiles + per-session overrides)
+
+OpenClaw also supports **provider plugins** that ship their own OAuth or API‑key
+flows. Run them via:
+
+```bash
+openclaw models auth login --provider <id>
+```
+
+## The token sink (why it exists)
+
+OAuth providers commonly mint a **new refresh token** during login/refresh flows. Some providers (or OAuth clients) can invalidate older refresh tokens when a new one is issued for the same user/app.
+
+Practical symptom:
+
+- you log in via OpenClaw _and_ via Claude Code / Codex CLI → one of them randomly gets “logged out” later
+
+To reduce that, OpenClaw treats `auth-profiles.json` as a **token sink**:
+
+- the runtime reads credentials from **one place**
+- we can keep multiple profiles and route them deterministically
+
+## Storage (where tokens live)
+
+Secrets are stored **per-agent**:
+
+- Auth profiles (OAuth + API keys): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+- Runtime cache (managed automatically; don’t edit): `~/.openclaw/agents/<agentId>/agent/auth.json`
+
+Legacy import-only file (still supported, but not the main store):
+
+- `~/.openclaw/credentials/oauth.json` (imported into `auth-profiles.json` on first use)
+
+All of the above also respect `$OPENCLAW_STATE_DIR` (state dir override). Full reference: [/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys)
+
+## Anthropic setup-token (subscription auth)
+
+Run `claude setup-token` on any machine, then paste it into OpenClaw:
+
+```bash
+openclaw models auth setup-token --provider anthropic
+```
+
+If you generated the token elsewhere, paste it manually:
+
+```bash
+openclaw models auth paste-token --provider anthropic
+```
+
+Verify:
+
+```bash
+openclaw models status
+```
+
+## OAuth exchange (how login works)
+
+OpenClaw’s interactive login flows are implemented in `@mariozechner/pi-ai` and wired into the wizards/commands.
+
+### Anthropic (Claude Pro/Max) setup-token
+
+Flow shape:
+
+1. run `claude setup-token`
+2. paste the token into OpenClaw
+3. store as a token auth profile (no refresh)
+
+The wizard path is `openclaw onboard` → auth choice `setup-token` (Anthropic).
+
+### OpenAI Codex (ChatGPT OAuth)
+
+Flow shape (PKCE):
+
+1. generate PKCE verifier/challenge + random `state`
+2. open `https://auth.openai.com/oauth/authorize?...`
+3. try to capture callback on `http://127.0.0.1:1455/auth/callback`
+4. if callback can’t bind (or you’re remote/headless), paste the redirect URL/code
+5. exchange at `https://auth.openai.com/oauth/token`
+6. extract `accountId` from the access token and store `{ access, refresh, expires, accountId }`
+
+Wizard path is `openclaw onboard` → auth choice `openai-codex`.
+
+## Refresh + expiry
+
+Profiles store an `expires` timestamp.
+
+At runtime:
+
+- if `expires` is in the future → use the stored access token
+- if expired → refresh (under a file lock) and overwrite the stored credentials
+
+The refresh flow is automatic; you generally don't need to manage tokens manually.
+
+## Multiple accounts (profiles) + routing
+
+Two patterns:
+
+### 1) Preferred: separate agents
+
+If you want “personal” and “work” to never interact, use isolated agents (separate sessions + credentials + workspace):
+
+```bash
+openclaw agents add work
+openclaw agents add personal
+```
+
+Then configure auth per-agent (wizard) and route chats to the right agent.
+
+### 2) Advanced: multiple profiles in one agent
+
+`auth-profiles.json` supports multiple profile IDs for the same provider.
+
+Pick which profile is used:
+
+- globally via config ordering (`auth.order`)
+- per-session via `/model ...@<profileId>`
+
+Example (session override):
+
+- `/model Opus@anthropic:work`
+
+How to see what profile IDs exist:
+
+- `openclaw channels list --json` (shows `auth[]`)
+
+Related docs:
+
+- [/concepts/model-failover](/concepts/model-failover) (rotation + cooldown rules)
+- [/tools/slash-commands](/tools/slash-commands) (command surface)

package/docs/concepts/presence.md

@@ -0,0 +1,102 @@
+---
+summary: "How OpenClaw presence entries are produced, merged, and displayed"
+read_when:
+  - Debugging the Instances tab
+  - Investigating duplicate or stale instance rows
+  - Changing gateway WS connect or system-event beacons
+title: "Presence"
+---
+
+# Presence
+
+OpenClaw “presence” is a lightweight, best‑effort view of:
+
+- the **Gateway** itself, and
+- **clients connected to the Gateway** (mac app, WebChat, CLI, etc.)
+
+Presence is used primarily to render the macOS app’s **Instances** tab and to
+provide quick operator visibility.
+
+## Presence fields (what shows up)
+
+Presence entries are structured objects with fields like:
+
+- `instanceId` (optional but strongly recommended): stable client identity (usually `connect.client.instanceId`)
+- `host`: human‑friendly host name
+- `ip`: best‑effort IP address
+- `version`: client version string
+- `deviceFamily` / `modelIdentifier`: hardware hints
+- `mode`: `ui`, `webchat`, `cli`, `backend`, `probe`, `test`, `node`, ...
+- `lastInputSeconds`: “seconds since last user input” (if known)
+- `reason`: `self`, `connect`, `node-connected`, `periodic`, ...
+- `ts`: last update timestamp (ms since epoch)
+
+## Producers (where presence comes from)
+
+Presence entries are produced by multiple sources and **merged**.
+
+### 1) Gateway self entry
+
+The Gateway always seeds a “self” entry at startup so UIs show the gateway host
+even before any clients connect.
+
+### 2) WebSocket connect
+
+Every WS client begins with a `connect` request. On successful handshake the
+Gateway upserts a presence entry for that connection.
+
+#### Why one‑off CLI commands don’t show up
+
+The CLI often connects for short, one‑off commands. To avoid spamming the
+Instances list, `client.mode === "cli"` is **not** turned into a presence entry.
+
+### 3) `system-event` beacons
+
+Clients can send richer periodic beacons via the `system-event` method. The mac
+app uses this to report host name, IP, and `lastInputSeconds`.
+
+### 4) Node connects (role: node)
+
+When a node connects over the Gateway WebSocket with `role: node`, the Gateway
+upserts a presence entry for that node (same flow as other WS clients).
+
+## Merge + dedupe rules (why `instanceId` matters)
+
+Presence entries are stored in a single in‑memory map:
+
+- Entries are keyed by a **presence key**.
+- The best key is a stable `instanceId` (from `connect.client.instanceId`) that survives restarts.
+- Keys are case‑insensitive.
+
+If a client reconnects without a stable `instanceId`, it may show up as a
+**duplicate** row.
+
+## TTL and bounded size
+
+Presence is intentionally ephemeral:
+
+- **TTL:** entries older than 5 minutes are pruned
+- **Max entries:** 200 (oldest dropped first)
+
+This keeps the list fresh and avoids unbounded memory growth.
+
+## Remote/tunnel caveat (loopback IPs)
+
+When a client connects over an SSH tunnel / local port forward, the Gateway may
+see the remote address as `127.0.0.1`. To avoid overwriting a good client‑reported
+IP, loopback remote addresses are ignored.
+
+## Consumers
+
+### macOS Instances tab
+
+The macOS app renders the output of `system-presence` and applies a small status
+indicator (Active/Idle/Stale) based on the age of the last update.
+
+## Debugging tips
+
+- To see the raw list, call `system-presence` against the Gateway.
+- If you see duplicates:
+  - confirm clients send a stable `client.instanceId` in the handshake
+  - confirm periodic beacons use the same `instanceId`
+  - check whether the connection‑derived entry is missing `instanceId` (duplicates are expected)