docs: align CLI docs and help surface

docs/cli/clawbot.md

@@ -0,0 +1,21 @@
+---
+summary: "CLI reference for `openclaw clawbot` (legacy alias namespace)"
+read_when:
+  - You maintain older scripts using `openclaw clawbot ...`
+  - You need migration guidance to current commands
+title: "clawbot"
+---
+
+# `openclaw clawbot`
+
+Legacy alias namespace kept for backwards compatibility.
+
+Current supported alias:
+
+- `openclaw clawbot qr` (same behavior as [`openclaw qr`](/cli/qr))
+
+## Migration
+
+Prefer modern top-level commands directly:
+
+- `openclaw clawbot qr` -> `openclaw qr`

docs/cli/completion.md

@@ -0,0 +1,35 @@
+---
+summary: "CLI reference for `openclaw completion` (generate/install shell completion scripts)"
+read_when:
+  - You want shell completions for zsh/bash/fish/PowerShell
+  - You need to cache completion scripts under OpenClaw state
+title: "completion"
+---
+
+# `openclaw completion`
+
+Generate shell completion scripts and optionally install them into your shell profile.
+
+## Usage
+
+```bash
+openclaw completion
+openclaw completion --shell zsh
+openclaw completion --install
+openclaw completion --shell fish --install
+openclaw completion --write-state
+openclaw completion --shell bash --write-state
+```
+
+## Options
+
+- `-s, --shell <shell>`: shell target (`zsh`, `bash`, `powershell`, `fish`; default: `zsh`)
+- `-i, --install`: install completion by adding a source line to your shell profile
+- `--write-state`: write completion script(s) to `$OPENCLAW_STATE_DIR/completions` without printing to stdout
+- `-y, --yes`: skip install confirmation prompts
+
+## Notes
+
+- `--install` writes a small "OpenClaw Completion" block into your shell profile and points it at the cached script.
+- Without `--install` or `--write-state`, the command prints the script to stdout.
+- Completion generation eagerly loads command trees so nested subcommands are included.

docs/cli/daemon.md

@@ -0,0 +1,43 @@
+---
+summary: "CLI reference for `openclaw daemon` (legacy alias for gateway service management)"
+read_when:
+  - You still use `openclaw daemon ...` in scripts
+  - You need service lifecycle commands (install/start/stop/restart/status)
+title: "daemon"
+---
+
+# `openclaw daemon`
+
+Legacy alias for Gateway service management commands.
+
+`openclaw daemon ...` maps to the same service control surface as `openclaw gateway ...` service commands.
+
+## Usage
+
+```bash
+openclaw daemon status
+openclaw daemon install
+openclaw daemon start
+openclaw daemon stop
+openclaw daemon restart
+openclaw daemon uninstall
+```
+
+## Subcommands
+
+- `status`: show service install state and probe Gateway health
+- `install`: install service (`launchd`/`systemd`/`schtasks`)
+- `uninstall`: remove service
+- `start`: start service
+- `stop`: stop service
+- `restart`: restart service
+
+## Common options
+
+- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--deep`, `--json`
+- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
+- lifecycle (`uninstall|start|stop|restart`): `--json`
+
+## Prefer
+
+Use [`openclaw gateway`](/cli/gateway) for current docs and examples.

docs/cli/index.md

@@ -16,6 +16,7 @@ This page describes the current CLI behavior. If commands change, update this do
 - [`onboard`](/cli/onboard)
 - [`configure`](/cli/configure)
 - [`config`](/cli/config)
+- [`completion`](/cli/completion)
 - [`doctor`](/cli/doctor)
 - [`dashboard`](/cli/dashboard)
 - [`reset`](/cli/reset)
@@ -33,6 +34,7 @@ This page describes the current CLI behavior. If commands change, update this do
 - [`system`](/cli/system)
 - [`models`](/cli/models)
 - [`memory`](/cli/memory)
+- [`directory`](/cli/directory)
 - [`nodes`](/cli/nodes)
 - [`devices`](/cli/devices)
 - [`node`](/cli/node)
@@ -46,10 +48,13 @@ This page describes the current CLI behavior. If commands change, update this do
 - [`hooks`](/cli/hooks)
 - [`webhooks`](/cli/webhooks)
 - [`pairing`](/cli/pairing)
+- [`qr`](/cli/qr)
 - [`plugins`](/cli/plugins) (plugin commands)
 - [`channels`](/cli/channels)
 - [`security`](/cli/security)
 - [`skills`](/cli/skills)
+- [`daemon`](/cli/daemon) (legacy alias for gateway service commands)
+- [`clawbot`](/cli/clawbot) (legacy alias namespace)
 - [`voicecall`](/cli/voicecall) (plugin; if installed)
 
 ## Global flags
@@ -94,7 +99,9 @@ openclaw [--dev] [--profile <name>] <command>
     get
     set
     unset
+  completion
   doctor
+  dashboard
   security
     audit
   reset
@@ -108,6 +115,7 @@ openclaw [--dev] [--profile <name>] <command>
     remove
     login
     logout
+  directory
   skills
     list
     info
@@ -145,6 +153,13 @@ openclaw [--dev] [--profile <name>] <command>
     stop
     restart
     run
+  daemon
+    status
+    install
+    uninstall
+    start
+    stop
+    restart
   logs
   system
     event
@@ -231,6 +246,9 @@ openclaw [--dev] [--profile <name>] <command>
   pairing
     list
     approve
+  qr
+  clawbot
+    qr
   docs
   dns
     setup

docs/cli/qr.md

@@ -0,0 +1,39 @@
+---
+summary: "CLI reference for `openclaw qr` (generate iOS pairing QR + setup code)"
+read_when:
+  - You want to pair the iOS app with a gateway quickly
+  - You need setup-code output for remote/manual sharing
+title: "qr"
+---
+
+# `openclaw qr`
+
+Generate an iOS pairing QR and setup code from your current Gateway configuration.
+
+## Usage
+
+```bash
+openclaw qr
+openclaw qr --setup-code-only
+openclaw qr --json
+openclaw qr --remote
+openclaw qr --url wss://gateway.example/ws --token '<token>'
+```
+
+## Options
+
+- `--remote`: use `gateway.remote.url` plus remote token/password from config
+- `--url <url>`: override gateway URL used in payload
+- `--public-url <url>`: override public URL used in payload
+- `--token <token>`: override gateway token for payload
+- `--password <password>`: override gateway password for payload
+- `--setup-code-only`: print only setup code
+- `--no-ascii`: skip ASCII QR rendering
+- `--json`: emit JSON (`setupCode`, `gatewayUrl`, `auth`, `urlSource`)
+
+## Notes
+
+- `--token` and `--password` are mutually exclusive.
+- After scanning, approve device pairing with:
+  - `openclaw devices list`
+  - `openclaw devices approve <requestId>`

docs/docs.json

@@ -271,6 +271,10 @@
       "source": "/start/clawd/",
       "destination": "/start/openclaw"
     },
+    {
+      "source": "/start/pairing",
+      "destination": "/channels/pairing"
+    },
     {
       "source": "/clawhub",
       "destination": "/tools/clawhub"
@@ -1182,14 +1186,20 @@
                 "group": "CLI commands",
                 "pages": [
                   "cli/index",
+                  "cli/acp",
                   "cli/agent",
                   "cli/agents",
                   "cli/approvals",
                   "cli/browser",
                   "cli/channels",
+                  "cli/clawbot",
+                  "cli/completion",
+                  "cli/config",
                   "cli/configure",
                   "cli/cron",
+                  "cli/daemon",
                   "cli/dashboard",
+                  "cli/devices",
                   "cli/directory",
                   "cli/dns",
                   "cli/docs",
@@ -1201,10 +1211,12 @@
                   "cli/memory",
                   "cli/message",
                   "cli/models",
+                  "cli/node",
                   "cli/nodes",
                   "cli/onboard",
                   "cli/pairing",
                   "cli/plugins",
+                  "cli/qr",
                   "cli/reset",
                   "cli/sandbox",
                   "cli/security",
@@ -1216,7 +1228,8 @@
                   "cli/tui",
                   "cli/uninstall",
                   "cli/update",
-                  "cli/voicecall"
+                  "cli/voicecall",
+                  "cli/webhooks"
                 ]
               },
               {

src/cli/clawbot-cli.ts

@@ -1,7 +1,16 @@
 import type { Command } from "commander";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";
 import { registerQrCli } from "./qr-cli.js";
 
 export function registerClawbotCli(program: Command) {
-  const clawbot = program.command("clawbot").description("Legacy clawbot command aliases");
+  const clawbot = program
+    .command("clawbot")
+    .description("Legacy clawbot command aliases")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/clawbot", "docs.openclaw.ai/cli/clawbot")}\n`,
+    );
   registerQrCli(clawbot);
 }

