OpenClaw CLI 评分指南：cli-install-update-onboard-doctor 完整性评分细则与算分实践

OpenClaw 的成熟度记分卡（maturity scorecard）把系统能力拆分为若干"表面"（surface），其中 cli 表面覆盖从安装、引导（onboarding）到修复（doctor）与升级的完整 CLI 操作者旅程。本文以仓库内 .agents/skills/claw-score/references/completeness/cli-install-update-onboard-doctor.md 评分细则为主体，结合 taxonomy.yaml、qa/maturity-scores.yaml 与 docs/cli、src/cli 的实际证据，完整讲清楚该表面的七个类别、逐项评分问题、与默认完整性流程的差异，以及如何落地一次可验证的完整性打分。读完后你能够独立为 CLI 表面复算 Completeness 分数，并知道每个类别的判定依据应来自哪些仓库工件。

评分细则的定位：claw-score 技能与数据源模型

该细则文件是 .agents/skills/claw-score/ 技能的一部分。这个技能是 OpenClaw 仓库内维护成熟度记分卡的本地化工作流，它拥有以下工件的操作权：

• taxonomy.yaml：手工维护的"表面—等级—类别—特性—coverage ID—文档引用—完整性指令路径"唯一事实源（source of truth）；
• qa/maturity-scores.yaml：Quality、Completeness 与 LTS 评审状态的提交态聚合源；
• qa/scenarios/index.yaml：QA 场景索引；
• 生成的公开文档 docs/maturity/scorecard.md 与 docs/maturity/taxonomy.md 由 pnpm maturity:render 产出，不允许手改生成的 Markdown。

按技能文档（SKILL.md）的"Source Model"约定：coverage ID 采用 namespace.behavior 点分形式，同一特性可以列多个 ID（它们是 AND 语义的证明目标，而不是别名）；分数修改必须基于公开或脱敏工件证据，主观分数变更要做最小可辩护编辑并留下证据路径。

表面专属评分问题（Surface-Specific Scoring Questions）

细则的核心是对 CLI 表面的每个类别反复追问五个问题（原文即以下五条）：

1. 普通操作者能否仅靠 CLI 端到端完成该类别的任务？（Can a normal operator complete the job end to end from the CLI?）
2. 对类别重要的预期环境是否都有覆盖——本地安装、远程 Gateway 使用、受监督服务（supervised services）、Windows/WSL2？
3. 相关的主要生命周期阶段是否齐备：setup（搭建）、inspection（检查）、change（变更）、repair（修复）、upgrade（升级）？
4. 常见恢复与排障分支是否存在，还是工作流在 happy path 之后直接"死胡同"？
5. 文档中列出的主要操作者期望是否仍有未实现项？

注意第 2 条对 Windows 与 WSL2 的专门说明：评分要对照"预期支持体验"（intended supported experience），而不是要求与 macOS/Linux 内部实现完全对等。

与默认完整性流程的差异（Surface-Specific Guidance）

claw-score 技能定义了一个默认完整性流程（Default Completeness Process）：Completeness 对照"操作者可见的预期工作流"打分，而不是对照测试广度或实现质量。CLI 表面细则在此之上给出四条修正：

• Completeness 度量的是"安装、引导、配置、修复、升级"这条 CLI 操作者旅程，横跨预期环境与恢复分支；
• 要按完整操作者旅程评分，而不是只评安装或 happy path；
• 凡是类别暴露了 repair（修复）、migration（迁移）、remote（远程）、平台专属分支的，这些分支应被要求存在；
• Windows 与 WSL2 按预期支持体验评分，而非 macOS/Linux 内部对等。

技能文档同时规定了优先级：当表面的 Surface-Specific Scoring Questions 与 Surface-Specific Guidance 与默认流程冲突时，以表面指令为准，并在分数理由中体现该表面专属指令。

默认完整性分档（Bands）

细则文件本身不重复分档，分档继承自技能文档的默认流程，共五档：

档位	分数区间	含义
Clawesome	95–100	覆盖预期工作流、变体与恢复分支，仅剩少量打磨缺口
Stable	80–95	预期工作流集合大体齐备，仅存在有界的缺失分支
Beta	70–80	主工作流存在，但仍有重要分支或恢复路径缺失
Alpha	50–70	仅存在部分能力集合，可完成部分核心任务而非完整工作流
Experimental	0–50	仅暴露预期能力集的碎片

三条默认指导值得记住：工作流完整、变体齐备时给高分；只有 happy path、重要变体未文档化或未实现、恢复/状态路径缺失时降分；测试稀薄属于 Coverage 问题，实现脆弱属于 Quality 问题，都不应拉低 Completeness。

类别范围（Category Scope）与 taxonomy 逐类映射

细则的 Category Scope 用一行列出了 CLI 表面的七个类别。在 taxonomy.yaml 中，cli 表面（family: core，level: stable / M4）以 completeness_instructions: references/completeness/cli-install-update-onboard-doctor.md 显式引用本细则。下表是细则类别范围与 taxonomy 类别 ID 的对应关系，以及每个类别的特性清单（特性名均为 taxonomy 中的 feature 条目）：

