Debugging Your OpenClaw Gateway Like a Pro

Run the OpenClaw Command ladder for quick diagnostics

When you need to fix issues with the OpenClaw Gateway, you can use the Command ladder to quickly find the root cause. These steps help you verify that your services are running and that the CLI is communicating with the backend.

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

You should look for these healthy signals to confirm everything is working:

The command openclaw gateway status should show Runtime: running, Connectivity probe: ok, and a Capability: ... line.
The openclaw doctor command should report that there are no blocking configuration or service issues.
Running openclaw channels status --probe should display the live transport status for each account and show results like works or audit ok.

If you need a faster triage flow before diving deep, you can start at /help/troubleshooting.

Fix Anthropic 429 errors for long context in OpenClaw

You might see an HTTP 429 error when your requests exceed the standard context window and require the 1M beta path. This usually happens during long sessions or when you use specific high-capacity models that have strict usage limits.

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

When you check your setup, look for these specific indicators:

The selected Anthropic Opus or Sonnet model has the parameter params.context1m: true enabled.
Your current Anthropic credential is not eligible for long-context usage.
Requests only fail during long sessions or model runs that specifically need the 1M beta path.

You have a few options to fix this:

Disable context1m for that specific model so it falls back to the normal context window.
Use an Anthropic credential that is eligible for long-context requests or switch to a direct Anthropic API key.
Configure fallback models so your runs can continue even if the Anthropic long-context requests are rejected.

You can find more details in these resources:

Troubleshoot local OpenAI-compatible backend failures in OpenClaw

Sometimes your local backend passes a simple curl test but fails when the OpenClaw agent starts a real conversation. This often points to a mismatch in how the model handles structured JSON content or how the server reacts to larger prompt sizes.

curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow

You should investigate the following symptoms:

Direct tiny calls succeed, but OpenClaw runs fail when the prompts get larger.
The backend returns errors stating that messages[].content expects a string instead of an object.
The backend crashes only when it encounters larger prompt-token counts or full agent runtime prompts.

Check for these common signatures in your logs:

If you see messages[...].content: invalid type: sequence, expected a string, your backend is rejecting structured content. You can fix this by setting models.providers.<provider>.models[].compat.requiresStringContent: true.
If tiny requests work but the agent fails with backend crashes, the OpenClaw transport is likely fine, but the backend cannot handle the agent-runtime prompt shape.
If failures decrease after you disable tools but don’t go away, the tool schemas were adding pressure, but the core issue is still the model capacity or a backend bug.

To resolve these issues, you can try these steps:

Set compat.requiresStringContent: true for backends that only support string-based Chat Completions.
Set compat.supportsTools: false for models or backends that cannot handle the tool schema surface of OpenClaw.
Lower the prompt pressure by using a smaller workspace bootstrap, shortening your session history, or switching to a lighter local model.
If tiny requests pass but agent turns still crash the backend, you should treat it as a limitation of the upstream server and file a report with the payload shape.

Resolve missing replies in OpenClaw channels

If your channels are up but you aren’t getting any answers, you should check your routing and policy settings before you try to reconnect anything. It is common for messages to be filtered out by specific rules or pairing requirements that you have configured.

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

You should look for these specific issues in your configuration:

Pairing is still pending for users sending direct messages.
Group mention gating is active through requireMention or mentionPatterns.
There are mismatches in your channel or group allowlist.

These common signatures will help you identify the problem:

drop guild message (mention required) means the group message was ignored because you didn’t mention the bot.
pairing request indicates that the sender still needs your approval to communicate.
blocked or allowlist messages show that the sender or the channel was filtered out by your security policy.

Check these links for more help:

Fix OpenClaw Dashboard and Control UI Connectivity

Getting your OpenClaw dashboard to talk to the Gateway can sometimes be tricky if the URLs or auth tokens don’t match up. You should start by running these CLI commands to see exactly what the system thinks is happening.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

You need to look for a few specific things in the output. First, check if the probe URL and dashboard URL are correct. Then, see if there is an auth mode or token mismatch between your client and the Gateway. Finally, verify if you are using HTTP in a situation where device identity is required.

Here are some common signatures to watch for:

device identity required means you are in a non-secure context or missing device auth.
origin not allowed happens when the browser Origin is not in gateway.controlUi.allowedOrigins (or you are connecting from a non-loopback browser origin without an explicit allowlist).
device nonce required or device nonce mismatch indicates the client isn’t completing the challenge-based device auth flow (connect.challenge + device.nonce).
device signature invalid or device signature expired means the client signed the wrong payload or used a stale timestamp for the current handshake.
AUTH_TOKEN_MISMATCH with canRetryWithDeviceToken=true allows the client to do one trusted retry with a cached device token.
That cached-token retry reuses the cached scope set stored with the paired device token. Explicit deviceToken or explicit scopes callers keep their requested scope set instead.
Outside that retry path, connection auth precedence is explicit shared token/password first, then explicit deviceToken, then stored device token, and finally the bootstrap token.
On the async Tailscale Serve Control UI path, failed attempts for the same {scope, ip} are serialized before the limiter records the failure. Two bad concurrent retries from the same client can therefore surface retry later on the second attempt instead of two plain mismatches.
too many failed authentication attempts (retry later) from a browser-origin loopback client means repeated failures from that same normalized Origin are locked out temporarily; another localhost origin uses a separate bucket.
Repeated unauthorized after that retry suggests shared token/device token drift; you should refresh your token config and re-approve or rotate the device token if needed.
gateway connect failed: usually points to the wrong host, port, or URL target.

Auth detail codes quick map

Use error.details.code from the failed connect response to pick the next action:

Detail code	Meaning	Recommended action

Fix Gateway restored last-known-good config

You might find that your Gateway starts up successfully, but the logs indicate it had to restore a previous version of your openclaw.json file. This usually happens when a recent configuration change fails validation, prompting OpenClaw to revert to a stable, working state to prevent a crash.

openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

When you check your logs or system status, you should look for these specific indicators:

The message Config auto-restored from last-known-good or gateway: invalid config was restored from last-known-good backup.
A log entry stating config reload restored last-known-good config after invalid-config.
A file named openclaw.json.clobbered.* with a timestamp located in the same directory as your active config.
A system event from the main-agent that begins with the text Config recovery warning.

This situation occurs because the configuration you provided did not pass the validation checks during the startup process or a hot reload. To protect your setup, OpenClaw saves the rejected data as a .clobbered.* file and restores the active configuration from the last validated copy. The system then warns the main-agent not to overwrite the rejected configuration automatically.

To inspect and repair the issue, you can use these commands:

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

You can identify what went wrong by looking at these common signatures:

If a .clobbered.* file exists, it means an external direct edit or a startup read was invalid and had to be restored.
If a .rejected.* file exists, an OpenClaw-owned configuration write failed the schema or safety checks before it could be committed.
The error Config write rejected: suggests the update tried to remove a required JSON structure, significantly shrink the file size, or save an invalid configuration.
The message Config last-known-good promotion skipped indicates the candidate configuration contained redacted secret placeholders like ***, which cannot be promoted to a stable version.

To fix this, you have a few options:

You can keep the restored active configuration if it is already correct for your needs.
You can manually copy the specific keys you intended to change from the .clobbered.* or .rejected.* files and apply them using CLI commands like openclaw config set or config.patch.
Always run openclaw config validate to verify your changes before you restart the service.
If you choose to edit the file by hand, ensure you maintain the full JSON structure rather than just saving a partial object.

Resolve Gateway probe warnings

Sometimes the openclaw gateway probe command successfully reaches its target but still displays a warning block in your terminal. These warnings are designed to help you troubleshoot issues with connectivity, permissions, or configuration conflicts that might limit your access.

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

When reviewing the output, pay attention to these details:

Check the warnings[].code and primaryTargetId fields in the JSON output for specific error codes.
Determine if the warning relates to an SSH fallback, the detection of multiple gateways, missing permission scopes, or unresolved authentication references.

You will typically encounter these common signatures:

SSH tunnel failed to start; falling back to direct probes. indicates that the SSH configuration failed, so the CLI attempted to reach the configured or loopback targets directly.
multiple reachable gateways detected means more than one Gateway responded to the probe, which often happens in multi-gateway setups or if there are duplicate listeners.
Read-probe diagnostics are limited by gateway scopes (missing operator.read) shows that the connection worked, but you cannot see detailed diagnostics because your identity lacks the operator.read scope.
Capability: pairing-pending or gateway closed (1008): pairing required means the Gateway is active, but your client needs to complete the pairing or approval process before you can gain operator access.
Warnings about unresolved gateway.auth.* or gateway.remote.* SecretRef text mean that the necessary authentication materials were not found in the path used by the command.