src/cli/completion-cli.ts

@@ -4,6 +4,8 @@ import path from "node:path";
 import { Command, Option } from "commander";
 import { resolveStateDir } from "../config/paths.js";
 import { routeLogsToStderr } from "../logging/console.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";
 import { pathExists } from "../utils.js";
 import {
   buildFishOptionCompletionLine,
@@ -230,6 +232,11 @@ export function registerCompletionCli(program: Command) {
   program
     .command("completion")
     .description("Generate shell completion script")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/completion", "docs.openclaw.ai/cli/completion")}\n`,
+    )
     .addOption(
       new Option("-s, --shell <shell>", "Shell to generate completion for (default: zsh)").choices(
         COMPLETION_SHELLS,

src/cli/qr-cli.ts

@@ -4,6 +4,7 @@ import { loadConfig } from "../config/config.js";
 import { resolvePairingSetupFromConfig, encodePairingSetupCode } from "../pairing/setup-code.js";
 import { runCommandWithTimeout } from "../process/exec.js";
 import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
 import { theme } from "../terminal/theme.js";
 
 type QrCliOptions = {
@@ -38,6 +39,10 @@ export function registerQrCli(program: Command) {
   program
     .command("qr")
     .description("Generate an iOS pairing QR code and setup code")
+    .addHelpText(
+      "after",
+      () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/qr", "docs.openclaw.ai/cli/qr")}\n`,
+    )
     .option(
       "--remote",
       "Use gateway.remote.url and gateway.remote token/password (ignores device-pair publicUrl)",

src/commands/onboard-channels.ts

@@ -197,7 +197,7 @@ async function noteChannelPrimer(
       "Multi-user DMs: run: " +
         formatCliCommand('openclaw config set session.dmScope "per-channel-peer"') +
         ' (or "per-account-channel-peer" for multi-account channels) to isolate sessions.',
-      `Docs: ${formatDocsLink("/start/pairing", "start/pairing")}`,
+      `Docs: ${formatDocsLink("/channels/pairing", "channels/pairing")}`,
       "",
       ...channelLines,
     ].join("\n"),
@@ -253,7 +253,7 @@ async function maybeConfigureDmPolicies(params: {
         "Multi-user DMs: run: " +
           formatCliCommand('openclaw config set session.dmScope "per-channel-peer"') +
           ' (or "per-account-channel-peer" for multi-account channels) to isolate sessions.',
-        `Docs: ${formatDocsLink("/start/pairing", "start/pairing")}`,
+        `Docs: ${formatDocsLink("/channels/pairing", "channels/pairing")}`,
       ].join("\n"),
       `${policy.label} DM access`,
     );