细则类别（Category Scope）	taxonomy 类别 ID	特性（features）
CLI Setup	cli.cli-setup	Installer scripts、Local prefix install、Package-manager installs、Supported Node runtime、Source checkout install、CLI entrypoint
Onboarding and Auth Setup	cli.onboarding-and-auth-setup	Guided onboarding、Targeted reconfiguration、Auth choices、Gateway auth storage、Remote onboarding
Plugin and Channel Setup	cli.plugin-and-channel-setup	Channel picker、Plugin install sources、Channel account setup、Post-setup probes、Remote gateway caveat
Gateway Service Management	cli.gateway-service-management	Foreground gateway runs、Service install and control、Service auth wiring（Create / Discord config / System agent setup）、Drift and reinstall recovery、Service health checks
CLI Observability	cli.cli-observability	Status snapshots、Health snapshots、Remote log tailing、Diagnostics export、Support-safe redaction
Doctor	cli.doctor	Interactive repair、Config migration、Auth and SecretRef checks、Plugin validation and repair、Lint and JSON findings、Extra gateway discovery、Supervisor drift repair、Port and startup diagnosis、Runtime path checks、Restart guidance
Updates and Upgrades	cli.updates-and-upgrades	Update channels、Install-kind switching、Managed gateway restart、Update status and RPC、Plugin convergence

taxonomy 中每个类别还附带 docs（该类别证据所在的文档路径）与 human_lts_override 标记：七个类别中除 cli.plugin-and-channel-setup 为 false 外，其余六类均为 true——这与当前 LTS 状态 partial（6/7）完全吻合（见下文"当前评分状态"）。

类别证据落点：从细则条目到仓库工件

细则只定义"问什么"，"拿什么回答"则来自 taxonomy 的 docs 引用与仓库实际实现。按类别梳理关键证据落点：

CLI Setup：安装器、Node 运行时与入口

• 系统要求（docs/install/index.md）：Node 22.22.3+、24.15+ 或 25.9+，推荐 Node 26；安装器在缺失 Node 时于 macOS 预置 Node 26、Linux 预置 Node 24 LTS；pnpm 仅在源码构建时需要。
• 安装路径覆盖三类：托管安装器脚本（macOS/Linux/WSL2 的 install.sh、Windows PowerShell 的 install.ps1，可用 --no-onboard 跳过引导）、本地前缀安装 install-cli.sh（把 Node 与 OpenClaw 都收敛到 ~/.openclaw 前缀下）、以及操作者自管 Node 时的 npm/pnpm/bun 全局安装（含 npm 12 --allow-scripts=openclaw 的生命周期脚本策略说明）。
• 仓库内的安装脚本实体位于 scripts/（如 install.sh、install-cli.sh、install.ps1），源码安装与 CLI 入口的启动逻辑在 src/cli/。

Onboarding and Auth Setup

• openclaw onboard 是引导式入口（workspace、gateway、模型认证、channels、skills、健康检查），openclaw configure 用于定向重配置；远程引导（remote onboarding）明确"本地配置什么 vs 远程主机必须已有什么"。
• 对应文档：docs/cli/onboard.md、docs/cli/configure.md、docs/start/onboarding-overview.md。

Gateway Service Management 与 CLI Observability

• 服务生命周期：前台运行、install / status / start / stop / restart 等受管服务流、auth 接线、漂移与重装恢复、安装/重启后的健康检查；文档落点为 docs/cli/gateway.md 与 docs/gateway/troubleshooting.md。
• 可观测性：openclaw status（状态快照）、openclaw health（快速网关健康读取，支持 verbose/JSON）、openclaw logs（经 RPC 的远程日志 tail，支持 follow 与 JSON）、诊断导出与面向支持的脱敏约定；文档落点为 docs/cli/status.md、docs/cli/health.md、docs/cli/logs.md、docs/gateway/diagnostics.md。
• CLI 侧实现集中在 src/cli/（gateway-cli.ts、logs-cli.ts 等入口文件及对应测试），这是细则中"能否仅靠 CLI 端到端完成"这类问题的直接实现证据。

Doctor：修复姿态与检查项

docs/cli/doctor.md 把细则中 Doctor 类别的十个特性落实为一组"姿态"（postures），这是本类别最可验证的源码级证据：

姿态	命令	行为
Guided checks	openclaw doctor	传统健康流程；可复制 legacy 配置并应用自动状态迁移
Advisory JSON	openclaw doctor --json	只读发现项；产出报告后成功退出
Repair	openclaw doctor --fix	应用支持的修复；非交互修复不安全时使用提示确认
Lint	openclaw doctor --lint [--json]	只读发现项，带基于阈值的退出码，供 CI 门禁用
Shared SQLite maintenance	openclaw doctor --state-sqlite compact	显式检查点、压缩并校验规范共享状态库
Session SQLite tools	openclaw doctor --session-sqlite <mode>	检查/维护 SQLite 会话并显式导入历史数据

