Fixing OpenClaw Dev Update Error: unknown command 'doctor'

Introduction

If you’re running OpenClaw from source (dev version), you might occasionally run into unexpected errors. The one I hit recently was particularly frustrating — a failure during openclaw update that took some digging to resolve. Here’s how I figured it out.

The Problem

When running openclaw update, the process proceeds normally until the very last step — “Running doctor checks” — where it fails with:

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

The update is essentially complete at this point, making the failure all the more annoying.

Root Cause

After investigating, I found that the doctor command exists inside the maintenance subcommand, but it’s not registered as a top-level command because register.subclis.ts doesn’t reference it.

In other words, openclaw maintenance doctor works fine, but openclaw doctor doesn’t. The update script, however, calls openclaw doctor directly.

The Fix (3 Attempts)

Attempt 1: git pull + reinstall → Failed

The first thing I tried was hoping it had already been fixed upstream:

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

Result: Same error. The fix hadn’t been merged yet.

Attempt 2: pnpm build then update → Failed

I confirmed that the doctor command exists under maintenance:

openclaw maintenance --help

Rebuilt and tried again:

pnpm build
openclaw update

Result: Still failed. Rebuilding doesn’t fix a structural registration issue.

Attempt 3: Modify register.subclis.ts → Success 🎉

Time to fix it myself. First, I checked if maintenance is referenced in register.subclis.ts:

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

Nothing. That’s the problem.

Checked the export name in register.maintenance.ts:

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

Added the following to the end of the entries array in register.subclis.ts:

{
  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);
  },
}

Built and verified doctor works:

pnpm build
openclaw doctor --help

The doctor command is now recognized! Made a clean git state and ran update:

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

Update successful at last!

After the update completes, revert the temporary commit:

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

Important Note

Reverting means the same issue may recur on the next update. Until an official fix is released, you’ll need to remember this workaround and repeat the process each time.

That’s exactly why I’m documenting this — hopefully it saves someone else the same headache.

Wrapping Up

Running a dev version means dealing with these kinds of issues from time to time. The key takeaway is to read error messages carefully and trace through the source code to find the root cause. This particular case was a straightforward command registration issue once you understood the structure.

References

• OpenClaw Official Docs