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つ）

1つ目の方法：git pull + 再インストール → 失敗

最初に思いついたのは「もしかして既に修正されているかも？」という期待でした：

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

結果：同じエラーが発生。まだ公式には修正されていない問題でした。

2つ目の方法：pnpm build後にupdate → 失敗

doctorコマンドがmaintenance内に存在することを確認しました：

openclaw maintenance --help

ビルドし直してから再試行：

pnpm build
openclaw update

結果：依然として失敗。ビルドし直しても構造的な問題なので解決しませんでした。

3つ目の方法：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公式ドキュメント