几个与评分直接相关的实现事实（均见该文档）：

• 只读诊断应使用 --lint 或裸 --json；普通 doctor（含 doctor --non-interactive）即使没有 --fix 也可能复制 legacy 配置并迁移状态——--non-interactive 抑制的是提示，不是写入。
• 显式修复（explicit repair）会先停止匹配的受管 Gateway、排除其他进程、验证就绪后只重启一次服务，且保留服务定义；对自动分诊（automatic triage）子树内的修复，Doctor 会拒绝在需要停服的场景执行，避免取消正在进行的恢复。
• 远程模式（gateway.mode: "remote"）下，健康检查失败不会触发本地服务安装/启动/重启提示——这正是细则中"remote 分支必须存在"问题的实现侧答案。
• --force 单独出现不进入修复模式，仍保持 guided 姿态并要求交互确认；--fix/--repair/--yes 组合下才允许激进修复，且不绕过服务所有权、写访问或交互确认要求。

Updates and Upgrades

openclaw update 支持 stable/beta/dev 更新通道，支持包安装与 git/源码安装之间的切换（如 openclaw update --channel dev / --channel stable 在本地前缀安装中），并规定受管 Gateway 在更新流程中何时停止、重启或刻意不动。文档落点：docs/install/updating.md、docs/cli/update.md；CLI 侧实现见 src/cli/update-cli.ts 及 src/cli/ 下的 update-cli 目录与其 process 测试。

评分工作流与验证命令

技能文档规定为某表面打分或刷新分数的七步流程：

1. 读 taxonomy.yaml 中该表面（CLI 即 id: cli 的 surface 条目）；
2. 读 references/completeness/ 下该表面的完整性细则（即本文主体文件）；
3. 从文档、源码、测试与 QA 场景元数据收集公开仓库证据；
4. 优先使用既有 release profile 的 qa-evidence.json 工件作为执行证明；
5. 仅基于公开或脱敏工件证据更新 qa/maturity-scores.yaml 的 Quality、Completeness 与 LTS 评审状态；
6. 运行技能给出的 schema 校验命令（用 node --import tsx 加载 YAML 与 readValidatedQaMaturityScoreSources 校验 taxonomy.yaml、qa/scenarios/index.yaml 与 maturity scores schema）；
7. 若改了文档文字跑 pnpm check:docs，改了 coverage ID 或 profile 成员跑 pnpm openclaw qa coverage --json。

qa-evidence.json 工件提供每次运行的记分卡证据；release profile 工件是 Coverage 维度的事实源，可用于富化工件文档，但不作为 inventory 提交。

当前评分状态：CLI 表面在记分卡中的位置

qa/maturity-scores.yaml 中 cli 表面的最新提交态数据（last score run 完成于 2026-08-02）：

• 等级：Stable（M4）；
• Quality：83（Stable 档）；
• Completeness：90（Stable 档）；
• LTS：partial，supported_categories: 6 / total_categories: 7。

这与细则和 taxonomy 形成闭环：Completeness 90 落在"预期工作流集合大体齐备、仅有有界缺失分支"的 Stable 档，符合细则"按完整操作者旅程而非 happy path 评分"的要求；LTS 的 6/7 则精确对应 cli.plugin-and-channel-setup 类别 human_lts_override: false、其余六类为 true 的 taxonomy 标记。注意 taxonomy 中该表面还记录了自身 last_score_run（completed_at: 2026-05-30），与 qa/maturity-scores.yaml 的 2026-08-02 属于不同工件的各自运行记录，引用时应以各自文件为准。

实操要点与限制

• 打分对象是"操作者可见的工作流存在性"，不是测试广度（Coverage）或实现健壮性（Quality）；细则明确禁止因测试稀薄或实现脆弱下调 Completeness。
• Windows/WSL2 分支按"预期支持体验"评分，不要求与 macOS/Linux 内部实现逐项对等；这是该细则区别于其他表面细则的关键修正之一。
• 证据链要求：每个关键结论应能回溯到 taxonomy 条目、docs/cli/docs/install/docs/gateway 文档、src/cli 源码或其测试、或 release profile 的 qa-evidence.json 工件；分数理由需体现表面专属指令的适用。
• 适用前提：本套流程依赖 process_version: 3 的 taxonomy 结构与 extensions/qa-lab/src/scorecard-taxonomy.ts 导出的校验工具；生成的 docs/maturity/*.md 只能经渲染流程更新，不得手改。

按上述细则完成一次 CLI 表面的评分，产出就是三件事：更新 qa/maturity-scores.yaml 中最小可辩护的分数变更、通过技能 schema 校验命令、并在证据路径上留下文档/源码/工件引用——这使 Completeness 分数从主观判断变成可复核的仓库内工件链。