Merge branch 'main' into qianfan

docs/bedrock.md

@@ -78,8 +78,8 @@ export AWS_BEARER_TOKEN_BEDROCK="..."
         auth: "aws-sdk",
         models: [
           {
-            id: "anthropic.claude-opus-4-5-20251101-v1:0",
-            name: "Claude Opus 4.5 (Bedrock)",
+            id: "us.anthropic.claude-opus-4-6-v1:0",
+            name: "Claude Opus 4.6 (Bedrock)",
             reasoning: true,
             input: ["text", "image"],
             cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
@@ -92,7 +92,7 @@ export AWS_BEARER_TOKEN_BEDROCK="..."
   },
   agents: {
     defaults: {
-      model: { primary: "amazon-bedrock/anthropic.claude-opus-4-5-20251101-v1:0" },
+      model: { primary: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0" },
     },
   },
 }

docs/channels/discord.md

@@ -196,6 +196,7 @@ Notes:
 - If `channels` is present, any channel not listed is denied by default.
 - Use a `"*"` channel entry to apply defaults across all channels; explicit channel entries override the wildcard.
 - Threads inherit parent channel config (allowlist, `requireMention`, skills, prompts, etc.) unless you add the thread channel id explicitly.
+- Owner hint: when a per-guild or per-channel `users` allowlist matches the sender, OpenClaw treats that sender as the owner in the system prompt. For a global owner across channels, set `commands.ownerAllowFrom`.
 - Bot-authored messages are ignored by default; set `channels.discord.allowBots=true` to allow them (own messages remain filtered).
 - Warning: If you allow replies to other bots (`channels.discord.allowBots=true`), prevent bot-to-bot reply loops with `requireMention`, `channels.discord.guilds.*.channels.<id>.users` allowlists, and/or clear guardrails in `AGENTS.md` and `SOUL.md`.
 
@@ -334,7 +335,7 @@ ack reaction after the bot replies.
 - `guilds.<id>.channels.<channel>.toolsBySender`: optional per-sender tool policy overrides within the channel (`"*"` wildcard supported).
 - `guilds.<id>.channels.<channel>.users`: optional per-channel user allowlist.
 - `guilds.<id>.channels.<channel>.skills`: skill filter (omit = all skills, empty = none).
-- `guilds.<id>.channels.<channel>.systemPrompt`: extra system prompt for the channel (combined with channel topic).
+- `guilds.<id>.channels.<channel>.systemPrompt`: extra system prompt for the channel. Discord channel topics are injected as **untrusted** context (not system prompt).
 - `guilds.<id>.channels.<channel>.enabled`: set `false` to disable the channel.
 - `guilds.<id>.channels`: channel rules (keys are channel slugs or ids).
 - `guilds.<id>.requireMention`: per-guild mention requirement (overridable per channel).

docs/channels/feishu.md

@@ -447,7 +447,75 @@ openclaw pairing list feishu
 
 ### Streaming
 
-Feishu does not support message editing, so block streaming is enabled by default (`blockStreaming: true`). The bot waits for the full reply before sending.
+Feishu supports streaming replies via interactive cards. When enabled, the bot updates a card as it generates text.
+
+```json5
+{
+  channels: {
+    feishu: {
+      streaming: true, // enable streaming card output (default true)
+      blockStreaming: true, // enable block-level streaming (default true)
+    },
+  },
+}
+```
+
+Set `streaming: false` to wait for the full reply before sending.
+
+### Multi-agent routing
+
+Use `bindings` to route Feishu DMs or groups to different agents.
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "main" },
+      {
+        id: "clawd-fan",
+        workspace: "/home/user/clawd-fan",
+        agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
+      },
+      {
+        id: "clawd-xi",
+        workspace: "/home/user/clawd-xi",
+        agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
+      },
+    ],
+  },
+  bindings: [
+    {
+      agentId: "main",
+      match: {
+        channel: "feishu",
+        peer: { kind: "dm", id: "ou_xxx" },
+      },
+    },
+    {
+      agentId: "clawd-fan",
+      match: {
+        channel: "feishu",
+        peer: { kind: "dm", id: "ou_yyy" },
+      },
+    },
+    {
+      agentId: "clawd-xi",
+      match: {
+        channel: "feishu",
+        peer: { kind: "group", id: "oc_zzz" },
+      },
+    },
+  ],
+}
+```
+
+Routing fields:
+
+- `match.channel`: `"feishu"`
+- `match.peer.kind`: `"dm"` or `"group"`
+- `match.peer.id`: user Open ID (`ou_xxx`) or group ID (`oc_xxx`)
+
+See [Get group/user IDs](#get-groupuser-ids) for lookup tips.
 
 ---
 
@@ -472,7 +540,8 @@ Key options:
 | `channels.feishu.groups.<chat_id>.enabled`        | Enable group                    | `true`    |
 | `channels.feishu.textChunkLimit`                  | Message chunk size              | `2000`    |
 | `channels.feishu.mediaMaxMb`                      | Media size limit                | `30`      |
-| `channels.feishu.blockStreaming`                  | Disable streaming               | `true`    |
+| `channels.feishu.streaming`                       | Enable streaming card output    | `true`    |
+| `channels.feishu.blockStreaming`                  | Enable block streaming          | `true`    |
 
 ---
 
@@ -492,6 +561,7 @@ Key options:
 ### Receive
 
 - ✅ Text
+- ✅ Rich text (post)
 - ✅ Images
 - ✅ Files
 - ✅ Audio

docs/channels/telegram.md

@@ -392,6 +392,23 @@ Two independent controls:
 
 Most users want: `groupPolicy: "allowlist"` + `groupAllowFrom` + specific groups listed in `channels.telegram.groups`
 
+To allow **any group member** to talk in a specific group (while still keeping control commands restricted to authorized senders), set a per-group override:
+
+```json5
+{
+  channels: {
+    telegram: {
+      groups: {
+        "-1001234567890": {
+          groupPolicy: "open",
+          requireMention: false,
+        },
+      },
+    },
+  },
+}
+```
+
 ## Long-polling vs webhook
 
 - Default: long-polling (no public URL required).
@@ -714,12 +731,14 @@ Provider options:
 - `channels.telegram.groupPolicy`: `open | allowlist | disabled` (default: allowlist).
 - `channels.telegram.groupAllowFrom`: group sender allowlist (ids/usernames).
 - `channels.telegram.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
+  - `channels.telegram.groups.<id>.groupPolicy`: per-group override for groupPolicy (`open | allowlist | disabled`).
   - `channels.telegram.groups.<id>.requireMention`: mention gating default.
   - `channels.telegram.groups.<id>.skills`: skill filter (omit = all skills, empty = none).
   - `channels.telegram.groups.<id>.allowFrom`: per-group sender allowlist override.
   - `channels.telegram.groups.<id>.systemPrompt`: extra system prompt for the group.
   - `channels.telegram.groups.<id>.enabled`: disable the group when `false`.
   - `channels.telegram.groups.<id>.topics.<threadId>.*`: per-topic overrides (same fields as group).
+  - `channels.telegram.groups.<id>.topics.<threadId>.groupPolicy`: per-topic override for groupPolicy (`open | allowlist | disabled`).
   - `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: per-topic mention gating override.
 - `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (default: allowlist).
 - `channels.telegram.accounts.<account>.capabilities.inlineButtons`: per-account override.

docs/cli/onboard.md

@@ -9,9 +9,12 @@ title: "onboard"
 
 Interactive onboarding wizard (local or remote Gateway setup).
 
-Related:
+## Related guides
 
-- Wizard guide: [Onboarding](/start/onboarding)
+- CLI onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
+- CLI onboarding reference: [CLI Onboarding Reference](/start/wizard-cli-reference)
+- CLI automation: [CLI Automation](/start/wizard-cli-automation)
+- macOS onboarding: [Onboarding (macOS App)](/start/onboarding)
 
 ## Examples
 
@@ -27,3 +30,14 @@ Flow notes:
 - `quickstart`: minimal prompts, auto-generates a gateway token.
 - `manual`: full prompts for port/bind/auth (alias of `advanced`).
 - Fastest first chat: `openclaw dashboard` (Control UI, no channel setup).
+
+## Common follow-up commands
+
+```bash
+openclaw configure
+openclaw agents add <name>
+```
+
+<Note>
+`--json` does not imply non-interactive mode. Use `--non-interactive` for scripts.
+</Note>

docs/concepts/memory.md

@@ -25,7 +25,7 @@ The default workspace layout uses two memory layers:
   - **Only load in the main, private session** (never in group contexts).
 
 These files live under the workspace (`agents.defaults.workspace`, default
-`~/clawd`). See [Agent workspace](/concepts/agent-workspace) for the full layout.
+`~/.openclaw/workspace`). See [Agent workspace](/concepts/agent-workspace) for the full layout.
 
 ## When to write memory
 

docs/concepts/model-providers.md

@@ -13,7 +13,7 @@ For model selection rules, see [/concepts/models](/concepts/models).
 
 ## Quick rules
 
-- Model refs use `provider/model` (example: `opencode/claude-opus-4-5`).
+- Model refs use `provider/model` (example: `opencode/claude-opus-4-6`).
 - If you set `agents.defaults.models`, it becomes the allowlist.
 - CLI helpers: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
 
@@ -26,12 +26,12 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 
 - Provider: `openai`
 - Auth: `OPENAI_API_KEY`
-- Example model: `openai/gpt-5.2`
+- Example model: `openai/gpt-5.1-codex`
 - CLI: `openclaw onboard --auth-choice openai-api-key`
 
 ```json5
 {
-  agents: { defaults: { model: { primary: "openai/gpt-5.2" } } },
+  agents: { defaults: { model: { primary: "openai/gpt-5.1-codex" } } },
 }
 ```
 
@@ -39,12 +39,12 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 
 - Provider: `anthropic`
 - Auth: `ANTHROPIC_API_KEY` or `claude setup-token`
-- Example model: `anthropic/claude-opus-4-5`
+- Example model: `anthropic/claude-opus-4-6`
 - CLI: `openclaw onboard --auth-choice token` (paste setup-token) or `openclaw models auth paste-token --provider anthropic`
 
 ```json5
 {
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
 }
 ```
 
@@ -52,12 +52,12 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 
 - Provider: `openai-codex`
 - Auth: OAuth (ChatGPT)
-- Example model: `openai-codex/gpt-5.2`
+- Example model: `openai-codex/gpt-5.3-codex`
 - CLI: `openclaw onboard --auth-choice openai-codex` or `openclaw models auth login --provider openai-codex`
 
 ```json5
 {
-  agents: { defaults: { model: { primary: "openai-codex/gpt-5.2" } } },
+  agents: { defaults: { model: { primary: "openai-codex/gpt-5.3-codex" } } },
 }
 ```
 
@@ -65,12 +65,12 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 
 - Provider: `opencode`
 - Auth: `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`)
-- Example model: `opencode/claude-opus-4-5`
+- Example model: `opencode/claude-opus-4-6`
 - CLI: `openclaw onboard --auth-choice opencode-zen`
 
 ```json5
 {
-  agents: { defaults: { model: { primary: "opencode/claude-opus-4-5" } } },
+  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
 }
 ```
 
@@ -106,7 +106,7 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 
 - Provider: `vercel-ai-gateway`
 - Auth: `AI_GATEWAY_API_KEY`
-- Example model: `vercel-ai-gateway/anthropic/claude-opus-4.5`
+- Example model: `vercel-ai-gateway/anthropic/claude-opus-4.6`
 - CLI: `openclaw onboard --auth-choice ai-gateway-api-key`
 
 ### Other built-in providers
@@ -309,7 +309,7 @@ Notes:
 
 ```bash
 openclaw onboard --auth-choice opencode-zen
-openclaw models set opencode/claude-opus-4-5
+openclaw models set opencode/claude-opus-4-6
 openclaw models list
 ```
 

docs/concepts/models.md

@@ -83,7 +83,7 @@ Example allowlist config:
     model: { primary: "anthropic/claude-sonnet-4-5" },
     models: {
       "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
-      "anthropic/claude-opus-4-5": { alias: "Opus" },
+      "anthropic/claude-opus-4-6": { alias: "Opus" },
     },
   },
 }

docs/concepts/multi-agent.md

@@ -221,7 +221,7 @@ Split by channel: route WhatsApp to a fast everyday agent and Telegram to an Opu
         id: "opus",
         name: "Deep Work",
         workspace: "~/.openclaw/workspace-opus",
-        model: "anthropic/claude-opus-4-5",
+        model: "anthropic/claude-opus-4-6",
       },
     ],
   },
@@ -255,7 +255,7 @@ Keep WhatsApp on the fast agent, but route one DM to Opus:
         id: "opus",
         name: "Deep Work",
         workspace: "~/.openclaw/workspace-opus",
-        model: "anthropic/claude-opus-4-5",
+        model: "anthropic/claude-opus-4-6",
       },
     ],
   },

docs/concepts/session.md

@@ -17,9 +17,17 @@ Use `session.dmScope` to control how **direct messages** are grouped:
 - `per-account-channel-peer`: isolate by account + channel + sender (recommended for multi-account inboxes).
   Use `session.identityLinks` to map provider-prefixed peer ids to a canonical identity so the same person shares a DM session across channels when using `per-peer`, `per-channel-peer`, or `per-account-channel-peer`.
 
-### Secure DM mode (recommended)
+### Secure DM mode (recommended for multi-user setups)
 
-If your agent can receive DMs from **multiple people** (pairing approvals for more than one sender, a DM allowlist with multiple entries, or `dmPolicy: "open"`), enable **secure DM mode** to avoid cross-user context leakage:
+> **Security Warning:** If your agent can receive DMs from **multiple people**, you should strongly consider enabling secure DM mode. Without it, all users share the same conversation context, which can leak private information between users.
+
+**Example of the problem with default settings:**
+
+- Alice (`<SENDER_A>`) messages your agent about a private topic (for example, a medical appointment)
+- Bob (`<SENDER_B>`) messages your agent asking "What were we talking about?"
+- Because both DMs share the same session, the model may answer Bob using Alice's prior context.
+
+**The fix:** Set `dmScope` to isolate sessions per user:
 
 ```json5
 // ~/.openclaw/openclaw.json
@@ -31,11 +39,19 @@ If your agent can receive DMs from **multiple people** (pairing approvals for mo
 }
 ```
 
+**When to enable this:**
+
+- You have pairing approvals for more than one sender
+- You use a DM allowlist with multiple entries
+- You set `dmPolicy: "open"`
+- Multiple phone numbers or accounts can message your agent
+
 Notes:
 
-- Default is `dmScope: "main"` for continuity (all DMs share the main session).
+- Default is `dmScope: "main"` for continuity (all DMs share the main session). This is fine for single-user setups.
 - For multi-account inboxes on the same channel, prefer `per-account-channel-peer`.
 - If the same person contacts you on multiple channels, use `session.identityLinks` to collapse their DM sessions into one canonical identity.
+- You can verify your DM settings with `openclaw security audit` (see [security](/cli/security)).
 
 ## Gateway is the source of truth
 

docs/custom.css

@@ -1,4 +0,0 @@
-#content-area h1:first-of-type,
-.prose h1:first-of-type {
-  display: none !important;
-}

docs/docs.json

@@ -338,6 +338,14 @@
       "source": "/getting-started",
       "destination": "/start/getting-started"
     },
+    {
+      "source": "/quickstart",
+      "destination": "/start/getting-started"
+    },
+    {
+      "source": "/start/quickstart",
+      "destination": "/start/getting-started"
+    },
     {
       "source": "/gmail-pubsub",
       "destination": "/automation/gmail-pubsub"
@@ -694,6 +702,18 @@
       "source": "/wizard",
       "destination": "/start/wizard"
     },
+    {
+      "source": "/start/wizard-cli-flow",
+      "destination": "/start/wizard-cli-reference"
+    },
+    {
+      "source": "/start/wizard-cli-auth",
+      "destination": "/start/wizard-cli-reference"
+    },
+    {
+      "source": "/start/wizard-cli-outputs",
+      "destination": "/start/wizard-cli-reference"
+    },
     {
       "source": "/start/faq",
       "destination": "/help/faq"
@@ -707,20 +727,52 @@
       "destination": "/plugin"
     },
     {
-      "source": "/install/railway",
-      "destination": "/railway"
+      "source": "/railway",
+      "destination": "/install/railway"
     },
     {
-      "source": "/install/northflank",
-      "destination": "/northflank"
+      "source": "/northflank",
+      "destination": "/install/northflank"
     },
     {
-      "source": "/install/northflank/",
-      "destination": "/northflank"
+      "source": "/render",
+      "destination": "/install/render"
     },
     {
       "source": "/gcp",
-      "destination": "/platforms/gcp"
+      "destination": "/install/gcp"
+    },
+    {
+      "source": "/platforms/fly",
+      "destination": "/install/fly"
+    },
+    {
+      "source": "/platforms/hetzner",
+      "destination": "/install/hetzner"
+    },
+    {
+      "source": "/platforms/gcp",
+      "destination": "/install/gcp"
+    },
+    {
+      "source": "/platforms/macos-vm",
+      "destination": "/install/macos-vm"
+    },
+    {
+      "source": "/platforms/exe-dev",
+      "destination": "/install/exe-dev"
+    },
+    {
+      "source": "/platforms/railway",
+      "destination": "/install/railway"
+    },
+    {
+      "source": "/platforms/render",
+      "destination": "/install/render"
+    },
+    {
+      "source": "/platforms/northflank",
+      "destination": "/install/northflank"
     }
   ],
   "navigation": {
@@ -733,46 +785,55 @@
             "groups": [
               {
                 "group": "Overview",
-                "pages": ["index", "concepts/features", "start/showcase", "start/lore"]
+                "pages": ["index", "concepts/features", "start/showcase"]
               },
               {
-                "group": "Installation",
+                "group": "First steps",
+                "pages": ["start/getting-started", "start/wizard", "start/onboarding"]
+              },
+              {
+                "group": "Guides",
+                "pages": ["start/openclaw"]
+              }
+            ]
+          },
+          {
+            "tab": "Install",
+            "groups": [
+              {
+                "group": "Install overview",
+                "pages": ["install/index", "install/installer"]
+              },
+              {
+                "group": "Install methods",
                 "pages": [
-                  "install/index",
-                  "install/installer",
+                  "install/node",
                   "install/docker",
-                  "install/bun",
                   "install/nix",
                   "install/ansible",
-                  "install/development-channels",
-                  "install/updating",
-                  "install/uninstall"
+                  "install/bun"
                 ]
               },
               {
-                "group": "Setup",
+                "group": "Maintenance",
+                "pages": ["install/updating", "install/migrating", "install/uninstall"]
+              },
+              {
+                "group": "Hosting and deployment",
                 "pages": [
-                  "start/getting-started",
-                  "start/quickstart",
-                  "start/wizard",
-                  "start/setup",
-                  "start/onboarding",
-                  "start/pairing",
-                  "start/openclaw",
-                  "start/hubs",
-                  "start/docs-directory"
+                  "install/fly",
+                  "install/hetzner",
+                  "install/gcp",
+                  "install/macos-vm",
+                  "install/exe-dev",
+                  "install/railway",
+                  "install/render",
+                  "install/northflank"
                 ]
               },
               {
-                "group": "Platforms",
-                "pages": [
-                  "platforms/index",
-                  "platforms/macos",
-                  "platforms/linux",
-                  "platforms/windows",
-                  "platforms/android",
-                  "platforms/ios"
-                ]
+                "group": "Advanced",
+                "pages": ["install/development-channels"]
               }
             ]
           },
@@ -806,6 +867,7 @@
               {
                 "group": "Configuration",
                 "pages": [
+                  "start/pairing",
                   "concepts/group-messages",
                   "concepts/groups",
                   "broadcast-groups",
@@ -828,6 +890,7 @@
                   "concepts/system-prompt",
                   "concepts/context",
                   "concepts/agent-workspace",
+                  "start/bootstrapping",
                   "concepts/oauth"
                 ]
               },
