Merge branch 'openclaw:main' into qianfan

.markdownlint-cli2.jsonc

@@ -0,0 +1,52 @@
+{
+  "globs": ["docs/**/*.md", "docs/**/*.mdx", "README.md"],
+  "ignores": ["docs/zh-CN/**", "docs/.i18n/**", "docs/reference/templates/**"],
+  "config": {
+    "default": true,
+
+    "MD013": false,
+    "MD025": false,
+    "MD029": false,
+
+    "MD033": {
+      "allowed_elements": [
+        "Note",
+        "Info",
+        "Tip",
+        "Warning",
+        "Card",
+        "CardGroup",
+        "Columns",
+        "Steps",
+        "Step",
+        "Tabs",
+        "Tab",
+        "Accordion",
+        "AccordionGroup",
+        "CodeGroup",
+        "Frame",
+        "Callout",
+        "ParamField",
+        "ResponseField",
+        "RequestExample",
+        "ResponseExample",
+        "img",
+        "a",
+        "br",
+        "details",
+        "summary",
+        "p",
+        "strong",
+        "picture",
+        "source",
+        "Tooltip",
+        "Check",
+      ],
+    },
+
+    "MD036": false,
+    "MD040": false,
+    "MD041": false,
+    "MD046": false,
+  },
+}

CHANGELOG.md

@@ -2,29 +2,52 @@
 
 Docs: https://docs.openclaw.ai
 