Fix OpenClaw channel message flow issues

If your OpenClaw channel shows as connected but you aren’t seeing any messages, you need to check your policies and permissions. It is frustrating when the status looks green but the data isn’t moving, so you should look closely at the delivery rules.

You should first run these CLI commands to get a deep look at what is happening under the hood of your setup.

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

You need to look for specific configurations like the DM policy, which could be set to pairing, allowlist, open, or disabled.
Check if there are group allowlist restrictions or if mentions are required for the messages to flow correctly.
Verify if there are any missing channel API permissions or scopes that are preventing the delivery of your messages.

You might see these common signatures in your logs:

mention required means the message was ignored because of the group mention policy.
pairing or pending approval traces suggest the sender has not been approved yet.
missing_scope, not_in_channel, Forbidden, or 401/403 errors point to a channel auth or permissions issue.

Troubleshoot OpenClaw cron and heartbeat delivery

If your OpenClaw cron jobs or heartbeats did not run or deliver, you should verify the scheduler state first and then check the delivery target. This helps you figure out if the issue is with the trigger itself or the final destination.

Use the following CLI commands to check the status of your cron jobs and the latest heartbeat runs.

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

You should confirm that the cron is enabled and that a “next wake” time is present in the system.
Review the job run history to see if the status is recorded as ok, skipped, or error.
Check for heartbeat skip reasons like quiet-hours, requests-in-flight, alerts-disabled, empty-heartbeat-file, or no-tasks-due.

Keep an eye out for these common signatures in your output:

cron: scheduler disabled; jobs will not run automatically means the cron functionality is turned off.
cron: timer tick failed indicates a scheduler tick failure, so you should check for file, log, or runtime errors.
heartbeat skipped with reason=quiet-hours means you are currently outside the active hours window you configured.
heartbeat skipped with reason=empty-heartbeat-file happens when your HEARTBEAT.md exists but only has blank lines or headers, causing OpenClaw to skip the model call.
heartbeat skipped with reason=no-tasks-due means your HEARTBEAT.md has a tasks: block, but no tasks are ready for this specific tick.
heartbeat: unknown accountId indicates an invalid account id for the heartbeat delivery target.
heartbeat skipped with reason=dm-blocked occurs when the heartbeat target is a DM-style destination but your agents.defaults.heartbeat.directPolicy is set to block.

Fix Node paired tool failures

If your OpenClaw node is paired but the tools are failing, you need to isolate the foreground state and permissions. This usually happens when the app loses focus or the OS blocks a specific capability.

Run openclaw nodes status to see if the node is actually online.
Use openclaw nodes describe —node <idOrNameOrIp> to check its capabilities.
Check openclaw approvals get —node <idOrNameOrIp> for any pending requests.
Monitor the logs with openclaw logs —follow.
Verify the overall system with openclaw status.

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

You should look for these specific indicators:

Node online with expected capabilities.
OS permission grants for camera/mic/location/screen.
Exec approvals and allowlist state.
Active network connectivity for the node.

Common signatures:

NODE_BACKGROUND_UNAVAILABLE → node app must be in foreground.
*_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → missing OS permission.
SYSTEM_RUN_DENIED: approval required → exec approval pending.
SYSTEM_RUN_DENIED: allowlist miss → command blocked by allowlist.

Troubleshoot Browser tool failures

You might find that browser tool actions fail even when the Gateway itself is running perfectly. Checking your browser profiles and the CLI logs will help you spot if a plugin is missing or a path is wrong.

Check the current browser state with openclaw browser status.
Try starting a specific profile using openclaw browser start —browser-profile openclaw.
List all available profiles with openclaw browser profiles.
Watch the real-time output via openclaw logs —follow.
Run openclaw doctor for a full diagnostic check.

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

Look for these details:

Whether plugins.allow is set and includes browser.
Valid browser executable path.
CDP profile reachability.
Local Chrome availability for existing-session / user profiles.

Common signatures:

unknown command "browser" or unknown command 'browser' → the bundled browser plugin is excluded by plugins.allow.
browser tool missing / unavailable while browser.enabled=true → plugins.allow excludes browser, so the plugin never loaded.
Failed to start Chrome CDP on port → browser process failed to launch.
browser.executablePath not found → configured path is invalid.
browser.cdpUrl must be http(s) or ws(s) → the configured CDP URL uses an unsupported scheme such as file: or ftp:.
browser.cdpUrl has invalid port → the configured CDP URL has a bad or out-of-range port.
No Chrome tabs found for profile="user" → the Chrome MCP attach profile has no open local Chrome tabs.
Remote CDP for profile "<name>" is not reachable → the configured remote CDP endpoint is not reachable from the gateway host.
Browser attachOnly is enabled ... not reachable or Browser attachOnly is enabled and CDP websocket ... is not reachable → attach-only profile has no reachable target, or the HTTP endpoint answered but the CDP WebSocket still could not be opened.
Playwright is not available in this gateway build; '<feature>' is unsupported. → the current gateway install lacks the full Playwright package; ARIA snapshots and basic page screenshots can still work, but navigation, AI snapshots, CSS-selector element screenshots, and PDF export stay unavailable.
fullPage is not supported for element screenshots → screenshot request mixed --full-page with --ref or --element.
element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome MCP / existing-session screenshot calls must use page capture or a snapshot --ref, not CSS --element.
existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome MCP upload hooks need snapshot refs, not CSS selectors.
existing-session file uploads currently support one file at a time. → send one upload per call on Chrome MCP profiles.
existing-session dialog handling does not support timeoutMs. → dialog hooks on Chrome MCP profiles do not support timeout overrides.
response body is not supported for existing-session profiles yet. → responsebody still requires a managed browser or raw CDP profile.
stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run openclaw browser stop —browser-profile <name> to close the active control session and release Playwright/CDP emulation state without restarting the whole gateway.

Resolve issues after an OpenClaw upgrade

Most issues after an OpenClaw upgrade happen because of configuration drift or new, stricter security defaults. You can usually fix this by checking your auth settings or re-syncing your device identity.

1) Auth and URL override behavior changed

If you find that your commands are failing after an update, the CLI might be looking at the wrong target. You should verify if your local service is being bypassed by a remote configuration.

Check the Gateway status with openclaw gateway status.
Verify the mode using openclaw config get gateway.mode.
Confirm the remote URL with openclaw config get gateway.remote.url.
Check the auth mode via openclaw config get gateway.auth.mode.

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

What to check:

If gateway.mode=remote, CLI calls may be targeting remote while your local service is fine.
Explicit `—url** calls do not fall back to stored credentials.

Common signatures:

gateway connect failed: → wrong URL target.
unauthorized → endpoint reachable but wrong auth.

2) Bind and auth guardrails are stricter

Security is tighter in recent versions, so non-loopback binds now require explicit authentication. You need to make sure your tokens and proxy settings are correctly aligned with the new requirements.

Check the bind address with openclaw config get gateway.bind.
Verify the auth mode using openclaw config get gateway.auth.mode.
Check the auth token via openclaw config get gateway.auth.token.
Check the Gateway status with openclaw gateway status.
Watch the logs with openclaw logs —follow.

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

What to check:

Non-loopback binds (lan, tailnet, custom) need a valid gateway auth path: shared token/password auth, or a correctly configured non-loopback trusted-proxy deployment.
Old keys like gateway.token do not replace gateway.auth.token.

Common signatures:

refusing to bind gateway ... without auth → non-loopback bind without a valid gateway auth path.
Connectivity probe: failed while runtime is running → gateway alive but inaccessible with current auth/url.

3) Pairing and device identity state changed

Identity management might require fresh approvals if you have changed your policies or updated your device. You should check the pending lists to see if your device is waiting for permission to connect.

List your devices with openclaw devices list.
Check pairing channels using openclaw pairing list —channel <channel> [—account <id>].
Monitor the logs with openclaw logs —follow.
Run openclaw doctor to find identity mismatches.

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

What to check:

Pending device approvals for dashboard/nodes.
Pending DM pairing approvals after policy or identity changes.

Common signatures:

device identity required → device auth not satisfied.
pairing required → sender/device must be approved.

If the service config and runtime still disagree after checks, reinstall service metadata from the same profile/state directory:

openclaw gateway install --force
openclaw gateway restart

openclaw --version
openclaw doctor
openclaw gateway status

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # also scan system-level services

OpenClaw Expert

Still stuck?

If this page didn't answer your case, ask OpenClaw Expert for step-by-step guidance.