@@ -960,7 +1023,46 @@
             ]
           },
           {
-            "tab": "Infrastructure",
+            "tab": "Platforms",
+            "groups": [
+              {
+                "group": "Platforms overview",
+                "pages": [
+                  "platforms/index",
+                  "platforms/macos",
+                  "platforms/linux",
+                  "platforms/windows",
+                  "platforms/android",
+                  "platforms/ios"
+                ]
+              },
+              {
+                "group": "macOS companion app",
+                "pages": [
+                  "platforms/mac/dev-setup",
+                  "platforms/mac/menu-bar",
+                  "platforms/mac/voicewake",
+                  "platforms/mac/voice-overlay",
+                  "platforms/mac/webchat",
+                  "platforms/mac/canvas",
+                  "platforms/mac/child-process",
+                  "platforms/mac/health",
+                  "platforms/mac/icon",
+                  "platforms/mac/logging",
+                  "platforms/mac/permissions",
+                  "platforms/mac/remote",
+                  "platforms/mac/signing",
+                  "platforms/mac/release",
+                  "platforms/mac/bundled-gateway",
+                  "platforms/mac/xpc",
+                  "platforms/mac/skills",
+                  "platforms/mac/peekaboo"
+                ]
+              }
+            ]
+          },
+          {
+            "tab": "Gateway & Ops",
             "groups": [
               {
                 "group": "Gateway",
@@ -1013,20 +1115,8 @@
                 ]
               },
               {
-                "group": "Remote access and deployment",
-                "pages": [
-                  "gateway/remote",
-                  "gateway/remote-gateway-readme",
-                  "gateway/tailscale",
-                  "platforms/fly",
-                  "platforms/hetzner",
-                  "platforms/gcp",
-                  "platforms/macos-vm",
-                  "platforms/exe-dev",
-                  "railway",
-                  "render",
-                  "northflank"
-                ]
+                "group": "Remote access",
+                "pages": ["gateway/remote", "gateway/remote-gateway-readme", "gateway/tailscale"]
               },
               {
                 "group": "Security",
@@ -1035,29 +1125,6 @@
               {
                 "group": "Web interfaces",
                 "pages": ["web/index", "web/control-ui", "web/dashboard", "web/webchat", "tui"]
-              },
-              {
-                "group": "macOS companion app",
-                "pages": [
-                  "platforms/mac/dev-setup",
-                  "platforms/mac/menu-bar",
-                  "platforms/mac/voicewake",
-                  "platforms/mac/voice-overlay",
-                  "platforms/mac/webchat",
-                  "platforms/mac/canvas",
-                  "platforms/mac/child-process",
-                  "platforms/mac/health",
-                  "platforms/mac/icon",
-                  "platforms/mac/logging",
-                  "platforms/mac/permissions",
-                  "platforms/mac/remote",
-                  "platforms/mac/signing",
-                  "platforms/mac/release",
-                  "platforms/mac/bundled-gateway",
-                  "platforms/mac/xpc",
-                  "platforms/mac/skills",
-                  "platforms/mac/peekaboo"
-                ]
               }
             ]
           },
@@ -1126,6 +1193,7 @@
               {
                 "group": "Technical reference",
                 "pages": [
+                  "reference/wizard",
                   "concepts/typebox",
                   "concepts/markdown-formatting",
                   "concepts/typing-indicators",
@@ -1151,6 +1219,10 @@
                 "group": "Help",
                 "pages": ["help/index", "help/troubleshooting", "help/faq"]
               },
+              {
+                "group": "Community",
+                "pages": ["start/lore"]
+              },
               {
                 "group": "Environment and debugging",
                 "pages": [
@@ -1160,6 +1232,14 @@
                   "scripts",
                   "reference/session-management-compaction"
                 ]
+              },
+              {
+                "group": "Developer workflows",
+                "pages": ["start/setup", "help/submitting-a-pr", "help/submitting-an-issue"]
+              },
+              {
+                "group": "Docs meta",
+                "pages": ["start/hubs", "start/docs-directory"]
               }
             ]
           }
