When OpenClaw breaks, how to sort the failure into the correct fault line before you waste hours guessing

My view of OpenClaw troubleshooting has changed quite a bit.

At first I treated most failures as though they belonged to the same family:

  • cannot connect, therefore network problem
  • agent only replies in text, therefore model problem
  • dashboard 401 / 1008, therefore token problem
  • browser acts strangely, therefore browser problem

After a few real runs, that model stopped being useful. The time sink with OpenClaw is not merely that bugs exist. It is that different fault classes often present with extremely similar symptoms.

That gets worse when you combine a low-RAM host, a recent update, a browser path, and a channel at the same time. The surface symptoms start impersonating one another.

So this is not a bug encyclopaedia.
What I want to leave behind is the troubleshooting map I trust now.

The one sentence that matters most

When OpenClaw breaks, classify first and repair second.

If you misidentify the fault domain at the start, the rest of your effort tends to become expensive theatre.

The first-round command set I now run almost by default

The FAQ’s “first 60 seconds” sequence is worth copying because the order is sensible. My own first pass is usually:

openclaw status
openclaw status --all
openclaw gateway status
openclaw logs --follow
openclaw doctor

If the Gateway is alive and I need deeper probing:

openclaw status --deep
openclaw health --verbose

If I suspect browser-specific breakage:

openclaw browser status
openclaw browser profiles

If I suspect a channel-specific path:

openclaw channels status --probe

The value is not in the number of commands. It is in the ordering. First establish:

  1. whether the Gateway exists and is reachable
  2. whether the CLI can actually handshake with it
  3. which layer the logs are complaining about
  4. whether doctor is already pointing at schema, service, token, or permission issues

Not every incident deserves a reinstall.

The fault domains I use now

Fault line 1: service / daemon

Start with:

openclaw gateway status

If this is already wrong, do not start speculating about models, channels, or browser.

You need to answer:

  • is the service actually loaded?
  • is the process genuinely running?
  • is the probe target the one you think it is?
  • are the CLI and the service even reading the same config?

This line is especially important on macOS, where LaunchAgent problems are not always “service absent”. Sometimes they are “service alive, but alive in the wrong state”. Recent issue reports show patterns such as:

  • restart paths failing to reload cleanly
  • config-triggered restarts timing out under launchctl
  • gateway stop unloading the service without a clean re-start path
  • LaunchAgent environment or token drift

These are awkward precisely because they produce a misleading situation: the Gateway seems present, but probes, scopes, or later connections behave as though another layer is broken.

Fault line 2: auth / token / device token

If the Gateway exists but you see symptoms like:

  • unauthorized
  • AUTH_TOKEN_MISMATCH
  • AUTH_DEVICE_TOKEN_MISMATCH
  • dashboard 1008 failures
  • “reachable” output with a failing RPC probe

then stop guessing about browser and models.

Check:

openclaw config get gateway.auth.token
openclaw devices list
openclaw gateway status

And use the token drift recovery checklist when appropriate.

One detail worth remembering: the dashboard / Control UI stores the token in the context of the current browser tab and selected gateway URL. It is not some mystical permanent login state. So a surprising amount of “it worked yesterday” behaviour is simply:

  • different URL
  • token not pasted into that tab/session
  • stale device token
  • or the service using different token material from what you assumed

Fault line 3: tool set / profile / session snapshot

This line is very often misdiagnosed as model degradation.

Typical symptoms:

  • the agent only replies with text
  • exec, read, write, or browser come back as missing
  • the config appears to define the tools, but the agent cannot see them

Before reinstalling anything, check at least:

openclaw config get tools.profile
openclaw status

and then ask whether you are still reusing an older session.

That detail mattered in a large wave of issues recently. tools.profile=messaging strips out runtime and filesystem tools at the base-allowlist layer. And in some cases, changing the profile is not enough on its own: you also need a fresh session, because the existing conversation may still be operating with an older tool snapshot.

If you miss that, it is very easy to conclude that OpenClaw’s tool system is broken, when in fact you are just looking at stale session state plus a restrictive profile.

Fault line 4: browser

If the Gateway is healthy and auth is healthy but browser behaviour is not, follow the browser line properly instead of letting it bleed into everything else.

My usual first checks are:

openclaw browser status
openclaw browser profiles
openclaw logs --follow

The main categories I want to exclude are:

1. the browser tooling never loaded

If plugins.allow excludes browser, then browser.enabled=true does not rescue you.

2. the binary or CDP path is wrong

Bad executable path, CDP not listening, wrong profile target, and so on.

3. the browser mode is wrong for the host topology

user / existing-session is a host-local path. If the Gateway is not on the same machine as Chrome, that mode is not supposed to feel natural.

4. orphan or zombie browser processes

There have been issue reports around browser processes surviving Gateway restarts and gradually accumulating memory. On the surface, this can feel like “browser is getting strange over time”. At the lower level it has already crossed into resource pressure.

Fault line 5: low RAM / resource pressure

This is the one I have become most suspicious of in practice.

The frustrating thing about low-memory hosts is not that they always fail immediately. It is that they often make one problem impersonate another.

Examples include:

  • CLI commands suddenly hitting heap OOM
  • browser tabs not being cleaned up
  • openclaw message send crashing on 4GB hosts in certain versions
  • long sessions becoming increasingly erratic
  • behaviour that looks like config drift but is really process stress

This is why I keep using the Oracle VM 1GB case as a useful counterexample. It does not prove “OpenClaw cannot run on small machines”. It does remind me that:

small machines magnify edge-case behaviour and often make the symptoms less honest.

If you are trying to debug OpenClaw on a 1GB or 2GB host, my question is usually not “what else can we guess?” It is:

are we looking at a genuine configuration mistake, or at a host that should never have been the primary debugging surface in the first place?

My own emergency order of operations

When I inherit a problem OpenClaw host, I usually do this.

1. Run the smallest useful diagnostic set

openclaw status
openclaw gateway status
openclaw logs --follow

2. Take a recovery snapshot before larger intervention

openclaw backup create --verify

3. Identify the fault domain

  • service / daemon
  • auth / token
  • tools.profile / session snapshot
  • browser
  • resource pressure

4. Only then perform the targeted fix

For example:

  • token drift -> devices approval / rotation path
  • tools.profile -> adjust profile and start a fresh session
  • browser issues -> inspect profile mode, CDP, or orphaned processes
  • low-RAM symptoms -> move host or reduce workload instead of endlessly re-guessing config

The benefit of this order is simple: you are less likely to turn one fault into three by panicking.

Final view

The troubleshooting rule I trust most in OpenClaw is not a magic command. It is this:

classify first, repair second; preserve first, experiment second.

“Preserve” here includes:

  • taking a backup before major surgery
  • confirming service and token state first
  • cutting the incident into the correct fault line
  • resisting the urge to delete ~/.openclaw immediately

Because the hard part is often not the bug itself. It is the way the symptom tempts you onto the wrong line of investigation.

In this system, fault classification is worth more than speed.