OpenClaw dev版更新错误解决：unknown command doctor的处理方法

前言

在使用OpenClaw dev版（从源码直接构建）的过程中，偶尔会遇到意想不到的错误。这次我碰到的是执行openclaw update时出现的一个相当棘手的错误。经过一番折腾，终于解决了，在此分享整个过程。

问题状况

执行openclaw update后，更新进程会正常运行，但在最后一步”Running doctor checks”处失败，出现以下错误：

error: unknown command 'doctor' (Did you mean docs?)

更新本身几乎已经完成了，却在最后的健康检查阶段挂掉，让人格外郁闷。

原因

深入调查后发现，doctor命令虽然存在于maintenance子命令中，但由于register.subclis.ts没有引用它，导致没有注册为顶级命令。

也就是说，openclaw maintenance doctor可以执行，但openclaw doctor无法执行。而更新脚本恰恰调用的是openclaw doctor。

解决过程（尝试了3种方法）

第一种方法：git pull + 重新安装 → 失败

首先想到的是”说不定已经修复了呢？”：

cd /path/to/openclaw
git pull
rm -rf node_modules
pnpm install
openclaw update

结果：同样的错误。这个问题还没有被官方修复。

第二种方法：pnpm build后update → 失败

确认了doctor命令存在于maintenance中：

openclaw maintenance --help

重新构建后再试：

pnpm build
openclaw update

结果：依然失败。重新构建也无法解决结构性问题。

第三种方法：修改register.subclis.ts → 成功 🎉

决定直接修改源码。首先确认maintenance是否在register.subclis.ts中被引用：

grep -n "maintenance" src/cli/program/register.subclis.ts

没有任何输出。这就是问题所在。

确认register.maintenance.ts的export名称：

grep "export" src/cli/program/register.maintenance.ts
# export function registerMaintenanceCommands(program: Command) {

在register.subclis.ts的entries数组末尾添加以下内容：

{
  name: "doctor",
  description: "Health checks + quick fixes for the gateway and channels",
  register: async (program) => {
    const mod = await import("./register.maintenance.js");
    mod.registerMaintenanceCommands(program);
  },
}

构建后确认doctor正常工作：

pnpm build
openclaw doctor --help

现在doctor命令可以识别了！让Git状态保持干净并执行update：

git add . && git commit -m "add doctor command"
openclaw update

终于更新成功！

更新完成后，撤销临时提交：

git reset HEAD~1 && git checkout -- .

注意事项

撤销后，下次更新时可能会再次遇到同样的问题。在官方修复之前，需要记住这个方法，每次更新时可能都要重复相同的步骤。

这也是我把这篇文章记录下来的原因。希望对遇到同样问题的朋友有所帮助。

总结

使用dev版就难免会遇到这类问题。关键是要养成仔细阅读错误信息、追踪源代码寻找原因的习惯。这次的问题，理解了命令注册结构后就能比较轻松地解决。

参考资料

• OpenClaw官方文档