@@ -1169,60 +1249,79 @@
         "language": "zh-Hans",
         "tabs": [
           {
-            "tab": "Get started",
+            "tab": "快速开始",
             "groups": [
               {
-                "group": "Overview",
-                "pages": ["zh-CN/index", "zh-CN/start/showcase", "zh-CN/start/lore"]
+                "group": "概览",
+                "pages": ["zh-CN/index", "zh-CN/concepts/features", "zh-CN/start/showcase"]
               },
               {
-                "group": "Installation",
-                "pages": [
-                  "zh-CN/install/index",
-                  "zh-CN/install/installer",
-                  "zh-CN/install/docker",
-                  "zh-CN/install/bun",
-                  "zh-CN/install/nix",
-                  "zh-CN/install/ansible",
-                  "zh-CN/install/development-channels",
-                  "zh-CN/install/updating",
-                  "zh-CN/install/uninstall"
-                ]
-              },
-              {
-                "group": "Setup",
+                "group": "第一步",
                 "pages": [
                   "zh-CN/start/getting-started",
                   "zh-CN/start/wizard",
-                  "zh-CN/start/setup",
-                  "zh-CN/start/onboarding",
-                  "zh-CN/start/pairing",
-                  "zh-CN/start/openclaw",
-                  "zh-CN/start/hubs"
+                  "zh-CN/start/onboarding"
                 ]
               },
               {
-                "group": "Platforms",
-                "pages": [
-                  "zh-CN/platforms/index",
-                  "zh-CN/platforms/macos",
-                  "zh-CN/platforms/linux",
-                  "zh-CN/platforms/windows",
-                  "zh-CN/platforms/android",
-                  "zh-CN/platforms/ios"
-                ]
+                "group": "指南",
+                "pages": ["zh-CN/start/openclaw"]
               }
             ]
           },
           {
-            "tab": "Channels",
+            "tab": "安装",
             "groups": [
               {
-                "group": "Overview",
+                "group": "安装概览",
+                "pages": ["zh-CN/install/index", "zh-CN/install/installer"]
+              },
+              {
+                "group": "安装方式",
+                "pages": [
+                  "zh-CN/install/node",
+                  "zh-CN/install/docker",
+                  "zh-CN/install/nix",
+                  "zh-CN/install/ansible",
+                  "zh-CN/install/bun"
+                ]
+              },
+              {
+                "group": "维护",
+                "pages": [
+                  "zh-CN/install/updating",
+                  "zh-CN/install/migrating",
+                  "zh-CN/install/uninstall"
+                ]
+              },
+              {
+                "group": "托管与部署",
+                "pages": [
+                  "zh-CN/install/fly",
+                  "zh-CN/install/hetzner",
+                  "zh-CN/install/gcp",
+                  "zh-CN/install/macos-vm",
+                  "zh-CN/install/exe-dev",
+                  "zh-CN/install/railway",
+                  "zh-CN/install/render",
+                  "zh-CN/install/northflank"
+                ]
+              },
+              {
+                "group": "高级",
+                "pages": ["zh-CN/install/development-channels"]
+              }
+            ]
+          },
+          {
+            "tab": "消息渠道",
+            "groups": [
+              {
+                "group": "概览",
                 "pages": ["zh-CN/channels/index"]
               },
               {
-                "group": "Messaging platforms",
+                "group": "消息平台",
                 "pages": [
                   "zh-CN/channels/whatsapp",
                   "zh-CN/channels/telegram",
@@ -1242,8 +1341,9 @@
                 ]
               },
               {
-                "group": "Configuration",
+                "group": "配置",
                 "pages": [
+                  "zh-CN/start/pairing",
                   "zh-CN/concepts/group-messages",
                   "zh-CN/concepts/groups",
                   "zh-CN/broadcast-groups",
@@ -1255,10 +1355,10 @@
             ]
           },
           {
-            "tab": "Agents",
+            "tab": "代理",
             "groups": [
               {
-                "group": "Fundamentals",
+                "group": "基础",
                 "pages": [
                   "zh-CN/concepts/architecture",
                   "zh-CN/concepts/agent",
@@ -1270,7 +1370,7 @@
                 ]
               },
               {
-                "group": "Sessions and memory",
+                "group": "会话与记忆",
                 "pages": [
                   "zh-CN/concepts/session",
                   "zh-CN/concepts/sessions",
@@ -1281,11 +1381,11 @@
                 ]
               },
               {
-                "group": "Multi-agent",
+                "group": "多代理",
                 "pages": ["zh-CN/concepts/multi-agent", "zh-CN/concepts/presence"]
               },
               {
-                "group": "Messages and delivery",
+                "group": "消息与投递",
                 "pages": [
                   "zh-CN/concepts/messages",
                   "zh-CN/concepts/streaming",
@@ -1296,14 +1396,14 @@
             ]
           },
           {
-            "tab": "Tools",
+            "tab": "工具",
             "groups": [
               {
-                "group": "Overview",
+                "group": "概览",
                 "pages": ["zh-CN/tools/index"]
               },
               {
-                "group": "Built-in tools",
+                "group": "内置工具",
                 "pages": [
                   "zh-CN/tools/lobster",
                   "zh-CN/tools/llm-task",
@@ -1316,7 +1416,7 @@
                 ]
               },
               {
-                "group": "Browser",
+                "group": "浏览器",
                 "pages": [
                   "zh-CN/tools/browser",
                   "zh-CN/tools/browser-login",
@@ -1325,7 +1425,7 @@
                 ]
               },
               {
-                "group": "Agent coordination",
+                "group": "代理协作",
                 "pages": [
                   "zh-CN/tools/agent-send",
                   "zh-CN/tools/subagents",
@@ -1333,7 +1433,7 @@
                 ]
               },
               {
-                "group": "Skills and extensions",
+                "group": "技能与扩展",
                 "pages": [
                   "zh-CN/tools/slash-commands",
                   "zh-CN/tools/skills",
@@ -1345,7 +1445,7 @@
                 ]
               },
               {
-                "group": "Automation",
+                "group": "自动化",
                 "pages": [
                   "zh-CN/hooks",
                   "zh-CN/hooks/soul-evil",
@@ -1358,7 +1458,7 @@
                 ]
               },
               {
-                "group": "Media and devices",
+                "group": "媒体与设备",
                 "pages": [
                   "zh-CN/nodes/index",
                   "zh-CN/nodes/images",
@@ -1372,10 +1472,10 @@
             ]
           },
           {
-            "tab": "Models",
+            "tab": "模型",
             "groups": [
               {
-                "group": "Overview",
+                "group": "概览",
                 "pages": [
                   "zh-CN/providers/index",
                   "zh-CN/providers/models",
@@ -1383,11 +1483,11 @@
                 ]
               },
               {
-                "group": "Configuration",
+                "group": "配置",
                 "pages": ["zh-CN/concepts/model-providers", "zh-CN/concepts/model-failover"]
               },
               {
-                "group": "Providers",
+                "group": "提供商",
                 "pages": [
                   "zh-CN/providers/anthropic",
                   "zh-CN/providers/openai",
@@ -1405,89 +1505,21 @@
             ]
           },
           {
-            "tab": "Infrastructure",
+            "tab": "平台",
             "groups": [
               {
-                "group": "Gateway",
+                "group": "平台概览",
                 "pages": [
-                  "zh-CN/gateway/index",
-                  {
-                    "group": "Configuration and operations",
-                    "pages": [
-                      "zh-CN/gateway/configuration",
-                      "zh-CN/gateway/configuration-examples",
-                      "zh-CN/gateway/authentication",
-                      "zh-CN/gateway/health",
-                      "zh-CN/gateway/heartbeat",
-                      "zh-CN/gateway/doctor",
-                      "zh-CN/gateway/logging",
-                      "zh-CN/gateway/gateway-lock",
-                      "zh-CN/gateway/background-process",
-                      "zh-CN/gateway/multiple-gateways",
-                      "zh-CN/gateway/troubleshooting"
-                    ]
-                  },
-                  {
-                    "group": "Security and sandboxing",
-                    "pages": [
-                      "zh-CN/gateway/security/index",
-                      "zh-CN/gateway/sandboxing",
-                      "zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated"
-                    ]
-                  },
-                  {
-                    "group": "Protocols and APIs",
-                    "pages": [
-                      "zh-CN/gateway/protocol",
-                      "zh-CN/gateway/bridge-protocol",
-                      "zh-CN/gateway/openai-http-api",
-                      "zh-CN/gateway/tools-invoke-http-api",
-                      "zh-CN/gateway/cli-backends",
-                      "zh-CN/gateway/local-models"
-                    ]
-                  },
-                  {
-                    "group": "Networking and discovery",
-                    "pages": [
-                      "zh-CN/gateway/pairing",
-                      "zh-CN/gateway/discovery",
-                      "zh-CN/gateway/bonjour"
-                    ]
-                  }
+                  "zh-CN/platforms/index",
+                  "zh-CN/platforms/macos",
+                  "zh-CN/platforms/linux",
+                  "zh-CN/platforms/windows",
+                  "zh-CN/platforms/android",
+                  "zh-CN/platforms/ios"
                 ]
               },
               {
-                "group": "Remote access and deployment",
-                "pages": [
-                  "zh-CN/gateway/remote",
-                  "zh-CN/gateway/remote-gateway-readme",
-                  "zh-CN/gateway/tailscale",
-                  "zh-CN/platforms/fly",
-                  "zh-CN/platforms/hetzner",
-                  "zh-CN/platforms/gcp",
-                  "zh-CN/platforms/macos-vm",
-                  "zh-CN/platforms/exe-dev",
-                  "zh-CN/railway",
-                  "zh-CN/render",
-                  "zh-CN/northflank"
-                ]
-              },
-              {
-                "group": "Security",
-                "pages": ["zh-CN/security/formal-verification"]
-              },
-              {
-                "group": "Web interfaces",
-                "pages": [
-                  "zh-CN/web/index",
-                  "zh-CN/web/control-ui",
-                  "zh-CN/web/dashboard",
-                  "zh-CN/web/webchat",
-                  "zh-CN/tui"
-                ]
-              },
-              {
-                "group": "macOS companion app",
+                "group": "macOS 配套应用",
                 "pages": [
                   "zh-CN/platforms/mac/dev-setup",
                   "zh-CN/platforms/mac/menu-bar",
@@ -1512,10 +1544,87 @@
             ]
           },
           {
-            "tab": "Reference",
+            "tab": "网关与运维",
             "groups": [
               {
-                "group": "CLI commands",
+                "group": "网关",
+                "pages": [
+                  "zh-CN/gateway/index",
+                  {
+                    "group": "配置与运维",
+                    "pages": [
+                      "zh-CN/gateway/configuration",
+                      "zh-CN/gateway/configuration-examples",
+                      "zh-CN/gateway/authentication",
+                      "zh-CN/gateway/health",
+                      "zh-CN/gateway/heartbeat",
+                      "zh-CN/gateway/doctor",
+                      "zh-CN/gateway/logging",
+                      "zh-CN/gateway/gateway-lock",
+                      "zh-CN/gateway/background-process",
+                      "zh-CN/gateway/multiple-gateways",
+                      "zh-CN/gateway/troubleshooting"
+                    ]
+                  },
+                  {
+                    "group": "安全与沙箱",
+                    "pages": [
+                      "zh-CN/gateway/security/index",
+                      "zh-CN/gateway/sandboxing",
+                      "zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated"
+                    ]
+                  },
+                  {
+                    "group": "协议与 API",
+                    "pages": [
+                      "zh-CN/gateway/protocol",
+                      "zh-CN/gateway/bridge-protocol",
+                      "zh-CN/gateway/openai-http-api",
+                      "zh-CN/gateway/tools-invoke-http-api",
+                      "zh-CN/gateway/cli-backends",
+                      "zh-CN/gateway/local-models"
+                    ]
+                  },
+                  {
+                    "group": "网络与发现",
+                    "pages": [
+                      "zh-CN/gateway/network-model",
+                      "zh-CN/gateway/pairing",
+                      "zh-CN/gateway/discovery",
+                      "zh-CN/gateway/bonjour"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "远程访问",
+                "pages": [
+                  "zh-CN/gateway/remote",
+                  "zh-CN/gateway/remote-gateway-readme",
+                  "zh-CN/gateway/tailscale"
+                ]
+              },
+              {
+                "group": "安全",
+                "pages": ["zh-CN/security/formal-verification"]
+              },
+              {
+                "group": "Web 界面",
+                "pages": [
+                  "zh-CN/web/index",
+                  "zh-CN/web/control-ui",
+                  "zh-CN/web/dashboard",
+                  "zh-CN/web/webchat",
+                  "zh-CN/tui"
+                ]
+              }
+            ]
+          },
+          {
+            "tab": "参考",
+            "groups": [
+              {
+                "group": "CLI 命令",
                 "pages": [
                   "zh-CN/cli/index",
                   "zh-CN/cli/agent",
@@ -1556,11 +1665,11 @@
                 ]
               },
               {
-                "group": "RPC and API",
+                "group": "RPC 与 API",
                 "pages": ["zh-CN/reference/rpc", "zh-CN/reference/device-models"]
               },
               {
-                "group": "Templates",
+                "group": "模板",
                 "pages": [
                   "zh-CN/reference/AGENTS.default",
                   "zh-CN/reference/templates/AGENTS",
@@ -1574,7 +1683,7 @@
                 ]
               },
               {
-                "group": "Technical reference",
+                "group": "技术参考",
                 "pages": [
                   "zh-CN/concepts/typebox",
                   "zh-CN/concepts/markdown-formatting",
@@ -1585,20 +1694,28 @@
                 ]
               },
               {
-                "group": "Release notes",
+                "group": "项目",
+                "pages": ["zh-CN/reference/credits"]
+              },
+              {
+                "group": "发布说明",
                 "pages": ["zh-CN/reference/RELEASING", "zh-CN/reference/test"]
               }
             ]
           },
           {
-            "tab": "Help",
+            "tab": "帮助",
             "groups": [
               {
-                "group": "Help",
+                "group": "帮助",
                 "pages": ["zh-CN/help/index", "zh-CN/help/troubleshooting", "zh-CN/help/faq"]
               },
               {
-                "group": "Environment and debugging",
+                "group": "社区",
+                "pages": ["zh-CN/start/lore"]
+              },
+              {
+                "group": "环境与调试",
                 "pages": [
                   "zh-CN/environment",
                   "zh-CN/debugging",
@@ -1606,6 +1723,14 @@
                   "zh-CN/scripts",
                   "zh-CN/reference/session-management-compaction"
                 ]
+              },
+              {
+                "group": "开发者工作流",
+                "pages": ["zh-CN/start/setup"]
+              },
+              {
+                "group": "文档元信息",
+                "pages": ["zh-CN/start/hubs", "zh-CN/start/docs-directory"]
               }
             ]
           }

docs/gateway/cli-backends.md

@@ -25,13 +25,13 @@ want “always works” text responses without relying on external APIs.
 You can use Claude Code CLI **without any config** (OpenClaw ships a built-in default):
 
 ```bash
-openclaw agent --message "hi" --model claude-cli/opus-4.5
+openclaw agent --message "hi" --model claude-cli/opus-4.6
 ```
 
 Codex CLI also works out of the box:
 
 ```bash
-openclaw agent --message "hi" --model codex-cli/gpt-5.2-codex
+openclaw agent --message "hi" --model codex-cli/gpt-5.3-codex
 ```
 
 If your gateway runs under launchd/systemd and PATH is minimal, add just the
@@ -62,11 +62,12 @@ Add a CLI backend to your fallback list so it only runs when primary models fail
   agents: {
     defaults: {
       model: {
-        primary: "anthropic/claude-opus-4-5",
-        fallbacks: ["claude-cli/opus-4.5"],
+        primary: "anthropic/claude-opus-4-6",
+        fallbacks: ["claude-cli/opus-4.6", "claude-cli/opus-4.5"],
       },
       models: {
-        "anthropic/claude-opus-4-5": { alias: "Opus" },
+        "anthropic/claude-opus-4-6": { alias: "Opus" },
+        "claude-cli/opus-4.6": {},
         "claude-cli/opus-4.5": {},
       },
     },
@@ -112,6 +113,7 @@ The provider id becomes the left side of your model ref:
           input: "arg",
           modelArg: "--model",
           modelAliases: {
+            "claude-opus-4-6": "opus",
             "claude-opus-4-5": "opus",
             "claude-sonnet-4-5": "sonnet",
           },

docs/gateway/configuration-examples.md

@@ -226,13 +226,13 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
       userTimezone: "America/Chicago",
       model: {
         primary: "anthropic/claude-sonnet-4-5",
-        fallbacks: ["anthropic/claude-opus-4-5", "openai/gpt-5.2"],
+        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.2"],
       },
       imageModel: {
         primary: "openrouter/anthropic/claude-sonnet-4-5",
       },
       models: {
-        "anthropic/claude-opus-4-5": { alias: "opus" },
+        "anthropic/claude-opus-4-6": { alias: "opus" },
         "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
         "openai/gpt-5.2": { alias: "gpt" },
       },
@@ -496,7 +496,7 @@ If more than one person can DM your bot (multiple entries in `allowFrom`, pairin
     workspace: "~/.openclaw/workspace",
     model: {
       primary: "anthropic/claude-sonnet-4-5",
-      fallbacks: ["anthropic/claude-opus-4-5"],
+      fallbacks: ["anthropic/claude-opus-4-6"],
     },
   },
 }
@@ -534,7 +534,7 @@ If more than one person can DM your bot (multiple entries in `allowFrom`, pairin
   agent: {
     workspace: "~/.openclaw/workspace",
     model: {
-      primary: "anthropic/claude-opus-4-5",
+      primary: "anthropic/claude-opus-4-6",
       fallbacks: ["minimax/MiniMax-M2.1"],
     },
   },

docs/gateway/configuration.md

@@ -1547,8 +1547,8 @@ The `responsePrefix` string can include template variables that resolve dynamica
 
 | Variable          | Description            | Example                     |
 | ----------------- | ---------------------- | --------------------------- |
-| `{model}`         | Short model name       | `claude-opus-4-5`, `gpt-4o` |
-| `{modelFull}`     | Full model identifier  | `anthropic/claude-opus-4-5` |
+| `{model}`         | Short model name       | `claude-opus-4-6`, `gpt-4o` |
+| `{modelFull}`     | Full model identifier  | `anthropic/claude-opus-4-6` |
 | `{provider}`      | Provider name          | `anthropic`, `openai`       |
 | `{thinkingLevel}` | Current thinking level | `high`, `low`, `off`        |
 | `{identity.name}` | Agent identity name    | (same as `"auto"` mode)     |
@@ -1564,7 +1564,7 @@ Unresolved variables remain as literal text.
 }
 ```
 
-Example output: `[claude-opus-4-5 | think:high] Here's my response...`
+Example output: `[claude-opus-4-6 | think:high] Here's my response...`
 
 WhatsApp inbound prefix is configured via `channels.whatsapp.messagePrefix` (deprecated:
 `messages.messagePrefix`). Default stays **unchanged**: `"[openclaw]"` when
@@ -1710,7 +1710,7 @@ Z.AI GLM-4.x models automatically enable thinking mode unless you:
 OpenClaw also ships a few built-in alias shorthands. Defaults only apply when the model
 is already present in `agents.defaults.models`:
 
-- `opus` -> `anthropic/claude-opus-4-5`
+- `opus` -> `anthropic/claude-opus-4-6`
 - `sonnet` -> `anthropic/claude-sonnet-4-5`
 - `gpt` -> `openai/gpt-5.2`
 - `gpt-mini` -> `openai/gpt-5-mini`
@@ -1719,18 +1719,18 @@ is already present in `agents.defaults.models`:
 
 If you configure the same alias name (case-insensitive) yourself, your value wins (defaults never override).
 
-Example: Opus 4.5 primary with MiniMax M2.1 fallback (hosted MiniMax):
+Example: Opus 4.6 primary with MiniMax M2.1 fallback (hosted MiniMax):
 
 ```json5
 {
   agents: {
     defaults: {
       models: {
-        "anthropic/claude-opus-4-5": { alias: "opus" },
+        "anthropic/claude-opus-4-6": { alias: "opus" },
         "minimax/MiniMax-M2.1": { alias: "minimax" },
       },
       model: {
-        primary: "anthropic/claude-opus-4-5",
+        primary: "anthropic/claude-opus-4-6",
         fallbacks: ["minimax/MiniMax-M2.1"],
       },
     },
@@ -1786,7 +1786,7 @@ Example:
   agents: {
     defaults: {
       models: {
-        "anthropic/claude-opus-4-5": { alias: "Opus" },
+        "anthropic/claude-opus-4-6": { alias: "Opus" },
         "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
         "openrouter/deepseek/deepseek-r1:free": {},
         "zai/glm-4.7": {
@@ -1800,7 +1800,7 @@ Example:
         },
       },
       model: {
-        primary: "anthropic/claude-opus-4-5",
+        primary: "anthropic/claude-opus-4-6",
         fallbacks: [
           "openrouter/deepseek/deepseek-r1:free",
           "openrouter/meta-llama/llama-3.3-70b-instruct:free",
@@ -2011,7 +2011,7 @@ Typing indicators:
 - `session.typingIntervalSeconds`: per-session override for the refresh interval.
   See [/concepts/typing-indicators](/concepts/typing-indicators) for behavior details.
 
-`agents.defaults.model.primary` should be set as `provider/model` (e.g. `anthropic/claude-opus-4-5`).
+`agents.defaults.model.primary` should be set as `provider/model` (e.g. `anthropic/claude-opus-4-6`).
 Aliases come from `agents.defaults.models.*.alias` (e.g. `Opus`).
 If you omit the provider, OpenClaw currently assumes `anthropic` as a temporary
 deprecation fallback.
@@ -2485,7 +2485,7 @@ the built-in `opencode` provider from pi-ai; set `OPENCODE_API_KEY` (or
 
 Notes:
 
-- Model refs use `opencode/<modelId>` (example: `opencode/claude-opus-4-5`).
+- Model refs use `opencode/<modelId>` (example: `opencode/claude-opus-4-6`).
 - If you enable an allowlist via `agents.defaults.models`, add each model you plan to use.
 - Shortcut: `openclaw onboard --auth-choice opencode-zen`.
 
@@ -2493,8 +2493,8 @@ Notes:
 {
   agents: {
     defaults: {
-      model: { primary: "opencode/claude-opus-4-5" },
-      models: { "opencode/claude-opus-4-5": { alias: "Opus" } },
+      model: { primary: "opencode/claude-opus-4-6" },
+      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },
     },
   },
 }
@@ -2652,7 +2652,7 @@ Use MiniMax M2.1 directly without LM Studio:
   agent: {
     model: { primary: "minimax/MiniMax-M2.1" },
     models: {
-      "anthropic/claude-opus-4-5": { alias: "Opus" },
+      "anthropic/claude-opus-4-6": { alias: "Opus" },
       "minimax/MiniMax-M2.1": { alias: "Minimax" },
     },
   },
@@ -3173,8 +3173,7 @@ Defaults:
 Requests must include the hook token:
 
 - `Authorization: Bearer <token>` **or**
-- `x-openclaw-token: <token>` **or**
-- `?token=<token>`
+- `x-openclaw-token: <token>`
 
 Endpoints:
 

docs/gateway/heartbeat.md

@@ -83,7 +83,7 @@ and logged; a message that is only `HEARTBEAT_OK` is dropped.
     defaults: {
       heartbeat: {
         every: "30m", // default: 30m (0m disables)
-        model: "anthropic/claude-opus-4-5",
+        model: "anthropic/claude-opus-4-6",
         includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
         target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
         to: "+15551234567", // optional channel-specific override
@@ -137,6 +137,30 @@ Example: two agents, only the second agent runs heartbeats.
 }
 ```
 
+### Active hours example
+
+Restrict heartbeats to business hours in a specific timezone:
+
+```json5
+{
+  agents: {
+    defaults: {
+      heartbeat: {
+        every: "30m",
+        target: "last",
+        activeHours: {
+          start: "09:00",
+          end: "22:00",
+          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
+        },
+      },
+    },
+  },
+}
+```
+
+Outside this window (before 9am or after 10pm Eastern), heartbeats are skipped. The next scheduled tick inside the window will run normally.
+
 ### Multi account example
 
 Use `accountId` to target a specific account on multi-account channels like Telegram:
@@ -183,6 +207,11 @@ Use `accountId` to target a specific account on multi-account channels like Tele
 - `accountId`: optional account id for multi-account channels. When `target: "last"`, the account id applies to the resolved last channel if it supports accounts; otherwise it is ignored. If the account id does not match a configured account for the resolved channel, delivery is skipped.
 - `prompt`: overrides the default prompt body (not merged).
 - `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery.
+- `activeHours`: restricts heartbeat runs to a time window. Object with `start` (HH:MM, inclusive), `end` (HH:MM exclusive; `24:00` allowed for end-of-day), and optional `timezone`.
+  - Omitted or `"user"`: uses your `agents.defaults.userTimezone` if set, otherwise falls back to the host system timezone.
+  - `"local"`: always uses the host system timezone.
+  - Any IANA identifier (e.g. `America/New_York`): used directly; if invalid, falls back to the `"user"` behavior above.
+  - Outside the active window, heartbeats are skipped until the next tick inside the window.
 
 ## Delivery behavior
 

docs/gateway/local-models.md

@@ -21,7 +21,7 @@ Best current local stack. Load MiniMax M2.1 in LM Studio, enable the local serve
     defaults: {
       model: { primary: "lmstudio/minimax-m2.1-gs32" },
       models: {
-        "anthropic/claude-opus-4-5": { alias: "Opus" },
+        "anthropic/claude-opus-4-6": { alias: "Opus" },
         "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" },
       },
     },
@@ -68,12 +68,12 @@ Keep hosted models configured even when running local; use `models.mode: "merge"
     defaults: {
       model: {
         primary: "anthropic/claude-sonnet-4-5",
-        fallbacks: ["lmstudio/minimax-m2.1-gs32", "anthropic/claude-opus-4-5"],
+        fallbacks: ["lmstudio/minimax-m2.1-gs32", "anthropic/claude-opus-4-6"],
       },
       models: {
         "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
         "lmstudio/minimax-m2.1-gs32": { alias: "MiniMax Local" },
-        "anthropic/claude-opus-4-5": { alias: "Opus" },
+        "anthropic/claude-opus-4-6": { alias: "Opus" },
       },
     },
   },

docs/gateway/remote.md

@@ -28,7 +28,7 @@ Run the Gateway on a persistent host and reach it via **Tailscale** or SSH.
 
 - **Best UX:** keep `gateway.bind: "loopback"` and use **Tailscale Serve** for the Control UI.
 - **Fallback:** keep loopback + SSH tunnel from any machine that needs access.
-- **Examples:** [exe.dev](/platforms/exe-dev) (easy VM) or [Hetzner](/platforms/hetzner) (production VPS).
+- **Examples:** [exe.dev](/install/exe-dev) (easy VM) or [Hetzner](/install/hetzner) (production VPS).
 
 This is ideal when your laptop sleeps often but you want the agent always-on.
 

docs/gateway/security/index.md

@@ -243,7 +243,7 @@ Even with strong system prompts, **prompt injection is not solved**. System prom
 - Run sensitive tool execution in a sandbox; keep secrets out of the agent’s reachable filesystem.
 - Note: sandboxing is opt-in. If sandbox mode is off, exec runs on the gateway host even though tools.exec.host defaults to sandbox, and host exec does not require approvals unless you set host=gateway and configure exec approvals.
 - Limit high-risk tools (`exec`, `browser`, `web_fetch`, `web_search`) to trusted agents or explicit allowlists.
-- **Model choice matters:** older/legacy models can be less robust against prompt injection and tool misuse. Prefer modern, instruction-hardened models for any bot with tools. We recommend Anthropic Opus 4.5 because it’s quite good at recognizing prompt injections (see [“A step forward on safety”](https://www.anthropic.com/news/claude-opus-4-5)).
+- **Model choice matters:** older/legacy models can be less robust against prompt injection and tool misuse. Prefer modern, instruction-hardened models for any bot with tools. We recommend Anthropic Opus 4.6 (or the latest Opus) because it’s strong at recognizing prompt injections (see [“A step forward on safety”](https://www.anthropic.com/news/claude-opus-4-5)).
 
 Red flags to treat as untrusted:
 

docs/help/faq.md

@@ -141,7 +141,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [Can I use self-hosted models (llama.cpp, vLLM, Ollama)?](#can-i-use-selfhosted-models-llamacpp-vllm-ollama)
   - [What do OpenClaw, Flawd, and Krill use for models?](#what-do-openclaw-flawd-and-krill-use-for-models)
   - [How do I switch models on the fly (without restarting)?](#how-do-i-switch-models-on-the-fly-without-restarting)
-  - [Can I use GPT 5.2 for daily tasks and Codex 5.2 for coding](#can-i-use-gpt-52-for-daily-tasks-and-codex-52-for-coding)
+  - [Can I use GPT 5.2 for daily tasks and Codex 5.3 for coding](#can-i-use-gpt-52-for-daily-tasks-and-codex-53-for-coding)
   - [Why do I see "Model … is not allowed" and then no reply?](#why-do-i-see-model-is-not-allowed-and-then-no-reply)
   - [Why do I see "Unknown model: minimax/MiniMax-M2.1"?](#why-do-i-see-unknown-model-minimaxminimaxm21)
   - [Can I use MiniMax as my default and OpenAI for complex tasks?](#can-i-use-minimax-as-my-default-and-openai-for-complex-tasks)
@@ -334,21 +334,21 @@ If you don't have a global install yet, run it via `pnpm openclaw onboard`.
 
 ### How do I open the dashboard after onboarding
 
-The wizard now opens your browser with a tokenized dashboard URL right after onboarding and also prints the full link (with token) in the summary. Keep that tab open; if it didn't launch, copy/paste the printed URL on the same machine. Tokens stay local to your host-nothing is fetched from the browser.
+The wizard opens your browser with a clean (non-tokenized) dashboard URL right after onboarding and also prints the link in the summary. Keep that tab open; if it didn't launch, copy/paste the printed URL on the same machine.
 
 ### How do I authenticate the dashboard token on localhost vs remote
 
 **Localhost (same machine):**
 
 - Open `http://127.0.0.1:18789/`.
-- If it asks for auth, run `openclaw dashboard` and use the tokenized link (`?token=...`).
-- The token is the same value as `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) and is stored by the UI after first load.
+- If it asks for auth, paste the token from `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) into Control UI settings.
+- Retrieve it from the gateway host: `openclaw config get gateway.auth.token` (or generate one: `openclaw doctor --generate-gateway-token`).
 
 **Not on localhost:**
 
 - **Tailscale Serve** (recommended): keep bind loopback, run `openclaw gateway --tailscale serve`, open `https://<magicdns>/`. If `gateway.auth.allowTailscale` is `true`, identity headers satisfy auth (no token).
 - **Tailnet bind**: run `openclaw gateway --bind tailnet --token "<token>"`, open `http://<tailscale-ip>:18789/`, paste token in dashboard settings.
-- **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/?token=...` from `openclaw dashboard`.
+- **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/` and paste the token in Control UI settings.
 
 See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details.
 
@@ -591,7 +591,7 @@ Short answer: follow the Linux guide, then run the onboarding wizard.
 
 Any Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway.
 
-Guides: [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [Fly.io](/platforms/fly).
+Guides: [exe.dev](/install/exe-dev), [Hetzner](/install/hetzner), [Fly.io](/install/fly).
 Remote access: [Gateway remote](/gateway/remote).
 
 ### Where are the cloudVPS install guides
@@ -599,9 +599,9 @@ Remote access: [Gateway remote](/gateway/remote).
 We keep a **hosting hub** with the common providers. Pick one and follow the guide:
 
 - [VPS hosting](/vps) (all providers in one place)
-- [Fly.io](/platforms/fly)
-- [Hetzner](/platforms/hetzner)
-- [exe.dev](/platforms/exe-dev)
+- [Fly.io](/install/fly)
+- [Hetzner](/install/hetzner)
+- [exe.dev](/install/exe-dev)
 
 How it works in the cloud: the **Gateway runs on the server**, and you access it
 from your laptop/phone via the Control UI (or Tailscale/SSH). Your state + workspace
@@ -707,7 +707,7 @@ Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**.
 
 ### How does Codex auth work
 
-OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). The wizard can run the OAuth flow and will set the default model to `openai-codex/gpt-5.2` when appropriate. See [Model providers](/concepts/model-providers) and [Wizard](/start/wizard).
+OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). The wizard can run the OAuth flow and will set the default model to `openai-codex/gpt-5.3-codex` when appropriate. See [Model providers](/concepts/model-providers) and [Wizard](/start/wizard).
 
 ### Do you support OpenAI subscription auth Codex OAuth
 
@@ -910,7 +910,7 @@ Baseline guidance:
 
 If you are on Windows, **WSL2 is the easiest VM style setup** and has the best tooling
 compatibility. See [Windows](/platforms/windows), [VPS hosting](/vps).
-If you are running macOS in a VM, see [macOS VM](/platforms/macos-vm).
+If you are running macOS in a VM, see [macOS VM](/install/macos-vm).
 
 ## What is OpenClaw?
 
@@ -1936,11 +1936,11 @@ OpenClaw's default model is whatever you set as:
 agents.defaults.model.primary
 ```
 
-Models are referenced as `provider/model` (example: `anthropic/claude-opus-4-5`). If you omit the provider, OpenClaw currently assumes `anthropic` as a temporary deprecation fallback - but you should still **explicitly** set `provider/model`.
+Models are referenced as `provider/model` (example: `anthropic/claude-opus-4-6`). If you omit the provider, OpenClaw currently assumes `anthropic` as a temporary deprecation fallback - but you should still **explicitly** set `provider/model`.
 
 ### What model do you recommend
 
-**Recommended default:** `anthropic/claude-opus-4-5`.
+**Recommended default:** `anthropic/claude-opus-4-6`.
 **Good alternative:** `anthropic/claude-sonnet-4-5`.
 **Reliable (less character):** `openai/gpt-5.2` - nearly as good as Opus, just less personality.
 **Budget:** `zai/glm-4.7`.
@@ -1989,7 +1989,7 @@ Docs: [Models](/concepts/models), [Configure](/cli/configure), [Config](/cli/con
 
 ### What do OpenClaw, Flawd, and Krill use for models
 
-- **OpenClaw + Flawd:** Anthropic Opus (`anthropic/claude-opus-4-5`) - see [Anthropic](/providers/anthropic).
+- **OpenClaw + Flawd:** Anthropic Opus (`anthropic/claude-opus-4-6`) - see [Anthropic](/providers/anthropic).
 - **Krill:** MiniMax M2.1 (`minimax/MiniMax-M2.1`) - see [MiniMax](/providers/minimax).
 
 ### How do I switch models on the fly without restarting
@@ -2029,18 +2029,18 @@ It also shows the configured provider endpoint (`baseUrl`) and API mode (`api`)
 Re-run `/model` **without** the `@profile` suffix:
 
 ```
-/model anthropic/claude-opus-4-5
+/model anthropic/claude-opus-4-6
 ```
 
 If you want to return to the default, pick it from `/model` (or send `/model <default provider/model>`).
 Use `/model status` to confirm which auth profile is active.
 
-### Can I use GPT 5.2 for daily tasks and Codex 5.2 for coding
+### Can I use GPT 5.2 for daily tasks and Codex 5.3 for coding
 
 Yes. Set one as default and switch as needed:
 
-- **Quick switch (per session):** `/model gpt-5.2` for daily tasks, `/model gpt-5.2-codex` for coding.
-- **Default + switch:** set `agents.defaults.model.primary` to `openai-codex/gpt-5.2`, then switch to `openai-codex/gpt-5.2-codex` when coding (or the other way around).
+- **Quick switch (per session):** `/model gpt-5.2` for daily tasks, `/model gpt-5.3-codex` for coding.
+- **Default + switch:** set `agents.defaults.model.primary` to `openai/gpt-5.2`, then switch to `openai-codex/gpt-5.3-codex` when coding (or the other way around).
 - **Sub-agents:** route coding tasks to sub-agents with a different default model.
 
 See [Models](/concepts/models) and [Slash commands](/tools/slash-commands).
@@ -2118,7 +2118,7 @@ Docs: [Models](/concepts/models), [Multi-Agent Routing](/concepts/multi-agent),
 
 Yes. OpenClaw ships a few default shorthands (only applied when the model exists in `agents.defaults.models`):
 
-- `opus` → `anthropic/claude-opus-4-5`
+- `opus` → `anthropic/claude-opus-4-6`
 - `sonnet` → `anthropic/claude-sonnet-4-5`
 - `gpt` → `openai/gpt-5.2`
 - `gpt-mini` → `openai/gpt-5-mini`
@@ -2135,9 +2135,9 @@ Aliases come from `agents.defaults.models.<modelId>.alias`. Example:
 {
   agents: {
     defaults: {
-      model: { primary: "anthropic/claude-opus-4-5" },
+      model: { primary: "anthropic/claude-opus-4-6" },
       models: {
-        "anthropic/claude-opus-4-5": { alias: "opus" },
+        "anthropic/claude-opus-4-6": { alias: "opus" },
         "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
         "anthropic/claude-haiku-4-5": { alias: "haiku" },
       },
@@ -2383,15 +2383,14 @@ Your gateway is running with auth enabled (`gateway.auth.*`), but the UI is not
 Facts (from code):
 
 - The Control UI stores the token in browser localStorage key `openclaw.control.settings.v1`.
-- The UI can import `?token=...` (and/or `?password=...`) once, then strips it from the URL.
 
 Fix:
 
-- Fastest: `openclaw dashboard` (prints + copies tokenized link, tries to open; shows SSH hint if headless).
+- Fastest: `openclaw dashboard` (prints + copies the dashboard URL, tries to open; shows SSH hint if headless).
 - If you don't have a token yet: `openclaw doctor --generate-gateway-token`.
-- If remote, tunnel first: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/?token=...`.
+- If remote, tunnel first: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`.
 - Set `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) on the gateway host.
-- In the Control UI settings, paste the same token (or refresh with a one-time `?token=...` link).
+- In the Control UI settings, paste the same token.
 - Still stuck? Run `openclaw status --all` and follow [Troubleshooting](/gateway/troubleshooting). See [Dashboard](/web/dashboard) for auth details.
 
 ### I set gatewaybind tailnet but it cant bind nothing listens
@@ -2823,7 +2822,7 @@ You can add options like `debounce:2s cap:25 drop:summarize` for followup modes.
 
 **Q: "What's the default model for Anthropic with an API key?"**
 
-**A:** In OpenClaw, credentials and model selection are separate. Setting `ANTHROPIC_API_KEY` (or storing an Anthropic API key in auth profiles) enables authentication, but the actual default model is whatever you configure in `agents.defaults.model.primary` (for example, `anthropic/claude-sonnet-4-5` or `anthropic/claude-opus-4-5`). If you see `No credentials found for profile "anthropic:default"`, it means the Gateway couldn't find Anthropic credentials in the expected `auth-profiles.json` for the agent that's running.
+**A:** In OpenClaw, credentials and model selection are separate. Setting `ANTHROPIC_API_KEY` (or storing an Anthropic API key in auth profiles) enables authentication, but the actual default model is whatever you configure in `agents.defaults.model.primary` (for example, `anthropic/claude-sonnet-4-5` or `anthropic/claude-opus-4-6`). If you see `No credentials found for profile "anthropic:default"`, it means the Gateway couldn't find Anthropic credentials in the expected `auth-profiles.json` for the agent that's running.
 
 ---
 

docs/help/submitting-a-pr.md

@@ -0,0 +1,214 @@
+---
+summary: "How to submit a high signal PR"
+title: "Submitting a PR"
+---
+
+# Submitting a PR
+
+Good PRs make it easy for reviewers to understand intent, verify behavior, and land changes safely. This guide focuses on high-signal, low-noise submissions that work well with both human review and LLM-assisted review.
+
+## What makes a good PR
+
+- [ ] Clear intent: explain the problem, why it matters, and what the change does.
+- [ ] Tight scope: keep changes focused and avoid drive-by refactors.
+- [ ] Behavior summary: call out user-visible changes, config changes, and defaults.
+- [ ] Tests: list what ran, what was skipped, and why.
+- [ ] Evidence: include logs, screenshots, or short recordings for UI or workflows.
+- [ ] Code word: include “lobster-biscuit” somewhere in the PR description to confirm you read this guide.
+- [ ] Baseline checks: run the relevant `pnpm` commands for this repo and fix failures before opening the PR.
+- [ ] Due diligence: search the codebase for existing functionality and check GitHub for related issues or prior fixes.
+- [ ] Grounded in reality: claims should be backed by evidence, reproduction, or direct observation.
+- [ ] Title guidance: use a verb + scope + outcome (for example `Docs: add PR and issue templates`).
+
+Guideline: concision > grammar. Be terse if it makes review faster.
+
+Baseline validation commands (run as appropriate for the change, and fix failures before submitting):
+
+- `pnpm lint`
+- `pnpm check`
+- `pnpm build`
+- `pnpm test`
+- If you touch protocol code: `pnpm protocol:check`
+
+## Progressive disclosure
+
+Use a short top section, then deeper details as needed.
+
+1. Summary and intent
+2. Behavior changes and risks
+3. Tests and verification
+4. Implementation details and evidence
+
+This keeps review fast while preserving deep context for anyone who needs it.
+
+## Common PR types and expectations
+
+- [ ] Fix: include clear repro, root cause summary, and verification steps.
+- [ ] Feature: include use cases, behavior changes, and screenshots or demos when UI is involved.
+- [ ] Refactor: explicitly state “no behavior change” and list what moved or was simplified.
+- [ ] Chore/Maintenance: note why it matters (build time, CI stability, dependency hygiene).
+- [ ] Docs: include before/after context and link to the updated page. Run `pnpm format`.
+- [ ] Test: explain the gap it covers and how it prevents regressions.
+- [ ] Perf: include baseline and after metrics, plus how they were measured.
+- [ ] UX/UI: include screenshots or short recordings and any accessibility impact.
+- [ ] Infra/Build: call out affected environments and how to validate.
+- [ ] Security: include threat or risk summary, repro steps, and verification plan. Avoid sensitive data in public logs.
+- [ ] Security: keep reports grounded in reality; avoid speculative claims.
+
+## Checklist
+
+- [ ] Problem and intent are clear
+- [ ] Scope is focused
+- [ ] Behavior changes are listed
+- [ ] Tests are listed with results
+- [ ] Evidence is attached when needed
+- [ ] No secrets or private data
+- [ ] Grounded in reality: no guesswork or invented context.
+
+## Template
+
+```md
+## Summary
+
+## Behavior Changes
+
+## Codebase and GitHub Search
+
+## Tests
+
+## Evidence
+```
+
+## Templates by PR type
+
+### Fix
+
+```md
+## Summary
+
+## Repro Steps
+
+## Root Cause
+
+## Behavior Changes
+
+## Tests
+
+## Evidence
+```
+
+### Feature
+
+```md
+## Summary
+
+## Use Cases
+
+## Behavior Changes
+
+## Existing Functionality Check
+
+I searched the codebase for existing functionality before implementing this.
+
+## Tests
+
+## Evidence
+```
+
+### Refactor
+
+```md
+## Summary
+
+## Scope
+
+## No Behavior Change Statement
+
+## Tests
+```
+
+### Chore/Maintenance
+
+```md
+## Summary
+
+## Why This Matters
+
+## Tests
+```
+
+### Docs
+
+```md
+## Summary
+
+## Pages Updated
+
+## Screenshots or Before/After
+
+## Formatting
+
+pnpm format
+```
+
+### Test
+
+```md
+## Summary
+
+## Gap Covered
+
+## Tests
+```
+
+### Perf
+
+```md
+## Summary
+
+## Baseline
+
+## After
+
+## Measurement Method
+
+## Tests
+```
+
+### UX/UI
+
+```md
+## Summary
+
+## Screenshots or Video
+
+## Accessibility Impact
+
+## Tests
+```
+
+### Infra/Build
+
+```md
+## Summary
+
+## Environments Affected
+
+## Validation Steps
+```
+
+### Security
+
+```md
+## Summary
+
+## Risk Summary
+
+## Repro Steps
+
+## Mitigation or Fix
+
+## Verification
+
+## Tests
+```

docs/help/submitting-an-issue.md

@@ -0,0 +1,165 @@
+---
+summary: "How to file high signal issues and bug reports"
+title: "Submitting an Issue"
+---
+
+# Submitting an Issue
+
+Good issues make it easy to reproduce, diagnose, and fix problems quickly. This guide covers what to include for bugs, regressions, and feature gaps.
+
+## What makes a good issue
+
+- [ ] Clear title: include the area and the symptom.
+- [ ] Repro steps: minimal steps that consistently reproduce the issue.
+- [ ] Expected vs actual: what you thought would happen and what did.
+- [ ] Impact: who is affected and how severe the problem is.
+- [ ] Environment: OS, runtime, versions, and relevant config.
+- [ ] Evidence: logs, screenshots, or recordings (redacted; prefer non-PII data).
+- [ ] Scope: note if it is new, regression, or long-standing.
+- [ ] Code word: include “lobster-biscuit” somewhere in the issue description to confirm you read this guide.
+- [ ] Due diligence: search the codebase for existing functionality and check GitHub to see if the issue is already filed or fixed.
+- [ ] I searched for existing and recently closed issues/PRs.
+- [ ] For security reports: confirmed it has not already been fixed or addressed recently.
+- [ ] Grounded in reality: claims should be backed by evidence, reproduction, or direct observation.
+
+Guideline: concision > grammar. Be terse if it makes review faster.
+
+Baseline validation commands (run as appropriate for the change, and fix failures before submitting a PR):
+
+- `pnpm lint`
+- `pnpm check`
+- `pnpm build`
+- `pnpm test`
+- If you touch protocol code: `pnpm protocol:check`
+
+## Templates
+
+### Bug report
+
+```md
+## Bug report checklist
+
+- [ ] Minimal repro steps
+- [ ] Expected vs actual
+- [ ] Versions and environment
+- [ ] Affected channels and where it does not reproduce
+- [ ] Logs or screenshots
+- [ ] Evidence is redacted and non-PII where possible
+- [ ] Impact and severity
+- [ ] Any known workarounds
+
+## Summary
+
+## Repro Steps
+
+## Expected
+
+## Actual
+
+## Environment
+
+## Logs or Evidence
+
+## Impact
+
+## Workarounds
+```
+
+### Security issue
+
+```md
+## Summary
+
+## Impact
+
+## Affected Versions
+
+## Repro Steps (if safe to share)
+
+## Mitigation or Workaround
+
+## Evidence (redacted)
+```
+
+Security note: avoid posting secrets or exploit details in public issues. If the report is sensitive, keep repro details minimal and ask for a private disclosure path.
+
+### Regression report
+
+```md
+## Summary
+
+## Last Known Good
+
+## First Known Bad
+
+## Repro Steps
+
+## Expected
+
+## Actual
+
+## Environment
+
+## Logs or Evidence
+
+## Impact
+```
+
+### Feature request
+
+```md
+## Summary
+
+## Problem
+
+## Proposed Solution
+
+## Alternatives Considered
+
+## Impact
+
+## Evidence or Examples
+```
+
+### Enhancement request
+
+```md
+## Summary
+
+## Current Behavior
+
+## Desired Behavior
+
+## Why This Matters
+
+## Alternatives Considered
+
+## Evidence or Examples
+```
+
+### Investigation request
+
+```md
+## Summary
+
+## Symptoms
+
+## What Was Tried
+
+## Environment
+
+## Logs or Evidence
+
+## Impact
+```
+
+## If you are submitting a fix PR
+
+Creating a separate issue first is optional. If you skip it, include the relevant details in the PR description.
+
+- Keep the PR focused on the issue.
+- Include the issue number in the PR description.
+- Add tests when possible, or explain why they are not feasible.
+- Note any behavior changes and risks.
+- Include redacted logs, screenshots, or videos that validate the fix.
+- Run relevant `pnpm` validation commands and report results when appropriate.

docs/index.md

@@ -41,7 +41,20 @@ title: "OpenClaw"
   </Card>
 </Columns>
 
-OpenClaw connects chat apps to coding agents like Pi through a single Gateway process. It powers the OpenClaw assistant and supports local or remote setups.
+## What is OpenClaw?
+
+OpenClaw is a **self-hosted gateway** that connects your favorite chat apps — WhatsApp, Telegram, Discord, iMessage, and more — to AI coding agents like Pi. You run a single Gateway process on your own machine (or a server), and it becomes the bridge between your messaging apps and an always-available AI assistant.
+
+**Who is it for?** Developers and power users who want a personal AI assistant they can message from anywhere — without giving up control of their data or relying on a hosted service.
+
+**What makes it different?**
+
+- **Self-hosted**: runs on your hardware, your rules
+- **Multi-channel**: one Gateway serves WhatsApp, Telegram, Discord, and more simultaneously
+- **Agent-native**: built for coding agents with tool use, sessions, memory, and multi-agent routing
+- **Open source**: MIT licensed, community-driven
+
+**What do you need?** Node 22+, an API key (Anthropic recommended), and 5 minutes.
 
 ## How it works
 

docs/install/docker.md

@@ -56,14 +56,14 @@ After it finishes:
 
 - Open `http://127.0.0.1:18789/` in your browser.
 - Paste the token into the Control UI (Settings → token).
-- Need the tokenized URL again? Run `docker compose run --rm openclaw-cli dashboard --no-open`.
+- Need the URL again? Run `docker compose run --rm openclaw-cli dashboard --no-open`.
 
 It writes config/workspace on the host:
 
 - `~/.openclaw/`
 - `~/.openclaw/workspace`
 
-Running on a VPS? See [Hetzner (Docker VPS)](/platforms/hetzner).
+Running on a VPS? See [Hetzner (Docker VPS)](/install/hetzner).
 
 ### Manual flow (compose)
 

docs/install/exe-dev.md

@@ -103,9 +103,10 @@ server {
 
 ## 5) Access OpenClaw and grant privileges
 
-Access `https://<vm-name>.exe.xyz/?token=YOUR-TOKEN-FROM-TERMINAL` (see the Control UI output from onboarding). Approve
-devices with `openclaw devices list` and `openclaw devices approve <requestId>`. When in doubt,
-use Shelley from your browser!
+Access `https://<vm-name>.exe.xyz/` (see the Control UI output from onboarding). If it prompts for auth, paste the
+token from `gateway.auth.token` on the VM (retrieve with `openclaw config get gateway.auth.token`, or generate one
+with `openclaw doctor --generate-gateway-token`). Approve devices with `openclaw devices list` and
+`openclaw devices approve <requestId>`. When in doubt, use Shelley from your browser!
 
 ## Remote Access
 

docs/install/fly.md

@@ -148,7 +148,7 @@ cat > /data/openclaw.json << 'EOF'
   "agents": {
     "defaults": {
       "model": {
-        "primary": "anthropic/claude-opus-4-5",
+        "primary": "anthropic/claude-opus-4-6",
         "fallbacks": ["anthropic/claude-sonnet-4-5", "openai/gpt-4o"]
       },
       "maxConcurrent": 4

docs/install/index.md

@@ -3,10 +3,10 @@ summary: "Install OpenClaw (recommended installer, global install, or from sourc
 read_when:
   - Installing OpenClaw
   - You want to install from GitHub
-title: "Install"
+title: "Install Overview"
 ---
 
-# Install
+# Install Overview
 
 Use the installer unless you have a reason not to. It sets up the CLI and runs onboarding.
 
@@ -102,6 +102,8 @@ openclaw onboard --install-daemon
 
 Tip: if you don’t have a global install yet, run repo commands via `pnpm openclaw ...`.
 
+For deeper development workflows, see [Setup](/start/setup).
+
 ### 4) Other install options
 
 - Docker: [Docker](/install/docker)

docs/nodes/media-understanding.md

@@ -186,7 +186,7 @@ If you omit `capabilities`, the entry is eligible for the list it appears in.
 **Image**
 
 - Prefer your active model if it supports images.
-- Good defaults: `openai/gpt-5.2`, `anthropic/claude-opus-4-5`, `google/gemini-3-pro-preview`.
+- Good defaults: `openai/gpt-5.2`, `anthropic/claude-opus-4-6`, `google/gemini-3-pro-preview`.
 
 **Audio**
 
@@ -300,7 +300,7 @@ When `mode: "all"`, outputs are labeled `[Image 1/2]`, `[Audio 2/2]`, etc.
         maxChars: 500,
         models: [
           { provider: "openai", model: "gpt-5.2" },
-          { provider: "anthropic", model: "claude-opus-4-5" },
+          { provider: "anthropic", model: "claude-opus-4-6" },
           {
             type: "cli",
             command: "gemini",

docs/platforms/digitalocean.md

@@ -27,7 +27,7 @@ If you want a $0/month option and don’t mind ARM + provider-specific setup, se
 **Picking a provider:**
 
 - DigitalOcean: simplest UX + predictable setup (this guide)
-- Hetzner: good price/perf (see [Hetzner guide](/platforms/hetzner))
+- Hetzner: good price/perf (see [Hetzner guide](/install/hetzner))
 - Oracle Cloud: can be $0/month, but is more finicky and ARM-only (see [Oracle guide](/platforms/oracle))
 
 ---
@@ -256,7 +256,7 @@ free -h
 
 ## See Also
 
-- [Hetzner guide](/platforms/hetzner) — cheaper, more powerful
+- [Hetzner guide](/install/hetzner) — cheaper, more powerful
 - [Docker install](/install/docker) — containerized setup
 - [Tailscale](/gateway/tailscale) — secure remote access
 - [Configuration](/gateway/configuration) — full config reference

docs/platforms/index.md

@@ -26,10 +26,10 @@ Native companion apps for Windows are also planned; the Gateway is recommended v
 ## VPS & hosting
 
 - VPS hub: [VPS hosting](/vps)
-- Fly.io: [Fly.io](/platforms/fly)
-- Hetzner (Docker): [Hetzner](/platforms/hetzner)
-- GCP (Compute Engine): [GCP](/platforms/gcp)
-- exe.dev (VM + HTTPS proxy): [exe.dev](/platforms/exe-dev)
+- Fly.io: [Fly.io](/install/fly)
+- Hetzner (Docker): [Hetzner](/install/hetzner)
+- GCP (Compute Engine): [GCP](/install/gcp)
+- exe.dev (VM + HTTPS proxy): [exe.dev](/install/exe-dev)
 
 ## Common links
 

docs/platforms/linux.md

@@ -21,7 +21,7 @@ Native Linux companion apps are planned. Contributions are welcome if you want t
 4. From your laptop: `ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
 5. Open `http://127.0.0.1:18789/` and paste your token
 
-Step-by-step VPS guide: [exe.dev](/platforms/exe-dev)
+Step-by-step VPS guide: [exe.dev](/install/exe-dev)
 
 ## Install
 

docs/platforms/mac/release.md

@@ -34,17 +34,17 @@ Notes:
 # From repo root; set release IDs so Sparkle feed is enabled.
 # APP_BUILD must be numeric + monotonic for Sparkle compare.
 BUNDLE_ID=bot.molt.mac \
-APP_VERSION=2026.2.3 \
+APP_VERSION=2026.2.4 \
 APP_BUILD="$(git rev-list --count HEAD)" \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-app.sh
 
 # Zip for distribution (includes resource forks for Sparkle delta support)
-ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.2.3.zip
+ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.2.4.zip
 
 # Optional: also build a styled DMG for humans (drag to /Applications)
-scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.3.dmg
+scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.4.dmg
 
 # Recommended: build + notarize/staple zip + DMG
 # First, create a keychain profile once:
@@ -52,14 +52,14 @@ scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.3.dmg
 #     --apple-id "<apple-id>" --team-id "<team-id>" --password "<app-specific-password>"
 NOTARIZE=1 NOTARYTOOL_PROFILE=openclaw-notary \
 BUNDLE_ID=bot.molt.mac \
-APP_VERSION=2026.2.3 \
+APP_VERSION=2026.2.4 \
 APP_BUILD="$(git rev-list --count HEAD)" \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-dist.sh
 
 # Optional: ship dSYM alongside the release
-ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.2.3.dSYM.zip
+ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.2.4.dSYM.zip
 ```
 
 ## Appcast entry
@@ -67,7 +67,7 @@ ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenCl
 Use the release note generator so Sparkle renders formatted HTML notes:
 
 ```bash
-SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.2.3.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml
+SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.2.4.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml
 ```
 
 Generates HTML release notes from `CHANGELOG.md` (via [`scripts/changelog-to-html.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/changelog-to-html.sh)) and embeds them in the appcast entry.
@@ -75,7 +75,7 @@ Commit the updated `appcast.xml` alongside the release assets (zip + dSYM) when
 
 ## Publish & verify
 
-- Upload `OpenClaw-2026.2.3.zip` (and `OpenClaw-2026.2.3.dSYM.zip`) to the GitHub release for tag `v2026.2.3`.
+- Upload `OpenClaw-2026.2.4.zip` (and `OpenClaw-2026.2.4.dSYM.zip`) to the GitHub release for tag `v2026.2.4`.
 - Ensure the raw appcast URL matches the baked feed: `https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml`.
 - Sanity checks:
   - `curl -I https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml` returns 200.

docs/platforms/oracle.md

@@ -300,4 +300,4 @@ tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace
 - [Tailscale integration](/gateway/tailscale) — full Tailscale docs
 - [Gateway configuration](/gateway/configuration) — all config options
 - [DigitalOcean guide](/platforms/digitalocean) — if you want paid + easier signup
-- [Hetzner guide](/platforms/hetzner) — Docker-based alternative
+- [Hetzner guide](/install/hetzner) — Docker-based alternative

docs/platforms/raspberry-pi.md

@@ -353,6 +353,6 @@ echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
 
 - [Linux guide](/platforms/linux) — general Linux setup
 - [DigitalOcean guide](/platforms/digitalocean) — cloud alternative
-- [Hetzner guide](/platforms/hetzner) — Docker setup
+- [Hetzner guide](/install/hetzner) — Docker setup
 - [Tailscale](/gateway/tailscale) — remote access
 - [Nodes](/nodes) — pair your laptop/phone with the Pi gateway

docs/providers/anthropic.md

@@ -31,7 +31,7 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
 ```json5
 {
   env: { ANTHROPIC_API_KEY: "sk-ant-..." },
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
 }
 ```
 
@@ -54,7 +54,7 @@ Use the `cacheRetention` parameter in your model config:
   agents: {
     defaults: {
       models: {
-        "anthropic/claude-opus-4-5": {
+        "anthropic/claude-opus-4-6": {
           params: { cacheRetention: "long" },
         },
       },
@@ -114,7 +114,7 @@ openclaw onboard --auth-choice setup-token
 
 ```json5
 {
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
 }
 ```
 

docs/providers/index.md

@@ -29,7 +29,7 @@ See [Venice AI](/providers/venice).
 
 ```json5
 {
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
 }
 ```
 

docs/providers/minimax.md

@@ -96,7 +96,7 @@ Configure via CLI:
 
 ### MiniMax M2.1 as fallback (Opus primary)
 
-**Best for:** keep Opus 4.5 as primary, fail over to MiniMax M2.1.
+**Best for:** keep Opus 4.6 as primary, fail over to MiniMax M2.1.
 
 ```json5
 {
@@ -104,11 +104,11 @@ Configure via CLI:
   agents: {
     defaults: {
       models: {
-        "anthropic/claude-opus-4-5": { alias: "opus" },
+        "anthropic/claude-opus-4-6": { alias: "opus" },
         "minimax/MiniMax-M2.1": { alias: "minimax" },
       },
       model: {
-        primary: "anthropic/claude-opus-4-5",
+        primary: "anthropic/claude-opus-4-6",
         fallbacks: ["minimax/MiniMax-M2.1"],
       },
     },

docs/providers/models.md

@@ -27,7 +27,7 @@ See [Venice AI](/providers/venice).
 
 ```json5
 {
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
 }
 ```
 

docs/providers/ollama.md

@@ -17,6 +17,8 @@ Ollama is a local LLM runtime that makes it easy to run open-source models on yo
 2. Pull a model:
 
 ```bash
+ollama pull gpt-oss:20b
+# or
 ollama pull llama3.3
 # or
 ollama pull qwen2.5-coder:32b
@@ -40,7 +42,7 @@ openclaw config set models.providers.ollama.apiKey "ollama-local"
 {
   agents: {
     defaults: {
-      model: { primary: "ollama/llama3.3" },
+      model: { primary: "ollama/gpt-oss:20b" },
     },
   },
 }
@@ -105,8 +107,8 @@ Use explicit config when:
         api: "openai-completions",
         models: [
           {
-            id: "llama3.3",
-            name: "Llama 3.3",
+            id: "gpt-oss:20b",
+            name: "GPT-OSS 20B",
             reasoning: false,
             input: ["text"],
             cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
@@ -148,8 +150,8 @@ Once configured, all your Ollama models are available:
   agents: {
     defaults: {
       model: {
-        primary: "ollama/llama3.3",
-        fallback: ["ollama/qwen2.5-coder:32b"],
+        primary: "ollama/gpt-oss:20b",
+        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
       },
     },
   },
@@ -170,6 +172,48 @@ ollama pull deepseek-r1:32b
 
 Ollama is free and runs locally, so all model costs are set to $0.
 
+### Streaming Configuration
+
+Due to a [known issue](https://github.com/badlogic/pi-mono/issues/1205) in the underlying SDK with Ollama's response format, **streaming is disabled by default** for Ollama models. This prevents corrupted responses when using tool-capable models.
+
+When streaming is disabled, responses are delivered all at once (non-streaming mode), which avoids the issue where interleaved content/reasoning deltas cause garbled output.
+
+#### Re-enable Streaming (Advanced)
+
+If you want to re-enable streaming for Ollama (may cause issues with tool-capable models):
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "ollama/gpt-oss:20b": {
+          streaming: true,
+        },
+      },
+    },
+  },
+}
+```
+
+#### Disable Streaming for Other Providers
+
+You can also disable streaming for any provider if needed:
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-4": {
+          streaming: false,
+        },
+      },
+    },
+  },
+}
+```
+
 ### Context windows
 
 For auto-discovered models, OpenClaw uses the context window reported by Ollama when available, otherwise it defaults to `8192`. You can override `contextWindow` and `maxTokens` in explicit provider config.
@@ -201,7 +245,8 @@ To add models:
 
 ```bash
 ollama list  # See what's installed
-ollama pull llama3.3  # Pull a model
+ollama pull gpt-oss:20b  # Pull a tool-capable model
+ollama pull llama3.3     # Or another model
 ```
 
 ### Connection refused
@@ -216,6 +261,15 @@ ps aux | grep ollama
 ollama serve
 ```
 
+### Corrupted responses or tool names in output
+
+If you see garbled responses containing tool names (like `sessions_send`, `memory_get`) or fragmented text when using Ollama models, this is due to an upstream SDK issue with streaming responses. **This is fixed by default** in the latest OpenClaw version by disabling streaming for Ollama models.
+
+If you manually enabled streaming and experience this issue:
+
+1. Remove the `streaming: true` configuration from your Ollama model entries, or
+2. Explicitly set `streaming: false` for Ollama models (see [Streaming Configuration](#streaming-configuration))
+
 ## See Also
 
 - [Model Providers](/concepts/model-providers) - Overview of all providers

docs/providers/openai.md

@@ -29,7 +29,7 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY"
 ```json5
 {
   env: { OPENAI_API_KEY: "sk-..." },
-  agents: { defaults: { model: { primary: "openai/gpt-5.2" } } },
+  agents: { defaults: { model: { primary: "openai/gpt-5.1-codex" } } },
 }
 ```
 
@@ -52,7 +52,7 @@ openclaw models auth login --provider openai-codex
 
 ```json5
 {
-  agents: { defaults: { model: { primary: "openai-codex/gpt-5.2" } } },
+  agents: { defaults: { model: { primary: "openai-codex/gpt-5.3-codex" } } },
 }
 ```
 

docs/providers/opencode.md

@@ -25,7 +25,7 @@ openclaw onboard --opencode-zen-api-key "$OPENCODE_API_KEY"
 ```json5
 {
   env: { OPENCODE_API_KEY: "sk-..." },
-  agents: { defaults: { model: { primary: "opencode/claude-opus-4-5" } } },
+  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
 }
 ```
 

docs/providers/vercel-ai-gateway.md

@@ -28,7 +28,7 @@ openclaw onboard --auth-choice ai-gateway-api-key
 {
   agents: {
     defaults: {
-      model: { primary: "vercel-ai-gateway/anthropic/claude-opus-4.5" },
+      model: { primary: "vercel-ai-gateway/anthropic/claude-opus-4.6" },
     },
   },
 }

docs/reference/wizard.md

@@ -0,0 +1,268 @@
+---
+summary: "Full reference for the CLI onboarding wizard: every step, flag, and config field"
+read_when:
+  - Looking up a specific wizard step or flag
+  - Automating onboarding with non-interactive mode
+  - Debugging wizard behavior
+title: "Onboarding Wizard Reference"
+sidebarTitle: "Wizard Reference"
+---
+
+# Onboarding Wizard Reference
+
+This is the full reference for the `openclaw onboard` CLI wizard.
+For a high-level overview, see [Onboarding Wizard](/start/wizard).
+
+## Flow details (local mode)
+
+<Steps>
+  <Step title="Existing config detection">
+    - If `~/.openclaw/openclaw.json` exists, choose **Keep / Modify / Reset**.
+    - Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset**
+      (or pass `--reset`).
+    - If the config is invalid or contains legacy keys, the wizard stops and asks
+      you to run `openclaw doctor` before continuing.
+    - Reset uses `trash` (never `rm`) and offers scopes:
+      - Config only
+      - Config + credentials + sessions
+      - Full reset (also removes workspace)
+  </Step>
+  <Step title="Model/Auth">
+    - **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
+    - **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present.
+    - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default).
+    - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it.
+    - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
+      - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
+    - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.openclaw/.env` so launchd can read it.
+    - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth).
+    - **API key**: stores the key for you.
+    - **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.
+    - More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway)
+    - **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
+    - More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
+    - **MiniMax M2.1**: config is auto-written.
+    - More detail: [MiniMax](/providers/minimax)
+    - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.
+    - More detail: [Synthetic](/providers/synthetic)
+    - **Moonshot (Kimi K2)**: config is auto-written.
+    - **Kimi Coding**: config is auto-written.
+    - More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
+    - **Skip**: no auth configured yet.
+    - Pick a default model from detected options (or enter provider/model manually).
+    - Wizard runs a model check and warns if the configured model is unknown or missing auth.
+    - OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
+    - More detail: [/concepts/oauth](/concepts/oauth)
+    <Note>
+    Headless/server tip: complete OAuth on a machine with a browser, then copy
+    `~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`) to the
+    gateway host.
+    </Note>
+  </Step>
+  <Step title="Workspace">
+    - Default `~/.openclaw/workspace` (configurable).
+    - Seeds the workspace files needed for the agent bootstrap ritual.
+    - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
+  </Step>
+  <Step title="Gateway">
+    - Port, bind, auth mode, tailscale exposure.
+    - Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate.
+    - Disable auth only if you fully trust every local process.
+    - Non‑loopback binds still require auth.
+  </Step>
+  <Step title="Channels">
+    - [WhatsApp](/channels/whatsapp): optional QR login.
+    - [Telegram](/channels/telegram): bot token.
+    - [Discord](/channels/discord): bot token.
+    - [Google Chat](/channels/googlechat): service account JSON + webhook audience.
+    - [Mattermost](/channels/mattermost) (plugin): bot token + base URL.
+    - [Signal](/channels/signal): optional `signal-cli` install + account config.
+    - [BlueBubbles](/channels/bluebubbles): **recommended for iMessage**; server URL + password + webhook.
+    - [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access.
+    - DM security: default is pairing. First DM sends a code; approve via `openclaw pairing approve <channel> <code>` or use allowlists.
+  </Step>
+  <Step title="Daemon install">
+    - macOS: LaunchAgent
+      - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
+    - Linux (and Windows via WSL2): systemd user unit
+      - Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
+      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
+    - **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
+  </Step>
+  <Step title="Health check">
+    - Starts the Gateway (if needed) and runs `openclaw health`.
+    - Tip: `openclaw status --deep` adds gateway health probes to status output (requires a reachable gateway).
+  </Step>
+  <Step title="Skills (recommended)">
+    - Reads the available skills and checks requirements.
+    - Lets you choose a node manager: **npm / pnpm** (bun not recommended).
+    - Installs optional dependencies (some use Homebrew on macOS).
+  </Step>
+  <Step title="Finish">
+    - Summary + next steps, including iOS/Android/macOS apps for extra features.
+  </Step>
+</Steps>
+
+<Note>
+If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
+If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
+</Note>
+
+## Non-interactive mode
+
+Use `--non-interactive` to automate or script onboarding:
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --install-daemon \
+  --daemon-runtime node \
+  --skip-skills
+```
+
+Add `--json` for a machine‑readable summary.
+
+<Note>
+`--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
+</Note>
+
+<AccordionGroup>
+  <Accordion title="Gemini example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice gemini-api-key \
+      --gemini-api-key "$GEMINI_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Z.AI example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice zai-api-key \
+      --zai-api-key "$ZAI_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Vercel AI Gateway example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice ai-gateway-api-key \
+      --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Cloudflare AI Gateway example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice cloudflare-ai-gateway-api-key \
+      --cloudflare-ai-gateway-account-id "your-account-id" \
+      --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
+      --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Moonshot example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice moonshot-api-key \
+      --moonshot-api-key "$MOONSHOT_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Synthetic example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice synthetic-api-key \
+      --synthetic-api-key "$SYNTHETIC_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="OpenCode Zen example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice opencode-zen \
+      --opencode-zen-api-key "$OPENCODE_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+</AccordionGroup>
+
+### Add agent (non-interactive)
+
+```bash
+openclaw agents add work \
+  --workspace ~/.openclaw/workspace-work \
+  --model openai/gpt-5.2 \
+  --bind whatsapp:biz \
+  --non-interactive \
+  --json
+```
+
+## Gateway wizard RPC
+
+The Gateway exposes the wizard flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
+Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.
+
+## Signal setup (signal-cli)
+
+The wizard can install `signal-cli` from GitHub releases:
+
+- Downloads the appropriate release asset.
+- Stores it under `~/.openclaw/tools/signal-cli/<version>/`.
+- Writes `channels.signal.cliPath` to your config.
+
+Notes:
+
+- JVM builds require **Java 21**.
+- Native builds are used when available.
+- Windows uses WSL2; signal-cli install follows the Linux flow inside WSL.
+
+## What the wizard writes
+
+Typical fields in `~/.openclaw/openclaw.json`:
+
+- `agents.defaults.workspace`
+- `agents.defaults.model` / `models.providers` (if Minimax chosen)
+- `gateway.*` (mode, bind, auth, tailscale)
+- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
+- Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`openclaw agents add` writes `agents.list[]` and optional `bindings`.
+
+WhatsApp credentials go under `~/.openclaw/credentials/whatsapp/<accountId>/`.
+Sessions are stored under `~/.openclaw/agents/<agentId>/sessions/`.
+
+Some channels are delivered as plugins. When you pick one during onboarding, the wizard
+will prompt to install it (npm or a local path) before it can be configured.
+
+## Related docs
+
+- Wizard overview: [Onboarding Wizard](/start/wizard)
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Config reference: [Gateway configuration](/gateway/configuration)
+- Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Google Chat](/channels/googlechat), [Signal](/channels/signal), [BlueBubbles](/channels/bluebubbles) (iMessage), [iMessage](/channels/imessage) (legacy)
+- Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config)

docs/start/bootstrapping.md

@@ -0,0 +1,41 @@
+---
+summary: "Agent bootstrapping ritual that seeds the workspace and identity files"
+read_when:
+  - Understanding what happens on the first agent run
+  - Explaining where bootstrapping files live
+  - Debugging onboarding identity setup
+title: "Agent Bootstrapping"
+sidebarTitle: "Bootstrapping"
+---
+
+# Agent Bootstrapping
+
+Bootstrapping is the **first‑run** ritual that prepares an agent workspace and
+collects identity details. It happens after onboarding, when the agent starts
+for the first time.
+
+## What bootstrapping does
+
+On the first agent run, OpenClaw bootstraps the workspace (default
+`~/.openclaw/workspace`):
+
+- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
+- Runs a short Q&A ritual (one question at a time).
+- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`.
+- Removes `BOOTSTRAP.md` when finished so it only runs once.
+
+## Where it runs
+
+Bootstrapping always runs on the **gateway host**. If the macOS app connects to
+a remote Gateway, the workspace and bootstrapping files live on that remote
+machine.
+
+<Note>
+When the Gateway runs on another machine, edit workspace files on the gateway
+host (for example, `user@gateway-host:~/.openclaw/workspace`).
+</Note>
+
+## Related docs
+
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Workspace layout: [Agent workspace](/concepts/agent-workspace)

docs/start/docs-directory.md

@@ -6,6 +6,7 @@ title: "Docs directory"
 ---
 
 <Note>
+This page is a curated index. If you are new, start with [Getting Started](/start/getting-started).
 For a complete map of the docs, see [Docs hubs](/start/hubs).
 </Note>
 

docs/start/getting-started.md

@@ -1,208 +1,120 @@
 ---
-summary: "Beginner guide: from zero to first message (wizard, auth, channels, pairing)"
+summary: "Get OpenClaw installed and run your first chat in minutes."
 read_when:
   - First time setup from zero
-  - You want the fastest path from install → onboarding → first message
+  - You want the fastest path to a working chat
 title: "Getting Started"
 ---
 
 # Getting Started
 
-Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible.
+Goal: go from zero to a first working chat with minimal setup.
 
+<Info>
 Fastest chat: open the Control UI (no channel setup needed). Run `openclaw dashboard`
-and chat in the browser, or open `http://127.0.0.1:18789/` on the gateway host.
+and chat in the browser, or open `http://127.0.0.1:18789/` on the
+<Tooltip headline="Gateway host" tip="The machine running the OpenClaw gateway service.">gateway host</Tooltip>.
 Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui).
+</Info>
 
-Recommended path: use the **CLI onboarding wizard** (`openclaw onboard`). It sets up:
+## Prereqs
 
-- model/auth (OAuth recommended)
-- gateway settings
-- channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/...)
-- pairing defaults (secure DMs)
-- workspace bootstrap + skills
-- optional background service
+- Node 22 or newer
 
-If you want the deeper reference pages, jump to: [Wizard](/start/wizard), [Setup](/start/setup), [Pairing](/start/pairing), [Security](/gateway/security).
+<Tip>
+Check your Node version with `node --version` if you are unsure.
+</Tip>
 
-Sandboxing note: `agents.defaults.sandbox.mode: "non-main"` uses `session.mainKey` (default `"main"`),
-so group/channel sessions are sandboxed. If you want the main agent to always
-run on host, set an explicit per-agent override:
+## Quick setup (CLI)
 
-```json
-{
-  "routing": {
-    "agents": {
-      "main": {
-        "workspace": "~/.openclaw/workspace",
-        "sandbox": { "mode": "off" }
-      }
-    }
-  }
-}
-```
+<Steps>
+  <Step title="Install OpenClaw (recommended)">
+    <Tabs>
+      <Tab title="macOS/Linux">
+        ```bash
+        curl -fsSL https://openclaw.ai/install.sh | bash
+        ```
+      </Tab>
+      <Tab title="Windows (PowerShell)">
+        ```powershell
+        iwr -useb https://openclaw.ai/install.ps1 | iex
+        ```
+      </Tab>
+    </Tabs>
 
-## 0) Prereqs
+    <Note>
+    Other install methods and requirements: [Install](/install).
+    </Note>
 
-- Node `>=22`
-- `pnpm` (optional; recommended if you build from source)
-- **Recommended:** Brave Search API key for web search. Easiest path:
-  `openclaw configure --section web` (stores `tools.web.search.apiKey`).
-  See [Web tools](/tools/web).
+  </Step>
+  <Step title="Run the onboarding wizard">
+    ```bash
+    openclaw onboard --install-daemon
+    ```
 
-macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
-Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested, more problematic, and has poorer tool compatibility. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/platforms/windows).
+    The wizard configures auth, gateway settings, and optional channels.
+    See [Onboarding Wizard](/start/wizard) for details.
 
-## 1) Install the CLI (recommended)
+  </Step>
+  <Step title="Check the Gateway">
+    If you installed the service, it should already be running:
 
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash
-```
+    ```bash
+    openclaw gateway status
+    ```
 
-Installer options (install method, non-interactive, from GitHub): [Install](/install).
+  </Step>
+  <Step title="Open the Control UI">
+    ```bash
+    openclaw dashboard
+    ```
+  </Step>
+</Steps>
 
-Windows (PowerShell):
+<Check>
+If the Control UI loads, your Gateway is ready for use.
+</Check>
 
-```powershell
-iwr -useb https://openclaw.ai/install.ps1 | iex
-```
+## Optional checks and extras
 
-Alternative (global install):
+<AccordionGroup>
+  <Accordion title="Run the Gateway in the foreground">
+    Useful for quick tests or troubleshooting.
 
-```bash
-npm install -g openclaw@latest
-```
+    ```bash
+    openclaw gateway --port 18789
+    ```
 
-```bash
-pnpm add -g openclaw@latest
-```
+  </Accordion>
+  <Accordion title="Send a test message">
+    Requires a configured channel.
 
-## 2) Run the onboarding wizard (and install the service)
+    ```bash
+    openclaw message send --target +15555550123 --message "Hello from OpenClaw"
+    ```
 
-```bash
-openclaw onboard --install-daemon
-```
+  </Accordion>
+</AccordionGroup>
 
-What you’ll choose:
+## Go deeper
 
-- **Local vs Remote** gateway
-- **Auth**: OpenAI Code (Codex) subscription (OAuth) or API keys. For Anthropic we recommend an API key; `claude setup-token` is also supported.
-- **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, Mattermost plugin tokens, etc.
-- **Daemon**: background install (launchd/systemd; WSL2 uses systemd)
-  - **Runtime**: Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
-- **Gateway token**: the wizard generates one by default (even on loopback) and stores it in `gateway.auth.token`.
+<Columns>
+  <Card title="Onboarding Wizard (details)" href="/start/wizard">
+    Full CLI wizard reference and advanced options.
+  </Card>
+  <Card title="macOS app onboarding" href="/start/onboarding">
+    First run flow for the macOS app.
+  </Card>
+</Columns>
 
-Wizard doc: [Wizard](/start/wizard)
+## What you will have
 
-### Auth: where it lives (important)
+- A running Gateway
+- Auth configured
+- Control UI access or a connected channel
 
-- **Recommended Anthropic path:** set an API key (wizard can store it for service use). `claude setup-token` is also supported if you want to reuse Claude Code credentials.
+## Next steps
 
-- OAuth credentials (legacy import): `~/.openclaw/credentials/oauth.json`
-- Auth profiles (OAuth + API keys): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
-
-Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host.
-
-## 3) Start the Gateway
-
-If you installed the service during onboarding, the Gateway should already be running:
-
-```bash
-openclaw gateway status
-```
-
-Manual run (foreground):
-
-```bash
-openclaw gateway --port 18789 --verbose
-```
-
-Dashboard (local loopback): `http://127.0.0.1:18789/`
-If a token is configured, paste it into the Control UI settings (stored as `connect.params.auth.token`).
-
-⚠️ **Bun warning (WhatsApp + Telegram):** Bun has known issues with these
-channels. If you use WhatsApp or Telegram, run the Gateway with **Node**.
-
-## 3.5) Quick verify (2 min)
-
-```bash
-openclaw status
-openclaw health
-openclaw security audit --deep
-```
-
-## 4) Pair + connect your first chat surface
-
-### WhatsApp (QR login)
-
-```bash
-openclaw channels login
-```
-
-Scan via WhatsApp → Settings → Linked Devices.
-
-WhatsApp doc: [WhatsApp](/channels/whatsapp)
-
-### Telegram / Discord / others
-
-The wizard can write tokens/config for you. If you prefer manual config, start with:
-
-- Telegram: [Telegram](/channels/telegram)
-- Discord: [Discord](/channels/discord)
-- Mattermost (plugin): [Mattermost](/channels/mattermost)
-
-**Telegram DM tip:** your first DM returns a pairing code. Approve it (see next step) or the bot won’t respond.
-
-## 5) DM safety (pairing approvals)
-
-Default posture: unknown DMs get a short code and messages are not processed until approved.
-If your first DM gets no reply, approve the pairing:
-
-```bash
-openclaw pairing list whatsapp
-openclaw pairing approve whatsapp <code>
-```
-
-Pairing doc: [Pairing](/start/pairing)
-
-## From source (development)
-
-If you’re hacking on OpenClaw itself, run from source:
-
-```bash
-git clone https://github.com/openclaw/openclaw.git
-cd openclaw
-pnpm install
-pnpm ui:build # auto-installs UI deps on first run
-pnpm build
-openclaw onboard --install-daemon
-```
-
-If you don’t have a global install yet, run the onboarding step via `pnpm openclaw ...` from the repo.
-`pnpm build` also bundles A2UI assets; if you need to run just that step, use `pnpm canvas:a2ui:bundle`.
-
-Gateway (from this repo):
-
-```bash
-node openclaw.mjs gateway --port 18789 --verbose
-```
-
-## 7) Verify end-to-end
-
-In a new terminal, send a test message:
-
-```bash
-openclaw message send --target +15555550123 --message "Hello from OpenClaw"
-```
-
-If `openclaw health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.
-
-Tip: `openclaw status --all` is the best pasteable, read-only debug report.
-Health probes: `openclaw health` (or `openclaw status --deep`) asks the running gateway for a health snapshot.
-
-## Next steps (optional, but great)
-
-- macOS menu bar app + voice wake: [macOS app](/platforms/macos)
-- iOS/Android nodes (Canvas/camera/voice): [Nodes](/nodes)
-- Remote access (SSH tunnel / Tailscale Serve): [Remote access](/gateway/remote) and [Tailscale](/gateway/tailscale)
-- Always-on / VPN setups: [Remote access](/gateway/remote), [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [macOS remote](/platforms/mac/remote)
+- DM safety and approvals: [Pairing](/start/pairing)
+- Connect more channels: [Channels](/channels)
+- Advanced workflows and from source: [Setup](/start/setup)

docs/start/hubs.md

@@ -7,6 +7,10 @@ title: "Docs Hubs"
 
 # Docs hubs
 
+<Note>
+If you are new to OpenClaw, start with [Getting Started](/start/getting-started).
+</Note>
+
 Use these hubs to discover every page, including deep dives and reference docs that don’t appear in the left nav.
 
 ## Start here

docs/start/onboarding.md

@@ -3,108 +3,78 @@ summary: "First-run onboarding flow for OpenClaw (macOS app)"
 read_when:
   - Designing the macOS onboarding assistant
   - Implementing auth or identity setup
-title: "Onboarding"
+title: "Onboarding (macOS App)"
+sidebarTitle: "Onboarding: macOS App"
 ---
 
-# Onboarding (macOS app)
+# Onboarding (macOS App)
 
 This doc describes the **current** first‑run onboarding 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.
 
-## Page order (current)
-
-1. Welcome + security notice
-2. **Gateway selection** (Local / Remote / Configure later)
-3. **Auth (Anthropic OAuth)** — local only
-4. **Setup Wizard** (Gateway‑driven)
-5. **Permissions** (TCC prompts)
-6. **CLI** (optional)
-7. **Onboarding chat** (dedicated session)
-8. Ready
-
-## 1) Welcome + security notice
-
-Read the security notice displayed and decide accordingly.
-
-## 2) Local vs Remote
+<Steps>
+<Step title="Approve macOS warning">
+<Frame>
+<img src="/assets/macos-onboarding/01-macos-warning.jpeg" alt="" />
+</Frame>
+</Step>
+<Step title="Approve find local networks">
+<Frame>
+<img src="/assets/macos-onboarding/02-local-networks.jpeg" alt="" />
+</Frame>
+</Step>
+<Step title="Welcome and security notice">
+<Frame caption="Read the security notice displayed and decide accordingly">
+<img src="/assets/macos-onboarding/03-security-notice.png" alt="" />
+</Frame>
+</Step>
+<Step title="Local vs Remote">
+<Frame>
+<img src="/assets/macos-onboarding/04-choose-gateway.png" alt="" />
+</Frame>
 
 Where does the **Gateway** run?
 
-- **Local (this Mac):** onboarding can run OAuth flows and write credentials
+- **This Mac (Local only):** onboarding can run OAuth flows and write credentials
   locally.
 - **Remote (over SSH/Tailnet):** onboarding does **not** run OAuth locally;
   credentials must exist on the gateway host.
 - **Configure later:** skip setup and leave the app unconfigured.
 
-Gateway auth tip:
-
+<Tip>
+**Gateway auth tip:**
 - 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.
-
-## 3) Local-only auth (Anthropic OAuth)
-
-The macOS app supports Anthropic OAuth (Claude Pro/Max). The flow:
-
-- Opens the browser for OAuth (PKCE)
-- Asks the user to paste the `code#state` value
-- Writes credentials to `~/.openclaw/credentials/oauth.json`
-
-Other providers (OpenAI, custom APIs) are configured via environment variables
-or config files for now.
-
-## 4) Setup Wizard (Gateway‑driven)
-
-The app can run the same setup wizard as the CLI. This keeps onboarding in sync
-with Gateway‑side behavior and avoids duplicating logic in SwiftUI.
-
-## 5) Permissions
+</Tip>
+</Step>
+<Step title="Permissions">
+<Frame caption="Choose what permissions do you want to give OpenClaw">
+<img src="/assets/macos-onboarding/05-permissions.png" alt="" />
+</Frame>
 
 Onboarding requests TCC permissions needed for:
 
+- Automation (AppleScript)
 - Notifications
 - Accessibility
 - Screen Recording
-- Microphone / Speech Recognition
-- Automation (AppleScript)
+- Microphone
+- Speech Recognition
+- Camera
+- Location
 
-## 6) CLI (optional)
-
-The app can install the global `openclaw` CLI via npm/pnpm so terminal
-workflows and launchd tasks work out of the box.
-
-## 7) 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
-from your normal conversation.
-
-## Agent bootstrap ritual
-
-On the first agent run, OpenClaw bootstraps a workspace (default `~/.openclaw/workspace`):
-
-- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`
-- Runs a short Q&A ritual (one question at a time)
-- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`
-- Removes `BOOTSTRAP.md` when finished so it only runs once
-
-## Optional: Gmail hooks (manual)
-
-Gmail Pub/Sub setup is currently a manual step. Use:
-
-```bash
-openclaw webhooks gmail setup --account you@gmail.com
-```
-
-See [/automation/gmail-pubsub](/automation/gmail-pubsub) for details.
-
-## Remote mode notes
-
-When the Gateway runs on another machine, credentials and workspace files live
-**on that host**. If you need OAuth in remote mode, create:
-
-- `~/.openclaw/credentials/oauth.json`
-- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
-
-on the gateway host.
+</Step>
+<Step title="CLI">
+  <Info>This step is optional</Info>
+  The app can install the global `openclaw` CLI via npm/pnpm so terminal
+  workflows and launchd tasks work out of the box.
+</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
+  from your normal conversation. See [Bootstrapping](/start/bootstrapping) for
+  what happens on the gateway host during the first agent run.
+</Step>
+</Steps>

docs/start/openclaw.md

@@ -26,26 +26,9 @@ Start conservative:
 
 ## Prerequisites
 
-- Node **22+**
-- OpenClaw available on PATH (recommended: global install)
+- OpenClaw installed and onboarded — see [Getting Started](/start/getting-started) if you haven't done this yet
 - A second phone number (SIM/eSIM/prepaid) for the assistant
 
-```bash
-npm install -g openclaw@latest
-# or: pnpm add -g openclaw@latest
-```
-
-From source (development):
-
-```bash
-git clone https://github.com/openclaw/openclaw.git
-cd openclaw
-pnpm install
-pnpm ui:build # auto-installs UI deps on first run
-pnpm build
-pnpm link --global
-```
-
 ## The two-phone setup (recommended)
 
 You want this:
@@ -91,7 +74,7 @@ openclaw gateway --port 18789
 
 Now message the assistant number from your allowlisted phone.
 
-When onboarding finishes, we auto-open the dashboard with your gateway token and print the tokenized link. To reopen later: `openclaw dashboard`.
+When onboarding finishes, we auto-open the dashboard and print a clean (non-tokenized) link. If it prompts for auth, paste the token from `gateway.auth.token` into Control UI settings. To reopen later: `openclaw dashboard`.
 
 ## Give the agent a workspace (AGENTS)
 
@@ -142,7 +125,7 @@ Example:
 {
   logging: { level: "info" },
   agent: {
-    model: "anthropic/claude-opus-4-5",
+    model: "anthropic/claude-opus-4-6",
     workspace: "~/.openclaw/workspace",
     thinkingDefault: "high",
     timeoutSeconds: 1800,

docs/start/quickstart.md

@@ -1,81 +1,22 @@
 ---
-summary: "Install OpenClaw, onboard the Gateway, and pair your first channel."
+summary: "Quick start has moved to Getting Started."
 read_when:
-  - You want the fastest path from install to a working Gateway
+  - You are looking for the fastest setup steps
+  - You were sent here from an older link
 title: "Quick start"
 ---
 
-<Note>
-OpenClaw requires Node 22 or newer.
-</Note>
-
-## Install
-
-<Tabs>
-  <Tab title="npm">
-    ```bash
-    npm install -g openclaw@latest
-    ```
-  </Tab>
-  <Tab title="pnpm">
-    ```bash
-    pnpm add -g openclaw@latest
-    ```
-  </Tab>
-</Tabs>
-
-## Onboard and run the Gateway
-
-<Steps>
-  <Step title="Onboard and install the service">
-    ```bash
-    openclaw onboard --install-daemon
-    ```
-  </Step>
-  <Step title="Pair WhatsApp">
-    ```bash
-    openclaw channels login
-    ```
-  </Step>
-  <Step title="Start the Gateway">
-    ```bash
-    openclaw gateway --port 18789
-    ```
-  </Step>
-</Steps>
-
-After onboarding, the Gateway runs via the user service. You can still run it manually with `openclaw gateway`.
+# Quick start
 
 <Info>
-Switching between npm and git installs later is easy. Install the other flavor and run
-`openclaw doctor` to update the gateway service entrypoint.
+Quick start is now part of [Getting Started](/start/getting-started).
 </Info>
 
-## From source (development)
-
-```bash
-git clone https://github.com/openclaw/openclaw.git
-cd openclaw
-pnpm install
-pnpm ui:build # auto-installs UI deps on first run
-pnpm build
-openclaw onboard --install-daemon
-```
-
-If you do not have a global install yet, run onboarding via `pnpm openclaw ...` from the repo.
-
-## Multi instance quickstart (optional)
-
-```bash
-OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
-OPENCLAW_STATE_DIR=~/.openclaw-a \
-openclaw gateway --port 19001
-```
-
-## Send a test message
-
-Requires a running Gateway.
-
-```bash
-openclaw message send --target +15555550123 --message "Hello from OpenClaw"
-```
+<Columns>
+  <Card title="Getting Started" href="/start/getting-started">
+    Install OpenClaw and run your first chat in minutes.
+  </Card>
+  <Card title="Onboarding Wizard" href="/start/wizard">
+    Full CLI wizard reference and advanced options.
+  </Card>
+</Columns>

docs/start/setup.md

@@ -1,5 +1,5 @@
 ---
-summary: "Setup guide: keep your OpenClaw setup tailored while staying up-to-date"
+summary: "Advanced setup and development workflows for OpenClaw"
 read_when:
   - Setting up a new machine
   - You want “latest + greatest” without breaking your personal setup
@@ -8,6 +8,11 @@ title: "Setup"
 
 # Setup
 
+<Note>
+If you are setting up for the first time, start with [Getting Started](/start/getting-started).
+For wizard details, see [Onboarding Wizard](/start/wizard).
+</Note>
+
 Last updated: 2026-01-01
 
 ## TL;DR
@@ -43,6 +48,14 @@ openclaw setup
 
 If you don’t have a global install yet, run it via `pnpm openclaw setup`.
 
+## Run the Gateway from this repo
+
+After `pnpm build`, you can run the packaged CLI directly:
+
+```bash
+node openclaw.mjs gateway --port 18789 --verbose
+```
+
 ## Stable workflow (macOS app first)
 
 1. Install + launch **OpenClaw.app** (menu bar).

docs/start/wizard-cli-automation.md

@@ -0,0 +1,141 @@
+---
+summary: "Scripted onboarding and agent setup for the OpenClaw CLI"
+read_when:
+  - You are automating onboarding in scripts or CI
+  - You need non-interactive examples for specific providers
+title: "CLI Automation"
+sidebarTitle: "CLI automation"
+---
+
+# CLI Automation
+
+Use `--non-interactive` to automate `openclaw onboard`.
+
+<Note>
+`--json` does not imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
+</Note>
+
+## Baseline non-interactive example
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --install-daemon \
+  --daemon-runtime node \
+  --skip-skills
+```
+
+Add `--json` for a machine-readable summary.
+
+## Provider-specific examples
+
+<AccordionGroup>
+  <Accordion title="Gemini example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice gemini-api-key \
+      --gemini-api-key "$GEMINI_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Z.AI example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice zai-api-key \
+      --zai-api-key "$ZAI_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Vercel AI Gateway example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice ai-gateway-api-key \
+      --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Cloudflare AI Gateway example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice cloudflare-ai-gateway-api-key \
+      --cloudflare-ai-gateway-account-id "your-account-id" \
+      --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
+      --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Moonshot example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice moonshot-api-key \
+      --moonshot-api-key "$MOONSHOT_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Synthetic example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice synthetic-api-key \
+      --synthetic-api-key "$SYNTHETIC_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="OpenCode Zen example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice opencode-zen \
+      --opencode-zen-api-key "$OPENCODE_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Add another agent
+
+Use `openclaw agents add <name>` to create a separate agent with its own workspace,
+sessions, and auth profiles. Running without `--workspace` launches the wizard.
+
+```bash
+openclaw agents add work \
+  --workspace ~/.openclaw/workspace-work \
+  --model openai/gpt-5.2 \
+  --bind whatsapp:biz \
+  --non-interactive \
+  --json
+```
+
+What it sets:
+
+- `agents.list[].name`
+- `agents.list[].workspace`
+- `agents.list[].agentDir`
+
+Notes:
+
+- Default workspaces follow `~/.openclaw/workspace-<agentId>`.
+- Add `bindings` to route inbound messages (the wizard can do this).
+- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
+
+## Related docs
+
+- Onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
+- Full reference: [CLI Onboarding Reference](/start/wizard-cli-reference)
+- Command reference: [`openclaw onboard`](/cli/onboard)

docs/start/wizard-cli-reference.md

@@ -0,0 +1,244 @@
+---
+summary: "Complete reference for CLI onboarding flow, auth/model setup, outputs, and internals"
+read_when:
+  - You need detailed behavior for openclaw onboard
+  - You are debugging onboarding results or integrating onboarding clients
+title: "CLI Onboarding Reference"
+sidebarTitle: "CLI reference"
+---
+
+# CLI Onboarding Reference
+
+This page is the full reference for `openclaw onboard`.
+For the short guide, see [Onboarding Wizard (CLI)](/start/wizard).
+
+## What the wizard does
+
+Local mode (default) walks you through:
+
+- Model and auth setup (OpenAI Code subscription OAuth, Anthropic API key or setup token, plus MiniMax, GLM, Moonshot, and AI Gateway options)
+- Workspace location and bootstrap files
+- Gateway settings (port, bind, auth, tailscale)
+- Channels and providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost plugin, Signal)
+- Daemon install (LaunchAgent or systemd user unit)
+- Health check
+- Skills setup
+
+Remote mode configures this machine to connect to a gateway elsewhere.
+It does not install or modify anything on the remote host.
+
+## Local flow details
+
+<Steps>
+  <Step title="Existing config detection">
+    - If `~/.openclaw/openclaw.json` exists, choose Keep, Modify, or Reset.
+    - Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass `--reset`).
+    - If config is invalid or contains legacy keys, the wizard stops and asks you to run `openclaw doctor` before continuing.
+    - Reset uses `trash` and offers scopes:
+      - Config only
+      - Config + credentials + sessions
+      - Full reset (also removes workspace)
+  </Step>
+  <Step title="Model and auth">
+    - Full option matrix is in [Auth and model options](#auth-and-model-options).
+  </Step>
+  <Step title="Workspace">
+    - Default `~/.openclaw/workspace` (configurable).
+    - Seeds workspace files needed for first-run bootstrap ritual.
+    - Workspace layout: [Agent workspace](/concepts/agent-workspace).
+  </Step>
+  <Step title="Gateway">
+    - Prompts for port, bind, auth mode, and tailscale exposure.
+    - Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
+    - Disable auth only if you fully trust every local process.
+    - Non-loopback binds still require auth.
+  </Step>
+  <Step title="Channels">
+    - [WhatsApp](/channels/whatsapp): optional QR login
+    - [Telegram](/channels/telegram): bot token
+    - [Discord](/channels/discord): bot token
+    - [Google Chat](/channels/googlechat): service account JSON + webhook audience
+    - [Mattermost](/channels/mattermost) plugin: bot token + base URL
+    - [Signal](/channels/signal): optional `signal-cli` install + account config
+    - [BlueBubbles](/channels/bluebubbles): recommended for iMessage; server URL + password + webhook
+    - [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access
+    - DM security: default is pairing. First DM sends a code; approve via
+      `openclaw pairing approve <channel> <code>` or use allowlists.
+  </Step>
+  <Step title="Daemon install">
+    - macOS: LaunchAgent
+      - Requires logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
+    - Linux and Windows via WSL2: systemd user unit
+      - Wizard attempts `loginctl enable-linger <user>` so gateway stays up after logout.
+      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
+    - Runtime selection: Node (recommended; required for WhatsApp and Telegram). Bun is not recommended.
+  </Step>
+  <Step title="Health check">
+    - Starts gateway (if needed) and runs `openclaw health`.
+    - `openclaw status --deep` adds gateway health probes to status output.
+  </Step>
+  <Step title="Skills">
+    - Reads available skills and checks requirements.
+    - Lets you choose node manager: npm or pnpm (bun not recommended).
+    - Installs optional dependencies (some use Homebrew on macOS).
+  </Step>
+  <Step title="Finish">
+    - Summary and next steps, including iOS, Android, and macOS app options.
+  </Step>
+</Steps>
+
+<Note>
+If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
+If Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
+</Note>
+
+## Remote mode details
+
+Remote mode configures this machine to connect to a gateway elsewhere.
+
+<Info>
+Remote mode does not install or modify anything on the remote host.
+</Info>
+
+What you set:
+
+- Remote gateway URL (`ws://...`)
+- Token if remote gateway auth is required (recommended)
+
+<Note>
+- If gateway is loopback-only, use SSH tunneling or a tailnet.
+- Discovery hints:
+  - macOS: Bonjour (`dns-sd`)
+  - Linux: Avahi (`avahi-browse`)
+</Note>
+
+## Auth and model options
+
+<AccordionGroup>
+  <Accordion title="Anthropic API key (recommended)">
+    Uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
+  </Accordion>
+  <Accordion title="Anthropic OAuth (Claude Code CLI)">
+    - macOS: checks Keychain item "Claude Code-credentials"
+    - Linux and Windows: reuses `~/.claude/.credentials.json` if present
+
+    On macOS, choose "Always Allow" so launchd starts do not block.
+
+  </Accordion>
+  <Accordion title="Anthropic token (setup-token paste)">
+    Run `claude setup-token` on any machine, then paste the token.
+    You can name it; blank uses default.
+  </Accordion>
+  <Accordion title="OpenAI Code subscription (Codex CLI reuse)">
+    If `~/.codex/auth.json` exists, the wizard can reuse it.
+  </Accordion>
+  <Accordion title="OpenAI Code subscription (OAuth)">
+    Browser flow; paste `code#state`.
+
+    Sets `agents.defaults.model` to `openai-codex/gpt-5.3-codex` when model is unset or `openai/*`.
+
+  </Accordion>
+  <Accordion title="OpenAI API key">
+    Uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to
+    `~/.openclaw/.env` so launchd can read it.
+
+    Sets `agents.defaults.model` to `openai/gpt-5.1-codex` when model is unset, `openai/*`, or `openai-codex/*`.
+
+  </Accordion>
+  <Accordion title="OpenCode Zen">
+    Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`).
+    Setup URL: [opencode.ai/auth](https://opencode.ai/auth).
+  </Accordion>
+  <Accordion title="API key (generic)">
+    Stores the key for you.
+  </Accordion>
+  <Accordion title="Vercel AI Gateway">
+    Prompts for `AI_GATEWAY_API_KEY`.
+    More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway).
+  </Accordion>
+  <Accordion title="Cloudflare AI Gateway">
+    Prompts for account ID, gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
+    More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway).
+  </Accordion>
+  <Accordion title="MiniMax M2.1">
+    Config is auto-written.
+    More detail: [MiniMax](/providers/minimax).
+  </Accordion>
+  <Accordion title="Synthetic (Anthropic-compatible)">
+    Prompts for `SYNTHETIC_API_KEY`.
+    More detail: [Synthetic](/providers/synthetic).
+  </Accordion>
+  <Accordion title="Moonshot and Kimi Coding">
+    Moonshot (Kimi K2) and Kimi Coding configs are auto-written.
+    More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot).
+  </Accordion>
+  <Accordion title="Skip">
+    Leaves auth unconfigured.
+  </Accordion>
+</AccordionGroup>
+
+Model behavior:
+
+- Pick default model from detected options, or enter provider and model manually.
+- Wizard runs a model check and warns if the configured model is unknown or missing auth.
+
+Credential and profile paths:
+
+- OAuth credentials: `~/.openclaw/credentials/oauth.json`
+- Auth profiles (API keys + OAuth): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+
+<Note>
+Headless and server tip: complete OAuth on a machine with a browser, then copy
+`~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`)
+to the gateway host.
+</Note>
+
+## Outputs and internals
+
+Typical fields in `~/.openclaw/openclaw.json`:
+
+- `agents.defaults.workspace`
+- `agents.defaults.model` / `models.providers` (if Minimax chosen)
+- `gateway.*` (mode, bind, auth, tailscale)
+- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
+- Channel allowlists (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible)
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`openclaw agents add` writes `agents.list[]` and optional `bindings`.
+
+WhatsApp credentials go under `~/.openclaw/credentials/whatsapp/<accountId>/`.
+Sessions are stored under `~/.openclaw/agents/<agentId>/sessions/`.
+
+<Note>
+Some channels are delivered as plugins. When selected during onboarding, the wizard
+prompts to install the plugin (npm or local path) before channel configuration.
+</Note>
+
+Gateway wizard RPC:
+
+- `wizard.start`
+- `wizard.next`
+- `wizard.cancel`
+- `wizard.status`
+
+Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.
+
+Signal setup behavior:
+
+- Downloads the appropriate release asset
+- Stores it under `~/.openclaw/tools/signal-cli/<version>/`
+- Writes `channels.signal.cliPath` in config
+- JVM builds require Java 21
+- Native builds are used when available
+- Windows uses WSL2 and follows Linux signal-cli flow inside WSL
+
+## Related docs
+
+- Onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
+- Automation and scripts: [CLI Automation](/start/wizard-cli-automation)
+- Command reference: [`openclaw onboard`](/cli/onboard)

docs/start/wizard.md

@@ -3,7 +3,8 @@ summary: "CLI onboarding wizard: guided setup for gateway, workspace, channels,
 read_when:
   - Running or configuring the onboarding wizard
   - Setting up a new machine
-title: "Onboarding Wizard"
+title: "Onboarding Wizard (CLI)"
+sidebarTitle: "Onboarding: CLI"
 ---
 
 # Onboarding Wizard (CLI)
@@ -13,166 +14,70 @@ Linux, or Windows (via WSL2; strongly recommended).
 It configures a local Gateway or a remote Gateway connection, plus channels, skills,
 and workspace defaults in one guided flow.
 
-Primary entrypoint:
-
 ```bash
 openclaw onboard
 ```
 
+<Info>
 Fastest first chat: open the Control UI (no channel setup needed). Run
 `openclaw dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).
+</Info>
 
-Follow‑up reconfiguration:
+To reconfigure later:
 
 ```bash
 openclaw configure
+openclaw agents add <name>
 ```
 
+<Note>
+`--json` does not imply non-interactive mode. For scripts, use `--non-interactive`.
+</Note>
+
+<Tip>
 Recommended: set up a Brave Search API key so the agent can use `web_search`
 (`web_fetch` works without a key). Easiest path: `openclaw configure --section web`
 which stores `tools.web.search.apiKey`. Docs: [Web tools](/tools/web).
+</Tip>
 
 ## QuickStart vs Advanced
 
 The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
 
-**QuickStart** keeps the defaults:
+<Tabs>
+  <Tab title="QuickStart (defaults)">
+    - Local gateway (loopback)
+    - Workspace default (or existing workspace)
+    - Gateway port **18789**
+    - Gateway auth **Token** (auto‑generated, even on loopback)
+    - Tailscale exposure **Off**
+    - Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)
+  </Tab>
+  <Tab title="Advanced (full control)">
+    - Exposes every step (mode, workspace, gateway, channels, daemon, skills).
+  </Tab>
+</Tabs>
 
-- Local gateway (loopback)
-- Workspace default (or existing workspace)
-- Gateway port **18789**
-- Gateway auth **Token** (auto‑generated, even on loopback)
-- Tailscale exposure **Off**
-- Telegram + WhatsApp DMs default to **allowlist** (you’ll be prompted for your phone number)
+## What the wizard configures
 
-**Advanced** exposes every step (mode, workspace, gateway, channels, daemon, skills).
+**Local mode (default)** walks you through these steps:
 
-## What the wizard does
+1. **Model/Auth** — Anthropic API key (recommended), OAuth, OpenAI, or other providers. Pick a default model.
+2. **Workspace** — Location for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files.
+3. **Gateway** — Port, bind address, auth mode, Tailscale exposure.
+4. **Channels** — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, or iMessage.
+5. **Daemon** — Installs a LaunchAgent (macOS) or systemd user unit (Linux/WSL2).
+6. **Health check** — Starts the Gateway and verifies it's running.
+7. **Skills** — Installs recommended skills and optional dependencies.
 
-**Local mode (default)** walks you through:
-
-- Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or setup-token (paste), plus MiniMax/GLM/Moonshot/AI Gateway options)
-- Workspace location + bootstrap files
-- Gateway settings (port/bind/auth/tailscale)
-- Providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost (plugin), Signal)
-- Daemon install (LaunchAgent / systemd user unit)
-- Health check
-- Skills (recommended)
+<Note>
+Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`).
+If the config is invalid or contains legacy keys, the wizard asks you to run `openclaw doctor` first.
+</Note>
 
 **Remote mode** only configures the local client to connect to a Gateway elsewhere.
 It does **not** install or change anything on the remote host.
 
-To add more isolated agents (separate workspace + sessions + auth), use:
-
-```bash
-openclaw agents add <name>
-```
-
-Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
-
-## Flow details (local)
-
-1. **Existing config detection**
-   - If `~/.openclaw/openclaw.json` exists, choose **Keep / Modify / Reset**.
-   - Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset**
-     (or pass `--reset`).
-   - If the config is invalid or contains legacy keys, the wizard stops and asks
-     you to run `openclaw doctor` before continuing.
-   - Reset uses `trash` (never `rm`) and offers scopes:
-     - Config only
-     - Config + credentials + sessions
-     - Full reset (also removes workspace)
-
-2. **Model/Auth**
-   - **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
-   - **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present.
-   - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default).
-   - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it.
-   - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
-     - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
-   - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.openclaw/.env` so launchd can read it.
-   - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth).
-   - **API key**: stores the key for you.
-   - **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.
-   - More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway)
-   - **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
-   - More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
-   - **MiniMax M2.1**: config is auto-written.
-   - More detail: [MiniMax](/providers/minimax)
-   - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.
-   - More detail: [Synthetic](/providers/synthetic)
-   - **Moonshot (Kimi K2)**: config is auto-written.
-   - **Kimi Coding**: config is auto-written.
-   - More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
-   - **Skip**: no auth configured yet.
-   - Pick a default model from detected options (or enter provider/model manually).
-   - Wizard runs a model check and warns if the configured model is unknown or missing auth.
-
-- OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
-- More detail: [/concepts/oauth](/concepts/oauth)
-
-3. **Workspace**
-   - Default `~/.openclaw/workspace` (configurable).
-   - Seeds the workspace files needed for the agent bootstrap ritual.
-   - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
-
-4. **Gateway**
-   - Port, bind, auth mode, tailscale exposure.
-   - Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate.
-   - Disable auth only if you fully trust every local process.
-   - Non‑loopback binds still require auth.
-
-5. **Channels**
-   - [WhatsApp](/channels/whatsapp): optional QR login.
-   - [Telegram](/channels/telegram): bot token.
-   - [Discord](/channels/discord): bot token.
-   - [Google Chat](/channels/googlechat): service account JSON + webhook audience.
-   - [Mattermost](/channels/mattermost) (plugin): bot token + base URL.
-   - [Signal](/channels/signal): optional `signal-cli` install + account config.
-   - [BlueBubbles](/channels/bluebubbles): **recommended for iMessage**; server URL + password + webhook.
-   - [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access.
-   - DM security: default is pairing. First DM sends a code; approve via `openclaw pairing approve <channel> <code>` or use allowlists.
-
-6. **Daemon install**
-   - macOS: LaunchAgent
-     - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
-   - Linux (and Windows via WSL2): systemd user unit
-     - Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
-     - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
-   - **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
-
-7. **Health check**
-   - Starts the Gateway (if needed) and runs `openclaw health`.
-   - Tip: `openclaw status --deep` adds gateway health probes to status output (requires a reachable gateway).
-
-8. **Skills (recommended)**
-   - Reads the available skills and checks requirements.
-   - Lets you choose a node manager: **npm / pnpm** (bun not recommended).
-   - Installs optional dependencies (some use Homebrew on macOS).
-
-9. **Finish**
-   - Summary + next steps, including iOS/Android/macOS apps for extra features.
-
-- If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
-- If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
-
-## Remote mode
-
-Remote mode configures a local client to connect to a Gateway elsewhere.
-
-What you’ll set:
-
-- Remote Gateway URL (`ws://...`)
-- Token if the remote Gateway requires auth (recommended)
-
-Notes:
-
-- No remote installs or daemon changes are performed.
-- If the Gateway is loopback‑only, use SSH tunneling or a tailnet.
-- Discovery hints:
-  - macOS: Bonjour (`dns-sd`)
-  - Linux: Avahi (`avahi-browse`)
-
 ## Add another agent
 
 Use `openclaw agents add <name>` to create a separate agent with its own workspace,
@@ -190,160 +95,14 @@ Notes:
 - Add `bindings` to route inbound messages (the wizard can do this).
 - Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
 
-## Non‑interactive mode
+## Full reference
 
-Use `--non-interactive` to automate or script onboarding:
-
-```bash
-openclaw onboard --non-interactive \
-  --mode local \
-  --auth-choice apiKey \
-  --anthropic-api-key "$ANTHROPIC_API_KEY" \
-  --gateway-port 18789 \
-  --gateway-bind loopback \
-  --install-daemon \
-  --daemon-runtime node \
-  --skip-skills
-```
-
-Add `--json` for a machine‑readable summary.
-
-Gemini example:
-
-```bash
-openclaw onboard --non-interactive \
-  --mode local \
-  --auth-choice gemini-api-key \
-  --gemini-api-key "$GEMINI_API_KEY" \
-  --gateway-port 18789 \
-  --gateway-bind loopback
-```
-
-Z.AI example:
-
-```bash
-openclaw onboard --non-interactive \
-  --mode local \
-  --auth-choice zai-api-key \
-  --zai-api-key "$ZAI_API_KEY" \
-  --gateway-port 18789 \
-  --gateway-bind loopback
-```
-
-Vercel AI Gateway example:
-
-```bash
-openclaw onboard --non-interactive \
-  --mode local \
-  --auth-choice ai-gateway-api-key \
-  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
-  --gateway-port 18789 \
-  --gateway-bind loopback
-```
-
-Cloudflare AI Gateway example:
-
-```bash
-openclaw onboard --non-interactive \
-  --mode local \
-  --auth-choice cloudflare-ai-gateway-api-key \
-  --cloudflare-ai-gateway-account-id "your-account-id" \
-  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
-  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
-  --gateway-port 18789 \
-  --gateway-bind loopback
-```
-
-Moonshot example:
-
-```bash
-openclaw onboard --non-interactive \
-  --mode local \
-  --auth-choice moonshot-api-key \
-  --moonshot-api-key "$MOONSHOT_API_KEY" \
-  --gateway-port 18789 \
-  --gateway-bind loopback
-```
-
-Synthetic example:
-
-```bash
-openclaw onboard --non-interactive \
-  --mode local \
-  --auth-choice synthetic-api-key \
-  --synthetic-api-key "$SYNTHETIC_API_KEY" \
-  --gateway-port 18789 \
-  --gateway-bind loopback
-```
-
-OpenCode Zen example:
-
-```bash
-openclaw onboard --non-interactive \
-  --mode local \
-  --auth-choice opencode-zen \
-  --opencode-zen-api-key "$OPENCODE_API_KEY" \
-  --gateway-port 18789 \
-  --gateway-bind loopback
-```
-
-Add agent (non‑interactive) example:
-
-```bash
-openclaw agents add work \
-  --workspace ~/.openclaw/workspace-work \
-  --model openai/gpt-5.2 \
-  --bind whatsapp:biz \
-  --non-interactive \
-  --json
-```
-
-## Gateway wizard RPC
-
-The Gateway exposes the wizard flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
-Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.
-
-## Signal setup (signal-cli)
-
-The wizard can install `signal-cli` from GitHub releases:
-
-- Downloads the appropriate release asset.
-- Stores it under `~/.openclaw/tools/signal-cli/<version>/`.
-- Writes `channels.signal.cliPath` to your config.
-
-Notes:
-
-- JVM builds require **Java 21**.
-- Native builds are used when available.
-- Windows uses WSL2; signal-cli install follows the Linux flow inside WSL.
-
-## What the wizard writes
-
-Typical fields in `~/.openclaw/openclaw.json`:
-
-- `agents.defaults.workspace`
-- `agents.defaults.model` / `models.providers` (if Minimax chosen)
-- `gateway.*` (mode, bind, auth, tailscale)
-- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
-- Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).
-- `skills.install.nodeManager`
-- `wizard.lastRunAt`
-- `wizard.lastRunVersion`
-- `wizard.lastRunCommit`
-- `wizard.lastRunCommand`
-- `wizard.lastRunMode`
-
-`openclaw agents add` writes `agents.list[]` and optional `bindings`.
-
-WhatsApp credentials go under `~/.openclaw/credentials/whatsapp/<accountId>/`.
-Sessions are stored under `~/.openclaw/agents/<agentId>/sessions/`.
-
-Some channels are delivered as plugins. When you pick one during onboarding, the wizard
-will prompt to install it (npm or a local path) before it can be configured.
+For detailed step-by-step breakdowns, non-interactive scripting, Signal setup,
+RPC API, and a full list of config fields the wizard writes, see the
+[Wizard Reference](/reference/wizard).
 
 ## Related docs
 
+- CLI command reference: [`openclaw onboard`](/cli/onboard)
 - macOS app onboarding: [Onboarding](/start/onboarding)
-- Config reference: [Gateway configuration](/gateway/configuration)
-- Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Google Chat](/channels/googlechat), [Signal](/channels/signal), [BlueBubbles](/channels/bluebubbles) (iMessage), [iMessage](/channels/imessage) (legacy)
-- Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config)
+- Agent first-run ritual: [Agent Bootstrapping](/start/bootstrapping)

docs/style.css

@@ -0,0 +1,3 @@
+#content > h1:first-of-type {
+  display: none !important;
+}

docs/testing.md

@@ -110,7 +110,7 @@ Live tests are split into two layers so we can isolate failures:
 - How to select models:
   - `OPENCLAW_LIVE_MODELS=modern` to run the modern allowlist (Opus/Sonnet/Haiku 4.5, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.1, Grok 4)
   - `OPENCLAW_LIVE_MODELS=all` is an alias for the modern allowlist
-  - or `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,..."` (comma allowlist)
+  - or `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,..."` (comma allowlist)
 - How to select providers:
   - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (comma allowlist)
 - Where keys come from:
@@ -172,7 +172,7 @@ openclaw models list --json
   - Profile: `OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test`
   - Raw token: `OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...`
 - Model override (optional):
-  - `OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-5`
+  - `OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-6`
 
 Setup example:
 
@@ -193,8 +193,8 @@ OPENCLAW_LIVE_SETUP_TOKEN=1 OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-to
   - Command: `claude`
   - Args: `["-p","--output-format","json","--dangerously-skip-permissions"]`
 - Overrides (optional):
-  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-5"`
-  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2-codex"`
+  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-6"`
+  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.3-codex"`
   - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"`
   - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","json","--permission-mode","bypassPermissions"]'`
   - `OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'`
@@ -223,7 +223,7 @@ Narrow, explicit allowlists are fastest and least flaky:
   - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
 
 - Tool calling across several providers:
-  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-flash-preview,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
 
 - Google focus (Gemini API key + Antigravity):
   - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
@@ -247,22 +247,22 @@ There is no fixed “CI model list” (live is opt-in), but these are the **reco
 This is the “common models” run we expect to keep working:
 
 - OpenAI (non-Codex): `openai/gpt-5.2` (optional: `openai/gpt-5.1`)
-- OpenAI Codex: `openai-codex/gpt-5.2` (optional: `openai-codex/gpt-5.2-codex`)
-- Anthropic: `anthropic/claude-opus-4-5` (or `anthropic/claude-sonnet-4-5`)
+- OpenAI Codex: `openai-codex/gpt-5.3-codex` (optional: `openai-codex/gpt-5.3-codex-codex`)
+- Anthropic: `anthropic/claude-opus-4-6` (or `anthropic/claude-sonnet-4-5`)
 - Google (Gemini API): `google/gemini-3-pro-preview` and `google/gemini-3-flash-preview` (avoid older Gemini 2.x models)
 - Google (Antigravity): `google-antigravity/claude-opus-4-5-thinking` and `google-antigravity/gemini-3-flash`
 - Z.AI (GLM): `zai/glm-4.7`
 - MiniMax: `minimax/minimax-m2.1`
 
 Run gateway smoke with tools + image:
-`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.3-codex,anthropic/claude-opus-4-6,google/gemini-3-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
 
 ### Baseline: tool calling (Read + optional Exec)
 
 Pick at least one per provider family:
 
 - OpenAI: `openai/gpt-5.2` (or `openai/gpt-5-mini`)
-- Anthropic: `anthropic/claude-opus-4-5` (or `anthropic/claude-sonnet-4-5`)
+- Anthropic: `anthropic/claude-opus-4-6` (or `anthropic/claude-sonnet-4-5`)
 - Google: `google/gemini-3-flash-preview` (or `google/gemini-3-pro-preview`)
 - Z.AI (GLM): `zai/glm-4.7`
 - MiniMax: `minimax/minimax-m2.1`

docs/token-use.md

@@ -93,9 +93,9 @@ https://docs.anthropic.com/docs/build-with-claude/prompt-caching
 agents:
   defaults:
     model:
-      primary: "anthropic/claude-opus-4-5"
+      primary: "anthropic/claude-opus-4-6"
     models:
-      "anthropic/claude-opus-4-5":
+      "anthropic/claude-opus-4-6":
         params:
           cacheRetention: "long"
     heartbeat:

docs/tools/llm-task.md

@@ -55,7 +55,7 @@ without writing custom OpenClaw code for each workflow.
           "defaultProvider": "openai-codex",
           "defaultModel": "gpt-5.2",
           "defaultAuthProfileId": "main",
-          "allowedModels": ["openai-codex/gpt-5.2"],
+          "allowedModels": ["openai-codex/gpt-5.3-codex"],
           "maxTokens": 800,
           "timeoutMs": 30000
         }

docs/tools/thinking.md

@@ -16,6 +16,7 @@ title: "Thinking Levels"
   - medium → “think harder”
   - high → “ultrathink” (max budget)
   - xhigh → “ultrathink+” (GPT-5.2 + Codex models only)
+  - `x-high`, `x_high`, `extra-high`, `extra high`, and `extra_high` map to `xhigh`.
   - `highest`, `max` map to `high`.
 - Provider notes:
   - Z.AI (`zai/*`) only supports binary thinking (`on`/`off`). Any non-`off` level is treated as `on` (mapped to `low`).

docs/vps.md

@@ -13,13 +13,13 @@ deployments work at a high level.
 
 ## Pick a provider
 
-- **Railway** (one‑click + browser setup): [Railway](/railway)
-- **Northflank** (one‑click + browser setup): [Northflank](/northflank)
+- **Railway** (one‑click + browser setup): [Railway](/install/railway)
+- **Northflank** (one‑click + browser setup): [Northflank](/install/northflank)
 - **Oracle Cloud (Always Free)**: [Oracle](/platforms/oracle) — $0/month (Always Free, ARM; capacity/signup can be finicky)
-- **Fly.io**: [Fly.io](/platforms/fly)
-- **Hetzner (Docker)**: [Hetzner](/platforms/hetzner)
-- **GCP (Compute Engine)**: [GCP](/platforms/gcp)
-- **exe.dev** (VM + HTTPS proxy): [exe.dev](/platforms/exe-dev)
+- **Fly.io**: [Fly.io](/install/fly)
+- **Hetzner (Docker)**: [Hetzner](/install/hetzner)
+- **GCP (Compute Engine)**: [GCP](/install/gcp)
+- **exe.dev** (VM + HTTPS proxy): [exe.dev](/install/exe-dev)
 - **AWS (EC2/Lightsail/free tier)**: works well too. Video guide:
   https://x.com/techfrenAJ/status/2014934471095812547
 

docs/web/dashboard.md

@@ -29,18 +29,18 @@ Prefer localhost, Tailscale Serve, or an SSH tunnel.
 
 ## Fast path (recommended)
 
-- After onboarding, the CLI now auto-opens the dashboard with your token and prints the same tokenized link.
+- After onboarding, the CLI auto-opens the dashboard and prints a clean (non-tokenized) link.
 - Re-open anytime: `openclaw dashboard` (copies link, opens browser if possible, shows SSH hint if headless).
-- The token stays local (query param only); the UI strips it after first load and saves it in localStorage.
+- If the UI prompts for auth, paste the token from `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) into Control UI settings.
 
 ## Token basics (local vs remote)
 
-- **Localhost**: open `http://127.0.0.1:18789/`. If you see “unauthorized,” run `openclaw dashboard` and use the tokenized link (`?token=...`).
-- **Token source**: `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`); the UI stores it after first load.
+- **Localhost**: open `http://127.0.0.1:18789/`.
+- **Token source**: `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`); the UI stores a copy in localStorage after you connect.
 - **Not localhost**: use Tailscale Serve (tokenless if `gateway.auth.allowTailscale: true`), tailnet bind with a token, or an SSH tunnel. See [Web surfaces](/web).
 
 ## If you see “unauthorized” / 1008
 
-- Run `openclaw dashboard` to get a fresh tokenized link.
-- Ensure the gateway is reachable (local: `openclaw status`; remote: SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/?token=...`).
-- In the dashboard settings, paste the same token you configured in `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).
+- Ensure the gateway is reachable (local: `openclaw status`; remote: SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`).
+- Retrieve the token from the gateway host: `openclaw config get gateway.auth.token` (or generate one: `openclaw doctor --generate-gateway-token`).
+- In the dashboard settings, paste the token into the auth field, then connect.

docs/zh-CN/channels/feishu.md

@@ -109,17 +109,23 @@ Lark（国际版）请使用 https://open.larksuite.com/app，并在配置中设
       "application:application.app_message_stats.overview:readonly",
       "application:application:self_manage",
       "application:bot.menu:write",
+      "cardkit:card:write",
       "contact:user.employee_id:readonly",
       "corehr:file:download",
+      "docs:document.content:read",
       "event:ip_list",
+      "im:chat",
       "im:chat.access_event.bot_p2p_chat:read",
       "im:chat.members:bot_access",
       "im:message",
       "im:message.group_at_msg:readonly",
+      "im:message.group_msg",
       "im:message.p2p_msg:readonly",
       "im:message:readonly",
       "im:message:send_as_bot",
-      "im:resource"
+      "im:resource",
+      "sheets:spreadsheet",
+      "wiki:wiki:readonly"
     ],
     "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
   }
@@ -453,7 +459,116 @@ openclaw pairing list feishu
 
 ### 流式输出
 
-飞书目前不支持消息编辑，因此默认禁用流式输出（`blockStreaming: true`）。机器人会等待完整回复后一次性发送。
+飞书支持通过交互式卡片实现流式输出，机器人会实时更新卡片内容显示生成进度。默认配置：
+
+```json5
+{
+  channels: {
+    feishu: {
+      streaming: true, // 启用流式卡片输出（默认 true）
+      blockStreaming: true, // 启用块级流式（默认 true）
+    },
+  },
+}
+```
+
+如需禁用流式输出（等待完整回复后一次性发送），可设置 `streaming: false`。
+
+### 消息引用
+
+在群聊中，机器人的回复可以引用用户发送的原始消息，让对话上下文更加清晰。
+
+配置选项：
+
+```json5
+{
+  channels: {
+    feishu: {
+      // 账户级别配置（默认 "all"）
+      replyToMode: "all",
+      groups: {
+        oc_xxx: {
+          // 特定群组可以覆盖
+          replyToMode: "first",
+        },
+      },
+    },
+  },
+}
+```
+
+`replyToMode` 值说明：
+
+| 值        | 行为                               |
+| --------- | ---------------------------------- |
+| `"off"`   | 不引用原消息（私聊默认值）         |
+| `"first"` | 仅在第一条回复时引用原消息         |
+| `"all"`   | 所有回复都引用原消息（群聊默认值） |
+
+> 注意：消息引用功能与流式卡片输出（`streaming: true`）不能同时使用。当启用流式输出时，回复会以卡片形式呈现，不会显示引用。
+
+### 多 Agent 路由
+
+通过 `bindings` 配置，您可以用一个飞书机器人对接多个不同功能或性格的 Agent。系统会根据用户 ID 或群组 ID 自动将对话分发到对应的 Agent。
+
+配置示例：
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "main" },
+      {
+        id: "clawd-fan",
+        workspace: "/home/user/clawd-fan",
+        agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
+      },
+      {
+        id: "clawd-xi",
+        workspace: "/home/user/clawd-xi",
+        agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
+      },
+    ],
+  },
+  bindings: [
+    {
+      // 用户 A 的私聊 → main agent
+      agentId: "main",
+      match: {
+        channel: "feishu",
+        peer: { kind: "dm", id: "ou_28b31a88..." },
+      },
+    },
+    {
+      // 用户 B 的私聊 → clawd-fan agent
+      agentId: "clawd-fan",
+      match: {
+        channel: "feishu",
+        peer: { kind: "dm", id: "ou_0fe6b1c9..." },
+      },
+    },
+    {
+      // 某个群组 → clawd-xi agent
+      agentId: "clawd-xi",
+      match: {
+        channel: "feishu",
+        peer: { kind: "group", id: "oc_xxx..." },
+      },
+    },
+  ],
+}
+```
+
+匹配规则说明：
+
+| 字段              | 说明                                          |
+| ----------------- | --------------------------------------------- |
+| `agentId`         | 目标 Agent 的 ID，需要在 `agents.list` 中定义 |
+| `match.channel`   | 渠道类型，这里固定为 `"feishu"`               |
+| `match.peer.kind` | 对话类型：`"dm"`（私聊）或 `"group"`（群组）  |
+| `match.peer.id`   | 用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`） |
+
+> 获取 ID 的方法：参见上文 [获取群组/用户 ID](#获取群组用户-id) 章节。
 
 ---
 
@@ -478,7 +593,8 @@ openclaw pairing list feishu
 | `channels.feishu.groups.<chat_id>.enabled`        | 是否启用该群组                 | `true`    |
 | `channels.feishu.textChunkLimit`                  | 消息分块大小                   | `2000`    |
 | `channels.feishu.mediaMaxMb`                      | 媒体大小限制                   | `30`      |
-| `channels.feishu.blockStreaming`                  | 禁用流式输出                   | `true`    |
+| `channels.feishu.streaming`                       | 启用流式卡片输出               | `true`    |
+| `channels.feishu.blockStreaming`                  | 启用块级流式                   | `true`    |
 
 ---
 

docs/zh-CN/gateway/remote.md

@@ -35,7 +35,7 @@ x-i18n:
 
 - **最佳用户体验：** 保持 `gateway.bind: "loopback"` 并使用 **Tailscale Serve** 作为控制 UI。
 - **回退方案：** 保持 loopback + 从任何需要访问的机器建立 SSH 隧道。
-- **示例：** [exe.dev](/platforms/exe-dev)（简易 VM）或 [Hetzner](/platforms/hetzner)（生产 VPS）。
+- **示例：** [exe.dev](/install/exe-dev)（简易 VM）或 [Hetzner](/install/hetzner)（生产 VPS）。
 
 当你的笔记本电脑经常休眠但你希望智能体始终在线时，这是理想的选择。
 

docs/zh-CN/help/faq.md

@@ -572,7 +572,7 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
 
 任何 Linux VPS 都可以。在服务器上安装，然后使用 SSH/Tailscale 访问 Gateway 网关。
 
-指南：[exe.dev](/platforms/exe-dev)、[Hetzner](/platforms/hetzner)、[Fly.io](/platforms/fly)。
+指南：[exe.dev](/install/exe-dev)、[Hetzner](/install/hetzner)、[Fly.io](/install/fly)。
 远程访问：[Gateway 网关远程](/gateway/remote)。
 
 ### 云/VPS 安装指南在哪里
@@ -580,9 +580,9 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
 我们维护了一个**托管中心**，涵盖常见提供商。选择一个并按指南操作：
 
 - [VPS 托管](/vps)（所有提供商汇总）
-- [Fly.io](/platforms/fly)
-- [Hetzner](/platforms/hetzner)
-- [exe.dev](/platforms/exe-dev)
+- [Fly.io](/install/fly)
+- [Hetzner](/install/hetzner)
+- [exe.dev](/install/exe-dev)
 
 在云端的工作方式：**Gateway 网关运行在服务器上**，你通过控制 UI（或 Tailscale/SSH）从笔记本/手机访问。你的状态 + 工作区位于服务器上，因此将主机视为数据来源并做好备份。
 
@@ -863,7 +863,7 @@ OpenClaw 是轻量级的。对于基本的 Gateway 网关 + 一个聊天渠道
 - **操作系统：** Ubuntu LTS 或其他现代 Debian/Ubuntu。
 
 如果你使用 Windows，**WSL2 是最简单的虚拟机式设置**，具有最佳的工具兼容性。参阅 [Windows](/platforms/windows)、[VPS 托管](/vps)。
-如果你在虚拟机中运行 macOS，参阅 [macOS VM](/platforms/macos-vm)。
+如果你在虚拟机中运行 macOS，参阅 [macOS VM](/install/macos-vm)。
 
 ## 什么是 OpenClaw？
 

docs/zh-CN/install/docker.md

@@ -70,7 +70,7 @@ Docker 是**可选的**。仅当你想要容器化的 Gateway 网关或验证 Do
 - `~/.openclaw/`
 - `~/.openclaw/workspace`
 
-在 VPS 上运行？参阅 [Hetzner（Docker VPS）](/platforms/hetzner)。
+在 VPS 上运行？参阅 [Hetzner（Docker VPS）](/install/hetzner)。
 
 ### 手动流程（compose）
 

docs/zh-CN/platforms/digitalocean.md

@@ -34,7 +34,7 @@ x-i18n:
 **选择提供商：**
 
 - DigitalOcean：最简单的用户体验 + 可预测的设置（本指南）
-- Hetzner：性价比高（参见 [Hetzner 指南](/platforms/hetzner)）
+- Hetzner：性价比高（参见 [Hetzner 指南](/install/hetzner)）
 - Oracle Cloud：可以 $0/月，但更麻烦且仅限 ARM（参见 [Oracle 指南](/platforms/oracle)）
 
 ---
@@ -263,7 +263,7 @@ free -h
 
 ## 另请参阅
 
-- [Hetzner 指南](/platforms/hetzner) — 更便宜、更强大
+- [Hetzner 指南](/install/hetzner) — 更便宜、更强大
 - [Docker 安装](/install/docker) — 容器化设置
 - [Tailscale](/gateway/tailscale) — 安全远程访问
 - [配置](/gateway/configuration) — 完整配置参考

docs/zh-CN/platforms/index.md

@@ -33,10 +33,10 @@ Windows 原生配套应用也在计划中；推荐通过 WSL2 使用 Gateway 网
 ## VPS 和托管
 
 - VPS 中心：[VPS 托管](/vps)
-- Fly.io：[Fly.io](/platforms/fly)
-- Hetzner（Docker）：[Hetzner](/platforms/hetzner)
-- GCP（Compute Engine）：[GCP](/platforms/gcp)
-- exe.dev（VM + HTTPS 代理）：[exe.dev](/platforms/exe-dev)
+- Fly.io：[Fly.io](/install/fly)
+- Hetzner（Docker）：[Hetzner](/install/hetzner)
+- GCP（Compute Engine）：[GCP](/install/gcp)
+- exe.dev（VM + HTTPS 代理）：[exe.dev](/install/exe-dev)
 
 ## 常用链接
 

docs/zh-CN/platforms/linux.md

@@ -28,7 +28,7 @@ Gateway 网关在 Linux 上完全支持。**Node 是推荐的运行时**。
 4. 从你的笔记本电脑：`ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
 5. 打开 `http://127.0.0.1:18789/` 并粘贴你的令牌
 
-分步 VPS 指南：[exe.dev](/platforms/exe-dev)
+分步 VPS 指南：[exe.dev](/install/exe-dev)
 
 ## 安装
 

docs/zh-CN/platforms/oracle.md

@@ -307,4 +307,4 @@ tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace
 - [Tailscale 集成](/gateway/tailscale) — 完整的 Tailscale 文档
 - [Gateway 网关配置](/gateway/configuration) — 所有配置选项
 - [DigitalOcean 指南](/platforms/digitalocean) — 如果你想要付费 + 更容易注册
-- [Hetzner 指南](/platforms/hetzner) — 基于 Docker 的替代方案
+- [Hetzner 指南](/install/hetzner) — 基于 Docker 的替代方案

docs/zh-CN/platforms/raspberry-pi.md

@@ -360,6 +360,6 @@ echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
 
 - [Linux 指南](/platforms/linux) — 通用 Linux 设置
 - [DigitalOcean 指南](/platforms/digitalocean) — 云替代方案
-- [Hetzner 指南](/platforms/hetzner) — Docker 设置
+- [Hetzner 指南](/install/hetzner) — Docker 设置
 - [Tailscale](/gateway/tailscale) — 远程访问
 - [节点](/nodes) — 将你的笔记本电脑/手机与 Pi Gateway 网关配对

docs/zh-CN/providers/ollama.md

@@ -156,7 +156,7 @@ export OLLAMA_API_KEY="ollama-local"
     defaults: {
       model: {
         primary: "ollama/llama3.3",
-        fallback: ["ollama/qwen2.5-coder:32b"],
+        fallbacks: ["ollama/qwen2.5-coder:32b"],
       },
     },
   },

docs/zh-CN/start/getting-started.md

@@ -203,4 +203,4 @@ openclaw message send --target +15555550123 --message "Hello from OpenClaw"
 - macOS 菜单栏应用 + 语音唤醒：[macOS 应用](/platforms/macos)
 - iOS/Android 节点（Canvas/相机/语音）：[节点](/nodes)
 - 远程访问（SSH 隧道 / Tailscale Serve）：[远程访问](/gateway/remote) 和 [Tailscale](/gateway/tailscale)
-- 常开 / VPN 设置：[远程访问](/gateway/remote)、[exe.dev](/platforms/exe-dev)、[Hetzner](/platforms/hetzner)、[macOS 远程](/platforms/mac/remote)
+- 常开 / VPN 设置：[远程访问](/gateway/remote)、[exe.dev](/install/exe-dev)、[Hetzner](/install/hetzner)、[macOS 远程](/platforms/mac/remote)

docs/zh-CN/vps.md

@@ -22,10 +22,10 @@ x-i18n:
 - **Railway**（一键 + 浏览器设置）：[Railway](/railway)
 - **Northflank**（一键 + 浏览器设置）：[Northflank](/northflank)
 - **Oracle Cloud（永久免费）**：[Oracle](/platforms/oracle) — $0/月（永久免费，ARM；容量/注册可能不太稳定）
-- **Fly.io**：[Fly.io](/platforms/fly)
-- **Hetzner（Docker）**：[Hetzner](/platforms/hetzner)
-- **GCP（Compute Engine）**：[GCP](/platforms/gcp)
-- **exe.dev**（VM + HTTPS 代理）：[exe.dev](/platforms/exe-dev)
+- **Fly.io**：[Fly.io](/install/fly)
+- **Hetzner（Docker）**：[Hetzner](/install/hetzner)
+- **GCP（Compute Engine）**：[GCP](/install/gcp)
+- **exe.dev**（VM + HTTPS 代理）：[exe.dev](/install/exe-dev)
 - **AWS（EC2/Lightsail/免费套餐）**：也运行良好。视频指南：
   https://x.com/techfrenAJ/status/2014934471095812547