--- 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 -f target_ref= -f release_gate=true -f pull_request_number= ``` 运行必须位于 分支引用上，以便 `head_sha` 匹配，且标题会变为 `CI release gate `，从而被 `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 实现。