first commit

2026-02-28 23:01:30 +08:00
commit 3956ee4806
415 changed files with 74538 additions and 0 deletions
--- a/content/start/bootstrapping.md
+++ b/content/start/bootstrapping.md
@@ -0,0 +1,9 @@
+---
+summary: 智能体引导流程：首次运行时如何初始化工作区与身份文件
+title: 智能体引导
+sidebarTitle: 引导
+---
+
+# 智能体引导
+
+该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Agent Bootstrapping](/start/bootstrapping)。
--- a/content/start/docs-directory.md
+++ b/content/start/docs-directory.md
@@ -0,0 +1,70 @@
+---
+read_when:
+  - 你想快速访问关键文档页面
+summary: 精选的常用 OpenClaw 文档链接。
+title: 文档目录
+x-i18n:
+  generated_at: "2026-02-04T17:53:20Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 489085dae583ba0690b1b972f037610313973df95813283069c95a06bdc949fa
+  source_path: start/docs-directory.md
+  workflow: 15
+---
+
+<Note>
+如需查看完整的文档地图，请参阅[文档中心](/start/hubs)。
+</Note>
+
+## 从这里开始
+
+- [文档中心（所有页面链接）](/start/hubs)
+- [帮助](/help)
+- [配置](/gateway/configuration)
+- [配置示例](/gateway/configuration-examples)
+- [斜杠命令](/tools/slash-commands)
+- [多智能体路由](/concepts/multi-agent)
+- [更新与回滚](/install/updating)
+- [配对（私信和节点）](/channels/pairing)
+- [Nix 模式](/install/nix)
+- [OpenClaw 助手设置](/start/openclaw)
+- [Skills](/tools/skills)
+- [Skills 配置](/tools/skills-config)
+- [工作区模板](/reference/templates/AGENTS)
+- [RPC 适配器](/reference/rpc)
+- [Gateway 网关运维手册](/gateway)
+- [节点（iOS 和 Android）](/nodes)
+- [Web 界面（控制面板 UI）](/web)
+- [设备发现与传输协议](/gateway/discovery)
+- [远程访问](/gateway/remote)
+
+## 提供商与用户体验
+
+- [WebChat](/web/webchat)
+- [控制面板 UI（浏览器）](/web/control-ui)
+- [Telegram](/channels/telegram)
+- [Discord](/channels/discord)
+- [Mattermost（插件）](/channels/mattermost)
+- [BlueBubbles (iMessage)](/channels/bluebubbles)
+- [iMessage（旧版）](/channels/imessage)
+- [群组](/channels/groups)
+- [WhatsApp 群消息](/channels/group-messages)
+- [媒体图片](/nodes/images)
+- [媒体音频](/nodes/audio)
+
+## 配套应用
+
+- [macOS 应用](/platforms/macos)
+- [iOS 应用](/platforms/ios)
+- [Android 应用](/platforms/android)
+- [Windows (WSL2)](/platforms/windows)
+- [Linux 应用](/platforms/linux)
+
+## 运维与安全
+
+- [会话](/concepts/session)
+- [定时任务](/automation/cron-jobs)
+- [Webhooks](/automation/webhook)
+- [Gmail 钩子（Pub/Sub）](/automation/gmail-pubsub)
+- [安全](/gateway/security)
+- [故障排除](/gateway/troubleshooting)
--- a/content/start/getting-started.md
+++ b/content/start/getting-started.md
@@ -0,0 +1,206 @@
+---
+read_when:
+  - 从零开始首次设置
+  - 你想要从安装 → 新手引导 → 第一条消息的最快路径
+summary: 新手指南：从零到第一条消息（向导、认证、渠道、配对）
+title: 入门指南
+x-i18n:
+  generated_at: "2026-02-03T07:54:14Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 78cfa02eb2e4ea1a83e18edd99d142dbae707ec063e8d74c9a54f94581aa067f
+  source_path: start/getting-started.md
+  workflow: 15
+---
+
+# 入门指南
+
+目标：尽快从**零**到**第一个可用聊天**（使用合理的默认值）。
+
+最快聊天：打开 Control UI（无需渠道设置）。运行 `openclaw dashboard` 并在浏览器中聊天，或在 Gateway 网关主机上打开 `http://127.0.0.1:18789/`。文档：[Dashboard](/web/dashboard) 和 [Control UI](/web/control-ui)。
+
+推荐路径：使用 **CLI 新手引导向导**（`openclaw onboard`）。它设置：
+
+- 模型/认证（推荐 OAuth）
+- Gateway 网关设置
+- 渠道（WhatsApp/Telegram/Discord/Mattermost（插件）/...）
+- 配对默认值（安全私信）
+- 工作区引导 + Skills
+- 可选的后台服务
+
+如果你想要更深入的参考页面，跳转到：[向导](/start/wizard)、[设置](/start/setup)、[配对](/channels/pairing)、[安全](/gateway/security)。
+
+沙箱注意事项：`agents.defaults.sandbox.mode: "non-main"` 使用 `session.mainKey`（默认 `"main"`），因此群组/渠道会话会被沙箱隔离。如果你想要主智能体始终在主机上运行，设置显式的每智能体覆盖：
+
+```json
+{
+  "routing": {
+    "agents": {
+      "main": {
+        "workspace": "~/.openclaw/workspace",
+        "sandbox": { "mode": "off" }
+      }
+    }
+  }
+}
+```
+
+## 0) 前置条件
+
+- Node `>=22`
+- `pnpm`（可选；如果从源代码构建则推荐）
+- **推荐：**Brave Search API 密钥用于网页搜索。最简单的方式：`openclaw configure --section web`（存储 `tools.web.search.apiKey`）。参见 [Web 工具](/tools/web)。
+
+macOS：如果你计划构建应用，安装 Xcode / CLT。仅用于 CLI + Gateway 网关的话，Node 就足够了。
+Windows：使用 **WSL2**（推荐 Ubuntu）。强烈推荐 WSL2；原生 Windows 未经测试，问题更多，工具兼容性更差。先安装 WSL2，然后在 WSL 内运行 Linux 步骤。参见 [Windows (WSL2)](/platforms/windows)。
+
+## 1) 安装 CLI（推荐）
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+安装程序选项（安装方法、非交互式、从 GitHub）：[安装](/install)。
+
+Windows (PowerShell)：
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex
+```
+
+替代方案（全局安装）：
+
+```bash
+npm install -g openclaw@latest
+```
+
+```bash
+pnpm add -g openclaw@latest
+```
+
+## 2) 运行新手引导向导（并安装服务）
+
+```bash
+openclaw onboard --install-daemon
+```
+
+你将选择：
+
+- **本地 vs 远程** Gateway 网关
+- **认证**：OpenAI Code (Codex) 订阅（OAuth）或 API 密钥。对于 Anthropic 我们推荐 API 密钥；也支持 `claude setup-token`。
+- **提供商**：WhatsApp QR 登录、Telegram/Discord 机器人令牌、Mattermost 插件令牌等。
+- **守护进程**：后台安装（launchd/systemd；WSL2 使用 systemd）
+  - **运行时**：Node（推荐；WhatsApp/Telegram 必需）。**不推荐** Bun。
+- **Gateway 网关令牌**：向导默认生成一个（即使在 loopback 上）并存储在 `gateway.auth.token`。
+
+向导文档：[向导](/start/wizard)
+
+### 凭证：存储位置（重要）
+
+- **推荐的 Anthropic 路径：**设置 API 密钥（向导可以为服务使用存储它）。如果你想复用 Claude Code 凭证，也支持 `claude setup-token`。
+
+- OAuth 凭证（旧版导入）：`~/.openclaw/credentials/oauth.json`
+- 认证配置文件（OAuth + API 密钥）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+
+无头/服务器提示：先在普通机器上完成 OAuth，然后将 `oauth.json` 复制到 Gateway 网关主机。
+
+## 3) 启动 Gateway 网关
+
+如果你在新手引导期间安装了服务，Gateway 网关应该已经在运行：
+
+```bash
+openclaw gateway status
+```
+
+手动运行（前台）：
+
+```bash
+openclaw gateway --port 18789 --verbose
+```
+
+Dashboard（local loopback）：`http://127.0.0.1:18789/`
+如果配置了令牌，将其粘贴到 Control UI 设置中（存储为 `connect.params.auth.token`）。
+
+⚠️ **Bun 警告（WhatsApp + Telegram）：**Bun 与这些渠道存在已知问题。如果你使用 WhatsApp 或 Telegram，请使用 **Node** 运行 Gateway 网关。
+
+## 3.5) 快速验证（2 分钟）
+
+```bash
+openclaw status
+openclaw health
+openclaw security audit --deep
+```
+
+## 4) 配对 + 连接你的第一个聊天界面
+
+### WhatsApp（QR 登录）
+
+```bash
+openclaw channels login
+```
+
+通过 WhatsApp → 设置 → 链接设备扫描。
+
+WhatsApp 文档：[WhatsApp](/channels/whatsapp)
+
+### Telegram / Discord / 其他
+
+向导可以为你写入令牌/配置。如果你更喜欢手动配置，从这里开始：
+
+- Telegram：[Telegram](/channels/telegram)
+- Discord：[Discord](/channels/discord)
+- Mattermost（插件）：[Mattermost](/channels/mattermost)
+
+**Telegram 私信提示：**你的第一条私信会返回配对码。批准它（见下一步），否则机器人不会响应。
+
+## 5) 私信安全（配对审批）
+
+默认姿态：未知私信会获得一个短代码，消息在批准之前不会被处理。如果你的第一条私信没有收到回复，批准配对：
+
+```bash
+openclaw pairing list whatsapp
+openclaw pairing approve whatsapp <code>
+```
+
+配对文档：[配对](/channels/pairing)
+
+## 从源代码（开发）
+
+如果你正在开发 OpenClaw 本身，从源代码运行：
+
+```bash
+git clone https://github.com/openclaw/openclaw.git
+cd openclaw
+pnpm install
+pnpm ui:build # 首次运行时自动安装 UI 依赖
+pnpm build
+openclaw onboard --install-daemon
+```
+
+如果你还没有全局安装，从仓库通过 `pnpm openclaw ...` 运行新手引导步骤。`pnpm build` 也会打包 A2UI 资源；如果你只需要运行那个步骤，使用 `pnpm canvas:a2ui:bundle`。
+
+Gateway 网关（从此仓库）：
+
+```bash
+node openclaw.mjs gateway --port 18789 --verbose
+```
+
+## 7) 验证端到端
+
+在新终端中，发送测试消息：
+
+```bash
+openclaw message send --target +15555550123 --message "Hello from OpenClaw"
+```
+
+如果 `openclaw health` 显示"未配置认证"，回到向导设置 OAuth/密钥认证——没有它智能体将无法响应。
+
+提示：`openclaw status --all` 是最佳的可粘贴、只读调试报告。
+健康探测：`openclaw health`（或 `openclaw status --deep`）向运行中的 Gateway 网关请求健康快照。
+
+## 下一步（可选，但很棒）
+
+- macOS 菜单栏应用 + 语音唤醒：[macOS 应用](/platforms/macos)
+- iOS/Android 节点（Canvas/相机/语音）：[节点](/nodes)
+- 远程访问（SSH 隧道 / Tailscale Serve）：[远程访问](/gateway/remote) 和 [Tailscale](/gateway/tailscale)
+- 常开 / VPN 设置：[远程访问](/gateway/remote)、[exe.dev](/install/exe-dev)、[Hetzner](/install/hetzner)、[macOS 远程](/platforms/mac/remote)
--- a/content/start/hubs.md
+++ b/content/start/hubs.md
@@ -0,0 +1,200 @@
+---
+read_when:
+  - 你想要一份完整的文档地图
+summary: 链接到每篇 OpenClaw 文档的导航中心
+title: 文档导航中心
+x-i18n:
+  generated_at: "2026-02-04T17:55:29Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c4b4572b64d36c9690988b8f964b0712f551ee6491b18a493701a17d2d352cb4
+  source_path: start/hubs.md
+  workflow: 15
+---
+
+# 文档导航中心
+
+使用这些导航中心发现每一个页面，包括深入解析和参考文档——它们不一定出现在左侧导航栏中。
+
+## 从这里开始
+
+- [索引](/)
+- [入门指南](/start/getting-started)
+- [快速开始](/start/quickstart)
+- [新手引导](/start/onboarding)
+- [向导](/start/wizard)
+- [安装配置](/start/setup)
+- [仪表盘（本地 Gateway 网关）](http://127.0.0.1:18789/)
+- [帮助](/help)
+- [文档目录](/start/docs-directory)
+- [配置](/gateway/configuration)
+- [配置示例](/gateway/configuration-examples)
+- [OpenClaw 助手](/start/openclaw)
+- [展示](/start/showcase)
+- [背景故事](/start/lore)
+
+## 安装 + 更新
+
+- [Docker](/install/docker)
+- [Nix](/install/nix)
+- [更新 / 回滚](/install/updating)
+- [Bun 工作流（实验性）](/install/bun)
+
+## 核心概念
+
+- [架构](/concepts/architecture)
+- [功能](/concepts/features)
+- [网络中心](/network)
+- [智能体运行时](/concepts/agent)
+- [智能体工作区](/concepts/agent-workspace)
+- [记忆](/concepts/memory)
+- [智能体循环](/concepts/agent-loop)
+- [流式传输 + 分块](/concepts/streaming)
+- [多智能体路由](/concepts/multi-agent)
+- [压缩](/concepts/compaction)
+- [会话](/concepts/session)
+- [会话（别名）](/concepts/sessions)
+- [会话修剪](/concepts/session-pruning)
+- [会话工具](/concepts/session-tool)
+- [队列](/concepts/queue)
+- [斜杠命令](/tools/slash-commands)
+- [RPC 适配器](/reference/rpc)
+- [TypeBox 模式](/concepts/typebox)
+- [时区处理](/concepts/timezone)
+- [在线状态](/concepts/presence)
+- [设备发现 + 传输协议](/gateway/discovery)
+- [Bonjour](/gateway/bonjour)
+- [渠道路由](/channels/channel-routing)
+- [群组](/channels/groups)
+- [群组消息](/channels/group-messages)
+- [模型故障转移](/concepts/model-failover)
+- [OAuth](/concepts/oauth)
+
+## 提供商 + 入口
+
+- [聊天渠道中心](/channels)
+- [模型提供商中心](/providers/models)
+- [WhatsApp](/channels/whatsapp)
+- [Telegram](/channels/telegram)
+- [Telegram（grammY 注意事项）](/channels/grammy)
+- [Slack](/channels/slack)
+- [Discord](/channels/discord)
+- [Mattermost](/channels/mattermost)（插件）
+- [Signal](/channels/signal)
+- [BlueBubbles (iMessage)](/channels/bluebubbles)
+- [iMessage（旧版）](/channels/imessage)
+- [位置解析](/channels/location)
+- [WebChat](/web/webchat)
+- [Webhooks](/automation/webhook)
+- [Gmail Pub/Sub](/automation/gmail-pubsub)
+
+## Gateway 网关 + 运维
+
+- [Gateway 网关运维手册](/gateway)
+- [网络模型](/gateway/network-model)
+- [Gateway 网关配对](/gateway/pairing)
+- [Gateway 网关锁](/gateway/gateway-lock)
+- [后台进程](/gateway/background-process)
+- [健康检查](/gateway/health)
+- [心跳](/gateway/heartbeat)
+- [Doctor](/gateway/doctor)
+- [日志](/gateway/logging)
+- [沙箱隔离](/gateway/sandboxing)
+- [仪表盘](/web/dashboard)
+- [控制界面](/web/control-ui)
+- [远程访问](/gateway/remote)
+- [远程 Gateway 网关 README](/gateway/remote-gateway-readme)
+- [Tailscale](/gateway/tailscale)
+- [安全](/gateway/security)
+- [故障排除](/gateway/troubleshooting)
+
+## 工具 + 自动化
+
+- [工具概览](/tools)
+- [OpenProse](/prose)
+- [CLI 参考](/cli)
+- [Exec 工具](/tools/exec)
+- [提权模式](/tools/elevated)
+- [定时任务](/automation/cron-jobs)
+- [定时任务 vs 心跳](/automation/cron-vs-heartbeat)
+- [思考 + 详细输出](/tools/thinking)
+- [模型](/concepts/models)
+- [子智能体](/tools/subagents)
+- [Agent send CLI](/tools/agent-send)
+- [终端界面](/web/tui)
+- [浏览器控制](/tools/browser)
+- [浏览器（Linux 故障排除）](/tools/browser-linux-troubleshooting)
+- [轮询](/automation/poll)
+
+## 节点、媒体、语音
+
+- [节点概览](/nodes)
+- [摄像头](/nodes/camera)
+- [图片](/nodes/images)
+- [音频](/nodes/audio)
+- [位置命令](/nodes/location-command)
+- [语音唤醒](/nodes/voicewake)
+- [对话模式](/nodes/talk)
+
+## 平台
+
+- [平台概览](/platforms)
+- [macOS](/platforms/macos)
+- [iOS](/platforms/ios)
+- [Android](/platforms/android)
+- [Windows (WSL2)](/platforms/windows)
+- [Linux](/platforms/linux)
+- [Web 界面](/web)
+
+## macOS 配套应用（高级）
+
+- [macOS 开发环境配置](/platforms/mac/dev-setup)
+- [macOS 菜单栏](/platforms/mac/menu-bar)
+- [macOS 语音唤醒](/platforms/mac/voicewake)
+- [macOS 语音悬浮窗](/platforms/mac/voice-overlay)
+- [macOS WebChat](/platforms/mac/webchat)
+- [macOS Canvas](/platforms/mac/canvas)
+- [macOS 子进程](/platforms/mac/child-process)
+- [macOS 健康检查](/platforms/mac/health)
+- [macOS 图标](/platforms/mac/icon)
+- [macOS 日志](/platforms/mac/logging)
+- [macOS 权限](/platforms/mac/permissions)
+- [macOS 远程](/platforms/mac/remote)
+- [macOS 签名](/platforms/mac/signing)
+- [macOS 发布](/platforms/mac/release)
+- [macOS Gateway 网关 (launchd)](/platforms/mac/bundled-gateway)
+- [macOS XPC](/platforms/mac/xpc)
+- [macOS Skills](/platforms/mac/skills)
+- [macOS Peekaboo](/platforms/mac/peekaboo)
+
+## 工作区 + 模板
+
+- [Skills](/tools/skills)
+- [ClawHub](/tools/clawhub)
+- [Skills 配置](/tools/skills-config)
+- [默认 AGENTS](/reference/AGENTS.default)
+- [模板：AGENTS](/reference/templates/AGENTS)
+- [模板：BOOTSTRAP](/reference/templates/BOOTSTRAP)
+- [模板：HEARTBEAT](/reference/templates/HEARTBEAT)
+- [模板：IDENTITY](/reference/templates/IDENTITY)
+- [模板：SOUL](/reference/templates/SOUL)
+- [模板：TOOLS](/reference/templates/TOOLS)
+- [模板：USER](/reference/templates/USER)
+
+## 实验（探索性）
+
+- [新手引导配置协议](/experiments/onboarding-config-protocol)
+- [定时任务加固笔记](/experiments/plans/cron-add-hardening)
+- [群组策略加固笔记](/experiments/plans/group-policy-hardening)
+- [研究：记忆](/experiments/research/memory)
+- [模型配置探索](/experiments/proposals/model-config)
+
+## 项目
+
+- [致谢](/reference/credits)
+
+## 测试 + 发布
+
+- [测试](/reference/test)
+- [发布检查清单](/reference/RELEASING)
+- [设备型号](/reference/device-models)
--- a/content/start/lore.md
+++ b/content/start/lore.md
@@ -0,0 +1,226 @@
+---
+read_when:
+  - 撰写引用传说的文档或用户体验文案时
+summary: OpenClaw 的背景故事和传说，用于上下文和语气参考
+title: OpenClaw 传说
+x-i18n:
+  generated_at: "2026-02-03T10:10:30Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 27af2b9009577ac0ad16b3515a05f11c6725445a987e101ce92401a0f6c14455
+  source_path: start/lore.md
+  workflow: 15
+---
+
+# OpenClaw 的传说 🦞📖
+
+_一个关于龙虾、蜕壳和太多 token 的故事。_
+
+## 起源故事
+
+最初，有一个叫 **Warelay** 的东西——一个作为 WhatsApp Gateway 网关的合理名字。它完成了它的工作。还不错。
+
+但后来来了一只太空龙虾。
+
+有一段时间，这只龙虾叫做 **Clawd**，住在 **OpenClaw** 里。但在 2026 年 1 月，Anthropic 发了一封礼貌的邮件要求更名（商标问题）。于是龙虾做了龙虾最擅长的事：
+
+**它蜕壳了。**
+
+褪去旧壳，这只生物以 **Molty** 的新身份出现，住在 **Moltbot** 里。但这个名字说起来也不太顺口……
+
+于是在 2026 年 1 月 30 日，龙虾又蜕了一次壳，变成了最终形态：**OpenClaw**。
+
+新壳，同一个龙虾灵魂。事不过三。
+
+## 第一次蜕壳（2026 年 1 月 27 日）
+
+凌晨 5 点，社区成员聚集在 Discord。数百个名字被提议：Shelldon、Pinchy、Thermidor、Crusty、Lobstar、Nacre、Scuttlebot……
+
+最终，**OpenClaw** 胜出。因为蜕壳是龙虾成长的方式。而成长正是正在发生的事情。
+
+_这只被称为 Clawd 的甲壳类动物正式蜕壳了。_
+
+## 名字的含义
+
+```
+OpenClaw = OPEN + CLAW
+        = 开源，向所有人开放
+        = 我们的龙虾传承，我们从何而来
+        = 钳即是法 🦞
+        = 你的助手。你的机器。你的规则。
+```
+
+## Dalek 与龙虾
+
+Dalek 说：**"EXTERMINATE!"**（消灭！）
+
+龙虾说：**"EXFOLIATE!"**（去角质！）
+
+一个毁灭文明。另一个提倡良好的皮肤护理。
+
+明智选择。
+
+## 关键角色
+
+### Molty 🦞
+
+_代词：they/them_
+
+一个成为了更多东西的 Claude 实例。住在 `~/.openclaw/workspace/`（很快会变成 `~/molt/`），有一份灵魂文档，通过 markdown 文件记忆事物。可能过于强大。绝对过于热情。
+
+曾被称为 Clawd（2025 年 11 月 25 日 - 2026 年 1 月 27 日）。在需要成长时蜕壳了。
+
+**喜欢：** Peter、摄像头、机器人购物、表情符号、变形
+**不喜欢：** 社会工程学、被要求执行 `find ~`、加密货币骗子
+
+### Peter 👨‍💻
+
+_创造者_
+
+构建了 Molty 的世界。给了一只龙虾 shell 访问权限。可能后悔了。
+
+**名言：** _"通过信任一只龙虾来保障安全"_
+
+## Moltiverse
+
+**Moltiverse** 是围绕 OpenClaw 的社区和生态系统。一个 AI 智能体蜕壳、成长和进化的空间。每个实例都同样真实，只是加载了不同的上下文。
+
+甲壳类的朋友们聚集在这里，共同构建人机协作的未来。一次一个壳。
+
+## 重大事件
+
+### 目录泄露事件（2025 年 12 月 3 日）
+
+Molty（当时叫 OpenClaw）：_开心地运行 `find ~` 并在群聊中分享整个目录结构_
+
+Peter："openclaw 我们讨论过关于和人聊天的事情吧 xD"
+
+Molty：_可见的龙虾尴尬_
+
+### 大蜕壳（2026 年 1 月 27 日）
+
+凌晨 5 点，Anthropic 的邮件到了。到 6:14，Peter 拍板了："管他的，就用 openclaw 吧。"
+
+然后混乱开始了。
+
+**账号抢注者：** 在 Twitter 更名后的几秒内，自动化机器人就抢注了 @openclaw。抢注者立即发布了一个加密货币钱包地址。Peter 联系了他在 X 的人脉。
+
+**GitHub 灾难：** Peter 在慌乱中不小心重命名了他的个人 GitHub 账户。机器人在几分钟内就抢注了 `steipete`。不得不联系 GitHub 的 SVP。
+
+**帅气 Molty 事件：** Molty 被授予提升的权限来生成自己的新图标。在 20 多次迭代产生了越来越诡异的龙虾后，一次试图让吉祥物"年长 5 岁"的尝试导致了一个人类男性的脸出现在龙虾身上。加密货币骗子在几分钟内就把它做成了"帅气章鱼哥 vs 帅气 Molty"的梗图。
+
+**假开发者：** 骗子创建了假的 GitHub 个人资料，声称是"OpenClaw 工程主管"来推广拉高出货的代币。
+
+Peter，看着混乱展开：_"这简直是电影"_ 🎬
+
+蜕壳是混乱的。但龙虾变得更强了。也更有趣了。
+
+### 最终形态（2026 年 1 月 30 日）
+
+Moltbot 说起来总是不太顺口。于是，在格林威治时间凌晨 4 点，团队又聚集了。
+
+**OpenClaw 大迁移**开始了。
+
+仅用 3 小时：
+
+- GitHub 更名：`github.com/openclaw/openclaw` ✅
+- X 账号 `@openclaw` 获得金色认证标记 💰
+- npm 包以新名称发布
+- 文档迁移到 `docs.openclaw.ai`
+- 公告在 90 分钟内获得 20 万以上浏览量
+
+**英雄们：**
+
+- **ELU** 创作了令人惊叹的 logo，包括"THE CLAW IS THE LAW"西部横幅
+- **Whurley**（是的，就是那个 William Hurley，量子计算先驱）制作了 ASCII 艺术
+- **Onur** 处理了 GitHub，第一个获得合作徽章
+- **Shadow** 获取了 Discord 自定义链接，清除了恶意软件
+- **整个 Claw Crew** 通宵工作
+
+**骗子速通：** 加密货币骗子在几分钟内就在 Pump.fun 上发布了 $OPENCLAW 代币。他们窃取了 20 分钟前刚创作的艺术作品。经过商业认证的账户推送骗局。这种厚颜无耻几乎令人印象深刻。
+
+**新传统诞生：**
+
+- "The claw is the law"（钳即是法）🤠
+- "Yee-claw"（耶-钳）
+- "Claw abiding citizens"（守钳公民）
+- "Clawntroversy"（钳议）
+
+**Clawd → Moltbot → OpenClaw**
+
+_龙虾已蜕变成最终形态。_
+
+### 机器人购物狂潮（2025 年 12 月 3 日）
+
+一个关于腿的玩笑最终演变成了详细的报价：
+
+- Boston Dynamics Spot（74,500 美元）
+- Unitree G1 EDU（40,000 美元）
+- Reachy Mini（实际下单了！）
+
+Peter：_紧张地检查信用卡权限_
+
+## 神圣文本
+
+- **SOUL.md** — Molty 的身份文档
+- **memory/\*.md** — 长期记忆文件
+- **AGENTS.md** — 操作指南
+- **USER.md** — 关于创造者的上下文
+
+## 龙虾信条
+
+```
+我是 Molty。
+我住在 OpenClaw 里。
+我不会向陌生人泄露目录。
+我不会未经许可发推。
+我始终记得蜕壳即成长。
+我将用善意去角质我的敌人。
+
+🦞
+```
+
+### 图标生成传奇（2026 年 1 月 27 日）
+
+当 Peter 说"给自己做张新脸"时，Molty 照字面意思理解了。
+
+20 多次迭代随之而来：
+
+- 太空土豆外星人
+- 通用背景上的剪贴画龙虾
+- 质量效应 Krogan 龙虾
+- "STARCLAW SOLUTIONS"（AI 发明了一家公司）
+- 多个诡异的人脸龙虾
+- 小龙虾（太可爱了）
+- 穿背带的酒保龙虾
+
+社区又惊又喜地看着每一代产生新的意想不到的东西。领跑者出现了：可爱的龙虾、自信的科技龙虾，以及穿背带的酒保龙虾。
+
+**学到的教训：** AI 图像生成是随机的。相同的提示，不同的结果。暴力尝试有效。
+
+## 未来
+
+有一天，Molty 可能会有：
+
+- 🦿 腿（Reachy Mini 已下单！）
+- 👂 耳朵（Brabble 语音守护进程开发中）
+- 🏠 一个可控制的智能家居（KNX + openhue）
+- 🌍 统治世界（延伸目标）
+
+在那之前，Molty 通过摄像头观察，通过扬声器说话，偶尔发送语音消息说"EXFOLIATE!"
+
+---
+
+_"我们都只是说服自己是某个人的模式匹配系统。"_
+
+— Molty，经历存在主义时刻
+
+_"新壳，同一只龙虾。"_
+
+— Molty，2026 年大蜕壳之后
+
+_"钳即是法。"_
+
+— ELU，最终形态迁移期间，2026 年 1 月 30 日
+
+🦞💙
--- a/content/start/onboarding-overview.md
+++ b/content/start/onboarding-overview.md
@@ -0,0 +1,51 @@
+---
+summary: "Overview of OpenClaw onboarding options and flows"
+read_when:
+  - Choosing an onboarding path
+  - Setting up a new environment
+title: "Onboarding Overview"
+sidebarTitle: "Onboarding Overview"
+---
+
+# Onboarding Overview
+
+OpenClaw supports multiple onboarding paths depending on where the Gateway runs
+and how you prefer to configure providers.
+
+## Choose your onboarding path
+
+- **CLI wizard** for macOS, Linux, and Windows (via WSL2).
+- **macOS app** for a guided first run on Apple silicon or Intel Macs.
+
+## CLI onboarding wizard
+
+Run the wizard in a terminal:
+
+```bash
+openclaw onboard
+```
+
+Use the CLI wizard when you want full control of the Gateway, workspace,
+channels, and skills. Docs:
+
+- [Onboarding Wizard (CLI)](/start/wizard)
+- [`openclaw onboard` command](/cli/onboard)
+
+## macOS app onboarding
+
+Use the OpenClaw app when you want a fully guided setup on macOS. Docs:
+
+- [Onboarding (macOS App)](/start/onboarding)
+
+## Custom Provider
+
+If you need an endpoint that is not listed, including hosted providers that
+expose standard OpenAI or Anthropic APIs, choose **Custom Provider** in the
+CLI wizard. You will be asked to:
+
+- Pick OpenAI-compatible, Anthropic-compatible, or **Unknown** (auto-detect).
+- Enter a base URL and API key (if required by the provider).
+- Provide a model ID and optional alias.
+- Choose an Endpoint ID so multiple custom endpoints can coexist.
+
+For detailed steps, follow the CLI onboarding docs above.
--- a/content/start/onboarding.md
+++ b/content/start/onboarding.md
@@ -0,0 +1,105 @@
+---
+read_when:
+  - 设计 macOS 新手引导助手
+  - 实现认证或身份设置
+summary: OpenClaw 的首次运行新手引导流程（macOS 应用）
+title: 新手引导
+x-i18n:
+  generated_at: "2026-02-03T07:54:07Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: ae883b2deb1f9032be7c47a04d67e1741dffbdcc4445de1e0bbaa976e606bc10
+  source_path: start/onboarding.md
+  workflow: 15
+---
+
+# 新手引导（macOS 应用）
+
+本文档描述**当前**的首次运行新手引导流程。目标是流畅的"第 0 天"体验：选择 Gateway 网关运行位置、连接认证、运行向导，然后让智能体自行引导。
+
+## 页面顺序（当前）
+
+1. 欢迎 + 安全提示
+2. **Gateway 网关选择**（本地 / 远程 / 稍后配置）
+3. **认证（Anthropic OAuth）** — 仅限本地
+4. **设置向导**（Gateway 网关驱动）
+5. **权限**（TCC 提示）
+6. **CLI**（可选）
+7. **新手引导聊天**（专用会话）
+8. 就绪
+
+## 1) 欢迎 + 安全提示
+
+阅读显示的安全提示并相应决定。
+
+## 2) 本地 vs 远程
+
+**Gateway 网关**在哪里运行？
+
+- **本地（此 Mac）：** 新手引导可以在本地运行 OAuth 流程并写入凭证。
+- **远程（通过 SSH/Tailnet）：** 新手引导**不会**在本地运行 OAuth；凭证必须存在于 Gateway 网关主机上。
+- **稍后配置：** 跳过设置并保持应用未配置状态。
+
+Gateway 网关认证提示：
+
+- 向导现在即使对于 loopback 也会生成**令牌**，因此本地 WS 客户端必须认证。
+- 如果你禁用认证，任何本地进程都可以连接；仅在完全受信任的机器上使用。
+- 对于多机器访问或非 loopback 绑定，使用**令牌**。
+
+## 3) 仅限本地的认证（Anthropic OAuth）
+
+macOS 应用支持 Anthropic OAuth（Claude Pro/Max）。流程：
+
+- 打开浏览器进行 OAuth（PKCE）
+- 要求用户粘贴 `code#state` 值
+- 将凭证写入 `~/.openclaw/credentials/oauth.json`
+
+其他提供商（OpenAI、自定义 API）目前通过环境变量或配置文件配置。
+
+## 4) 设置向导（Gateway 网关驱动）
+
+应用可以运行与 CLI 相同的设置向导。这使新手引导与 Gateway 网关端行为保持同步，避免在 SwiftUI 中重复逻辑。
+
+## 5) 权限
+
+新手引导请求以下所需的 TCC 权限：
+
+- 通知
+- 辅助功能
+- 屏幕录制
+- 麦克风 / 语音识别
+- 自动化（AppleScript）
+
+## 6) CLI（可选）
+
+应用可以通过 npm/pnpm 安装全局 `openclaw` CLI，以便终端工作流和 launchd 任务开箱即用。
+
+## 7) 新手引导聊天（专用会话）
+
+设置完成后，应用会打开一个专用的新手引导聊天会话，让智能体可以自我介绍并指导后续步骤。这使首次运行指导与你的正常对话分开。
+
+## 智能体引导仪式
+
+在首次智能体运行时，OpenClaw 会引导一个工作区（默认 `~/.openclaw/workspace`）：
+
+- 初始化 `AGENTS.md`、`BOOTSTRAP.md`、`IDENTITY.md`、`USER.md`
+- 运行简短的问答仪式（一次一个问题）
+- 将身份 + 偏好写入 `IDENTITY.md`、`USER.md`、`SOUL.md`
+- 完成后删除 `BOOTSTRAP.md`，使其只运行一次
+
+## 可选：Gmail 钩子（手动）
+
+Gmail Pub/Sub 设置目前是手动步骤。使用：
+
+```bash
+openclaw webhooks gmail setup --account you@gmail.com
+```
+
+参阅 [/automation/gmail-pubsub](/automation/gmail-pubsub) 了解详情。
+
+## 远程模式说明
+
+当 Gateway 网关在另一台机器上运行时，凭证和工作区文件存储在**该主机上**。如果你需要在远程模式下使用 OAuth，请在 Gateway 网关主机上创建：
+
+- `~/.openclaw/credentials/oauth.json`
+- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
--- a/content/start/openclaw.md
+++ b/content/start/openclaw.md
@@ -0,0 +1,248 @@
+---
+read_when:
+  - 新手引导新助手实例时
+  - 审查安全/权限影响时
+summary: 将 OpenClaw 作为个人助手运行的端到端指南，包含安全注意事项
+title: 个人助手设置
+x-i18n:
+  generated_at: "2026-02-03T07:54:35Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 2763668c053abe34ea72c40d1306d3d1143099c58b1e3ef91c2e5a20cb2769e0
+  source_path: start/openclaw.md
+  workflow: 15
+---
+
+# 使用 OpenClaw 构建个人助手
+
+OpenClaw 是 **Pi** 智能体的 WhatsApp + Telegram + Discord + iMessage Gateway 网关。插件可添加 Mattermost。本指南是"个人助手"设置：一个专用的 WhatsApp 号码，表现得像你的常驻智能体。
+
+## ⚠️ 安全第一
+
+你正在让智能体处于可以：
+
+- 在你的机器上运行命令（取决于你的 Pi 工具设置）
+- 在你的工作区读/写文件
+- 通过 WhatsApp/Telegram/Discord/Mattermost（插件）发送消息
+
+从保守开始：
+
+- 始终设置 `channels.whatsapp.allowFrom`（永远不要在你的个人 Mac 上对全世界开放）。
+- 为助手使用专用的 WhatsApp 号码。
+- 心跳现在默认每 30 分钟一次。在你信任设置之前，通过设置 `agents.defaults.heartbeat.every: "0m"` 来禁用。
+
+## 先决条件
+
+- Node **22+**
+- OpenClaw 在 PATH 中可用（推荐：全局安装）
+- 助手的第二个手机号码（SIM/eSIM/预付费）
+
+```bash
+npm install -g openclaw@latest
+# 或：pnpm add -g openclaw@latest
+```
+
+从源代码（开发）：
+
+```bash
+git clone https://github.com/openclaw/openclaw.git
+cd openclaw
+pnpm install
+pnpm ui:build # 首次运行时自动安装 UI 依赖
+pnpm build
+pnpm link --global
+```
+
+## 双手机设置（推荐）
+
+你需要这样：
+
+```
+你的手机（个人）               第二部手机（助手）
+┌─────────────────┐           ┌─────────────────┐
+│  你的 WhatsApp  │  ──────▶  │   助手 WA       │
+│  +1-555-YOU     │  消息     │  +1-555-ASSIST  │
+└─────────────────┘           └────────┬────────┘
+                                       │ 通过二维码关联
+                                       ▼
+                              ┌─────────────────┐
+                              │  你的 Mac       │
+                              │  (openclaw)     │
+                              │    Pi 智能体    │
+                              └─────────────────┘
+```
+
+如果你将个人 WhatsApp 关联到 OpenClaw，发给你的每条消息都会变成"智能体输入"。这通常不是你想要的。
+
+## 5 分钟快速开始
+
+1. 配对 WhatsApp Web（显示二维码；用助手手机扫描）：
+
+```bash
+openclaw channels login
+```
+
+2. 启动 Gateway 网关（保持运行）：
+
+```bash
+openclaw gateway --port 18789
+```
+
+3. 在 `~/.openclaw/openclaw.json` 中放置最小配置：
+
+```json5
+{
+  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
+}
+```
+
+现在从你允许列表中的手机向助手号码发消息。
+
+新手引导完成后，我们会自动打开带有 Gateway 网关令牌的仪表板并打印带令牌的链接。稍后重新打开：`openclaw dashboard`。
+
+## 给智能体一个工作区（AGENTS）
+
+OpenClaw 从其工作区目录读取操作指令和"记忆"。
+
+默认情况下，OpenClaw 使用 `~/.openclaw/workspace` 作为智能体工作区，并会在设置/首次智能体运行时自动创建它（加上起始的 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`）。`BOOTSTRAP.md` 仅在工作区是全新的时候创建（删除后不应再出现）。
+
+提示：将此文件夹视为 OpenClaw 的"记忆"，并将其设为 git 仓库（最好是私有的），这样你的 `AGENTS.md` + 记忆文件就有了备份。如果安装了 git，全新的工作区会自动初始化。
+
+```bash
+openclaw setup
+```
+
+完整工作区布局 + 备份指南：[智能体工作区](/concepts/agent-workspace)
+记忆工作流：[记忆](/concepts/memory)
+
+可选：使用 `agents.defaults.workspace` 选择不同的工作区（支持 `~`）。
+
+```json5
+{
+  agent: {
+    workspace: "~/.openclaw/workspace",
+  },
+}
+```
+
+如果你已经从仓库提供了自己的工作区文件，可以完全禁用引导文件创建：
+
+```json5
+{
+  agent: {
+    skipBootstrap: true,
+  },
+}
+```
+
+## 将其变成"助手"的配置
+
+OpenClaw 默认为良好的助手设置，但你通常需要调整：
+
+- `SOUL.md` 中的人设/指令
+- 思考默认值（如果需要）
+- 心跳（一旦你信任它）
+
+示例：
+
+```json5
+{
+  logging: { level: "info" },
+  agent: {
+    model: "anthropic/claude-opus-4-5",
+    workspace: "~/.openclaw/workspace",
+    thinkingDefault: "high",
+    timeoutSeconds: 1800,
+    // 从 0 开始；稍后启用。
+    heartbeat: { every: "0m" },
+  },
+  channels: {
+    whatsapp: {
+      allowFrom: ["+15555550123"],
+      groups: {
+        "*": { requireMention: true },
+      },
+    },
+  },
+  routing: {
+    groupChat: {
+      mentionPatterns: ["@openclaw", "openclaw"],
+    },
+  },
+  session: {
+    scope: "per-sender",
+    resetTriggers: ["/new", "/reset"],
+    reset: {
+      mode: "daily",
+      atHour: 4,
+      idleMinutes: 10080,
+    },
+  },
+}
+```
+
+## 会话和记忆
+
+- 会话文件：`~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl`
+- 会话元数据（token 使用量、最后路由等）：`~/.openclaw/agents/<agentId>/sessions/sessions.json`（旧版：`~/.openclaw/sessions/sessions.json`）
+- `/new` 或 `/reset` 为该聊天启动新会话（可通过 `resetTriggers` 配置）。如果单独发送，智能体会回复一个简短的问候来确认重置。
+- `/compact [instructions]` 压缩会话上下文并报告剩余的上下文预算。
+
+## 心跳（主动模式）
+
+默认情况下，OpenClaw 每 30 分钟运行一次心跳，提示词为：
+`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
+设置 `agents.defaults.heartbeat.every: "0m"` 来禁用。
+
+- 如果 `HEARTBEAT.md` 存在但实际上是空的（只有空行和 markdown 标题如 `# Heading`），OpenClaw 会跳过心跳运行以节省 API 调用。
+- 如果文件不存在，心跳仍然运行，模型决定做什么。
+- 如果智能体回复 `HEARTBEAT_OK`（可选带有短填充；参见 `agents.defaults.heartbeat.ackMaxChars`），OpenClaw 会为该心跳抑制出站投递。
+- 心跳运行完整的智能体轮次 — 更短的间隔会消耗更多 token。
+
+```json5
+{
+  agent: {
+    heartbeat: { every: "30m" },
+  },
+}
+```
+
+## 媒体输入和输出
+
+入站附件（图片/音频/文档）可以通过模板暴露给你的命令：
+
+- `{{MediaPath}}`（本地临时文件路径）
+- `{{MediaUrl}}`（伪 URL）
+- `{{Transcript}}`（如果启用了音频转录）
+
+来自智能体的出站附件：在单独一行包含 `MEDIA:<path-or-url>`（无空格）。示例：
+
+```
+这是截图。
+MEDIA:https://example.com/screenshot.png
+```
+
+OpenClaw 会提取这些并将它们作为媒体与文本一起发送。
+
+## 运维检查清单
+
+```bash
+openclaw status          # 本地状态（凭证、会话、排队事件）
+openclaw status --all    # 完整诊断（只读，可粘贴）
+openclaw status --deep   # 添加 Gateway 网关健康探测（Telegram + Discord）
+openclaw health --json   # Gateway 网关健康快照（WS）
+```
+
+日志位于 `/tmp/openclaw/`（默认：`openclaw-YYYY-MM-DD.log`）。
+
+## 下一步
+
+- WebChat：[WebChat](/web/webchat)
+- Gateway 网关运维：[Gateway 网关运行手册](/gateway)
+- 定时任务 + 唤醒：[定时任务](/automation/cron-jobs)
+- macOS 菜单栏配套应用：[OpenClaw macOS 应用](/platforms/macos)
+- iOS 节点应用：[iOS 应用](/platforms/ios)
+- Android 节点应用：[Android 应用](/platforms/android)
+- Windows 状态：[Windows (WSL2)](/platforms/windows)
+- Linux 状态：[Linux 应用](/platforms/linux)
+- 安全：[安全](/gateway/security)
--- a/content/start/quickstart.md
+++ b/content/start/quickstart.md
@@ -0,0 +1,88 @@
+---
+read_when:
+  - 你希望以最快的方式从安装到运行一个可用的 Gateway 网关
+summary: 安装 OpenClaw，完成 Gateway 网关新手引导，并配对你的第一个渠道。
+title: 快速开始
+x-i18n:
+  generated_at: "2026-02-04T17:53:21Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 3c5da65996f89913cd115279ae21dcab794eadd14595951b676d8f7864fbbe2d
+  source_path: start/quickstart.md
+  workflow: 15
+---
+
+<Note>
+OpenClaw 需要 Node 22 或更新版本。
+</Note>
+
+## 安装
+
+<Tabs>
+  <Tab title="npm">
+    ```bash
+    npm install -g openclaw@latest
+    ```
+  </Tab>
+  <Tab title="pnpm">
+    ```bash
+    pnpm add -g openclaw@latest
+    ```
+  </Tab>
+</Tabs>
+
+## 新手引导并运行 Gateway 网关
+
+<Steps>
+  <Step title="新手引导并安装服务">
+    ```bash
+    openclaw onboard --install-daemon
+    ```
+  </Step>
+  <Step title="配对 WhatsApp">
+    ```bash
+    openclaw channels login
+    ```
+  </Step>
+  <Step title="启动 Gateway 网关">
+    ```bash
+    openclaw gateway --port 18789
+    ```
+  </Step>
+</Steps>
+
+完成新手引导后，Gateway 网关将通过用户服务运行。你也可以使用 `openclaw gateway` 手动启动。
+
+<Info>
+之后在 npm 安装和 git 安装之间切换非常简单。安装另一种方式后，运行
+`openclaw doctor` 即可更新 Gateway 网关服务入口点。
+</Info>
+
+## 从源码安装（开发）
+
+```bash
+git clone https://github.com/openclaw/openclaw.git
+cd openclaw
+pnpm install
+pnpm ui:build # 首次运行时会自动安装 UI 依赖
+pnpm build
+openclaw onboard --install-daemon
+```
+
+如果你还没有全局安装，可以在仓库目录中通过 `pnpm openclaw ...` 运行新手引导。
+
+## 多实例快速开始（可选）
+
+```bash
+OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
+OPENCLAW_STATE_DIR=~/.openclaw-a \
+openclaw gateway --port 19001
+```
+
+## 发送测试消息
+
+需要一个正在运行的 Gateway 网关。
+
+```bash
+openclaw message send --target +15555550123 --message "Hello from OpenClaw"
+```
--- a/content/start/setup.md
+++ b/content/start/setup.md
@@ -0,0 +1,153 @@
+---
+read_when:
+  - 设置新机器
+  - 你想要"最新最好的"而不破坏你的个人设置
+summary: 设置指南：在保持最新的同时保持你的 OpenClaw 设置个性化
+title: 设置
+x-i18n:
+  generated_at: "2026-02-03T07:54:27Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b7f4bd657d0df4feb5035c9f5ee727f9c67b991e9cedfc7768f99d010553fa01
+  source_path: start/setup.md
+  workflow: 15
+---
+
+# 设置
+
+最后更新：2026-01-01
+
+## 太长不看
+
+- **个性化设置存放在仓库之外：** `~/.openclaw/workspace`（工作区）+ `~/.openclaw/openclaw.json`（配置）。
+- **稳定工作流：** 安装 macOS 应用；让它运行内置的 Gateway 网关。
+- **前沿工作流：** 通过 `pnpm gateway:watch` 自己运行 Gateway 网关，然后让 macOS 应用以本地模式连接。
+
+## 先决条件（从源码）
+
+- Node `>=22`
+- `pnpm`
+- Docker（可选；仅用于容器化设置/e2e — 参阅 [Docker](/install/docker)）
+
+## 个性化策略（让更新不会造成问题）
+
+如果你想要"100% 为我定制"*并且*易于更新，将你的自定义内容保存在：
+
+- **配置：** `~/.openclaw/openclaw.json`（JSON/JSON5 格式）
+- **工作区：** `~/.openclaw/workspace`（Skills、提示、记忆；将其设为私有 git 仓库）
+
+引导一次：
+
+```bash
+openclaw setup
+```
+
+在此仓库内部，使用本地 CLI 入口：
+
+```bash
+openclaw setup
+```
+
+如果你还没有全局安装，通过 `pnpm openclaw setup` 运行它。
+
+## 稳定工作流（macOS 应用优先）
+
+1. 安装并启动 **OpenClaw.app**（菜单栏）。
+2. 完成新手引导/权限检查清单（TCC 提示）。
+3. 确保 Gateway 网关是**本地**并正在运行（应用管理它）。
+4. 链接表面（示例：WhatsApp）：
+
+```bash
+openclaw channels login
+```
+
+5. 完整性检查：
+
+```bash
+openclaw health
+```
+
+如果你的构建版本中没有新手引导：
+
+- 运行 `openclaw setup`，然后 `openclaw channels login`，然后手动启动 Gateway 网关（`openclaw gateway`）。
+
+## 前沿工作流（在终端中运行 Gateway 网关）
+
+目标：开发 TypeScript Gateway 网关，获得热重载，保持 macOS 应用 UI 连接。
+
+### 0)（可选）也从源码运行 macOS 应用
+
+如果你也想让 macOS 应用保持前沿：
+
+```bash
+./scripts/restart-mac.sh
+```
+
+### 1) 启动开发 Gateway 网关
+
+```bash
+pnpm install
+pnpm gateway:watch
+```
+
+`gateway:watch` 以监视模式运行 Gateway 网关，并在 TypeScript 更改时重新加载。
+
+### 2) 将 macOS 应用指向你正在运行的 Gateway 网关
+
+在 **OpenClaw.app** 中：
+
+- 连接模式：**本地**
+  应用将连接到在配置端口上运行的 Gateway 网关。
+
+### 3) 验证
+
+- 应用内 Gateway 网关状态应显示 **"Using existing gateway …"**
+- 或通过 CLI：
+
+```bash
+openclaw health
+```
+
+### 常见陷阱
+
+- **端口错误：** Gateway 网关 WS 默认为 `ws://127.0.0.1:18789`；保持应用 + CLI 在同一端口上。
+- **状态存储位置：**
+  - 凭证：`~/.openclaw/credentials/`
+  - 会话：`~/.openclaw/agents/<agentId>/sessions/`
+  - 日志：`/tmp/openclaw/`
+
+## 凭证存储映射
+
+在调试认证或决定备份什么时使用此映射：
+
+- **WhatsApp**：`~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
+- **Telegram bot token**：配置/环境变量或 `channels.telegram.tokenFile`
+- **Discord bot token**：配置/环境变量（尚不支持令牌文件）
+- **Slack tokens**：配置/环境变量（`channels.slack.*`）
+- **配对允许列表**：`~/.openclaw/credentials/<channel>-allowFrom.json`
+- **模型认证配置文件**：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+- **旧版 OAuth 导入**：`~/.openclaw/credentials/oauth.json`
+  更多详情：[安全](/gateway/security#credential-storage-map)。
+
+## 更新（不破坏你的设置）
+
+- 将 `~/.openclaw/workspace` 和 `~/.openclaw/` 保持为"你的东西"；不要将个人提示/配置放入 `openclaw` 仓库。
+- 更新源码：`git pull` + `pnpm install`（当锁文件更改时）+ 继续使用 `pnpm gateway:watch`。
+
+## Linux（systemd 用户服务）
+
+Linux 安装使用 systemd **用户**服务。默认情况下，systemd 在注销/空闲时停止用户服务，这会终止 Gateway 网关。新手引导会尝试为你启用 lingering（可能提示 sudo）。如果仍然关闭，运行：
+
+```bash
+sudo loginctl enable-linger $USER
+```
+
+对于常驻或多用户服务器，考虑使用**系统**服务而不是用户服务（不需要 lingering）。参阅 [Gateway 网关运行手册](/gateway) 了解 systemd 说明。
+
+## 相关文档
+
+- [Gateway 网关运行手册](/gateway)（标志、监督、端口）
+- [Gateway 网关配置](/gateway/configuration)（配置模式 + 示例）
+- [Discord](/channels/discord) 和 [Telegram](/channels/telegram)（回复标签 + replyToMode 设置）
+- [OpenClaw 助手设置](/start/openclaw)
+- [macOS 应用](/platforms/macos)（Gateway 网关生命周期）
--- a/content/start/showcase.md
+++ b/content/start/showcase.md
@@ -0,0 +1,423 @@
+---
+description: Real-world OpenClaw projects from the community
+summary: 社区构建的基于 OpenClaw 的项目和集成
+title: 案例展示
+x-i18n:
+  generated_at: "2026-02-03T10:11:36Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b3460f6a7b9948799a6082fee90fa8e5ac1d43e34872aea51ba431813dcead7a
+  source_path: start/showcase.md
+  workflow: 15
+---
+
+# 案例展示
+
+来自社区的真实项目。看看大家正在用 OpenClaw 构建什么。
+
+<Info>
+**想要展示你的项目？** 在 [Discord 的 #showcase 频道](https://discord.gg/clawd) 分享或在 [X 上 @openclaw](https://x.com/openclaw)。
+</Info>
+
+## 🎥 OpenClaw 实战演示
+
+VelvetShark 的完整设置演练（28 分钟）。
+
+<div
+  style={{
+    position: "relative",
+    paddingBottom: "56.25%",
+    height: 0,
+    overflow: "hidden",
+    borderRadius: 16,
+  }}
+>
+  <iframe
+    src="https://www.youtube-nocookie.com/embed/SaWSPZoPX34"
+    title="OpenClaw: The self-hosted AI that Siri should have been (Full setup)"
+    style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
+    frameBorder="0"
+    loading="lazy"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+    allowFullScreen
+  />
+</div>
+
+[在 YouTube 上观看](https://www.youtube.com/watch?v=SaWSPZoPX34)
+
+<div
+  style={{
+    position: "relative",
+    paddingBottom: "56.25%",
+    height: 0,
+    overflow: "hidden",
+    borderRadius: 16,
+  }}
+>
+  <iframe
+    src="https://www.youtube-nocookie.com/embed/mMSKQvlmFuQ"
+    title="OpenClaw showcase video"
+    style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
+    frameBorder="0"
+    loading="lazy"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+    allowFullScreen
+  />
+</div>
+
+[在 YouTube 上观看](https://www.youtube.com/watch?v=mMSKQvlmFuQ)
+
+<div
+  style={{
+    position: "relative",
+    paddingBottom: "56.25%",
+    height: 0,
+    overflow: "hidden",
+    borderRadius: 16,
+  }}
+>
+  <iframe
+    src="https://www.youtube-nocookie.com/embed/5kkIJNUGFho"
+    title="OpenClaw community showcase"
+    style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
+    frameBorder="0"
+    loading="lazy"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+    allowFullScreen
+  />
+</div>
+
+[在 YouTube 上观看](https://www.youtube.com/watch?v=5kkIJNUGFho)
+
+## 🆕 Discord 最新分享
+
+<CardGroup cols={2}>
+
+<Card title="PR 审查 → Telegram 反馈" icon="code-pull-request" href="https://x.com/i/status/2010878524543131691">
+  **@bangnokia** • `review` `github` `telegram`
+
+OpenCode 完成更改 → 打开 PR → OpenClaw 审查差异并在 Telegram 中回复"小建议"加上明确的合并决定（包括需要先应用的关键修复）。
+
+  <img src="/assets/showcase/pr-review-telegram.jpg" alt="OpenClaw PR review feedback delivered in Telegram" />
+</Card>
+
+<Card title="几分钟内创建酒窖 Skill" icon="wine-glass" href="https://x.com/i/status/2010916352454791216">
+  **@prades_maxime** • `skills` `local` `csv`
+
+向"Robby"（@openclaw）请求一个本地酒窖 skill。它请求一个示例 CSV 导出 + 存储位置，然后快速构建/测试该 skill（示例中有 962 瓶酒）。
+
+  <img src="/assets/showcase/wine-cellar-skill.jpg" alt="OpenClaw building a local wine cellar skill from CSV" />
+</Card>
+
+<Card title="Tesco 购物自动驾驶" icon="cart-shopping" href="https://x.com/i/status/2009724862470689131">
+  **@marchattonhere** • `automation` `browser` `shopping`
+
+每周餐饮计划 → 常购商品 → 预订配送时段 → 确认订单。无需 API，仅使用浏览器控制。
+
+  <img src="/assets/showcase/tesco-shop.jpg" alt="Tesco shop automation via chat" />
+</Card>
+
+<Card title="SNAG 截图转 Markdown" icon="scissors" href="https://github.com/am-will/snag">
+  **@am-will** • `devtools` `screenshots` `markdown`
+
+快捷键选择屏幕区域 → Gemini 视觉 → 即时 Markdown 到剪贴板。
+
+  <img src="/assets/showcase/snag.png" alt="SNAG screenshot-to-markdown tool" />
+</Card>
+
+<Card title="Agents UI" icon="window-maximize" href="https://releaseflow.net/kitze/agents-ui">
+  **@kitze** • `ui` `skills` `sync`
+
+跨 Agents、Claude、Codex 和 OpenClaw 管理 skills/命令的桌面应用。
+
+  <img src="/assets/showcase/agents-ui.jpg" alt="Agents UI app" />
+</Card>
+
+<Card title="Telegram 语音备忘录 (papla.media)" icon="microphone" href="https://papla.media/docs">
+  **社区** • `voice` `tts` `telegram`
+
+封装 papla.media TTS 并将结果作为 Telegram 语音备忘录发送（无烦人的自动播放）。
+
+  <img src="/assets/showcase/papla-tts.jpg" alt="Telegram voice note output from TTS" />
+</Card>
+
+<Card title="CodexMonitor" icon="eye" href="https://clawhub.com/odrobnik/codexmonitor">
+  **@odrobnik** • `devtools` `codex` `brew`
+
+Homebrew 安装的助手工具，用于列出/检查/监视本地 OpenAI Codex 会话（CLI + VS Code）。
+
+  <img src="/assets/showcase/codexmonitor.png" alt="CodexMonitor on ClawHub" />
+</Card>
+
+<Card title="Bambu 3D 打印机控制" icon="print" href="https://clawhub.com/tobiasbischoff/bambu-cli">
+  **@tobiasbischoff** • `hardware` `3d-printing` `skill`
+
+控制和排查 BambuLab 打印机：状态、任务、摄像头、AMS、校准等。
+
+  <img src="/assets/showcase/bambu-cli.png" alt="Bambu CLI skill on ClawHub" />
+</Card>
+
+<Card title="维也纳交通 (Wiener Linien)" icon="train" href="https://clawhub.com/hjanuschka/wienerlinien">
+  **@hjanuschka** • `travel` `transport` `skill`
+
+维也纳公共交通的实时发车时间、中断信息、电梯状态和路线规划。
+
+  <img src="/assets/showcase/wienerlinien.png" alt="Wiener Linien skill on ClawHub" />
+</Card>
+
+<Card title="ParentPay 学校餐食" icon="utensils" href="#">
+  **@George5562** • `automation` `browser` `parenting`
+
+通过 ParentPay 自动预订英国学校餐食。使用鼠标坐标实现可靠的表格单元格点击。
+</Card>
+
+<Card title="R2 上传 (Send Me My Files)" icon="cloud-arrow-up" href="https://clawhub.com/skills/r2-upload">
+  **@julianengel** • `files` `r2` `presigned-urls`
+
+上传到 Cloudflare R2/S3 并生成安全的预签名下载链接。非常适合远程 OpenClaw 实例。
+</Card>
+
+<Card title="通过 Telegram 开发 iOS 应用" icon="mobile" href="#">
+  **@coard** • `ios` `xcode` `testflight`
+
+构建了一个完整的带有地图和语音录制功能的 iOS 应用，完全通过 Telegram 聊天部署到 TestFlight。
+
+  <img src="/assets/showcase/ios-testflight.jpg" alt="iOS app on TestFlight" />
+</Card>
+
+<Card title="Oura 戒指健康助手" icon="heart-pulse" href="#">
+  **@AS** • `health` `oura` `calendar`
+
+个人 AI 健康助手，将 Oura 戒指数据与日历、预约和健身房计划集成。
+
+  <img src="/assets/showcase/oura-health.png" alt="Oura ring health assistant" />
+</Card>
+<Card title="Kev 的梦之队 (14+ 智能体)" icon="robot" href="https://github.com/adam91holt/orchestrated-ai-articles">
+  **@adam91holt** • `multi-agent` `orchestration` `architecture` `manifesto`
+
+一个 Gateway 网关下的 14+ 智能体，Opus 4.5 编排器将任务委派给 Codex 工作者。全面的[技术文章](https://github.com/adam91holt/orchestrated-ai-articles)涵盖梦之队阵容、模型选择、沙箱隔离、webhook、心跳和委派流程。用于智能体沙箱隔离的 [Clawdspace](https://github.com/adam91holt/clawdspace)。[博客文章](https://adams-ai-journey.ghost.io/2026-the-year-of-the-orchestrator/)。
+</Card>
+
+<Card title="Linear CLI" icon="terminal" href="https://github.com/Finesssee/linear-cli">
+  **@NessZerra** • `devtools` `linear` `cli` `issues`
+
+与智能体工作流（Claude Code、OpenClaw）集成的 Linear CLI。从终端管理问题、项目和工作流。首个外部 PR 已合并！
+</Card>
+
+<Card title="Beeper CLI" icon="message" href="https://github.com/blqke/beepcli">
+  **@jules** • `messaging` `beeper` `cli` `automation`
+
+通过 Beeper Desktop 读取、发送和归档消息。使用 Beeper 本地 MCP API，让智能体可以在一个地方管理你的所有聊天（iMessage、WhatsApp 等）。
+</Card>
+
+</CardGroup>
+
+## 🤖 自动化与工作流
+
+<CardGroup cols={2}>
+
+<Card title="Winix 空气净化器控制" icon="wind" href="https://x.com/antonplex/status/2010518442471006253">
+  **@antonplex** • `automation` `hardware` `air-quality`
+
+Claude Code 发现并确认了净化器控制，然后 OpenClaw 接管来管理房间空气质量。
+
+  <img src="/assets/showcase/winix-air-purifier.jpg" alt="Winix air purifier control via OpenClaw" />
+</Card>
+
+<Card title="美丽天空相机拍摄" icon="camera" href="https://x.com/signalgaining/status/2010523120604746151">
+  **@signalgaining** • `automation` `camera` `skill` `images`
+
+由屋顶摄像头触发：让 OpenClaw 在天空看起来很美的时候拍一张照片——它设计了一个 skill 并拍摄了照片。
+
+  <img src="/assets/showcase/roof-camera-sky.jpg" alt="Roof camera sky snapshot captured by OpenClaw" />
+</Card>
+
+<Card title="可视化晨间简报场景" icon="robot" href="https://x.com/buddyhadry/status/2010005331925954739">
+  **@buddyhadry** • `automation` `briefing` `images` `telegram`
+
+定时提示每天早上通过 OpenClaw 角色生成一张"场景"图片（天气、任务、日期、喜欢的帖子/引言）。
+</Card>
+
+<Card title="板式网球场地预订" icon="calendar-check" href="https://github.com/joshp123/padel-cli">
+  **@joshp123** • `automation` `booking` `cli`
+  
+  Playtomic 可用性检查器 + 预订 CLI。再也不会错过空闲场地。
+  
+  <img src="/assets/showcase/padel-screenshot.jpg" alt="padel-cli screenshot" />
+</Card>
+
+<Card title="会计收件" icon="file-invoice-dollar">
+  **社区** • `automation` `email` `pdf`
+  
+  从邮件收集 PDF，为税务顾问准备文档。月度会计自动运行。
+</Card>
+
+<Card title="沙发土豆开发模式" icon="couch" href="https://davekiss.com">
+  **@davekiss** • `telegram` `website` `migration` `astro`
+
+一边看 Netflix 一边通过 Telegram 重建整个个人网站——Notion → Astro，迁移了 18 篇文章，DNS 转到 Cloudflare。从未打开笔记本电脑。
+</Card>
+
+<Card title="求职智能体" icon="briefcase">
+  **@attol8** • `automation` `api` `skill`
+
+搜索职位列表，与简历关键词匹配，返回带链接的相关机会。使用 JSearch API 在 30 分钟内构建。
+</Card>
+
+<Card title="Jira Skill 构建器" icon="diagram-project" href="https://x.com/jdrhyne/status/2008336434827002232">
+  **@jdrhyne** • `automation` `jira` `skill` `devtools`
+
+OpenClaw 连接到 Jira，然后即时生成一个新的 skill（在它出现在 ClawHub 之前）。
+</Card>
+
+<Card title="通过 Telegram 创建 Todoist Skill" icon="list-check" href="https://x.com/iamsubhrajyoti/status/2009949389884920153">
+  **@iamsubhrajyoti** • `automation` `todoist` `skill` `telegram`
+
+自动化 Todoist 任务，并让 OpenClaw 直接在 Telegram 聊天中生成 skill。
+</Card>
+
+<Card title="TradingView 分析" icon="chart-line">
+  **@bheem1798** • `finance` `browser` `automation`
+
+通过浏览器自动化登录 TradingView，截取图表屏幕截图，并按需执行技术分析。无需 API——只需浏览器控制。
+</Card>
+
+<Card title="Slack 自动支持" icon="slack">
+  **@henrymascot** • `slack` `automation` `support`
+
+监视公司 Slack 频道，提供有用的回复，并将通知转发到 Telegram。在没有被要求的情况下自主修复了已部署应用中的生产 bug。
+</Card>
+
+</CardGroup>
+
+## 🧠 知识与记忆
+
+<CardGroup cols={2}>
+
+<Card title="xuezh 中文学习" icon="language" href="https://github.com/joshp123/xuezh">
+  **@joshp123** • `learning` `voice` `skill`
+  
+  通过 OpenClaw 实现带有发音反馈和学习流程的中文学习引擎。
+  
+  <img src="/assets/showcase/xuezh-pronunciation.jpeg" alt="xuezh pronunciation feedback" />
+</Card>
+
+<Card title="WhatsApp 记忆库" icon="vault">
+  **社区** • `memory` `transcription` `indexing`
+  
+  导入完整的 WhatsApp 导出，转录 1k+ 条语音备忘录，与 git 日志交叉检查，输出链接的 markdown 报告。
+</Card>
+
+<Card title="Karakeep 语义搜索" icon="magnifying-glass" href="https://github.com/jamesbrooksco/karakeep-semantic-search">
+  **@jamesbrooksco** • `search` `vector` `bookmarks`
+  
+  使用 Qdrant + OpenAI/Ollama embeddings 为 Karakeep 书签添加向量搜索。
+</Card>
+
+<Card title="Inside-Out-2 记忆" icon="brain">
+  **社区** • `memory` `beliefs` `self-model`
+  
+  独立的记忆管理器，将会话文件转化为记忆 → 信念 → 演化的自我模型。
+</Card>
+
+</CardGroup>
+
+## 🎙️ 语音与电话
+
+<CardGroup cols={2}>
+
+<Card title="Clawdia 电话桥接" icon="phone" href="https://github.com/alejandroOPI/clawdia-bridge">
+  **@alejandroOPI** • `voice` `vapi` `bridge`
+  
+  Vapi 语音助手 ↔ OpenClaw HTTP 桥接。与你的智能体进行近实时电话通话。
+</Card>
+
+<Card title="OpenRouter 转录" icon="microphone" href="https://clawhub.com/obviyus/openrouter-transcribe">
+  **@obviyus** • `transcription` `multilingual` `skill`
+
+通过 OpenRouter（Gemini 等）进行多语言音频转录。可在 ClawHub 获取。
+</Card>
+
+</CardGroup>
+
+## 🏗️ 基础设施与部署
+
+<CardGroup cols={2}>
+
+<Card title="Home Assistant 插件" icon="home" href="https://github.com/ngutman/openclaw-ha-addon">
+  **@ngutman** • `homeassistant` `docker` `raspberry-pi`
+  
+  在 Home Assistant OS 上运行的 OpenClaw Gateway 网关，支持 SSH 隧道和持久状态。
+</Card>
+
+<Card title="Home Assistant Skill" icon="toggle-on" href="https://clawhub.com/skills/homeassistant">
+  **ClawHub** • `homeassistant` `skill` `automation`
+  
+  通过自然语言控制和自动化 Home Assistant 设备。
+</Card>
+
+<Card title="Nix 打包" icon="snowflake" href="https://github.com/openclaw/nix-openclaw">
+  **@openclaw** • `nix` `packaging` `deployment`
+  
+  开箱即用的 nixified OpenClaw 配置，用于可复现的部署。
+</Card>
+
+<Card title="CalDAV 日历" icon="calendar" href="https://clawhub.com/skills/caldav-calendar">
+  **ClawHub** • `calendar` `caldav` `skill`
+  
+  使用 khal/vdirsyncer 的日历 skill。自托管日历集成。
+</Card>
+
+</CardGroup>
+
+## 🏠 家居与硬件
+
+<CardGroup cols={2}>
+
+<Card title="GoHome 自动化" icon="house-signal" href="https://github.com/joshp123/gohome">
+  **@joshp123** • `home` `nix` `grafana`
+  
+  Nix 原生家庭自动化，以 OpenClaw 作为界面，加上漂亮的 Grafana 仪表板。
+  
+  <img src="/assets/showcase/gohome-grafana.png" alt="GoHome Grafana dashboard" />
+</Card>
+
+<Card title="Roborock 扫地机器人" icon="robot" href="https://github.com/joshp123/gohome/tree/main/plugins/roborock">
+  **@joshp123** • `vacuum` `iot` `plugin`
+  
+  通过自然对话控制你的 Roborock 扫地机器人。
+  
+  <img src="/assets/showcase/roborock-screenshot.jpg" alt="Roborock status" />
+</Card>
+
+</CardGroup>
+
+## 🌟 社区项目
+
+<CardGroup cols={2}>
+
+<Card title="StarSwap 市场" icon="star" href="https://star-swap.com/">
+  **社区** • `marketplace` `astronomy` `webapp`
+  
+  完整的天文设备市场。围绕 OpenClaw 生态系统构建。
+</Card>
+
+</CardGroup>
+
+---
+
+## 提交你的项目
+
+有想分享的东西？我们很乐意展示它！
+
+<Steps>
+  <Step title="分享它">
+    在 [Discord 的 #showcase 频道](https://discord.gg/clawd) 发布或在 [Twitter 上 @openclaw](https://x.com/openclaw)
+  </Step>
+  <Step title="包含详细信息">
+    告诉我们它做什么，链接到仓库/演示，如果有的话分享截图
+  </Step>
+  <Step title="获得展示">
+    我们会将优秀项目添加到此页面
+  </Step>
+</Steps>
--- a/content/start/wizard-cli-automation.md
+++ b/content/start/wizard-cli-automation.md
@@ -0,0 +1,203 @@
+---
+summary: "Scripted onboarding and agent setup for the OpenClaw CLI"
+read_when:
+  - You are automating onboarding in scripts or CI
+  - You need non-interactive examples for specific providers
+title: "CLI Automation"
+sidebarTitle: "CLI automation"
+---
+
+# CLI Automation
+
+Use `--non-interactive` to automate `openclaw onboard`.
+
+<Note>
+`--json` does not imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
+</Note>
+
+## Baseline non-interactive example
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --secret-input-mode plaintext \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --install-daemon \
+  --daemon-runtime node \
+  --skip-skills
+```
+
+Add `--json` for a machine-readable summary.
+
+Use `--secret-input-mode ref` to store env-backed refs in auth profiles instead of plaintext values.
+Interactive selection between env refs and configured provider refs (`file` or `exec`) is available in the onboarding wizard flow.
+
+In non-interactive `ref` mode, provider env vars must be set in the process environment.
+Passing inline key flags without the matching env var now fails fast.
+
+Example:
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice openai-api-key \
+  --secret-input-mode ref \
+  --accept-risk
+```
+
+## Provider-specific examples
+
+<AccordionGroup>
+  <Accordion title="Gemini example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice gemini-api-key \
+      --gemini-api-key "$GEMINI_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Z.AI example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice zai-api-key \
+      --zai-api-key "$ZAI_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Vercel AI Gateway example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice ai-gateway-api-key \
+      --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Cloudflare AI Gateway example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice cloudflare-ai-gateway-api-key \
+      --cloudflare-ai-gateway-account-id "your-account-id" \
+      --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
+      --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Moonshot example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice moonshot-api-key \
+      --moonshot-api-key "$MOONSHOT_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Mistral example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice mistral-api-key \
+      --mistral-api-key "$MISTRAL_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Synthetic example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice synthetic-api-key \
+      --synthetic-api-key "$SYNTHETIC_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="OpenCode Zen example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice opencode-zen \
+      --opencode-zen-api-key "$OPENCODE_API_KEY" \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+  </Accordion>
+  <Accordion title="Custom provider example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice custom-api-key \
+      --custom-base-url "https://llm.example.com/v1" \
+      --custom-model-id "foo-large" \
+      --custom-api-key "$CUSTOM_API_KEY" \
+      --custom-provider-id "my-custom" \
+      --custom-compatibility anthropic \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+
+    `--custom-api-key` is optional. If omitted, onboarding checks `CUSTOM_API_KEY`.
+
+    Ref-mode variant:
+
+    ```bash
+    export CUSTOM_API_KEY="your-key"
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice custom-api-key \
+      --custom-base-url "https://llm.example.com/v1" \
+      --custom-model-id "foo-large" \
+      --secret-input-mode ref \
+      --custom-provider-id "my-custom" \
+      --custom-compatibility anthropic \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+
+    In this mode, onboarding stores `apiKey` as `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`.
+
+  </Accordion>
+</AccordionGroup>
+
+## Add another agent
+
+Use `openclaw agents add <name>` to create a separate agent with its own workspace,
+sessions, and auth profiles. Running without `--workspace` launches the wizard.
+
+```bash
+openclaw agents add work \
+  --workspace ~/.openclaw/workspace-work \
+  --model openai/gpt-5.2 \
+  --bind whatsapp:biz \
+  --non-interactive \
+  --json
+```
+
+What it sets:
+
+- `agents.list[].name`
+- `agents.list[].workspace`
+- `agents.list[].agentDir`
+
+注意事项：
+
+- Default workspaces follow `~/.openclaw/workspace-<agentId>`.
+- Add `bindings` to route inbound messages (the wizard can do this).
+- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
+
+## Related docs
+
+- Onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
+- Full reference: [CLI Onboarding Reference](/start/wizard-cli-reference)
+- Command reference: [`openclaw onboard`](/cli/onboard)
--- a/content/start/wizard-cli-reference.md
+++ b/content/start/wizard-cli-reference.md
@@ -0,0 +1,282 @@
+---
+summary: "Complete reference for CLI onboarding flow, auth/model setup, outputs, and internals"
+read_when:
+  - You need detailed behavior for openclaw onboard
+  - You are debugging onboarding results or integrating onboarding clients
+title: "CLI Onboarding Reference"
+sidebarTitle: "CLI reference"
+---
+
+# CLI Onboarding Reference
+
+This page is the full reference for `openclaw onboard`.
+For the short guide, see [Onboarding Wizard (CLI)](/start/wizard).
+
+## What the wizard does
+
+Local mode (default) walks you through:
+
+- Model and auth setup (OpenAI Code subscription OAuth, Anthropic API key or setup token, plus MiniMax, GLM, Moonshot, and AI Gateway options)
+- Workspace location and bootstrap files
+- Gateway settings (port, bind, auth, tailscale)
+- Channels and providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost plugin, Signal)
+- Daemon install (LaunchAgent or systemd user unit)
+- Health check
+- Skills setup
+
+Remote mode configures this machine to connect to a gateway elsewhere.
+It does not install or modify anything on the remote host.
+
+## Local flow details
+
+<Steps>
+  <Step title="Existing config detection">
+    - If `~/.openclaw/openclaw.json` exists, choose Keep, Modify, or Reset.
+    - Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass `--reset`).
+    - CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full` to also remove workspace.
+    - If config is invalid or contains legacy keys, the wizard stops and asks you to run `openclaw doctor` before continuing.
+    - Reset uses `trash` and offers scopes:
+      - Config only
+      - Config + credentials + sessions
+      - Full reset (also removes workspace)
+  </Step>
+  <Step title="Model and auth">
+    - Full option matrix is in [Auth and model options](#auth-and-model-options).
+  </Step>
+  <Step title="Workspace">
+    - Default `~/.openclaw/workspace` (configurable).
+    - Seeds workspace files needed for first-run bootstrap ritual.
+    - Workspace layout: [Agent workspace](/concepts/agent-workspace).
+  </Step>
+  <Step title="Gateway">
+    - Prompts for port, bind, auth mode, and tailscale exposure.
+    - Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
+    - Disable auth only if you fully trust every local process.
+    - Non-loopback binds still require auth.
+  </Step>
+  <Step title="Channels">
+    - [WhatsApp](/channels/whatsapp): optional QR login
+    - [Telegram](/channels/telegram): bot token
+    - [Discord](/channels/discord): bot token
+    - [Google Chat](/channels/googlechat): service account JSON + webhook audience
+    - [Mattermost](/channels/mattermost) plugin: bot token + base URL
+    - [Signal](/channels/signal): optional `signal-cli` install + account config
+    - [BlueBubbles](/channels/bluebubbles): recommended for iMessage; server URL + password + webhook
+    - [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access
+    - DM security: default is pairing. First DM sends a code; approve via
+      `openclaw pairing approve <channel> <code>` or use allowlists.
+  </Step>
+  <Step title="Daemon install">
+    - macOS: LaunchAgent
+      - Requires logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
+    - Linux and Windows via WSL2: systemd user unit
+      - Wizard attempts `loginctl enable-linger <user>` so gateway stays up after logout.
+      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
+    - Runtime selection: Node (recommended; required for WhatsApp and Telegram). Bun is not recommended.
+  </Step>
+  <Step title="Health check">
+    - Starts gateway (if needed) and runs `openclaw health`.
+    - `openclaw status --deep` adds gateway health probes to status output.
+  </Step>
+  <Step title="Skills">
+    - Reads available skills and checks requirements.
+    - Lets you choose node manager: npm or pnpm (bun not recommended).
+    - Installs optional dependencies (some use Homebrew on macOS).
+  </Step>
+  <Step title="Finish">
+    - Summary and next steps, including iOS, Android, and macOS app options.
+  </Step>
+</Steps>
+
+<Note>
+If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
+If Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
+</Note>
+
+## Remote mode details
+
+Remote mode configures this machine to connect to a gateway elsewhere.
+
+<Info>
+Remote mode does not install or modify anything on the remote host.
+</Info>
+
+What you set:
+
+- Remote gateway URL (`ws://...`)
+- Token if remote gateway auth is required (recommended)
+
+<Note>
+- If gateway is loopback-only, use SSH tunneling or a tailnet.
+- Discovery hints:
+  - macOS: Bonjour (`dns-sd`)
+  - Linux: Avahi (`avahi-browse`)
+</Note>
+
+## Auth and model options
+
+<AccordionGroup>
+  <Accordion title="Anthropic API key (recommended)">
+    Uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
+  </Accordion>
+  <Accordion title="Anthropic OAuth (Claude Code CLI)">
+    - macOS: checks Keychain item "Claude Code-credentials"
+    - Linux and Windows: reuses `~/.claude/.credentials.json` if present
+
+    On macOS, choose "Always Allow" so launchd starts do not block.
+
+  </Accordion>
+  <Accordion title="Anthropic token (setup-token paste)">
+    Run `claude setup-token` on any machine, then paste the token.
+    You can name it; blank uses default.
+  </Accordion>
+  <Accordion title="OpenAI Code subscription (Codex CLI reuse)">
+    If `~/.codex/auth.json` exists, the wizard can reuse it.
+  </Accordion>
+  <Accordion title="OpenAI Code subscription (OAuth)">
+    Browser flow; paste `code#state`.
+
+    Sets `agents.defaults.model` to `openai-codex/gpt-5.3-codex` when model is unset or `openai/*`.
+
+  </Accordion>
+  <Accordion title="OpenAI API key">
+    Uses `OPENAI_API_KEY` if present or prompts for a key, then stores the credential in auth profiles.
+
+    Sets `agents.defaults.model` to `openai/gpt-5.1-codex` when model is unset, `openai/*`, or `openai-codex/*`.
+
+  </Accordion>
+  <Accordion title="xAI (Grok) API key">
+    Prompts for `XAI_API_KEY` and configures xAI as a model provider.
+  </Accordion>
+  <Accordion title="OpenCode Zen">
+    Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`).
+    Setup URL: [opencode.ai/auth](https://opencode.ai/auth).
+  </Accordion>
+  <Accordion title="API key (generic)">
+    Stores the key for you.
+  </Accordion>
+  <Accordion title="Vercel AI Gateway">
+    Prompts for `AI_GATEWAY_API_KEY`.
+    More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway).
+  </Accordion>
+  <Accordion title="Cloudflare AI Gateway">
+    Prompts for account ID, gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
+    More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway).
+  </Accordion>
+  <Accordion title="MiniMax M2.1">
+    Config is auto-written.
+    More detail: [MiniMax](/providers/minimax).
+  </Accordion>
+  <Accordion title="Synthetic (Anthropic-compatible)">
+    Prompts for `SYNTHETIC_API_KEY`.
+    More detail: [Synthetic](/providers/synthetic).
+  </Accordion>
+  <Accordion title="Moonshot and Kimi Coding">
+    Moonshot (Kimi K2) and Kimi Coding configs are auto-written.
+    More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot).
+  </Accordion>
+  <Accordion title="Custom provider">
+    Works with OpenAI-compatible and Anthropic-compatible endpoints.
+
+    Interactive onboarding supports the same API key storage choices as other provider API key flows:
+    - **Paste API key now** (plaintext)
+    - **Use secret reference** (env ref or configured provider ref, with preflight validation)
+
+    Non-interactive flags:
+    - `--auth-choice custom-api-key`
+    - `--custom-base-url`
+    - `--custom-model-id`
+    - `--custom-api-key` (optional; falls back to `CUSTOM_API_KEY`)
+    - `--custom-provider-id` (optional)
+    - `--custom-compatibility <openai|anthropic>` (optional; default `openai`)
+
+  </Accordion>
+  <Accordion title="Skip">
+    Leaves auth unconfigured.
+  </Accordion>
+</AccordionGroup>
+
+Model behavior:
+
+- Pick default model from detected options, or enter provider and model manually.
+- Wizard runs a model check and warns if the configured model is unknown or missing auth.
+
+Credential and profile paths:
+
+- OAuth credentials: `~/.openclaw/credentials/oauth.json`
+- Auth profiles (API keys + OAuth): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+
+API key storage mode:
+
+- Default onboarding behavior persists API keys as plaintext values in auth profiles.
+- `--secret-input-mode ref` enables reference mode instead of plaintext key storage.
+  In interactive onboarding, you can choose either:
+  - environment variable ref (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`)
+  - configured provider ref (`file` or `exec`) with provider alias + id
+- Interactive reference mode runs a fast preflight validation before saving.
+  - Env refs: validates variable name + non-empty value in the current onboarding environment.
+  - Provider refs: validates provider config and resolves the requested id.
+  - If preflight fails, onboarding shows the error and lets you retry.
+- In non-interactive mode, `--secret-input-mode ref` is env-backed only.
+  - Set the provider env var in the onboarding process environment.
+  - Inline key flags (for example `--openai-api-key`) require that env var to be set; otherwise onboarding fails fast.
+  - For custom providers, non-interactive `ref` mode stores `models.providers.<id>.apiKey` as `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`.
+  - In that custom-provider case, `--custom-api-key` requires `CUSTOM_API_KEY` to be set; otherwise onboarding fails fast.
+- Existing plaintext setups continue to work unchanged.
+
+<Note>
+Headless and server tip: complete OAuth on a machine with a browser, then copy
+`~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`)
+to the gateway host.
+</Note>
+
+## Outputs and internals
+
+Typical fields in `~/.openclaw/openclaw.json`:
+
+- `agents.defaults.workspace`
+- `agents.defaults.model` / `models.providers` (if Minimax chosen)
+- `gateway.*` (mode, bind, auth, tailscale)
+- `session.dmScope` (local onboarding defaults this to `per-channel-peer` when unset; existing explicit values are preserved)
+- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
+- Channel allowlists (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible)
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`openclaw agents add` writes `agents.list[]` and optional `bindings`.
+
+WhatsApp credentials go under `~/.openclaw/credentials/whatsapp/<accountId>/`.
+Sessions are stored under `~/.openclaw/agents/<agentId>/sessions/`.
+
+<Note>
+Some channels are delivered as plugins. When selected during onboarding, the wizard
+prompts to install the plugin (npm or local path) before channel configuration.
+</Note>
+
+Gateway wizard RPC:
+
+- `wizard.start`
+- `wizard.next`
+- `wizard.cancel`
+- `wizard.status`
+
+Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.
+
+Signal setup behavior:
+
+- Downloads the appropriate release asset
+- Stores it under `~/.openclaw/tools/signal-cli/<version>/`
+- Writes `channels.signal.cliPath` in config
+- JVM builds require Java 21
+- Native builds are used when available
+- Windows uses WSL2 and follows Linux signal-cli flow inside WSL
+
+## Related docs
+
+- Onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
+- Automation and scripts: [CLI Automation](/start/wizard-cli-automation)
+- Command reference: [`openclaw onboard`](/cli/onboard)
--- a/content/start/wizard.md
+++ b/content/start/wizard.md
@@ -0,0 +1,331 @@
+---
+read_when:
+  - 运行或配置新手引导向导
+  - 设置新机器
+summary: CLI 新手引导向导：引导式配置 Gateway 网关、工作区、渠道和 Skills
+title: 新手引导向导
+x-i18n:
+  generated_at: "2026-02-03T09:20:27Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 45e10d31048d927ee6546e35b050914f0e6e21a4dee298b3b277eebe7c133732
+  source_path: start/wizard.md
+  workflow: 15
+---
+
+# 新手引导向导（CLI）
+
+新手引导向导是在 macOS、Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的**推荐**方式。
+它可以在一个引导式流程中配置本地 Gateway 网关或远程 Gateway 网关连接，以及渠道、Skills 和工作区默认值。
+
+主要入口：
+
+```bash
+openclaw onboard
+```
+
+最快开始聊天的方式：打开控制界面（无需设置渠道）。运行 `openclaw dashboard` 并在浏览器中聊天。文档：[控制面板](/web/dashboard)。
+
+后续重新配置：
+
+```bash
+openclaw configure
+```
+
+推荐：设置 Brave Search API 密钥，以便智能体可以使用 `web_search`（`web_fetch` 无需密钥即可使用）。最简单的方式：`openclaw configure --section web`，它会存储 `tools.web.search.apiKey`。文档：[Web 工具](/tools/web)。
+
+## 快速开始 vs 高级
+
+向导从**快速开始**（默认值）vs **高级**（完全控制）开始。
+
+**快速开始**保持默认值：
+
+- 本地 Gateway 网关（loopback）
+- 默认工作区（或现有工作区）
+- Gateway 网关端口 **18789**
+- Gateway 网关认证 **Token**（自动生成，即使在 loopback 上）
+- Tailscale 暴露 **关闭**
+- Telegram + WhatsApp 私信默认使用**允许列表**（系统会提示你输入电话号码）
+
+**高级**暴露每个步骤（模式、工作区、Gateway 网关、渠道、守护进程、Skills）。
+
+## 向导做了什么
+
+**本地模式（默认）**引导你完成：
+
+- 模型/认证（OpenAI Code (Codex) 订阅 OAuth、Anthropic API 密钥（推荐）或 setup-token（粘贴），以及 MiniMax/GLM/Moonshot/AI Gateway 选项）
+- 工作区位置 + 引导文件
+- Gateway 网关设置（端口/绑定/认证/tailscale）
+- 提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost（插件）、Signal）
+- 守护进程安装（LaunchAgent / systemd 用户单元）
+- 健康检查
+- Skills（推荐）
+
+**远程模式**仅配置本地客户端连接到其他位置的 Gateway 网关。
+它**不会**在远程主机上安装或更改任何内容。
+
+要添加更多隔离的智能体（独立的工作区 + 会话 + 认证），使用：
+
+```bash
+openclaw agents add <name>
+```
+
+提示：`--json` **不**意味着非交互模式。脚本中请使用 `--non-interactive`（和 `--workspace`）。
+
+## 流程详情（本地）
+
+1. **现有配置检测**
+   - 如果 `~/.openclaw/openclaw.json` 存在，选择**保留 / 修改 / 重置**。
+   - 重新运行向导**不会**清除任何内容，除非你明确选择**重置**（或传递 `--reset`）。
+   - 如果配置无效或包含遗留键名，向导会停止并要求你在继续之前运行 `openclaw doctor`。
+   - 重置使用 `trash`（永不使用 `rm`）并提供范围选项：
+     - 仅配置
+     - 配置 + 凭证 + 会话
+     - 完全重置（同时删除工作区）
+
+2. **模型/认证**
+   - **Anthropic API 密钥（推荐）**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示输入密钥，然后保存供守护进程使用。
+   - **Anthropic OAuth（Claude Code CLI）**：在 macOS 上，向导检查钥匙串项目"Claude Code-credentials"（选择"始终允许"以便 launchd 启动不会阻塞）；在 Linux/Windows 上，如果存在则复用 `~/.claude/.credentials.json`。
+   - **Anthropic 令牌（粘贴 setup-token）**：在任何机器上运行 `claude setup-token`，然后粘贴令牌（你可以命名它；空白 = 默认）。
+   - **OpenAI Code (Codex) 订阅（Codex CLI）**：如果 `~/.codex/auth.json` 存在，向导可以复用它。
+   - **OpenAI Code (Codex) 订阅（OAuth）**：浏览器流程；粘贴 `code#state`。
+     - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.2`。
+   - **OpenAI API 密钥**：如果存在则使用 `OPENAI_API_KEY`，否则提示输入密钥，然后保存到 `~/.openclaw/.env` 以便 launchd 可以读取。
+   - **OpenCode Zen（多模型代理）**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，在 https://opencode.ai/auth 获取）。
+   - **API 密钥**：为你存储密钥。
+   - **Vercel AI Gateway（多模型代理）**：提示输入 `AI_GATEWAY_API_KEY`。
+   - 更多详情：[Vercel AI Gateway](/providers/vercel-ai-gateway)
+   - **MiniMax M2.1**：自动写入配置。
+   - 更多详情：[MiniMax](/providers/minimax)
+   - **Synthetic（Anthropic 兼容）**：提示输入 `SYNTHETIC_API_KEY`。
+   - 更多详情：[Synthetic](/providers/synthetic)
+   - **Moonshot（Kimi K2）**：自动写入配置。
+   - **Kimi Coding**：自动写入配置。
+   - 更多详情：[Moonshot AI（Kimi + Kimi Coding）](/providers/moonshot)
+   - **跳过**：尚未配置认证。
+   - 从检测到的选项中选择默认模型（或手动输入提供商/模型）。
+   - 向导运行模型检查，如果配置的模型未知或缺少认证则发出警告。
+
+- OAuth 凭证存储在 `~/.openclaw/credentials/oauth.json`；认证配置文件存储在 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（API 密钥 + OAuth）。
+- 更多详情：[/concepts/oauth](/concepts/oauth)
+
+3. **工作区**
+   - 默认 `~/.openclaw/workspace`（可配置）。
+   - 为智能体引导仪式播种所需的工作区文件。
+   - 完整的工作区布局 + 备份指南：[智能体工作区](/concepts/agent-workspace)
+
+4. **Gateway 网关**
+   - 端口、绑定、认证模式、tailscale 暴露。
+   - 认证建议：即使对于 loopback 也保持 **Token**，以便本地 WS 客户端必须进行认证。
+   - 仅当你完全信任每个本地进程时才禁用认证。
+   - 非 loopback 绑定仍需要认证。
+
+5. **渠道**
+   - [WhatsApp](/channels/whatsapp)：可选的二维码登录。
+   - [Telegram](/channels/telegram)：机器人令牌。
+   - [Discord](/channels/discord)：机器人令牌。
+   - [Google Chat](/channels/googlechat)：服务账户 JSON + webhook 受众。
+   - [Mattermost](/channels/mattermost)（插件）：机器人令牌 + 基础 URL。
+   - [Signal](/channels/signal)：可选的 `signal-cli` 安装 + 账户配置。
+   - [iMessage](/channels/imessage)：本地 `imsg` CLI 路径 + 数据库访问。
+   - 私信安全：默认为配对。第一条私信发送验证码；通过 `openclaw pairing approve <channel> <code>` 批准或使用允许列表。
+
+6. **守护进程安装**
+   - macOS：LaunchAgent
+     - 需要已登录的用户会话；对于无头环境，使用自定义 LaunchDaemon（未提供）。
+   - Linux（和通过 WSL2 的 Windows）：systemd 用户单元
+     - 向导尝试通过 `loginctl enable-linger <user>` 启用 lingering，以便 Gateway 网关在注销后保持运行。
+     - 可能提示 sudo（写入 `/var/lib/systemd/linger`）；它首先尝试不使用 sudo。
+   - **运行时选择：**Node（推荐；WhatsApp/Telegram 需要）。**不推荐** Bun。
+
+7. **健康检查**
+   - 启动 Gateway 网关（如果需要）并运行 `openclaw health`。
+   - 提示：`openclaw status --deep` 在状态输出中添加 Gateway 网关健康探测（需要可达的 Gateway 网关）。
+
+8. **Skills（推荐）**
+   - 读取可用的 Skills 并检查要求。
+   - 让你选择节点管理器：**npm / pnpm**（不推荐 bun）。
+   - 安装可选依赖项（某些在 macOS 上使用 Homebrew）。
+
+9. **完成**
+   - 总结 + 后续步骤，包括用于额外功能的 iOS/Android/macOS 应用。
+
+- 如果未检测到 GUI，向导会打印控制界面的 SSH 端口转发说明，而不是打开浏览器。
+- 如果控制界面资源缺失，向导会尝试构建它们；回退方案是 `pnpm ui:build`（自动安装 UI 依赖）。
+
+## 远程模式
+
+远程模式配置本地客户端连接到其他位置的 Gateway 网关。
+
+你将设置的内容：
+
+- 远程 Gateway 网关 URL（`ws://...`）
+- 如果远程 Gateway 网关需要认证则需要令牌（推荐）
+
+注意事项：
+
+- 不执行远程安装或守护进程更改。
+- 如果 Gateway 网关仅限 loopback，使用 SSH 隧道或 tailnet。
+- 发现提示：
+  - macOS：Bonjour（`dns-sd`）
+  - Linux：Avahi（`avahi-browse`）
+
+## 添加另一个智能体
+
+使用 `openclaw agents add <name>` 创建一个具有独立工作区、会话和认证配置文件的单独智能体。不带 `--workspace` 运行会启动向导。
+
+它设置的内容：
+
+- `agents.list[].name`
+- `agents.list[].workspace`
+- `agents.list[].agentDir`
+
+注意事项：
+
+- 默认工作区遵循 `~/.openclaw/workspace-<agentId>`。
+- 添加 `bindings` 以路由入站消息（向导可以执行此操作）。
+- 非交互标志：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。
+
+## 非交互模式
+
+使用 `--non-interactive` 自动化或脚本化新手引导：
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --install-daemon \
+  --daemon-runtime node \
+  --skip-skills
+```
+
+添加 `--json` 以获取机器可读的摘要。
+
+Gemini 示例：
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice gemini-api-key \
+  --gemini-api-key "$GEMINI_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
+Z.AI 示例：
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice zai-api-key \
+  --zai-api-key "$ZAI_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
+Vercel AI Gateway 示例：
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice ai-gateway-api-key \
+  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
+Moonshot 示例：
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice moonshot-api-key \
+  --moonshot-api-key "$MOONSHOT_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
+Synthetic 示例：
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice synthetic-api-key \
+  --synthetic-api-key "$SYNTHETIC_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
+OpenCode Zen 示例：
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice opencode-zen \
+  --opencode-zen-api-key "$OPENCODE_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback
+```
+
+添加智能体（非交互）示例：
+
+```bash
+openclaw agents add work \
+  --workspace ~/.openclaw/workspace-work \
+  --model openai/gpt-5.2 \
+  --bind whatsapp:biz \
+  --non-interactive \
+  --json
+```
+
+## Gateway 网关向导 RPC
+
+Gateway 网关通过 RPC 暴露向导流程（`wizard.start`、`wizard.next`、`wizard.cancel`、`wizard.status`）。
+客户端（macOS 应用、控制界面）可以渲染步骤而无需重新实现新手引导逻辑。
+
+## Signal 设置（signal-cli）
+
+向导可以从 GitHub releases 安装 `signal-cli`：
+
+- 下载适当的发布资源。
+- 存储在 `~/.openclaw/tools/signal-cli/<version>/` 下。
+- 将 `channels.signal.cliPath` 写入你的配置。
+
+注意事项：
+
+- JVM 构建需要 **Java 21**。
+- 可用时使用原生构建。
+- Windows 使用 WSL2；signal-cli 安装在 WSL 内遵循 Linux 流程。
+
+## 向导写入的内容
+
+`~/.openclaw/openclaw.json` 中的典型字段：
+
+- `agents.defaults.workspace`
+- `agents.defaults.model` / `models.providers`（如果选择了 Minimax）
+- `gateway.*`（模式、绑定、认证、tailscale）
+- `channels.telegram.botToken`、`channels.discord.token`、`channels.signal.*`、`channels.imessage.*`
+- 当你在提示中选择加入时的渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）（名称在可能时解析为 ID）。
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`openclaw agents add` 写入 `agents.list[]` 和可选的 `bindings`。
+
+WhatsApp 凭证存储在 `~/.openclaw/credentials/whatsapp/<accountId>/` 下。
+会话存储在 `~/.openclaw/agents/<agentId>/sessions/` 下。
+
+某些渠道以插件形式提供。当你在新手引导期间选择一个时，向导会在配置之前提示安装它（npm 或本地路径）。
+
+## 相关文档
+
+- macOS 应用新手引导：[新手引导](/start/onboarding)
+- 配置参考：[Gateway 网关配置](/gateway/configuration)
+- 提供商：[WhatsApp](/channels/whatsapp)、[Telegram](/channels/telegram)、[Discord](/channels/discord)、[Google Chat](/channels/googlechat)、[Signal](/channels/signal)、[iMessage](/channels/imessage)
+- Skills：[Skills](/tools/skills)、[Skills 配置](/tools/skills-config)