---
read_when:
    - 你正在实施或审查新手引导重新设计的某个阶段
summary: 托管员新手引导重新设计实施计划（持续更新文档）
title: 新手引导重新设计
x-i18n:
    generated_at: "2026-07-26T07:01:57Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: f892991583d0b77a670e9bf7aa5a0c74af3b3eac9e7b0448706486254eb7e2a0
    source_path: start/onboarding-redesign.md
    workflow: 16
---

# 新手引导重新设计实施计划

> **动态文档。** 本页面在实施层面跟踪系统管家新手引导的重新设计，
> 并随各阶段落地持续更新。最后一个阶段合并后，
> 本页面将改写为面向用户的新手引导指南，并加入
> 文档导航。在此之前，它有意不纳入 `docs.json`。

## 核心目标

非技术用户输入 `openclaw onboard`（或打开应用）后，会看到
一个统一的对话式角色——OpenClaw，即系统管家（“custodian”仅为
内部名称；用户始终看到“OpenClaw”）——它会找到用户的 AI，
通过告知默认值而非提问来完成所有设置，将智能体的孵化呈现为一个
可见的身份诞生时刻，并在此后始终作为系统的照管者保持可联系。
默认即可获得魔法般的体验，只有一个同意边界，没有死路。

设计原则（已经确定，请勿随意重新讨论）：

- **告知默认值并支持轻松撤销**，以此取代阻塞式提问。唯一的
  硬性要求是推理功能可用；其他一切都只是可选建议。
- **第零个问题是同意边界**：“Full access”（推荐）意味着
  设备发现会静默自动进行；“Ask first”则将所有设备发现——AI
  扫描、应用扫描和记忆源扫描——统一置于一次
  明确同意之后，同时提供一条完全手动且绝不扫描的路径。
- **以对话作为 UI，并逐步获得智能**：系统管家界面
  在任何 AI 可用之前就已存在（使用脚本化对话），在路由验证成功的
  瞬间转为由模型驱动，并明确告知用户。它绝不会伪装智能：
  在路由验证前输入自由文本时，会得体地回应“先让我把大脑运转起来”。
- **孵化是一场仪式**：保持在同一线程中，切换头像，智能体为自己
  命名并选择自己的形象。系统管家只讲解一次层级关系：“可以向我询问
  系统相关问题，也可以直接询问你的智能体——它会转达。”
- **信任按来源分级**：官方目录条目可以预先选中；
  无论模型排名如何，第三方 ClawHub Skills 都绝不会预先选中，
  而且其标签会说明它们将安装发布者的代码。
- **已配置的安装不可侵犯**：再次运行新手引导只是一次验证
  流程。它绝不会重新应用设置，也绝不会重启 Gateway 网关服务。
- **终端是后备方案，而不是问题**：当 Gateway 网关可访问时，优先使用浏览器
  仪表板；绝不询问“使用终端还是浏览器？”。
- **弱模型使用精简界面**（自动 `localModelLean`），并以
  通俗语言说明——绝不使用工具、代码模式或上下文窗口等术语。

## 当前已发布流程（阶段 1-3 完成后）

全新 macOS 安装上运行 `openclaw onboard` 的顺畅路径——总共按四次 Enter：

1. 安全说明 → 按一次 Enter 确认（持久保存；以后不再询问）。
2. **第零个问题**：“How should I set things up?”——Full access（推荐）
   或 Ask first。选择持久保存为 `wizard.accessMode`；再次运行时默认采用已保存的
   选择。受限模式 + “configure manually”可在不进行
   任何扫描的情况下进入提供商选择器，同时也会跳过记忆源扫描。
3. **设备发现过程展示**：检测编码 CLI、环境变量密钥和本地运行时；
   发现编码智能体时会给出一句俏皮提示；按顺序实时测试候选项，并将失败项
   静默汇总为一行摘要（详细信息位于“See other
   options”之后）。第一个可用路由会作为默认值告知用户，并提供
   单键进入完整选择器的路径；浏览其他选项或跳过仍会保留
   已可用的路由。
