Most OpenClaw problems are pretty ordinary once you narrow them down. Usually the Gateway is down, config validation failed, a channel transport broke, or your remote client is pointed at the wrong place.

That is the nice part. You usually do not need a long debugging session. You need a short command sequence and a little restraint before you start changing settings at random.

If you still need the base install path, start with How to Install OpenClaw on Ubuntu and Complete Your First Setup. If the install worked and you are now tuning behavior, my OpenClaw configuration guide for beginners is the better companion piece.

Start with the command ladder every time

This is the quickest way to stop guessing.

Run these in order:

openclaw status

openclaw gateway status

openclaw logs --follow

openclaw doctor

openclaw channels status --probe

When OpenClaw is healthy, you are looking for a few boring signals:

• openclaw gateway status shows Runtime: running
• the connectivity probe is ok
• openclaw doctor reports no blocking config or service issues
• openclaw channels status --probe shows live channel transport status and probe results where supported

If you start there every time, you can usually tell what kind of problem you have within a minute or two.

Problem 1: OpenClaw will not start after a config edit

This is one of the most common self-inflicted problems, especially after hand-editing ~/.openclaw/openclaw.json.

OpenClaw reads an optional JSON5 config from:

~/.openclaw/openclaw.json

The Gateway validates that file strictly. Unknown keys, invalid values, and wrong types can make the Gateway refuse to start.

When that happens, stick to diagnostic commands first:

openclaw doctor

openclaw logs --follow

openclaw status

If you want OpenClaw to repair common prefixed or clobbered config problems and restore the last known good copy when possible, run:

openclaw doctor --fix

Good recovery moves here:

• remove the setting you just added if the failure started immediately after that edit
• use openclaw config get <path> and openclaw config set <path> <value> instead of hand-editing large chunks when you only need one change
• rerun openclaw configure if you want a guided pass through the important settings

openclaw configure

Problem 2: An update finished, but the Gateway or channels are now broken

When OpenClaw gets weird right after an update, use the deeper update runbook instead of crossing your fingers and restarting it a few times.

Start here:

openclaw status --all

openclaw update status --json

openclaw gateway status --deep

openclaw doctor --fix

openclaw gateway restart

A few things are worth watching for after updates:

• pending or failed update restarts
• plugin load failures caused by a corrupted dependency tree
• channels that still exist in config but failed to load cleanly
• provider authentication problems that suddenly show up as 401 errors

If openclaw status --all mentions a plugin dependency problem, openclaw doctor --fix is the right next move, not random package surgery.

Problem 3: The Control UI works locally, but remote access is a mess

The safest normal OpenClaw pattern is still to keep the Gateway on loopback unless you have a deliberate reason to bind it elsewhere.

For a VPS or remote box, the clean fallback is an SSH tunnel:

ssh -N -L 18789:127.0.0.1:18789 user@host

Then open the local forwarded address in your browser or point your CLI at it.

If you rely on CLI remote mode, a basic remote config looks like this:

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}

Two easy mistakes show up a lot here:

Passing --url without credentials

If you override the Gateway URL explicitly, the CLI does not quietly borrow auth from your normal config.

That means this kind of check needs explicit auth when required:

openclaw gateway status --url ws://127.0.0.1:18789 --token your-token

Exposing the Gateway too early

If you bind OpenClaw to a non-loopback interface, you need real Gateway auth in front of it. Token, password, or a properly trusted proxy are the sane options.

For beginner-friendly remote access, I would still choose one of these first:

• loopback plus SSH tunnel
• loopback plus Tailscale Serve
• a trusted LAN or tailnet bind only when you intentionally want direct access

Problem 4: Telegram or another channel is connected, but replies are wrong or missing

This is another case where the command ladder helps.

openclaw channels status --probe

openclaw logs --follow

openclaw pairing list telegram

For Telegram, the usual trouble spots are:

• DM pairing was never approved
• dmPolicy is stricter than you meant it to be
• the bot is present in a group, but mention gating or privacy mode is blocking normal replies
• the token is wrong, stale, or copied badly
• DNS, IPv6, or proxy issues are interfering with Telegram API calls

A safe baseline DM config looks like this:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      allowFrom: ["tg:123"],
    },
  },
}

And for group chats, mention gating is usually the first thing to inspect:

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

If the bot works in direct messages but stays quiet in a group, do not assume the whole install is broken. It is often just mention gating, privacy mode, or group policy doing exactly what you asked it to do.

Problem 5: OpenClaw looks alive, but model calls still fail

If the Gateway is running and the channel transport is fine, the next suspect is usually provider configuration.

Start with:

openclaw logs --follow

openclaw models status

openclaw config get agents.defaults.models

Common failure patterns:

• a provider API key is missing or invalid
• the selected model is not actually available to that provider account
• a local OpenAI-compatible backend answers tiny manual probes but fails under real agent-sized prompts
• an upstream CDN or WAF is blocking normal SDK-shaped requests with generic 403 responses

If failures started right after you swapped providers or edited model defaults, check those settings before you start tearing apart the rest of the stack.

The same basic rule applies here too: a lot of "the bot is dumb" or "the bot is broken" complaints turn out to be model selection or auth problems.

Problem 6: You updated OpenClaw, but the wrong binary is on your PATH

This one is sneaky.

If one openclaw binary is older than the version that last wrote your config, OpenClaw can block destructive service actions rather than pretending everything is fine.

Check:

which openclaw

openclaw --version

openclaw gateway status --deep

openclaw config get meta.lastTouchedVersion

If those values do not line up, fix your PATH and make sure you are using the intended install. If needed, reinstall the service from the newer binary:

openclaw gateway install --force

openclaw gateway restart

That is a much better fix than treating every update problem like random corruption.

When doctor --fix is the right hammer

openclaw doctor --fix is useful, but it is not a substitute for reading what broke.

Use it when:

• config validation failed
• an update left stale auth shadows or plugin dependency staging behind
• the Gateway is clearly unhealthy and the doctor output points at fixable local state

Use a lighter touch when:

• the problem is obviously a bad token you still need to replace
• a remote URL or SSH tunnel is pointed at the wrong host or port
• a group policy is silencing the bot on purpose

The goal is not to avoid doctor --fix. The goal is to stop using it like a panic button for every symptom.

A calm troubleshooting order that works well

If you want a simple mental model, use this order:

1. check runtime status
2. check Gateway status
3. watch live logs
4. run doctor
5. probe channels
6. only then change config or restart things

That sequence catches a lot of problems before they turn into a longer outage.

Where to go next

Once OpenClaw is stable again, these are the next articles I would pair with this one:

• How to Install OpenClaw on Ubuntu and Complete Your First Setup
• OpenClaw Configuration Guide for Beginners: The Settings That Matter First
• A Curated List of OpenClaw Skills Worth Exploring
• How to Add last30days-skill to OpenClaw for Better Real-Time Research

Once those spokes are in place, the next useful follow-up is probably remote exposure and reverse proxying. That is usually where all the "it works on localhost" confidence gets tested.