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

动态文档。 本页面在实施层面跟踪系统管家新手引导的重新设计， 并随各阶段落地持续更新。最后一个阶段合并后， 本页面将改写为面向用户的新手引导指南，并加入 文档导航。在此之前，它有意不纳入 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——应用推荐（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 分支上分派发布门控：

  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 实现。