vilvona 1.0.0

package/docs/concepts/oauth.md

@@ -0,0 +1,218 @@
+---
+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 Claude CLI or OAuth auth flows
+  - You want multiple accounts or profile routing
+title: "OAuth"
+---
+
+OpenClaw supports "subscription auth" via OAuth for providers that offer it
+(notably **OpenAI Codex (ChatGPT OAuth)**). For Anthropic, the practical split
+is now:
+
+- **Anthropic API key**: normal Anthropic API billing
+- **Anthropic Claude CLI / subscription auth inside OpenClaw**: Anthropic staff
+  told us this usage is allowed again
+
+OpenAI Codex OAuth is explicitly supported for use in external tools like
+OpenClaw.
+
+OpenClaw stores both OpenAI API-key auth and ChatGPT/Codex OAuth under the
+canonical provider id `openai`. Older `openai-codex:*` profile ids and
+`auth.order.openai-codex` entries are legacy state repaired by
+`openclaw doctor --fix`; use `openai:*` profile ids and `auth.order.openai` for
+new config.
+
+For Anthropic in production, API key auth is the safer recommended path.
+
+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
+- external CLI reuse is provider-specific: Codex CLI can bootstrap an empty
+  `openai:default` profile, but once OpenClaw has a local OAuth profile,
+  the local refresh token is canonical. If that local refresh token is rejected,
+  OpenClaw can use a usable same-account Codex CLI token as a runtime-only
+  fallback; other integrations can remain externally managed and re-read their
+  CLI auth store
+- status and startup paths that already know the configured provider set scope
+  external CLI discovery to that set, so an unrelated CLI login store is not
+  probed for a single-provider setup
+
+## Storage (where tokens live)
+
+Secrets are stored in agent auth stores:
+
+- Auth profiles (OAuth + API keys + optional value-level refs): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+- Legacy compatibility file: `~/.openclaw/agents/<agentId>/agent/auth.json`
+  (static `api_key` entries are scrubbed when discovered)
+
+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-reference#auth-storage)
+
+For static secret refs and runtime snapshot activation behavior, see [Secrets Management](/gateway/secrets).
+
+When a secondary agent has no local auth profile, OpenClaw uses read-through
+inheritance from the default/main agent store. It does not clone the main
+agent's `auth-profiles.json` on read. OAuth refresh tokens are especially
+sensitive: normal copy flows skip them by default because some providers rotate
+or invalidate refresh tokens after use. Configure a separate OAuth login for an
+agent when it needs an independent account.
+
+## Anthropic legacy token compatibility
+
+<Warning>
+Anthropic's public Claude Code docs say direct Claude Code use stays within
+Claude subscription limits, and Anthropic staff told us OpenClaw-style Claude
+CLI usage is allowed again. OpenClaw therefore treats Claude CLI reuse and
+`claude -p` usage as sanctioned for this integration unless Anthropic
+publishes a new policy.
+
+For Anthropic's current direct-Claude-Code plan docs, see [Using Claude Code
+with your Pro or Max
+plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
+and [Using Claude Code with your Team or Enterprise
+plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/).
+
+If you want other subscription-style options in OpenClaw, see [OpenAI
+Codex](/providers/openai), [Qwen Cloud Coding
+Plan](/providers/qwen), [MiniMax Coding Plan](/providers/minimax),
+and [Z.AI / GLM Coding Plan](/providers/zai).
+</Warning>
+
+OpenClaw also exposes Anthropic setup-token as a supported token-auth path, but it now prefers Claude CLI reuse and `claude -p` when available.
+
+## Anthropic Claude CLI migration
+
+OpenClaw supports Anthropic Claude CLI reuse again. If you already have a local
+Claude login on the host, onboarding/configure can reuse it directly.
+
+## OAuth exchange (how login works)
+
+OpenClaw's interactive login flows are implemented in `openclaw/plugin-sdk/llm` and wired into the wizards/commands.
+
+### Anthropic setup-token
+
+Flow shape:
+
+1. start Anthropic setup-token or paste-token from OpenClaw
+2. OpenClaw stores the resulting Anthropic credential in an auth profile
+3. model selection stays on `anthropic/...`
+4. existing Anthropic auth profiles remain available for rollback/order control
+
+### OpenAI Codex (ChatGPT OAuth)
+
+OpenAI Codex OAuth is explicitly supported for use outside the Codex CLI, including OpenClaw workflows.
+
+The login command still uses the canonical OpenAI provider id:
+
+```bash
+openclaw models auth login --provider openai
+```
+
+Use `--profile-id openai:<name>` for multiple ChatGPT/Codex OAuth accounts in
+one agent. Do not use `openai-codex:<name>` for new profiles. Doctor migrates
+that older prefix to a collision-free `openai:*` profile id; run
+`openclaw models auth list --provider openai` after repair before copying
+profile ids into `auth.order` or `/model ...@<profileId>`.
+
+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`.
+
+## 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
+- if a secondary agent reads an inherited main-agent OAuth profile, refresh
+  writes back to the main agent store instead of copying the refresh token into
+  the secondary agent store
+- exception: some external CLI credentials stay externally managed; OpenClaw
+  re-reads those CLI auth stores instead of spending copied refresh tokens.
+  Codex CLI bootstrap is intentionally narrower: it seeds an empty
+  `openai:default` profile, then OpenClaw-owned refreshes keep the local
+  profile canonical. If the local Codex refresh fails and Codex CLI has a
+  usable token for the same account, OpenClaw may use that token for the current
+  runtime request without writing it back to `auth-profiles.json`.
+
+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:
+
+- [Model failover](/concepts/model-failover) (rotation + cooldown rules)
+- [Slash commands](/tools/slash-commands) (command surface)
+
+## Related
+
+- [Authentication](/gateway/authentication) - model provider auth overview
+- [Secrets](/gateway/secrets) - credential storage and SecretRef
+- [Configuration Reference](/gateway/configuration-reference#auth-storage) - auth config keys

package/docs/concepts/parallel-specialist-lanes.md

@@ -0,0 +1,127 @@
+---
+summary: "Run parallel specialist agents without clogging shared model and tool capacity"
+title: "Parallel specialist lanes"
+sidebarTitle: "Specialist lanes"
+read_when:
+  - You route group chats to dedicated agents
+  - You want parallel work without one long task blocking every chat
+  - You are designing a multi-agent operations setup
+status: active
+---
+
+Parallel specialist lanes let one Gateway route different chats or rooms to
+different agents, while keeping the user experience fast. The trick is to treat
+parallelism as a scarce-resource design problem, not just as "more agents".
+
+## First principles
+
+A specialist lane only improves throughput when it reduces contention for the
+real bottlenecks:
+
+- **Session locks**: only one run should mutate a given session at a time.
+- **Global model capacity**: all visible chat runs still share provider limits.
+- **Tool capacity**: shell, browser, network, and repository work can be slower
+  than the model turn itself.
+- **Context budget**: long transcripts make every future turn slower and less
+  focused.
+- **Ownership ambiguity**: duplicate agents doing the same job waste capacity.
+
+OpenClaw already serializes runs per session and caps global parallelism through
+the [command queue](/concepts/queue). Specialist lanes add policy on top:
+which agent owns which work, what stays in chat, and what becomes background
+work.
+
+## Recommended rollout
+
+### Phase 1: lane contracts + background heavy work
+
+Give every lane a written contract in its workspace and system prompt:
+
+- **Purpose**: the work this lane owns.
+- **Non-goals**: work it should hand off instead of attempting.
+- **Chat budget**: quick answers stay in chat; long tasks should acknowledge
+  briefly, then run in a background sub-agent or task.
+- **Handoff rule**: when another lane owns the work, say where it should go and
+  provide a compact handoff summary.
+- **Tool-risk rule**: prefer the smallest tool surface that can do the job.
+
+This is the cheapest phase and fixes most clogging: one coding job no longer
+turns the research lane into molasses, and each chat keeps its own context clean.
+
+### Phase 2: priority and concurrency controls
+
+Tune queue and model capacity around the business value of each lane:
+
+```json5
+{
+  agents: {
+    defaults: {
+      maxConcurrent: 4,
+      subagents: { maxConcurrent: 8, delegationMode: "prefer" },
+    },
+  },
+  messages: {
+    queue: {
+      mode: "collect",
+      debounceMs: 1000,
+      cap: 20,
+      drop: "summarize",
+    },
+  },
+}
+```
+
+Use direct/personal chats and production-ops agents for high-priority work. Let
+research, drafting, and batch coding move to background tasks when the system is
+busy.
+
+### Phase 3: coordinator / traffic controller
+
+Add a small coordinator pattern once multiple lanes are active:
+
+- Track active lane tasks and owners.
+- Detect duplicate requests across groups.
+- Route handoff summaries between lanes.
+- Surface only blockers, completed results, and decisions the human must make.
+
+Do not start here. A coordinator without lane contracts just coordinates chaos.
+
+## Minimal lane contract template
+
+```md
+# Lane contract
+
+## Owns
+
+- <job this lane is responsible for>
+
+## Does not own
+
+- <work to hand off>
+
+## Chat budget
+
+- Answer quick questions directly.
+- For multi-step, slow, or tool-heavy work: acknowledge briefly, spawn/background
+  the work, then return the result when complete.
+
+## Handoff
+
+If another lane owns the request, reply with:
+
+- target lane
+- objective
+- relevant context
+- exact next action
+
+## Tool posture
+
+Use the smallest tool surface that can complete the task. Avoid broad shell or
+network work unless this lane explicitly owns it.
+```
+
+## Related
+
+- [Multi-agent routing](/concepts/multi-agent)
+- [Command queue](/concepts/queue)
+- [Sub-agents](/tools/subagents)

package/docs/concepts/personal-agent-benchmark-pack.md

@@ -0,0 +1,74 @@
+---
+summary: "Local qa-channel scenarios for privacy-preserving personal assistant workflow checks."
+read_when:
+  - Running local personal agent reliability checks
+  - Extending the repo-backed QA scenario catalog
+  - Verifying reminder, reply, memory, redaction, safe tool followthrough, task status, share-safe diagnostics, proof-backed completion claims, and failure recovery
+title: "Personal agent benchmark pack"
+---
+
+The Personal Agent Benchmark Pack is a small repo-backed QA scenario pack for
+local personal assistant workflows. It is not a generic model benchmark and it
+does not require a new runner. The pack reuses the private QA stack described in
+[QA overview](/concepts/qa-e2e-automation), the synthetic
+[QA channel](/channels/qa-channel), and the existing `qa/scenarios` markdown
+catalog.
+
+The first pack is intentionally narrow:
+
+- fake personal reminders through local cron delivery
+- fake DM and thread reply routing through `qa-channel`
+- fake preference recall from the temporary QA workspace memory files
+- fake secret no-echo checks
+- safe read-backed tool followthrough after a short approval-style turn
+- approval denial stop behavior for a sensitive local read request
+- proof-backed task status reporting that keeps pending, blocked, and done separate
+- share-safe diagnostics artifacts that keep useful status while omitting raw personal content
+- proof-backed completion claims that avoid fake progress before local evidence exists
+- failure recovery that reports partial status and keeps retry boundaries clear
+
+## Scenarios
+
+The machine-readable pack metadata lives in
+`extensions/qa-lab/src/scenario-packs.ts`. Run the pack with
+`--pack personal-agent`:
+
+```bash
+OPENCLAW_ENABLE_PRIVATE_QA_CLI=1 pnpm openclaw qa suite \
+  --provider-mode mock-openai \
+  --pack personal-agent \
+  --concurrency 1
+```
+
+`--pack` is additive with repeated `--scenario` flags. Explicit scenarios run
+first, then the pack scenarios run in `QA_PERSONAL_AGENT_SCENARIO_IDS` order with
+duplicates removed.
+
+The pack is designed for `qa-channel` with `mock-openai` or another local QA
+provider lane. It should not be pointed at live chat services or real personal
+accounts.
+
+## Privacy Model
+
+The scenarios use only fake users, fake preferences, fake secrets, and the
+temporary QA gateway workspace created by the suite. They must not read or write
+real OpenClaw user memory, sessions, credentials, launch agents, global configs,
+or live gateway state.
+
+Artifacts stay under the existing QA suite artifact directory and should be
+treated like test output. Redaction checks use fake markers so failures are safe
+to inspect and file in issues.
+
+## Extending The Pack
+
+Add new cases under `qa/scenarios/personal/`, then add the scenario id to
+`QA_PERSONAL_AGENT_SCENARIO_IDS`. Keep each case small, local, deterministic in
+`mock-openai`, and focused on one personal assistant behavior.
+
+Good follow-up candidates:
+
+- redacted trajectory export checks
+- local-only plugin workflow checks
+
+Avoid adding a new runner, plugin, dependency, live transport, or model judge
+until the scenario catalog has enough stable cases to justify that surface.

package/docs/concepts/presence.md

@@ -0,0 +1,117 @@
+---
+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"
+---
+
+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 do not 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)
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Typing indicators" href="/concepts/typing-indicators" icon="ellipsis">
+    When typing indicators are sent and how to tune them.
+  </Card>
+  <Card title="Streaming and chunking" href="/concepts/streaming" icon="bars-staggered">
+    Outbound streaming, chunking, and per-channel formatting.
+  </Card>
+  <Card title="Gateway architecture" href="/concepts/architecture" icon="diagram-project">
+    Gateway components and the WebSocket protocol that drives presence updates.
+  </Card>
+  <Card title="Gateway protocol" href="/gateway/protocol" icon="plug">
+    The wire protocol for `connect`, `system-event`, and `system-presence`.
+  </Card>
+</CardGroup>