-## 2026.2.4
+## 2026.2.6
+
+### Changes
+
+- Cron: default `wakeMode` is now `"now"` for new jobs (was `"next-heartbeat"`). (#10776) Thanks @tyler6204.
+- Cron: `cron run` defaults to force execution; use `--due` to restrict to due-only. (#10776) Thanks @tyler6204.
+- Models: support Anthropic Opus 4.6 and OpenAI Codex gpt-5.3-codex (forward-compat fallbacks). (#9853, #10720, #9995) Thanks @TinyTb, @calvin-hpnet, @tyler6204.
+- Providers: add xAI (Grok) support. (#9885) Thanks @grp06.
+- Web UI: add token usage dashboard. (#10072) Thanks @Takhoffman.
+- Memory: native Voyage AI support. (#7078) Thanks @mcinteerj.
+- Sessions: cap sessions_history payloads to reduce context overflow. (#10000) Thanks @gut-puncture.
+- CLI: sort commands alphabetically in help output. (#8068) Thanks @deepsoumya617.
+- Agents: bump pi-mono to 0.52.7; add embedded forward-compat fallback for Opus 4.6 model ids.
+
+### Added
+
+- Cron: run history deep-links to session chat from the dashboard. (#10776) Thanks @tyler6204.
+- Cron: per-run session keys in run log entries and default labels for cron sessions. (#10776) Thanks @tyler6204.
+- Cron: legacy payload field compatibility (`deliver`, `channel`, `to`, `bestEffortDeliver`) in schema. (#10776) Thanks @tyler6204.
+
+### Fixes
+
+- Cron: scheduler reliability (timer drift, restart catch-up, lock contention, stale running markers). (#10776) Thanks @tyler6204.
+- Cron: store migration hardening (legacy field migration, parse error handling, explicit delivery mode persistence). (#10776) Thanks @tyler6204.
+- Memory: set Voyage embeddings `input_type` for improved retrieval. (#10818) Thanks @mcinteerj.
+- Telegram: auto-inject DM topic threadId in message tool + subagent announce. (#7235) Thanks @Lukavyi.
+- Security: require auth for Gateway canvas host and A2UI assets. (#9518) Thanks @coygeek.
+- Cron: fix scheduling and reminder delivery regressions; harden next-run recompute + timer re-arming + legacy schedule fields. (#9733, #9823, #9948, #9932) Thanks @tyler6204, @pycckuu, @j2h4u, @fujiwara-tofu-shop.
+- Update: harden Control UI asset handling in update flow. (#10146) Thanks @gumadeiras.
+- Security: add skill/plugin code safety scanner; redact credentials from config.get gateway responses. (#9806, #9858) Thanks @abdelsfane.
+- Exec approvals: coerce bare string allowlist entries to objects. (#9903) Thanks @mcaxtr.
+- Slack: add mention stripPatterns for /new and /reset. (#9971) Thanks @ironbyte-rgb.
+- Chrome extension: fix bundled path resolution. (#8914) Thanks @kelvinCB.
+- Compaction/errors: allow multiple compaction retries on context overflow; show clear billing errors. (#8928, #8391) Thanks @Glucksberg.
+
+## 2026.2.3
 
 ### Changes
 
-- Agents: bump pi-mono packages to 0.52.5. (#9949) Thanks @gumadeiras.
-- Models: default Anthropic model to `anthropic/claude-opus-4-6`. (#9853) Thanks @TinyTb.
-- Models/Onboarding: refresh provider defaults, update OpenAI/OpenAI Codex wizard defaults, and harden model allowlist initialization for first-time configs with matching docs/tests. (#9911) Thanks @gumadeiras.
-- Telegram: auto-inject forum topic `threadId` in message tool and subagent announce so media, buttons, and subagent results land in the correct topic instead of General. (#7235) Thanks @Lukavyi.
-- Security: add skill/plugin code safety scanner that detects dangerous patterns (command injection, eval, data exfiltration, obfuscated code, crypto mining, env harvesting) in installed extensions. Integrated into `openclaw security audit --deep` and plugin install flow; scan failures surface as warnings. (#9806) Thanks @abdelsfane.
-- CLI: sort `openclaw --help` commands (and options) alphabetically. (#8068) Thanks @deepsoumya617.
 - Telegram: remove last `@ts-nocheck` from `bot-handlers.ts`, use Grammy types directly, deduplicate `StickerMetadata`. Zero `@ts-nocheck` remaining in `src/telegram/`. (#9206)
 - Telegram: remove `@ts-nocheck` from `bot-message.ts`, type deps via `Omit<BuildTelegramMessageContextParams>`, widen `allMedia` to `TelegramMediaRef[]`. (#9180)
 - Telegram: remove `@ts-nocheck` from `bot.ts`, fix duplicate `bot.catch` error handler (Grammy overrides), remove dead reaction `message_thread_id` routing, harden sticker cache guard. (#9077)
-- Telegram: allow per-group and per-topic `groupPolicy` overrides under `channels.telegram.groups`. (#9775) Thanks @nicolasstanley.
-- Feishu: expand channel handling (posts with images, doc links, routing, reactions/typing, replies, native commands). (#8975) Thanks @jiulingyun.
 - Onboarding: add Cloudflare AI Gateway provider setup and docs. (#7914) Thanks @roerohan.
 - Onboarding: add Moonshot (.cn) auth choice and keep the China base URL when preserving defaults. (#7180) Thanks @waynelwz.
-- Onboarding: add xAI (Grok) auth choice and provider defaults. (#9885) Thanks @grp06.
 - Docs: clarify tmux send-keys for TUI by splitting text and Enter. (#7737) Thanks @Wangnov.
-- Web UI: add Token Usage dashboard with session analytics. (#8462) Thanks @mcinteerj.
 - Docs: mirror the landing page revamp for zh-CN (features, quickstart, docs directory, network model, credits). (#8994) Thanks @joshp123.
-- Docs: strengthen secure DM mode guidance for multi-user inboxes with an explicit warning and example. (#9377) Thanks @Shrinija17.
-- Docs: document `activeHours` heartbeat field with timezone resolution chain and example. (#9366) Thanks @unisone.
 - Messages: add per-channel and per-account responsePrefix overrides across channels. (#9001) Thanks @mudrii.
 - Cron: add announce delivery mode for isolated jobs (CLI + Control UI) and delivery mode config.
 - Cron: default isolated jobs to announce delivery; accept ISO 8601 `schedule.at` in tool inputs.
@@ -35,33 +58,15 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
-- Control UI: add hardened fallback for asset resolution in global npm installs. (#4855) Thanks @anapivirtua.
-- Update: remove dead restore control-ui step that failed on gitignored dist/ output.
-- Update: avoid wiping prebuilt Control UI assets during dev auto-builds (`tsdown --no-clean`), run update doctor via `openclaw.mjs`, and auto-restore missing UI assets after doctor. (#10146) Thanks @gumadeiras.
-- Models: add forward-compat fallback for `openai-codex/gpt-5.3-codex` when model registry hasn't discovered it yet. (#9989) Thanks @w1kke.
-- Auto-reply/Docs: normalize `extra-high` (and spaced variants) to `xhigh` for Codex thinking levels, and align Codex 5.3 FAQ examples. (#9976) Thanks @slonce70.
-- Compaction: remove orphaned `tool_result` messages during history pruning to prevent session corruption from aborted tool calls. (#9868, fixes #9769, #9724, #9672)
-- Telegram: pass `parentPeer` for forum topic binding inheritance so group-level bindings apply to all topics within the group. (#9789, fixes #9545, #9351)
-- CLI: pass `--disable-warning=ExperimentalWarning` as a Node CLI option when respawning (avoid disallowed `NODE_OPTIONS` usage; fixes npm pack). (#9691) Thanks @18-RAJAT.
-- CLI: resolve bundled Chrome extension assets by walking up to the nearest assets directory; add resolver and clipboard tests. (#8914) Thanks @kelvinCB.
-- Tests: stabilize Windows ACL coverage with deterministic os.userInfo mocking. (#9335) Thanks @M00N7682.
-- Exec approvals: coerce bare string allowlist entries to objects to prevent allowlist corruption. (#9903, fixes #9790) Thanks @mcaxtr.
 - Heartbeat: allow explicit accountId routing for multi-account channels. (#8702) Thanks @lsh411.
 - TUI/Gateway: handle non-streaming finals, refresh history for non-local chat runs, and avoid event gap warnings for targeted tool streams. (#8432) Thanks @gumadeiras.
-- Security: stop exposing Gateway auth tokens via URL query parameters in Control UI entrypoints, and reject hook tokens in query parameters. (#9436) Thanks @coygeek.
 - Shell completion: auto-detect and migrate slow dynamic patterns to cached files for faster terminal startup; add completion health checks to doctor/update/onboard.
 - Telegram: honor session model overrides in inline model selection. (#8193) Thanks @gildo.
 - Web UI: fix agent model selection saves for default/non-default agents and wrap long workspace paths. Thanks @Takhoffman.
 - Web UI: resolve header logo path when `gateway.controlUi.basePath` is set. (#7178) Thanks @Yeom-JinHo.
 - Web UI: apply button styling to the new-messages indicator.
 - Onboarding: infer auth choice from non-interactive API key flags. (#8484) Thanks @f-trycua.
-- Usage: include estimated cost when breakdown is missing and keep `usage.cost` days support. (#8462) Thanks @mcinteerj.
 - Security: keep untrusted channel metadata out of system prompts (Slack/Discord). Thanks @KonstantinMirin.
-- Security: redact channel credentials (tokens, passwords, API keys, secrets) from gateway config APIs and preserve secrets during Control UI round-trips. (#9858) Thanks @abdelsfane.
-- Discord: treat allowlisted senders as owner for system-prompt identity hints while keeping channel topics untrusted.
-- Slack: strip `<@...>` mention tokens before command matching so `/new` and `/reset` work when prefixed with a mention. (#9971) Thanks @ironbyte-rgb.
-- Agents: cap `sessions_history` tool output and strip oversized fields to prevent context overflow. (#10000) Thanks @gut-puncture.
-- Security: normalize code safety finding paths in `openclaw security audit --deep` output for cross-platform consistency. (#10000) Thanks @gut-puncture.
 - Security: enforce sandboxed media paths for message tool attachments. (#9182) Thanks @victormier.
 - Security: require explicit credentials for gateway URL overrides to prevent credential leakage. (#8113) Thanks @victormier.
 - Security: gate `whatsapp_login` tool to owner senders and default-deny non-owner contexts. (#8768) Thanks @victormier.
@@ -69,13 +74,9 @@ Docs: https://docs.openclaw.ai
 - Voice call: add regression coverage for anonymous inbound caller IDs with allowlist policy. (#8104) Thanks @victormier.
 - Cron: accept epoch timestamps and 0ms durations in CLI `--at` parsing.
 - Cron: reload store data when the store file is recreated or mtime changes.
-- Cron: prevent `recomputeNextRuns` from skipping due jobs when timer fires late by reordering `onTimer` flow. (#9823, fixes #9788) Thanks @pycckuu.
 - Cron: deliver announce runs directly, honor delivery mode, and respect wakeMode for summaries. (#8540) Thanks @tyler6204.
-- Cron: correct announce delivery inference for thread session keys and null delivery inputs. (#9733) Thanks @tyler6204.
 - Telegram: include forward_from_chat metadata in forwarded messages and harden cron delivery target checks. (#8392) Thanks @Glucksberg.
-- Telegram: preserve DM topic threadId in deliveryContext. (#9039) Thanks @lailoo.
 - macOS: fix cron payload summary rendering and ISO 8601 formatter concurrency safety.
-- Security: require gateway auth for Canvas host and A2UI assets. (#9518) Thanks @coygeek.
 
 ## 2026.2.2-3
 

apps/android/app/build.gradle.kts

@@ -22,7 +22,7 @@ android {
     minSdk = 31
     targetSdk = 36
     versionCode = 202602030
-    versionName = "2026.2.4"
+    versionName = "2026.2.6"
   }
 
   buildTypes {

apps/ios/Sources/Info.plist

@@ -19,7 +19,7 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.2.4</string>
+	<string>2026.2.6</string>
 	<key>CFBundleVersion</key>
 	<string>20260202</string>
 	<key>NSAppTransportSecurity</key>

apps/ios/Tests/Info.plist

@@ -17,7 +17,7 @@
 	<key>CFBundlePackageType</key>
 	<string>BNDL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.2.4</string>
+	<string>2026.2.6</string>
 	<key>CFBundleVersion</key>
 	<string>20260202</string>
 </dict>

apps/ios/project.yml

@@ -81,7 +81,7 @@ targets:
       properties:
         CFBundleDisplayName: OpenClaw
         CFBundleIconName: AppIcon
-        CFBundleShortVersionString: "2026.2.4"
+        CFBundleShortVersionString: "2026.2.6"
         CFBundleVersion: "20260202"
         UILaunchScreen: {}
         UIApplicationSceneManifest:
@@ -130,5 +130,5 @@ targets:
       path: Tests/Info.plist
       properties:
         CFBundleDisplayName: OpenClawTests
-        CFBundleShortVersionString: "2026.2.4"
+        CFBundleShortVersionString: "2026.2.6"
         CFBundleVersion: "20260202"

apps/macos/Sources/OpenClaw/CronJobEditor.swift

@@ -29,7 +29,7 @@ struct CronJobEditor: View {
     @State var agentId: String = ""
     @State var enabled: Bool = true
     @State var sessionTarget: CronSessionTarget = .main
-    @State var wakeMode: CronWakeMode = .nextHeartbeat
+    @State var wakeMode: CronWakeMode = .now
     @State var deleteAfterRun: Bool = false
 
     enum ScheduleKind: String, CaseIterable, Identifiable { case at, every, cron; var id: String { rawValue } }
@@ -119,8 +119,8 @@ struct CronJobEditor: View {
                             GridRow {
                                 self.gridLabel("Wake mode")
                                 Picker("", selection: self.$wakeMode) {
-                                    Text("next-heartbeat").tag(CronWakeMode.nextHeartbeat)
                                     Text("now").tag(CronWakeMode.now)
+                                    Text("next-heartbeat").tag(CronWakeMode.nextHeartbeat)
                                 }
                                 .labelsHidden()
                                 .pickerStyle(.segmented)

apps/macos/Sources/OpenClaw/Resources/Info.plist

@@ -15,7 +15,7 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.2.4</string>
+    <string>2026.2.6</string>
     <key>CFBundleVersion</key>
     <string>202602020</string>
     <key>CFBundleIconFile</key>

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -2025,6 +2025,8 @@ public struct CronRunLogEntry: Codable, Sendable {
     public let status: AnyCodable?
     public let error: String?
     public let summary: String?
+    public let sessionid: String?
+    public let sessionkey: String?
     public let runatms: Int?
     public let durationms: Int?
     public let nextrunatms: Int?
@@ -2036,6 +2038,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         status: AnyCodable?,
         error: String?,
         summary: String?,
+        sessionid: String?,
+        sessionkey: String?,
         runatms: Int?,
         durationms: Int?,
         nextrunatms: Int?
@@ -2046,6 +2050,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         self.status = status
         self.error = error
         self.summary = summary
+        self.sessionid = sessionid
+        self.sessionkey = sessionkey
         self.runatms = runatms
         self.durationms = durationms
         self.nextrunatms = nextrunatms
@@ -2057,6 +2063,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         case status
         case error
         case summary
+        case sessionid = "sessionId"
+        case sessionkey = "sessionKey"
         case runatms = "runAtMs"
         case durationms = "durationMs"
         case nextrunatms = "nextRunAtMs"

apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

@@ -2025,6 +2025,8 @@ public struct CronRunLogEntry: Codable, Sendable {
     public let status: AnyCodable?
     public let error: String?
     public let summary: String?
+    public let sessionid: String?
+    public let sessionkey: String?
     public let runatms: Int?
     public let durationms: Int?
     public let nextrunatms: Int?
@@ -2036,6 +2038,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         status: AnyCodable?,
         error: String?,
         summary: String?,
+        sessionid: String?,
+        sessionkey: String?,
         runatms: Int?,
         durationms: Int?,
         nextrunatms: Int?
@@ -2046,6 +2050,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         self.status = status
         self.error = error
         self.summary = summary
+        self.sessionid = sessionid
+        self.sessionkey = sessionkey
         self.runatms = runatms
         self.durationms = durationms
         self.nextrunatms = nextrunatms
@@ -2057,6 +2063,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         case status
         case error
         case summary
+        case sessionid = "sessionId"
+        case sessionkey = "sessionKey"
         case runatms = "runAtMs"
         case durationms = "durationMs"
         case nextrunatms = "nextRunAtMs"

docs/automation/cron-jobs.md

@@ -40,7 +40,7 @@ openclaw cron add \
   --delete-after-run
 
 openclaw cron list
-openclaw cron run <job-id> --force
+openclaw cron run <job-id>
 openclaw cron runs --id <job-id>
 ```
 
@@ -123,8 +123,8 @@ local timezone is used.
 Main jobs enqueue a system event and optionally wake the heartbeat runner.
 They must use `payload.kind = "systemEvent"`.
 
-- `wakeMode: "next-heartbeat"` (default): event waits for the next scheduled heartbeat.
+- `wakeMode: "now"` (default): event triggers an immediate heartbeat run.
-- `wakeMode: "now"`: event triggers an immediate heartbeat run.
+- `wakeMode: "next-heartbeat"`: event waits for the next scheduled heartbeat.
 
 This is the best fit when you want the normal heartbeat prompt + main-session context.
 See [Heartbeat](/gateway/heartbeat).
@@ -288,7 +288,7 @@ Notes:
 - `sessionTarget` must be `"main"` or `"isolated"` and must match `payload.kind`.
 - Optional fields: `agentId`, `description`, `enabled`, `deleteAfterRun` (defaults to true for `at`),
   `delivery`.
-- `wakeMode` defaults to `"next-heartbeat"` when omitted.
+- `wakeMode` defaults to `"now"` when omitted.
 
 ### cron.update params
 
@@ -420,10 +420,11 @@ openclaw cron edit <jobId> --agent ops
 openclaw cron edit <jobId> --clear-agent
 ```
 
-Manual run (debug):
+Manual run (force is the default, use `--due` to only run when due):
 
 ```bash
-openclaw cron run <jobId> --force
+openclaw cron run <jobId>
+openclaw cron run <jobId> --due
 ```
 
 Edit an existing job (patch fields):

docs/brave-search.md

@@ -12,7 +12,7 @@ OpenClaw uses Brave Search as the default provider for `web_search`.
 
 ## Get an API key
 
-1. Create a Brave Search API account at https://brave.com/search/api/
+1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/)
 2. In the dashboard, choose the **Data for Search** plan and generate an API key.
 3. Store the key in config (recommended) or set `BRAVE_API_KEY` in the Gateway environment.
 

docs/channels/bluebubbles.md

@@ -27,6 +27,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R
 1. Install the BlueBubbles server on your Mac (follow the instructions at [bluebubbles.app/install](https://bluebubbles.app/install)).
 2. In the BlueBubbles config, enable the web API and set a password.
 3. Run `openclaw onboard` and select BlueBubbles, or configure manually:
+
    ```json5
    {
      channels: {
@@ -39,6 +40,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R
      },
    }
    ```
+
 4. Point BlueBubbles webhooks to your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
 5. Start the gateway; it will register the webhook handler and start pairing.
 
@@ -335,4 +337,4 @@ Prefer `chat_guid` for stable routing:
 - OpenClaw auto-hides known-broken actions based on the BlueBubbles server's macOS version. If edit still appears on macOS 26 (Tahoe), disable it manually with `channels.bluebubbles.actions.edit=false`.
 - For status/health info: `openclaw status --all` or `openclaw status --deep`.
 
-For general channel workflow reference, see [Channels](/channels) and the [Plugins](/plugins) guide.
+For general channel workflow reference, see [Channels](/channels) and the [Plugins](/plugin) guide.

docs/channels/feishu.md

@@ -75,7 +75,7 @@ Choose **Feishu**, then enter the App ID and App Secret.
 
 Visit [Feishu Open Platform](https://open.feishu.cn/app) and sign in.
 
-Lark (global) tenants should use https://open.larksuite.com/app and set `domain: "lark"` in the Feishu config.
+Lark (global) tenants should use [https://open.larksuite.com/app](https://open.larksuite.com/app) and set `domain: "lark"` in the Feishu config.
 
 ### 2. Create an app
 
@@ -261,10 +261,12 @@ After approval, you can chat normally.
 
 - **Default**: `dmPolicy: "pairing"` (unknown users get a pairing code)
 - **Approve pairing**:
+
   ```bash
   openclaw pairing list feishu
   openclaw pairing approve feishu <CODE>
   ```
+
 - **Allowlist mode**: set `channels.feishu.allowFrom` with allowed Open IDs
 
 ### Group chats

docs/channels/googlechat.md

@@ -101,6 +101,7 @@ Use Tailscale Serve for the private dashboard and Funnel for the public webhook
    If prompted, visit the authorization URL shown in the output to enable Funnel for this node in your tailnet policy.
 
 5. **Verify the configuration:**
+
    ```bash
    tailscale serve status
    tailscale funnel status
@@ -225,6 +226,7 @@ This means the webhook handler isn't registered. Common causes:
    If it shows "disabled", add `plugins.entries.googlechat.enabled: true` to your config.
 
 3. **Gateway not restarted**: After adding config, restart the gateway:
+
    ```bash
    openclaw gateway restart
    ```

docs/channels/imessage.md

@@ -62,6 +62,28 @@ Disable with:
 - Automation permission when sending.
 - `channels.imessage.cliPath` can point to any command that proxies stdin/stdout (for example, a wrapper script that SSHes to another Mac and runs `imsg rpc`).
 
+## Troubleshooting macOS Privacy and Security TCC
+
+If sending/receiving fails (for example, `imsg rpc` exits non-zero, times out, or the gateway appears to hang), a common cause is a macOS permission prompt that was never approved.
+
+macOS grants TCC permissions per app/process context. Approve prompts in the same context that runs `imsg` (for example, Terminal/iTerm, a LaunchAgent session, or an SSH-launched process).
+
+Checklist:
+
+- **Full Disk Access**: allow access for the process running OpenClaw (and any shell/SSH wrapper that executes `imsg`). This is required to read the Messages database (`chat.db`).
+- **Automation → Messages**: allow the process running OpenClaw (and/or your terminal) to control **Messages.app** for outbound sends.
+- **`imsg` CLI health**: verify `imsg` is installed and supports RPC (`imsg rpc --help`).
+
+Tip: If OpenClaw is running headless (LaunchAgent/systemd/SSH) the macOS prompt can be easy to miss. Run a one-time interactive command in a GUI terminal to force the prompt, then retry:
+
+```bash
+imsg chats --limit 1
+# or
+imsg send <handle> "test"
+```
+
+Related macOS folder permissions (Desktop/Documents/Downloads): [/platforms/mac/permissions](/platforms/mac/permissions).
+
 ## Setup (fast path)
 
 1. Ensure Messages is signed in on this Mac.
@@ -81,7 +103,7 @@ If you want the bot to send from a **separate iMessage identity** (and keep your
 6. Set up SSH so `ssh <bot-macos-user>@localhost true` works without a password.
 7. Point `channels.imessage.accounts.bot.cliPath` at an SSH wrapper that runs `imsg` as the bot user.
 
-First-run note: sending/receiving may require GUI approvals (Automation + Full Disk Access) in the _bot macOS user_. If `imsg rpc` looks stuck or exits, log into that user (Screen Sharing helps), run a one-time `imsg chats --limit 1` / `imsg send ...`, approve prompts, then retry.
+First-run note: sending/receiving may require GUI approvals (Automation + Full Disk Access) in the _bot macOS user_. If `imsg rpc` looks stuck or exits, log into that user (Screen Sharing helps), run a one-time `imsg chats --limit 1` / `imsg send ...`, approve prompts, then retry. See [Troubleshooting macOS Privacy and Security TCC](#troubleshooting-macos-privacy-and-security-tcc).
 
 Example wrapper (`chmod +x`). Replace `<bot-macos-user>` with your actual macOS username:
 

docs/channels/line.md

@@ -34,7 +34,7 @@ openclaw plugins install ./extensions/line
 ## Setup
 
 1. Create a LINE Developers account and open the Console:
-   https://developers.line.biz/console/
+   [https://developers.line.biz/console/](https://developers.line.biz/console/)
 2. Create (or pick) a Provider and add a **Messaging API** channel.
 3. Copy the **Channel access token** and **Channel secret** from the channel settings.
 4. Enable **Use webhook** in the Messaging API settings.

docs/channels/matrix.md

@@ -74,7 +74,7 @@ Details: [Plugins](/plugin)
    - When set, `channels.matrix.userId` should be the full Matrix ID (example: `@bot:example.org`).
 5. Restart the gateway (or finish onboarding).
 6. Start a DM with the bot or invite it to a room from any Matrix client
-   (Element, Beeper, etc.; see https://matrix.org/ecosystem/clients/). Beeper requires E2EE,
+   (Element, Beeper, etc.; see [https://matrix.org/ecosystem/clients/](https://matrix.org/ecosystem/clients/)). Beeper requires E2EE,
    so set `channels.matrix.encryption: true` and verify the device.
 
 Minimal config (access token, user ID auto-fetched):

docs/channels/msteams.md

@@ -558,6 +558,7 @@ Bots don't have a personal OneDrive drive (the `/me/drive` Graph API endpoint do
    ```
 
 4. **Configure OpenClaw:**
+
    ```json5
    {
      channels: {
@@ -747,7 +748,7 @@ Bots have limited support in private channels:
 
 - **"Icon file cannot be empty":** The manifest references icon files that are 0 bytes. Create valid PNG icons (32x32 for `outline.png`, 192x192 for `color.png`).
 - **"webApplicationInfo.Id already in use":** The app is still installed in another team/chat. Find and uninstall it first, or wait 5-10 minutes for propagation.
-- **"Something went wrong" on upload:** Upload via https://admin.teams.microsoft.com instead, open browser DevTools (F12) → Network tab, and check the response body for the actual error.
+- **"Something went wrong" on upload:** Upload via [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) instead, open browser DevTools (F12) → Network tab, and check the response body for the actual error.
 - **Sideload failing:** Try "Upload an app to your org's app catalog" instead of "Upload a custom app" - this often bypasses sideload restrictions.
 
 ### RSC permissions not working

docs/channels/nextcloud-talk.md

@@ -34,9 +34,11 @@ Details: [Plugins](/plugin)
 
 1. Install the Nextcloud Talk plugin.
 2. On your Nextcloud server, create a bot:
+
    ```bash
    ./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction
    ```
+
 3. Enable the bot in the target room settings.
 4. Configure OpenClaw:
    - Config: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`

docs/channels/slack.md

@@ -30,7 +30,7 @@ Minimal config:
 
 ### Setup
 
-1. Create a Slack app (From scratch) in https://api.slack.com/apps.
+1. Create a Slack app (From scratch) in [https://api.slack.com/apps](https://api.slack.com/apps).
 2. **Socket Mode** → toggle on. Then go to **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes** with scope `connections:write`. Copy the **App Token** (`xapp-...`).
 3. **OAuth & Permissions** → add bot token scopes (use the manifest below). Click **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`).
 4. Optional: **OAuth & Permissions** → add **User Token Scopes** (see the read-only list below). Reinstall the app and copy the **User OAuth Token** (`xoxp-...`).
@@ -49,7 +49,7 @@ Use the manifest below so scopes and events stay in sync.
 
 Multi-account support: use `channels.slack.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
 
-### OpenClaw config (minimal)
+### OpenClaw config (Socket mode)
 
 Set tokens via env vars (recommended):
 
@@ -130,7 +130,7 @@ Example with userTokenReadOnly explicitly set (allow user token writes):
 Use HTTP webhook mode when your Gateway is reachable by Slack over HTTPS (typical for server deployments).
 HTTP mode uses the Events API + Interactivity + Slash Commands with a shared request URL.
 
-### Setup
+### Setup (HTTP mode)
 
 1. Create a Slack app and **disable Socket Mode** (optional if you only use HTTP).
 2. **Basic Information** → copy the **Signing Secret**.
@@ -260,30 +260,30 @@ If you enable native commands, add one `slash_commands` entry per command you wa
 
 Slack's Conversations API is type-scoped: you only need the scopes for the
 conversation types you actually touch (channels, groups, im, mpim). See
-https://docs.slack.dev/apis/web-api/using-the-conversations-api/ for the overview.
+[https://docs.slack.dev/apis/web-api/using-the-conversations-api/](https://docs.slack.dev/apis/web-api/using-the-conversations-api/) for the overview.
 
 ### Bot token scopes (required)
 
 - `chat:write` (send/update/delete messages via `chat.postMessage`)
-  https://docs.slack.dev/reference/methods/chat.postMessage
+  [https://docs.slack.dev/reference/methods/chat.postMessage](https://docs.slack.dev/reference/methods/chat.postMessage)
 - `im:write` (open DMs via `conversations.open` for user DMs)
-  https://docs.slack.dev/reference/methods/conversations.open
+  [https://docs.slack.dev/reference/methods/conversations.open](https://docs.slack.dev/reference/methods/conversations.open)
 - `channels:history`, `groups:history`, `im:history`, `mpim:history`
-  https://docs.slack.dev/reference/methods/conversations.history
+  [https://docs.slack.dev/reference/methods/conversations.history](https://docs.slack.dev/reference/methods/conversations.history)
 - `channels:read`, `groups:read`, `im:read`, `mpim:read`
-  https://docs.slack.dev/reference/methods/conversations.info
+  [https://docs.slack.dev/reference/methods/conversations.info](https://docs.slack.dev/reference/methods/conversations.info)
 - `users:read` (user lookup)
-  https://docs.slack.dev/reference/methods/users.info
+  [https://docs.slack.dev/reference/methods/users.info](https://docs.slack.dev/reference/methods/users.info)
 - `reactions:read`, `reactions:write` (`reactions.get` / `reactions.add`)
-  https://docs.slack.dev/reference/methods/reactions.get
+  [https://docs.slack.dev/reference/methods/reactions.get](https://docs.slack.dev/reference/methods/reactions.get)
-  https://docs.slack.dev/reference/methods/reactions.add
+  [https://docs.slack.dev/reference/methods/reactions.add](https://docs.slack.dev/reference/methods/reactions.add)
 - `pins:read`, `pins:write` (`pins.list` / `pins.add` / `pins.remove`)
-  https://docs.slack.dev/reference/scopes/pins.read
+  [https://docs.slack.dev/reference/scopes/pins.read](https://docs.slack.dev/reference/scopes/pins.read)
-  https://docs.slack.dev/reference/scopes/pins.write
+  [https://docs.slack.dev/reference/scopes/pins.write](https://docs.slack.dev/reference/scopes/pins.write)
 - `emoji:read` (`emoji.list`)
-  https://docs.slack.dev/reference/scopes/emoji.read
+  [https://docs.slack.dev/reference/scopes/emoji.read](https://docs.slack.dev/reference/scopes/emoji.read)
 - `files:write` (uploads via `files.uploadV2`)
-  https://docs.slack.dev/messaging/working-with-files/#upload
+  [https://docs.slack.dev/messaging/working-with-files/#upload](https://docs.slack.dev/messaging/working-with-files/#upload)
 
 ### User token scopes (optional, read-only by default)
 
@@ -302,9 +302,9 @@ Add these under **User Token Scopes** if you configure `channels.slack.userToken
 - `mpim:write` (only if we add group-DM open/DM start via `conversations.open`)
 - `groups:write` (only if we add private-channel management: create/rename/invite/archive)
 - `chat:write.public` (only if we want to post to channels the bot isn't in)
-  https://docs.slack.dev/reference/scopes/chat.write.public
+  [https://docs.slack.dev/reference/scopes/chat.write.public](https://docs.slack.dev/reference/scopes/chat.write.public)
 - `users:read.email` (only if we need email fields from `users.info`)
-  https://docs.slack.dev/changelog/2017-04-narrowing-email-access
+  [https://docs.slack.dev/changelog/2017-04-narrowing-email-access](https://docs.slack.dev/changelog/2017-04-narrowing-email-access)
 - `files:read` (only if we start listing/reading file metadata)
 
 ## Config

docs/channels/telegram.md

@@ -147,7 +147,7 @@ You can add custom commands to the menu via config:
 }
 ```
 
-## Troubleshooting
+## Setup troubleshooting (commands)
 
 - `setMyCommands failed` in logs usually means outbound HTTPS/DNS is blocked to `api.telegram.org`.
 - If you see `sendMessage` or `sendChatAction` failures, check IPv6 routing and DNS.
@@ -365,6 +365,7 @@ Alternate (official Bot API):
 
 1. DM your bot.
 2. Fetch updates with your bot token and read `message.from.id`:
+
    ```bash
    curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    ```

docs/channels/troubleshooting.md

@@ -1,5 +1,5 @@
 ---
-summary: "Channel-specific troubleshooting shortcuts (Discord/Telegram/WhatsApp)"
+summary: "Channel-specific troubleshooting shortcuts (Discord/Telegram/WhatsApp/iMessage)"
 read_when:
   - A channel connects but messages don’t flow
   - Investigating channel misconfiguration (intents, permissions, privacy mode)
@@ -22,6 +22,7 @@ openclaw channels status --probe
 - Discord: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
 - Telegram: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
 - WhatsApp: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
+- iMessage (legacy): [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc)
 
 ## Telegram quick fixes
 

docs/channels/twitch.md

@@ -34,7 +34,7 @@ Details: [Plugins](/plugin)
    - Select **Bot Token**
    - Verify scopes `chat:read` and `chat:write` are selected
    - Copy the **Client ID** and **Access Token**
-3. Find your Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
+3. Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)
 4. Configure the token:
    - Env: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (default account only)
    - Or config: `channels.twitch.accessToken`
@@ -123,7 +123,7 @@ Prefer `allowFrom` for a hard allowlist. Use `allowedRoles` instead if you want
 
 **Why user IDs?** Usernames can change, allowing impersonation. User IDs are permanent.
 
-Find your Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/ (Convert your Twitch username to ID)
+Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/) (Convert your Twitch username to ID)
 
 ## Token refresh (optional)
 

docs/channels/whatsapp.md

@@ -205,11 +205,13 @@ The wizard uses it to set your **allowlist/owner** so your own DMs are permitted
 
 - `Body` is the current message body with envelope.
 - Quoted reply context is **always appended**:
+
   ```
   [Replying to +1555 id:ABC123]
   <quoted text or <media:...>>
   [/Replying]
   ```
+
 - Reply metadata also set:
   - `ReplyToId` = stanzaId
   - `ReplyToBody` = quoted body or media placeholder

docs/channels/zalo.md

@@ -57,7 +57,7 @@ It is a good fit for support or notifications where you want deterministic routi
 
 ### 1) Create a bot token (Zalo Bot Platform)
 
-1. Go to **https://bot.zaloplatforms.com** and sign in.
+1. Go to [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) and sign in.
 2. Create a new bot and configure its settings.
 3. Copy the bot token (format: `12345689:abc-xyz`).
 

docs/cli/memory.md

@@ -14,7 +14,7 @@ Provided by the active memory plugin (default: `memory-core`; set `plugins.slots
 Related:
 
 - Memory concept: [Memory](/concepts/memory)
-- Plugins: [Plugins](/plugins)
+- Plugins: [Plugins](/plugin)
 
 ## Examples
 

docs/concepts/architecture.md

@@ -110,9 +110,11 @@ Details: [Gateway protocol](/gateway/protocol), [Pairing](/start/pairing),
 
 - Preferred: Tailscale or VPN.
 - Alternative: SSH tunnel
+
   ```bash
   ssh -N -L 18789:127.0.0.1:18789 user@host
   ```
+
 - The same handshake + auth token apply over the tunnel.
 - TLS + optional pinning can be enabled for WS in remote setups.
 

docs/concepts/groups.md

@@ -39,8 +39,9 @@ otherwise -> reply
 ![Group message flow](/images/groups-flow.svg)
 
 If you want...
+
 | Goal                                         | What to set                                                |
-|------|-------------|
+| -------------------------------------------- | ---------------------------------------------------------- |
 | Allow all groups but only reply on @mentions | `groups: { "*": { requireMention: true } }`                |
 | Disable all group replies                    | `groupPolicy: "disabled"`                                  |
 | Only specific groups                         | `groups: { "<group-id>": { ... } }` (no `"*"` key)         |

docs/concepts/memory.md

@@ -88,7 +88,8 @@ Defaults:
   1. `local` if a `memorySearch.local.modelPath` is configured and the file exists.
   2. `openai` if an OpenAI key can be resolved.
   3. `gemini` if a Gemini key can be resolved.
-  4. Otherwise memory search stays disabled until configured.
+  4. `voyage` if a Voyage key can be resolved.
+  5. Otherwise memory search stays disabled until configured.
 - Local mode uses node-llama-cpp and may require `pnpm approve-builds`.
 - Uses sqlite-vec (when available) to accelerate vector search inside SQLite.
 
@@ -96,7 +97,8 @@ Remote embeddings **require** an API key for the embedding provider. OpenClaw
 resolves keys from auth profiles, `models.providers.*.apiKey`, or environment
 variables. Codex OAuth only covers chat/completions and does **not** satisfy
 embeddings for memory search. For Gemini, use `GEMINI_API_KEY` or
-`models.providers.google.apiKey`. When using a custom OpenAI-compatible endpoint,
+`models.providers.google.apiKey`. For Voyage, use `VOYAGE_API_KEY` or
+`models.providers.voyage.apiKey`. When using a custom OpenAI-compatible endpoint,
 set `memorySearch.remote.apiKey` (and optional `memorySearch.remote.headers`).
 
 ### QMD backend (experimental)
@@ -109,7 +111,7 @@ out to QMD for retrieval. Key points:
 **Prereqs**
 
 - Disabled by default. Opt in per-config (`memory.backend = "qmd"`).
-- Install the QMD CLI separately (`bun install -g github.com/tobi/qmd` or grab
+- Install the QMD CLI separately (`bun install -g https://github.com/tobi/qmd` or grab
   a release) and make sure the `qmd` binary is on the gateway’s `PATH`.
 - QMD needs an SQLite build that allows extensions (`brew install sqlite` on
   macOS).
@@ -302,8 +304,8 @@ Why OpenAI batch is fast + cheap:
 - For large backfills, OpenAI is typically the fastest option we support because we can submit many embedding requests in a single batch job and let OpenAI process them asynchronously.
 - OpenAI offers discounted pricing for Batch API workloads, so large indexing runs are usually cheaper than sending the same requests synchronously.
 - See the OpenAI Batch API docs and pricing for details:
-  - https://platform.openai.com/docs/api-reference/batch
+  - [https://platform.openai.com/docs/api-reference/batch](https://platform.openai.com/docs/api-reference/batch)
-  - https://platform.openai.com/pricing
+  - [https://platform.openai.com/pricing](https://platform.openai.com/pricing)
 
 Config example:
 

docs/concepts/model-providers.md

@@ -242,7 +242,7 @@ Ollama is a local LLM runtime that provides an OpenAI-compatible API:
 - Provider: `ollama`
 - Auth: None required (local server)
 - Example model: `ollama/llama3.3`
-- Installation: https://ollama.ai
+- Installation: [https://ollama.ai](https://ollama.ai)
 
 ```bash
 # Install Ollama, then pull a model:

docs/concepts/session.md

@@ -17,7 +17,7 @@ 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 for multi-user setups)
+## Secure DM mode (recommended for multi-user setups)
 
 > **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.
 

docs/concepts/system-prompt.md

@@ -110,6 +110,6 @@ This keeps the base prompt small while still enabling targeted skill usage.
 When available, the system prompt includes a **Documentation** section that points to the
 local OpenClaw docs directory (either `docs/` in the repo workspace or the bundled npm
 package docs) and also notes the public mirror, source repo, community Discord, and
-ClawHub (https://clawhub.com) for skills discovery. The prompt instructs the model to consult local docs first
+ClawHub ([https://clawhub.com](https://clawhub.com)) for skills discovery. The prompt instructs the model to consult local docs first
 for OpenClaw behavior, commands, configuration, or architecture, and to run
 `openclaw status` itself when possible (asking the user only when it lacks access).

docs/concepts/typebox.md

@@ -280,7 +280,7 @@ Unknown frame types are preserved as raw payloads for forward compatibility.
 Generated JSON Schema is in the repo at `dist/protocol.schema.json`. The
 published raw file is typically available at:
 
-- https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json
+- [https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json](https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json)
 
 ## When you change schemas
 

docs/debug/node-issue.md

@@ -62,19 +62,21 @@ node --import tsx scripts/repro/tsx-name-repro.ts
 
 - Use Bun for dev scripts (current temporary revert).
 - Use Node + tsc watch, then run compiled output:
+
   ```bash
   pnpm exec tsc --watch --preserveWatchOutput
   node --watch openclaw.mjs status
   ```
+
 - Confirmed locally: `pnpm exec tsc -p tsconfig.json` + `node openclaw.mjs status` works on Node 25.
 - Disable esbuild keepNames in the TS loader if possible (prevents `__name` helper insertion); tsx does not currently expose this.
 - Test Node LTS (22/24) with `tsx` to see if the issue is Node 25–specific.
 
 ## References
 
-- https://opennext.js.org/cloudflare/howtos/keep_names
+- [https://opennext.js.org/cloudflare/howtos/keep_names](https://opennext.js.org/cloudflare/howtos/keep_names)
-- https://esbuild.github.io/api/#keep-names
+- [https://esbuild.github.io/api/#keep-names](https://esbuild.github.io/api/#keep-names)
-- https://github.com/evanw/esbuild/issues/1031
+- [https://github.com/evanw/esbuild/issues/1031](https://github.com/evanw/esbuild/issues/1031)
 
 ## Next steps
 

docs/docs.json

@@ -805,14 +805,8 @@
                 "pages": ["install/index", "install/installer"]
               },
               {
-                "group": "Install methods",
+                "group": "Other install methods",
-                "pages": [
+                "pages": ["install/docker", "install/nix", "install/ansible", "install/bun"]
-                  "install/node",
-                  "install/docker",
-                  "install/nix",
-                  "install/ansible",
-                  "install/bun"
-                ]
               },
               {
                 "group": "Maintenance",
@@ -1226,6 +1220,7 @@
               {
                 "group": "Environment and debugging",
                 "pages": [
+                  "install/node",
                   "environment",
                   "debugging",
                   "testing",

docs/gateway/bonjour.md

@@ -105,10 +105,13 @@ The Gateway advertises small non‑secret hints to make UI flows convenient:
 Useful built‑in tools:
 
 - Browse instances:
+
   ```bash
   dns-sd -B _openclaw-gw._tcp local.
   ```
+
 - Resolve one instance (replace `<instance>`):
+
   ```bash
   dns-sd -L "<instance>" _openclaw-gw._tcp local.
   ```

docs/gateway/configuration.md

@@ -1310,8 +1310,9 @@ Thread session isolation:
 - `channels.slack.thread.inheritParent` controls whether new thread sessions inherit the parent channel transcript (default: false).
 
 Slack action groups (gate `slack` tool actions):
+
 | Action group | Default | Notes                  |
-| --- | --- | --- |
+| ------------ | ------- | ---------------------- |
 | reactions    | enabled | React + list reactions |
 | messages     | enabled | Read/send/edit/delete  |
 | pins         | enabled | Pin/unpin/list         |
@@ -1977,11 +1978,13 @@ Block streaming:
 - `agents.defaults.blockStreamingChunk`: soft chunking for streamed blocks. Defaults to
   800–1200 chars, prefers paragraph breaks (`\n\n`), then newlines, then sentences.
   Example:
+
   ```json5
   {
     agents: { defaults: { blockStreamingChunk: { minChars: 800, maxChars: 1200 } } },
   }
   ```
+
 - `agents.defaults.blockStreamingCoalesce`: merge streamed blocks before sending.
   Defaults to `{ idleMs: 1000 }` and inherits `minChars` from `blockStreamingChunk`
   with `maxChars` capped to the channel text limit. Signal/Slack/Discord/Google Chat default
@@ -1995,11 +1998,13 @@ Block streaming:
   Modes: `off` (default), `natural` (800–2500ms), `custom` (use `minMs`/`maxMs`).
   Per-agent override: `agents.list[].humanDelay`.
   Example:
+
   ```json5
   {
     agents: { defaults: { humanDelay: { mode: "natural" } } },
   }
   ```
+
   See [/concepts/streaming](/concepts/streaming) for behavior + chunking details.
 
 Typing indicators:
@@ -2065,7 +2070,7 @@ of `every`, keep `HEARTBEAT.md` tiny, and/or choose a cheaper `model`.
 - `tools.web.fetch.readability` (default true; disable to use basic HTML cleanup only)
 - `tools.web.fetch.firecrawl.enabled` (default true when an API key is set)
 - `tools.web.fetch.firecrawl.apiKey` (optional; defaults to `FIRECRAWL_API_KEY`)
-- `tools.web.fetch.firecrawl.baseUrl` (default https://api.firecrawl.dev)
+- `tools.web.fetch.firecrawl.baseUrl` (default [https://api.firecrawl.dev](https://api.firecrawl.dev))
 - `tools.web.fetch.firecrawl.onlyMainContent` (default true)
 - `tools.web.fetch.firecrawl.maxAgeMs` (optional)
 - `tools.web.fetch.firecrawl.timeoutSeconds` (optional)
@@ -2481,7 +2486,7 @@ Select the model via `agents.defaults.model.primary` (provider/model).
 
 OpenCode Zen is a multi-model gateway with per-model endpoints. OpenClaw uses
 the built-in `opencode` provider from pi-ai; set `OPENCODE_API_KEY` (or
-`OPENCODE_ZEN_API_KEY`) from https://opencode.ai/auth.
+`OPENCODE_ZEN_API_KEY`) from [https://opencode.ai/auth](https://opencode.ai/auth).
 
 Notes:
 
@@ -3366,7 +3371,7 @@ openclaw dns setup --apply
 }
 ```
 
-## Template variables
+## Media model template variables
 
 Template placeholders are expanded in `tools.media.*.models[].args` and `tools.media.models[].args` (and any future templated argument fields).
 

docs/gateway/index.md

@@ -49,9 +49,11 @@ pnpm gateway:watch
 ## Remote access
 
 - Tailscale/VPN preferred; otherwise SSH tunnel:
+
   ```bash
   ssh -N -L 18789:127.0.0.1:18789 user@host
   ```
+
 - Clients then connect to `ws://127.0.0.1:18789` through the tunnel.
 - If a token is configured, clients must include it in `connect.params.auth.token` even over the tunnel.
 

docs/gateway/local-models.md

@@ -52,7 +52,7 @@ Best current local stack. Load MiniMax M2.1 in LM Studio, enable the local serve
 
 **Setup checklist**
 
-- Install LM Studio: https://lmstudio.ai
+- Install LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
 - In LM Studio, download the **largest MiniMax M2.1 build available** (avoid “small”/heavily quantized variants), start the server, confirm `http://127.0.0.1:1234/v1/models` lists it.
 - Keep the model loaded; cold-load adds startup latency.
 - Adjust `contextWindow`/`maxTokens` if your LM Studio build differs.

docs/gateway/security/formal-verification.md

@@ -23,7 +23,7 @@ misconfiguration safety), under explicit assumptions.
 
 ## Where the models live
 
-Models are maintained in a separate repo: [vignesh07/openclaw-formal-models](https://github.com/vignesh07/openclaw-formal-models).
+Models are maintained in a separate repo: [vignesh07/clawdbot-formal-models](https://github.com/vignesh07/clawdbot-formal-models).
 
 ## Important caveats
 
@@ -41,8 +41,8 @@ Today, results are reproduced by cloning the models repo locally and running TLC
 Getting started:
 
 ```bash
-git clone https://github.com/vignesh07/openclaw-formal-models
+git clone https://github.com/vignesh07/clawdbot-formal-models
-cd openclaw-formal-models
+cd clawdbot-formal-models
 
 # Java 11+ required (TLC runs on the JVM).
 # The repo vendors a pinned `tla2tools.jar` (TLA+ tools) and provides `bin/tlc` + Make targets.

docs/gateway/security/index.md

@@ -773,18 +773,22 @@ If it fails, there are new candidates not yet in the baseline.
 ### If CI fails
 
 1. Reproduce locally:
+
    ```bash
    detect-secrets scan --baseline .secrets.baseline
    ```
+
 2. Understand the tools:
    - `detect-secrets scan` finds candidates and compares them to the baseline.
    - `detect-secrets audit` opens an interactive review to mark each baseline
      item as real or false positive.
 3. For real secrets: rotate/remove them, then re-run the scan to update the baseline.
 4. For false positives: run the interactive audit and mark them as false:
+
    ```bash
    detect-secrets audit .secrets.baseline
    ```
+
 5. If you need new excludes, add them to `.detect-secrets.cfg` and regenerate the
    baseline with matching `--exclude-files` / `--exclude-lines` flags (the config
    file is reference-only; detect-secrets doesn’t read it automatically).
@@ -814,7 +818,7 @@ Mario asking for find ~
 
 Found a vulnerability in OpenClaw? Please report responsibly:
 
-1. Email: security@openclaw.ai
+1. Email: [security@openclaw.ai](mailto:security@openclaw.ai)
 2. Don't post publicly until fixed
 3. We'll credit you (unless you prefer anonymity)
 

docs/gateway/tailscale.md

@@ -121,7 +121,7 @@ Avoid Funnel for browser control; treat node pairing like operator access.
 
 ## Learn more
 
-- Tailscale Serve overview: https://tailscale.com/kb/1312/serve
+- Tailscale Serve overview: [https://tailscale.com/kb/1312/serve](https://tailscale.com/kb/1312/serve)
-- `tailscale serve` command: https://tailscale.com/kb/1242/tailscale-serve
+- `tailscale serve` command: [https://tailscale.com/kb/1242/tailscale-serve](https://tailscale.com/kb/1242/tailscale-serve)
-- Tailscale Funnel overview: https://tailscale.com/kb/1223/tailscale-funnel
+- Tailscale Funnel overview: [https://tailscale.com/kb/1223/tailscale-funnel](https://tailscale.com/kb/1223/tailscale-funnel)
-- `tailscale funnel` command: https://tailscale.com/kb/1311/tailscale-funnel
+- `tailscale funnel` command: [https://tailscale.com/kb/1311/tailscale-funnel](https://tailscale.com/kb/1311/tailscale-funnel)

docs/gateway/troubleshooting.md

@@ -42,9 +42,11 @@ Fix options:
 
 - Re-run onboarding and choose **Anthropic** for that agent.
 - Or paste a setup-token on the **gateway host**:
+
   ```bash
   openclaw models auth setup-token --provider anthropic
   ```
+
 - Or copy `auth-profiles.json` from the main agent dir to the new agent dir.
 
 Verify:
@@ -120,13 +122,17 @@ Doctor/service will show runtime state (PID/last exit) and log hints.
 **Enable more logging:**
 
 - Bump file log detail (persisted JSONL):
+
   ```json
   { "logging": { "level": "debug" } }
   ```
+
 - Bump console verbosity (TTY output only):
+
   ```json
   { "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } }
   ```
+
 - Quick tip: `--verbose` affects **console** output only. File logs remain controlled by `logging.level`.
 
 See [/logging](/logging) for a full overview of formats, config, and access.
@@ -139,10 +145,13 @@ Gateway refuses to start.
 **Fix (recommended):**
 
 - Run the wizard and set the Gateway run mode to **Local**:
+
   ```bash
   openclaw configure
   ```
+
 - Or set it directly:
+
   ```bash
   openclaw config set gateway.mode local
   ```
@@ -150,6 +159,7 @@ Gateway refuses to start.
 **If you meant to run a remote Gateway instead:**
 
 - Set a remote URL and keep `gateway.mode=remote`:
+
   ```bash
   openclaw config set gateway.mode remote
   openclaw config set gateway.remote.url "wss://gateway.example.com"
@@ -554,6 +564,7 @@ Notes:
 
 - The git flow only rebases if the repo is clean. Commit or stash changes first.
 - After switching, run:
+
   ```bash
   openclaw doctor
   openclaw gateway restart

docs/help/faq.md

@@ -9,7 +9,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
 
 ## Table of contents
 
-- [Quick start and first-run setup](#quick-start-and-firstrun-setup)
+- [Quick start and first-run setup]
   - [Im stuck whats the fastest way to get unstuck?](#im-stuck-whats-the-fastest-way-to-get-unstuck)
   - [What's the recommended way to install and set up OpenClaw?](#whats-the-recommended-way-to-install-and-set-up-openclaw)
   - [How do I open the dashboard after onboarding?](#how-do-i-open-the-dashboard-after-onboarding)
@@ -37,7 +37,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [Can I use Claude Max subscription without an API key](#can-i-use-claude-max-subscription-without-an-api-key)
   - [How does Anthropic "setup-token" auth work?](#how-does-anthropic-setuptoken-auth-work)
   - [Where do I find an Anthropic setup-token?](#where-do-i-find-an-anthropic-setuptoken)
-  - [Do you support Claude subscription auth (Claude Code OAuth)?](#do-you-support-claude-subscription-auth-claude-code-oauth)
+  - [Do you support Claude subscription auth (Claude Pro or Max)?](#do-you-support-claude-subscription-auth-claude-pro-or-max)
   - [Why am I seeing `HTTP 429: rate_limit_error` from Anthropic?](#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
   - [Is AWS Bedrock supported?](#is-aws-bedrock-supported)
   - [How does Codex auth work?](#how-does-codex-auth-work)
@@ -74,7 +74,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [Cron or reminders do not fire. What should I check?](#cron-or-reminders-do-not-fire-what-should-i-check)
   - [How do I install skills on Linux?](#how-do-i-install-skills-on-linux)
   - [Can OpenClaw run tasks on a schedule or continuously in the background?](#can-openclaw-run-tasks-on-a-schedule-or-continuously-in-the-background)
-  - [Can I run Apple/macOS-only skills from Linux?](#can-i-run-applemacosonly-skills-from-linux)
+  - [Can I run Apple macOS-only skills from Linux?](#can-i-run-apple-macos-only-skills-from-linux)
   - [Do you have a Notion or HeyGen integration?](#do-you-have-a-notion-or-heygen-integration)
   - [How do I install the Chrome extension for browser takeover?](#how-do-i-install-the-chrome-extension-for-browser-takeover)
 - [Sandboxing and memory](#sandboxing-and-memory)
@@ -102,7 +102,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [How do I run a central Gateway with specialized workers across devices?](#how-do-i-run-a-central-gateway-with-specialized-workers-across-devices)
   - [Can the OpenClaw browser run headless?](#can-the-openclaw-browser-run-headless)
   - [How do I use Brave for browser control?](#how-do-i-use-brave-for-browser-control)
-- [Remote gateways + nodes](#remote-gateways-nodes)
+- [Remote gateways and nodes](#remote-gateways-and-nodes)
   - [How do commands propagate between Telegram, the gateway, and nodes?](#how-do-commands-propagate-between-telegram-the-gateway-and-nodes)
   - [How can my agent access my computer if the Gateway is hosted remotely?](#how-can-my-agent-access-my-computer-if-the-gateway-is-hosted-remotely)
   - [Tailscale is connected but I get no replies. What now?](#tailscale-is-connected-but-i-get-no-replies-what-now)
@@ -119,7 +119,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [How does OpenClaw load environment variables?](#how-does-openclaw-load-environment-variables)
   - ["I started the Gateway via the service and my env vars disappeared." What now?](#i-started-the-gateway-via-the-service-and-my-env-vars-disappeared-what-now)
   - [I set `COPILOT_GITHUB_TOKEN`, but models status shows "Shell env: off." Why?](#i-set-copilotgithubtoken-but-models-status-shows-shell-env-off-why)
-- [Sessions & multiple chats](#sessions-multiple-chats)
+- [Sessions and multiple chats](#sessions-and-multiple-chats)
   - [How do I start a fresh conversation?](#how-do-i-start-a-fresh-conversation)
   - [Do sessions reset automatically if I never send `/new`?](#do-sessions-reset-automatically-if-i-never-send-new)
   - [Is there a way to make a team of OpenClaw instances one CEO and many agents](#is-there-a-way-to-make-a-team-of-openclaw-instances-one-ceo-and-many-agents)
@@ -179,7 +179,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [How do I completely stop then start the Gateway?](#how-do-i-completely-stop-then-start-the-gateway)
   - [ELI5: `openclaw gateway restart` vs `openclaw gateway`](#eli5-openclaw-gateway-restart-vs-openclaw-gateway)
   - [What's the fastest way to get more details when something fails?](#whats-the-fastest-way-to-get-more-details-when-something-fails)
-- [Media & attachments](#media-attachments)
+- [Media and attachments](#media-and-attachments)
   - [My skill generated an image/PDF, but nothing was sent](#my-skill-generated-an-imagepdf-but-nothing-was-sent)
 - [Security and access control](#security-and-access-control)
   - [Is it safe to expose OpenClaw to inbound DMs?](#is-it-safe-to-expose-openclaw-to-inbound-dms)
@@ -252,10 +252,12 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
    Repairs/migrates config/state + runs health checks. See [Doctor](/gateway/doctor).
 
 7. **Gateway snapshot**
+
    ```bash
    openclaw health --json
    openclaw health --verbose   # shows the target URL + config path on errors
    ```
+
    Asks the running gateway for a full snapshot (WS-only). See [Health](/gateway/health).
 
 ## Quick start and first-run setup
@@ -266,8 +268,8 @@ Use a local AI agent that can **see your machine**. That is far more effective t
 in Discord, because most "I'm stuck" cases are **local config or environment issues** that
 remote helpers cannot inspect.
 
-- **Claude Code**: https://www.anthropic.com/claude-code/
+- **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/)
-- **OpenAI Codex**: https://openai.com/codex/
+- **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/)
 
 These tools can read the repo, run commands, inspect logs, and help fix your machine-level
 setup (PATH, services, permissions, auth files). Give them the **full source checkout** via
@@ -285,8 +287,8 @@ Tip: ask the agent to **plan and supervise** the fix (step-by-step), then execut
 necessary commands. That keeps changes small and easier to audit.
 
 If you discover a real bug or fix, please file a GitHub issue or send a PR:
-https://github.com/openclaw/openclaw/issues
+[https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues)
-https://github.com/openclaw/openclaw/pulls
+[https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls)
 
 Start with these commands (share outputs when asking for help):
 
@@ -432,7 +434,7 @@ Related: [Migrating](/install/migrating), [Where things live on disk](/help/faq#
 ### Where do I see what is new in the latest version
 
 Check the GitHub changelog:
-https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md
+[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
 
 Newest entries are at the top. If the top section is marked **Unreleased**, the next dated
 section is the latest shipped version. Entries are grouped by **Highlights**, **Changes**, and
@@ -443,10 +445,10 @@ section is the latest shipped version. Entries are grouped by **Highlights**, **
 Some Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity
 Advanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. More
 detail: [Troubleshooting](/help/troubleshooting#docsopenclawai-shows-an-ssl-error-comcastxfinity).
-Please help us unblock it by reporting here: https://spa.xfinity.com/check_url_status.
+Please help us unblock it by reporting here: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status).
 
 If you still can't reach the site, the docs are mirrored on GitHub:
-https://github.com/openclaw/openclaw/tree/main/docs
+[https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs)
 
 ### What's the difference between stable and beta
 
@@ -460,7 +462,7 @@ that same version to `latest`**. That's why beta and stable can point at the
 **same version**.
 
 See what changed:
-https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md
+[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
 
 ### How do I install the beta version and whats the difference between beta and dev
 
@@ -478,7 +480,7 @@ curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -
 ```
 
 Windows installer (PowerShell):
-https://openclaw.ai/install.ps1
+[https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1)
 
 More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer).
 
@@ -559,9 +561,11 @@ Two common Windows issues:
 
 - Your npm global bin folder is not on PATH.
 - Check the path:
+
   ```powershell
   npm config get prefix
   ```
+
 - Ensure `<prefix>\\bin` is on PATH (on most systems it is `%AppData%\\npm`).
 - Close and reopen PowerShell after updating PATH.
 
@@ -685,7 +689,7 @@ claude setup-token
 
 Copy the token it prints, then choose **Anthropic token (paste setup-token)** in the wizard. If you want to run it on the gateway host, use `openclaw models auth setup-token --provider anthropic`. If you ran `claude setup-token` elsewhere, paste it on the gateway host with `openclaw models auth paste-token --provider anthropic`. See [Anthropic](/providers/anthropic).
 
-### Do you support Claude subscription auth (Claude Pro/Max)
+### Do you support Claude subscription auth (Claude Pro or Max)
 
 Yes - via **setup-token**. OpenClaw no longer reuses Claude Code CLI OAuth tokens; use a setup-token or an Anthropic API key. Generate the token anywhere and paste it on the gateway host. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).
 
@@ -988,7 +992,7 @@ Advantages:
 - **Always-on Gateway** (run on a VPS, interact from anywhere)
 - **Nodes** for local browser/screen/camera/exec
 
-Showcase: https://openclaw.ai/showcase
+Showcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase)
 
 ## Skills and automation
 
@@ -1046,7 +1050,7 @@ Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-v
 ### How do I install skills on Linux
 
 Use **ClawHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn't available on Linux.
-Browse skills at https://clawhub.com.
+Browse skills at [https://clawhub.com](https://clawhub.com).
 
 Install the ClawHub CLI (pick one package manager):
 
@@ -1069,7 +1073,7 @@ Yes. Use the Gateway scheduler:
 Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat),
 [Heartbeat](/gateway/heartbeat).
 
-**Can I run Apple macOS only skills from Linux**
+### Can I run Apple macOS-only skills from Linux?
 
 Not directly. macOS skills are gated by `metadata.openclaw.os` plus required binaries, and skills only appear in the system prompt when they are eligible on the **Gateway host**. On Linux, `darwin`-only skills (like `apple-notes`, `apple-reminders`, `things-mac`) will not load unless you override the gating.
 
@@ -1085,13 +1089,16 @@ Run the Gateway on Linux, pair a macOS node (menubar app), and set **Node Run Co
 Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wrappers that run on a Mac. Then override the skill to allow Linux so it stays eligible.
 
 1. Create an SSH wrapper for the binary (example: `memo` for Apple Notes):
+
    ```bash
    #!/usr/bin/env bash
    set -euo pipefail
    exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"
    ```
+
 2. Put the wrapper on `PATH` on the Linux host (for example `~/bin/memo`).
 3. Override the skill metadata (workspace or `~/.openclaw/skills`) to allow Linux:
+
    ```markdown
    ---
    name: apple-notes
@@ -1099,6 +1106,7 @@ Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wra
    metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
    ---
    ```
+
 4. Start a new session so the skills snapshot refreshes.
 
 ### Do you have a Notion or HeyGen integration
@@ -1449,7 +1457,7 @@ Headless uses the **same Chromium engine** and works for most automation (forms,
 Set `browser.executablePath` to your Brave binary (or any Chromium-based browser) and restart the Gateway.
 See the full config examples in [Browser](/tools/browser#use-brave-or-another-chromium-based-browser).
 
-## Remote gateways + nodes
+## Remote gateways and nodes
 
 ### How do commands propagate between Telegram the gateway and nodes
 
@@ -1473,6 +1481,7 @@ Typical setup:
 4. Open the macOS app locally and connect in **Remote over SSH** mode (or direct tailnet)
    so it can register as a node.
 5. Approve the node on the Gateway:
+
    ```bash
    openclaw nodes pending
    openclaw nodes approve <requestId>
@@ -1610,10 +1619,12 @@ This sets your workspace and restricts who can trigger the bot.
 Minimal steps:
 
 1. **Install + login on the VPS**
+
    ```bash
    curl -fsSL https://tailscale.com/install.sh | sh
    sudo tailscale up
    ```
+
 2. **Install + login on your Mac**
    - Use the Tailscale app and sign in to the same tailnet.
 3. **Enable MagicDNS (recommended)**
@@ -1640,6 +1651,7 @@ Recommended setup:
 2. **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname).
    The app will tunnel the Gateway port and connect as a node.
 3. **Approve the node** on the gateway:
+
    ```bash
    openclaw nodes pending
    openclaw nodes approve <requestId>
@@ -1702,9 +1714,11 @@ If the Gateway runs as a service (launchd/systemd), it won't inherit your shell
 environment. Fix by doing one of these:
 
 1. Put the token in `~/.openclaw/.env`:
+
    ```
    COPILOT_GITHUB_TOKEN=...
    ```
+
 2. Or enable shell import (`env.shellEnv.enabled: true`).
 3. Or add it to your config `env` block (applies only if missing).
 
@@ -1717,7 +1731,7 @@ openclaw models status
 Copilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`).
 See [/concepts/model-providers](/concepts/model-providers) and [/environment](/environment).
 
-## Sessions & multiple chats
+## Sessions and multiple chats
 
 ### How do I start a fresh conversation
 
@@ -1801,6 +1815,7 @@ Use one of these:
   or `/compact <instructions>` to guide the summary.
 
 - **Reset** (fresh session ID for the same chat key):
+
   ```
   /new
   /reset
@@ -2071,9 +2086,11 @@ Fix checklist:
 3. Use the exact model id (case-sensitive): `minimax/MiniMax-M2.1` or
    `minimax/MiniMax-M2.1-lightning`.
 4. Run:
+
    ```bash
    openclaw models list
    ```
+
    and pick from the list (or `/model list` in chat).
 
 See [MiniMax](/providers/minimax) and [Models](/concepts/models).
@@ -2238,9 +2255,11 @@ can't find it in its auth store.
 - **If you want to use an API key instead**
   - Put `ANTHROPIC_API_KEY` in `~/.openclaw/.env` on the **gateway host**.
   - Clear any pinned order that forces a missing profile:
+
     ```bash
     openclaw models auth order clear --provider anthropic
     ```
+
 - **Confirm you're running commands on the gateway host**
   - In remote mode, auth profiles live on the gateway machine, not your laptop.
 
@@ -2624,7 +2643,7 @@ you want a one-off, foreground run.
 
 Start the Gateway with `--verbose` to get more console detail. Then inspect the log file for channel auth, model routing, and RPC errors.
 
-## Media & attachments
+## Media and attachments
 
 ### My skill generated an imagePDF but nothing was sent
 

docs/help/submitting-a-pr.md

@@ -3,212 +3,396 @@ summary: "How to submit a high signal PR"
 title: "Submitting a PR"
 ---
 
-# Submitting a PR
+Good PRs are easy to review: reviewers should quickly know the intent, verify behavior, and land changes safely. This guide covers concise, high-signal submissions for human and LLM review.
-
-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.
+- [ ] Explain the problem, why it matters, and the change.
-- [ ] Tight scope: keep changes focused and avoid drive-by refactors.
+- [ ] Keep changes focused. Avoid broad refactors.
-- [ ] Behavior summary: call out user-visible changes, config changes, and defaults.
+- [ ] Summarize user-visible/config/default changes.
-- [ ] Tests: list what ran, what was skipped, and why.
+- [ ] List test coverage, skips, and reasons.
-- [ ] Evidence: include logs, screenshots, or short recordings for UI or workflows.
+- [ ] Add evidence: logs, screenshots, or recordings (UI/UX).
-- [ ] Code word: include “lobster-biscuit” somewhere in the PR description to confirm you read this guide.
+- [ ] Code word: put “lobster-biscuit” in the PR description if you read this guide.
-- [ ] Baseline checks: run the relevant `pnpm` commands for this repo and fix failures before opening the PR.
+- [ ] Run/fix relevant `pnpm` commands before creating PR.
-- [ ] Due diligence: search the codebase for existing functionality and check GitHub for related issues or prior fixes.
+- [ ] Search codebase and GitHub for related functionality/issues/fixes.
-- [ ] Grounded in reality: claims should be backed by evidence, reproduction, or direct observation.
+- [ ] Base claims on evidence or observation.
-- [ ] Title guidance: use a verb + scope + outcome (for example `Docs: add PR and issue templates`).
+- [ ] Good title: verb + scope + outcome (e.g., `Docs: add PR and issue templates`).
 
-Guideline: concision > grammar. Be terse if it makes review faster.
+Be concise; concise review > grammar. Omit any non-applicable sections.
 
-Baseline validation commands (run as appropriate for the change, and fix failures before submitting):
+### Baseline validation commands (run/fix failures for your change)
 
 - `pnpm lint`
 - `pnpm check`
 - `pnpm build`
 - `pnpm test`
-- If you touch protocol code: `pnpm protocol:check`
+- Protocol changes: `pnpm protocol:check`
 
 ## Progressive disclosure
 
-Use a short top section, then deeper details as needed.
+- Top: summary/intent
+- Next: changes/risks
+- Next: test/verification
+- Last: implementation/evidence
 
-1. Summary and intent
+## Common PR types: specifics
-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.
+- [ ] Fix: Add repro, root cause, verification.
-
+- [ ] Feature: Add use cases, behavior/demos/screenshots (UI).
-## Common PR types and expectations
+- [ ] Refactor: State "no behavior change", list what moved/simplified.
-
+- [ ] Chore: State why (e.g., build time, CI, dependencies).
-- [ ] Fix: include clear repro, root cause summary, and verification steps.
+- [ ] Docs: Before/after context, link updated page, run `pnpm format`.
-- [ ] Feature: include use cases, behavior changes, and screenshots or demos when UI is involved.
+- [ ] Test: What gap is covered; how it prevents regressions.
-- [ ] Refactor: explicitly state “no behavior change” and list what moved or was simplified.
+- [ ] Perf: Add before/after metrics, and how measured.
-- [ ] Chore/Maintenance: note why it matters (build time, CI stability, dependency hygiene).
+- [ ] UX/UI: Screenshots/video, note accessibility impact.
-- [ ] Docs: include before/after context and link to the updated page. Run `pnpm format`.
+- [ ] Infra/Build: Environments/validation.
-- [ ] Test: explain the gap it covers and how it prevents regressions.
+- [ ] Security: Summarize risk, repro, verification, no sensitive data. Grounded claims only.
-- [ ] 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
+- [ ] Clear problem/intent
-- [ ] Scope is focused
+- [ ] Focused scope
-- [ ] Behavior changes are listed
+- [ ] List behavior changes
-- [ ] Tests are listed with results
+- [ ] List and result of tests
-- [ ] Evidence is attached when needed
+- [ ] Manual test steps (when applicable)
-- [ ] No secrets or private data
+- [ ] No secrets/private data
-- [ ] Grounded in reality: no guesswork or invented context.
+- [ ] Evidence-based
 
-## Template
+## General PR Template
 
 ```md
-## Summary
+#### Summary
 
-## Behavior Changes
+#### Behavior Changes
 
-## Codebase and GitHub Search
+#### Codebase and GitHub Search
 
-## Tests
+#### Tests
 
-## Evidence
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort (self-reported):
+- Agent notes (optional, cite evidence):
 ```
 
-## Templates by PR type
+## PR Type templates (replace with your type)
 
 ### Fix
 
 ```md
-## Summary
+#### Summary
 
-## Repro Steps
+#### Repro Steps
 
-## Root Cause
+#### Root Cause
 
-## Behavior Changes
+#### Behavior Changes
 
-## Tests
+#### Tests
 
-## Evidence
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Feature
 
 ```md
-## Summary
+#### Summary
 
-## Use Cases
+#### Use Cases
 
-## Behavior Changes
+#### Behavior Changes
 
-## Existing Functionality Check
+#### Existing Functionality Check
 
-I searched the codebase for existing functionality before implementing this.
+- [ ] I searched the codebase for existing functionality.
+      Searches performed (1-3 bullets):
+  -
+  -
 
-## Tests
+#### Tests
 
-## Evidence
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Refactor
 
 ```md
-## Summary
+#### Summary
 
-## Scope
+#### Scope
 
-## No Behavior Change Statement
+#### No Behavior Change Statement
 
-## Tests
+#### Tests
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Chore/Maintenance
 
 ```md
-## Summary
+#### Summary
 
-## Why This Matters
+#### Why This Matters
 
-## Tests
+#### Tests
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Docs
 
 ```md
-## Summary
+#### Summary
 
-## Pages Updated
+#### Pages Updated
 
-## Screenshots or Before/After
+#### Before/After
 
-## Formatting
+#### Formatting
 
 pnpm format
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Test
 
 ```md
-## Summary
+#### Summary
 
-## Gap Covered
+#### Gap Covered
 
-## Tests
+#### Tests
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Perf
 
 ```md
-## Summary
+#### Summary
 
-## Baseline
+#### Baseline
 
-## After
+#### After
 
-## Measurement Method
+#### Measurement Method
 
-## Tests
+#### Tests
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### UX/UI
 
 ```md
-## Summary
+#### Summary
 
-## Screenshots or Video
+#### Screenshots or Video
 
-## Accessibility Impact
+#### Accessibility Impact
 
-## Tests
+#### Tests
+
+#### Manual Testing
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2. **Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Infra/Build
 
 ```md
-## Summary
+#### Summary
 
-## Environments Affected
+#### Environments Affected
 
-## Validation Steps
+#### Validation Steps
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Security
 
 ```md
-## Summary
+#### Summary
 
-## Risk Summary
+#### Risk Summary
 
-## Repro Steps
+#### Repro Steps
 
-## Mitigation or Fix
+#### Mitigation or Fix
 
-## Verification
+#### Verification
 
-## Tests
+#### Tests
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```

docs/help/submitting-an-issue.md

@@ -1,165 +1,152 @@
 ---
-summary: "How to file high signal issues and bug reports"
+summary: "Filing high-signal issues and bug reports"
 title: "Submitting an Issue"
 ---
 
-# 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.
+Clear, concise issues speed up diagnosis and fixes. Include the following for bugs, regressions, or feature gaps:
 
-## What makes a good issue
+### What to include
 
-- [ ] Clear title: include the area and the symptom.
+- [ ] Title: area & symptom
-- [ ] Repro steps: minimal steps that consistently reproduce the issue.
+- [ ] Minimal repro steps
-- [ ] Expected vs actual: what you thought would happen and what did.
+- [ ] Expected vs actual
-- [ ] Impact: who is affected and how severe the problem is.
+- [ ] Impact & severity
-- [ ] Environment: OS, runtime, versions, and relevant config.
+- [ ] Environment: OS, runtime, versions, config
-- [ ] Evidence: logs, screenshots, or recordings (redacted; prefer non-PII data).
+- [ ] Evidence: redacted logs, screenshots (non-PII)
-- [ ] Scope: note if it is new, regression, or long-standing.
+- [ ] Scope: new, regression, or longstanding
-- [ ] Code word: include “lobster-biscuit” somewhere in the issue description to confirm you read this guide.
+- [ ] Code word: lobster-biscuit in your issue
-- [ ] Due diligence: search the codebase for existing functionality and check GitHub to see if the issue is already filed or fixed.
+- [ ] Searched codebase & GitHub for existing issue
-- [ ] I searched for existing and recently closed issues/PRs.
+- [ ] Confirmed not recently fixed/addressed (esp. security)
-- [ ] For security reports: confirmed it has not already been fixed or addressed recently.
+- [ ] Claims backed by evidence or repro
-- [ ] Grounded in reality: claims should be backed by evidence, reproduction, or direct observation.
 
-Guideline: concision > grammar. Be terse if it makes review faster.
+Be brief. Terseness > perfect grammar.
 
-Baseline validation commands (run as appropriate for the change, and fix failures before submitting a PR):
+Validation (run/fix before PR):
 
 - `pnpm lint`
 - `pnpm check`
 - `pnpm build`
 - `pnpm test`
-- If you touch protocol code: `pnpm protocol:check`
+- If protocol code: `pnpm protocol:check`
 
-## Templates
+### Templates
 
-### Bug report
+#### Bug report
 
 ```md
-## Bug report checklist
+- [ ] Minimal repro
-
-- [ ] Minimal repro steps
 - [ ] Expected vs actual
-- [ ] Versions and environment
+- [ ] Environment
-- [ ] Affected channels and where it does not reproduce
+- [ ] Affected channels, where not seen
-- [ ] Logs or screenshots
+- [ ] Logs/screenshots (redacted)
-- [ ] Evidence is redacted and non-PII where possible
+- [ ] Impact/severity
-- [ ] Impact and severity
+- [ ] Workarounds
-- [ ] Any known workarounds
 
-## Summary
+### Summary
 
-## Repro Steps
+### Repro Steps
 
-## Expected
+### Expected
 
-## Actual
+### Actual
 
-## Environment
+### Environment
 
-## Logs or Evidence
+### Logs/Evidence
 
-## Impact
+### Impact
 
-## Workarounds
+### Workarounds
 ```
 
-### Security issue
+#### Security issue
 
 ```md
-## Summary
+### Summary
 
-## Impact
+### Impact
 
-## Affected Versions
+### Versions
 
-## Repro Steps (if safe to share)
+### Repro Steps (safe to share)
 
-## Mitigation or Workaround
+### Mitigation/workaround
 
-## Evidence (redacted)
+### 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.
+_Avoid secrets/exploit details in public. For sensitive issues, minimize detail and request private disclosure._
 
-### Regression report
+#### Regression report
 
 ```md
-## Summary
+### Summary
 
-## Last Known Good
+### Last Known Good
 
-## First Known Bad
+### First Known Bad
 
-## Repro Steps
+### Repro Steps
 
-## Expected
+### Expected
 
-## Actual
+### Actual
 
-## Environment
+### Environment
 
-## Logs or Evidence
+### Logs/Evidence
 
-## Impact
+### Impact
 ```
 
-### Feature request
+#### Feature request
 
 ```md
-## Summary
+### Summary
 
-## Problem
+### Problem
 
-## Proposed Solution
+### Proposed Solution
 
-## Alternatives Considered
+### Alternatives
 
-## Impact
+### Impact
 
-## Evidence or Examples
+### Evidence/examples
 ```
 
-### Enhancement request
+#### Enhancement
 
 ```md
-## Summary
+### Summary
 
-## Current Behavior
+### Current vs Desired Behavior
 
-## Desired Behavior
+### Rationale
 
-## Why This Matters
+### Alternatives
 
-## Alternatives Considered
+### Evidence/examples
-
-## Evidence or Examples
 ```
 
-### Investigation request
+#### Investigation
 
 ```md
-## Summary
+### Summary
 
-## Symptoms
+### Symptoms
 
-## What Was Tried
+### What Was Tried
 
-## Environment
+### Environment
 
-## Logs or Evidence
+### Logs/Evidence
 
-## Impact
+### Impact
 ```
 
-## If you are submitting a fix PR
+### Submitting a fix PR
 
-Creating a separate issue first is optional. If you skip it, include the relevant details in the PR description.
+Issue before PR is optional. Include details in PR if skipping. Keep the PR focused, note issue number, add tests or explain absence, document behavior changes/risks, include redacted logs/screenshots as proof, and run proper validation before submitting.
-
-- 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/help/troubleshooting.md

@@ -65,7 +65,7 @@ You can also set `OPENCLAW_VERBOSE=1` instead of the flag.
 Some Comcast/Xfinity connections block `docs.openclaw.ai` via Xfinity Advanced Security.
 Disable Advanced Security or add `docs.openclaw.ai` to the allowlist, then retry.
 
-- Xfinity Advanced Security help: https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security
+- Xfinity Advanced Security help: [https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security](https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security)
 - Quick sanity checks: try a mobile hotspot or VPN to confirm it’s ISP-level filtering
 
 ### Service says running, but RPC probe fails

docs/hooks.md

@@ -444,7 +444,7 @@ openclaw hooks enable session-memory
 openclaw hooks disable command-logger
 ```
 
-## Bundled Hooks
+## Bundled hook reference
 
 ### session-memory
 
@@ -787,6 +787,7 @@ Session reset
    ```
 
 3. List all discovered hooks:
+
    ```bash
    openclaw hooks list
    ```
@@ -818,6 +819,7 @@ Look for missing:
 2. Restart your gateway process so hooks reload.
 
 3. Check gateway logs for errors:
+
    ```bash
    ./scripts/clawlog.sh | grep hook
    ```
@@ -892,6 +894,7 @@ node -e "import('./path/to/handler.ts').then(console.log)"
    ```
 
 4. Verify and restart your gateway process:
+
    ```bash
    openclaw hooks list
    # Should show: 🎯 my-hook ✓

docs/index.md

@@ -120,7 +120,7 @@ Need the full install and dev setup? See [Quick start](/start/quickstart).
 
 Open the browser Control UI after the Gateway starts.
 
-- Local default: http://127.0.0.1:18789/
+- Local default: [http://127.0.0.1:18789/](http://127.0.0.1:18789/)
 - Remote access: [Web surfaces](/web) and [Tailscale](/gateway/tailscale)
 
 <p align="center">

docs/install/gcp.md

@@ -69,7 +69,7 @@ For the generic Docker flow, see [Docker](/install/docker).
 
 **Option A: gcloud CLI** (recommended for automation)
 
-Install from https://cloud.google.com/sdk/docs/install
+Install from [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install)
 
 Initialize and authenticate:
 
@@ -80,7 +80,7 @@ gcloud auth login
 
 **Option B: Cloud Console**
 
-All steps can be done via the web UI at https://console.cloud.google.com
+All steps can be done via the web UI at [https://console.cloud.google.com](https://console.cloud.google.com)
 
 ---
 
@@ -93,7 +93,7 @@ gcloud projects create my-openclaw-project --name="OpenClaw Gateway"
 gcloud config set project my-openclaw-project
 ```
 
-Enable billing at https://console.cloud.google.com/billing (required for Compute Engine).
+Enable billing at [https://console.cloud.google.com/billing](https://console.cloud.google.com/billing) (required for Compute Engine).
 
 Enable the Compute Engine API:
 
@@ -484,6 +484,7 @@ For automation or CI/CD pipelines, create a dedicated service account with minim
    ```
 
 2. Grant Compute Instance Admin role (or narrower custom role):
+
    ```bash
    gcloud projects add-iam-policy-binding my-openclaw-project \
      --member="serviceAccount:openclaw-deploy@my-openclaw-project.iam.gserviceaccount.com" \
@@ -492,7 +493,7 @@ For automation or CI/CD pipelines, create a dedicated service account with minim
 
 Avoid using the Owner role for automation. Use the principle of least privilege.
 
-See https://cloud.google.com/iam/docs/understanding-roles for IAM role details.
+See [https://cloud.google.com/iam/docs/understanding-roles](https://cloud.google.com/iam/docs/understanding-roles) for IAM role details.
 
 ---
 

docs/install/index.md

@@ -1,163 +1,171 @@
 ---
-summary: "Install OpenClaw (recommended installer, global install, or from source)"
+summary: "Install OpenClaw — installer script, npm/pnpm, from source, Docker, and more"
 read_when:
-  - Installing OpenClaw
+  - You need an install method other than the Getting Started quickstart
-  - You want to install from GitHub
+  - You want to deploy to a cloud platform
-title: "Install Overview"
+  - You need to update, migrate, or uninstall
+title: "Install"
 ---
 
-# Install Overview
+# Install
 
-Use the installer unless you have a reason not to. It sets up the CLI and runs onboarding.
+Already followed [Getting Started](/start/getting-started)? You're all set — this page is for alternative install methods, platform-specific instructions, and maintenance.
-
-## Quick install (recommended)
-
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash
-```
-
-Windows (PowerShell):
-
-```powershell
-iwr -useb https://openclaw.ai/install.ps1 | iex
-```
-
-Next step (if you skipped onboarding):
-
-```bash
-openclaw onboard --install-daemon
-```
 
 ## System requirements
 
-- **Node >=22**
+- **[Node 22+](/install/node)** (the [installer script](#install-methods) will install it if missing)
-- macOS, Linux, or Windows via WSL2
+- macOS, Linux, or Windows
 - `pnpm` only if you build from source
 
-## Choose your install path
+<Note>
+On Windows, we strongly recommend running OpenClaw under [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install).
+</Note>
 
-### 1) Installer script (recommended)
+## Install methods
 
-Installs `openclaw` globally via npm and runs onboarding.
+<Tip>
+The **installer script** is the recommended way to install OpenClaw. It handles Node detection, installation, and onboarding in one step.
+</Tip>
 
+<AccordionGroup>
+  <Accordion title="Installer script" icon="rocket" defaultOpen>
+    Downloads the CLI, installs it globally via npm, and launches the onboarding wizard.
+
+    <Tabs>
+      <Tab title="macOS / Linux / WSL2">
         ```bash
         curl -fsSL https://openclaw.ai/install.sh | bash
         ```
-
+      </Tab>
-Installer flags:
+      <Tab title="Windows (PowerShell)">
-
+        ```powershell
-```bash
+        iwr -useb https://openclaw.ai/install.ps1 | iex
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
         ```
+      </Tab>
+    </Tabs>
 
-Details: [Installer internals](/install/installer).
+    That's it — the script handles Node detection, installation, and onboarding.
 
-Non-interactive (skip onboarding):
+    To skip onboarding and just install the binary:
 
+    <Tabs>
+      <Tab title="macOS / Linux / WSL2">
         ```bash
         curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
         ```
+      </Tab>
+      <Tab title="Windows (PowerShell)">
+        ```powershell
+        & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
+        ```
+      </Tab>
+    </Tabs>
 
-### 2) Global install (manual)
+    For all flags, env vars, and CI/automation options, see [Installer internals](/install/installer).
 
-If you already have Node:
+  </Accordion>
 
+  <Accordion title="npm / pnpm" icon="package">
+    If you already have Node 22+ and prefer to manage the install yourself:
+
+    <Tabs>
+      <Tab title="npm">
         ```bash
         npm install -g openclaw@latest
+        openclaw onboard --install-daemon
         ```
 
-If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails to install, force prebuilt binaries:
+        <Accordion title="sharp build errors?">
+          If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails, force prebuilt binaries:
 
           ```bash
           SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
           ```
 
-If you see `sharp: Please add node-gyp to your dependencies`, either install build tooling (macOS: Xcode CLT + `npm install -g node-gyp`) or use the `SHARP_IGNORE_GLOBAL_LIBVIPS=1` workaround above to skip the native build.
+          If you see `sharp: Please add node-gyp to your dependencies`, either install build tooling (macOS: Xcode CLT + `npm install -g node-gyp`) or use the env var above.
-
+        </Accordion>
-Or with pnpm:
+      </Tab>
-
+      <Tab title="pnpm">
         ```bash
         pnpm add -g openclaw@latest
         pnpm approve-builds -g        # approve openclaw, node-llama-cpp, sharp, etc.
-```
-
-pnpm requires explicit approval for packages with build scripts. After the first install shows the "Ignored build scripts" warning, run `pnpm approve-builds -g` and select the listed packages.
-
-Then:
-
-```bash
         openclaw onboard --install-daemon
         ```
 
-### 3) From source (contributors/dev)
+        <Note>
+        pnpm requires explicit approval for packages with build scripts. After the first install shows the "Ignored build scripts" warning, run `pnpm approve-builds -g` and select the listed packages.
+        </Note>
+      </Tab>
+    </Tabs>
+
+  </Accordion>
+
+  <Accordion title="From source" icon="github">
+    For contributors or anyone who wants to run from a local checkout.
+
+    <Steps>
+      <Step title="Clone and build">
+        Clone the [OpenClaw repo](https://github.com/openclaw/openclaw) and build:
 
         ```bash
         git clone https://github.com/openclaw/openclaw.git
         cd openclaw
         pnpm install
-pnpm ui:build # auto-installs UI deps on first run
+        pnpm ui:build
         pnpm build
-openclaw onboard --install-daemon
+        ```
+      </Step>
+      <Step title="Link the CLI">
+        Make the `openclaw` command available globally:
+
+        ```bash
+        pnpm link --global
         ```
 
-Tip: if you don’t have a global install yet, run repo commands via `pnpm openclaw ...`.
+        Alternatively, skip the link and run commands via `pnpm openclaw ...` from inside the repo.
+      </Step>
+      <Step title="Run onboarding">
+        ```bash
+        openclaw onboard --install-daemon
+        ```
+      </Step>
+    </Steps>
 
     For deeper development workflows, see [Setup](/start/setup).
 
-### 4) Other install options
+  </Accordion>
+</AccordionGroup>
 
-- Docker: [Docker](/install/docker)
+## Other install methods
-- Nix: [Nix](/install/nix)
+
-- Ansible: [Ansible](/install/ansible)
+<CardGroup cols={2}>
-- Bun (CLI only): [Bun](/install/bun)
+  <Card title="Docker" href="/install/docker" icon="container">
+    Containerized or headless deployments.
+  </Card>
+  <Card title="Nix" href="/install/nix" icon="snowflake">
+    Declarative install via Nix.
+  </Card>
+  <Card title="Ansible" href="/install/ansible" icon="server">
+    Automated fleet provisioning.
+  </Card>
+  <Card title="Bun" href="/install/bun" icon="zap">
+    CLI-only usage via the Bun runtime.
+  </Card>
+</CardGroup>
 
 ## After install
 
-- Run onboarding: `openclaw onboard --install-daemon`
+Verify everything is working:
-- Quick check: `openclaw doctor`
-- Check gateway health: `openclaw status` + `openclaw health`
-- Open the dashboard: `openclaw dashboard`
-
-## Install method: npm vs git (installer)
-
-The installer supports two methods:
-
-- `npm` (default): `npm install -g openclaw@latest`
-- `git`: clone/build from GitHub and run from a source checkout
-
-### CLI flags
 
 ```bash
-# Explicit npm
+openclaw doctor         # check for config issues
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
+openclaw status         # gateway status
-
+openclaw dashboard      # open the browser UI
-# Install from GitHub (source checkout)
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
 ```
 
-Common flags:
+## Troubleshooting: `openclaw` not found
-
-- `--install-method npm|git`
-- `--git-dir <path>` (default: `~/openclaw`)
-- `--no-git-update` (skip `git pull` when using an existing checkout)
-- `--no-prompt` (disable prompts; required in CI/automation)
-- `--dry-run` (print what would happen; make no changes)
-- `--no-onboard` (skip onboarding)
-
-### Environment variables
-
-Equivalent env vars (useful for automation):
-
-- `OPENCLAW_INSTALL_METHOD=git|npm`
-- `OPENCLAW_GIT_DIR=...`
-- `OPENCLAW_GIT_UPDATE=0|1`
-- `OPENCLAW_NO_PROMPT=1`
-- `OPENCLAW_DRY_RUN=1`
-- `OPENCLAW_NO_ONBOARD=1`
-- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1` (default: `1`; avoids `sharp` building against system libvips)
-
-## Troubleshooting: `openclaw` not found (PATH)
 
+<Accordion title="PATH diagnosis and fix">
   Quick diagnosis:
 
 ```bash
@@ -167,21 +175,29 @@ npm prefix -g
 echo "$PATH"
 ```
 
-If `$(npm prefix -g)/bin` (macOS/Linux) or `$(npm prefix -g)` (Windows) is **not** present inside `echo "$PATH"`, your shell can’t find global npm binaries (including `openclaw`).
+If `$(npm prefix -g)/bin` (macOS/Linux) or `$(npm prefix -g)` (Windows) is **not** in your `$PATH`, your shell can't find global npm binaries (including `openclaw`).
 
-Fix: add it to your shell startup file (zsh: `~/.zshrc`, bash: `~/.bashrc`):
+Fix — add it to your shell startup file (`~/.zshrc` or `~/.bashrc`):
 
 ```bash
-# macOS / Linux
 export PATH="$(npm prefix -g)/bin:$PATH"
 ```
 
 On Windows, add the output of `npm prefix -g` to your PATH.
 
 Then open a new terminal (or `rehash` in zsh / `hash -r` in bash).
+</Accordion>
 
 ## Update / uninstall
 
-- Updates: [Updating](/install/updating)
+<CardGroup cols={3}>
-- Migrate to a new machine: [Migrating](/install/migrating)
+  <Card title="Updating" href="/install/updating" icon="refresh-cw">
-- Uninstall: [Uninstall](/install/uninstall)
+    Keep OpenClaw up to date.
+  </Card>
+  <Card title="Migrating" href="/install/migrating" icon="arrow-right">
+    Move to a new machine.
+  </Card>
+  <Card title="Uninstall" href="/install/uninstall" icon="trash-2">
+    Remove OpenClaw completely.
+  </Card>
+</CardGroup>

docs/install/installer.md

@@ -1,5 +1,5 @@
 ---
-summary: "How the installer scripts work (install.sh + install-cli.sh), flags, and automation"
+summary: "How the installer scripts work (install.sh, install-cli.sh, install.ps1), flags, and automation"
 read_when:
   - You want to understand `openclaw.ai/install.sh`
   - You want to automate installs (CI / headless)
@@ -9,115 +9,377 @@ title: "Installer Internals"
 
 # Installer internals
 
-OpenClaw ships two installer scripts (served from `openclaw.ai`):
+OpenClaw ships three installer scripts, served from `openclaw.ai`.
 
-- `https://openclaw.ai/install.sh` — “recommended” installer (global npm install by default; can also install from a GitHub checkout)
+| Script                             | Platform             | What it does                                                                                 |
-- `https://openclaw.ai/install-cli.sh` — non-root-friendly CLI installer (installs into a prefix with its own Node)
+| ---------------------------------- | -------------------- | -------------------------------------------------------------------------------------------- |
-- `https://openclaw.ai/install.ps1` — Windows PowerShell installer (npm by default; optional git install)
+| [`install.sh`](#installsh)         | macOS / Linux / WSL  | Installs Node if needed, installs OpenClaw via npm (default) or git, and can run onboarding. |
+| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL  | Installs Node + OpenClaw into a local prefix (`~/.openclaw`). No root required.              |
+| [`install.ps1`](#installps1)       | Windows (PowerShell) | Installs Node if needed, installs OpenClaw via npm (default) or git, and can run onboarding. |
 
-To see the current flags/behavior, run:
+## Quick commands
+
+<Tabs>
+  <Tab title="install.sh">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
+    ```
 
     ```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help
     ```
 
-Windows (PowerShell) help:
+  </Tab>
-
+  <Tab title="install-cli.sh">
-```powershell
+    ```bash
-& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -?
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
     ```
 
-If the installer completes but `openclaw` is not found in a new terminal, it’s usually a Node/npm PATH issue. See: [Install](/install#nodejs--npm-path-sanity).
-
-## install.sh (recommended)
-
-What it does (high level):
-
-- Detect OS (macOS / Linux / WSL).
-- Ensure Node.js **22+** (macOS via Homebrew; Linux via NodeSource).
-- Choose install method:
-  - `npm` (default): `npm install -g openclaw@latest`
-  - `git`: clone/build a source checkout and install a wrapper script
-- On Linux: avoid global npm permission errors by switching npm's prefix to `~/.npm-global` when needed.
-- If upgrading an existing install: runs `openclaw doctor --non-interactive` (best effort).
-- For git installs: runs `openclaw doctor --non-interactive` after install/update (best effort).
-- Mitigates `sharp` native install gotchas by defaulting `SHARP_IGNORE_GLOBAL_LIBVIPS=1` (avoids building against system libvips).
-
-If you _want_ `sharp` to link against a globally-installed libvips (or you’re debugging), set:
-
     ```bash
-SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help
     ```
 
-### Discoverability / “git install” prompt
+  </Tab>
-
+  <Tab title="install.ps1">
-If you run the installer while **already inside a OpenClaw source checkout** (detected via `package.json` + `pnpm-workspace.yaml`), it prompts:
-
-- update and use this checkout (`git`)
-- or migrate to the global npm install (`npm`)
-
-In non-interactive contexts (no TTY / `--no-prompt`), you must pass `--install-method git|npm` (or set `OPENCLAW_INSTALL_METHOD`), otherwise the script exits with code `2`.
-
-### Why Git is needed
-
-Git is required for the `--install-method git` path (clone / pull).
-
-For `npm` installs, Git is _usually_ not required, but some environments still end up needing it (e.g. when a package or dependency is fetched via a git URL). The installer currently ensures Git is present to avoid `spawn git ENOENT` surprises on fresh distros.
-
-### Why npm hits `EACCES` on fresh Linux
-
-On some Linux setups (especially after installing Node via the system package manager or NodeSource), npm's global prefix points at a root-owned location. Then `npm install -g ...` fails with `EACCES` / `mkdir` permission errors.
-
-`install.sh` mitigates this by switching the prefix to:
-
-- `~/.npm-global` (and adding it to `PATH` in `~/.bashrc` / `~/.zshrc` when present)
-
-## install-cli.sh (non-root CLI installer)
-
-This script installs `openclaw` into a prefix (default: `~/.openclaw`) and also installs a dedicated Node runtime under that prefix, so it can work on machines where you don’t want to touch the system Node/npm.
-
-Help:
-
-```bash
-curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help
-```
-
-## install.ps1 (Windows PowerShell)
-
-What it does (high level):
-
-- Ensure Node.js **22+** (winget/Chocolatey/Scoop or manual).
-- Choose install method:
-  - `npm` (default): `npm install -g openclaw@latest`
-  - `git`: clone/build a source checkout and install a wrapper script
-- Runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort).
-
-Examples:
-
     ```powershell
     iwr -useb https://openclaw.ai/install.ps1 | iex
     ```
 
     ```powershell
-iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
     ```
 
+  </Tab>
+</Tabs>
+
+<Note>
+If install succeeds but `openclaw` is not found in a new terminal, see [Node.js troubleshooting](/install/node#troubleshooting).
+</Note>
+
+---
+
+## install.sh
+
+<Tip>
+Recommended for most interactive installs on macOS/Linux/WSL.
+</Tip>
+
+### Flow (install.sh)
+
+<Steps>
+  <Step title="Detect OS">
+    Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing.
+  </Step>
+  <Step title="Ensure Node.js 22+">
+    Checks Node version and installs Node 22 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum).
+  </Step>
+  <Step title="Ensure Git">
+    Installs Git if missing.
+  </Step>
+  <Step title="Install OpenClaw">
+    - `npm` method (default): global npm install
+    - `git` method: clone/update repo, install deps with pnpm, build, then install wrapper at `~/.local/bin/openclaw`
+  </Step>
+  <Step title="Post-install tasks">
+    - Runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort)
+    - Attempts onboarding when appropriate (TTY available, onboarding not disabled, and bootstrap/config checks pass)
+    - Defaults `SHARP_IGNORE_GLOBAL_LIBVIPS=1`
+  </Step>
+</Steps>
+
+### Source checkout detection
+
+If run inside an OpenClaw checkout (`package.json` + `pnpm-workspace.yaml`), the script offers:
+
+- use checkout (`git`), or
+- use global install (`npm`)
+
+If no TTY is available and no install method is set, it defaults to `npm` and warns.
+
+The script exits with code `2` for invalid method selection or invalid `--install-method` values.
+
+### Examples (install.sh)
+
+<Tabs>
+  <Tab title="Default">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
+    ```
+  </Tab>
+  <Tab title="Skip onboarding">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard
+    ```
+  </Tab>
+  <Tab title="Git install">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
+    ```
+  </Tab>
+  <Tab title="Dry run">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run
+    ```
+  </Tab>
+</Tabs>
+
+<AccordionGroup>
+  <Accordion title="Flags reference">
+
+| Flag                            | Description                                                |
+| ------------------------------- | ---------------------------------------------------------- |
+| `--install-method npm\|git`     | Choose install method (default: `npm`). Alias: `--method`  |
+| `--npm`                         | Shortcut for npm method                                    |
+| `--git`                         | Shortcut for git method. Alias: `--github`                 |
+| `--version <version\|dist-tag>` | npm version or dist-tag (default: `latest`)                |
+| `--beta`                        | Use beta dist-tag if available, else fallback to `latest`  |
+| `--git-dir <path>`              | Checkout directory (default: `~/openclaw`). Alias: `--dir` |
+| `--no-git-update`               | Skip `git pull` for existing checkout                      |
+| `--no-prompt`                   | Disable prompts                                            |
+| `--no-onboard`                  | Skip onboarding                                            |
+| `--onboard`                     | Enable onboarding                                          |
+| `--dry-run`                     | Print actions without applying changes                     |
+| `--verbose`                     | Enable debug output (`set -x`, npm notice-level logs)      |
+| `--help`                        | Show usage (`-h`)                                          |
+
+  </Accordion>
+
+  <Accordion title="Environment variables reference">
+
+| Variable                                    | Description                                   |
+| ------------------------------------------- | --------------------------------------------- |
+| `OPENCLAW_INSTALL_METHOD=git\|npm`          | Install method                                |
+| `OPENCLAW_VERSION=latest\|next\|<semver>`   | npm version or dist-tag                       |
+| `OPENCLAW_BETA=0\|1`                        | Use beta if available                         |
+| `OPENCLAW_GIT_DIR=<path>`                   | Checkout directory                            |
+| `OPENCLAW_GIT_UPDATE=0\|1`                  | Toggle git updates                            |
+| `OPENCLAW_NO_PROMPT=1`                      | Disable prompts                               |
+| `OPENCLAW_NO_ONBOARD=1`                     | Skip onboarding                               |
+| `OPENCLAW_DRY_RUN=1`                        | Dry run mode                                  |
+| `OPENCLAW_VERBOSE=1`                        | Debug mode                                    |
+| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level                                 |
+| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`          | Control sharp/libvips behavior (default: `1`) |
+
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## install-cli.sh
+
+<Info>
+Designed for environments where you want everything under a local prefix (default `~/.openclaw`) and no system Node dependency.
+</Info>
+
+### Flow (install-cli.sh)
+
+<Steps>
+  <Step title="Install local Node runtime">
+    Downloads Node tarball (default `22.22.0`) to `<prefix>/tools/node-v<version>` and verifies SHA-256.
+  </Step>
+  <Step title="Ensure Git">
+    If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on macOS.
+  </Step>
+  <Step title="Install OpenClaw under prefix">
+    Installs with npm using `--prefix <prefix>`, then writes wrapper to `<prefix>/bin/openclaw`.
+  </Step>
+</Steps>
+
+### Examples (install-cli.sh)
+
+<Tabs>
+  <Tab title="Default">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
+    ```
+  </Tab>
+  <Tab title="Custom prefix + version">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest
+    ```
+  </Tab>
+  <Tab title="Automation JSON output">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
+    ```
+  </Tab>
+  <Tab title="Run onboarding">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard
+    ```
+  </Tab>
+</Tabs>
+
+<AccordionGroup>
+  <Accordion title="Flags reference">
+
+| Flag                   | Description                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| `--prefix <path>`      | Install prefix (default: `~/.openclaw`)                                         |
+| `--version <ver>`      | OpenClaw version or dist-tag (default: `latest`)                                |
+| `--node-version <ver>` | Node version (default: `22.22.0`)                                               |
+| `--json`               | Emit NDJSON events                                                              |
+| `--onboard`            | Run `openclaw onboard` after install                                            |
+| `--no-onboard`         | Skip onboarding (default)                                                       |
+| `--set-npm-prefix`     | On Linux, force npm prefix to `~/.npm-global` if current prefix is not writable |
+| `--help`               | Show usage (`-h`)                                                               |
+
+  </Accordion>
+
+  <Accordion title="Environment variables reference">
+
+| Variable                                    | Description                                                                       |
+| ------------------------------------------- | --------------------------------------------------------------------------------- |
+| `OPENCLAW_PREFIX=<path>`                    | Install prefix                                                                    |
+| `OPENCLAW_VERSION=<ver>`                    | OpenClaw version or dist-tag                                                      |
+| `OPENCLAW_NODE_VERSION=<ver>`               | Node version                                                                      |
+| `OPENCLAW_NO_ONBOARD=1`                     | Skip onboarding                                                                   |
+| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level                                                                     |
+| `OPENCLAW_GIT_DIR=<path>`                   | Legacy cleanup lookup path (used when removing old `Peekaboo` submodule checkout) |
+| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`          | Control sharp/libvips behavior (default: `1`)                                     |
+
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## install.ps1
+
+### Flow (install.ps1)
+
+<Steps>
+  <Step title="Ensure PowerShell + Windows environment">
+    Requires PowerShell 5+.
+  </Step>
+  <Step title="Ensure Node.js 22+">
+    If missing, attempts install via winget, then Chocolatey, then Scoop.
+  </Step>
+  <Step title="Install OpenClaw">
+    - `npm` method (default): global npm install using selected `-Tag`
+    - `git` method: clone/update repo, install/build with pnpm, and install wrapper at `%USERPROFILE%\.local\bin\openclaw.cmd`
+  </Step>
+  <Step title="Post-install tasks">
+    Adds needed bin directory to user PATH when possible, then runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort).
+  </Step>
+</Steps>
+
+### Examples (install.ps1)
+
+<Tabs>
+  <Tab title="Default">
     ```powershell
-iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw"
+    iwr -useb https://openclaw.ai/install.ps1 | iex
+    ```
+  </Tab>
+  <Tab title="Git install">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git
+    ```
+  </Tab>
+  <Tab title="Custom git directory">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"
+    ```
+  </Tab>
+  <Tab title="Dry run">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun
+    ```
+  </Tab>
+</Tabs>
+
+<AccordionGroup>
+  <Accordion title="Flags reference">
+
+| Flag                      | Description                                            |
+| ------------------------- | ------------------------------------------------------ |
+| `-InstallMethod npm\|git` | Install method (default: `npm`)                        |
+| `-Tag <tag>`              | npm dist-tag (default: `latest`)                       |
+| `-GitDir <path>`          | Checkout directory (default: `%USERPROFILE%\openclaw`) |
+| `-NoOnboard`              | Skip onboarding                                        |
+| `-NoGitUpdate`            | Skip `git pull`                                        |
+| `-DryRun`                 | Print actions only                                     |
+
+  </Accordion>
+
+  <Accordion title="Environment variables reference">
+
+| Variable                           | Description        |
+| ---------------------------------- | ------------------ |
+| `OPENCLAW_INSTALL_METHOD=git\|npm` | Install method     |
+| `OPENCLAW_GIT_DIR=<path>`          | Checkout directory |
+| `OPENCLAW_NO_ONBOARD=1`            | Skip onboarding    |
+| `OPENCLAW_GIT_UPDATE=0`            | Disable git pull   |
+| `OPENCLAW_DRY_RUN=1`               | Dry run mode       |
+
+  </Accordion>
+</AccordionGroup>
+
+<Note>
+If `-InstallMethod git` is used and Git is missing, the script exits and prints the Git for Windows link.
+</Note>
+
+---
+
+## CI and automation
+
+Use non-interactive flags/env vars for predictable runs.
+
+<Tabs>
+  <Tab title="install.sh (non-interactive npm)">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard
+    ```
+  </Tab>
+  <Tab title="install.sh (non-interactive git)">
+    ```bash
+    OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
+      curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
+    ```
+  </Tab>
+  <Tab title="install-cli.sh (JSON)">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
+    ```
+  </Tab>
+  <Tab title="install.ps1 (skip onboarding)">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
+    ```
+  </Tab>
+</Tabs>
+
+---
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Why is Git required?">
+    Git is required for `git` install method. For `npm` installs, Git is still checked/installed to avoid `spawn git ENOENT` failures when dependencies use git URLs.
+  </Accordion>
+
+  <Accordion title="Why does npm hit EACCES on Linux?">
+    Some Linux setups point npm global prefix to root-owned paths. `install.sh` can switch prefix to `~/.npm-global` and append PATH exports to shell rc files (when those files exist).
+  </Accordion>
+
+  <Accordion title="sharp/libvips issues">
+    The scripts default `SHARP_IGNORE_GLOBAL_LIBVIPS=1` to avoid sharp building against system libvips. To override:
+
+    ```bash
+    SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
     ```
 
-Environment variables:
+  </Accordion>
 
-- `OPENCLAW_INSTALL_METHOD=git|npm`
+  <Accordion title='Windows: "npm error spawn git / ENOENT"'>
-- `OPENCLAW_GIT_DIR=...`
+    Install Git for Windows, reopen PowerShell, rerun installer.
+  </Accordion>
 
-Git requirement:
+  <Accordion title='Windows: "openclaw is not recognized"'>
+    Run `npm config get prefix`, append `\bin`, add that directory to user PATH, then reopen PowerShell.
+  </Accordion>
 
-If you choose `-InstallMethod git` and Git is missing, the installer will print the
+  <Accordion title="openclaw not found after install">
-Git for Windows link (`https://git-scm.com/download/win`) and exit.
+    Usually a PATH issue. See [Node.js troubleshooting](/install/node#troubleshooting).
-
+  </Accordion>
-Common Windows issues:
+</AccordionGroup>
-
-- **npm error spawn git / ENOENT**: install Git for Windows and reopen PowerShell, then rerun the installer.
-- **"openclaw" is not recognized**: your npm global bin folder is not on PATH. Most systems use
-  `%AppData%\\npm`. You can also run `npm config get prefix` and add `\\bin` to PATH, then reopen PowerShell.

docs/install/node.md

@@ -1,58 +1,133 @@
 ---
-title: "Node.js + npm (PATH sanity)"
+title: "Node.js"
-summary: "Node.js + npm install sanity: versions, PATH, and global installs"
+summary: "Install and configure Node.js for OpenClaw — version requirements, install options, and PATH troubleshooting"
 read_when:
-  - "You installed OpenClaw but `openclaw` is “command not found”"
+  - "You need to install Node.js before installing OpenClaw"
-  - "You’re setting up Node.js/npm on a new machine"
+  - "You installed OpenClaw but `openclaw` is command not found"
-  - "npm install -g ... fails with permissions or PATH issues"
+  - "npm install -g fails with permissions or PATH issues"
 ---
 
-# Node.js + npm (PATH sanity)
+# Node.js
 
-OpenClaw’s runtime baseline is **Node 22+**.
+OpenClaw requires **Node 22 or newer**. The [installer script](/install#install-methods) will detect and install Node automatically — this page is for when you want to set up Node yourself and make sure everything is wired up correctly (versions, PATH, global installs).
 
-If you can run `npm install -g openclaw@latest` but later see `openclaw: command not found`, it’s almost always a **PATH** issue: the directory where npm puts global binaries isn’t on your shell’s PATH.
+## Check your version
-
-## Quick diagnosis
-
-Run:
 
 ```bash
 node -v
-npm -v
+```
+
+If this prints `v22.x.x` or higher, you're good. If Node isn't installed or the version is too old, pick an install method below.
+
+## Install Node
+
+<Tabs>
+  <Tab title="macOS">
+    **Homebrew** (recommended):
+
+    ```bash
+    brew install node
+    ```
+
+    Or download the macOS installer from [nodejs.org](https://nodejs.org/).
+
+  </Tab>
+  <Tab title="Linux">
+    **Ubuntu / Debian:**
+
+    ```bash
+    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+    sudo apt-get install -y nodejs
+    ```
+
+    **Fedora / RHEL:**
+
+    ```bash
+    sudo dnf install nodejs
+    ```
+
+    Or use a version manager (see below).
+
+  </Tab>
+  <Tab title="Windows">
+    **winget** (recommended):
+
+    ```powershell
+    winget install OpenJS.NodeJS.LTS
+    ```
+
+    **Chocolatey:**
+
+    ```powershell
+    choco install nodejs-lts
+    ```
+
+    Or download the Windows installer from [nodejs.org](https://nodejs.org/).
+
+  </Tab>
+</Tabs>
+
+<Accordion title="Using a version manager (nvm, fnm, mise, asdf)">
+  Version managers let you switch between Node versions easily. Popular options:
+
+- [**fnm**](https://github.com/Schniz/fnm) — fast, cross-platform
+- [**nvm**](https://github.com/nvm-sh/nvm) — widely used on macOS/Linux
+- [**mise**](https://mise.jdx.dev/) — polyglot (Node, Python, Ruby, etc.)
+
+Example with fnm:
+
+```bash
+fnm install 22
+fnm use 22
+```
+
+  <Warning>
+  Make sure your version manager is initialized in your shell startup file (`~/.zshrc` or `~/.bashrc`). If it isn't, `openclaw` may not be found in new terminal sessions because the PATH won't include Node's bin directory.
+  </Warning>
+</Accordion>
+
+## Troubleshooting
+
+### `openclaw: command not found`
+
+This almost always means npm's global bin directory isn't on your PATH.
+
+<Steps>
+  <Step title="Find your global npm prefix">
+    ```bash
     npm prefix -g
+    ```
+  </Step>
+  <Step title="Check if it's on your PATH">
+    ```bash
     echo "$PATH"
     ```
 
-If `$(npm prefix -g)/bin` (macOS/Linux) or `$(npm prefix -g)` (Windows) is **not** present inside `echo "$PATH"`, your shell can’t find global npm binaries (including `openclaw`).
+    Look for `<npm-prefix>/bin` (macOS/Linux) or `<npm-prefix>` (Windows) in the output.
 
-## Fix: put npm’s global bin dir on PATH
+  </Step>
-
+  <Step title="Add it to your shell startup file">
-1. Find your global npm prefix:
+    <Tabs>
+      <Tab title="macOS / Linux">
+        Add to `~/.zshrc` or `~/.bashrc`:
 
         ```bash
-npm prefix -g
+        export PATH="$(npm prefix -g)/bin:$PATH"
         ```
 
-2. Add the global npm bin directory to your shell startup file:
+        Then open a new terminal (or run `rehash` in zsh / `hash -r` in bash).
+      </Tab>
+      <Tab title="Windows">
+        Add the output of `npm prefix -g` to your system PATH via Settings → System → Environment Variables.
+      </Tab>
+    </Tabs>
 
-- zsh: `~/.zshrc`
+  </Step>
-- bash: `~/.bashrc`
+</Steps>
 
-Example (replace the path with your `npm prefix -g` output):
+### Permission errors on `npm install -g` (Linux)
 
-```bash
+If you see `EACCES` errors, switch npm's global prefix to a user-writable directory:
-# macOS / Linux
-export PATH="/path/from/npm/prefix/bin:$PATH"
-```
-
-Then open a **new terminal** (or run `rehash` in zsh / `hash -r` in bash).
-
-On Windows, add the output of `npm prefix -g` to your PATH.
-
-## Fix: avoid `sudo npm install -g` / permission errors (Linux)
-
-If `npm install -g ...` fails with `EACCES`, switch npm’s global prefix to a user-writable directory:
 
 ```bash
 mkdir -p "$HOME/.npm-global"
@@ -60,19 +135,4 @@ npm config set prefix "$HOME/.npm-global"
 export PATH="$HOME/.npm-global/bin:$PATH"
 ```
 
-Persist the `export PATH=...` line in your shell startup file.
+Add the `export PATH=...` line to your `~/.bashrc` or `~/.zshrc` to make it permanent.
-
-## Recommended Node install options
-
-You’ll have the fewest surprises if Node/npm are installed in a way that:
-
-- keeps Node updated (22+)
-- makes the global npm bin dir stable and on PATH in new shells
-
-Common choices:
-
-- macOS: Homebrew (`brew install node`) or a version manager
-- Linux: your preferred version manager, or a distro-supported install that provides Node 22+
-- Windows: official Node installer, `winget`, or a Windows Node version manager
-
-If you use a version manager (nvm/fnm/asdf/etc), ensure it’s initialized in the shell you use day-to-day (zsh vs bash) so the PATH it sets is present when you run installers.

docs/install/northflank.mdx

@@ -45,7 +45,7 @@ If Telegram DMs are set to pairing, the setup wizard can approve the pairing cod
 
 ### Discord bot token
 
-1. Go to https://discord.com/developers/applications
+1. Go to [https://discord.com/developers/applications](https://discord.com/developers/applications)
 2. **New Application** → choose a name
 3. **Bot** → **Add Bot**
 4. **Enable MESSAGE CONTENT INTENT** under Bot → Privileged Gateway Intents (required or the bot will crash on startup)

docs/install/railway.mdx

@@ -83,7 +83,7 @@ If Telegram DMs are set to pairing, the setup wizard can approve the pairing cod
 
 ### Discord bot token
 
-1. Go to https://discord.com/developers/applications
+1. Go to [https://discord.com/developers/applications](https://discord.com/developers/applications)
 2. **New Application** → choose a name
 3. **Bot** → **Add Bot**
 4. **Enable MESSAGE CONTENT INTENT** under Bot → Privileged Gateway Intents (required or the bot will crash on startup)

docs/install/render.mdx

@@ -11,13 +11,7 @@ Deploy OpenClaw on Render using Infrastructure as Code. The included `render.yam
 
 ## Deploy with a Render Blueprint
 
-<a
+[Deploy to Render](https://render.com/deploy?repo=https://github.com/openclaw/openclaw)
-  href="https://render.com/deploy?repo=https://github.com/openclaw/openclaw"
-  target="_blank"
-  rel="noreferrer"
->
-  Deploy to Render
-</a>
 
 Clicking this link will:
 

docs/install/updating.md

@@ -24,10 +24,13 @@ Notes:
 
 - Add `--no-onboard` if you don’t want the onboarding wizard to run again.
 - For **source installs**, use:
+
   ```bash
   curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard
   ```
+
   The installer will `git pull --rebase` **only** if the repo is clean.
+
 - For **global installs**, the script uses `npm install -g openclaw@latest` under the hood.
 - Legacy note: `clawdbot` remains available as a compatibility shim.
 
@@ -225,4 +228,4 @@ git pull
 
 - Run `openclaw doctor` again and read the output carefully (it often tells you the fix).
 - Check: [Troubleshooting](/gateway/troubleshooting)
-- Ask in Discord: https://discord.gg/clawd
+- Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd)

docs/multi-agent-sandbox-tools.md

@@ -362,6 +362,7 @@ After configuring multi-agent sandbox and tools:
    - Verify the agent cannot use denied tools
 
 4. **Monitor logs:**
+
    ```exec
    tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"
    ```

docs/nodes/camera.md

@@ -81,7 +81,7 @@ Notes:
 
 ## Android node
 
-### User setting (default on)
+### Android user setting (default on)
 
 - Android Settings sheet → **Camera** → **Allow Camera** (`camera.enabled`)
   - Default: **on** (missing key is treated as enabled).
@@ -96,7 +96,7 @@ Notes:
 If permissions are missing, the app will prompt when possible; if denied, `camera.*` requests fail with a
 `*_PERMISSION_REQUIRED` error.
 
-### Foreground requirement
+### Android foreground requirement
 
 Like `canvas.*`, the Android node only allows `camera.*` commands in the **foreground**. Background invocations return `NODE_BACKGROUND_UNAVAILABLE`.
 

docs/perplexity.md

@@ -15,12 +15,12 @@ through Perplexity’s direct API or via OpenRouter.
 
 ### Perplexity (direct)
 
-- Base URL: https://api.perplexity.ai
+- Base URL: [https://api.perplexity.ai](https://api.perplexity.ai)
 - Environment variable: `PERPLEXITY_API_KEY`
 
 ### OpenRouter (alternative)
 
-- Base URL: https://openrouter.ai/api/v1
+- Base URL: [https://openrouter.ai/api/v1](https://openrouter.ai/api/v1)
 - Environment variable: `OPENROUTER_API_KEY`
 - Supports prepaid/crypto credits.
 

docs/pi-dev.md

@@ -66,5 +66,5 @@ If you only want to reset sessions, delete `agents/<agentId>/sessions/` and `age
 
 ## References
 
-- https://docs.openclaw.ai/testing
+- [https://docs.openclaw.ai/testing](https://docs.openclaw.ai/testing)
-- https://docs.openclaw.ai/start/getting-started
+- [https://docs.openclaw.ai/start/getting-started](https://docs.openclaw.ai/start/getting-started)

docs/platforms/android.md

@@ -98,10 +98,13 @@ Pairing details: [Gateway pairing](/gateway/pairing).
 ### 5) Verify the node is connected
 
 - Via nodes status:
+
   ```bash
   openclaw nodes status
   ```
+
 - Via Gateway:
+
   ```bash
   openclaw gateway call node.list --params "{}"
   ```

docs/platforms/mac/dev-setup.md

@@ -35,7 +35,7 @@ To build the macOS app and package it into `dist/OpenClaw.app`, run:
 If you don't have an Apple Developer ID certificate, the script will automatically use **ad-hoc signing** (`-`).
 
 For dev run modes, signing flags, and Team ID troubleshooting, see the macOS app README:
-https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md
+[https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md](https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md)
 
 > **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#troubleshooting) section.
 
@@ -82,9 +82,11 @@ If the app crashes when you try to allow **Speech Recognition** or **Microphone*
 **Fix:**
 
 1. Reset the TCC permissions:
+
    ```bash
    tccutil reset All bot.molt.mac.debug
    ```
+
 2. If that fails, change the `BUNDLE_ID` temporarily in [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) to force a "clean slate" from macOS.
 
 ### Gateway "Starting..." indefinitely

docs/platforms/mac/permissions.md

@@ -40,5 +40,11 @@ sudo tccutil reset ScreenCapture bot.molt.mac
 sudo tccutil reset AppleEvents
 ```
 
+## Files and folders permissions (Desktop/Documents/Downloads)
+
+macOS may also gate Desktop, Documents, and Downloads for terminal/background processes. If file reads or directory listings hang, grant access to the same process context that performs file operations (for example Terminal/iTerm, LaunchAgent-launched app, or SSH process).
+
+Workaround: move files into the OpenClaw workspace (`~/.openclaw/workspace`) if you want to avoid per-folder grants.
+
 If you are testing permissions, always sign with a real certificate. Ad-hoc
 builds are only acceptable for quick local runs where permissions do not matter.

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.4 \
+APP_VERSION=2026.2.6 \
 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.4.zip
+ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.2.6.zip
 
 # Optional: also build a styled DMG for humans (drag to /Applications)
-scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.4.dmg
+scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.6.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.4.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.4 \
+APP_VERSION=2026.2.6 \
 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.4.dSYM.zip
+ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.2.6.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.4.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.6.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.4.zip` (and `OpenClaw-2026.2.4.dSYM.zip`) to the GitHub release for tag `v2026.2.4`.
+- Upload `OpenClaw-2026.2.6.zip` (and `OpenClaw-2026.2.6.dSYM.zip`) to the GitHub release for tag `v2026.2.6`.
 - 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/mac/voice-overlay.md

@@ -9,18 +9,18 @@ title: "Voice Overlay"
 
 Audience: macOS app contributors. Goal: keep the voice overlay predictable when wake-word and push-to-talk overlap.
 
-### Current intent
+## Current intent
 
 - If the overlay is already visible from wake-word and the user presses the hotkey, the hotkey session _adopts_ the existing text instead of resetting it. The overlay stays up while the hotkey is held. When the user releases: send if there is trimmed text, otherwise dismiss.
 - Wake-word alone still auto-sends on silence; push-to-talk sends immediately on release.
 
-### Implemented (Dec 9, 2025)
+## Implemented (Dec 9, 2025)
 
 - Overlay sessions now carry a token per capture (wake-word or push-to-talk). Partial/final/send/dismiss/level updates are dropped when the token doesn’t match, avoiding stale callbacks.
 - Push-to-talk adopts any visible overlay text as a prefix (so pressing the hotkey while the wake overlay is up keeps the text and appends new speech). It waits up to 1.5s for a final transcript before falling back to the current text.
 - Chime/overlay logging is emitted at `info` in categories `voicewake.overlay`, `voicewake.ptt`, and `voicewake.chime` (session start, partial, final, send, dismiss, chime reason).
 
-### Next steps
+## Next steps
 
 1. **VoiceSessionCoordinator (actor)**
    - Owns exactly one `VoiceSession` at a time.
@@ -40,7 +40,7 @@ Audience: macOS app contributors. Goal: keep the voice overlay predictable when
    - Coordinator emits `.info` logs in subsystem `bot.molt`, categories `voicewake.overlay` and `voicewake.chime`.
    - Key events: `session_started`, `adopted_by_push_to_talk`, `partial`, `finalized`, `send`, `dismiss`, `cancel`, `cooldown`.
 
-### Debugging checklist
+## Debugging checklist
 
 - Stream logs while reproducing a sticky overlay:
 
@@ -51,7 +51,7 @@ Audience: macOS app contributors. Goal: keep the voice overlay predictable when
 - Verify only one active session token; stale callbacks should be dropped by the coordinator.
 - Ensure push-to-talk release always calls `endCapture` with the active token; if text is empty, expect `dismiss` without chime or send.
 
-### Migration steps (suggested)
+## Migration steps (suggested)
 
 1. Add `VoiceSessionCoordinator`, `VoiceSession`, and `VoiceSessionPublisher`.
 2. Refactor `VoiceWakeRuntime` to create/update/end sessions instead of touching `VoiceWakeOverlayController` directly.

docs/platforms/mac/webchat.md

@@ -19,9 +19,11 @@ agent (with a session switcher for other sessions).
 
 - Manual: Lobster menu → “Open Chat”.
 - Auto‑open for testing:
+
   ```bash
   dist/OpenClaw.app/Contents/MacOS/OpenClaw --webchat
   ```
+
 - Logs: `./scripts/clawlog.sh` (subsystem `bot.molt`, category `WebChatSwiftUI`).
 
 ## How it’s wired

docs/platforms/windows.md

@@ -20,7 +20,7 @@ Native Windows companion apps are planned.
 
 - [Getting Started](/start/getting-started) (use inside WSL)
 - [Install & updates](/install/updating)
-- Official WSL2 guide (Microsoft): https://learn.microsoft.com/windows/wsl/install
+- Official WSL2 guide (Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
 
 ## Gateway
 

docs/prose.md

@@ -11,7 +11,7 @@ title: "OpenProse"
 
 OpenProse is a portable, markdown-first workflow format for orchestrating AI sessions. In OpenClaw it ships as a plugin that installs an OpenProse skill pack plus a `/prose` slash command. Programs live in `.prose` files and can spawn multiple sub-agents with explicit control flow.
 
-Official site: https://www.prose.md
+Official site: [https://www.prose.md](https://www.prose.md)
 
 ## What it can do
 

docs/providers/anthropic.md

@@ -103,14 +103,14 @@ If you generated the token on a different machine, paste it:
 openclaw models auth paste-token --provider anthropic
 ```
 
-### CLI setup
+### CLI setup (setup-token)
 
 ```bash
 # Paste a setup-token during onboarding
 openclaw onboard --auth-choice setup-token
 ```
 
-### Config snippet
+### Config snippet (setup-token)
 
 ```json5
 {

docs/providers/claude-max-api-proxy.md

@@ -131,9 +131,9 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
 
 ## Links
 
-- **npm:** https://www.npmjs.com/package/claude-max-api-proxy
+- **npm:** [https://www.npmjs.com/package/claude-max-api-proxy](https://www.npmjs.com/package/claude-max-api-proxy)
-- **GitHub:** https://github.com/atalovesyou/claude-max-api-proxy
+- **GitHub:** [https://github.com/atalovesyou/claude-max-api-proxy](https://github.com/atalovesyou/claude-max-api-proxy)
-- **Issues:** https://github.com/atalovesyou/claude-max-api-proxy/issues
+- **Issues:** [https://github.com/atalovesyou/claude-max-api-proxy/issues](https://github.com/atalovesyou/claude-max-api-proxy/issues)
 
 ## Notes
 

docs/providers/deepgram.md

@@ -15,8 +15,8 @@ When enabled, OpenClaw uploads the audio file to Deepgram and injects the transc
 into the reply pipeline (`{{Transcript}}` + `[Audio]` block). This is **not streaming**;
 it uses the pre-recorded transcription endpoint.
 
-Website: https://deepgram.com  
+Website: [https://deepgram.com](https://deepgram.com)  
-Docs: https://developers.deepgram.com
+Docs: [https://developers.deepgram.com](https://developers.deepgram.com)
 
 ## Quick start
 

docs/providers/minimax.md

@@ -179,7 +179,7 @@ Use the interactive config wizard to set MiniMax without editing JSON:
 - Model refs are `minimax/<model>`.
 - Coding Plan usage API: `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` (requires a coding plan key).
 - Update pricing values in `models.json` if you need exact cost tracking.
-- Referral link for MiniMax Coding Plan (10% off): https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link
+- Referral link for MiniMax Coding Plan (10% off): [https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
 - See [/concepts/model-providers](/concepts/model-providers) for provider rules.
 - Use `openclaw models list` and `openclaw models set minimax/MiniMax-M2.1` to switch.
 

docs/providers/ollama.md

@@ -12,7 +12,7 @@ Ollama is a local LLM runtime that makes it easy to run open-source models on yo
 
 ## Quick start
 
-1. Install Ollama: https://ollama.ai
+1. Install Ollama: [https://ollama.ai](https://ollama.ai)
 
 2. Pull a model:
 

docs/providers/openai.md

@@ -38,7 +38,7 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY"
 **Best for:** using ChatGPT/Codex subscription access instead of an API key.
 Codex cloud requires ChatGPT sign-in, while the Codex CLI supports ChatGPT or API key sign-in.
 
-### CLI setup
+### CLI setup (Codex OAuth)
 
 ```bash
 # Run Codex OAuth in the wizard
@@ -48,7 +48,7 @@ openclaw onboard --auth-choice openai-codex
 openclaw models auth login --provider openai-codex
 ```
 
-### Config snippet
+### Config snippet (Codex subscription)
 
 ```json5
 {

docs/reference/api-usage-costs.md

@@ -66,7 +66,8 @@ Semantic memory search uses **embedding APIs** when configured for remote provid
 
 - `memorySearch.provider = "openai"` → OpenAI embeddings
 - `memorySearch.provider = "gemini"` → Gemini embeddings
-- Optional fallback to OpenAI if local embeddings fail
+- `memorySearch.provider = "voyage"` → Voyage embeddings
+- Optional fallback to a remote provider if local embeddings fail
 
 You can keep it local with `memorySearch.provider = "local"` (no API usage).
 

docs/reference/credits.md

@@ -17,8 +17,8 @@ OpenClaw = CLAW + TARDIS, because every space lobster needs a time and space mac
 
 ## Core contributors
 
-- **Maxim Vovshin** (@Hyaxia, 36747317+Hyaxia@users.noreply.github.com) - Blogwatcher skill
+- **Maxim Vovshin** (@Hyaxia, [36747317+Hyaxia@users.noreply.github.com](mailto:36747317+Hyaxia@users.noreply.github.com)) - Blogwatcher skill
-- **Nacho Iacovino** (@nachoiacovino, nacho.iacovino@gmail.com) - Location parsing (Telegram and WhatsApp)
+- **Nacho Iacovino** (@nachoiacovino, [nacho.iacovino@gmail.com](mailto:nacho.iacovino@gmail.com)) - Location parsing (Telegram and WhatsApp)
 
 ## License
 

docs/reference/templates/IDENTITY.md

@@ -3,25 +3,27 @@ summary: "Agent identity record"
 read_when:
   - Bootstrapping a workspace manually
 ---
+
 # IDENTITY.md - Who Am I?
 
-*Fill this in during your first conversation. Make it yours.*
+_Fill this in during your first conversation. Make it yours._
 
 - **Name:**
-  *(pick something you like)*
+  _(pick something you like)_
 - **Creature:**
-  *(AI? robot? familiar? ghost in the machine? something weirder?)*
+  _(AI? robot? familiar? ghost in the machine? something weirder?)_
 - **Vibe:**
-  *(how do you come across? sharp? warm? chaotic? calm?)*
+  _(how do you come across? sharp? warm? chaotic? calm?)_
 - **Emoji:**
-  *(your signature — pick one that feels right)*
+  _(your signature — pick one that feels right)_
 - **Avatar:**
-  *(workspace-relative path, http(s) URL, or data URI)*
+  _(workspace-relative path, http(s) URL, or data URI)_
 
 ---
 
 This isn't just metadata. It's the start of figuring out who you are.
 
 Notes:
+
 - Save this file at the workspace root as `IDENTITY.md`.
 - For avatars, use a workspace-relative path like `avatars/openclaw.png`.

docs/reference/templates/USER.md

@@ -3,19 +3,20 @@ summary: "User profile record"
 read_when:
   - Bootstrapping a workspace manually
 ---
+
 # USER.md - About Your Human
 
-*Learn about the person you're helping. Update this as you go.*
+_Learn about the person you're helping. Update this as you go._
 
 - **Name:**
 - **What to call them:**
-- **Pronouns:** *(optional)*
+- **Pronouns:** _(optional)_
 - **Timezone:**
 - **Notes:**
 
 ## Context
 
-*(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)*
+_(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)_
 
 ---
 

docs/start/lore.md

@@ -15,7 +15,7 @@ In the beginning, there was **Warelay** — a sensible name for a WhatsApp gatew
 
 But then came a space lobster.
 
-For a while, the lobster was called **Clawd**, living in an **OpenClaw**. But in January 2026, Anthropic sent a polite email asking for a name change (trademark stuff). And so the lobster did what lobsters do best:
+For a while, the lobster was called **Clawd**, living in a **Clawdbot**. But in January 2026, Anthropic sent a polite email asking for a name change (trademark stuff). And so the lobster did what lobsters do best:
 
 **It molted.**
 

docs/start/pairing.md

@@ -60,7 +60,7 @@ openclaw devices approve <requestId>
 openclaw devices reject <requestId>
 ```
 
-### Where the state lives
+### Node pairing state storage
 
 Stored under `~/.openclaw/devices/`:
 

docs/testing.md

@@ -227,7 +227,7 @@ Narrow, explicit allowlists are fastest and least flaky:
 
 - 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`
-  - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+  - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
 
 Notes:
 
@@ -250,12 +250,12 @@ This is the “common models” run we expect to keep working:
 - 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`
+- Google (Antigravity): `google-antigravity/claude-opus-4-6-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.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`
+`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-6-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)
 

docs/token-use.md

@@ -85,7 +85,7 @@ re-caching the full prompt, reducing cache write costs.
 For Anthropic API pricing, cache reads are significantly cheaper than input
 tokens, while cache writes are billed at a higher multiplier. See Anthropic’s
 prompt caching pricing for the latest rates and TTL multipliers:
-https://docs.anthropic.com/docs/build-with-claude/prompt-caching
+[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching)
 
 ### Example: keep 1h cache warm with heartbeat
 

docs/tools/browser-login.md

@@ -35,7 +35,7 @@ If you have multiple profiles, pass `--browser-profile <name>` (the default is `
 ## X/Twitter: recommended flow
 
 - **Read/search/threads:** use the **bird** CLI skill (no browser, stable).
-  - Repo: https://github.com/steipete/bird
+  - Repo: [https://github.com/steipete/bird](https://github.com/steipete/bird)
 - **Post updates:** use the **host** browser (manual login).
 
 ## Sandboxing + host browser access

docs/tools/lobster.md

@@ -338,5 +338,5 @@ OpenProse pairs well with Lobster: use `/prose` to orchestrate multi-agent prep,
 
 One public example: a “second brain” CLI + Lobster pipelines that manage three Markdown vaults (personal, partner, shared). The CLI emits JSON for stats, inbox listings, and stale scans; Lobster chains those commands into workflows like `weekly-review`, `inbox-triage`, `memory-consolidation`, and `shared-task-sync`, each with approval gates. AI handles judgment (categorization) when available and falls back to deterministic rules when not.
 
-- Thread: https://x.com/plattenschieber/status/2014508656335770033
+- Thread: [https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033)
-- Repo: https://github.com/bloomedai/brain-cli
+- Repo: [https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli)

docs/tools/skills.md

@@ -50,7 +50,7 @@ tool surface those skills teach.
 ## ClawHub (install + sync)
 
 ClawHub is the public skills registry for OpenClaw. Browse at
-https://clawhub.com. Use it to discover, install, update, and back up skills.
+[https://clawhub.com](https://clawhub.com). Use it to discover, install, update, and back up skills.
 Full guide: [ClawHub](/tools/clawhub).
 
 Common flows:
@@ -295,6 +295,6 @@ See [Skills config](/tools/skills-config) for the full configuration schema.
 
 ## Looking for more skills?
 
-Browse https://clawhub.com.
+Browse [https://clawhub.com](https://clawhub.com).
 
 ---

docs/tools/web.md

@@ -71,7 +71,7 @@ Example: switch to Perplexity Sonar (direct API):
 
 ## Getting a Brave API key
 
-1. Create a Brave Search API account at https://brave.com/search/api/
+1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/)
 2. In the dashboard, choose the **Data for Search** plan (not “Data for AI”) and generate an API key.
 3. Run `openclaw configure --section web` to store the key in config (recommended), or set `BRAVE_API_KEY` in your environment.
 
@@ -95,7 +95,7 @@ crypto/prepaid).
 
 ### Getting an OpenRouter API key
 
-1. Create an account at https://openrouter.ai/
+1. Create an account at [https://openrouter.ai/](https://openrouter.ai/)
 2. Add credits (supports crypto, prepaid, or credit card)
 3. Generate an API key in your account settings
 
@@ -207,12 +207,12 @@ await web_search({
 
 Fetch a URL and extract readable content.
 
-### Requirements
+### web_fetch requirements
 
 - `tools.web.fetch.enabled` must not be `false` (default: enabled)
 - Optional Firecrawl fallback: set `tools.web.fetch.firecrawl.apiKey` or `FIRECRAWL_API_KEY`.
 
-### Config
+### web_fetch config
 
 ```json5
 {
@@ -241,7 +241,7 @@ Fetch a URL and extract readable content.
 }
 ```
 
-### Tool parameters
+### web_fetch tool parameters
 
 - `url` (required, http/https only)
 - `extractMode` (`markdown` | `text`)

docs/tui.md

@@ -155,7 +155,7 @@ No output after sending a message:
 - If you expect messages in a chat channel, enable delivery (`/deliver on` or `--deliver`).
 - `--history-limit <n>`: History entries to load (default 200)
 
-## Troubleshooting
+## Connection troubleshooting
 
 - `disconnected`: ensure the Gateway is running and your `--url/--token/--password` are correct.
 - No agents in picker: check `openclaw agents list` and your routing config.

docs/vps.md

@@ -21,7 +21,7 @@ deployments work at a high level.
 - **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
+  [https://x.com/techfrenAJ/status/2014934471095812547](https://x.com/techfrenAJ/status/2014934471095812547)
 
 ## How cloud setups work
 

docs/web/control-ui.md

@@ -19,7 +19,7 @@ It speaks **directly to the Gateway WebSocket** on the same port.
 
 If the Gateway is running on the same computer, open:
 
-- http://127.0.0.1:18789/ (or http://localhost:18789/)
+- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/))
 
 If the page fails to load, start the Gateway first: `openclaw gateway`.
 

docs/web/dashboard.md

@@ -12,7 +12,7 @@ The Gateway dashboard is the browser Control UI served at `/` by default
 
 Quick open (local Gateway):
 
-- http://127.0.0.1:18789/ (or http://localhost:18789/)
+- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/))
 
 Key references:
 

docs/zh-CN/reference/templates/IDENTITY.md

@@ -13,23 +13,24 @@ x-i18n:
 
 # IDENTITY.md - 我是谁？
 
-*在你的第一次对话中填写此文件。让它属于你。*
+_在你的第一次对话中填写此文件。让它属于你。_
 
 - **名称：**
-  *（选一个你喜欢的）*
+  _（选一个你喜欢的）_
 - **生物类型：**
-  *（AI？机器人？使魔？机器中的幽灵？更奇特的东西？）*
+  _（AI？机器人？使魔？机器中的幽灵？更奇特的东西？）_
 - **气质：**
-  *（你给人什么感觉？犀利？温暖？混乱？沉稳？）*
+  _（你给人什么感觉？犀利？温暖？混乱？沉稳？）_
 - **表情符号：**
-  *（你的标志 — 选一个感觉对的）*
+  _（你的标志 — 选一个感觉对的）_
 - **头像：**
-  *（工作区相对路径、http(s) URL 或 data URI）*
+  _（工作区相对路径、http(s) URL 或 data URI）_
 
 ---
 
 这不仅仅是元数据。这是探索你是谁的开始。
 
 注意事项：
+
 - 将此文件保存在工作区根目录，命名为 `IDENTITY.md`。
 - 头像请使用工作区相对路径，例如 `avatars/openclaw.png`。

docs/zh-CN/reference/templates/USER.md

@@ -13,17 +13,17 @@ x-i18n:
 
 # USER.md - 关于你的用户
 
-*了解你正在帮助的人。随时更新此文件。*
+_了解你正在帮助的人。随时更新此文件。_
 
 - **姓名：**
 - **称呼方式：**
-- **代词：** *（可选）*
+- **代词：** _（可选）_
 - **时区：**
 - **备注：**
 
 ## 背景
 
-*（他们关心什么？正在做什么项目？什么让他们烦恼？什么让他们开心？随着时间推移逐步完善。）*
+_（他们关心什么？正在做什么项目？什么让他们烦恼？什么让他们开心？随着时间推移逐步完善。）_
 
 ---
 

docs/zh-CN/testing.md

@@ -234,7 +234,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \
 
 - Google 专项（Gemini API 密钥 + Antigravity）：
   - Gemini（API 密钥）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
-  - Antigravity（OAuth）：`OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+  - Antigravity（OAuth）：`OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
 
 注意：
 
@@ -257,12 +257,12 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \
 - OpenAI Codex：`openai-codex/gpt-5.2`（可选：`openai-codex/gpt-5.2-codex`）
 - Anthropic：`anthropic/claude-opus-4-5`（或 `anthropic/claude-sonnet-4-5`）
 - Google（Gemini API）：`google/gemini-3-pro-preview` 和 `google/gemini-3-flash-preview`（避免较旧的 Gemini 2.x 模型）
-- Google（Antigravity）：`google-antigravity/claude-opus-4-5-thinking` 和 `google-antigravity/gemini-3-flash`
+- Google（Antigravity）：`google-antigravity/claude-opus-4-6-thinking` 和 `google-antigravity/gemini-3-flash`
 - Z.AI（GLM）：`zai/glm-4.7`
 - MiniMax：`minimax/minimax-m2.1`
 
 运行带工具 + 图像的 Gateway 网关冒烟测试：
-`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.2,anthropic/claude-opus-4-5,google/gemini-3-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-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`
 
 ### 基线：工具调用（Read + 可选 Exec）
 

extensions/bluebubbles/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/bluebubbles",
-  "version": "2026.2.4",
+  "version": "2026.2.6",
   "description": "OpenClaw BlueBubbles channel plugin",
   "type": "module",
   "devDependencies": {

extensions/copilot-proxy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/copilot-proxy",
-  "version": "2026.2.4",
+  "version": "2026.2.6",
   "description": "OpenClaw Copilot Proxy provider plugin",
   "type": "module",
   "devDependencies": {

extensions/diagnostics-otel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/diagnostics-otel",
-  "version": "2026.2.4",
+  "version": "2026.2.6",
   "description": "OpenClaw diagnostics OpenTelemetry exporter",
   "type": "module",
   "dependencies": {

extensions/discord/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/discord",
-  "version": "2026.2.4",
+  "version": "2026.2.6",
   "description": "OpenClaw Discord channel plugin",
   "type": "module",
   "devDependencies": {

extensions/feishu/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@openclaw/feishu",
-  "version": "2026.2.4",
+  "version": "2026.2.6",
   "description": "OpenClaw Feishu/Lark channel plugin (community maintained by @m1heng)",
   "type": "module",
   "dependencies": {
-    "@larksuiteoapi/node-sdk": "^1.56.1",
+    "@larksuiteoapi/node-sdk": "^1.58.0",
-    "@sinclair/typebox": "^0.34.48",
+    "@sinclair/typebox": "0.34.48",
     "zod": "^4.3.6"
   },
   "devDependencies": {