4. 记忆导入建议（Claude Code / Codex / Hermes）；拒绝设备发现时
   跳过。
5. 仅限全新安装：自动应用标准设置方案
   （工作区、Gateway 网关服务、会话——与对话中输入
   “yes”时运行的方案相同）。已配置的安装会输出“already set up”，且绝不触碰
   服务。
6. **应用推荐**：使用已验证的模型，将已安装应用与
   官方目录 + ClawHub 匹配；官方渠道插件默认勾选，
   第三方 Skills 需主动选择并带有警告标签。可以跳过；
   终止开关为 `wizard.appRecommendations`。
7. **孵化**：当 Gateway 网关可访问时，浏览器交接会打开（GUI）或
   输出（无头模式/SSH）仪表板 URL，并等待 Control UI
   连接——“Dashboard connected — continuing in your browser.”。否则，或
   使用 `--tui` 时，将打开终端 TUI，其中已预置启动孵化
   消息，随后智能体会自我介绍。

远程 Gateway 网关的新手引导保留旧版对话式交接
（`handoffMode: "chat"`）；设置必须应用于远程 Gateway 网关。

## 阶段

| #   | 阶段                                                                                                                                                     | 界面                 | 状态                                                                                                                            |
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| 1   | 已安装应用的插件推荐（扫描、候选项、AI 匹配器、向导步骤、`device.apps` 节点命令）                                              | 经典 + 引导式 CLI | 已合并（[#109668](https://github.com/openclaw/openclaw/pull/109668)）                                                              |
| 2   | CLI 系统管家主干（第零个问题、设备发现过程展示、自动应用 + 孵化）                                                                                | 引导式 CLI           | 已合并（[`a83ed13204f1`](https://github.com/openclaw/openclaw/commit/a83ed13204f118adf1009e5ac88d5afe1905b86c)）                   |
| 3   | 浏览器优先交接（GUI 会话检测、等待仪表板连接、TUI 作为后备方案）                                                                | CLI → Web            | 已合并（[#110054](https://github.com/openclaw/openclaw/pull/110054)）                                                              |
| 4   | Web 系统管家界面（选项卡片、`openclaw.chat` 上类型化的 `question` 字段、向导步骤镜像、首次运行交接）                                 | Control UI           | 已合并（[#110141](https://github.com/openclaw/openclaw/pull/110141)、[#110242](https://github.com/openclaw/openclaw/pull/110242)） |
| 5   | 孵化与启动（具备单次语义的推荐存储、自主命名的诞生流程、全新设置后自动孵化交接；头像阶梯延后实现） | 智能体启动      | 已合并（[#110173](https://github.com/openclaw/openclaw/pull/110173)、[#110331](https://github.com/openclaw/openclaw/pull/110331)） |
| 6   | 系统管家常驻 PR1（固定侧边栏入口、设置中的 Ask OpenClaw、使用常规界面框架的照管者问候；事件解说和渠道召唤属于 PR2）    | Web + 渠道       | 已合并（[#110269](https://github.com/openclaw/openclaw/pull/110269)）                                                              |
| 7   | 韧性（配置损坏时系统管家仍可访问、挽救部分界面、自动运行 Doctor）                                                                   | Gateway 网关              | 后续工作                                                                                                                         |

## 各阶段实施说明

### 阶段 1——应用推荐（PR #109668）

- 扫描器：`src/infra/installed-apps.ts`（无需 TCC 的 macOS 枚举；会跟随
  符号链接的 `.app` 应用包）。
- 候选项：官方目录 + ClawHub 搜索，总体预算为 20s，离线时可平稳
  降级为仅使用目录候选项。目录条目是没有顶层 `id` 的软件包
  清单——候选项以解析后的插件 ID 为键（已使用真实内置目录进行
  回归测试；曾经以 `entry.id` 为键，导致整个目录折叠成一个条目，
  丢失所有官方推荐）。
- AI 匹配器：在已验证路由上执行一次补全
  （`src/system-agent/setup-app-recommendations.ts`）；不使用精心维护的软件包 ID 映射——
  模型会排除偶然的名称重合。输出受解析后模型自身的
  `maxTokens` 预算限制（未传入显式上限时，由流式层应用该预算）。
- **供应链防护**：ClawHub 列表文本由发布者控制，并会
  进入匹配器提示词，因此列表可以将自己宣传为
  “recommended”。只有官方目录条目可以预先选中；ClawHub
  Skills 始终需要明确勾选，并标记为“third-party ClawHub
  skill; installs its publisher's code”。
- 节点命令 `device.apps`（TS 节点主机，与 Android 信封格式一致），默认
  禁止共享；Gateway 网关终止开关为 `wizard.appRecommendations`。
- 交付位于经典向导和引导式系统管家流程中
  （`src/wizard/setup.app-recommendations.ts`）；将其重新定位到启动流程末尾
  仍属于阶段 5（该服务已支持注入清单来源）。单次语义（仅在接受前
  提供一次，并存储扫描结果）也将随阶段 5 的存储一起落地；目前再次运行时会
  重新提供。
- 同时修复：自定义 `completeSetupInference` 提示词不再继承
  验证探测的 32-token 输出上限（`SETUP_INFERENCE_TEST_MAX_TOKENS`
  仅适用于“reply OK”探测）。

### 阶段 2——CLI 系统管家主干（PR #109841）

- `src/commands/onboard-guided.ts` 中的流程重构；远程 Gateway 网关新手引导
  通过 `handoffMode: "chat"` 保留旧版聊天交接。
- 第零个问题会持久保存 `wizard.accessMode`（“full” | “guarded”）；再次运行时
  默认采用已保存的选择（接受默认值绝不能静默地将 guarded
  降级为 full）。guarded + 手动模式使用
  `listManualSetupInferenceOptions`（仅配置/清单，不进行探测），并
  跳过记忆源扫描。
- 设备发现：静默收集失败（单行摘要；详细信息位于
  “See other options”之后）、编码智能体俏皮提示、告知路由默认值。提示中的
  会话数量暂缓实现（目前仅作定性描述），直到存在低成本的
  会话计数接口。
- 全新安装：`applySystemAgentSetup`（确定性的对话式
  “yes”），随后通过 `launchTuiCli` 孵化，并预置启动消息。
  已配置的安装（已存在模型或 Gateway 网关配置——向导
  时间戳不能证明任何事情，因为 configure/doctor 也共用它们）：
  仅执行验证——不应用设置，也不重启 Gateway 网关服务。应用失败时
  回退到对话式聊天。

### 阶段 3——浏览器优先交接（PR #110054，已合并）

- `src/commands/onboard-browser-handoff.ts` 负责纯图形会话
  检测（`SSH_CONNECTION`/`SSH_TTY`；Linux 上为 `DISPLAY`/`WAYLAND_DISPLAY`）
  以及 60 秒 GUI / 300 秒 SSH 等待。引导式新手引导目前
  仅在 macOS 上启用移交；`--tui` 和其他平台保留
  终端退出通道。Linux/Windows 支持将在后续跟进。
- Dashboard 链接使用与经典完成流程相同的 `resolveAdvertisedControlUiLinks`、
  `resolveLocalControlUiProbeLinks` 和 `buildOnboardingControlUiUrl` 辅助函数。
  浏览器启动使用共享的 `openUrl` 辅助函数。
- 就绪检查通过现有的 `system-presence` RPC 进行轮询，充当**提供已配置共享密钥的 CLI 模式 local loopback
  客户端**——这是每条 `openclaw` 命令使用的可信路径。使用原始共享身份验证的 Control UI 客户端
  会在 SecretRef Gateway 网关上被拒绝，并提示 "device identity required"。可达性
  预检解析的目标（及密钥）与等待循环相同，因此
  门控与等待绝不会在身份验证上产生分歧。只有当已连接的
  `openclaw-control-ui`/`webchat` 在线状态行相对于启动前基线是新增的，
  移交才会完成（已打开的 Dashboard 无法
  使其完成）。
- `gateway.controlUi.enabled: false` 会在显示任何 URL 之前短路。
- 已针对采用相同隔离配置的 Gateway 网关完成端到端验证：打印 URL → 真实
  浏览器连接 → "Dashboard connected — continuing in your browser" → 无
  终端退出通道。此前因 "token mismatch" 导致的搁置是测试工具
  造成的假象——请参阅下方测试操作手册。

### 阶段 4 — Web 管理员界面（已合并：#110141、#110242）

- `/custodian` 页面基于 `openclaw.chat`，使用选项卡片组件
  （2-4 张卡片，最多推荐一项，始终可跳过）；通过
  `?onboarding=1` 提供新手引导界面框架；模型设置首次运行完成后移交至此。
- 结构化问题是 `SystemAgentChatResult` 上类型化的附加 `question` 字段
  （每个选项都有 `reply` 文本；面向 macOS 应用/TUI 时，正文始终可以独立呈现）。生成方包括：
  两种新手引导欢迎变体，以及带有 2-4 个封闭选项的托管向导选择/确认步骤——真实渠道
  向导会将其呈现为卡片。PR1 的字符串标记临时方案已删除。
- 会话所有权按 Gateway 网关 URL + 提供的每项凭据划分范围
  （令牌、密码、引导令牌、已存储的设备令牌——在短暂的 hello 中断期间保持粘性）；
  失败的用户轮次绝不可重放；敏感输入会逐字发送，并在记录中
  进行遮蔽。

### 阶段 5 — 孵化与引导（已合并：#110173、#110331）

- 管理员会创建一个无名智能体（工具调用）；该智能体的引导流程
  从自我命名开始。PR1 交付的仪式最多包含三个节拍（名称 → 灵魂
  描述行 → Skills 问题），并将自行绘制头像/图像生成的阶梯式流程
  （模型生成的候选项 → 预设标记 → 保留徽标）推迟至后续跟进。同一
  线程中更换头像；爪印仍专供管理员使用。商定的身份会持久化两次：
  写入 `IDENTITY.md`/`SOUL.md`（智能体读取的内容），并通过
  `openclaw agents set-identity` 写入（渠道和 UI
  显示的内容）。
- 推荐项（阶段 1 服务，采用仅一次语义的已存储扫描）作为
  引导文件删除前的最后一个引导步骤出现："minimal set
  or maximum convenience?" 引导流程通过
  `openclaw onboard recommendations --json` 读取已存储的建议（仅包含不透明的安装 ID），并在处理选择后
  确认该建议，因此绝不会再次询问。渠道连接按钮附带各渠道的设置操作手册；
  智能体以对话方式收集
  凭据，并将配置写入操作转交给管理员
  （"asking OpenClaw…" 是规范表达方式）。
- 自我学习应以询问方式提出，而不是直接宣布，同时也作为 Skills 工作坊
  的同意确认；应说明 ClawHub 的发布信任、扫描、验证和完整性
  检查，以及发布者代码警告——绝不要暗示每个版本都已签名。
- 自动孵化已交付：全新安装的设置应用操作会宣布孵化并
  完成移交（终端 TUI / Gateway 网关客户端使用 `open-agent`）；Web 页面
  会进入智能体聊天，并预填 "Wake up, my friend!" 草稿。
  只有在写入后的干净验证通过时才会触发移交。删除后智能体数量为零时
  提供创建选项（而非自动创建）仍属于后续优化。

### 阶段 6 — 管理员在线状态（PR1 已合并：#110269；评论/召唤属于 PR2）

- PR1 已交付：默认固定的 "OpenClaw" 侧边栏条目（适用于新配置文件；
  现有用户保留已保存的固定项，并可通过 customize/More 访问）、作为 Settings
  第一个条目的 "Ask OpenClaw"，以及使用常规界面框架的 `/custodian` 访问，
  这些访问会请求管理员问候语（不使用新手引导欢迎变体），
  Exit setup 仅在新手引导模式下呈现。停靠式内联 Settings 窗格
  需要提取共享会话视图（后续跟进）。
- 带有防 Clippy 护栏的事件响应式评论：仅针对有重大影响或
  失败的更改；除非被询问，否则每次 Settings 访问最多一次。相同的
  事件接缝使管理员日后能够为身份验证降级或渠道故障发声。
- 渠道：日常使用中不可见（由智能体转达）；可通过显式
  召唤以及同一线程中的智能体宕机事件触达，并在平台允许时使用其自身名称和
  爪印头像。
- 设置期间检测到弱模型：自动设置 `localModelLean`，管理员
  会用直白语言说明情况并提供升级选项。
- 管理员知道自己的内部昵称（"some folks call me the
  custodian — OpenClaw's fine"），并始终按名称指代智能体。

### 阶段 7 — 韧性（构建前需要所有者决策）

最初的设想——“无论配置损坏到什么程度，都必须能够触达管理员”——
与仓库的安全策略冲突：根指南规定，当配置在结构上无效时，
Gateway 网关会**拒绝启动**，并且只有 SecretRef 所有者故障会降级为
已配置但不可用的能力。从无效配置提供任何界面都属于策略变更，
而非实现细节。以下两个范围需二选一：

- **选项 A（推荐，符合策略）：CLI 端自动 Doctor。** 当
  Gateway 网关或 CLI 因已知形态的无效配置而启动失败时，CLI 会提议
  （或在获得同意后运行）`openclaw doctor --fix`，随后重试一次并
  清楚报告结果。Gateway 网关行为不变；管理员仍可通过
  现有的 SecretRef 降级路径和终端触达。
- **选项 B（需要所有者明确批准 + 安全审查）：Gateway 网关
  最小界面模式。** 当配置在结构上无效时，启动一个锁定的
  界面，仅提供管理员会话和 Doctor 操作。这将改写失败时保持关闭的启动契约，
  因此在编写任何代码前，必须定义其自身的入口保护方案。

阶段 4-6 的剩余跟进项（已跟踪，尚未排期）：用于孵化流程的头像/图像生成
阶梯式流程；macOS 应用对类型化 `question` 字段的呈现；管理员的
停靠式内联 Settings 窗格（需要提取共享会话视图）；
事件响应式评论和渠道召唤/智能体宕机恢复
（阶段 6 PR2）；为弱模型自动执行 `localModelLean`；现有
用户已保存的侧边栏固定项是否应采用 OpenClaw 条目。

## 测试和落地操作手册（来之不易；阶段 4-6 开始前请先阅读）

- **`OPENCLAW_STATE_DIR` 不会隔离 Gateway 网关服务。**
  LaunchAgent 标签（`ai.openclaw.gateway`）在整台机器范围内全局生效：使用隔离状态目录的
  全新安装新手引导测试会重写并重启真实机器上的
  服务（包装脚本位于隔离目录中；清理该目录后，下次
  服务启动将失败）。进行任何全新安装测试后，应从真实环境中使用
  `openclaw gateway install --force && openclaw gateway
restart` 恢复，并验证 plist。产品后续跟进：
  按状态目录划分作用域的服务标签，或由新手引导检测外部服务。
- **安全的端到端测试工具**：在隔离配置中预先写入 `gateway`
  部分（这样新手引导会采用已配置安装路径，绝不会触碰
  服务），并在备用端口上使用普通令牌，将 `openclaw gateway run` 作为普通前台进程运行。
  该测试工具验证了阶段 3 循环，包括真实浏览器连接。
- **身份验证路径因客户端身份而异，而不只取决于凭据。** 在线状态和
  其他操作员读取操作使用 CLI 模式 local loopback 客户端，其凭据来自相同
  配置。使用令牌身份验证的 Gateway 网关需要共享密钥；SecretRef/none
  Gateway 网关可在没有令牌时回退到可信 local loopback 身份验证。标识为 Control UI
  的浏览器客户端需要设备身份或安全上下文
  local loopback 授权。若探测请求针对提供另一份
  配置的 Gateway 网关进行身份验证（参见 LaunchAgent 陷阱），则会因
  "token mismatch" 失败——这一假象曾短暂阻碍阶段 3。
- **完成探测**：`runSetupInferenceTest` 将验证探测限制为
  32 个输出令牌；自定义提示会绕过该限制，并受模型自身的
  `maxTokens` 约束。推理模型会先用隐藏推理消耗该预算——
  文本为空的轮次通常意味着预算已在此耗尽。
- **智能体落地需要精确匹配头部提交的托管 CI。** 在组织负载较高时，
  重型 `CI` 工作流可能不会因推送而进入队列；维护者的后备方案是
  在 PR 分支上分派发布门控：

  ```bash
  gh workflow run ci.yml --ref <branch> -f target_ref=<head-sha> -f release_gate=true -f pull_request_number=<pr>
  ```

  运行必须位于
  分支引用上，以便 `head_sha` 匹配，且标题会变为
  `CI release gate <sha>`，从而被 `scripts/verify-pr-hosted-gates.mjs`
  接受。然后照常执行 `scripts/pr` 准备/合并。

- **除聚焦测试外，CI 还会强制执行的门控**：文档地图
  （添加任何文档页面后执行 `pnpm docs:map:gen`）、oxlint（`no-map-spread`、
  `max-lines`——拆分文件，绝不要抑制）、`check:test-types`、knip
  死代码检查（仅导出生产代码使用的内容；测试通过公共 API 进行），
  以及实时测试分片分类器
  （`test/scripts/test-live-shard.test.ts` 必须列出任何新的 `*.live.test.ts`）。

## 决策日志

- 带终止开关的魔法扫描，而非以同意为先（阶段 1；持久化输出会在扫描前披露模型和 ClawHub 的使用情况，结果说明中也会再次提及）。
- 完整的纵向流程，包括节点 `device.apps` 命令（阶段 1）。
- 第三方 ClawHub Skills 绝不会被预选，并会标明将安装发布者的代码；官方条目可以预先勾选（阶段 1，已发布的安全策略）。
- 使用两张访问选项卡，而非三张；将同意步骤前置并融入选择中（阶段 2）。
- 自动孵化并发布通知，而非显示阻塞式按钮（阶段 2/5）。
- 浏览器优先：终端孵化是后备方案，绝不询问“终端还是浏览器？”（阶段 3）。
- 守护者会在渠道中出现（召唤 + 恢复），而非仅限 Web/CLI（阶段 6）。
- 孵化在同一线程中进行，并会更换头像；完成后，应用会过渡到常规 UI（阶段 5）。
- 设置界面保留名称“设置”；守护者位于其中（以及侧边栏中），而非取代该界面（阶段 6）。
- 选项卡受以下约束：2–4 个选项、恰好一个推荐项、始终可以跳过；新手引导和智能体提问工具使用同一个组件（阶段 4）。
- “正在询问 OpenClaw……”是规范的委派表达方式；灵魂可以增添个性，但工具叙述保持朴素（阶段 5）。
- 在解释弱模型裁剪时，面向用户的文案绝不使用“代码模式”“工具”或“上下文窗口”（阶段 6）。

## 已知缺口和后续工作

- LaunchAgent 标签未按状态目录限定作用域（这是上文所述的测试陷阱，也是真实存在的多实例产品缺口）。
- 推荐项的仅一次语义和已存储的扫描（阶段 5）；目前重新运行时会再次提供推荐项。
- 浏览器接续仅支持 macOS；Linux/Windows 支持尚待启用。
- 关于会话数量的俏皮话是定性的；获取具体数量需要一个低开销的会话计数接口。
- 浏览器接续会进入常规仪表板；新手引导模式下指向守护者的深层链接将在阶段 4 实现。
