troubleshooting

OpenClaw Troubleshooting

Overview

Diagnose and resolve OpenClaw runtime failures, gateway connectivity issues, channel-specific problems, and post-upgrade breakage. This skill provides a structured diagnostic workflow: run the command ladder first, match symptoms to known fixes, then escalate to channel-specific or post-upgrade guides as needed.

---

Diagnostic Command Ladder

Always start troubleshooting by running these five commands in order. Each successive command provides deeper visibility into the system state.

1. openclaw status

Get a high-level snapshot of the entire OpenClaw system -- daemon state, gateway reachability, active channels, and config validity.

openclaw status

A healthy system reports all components as ok or running. Any component showing error or stopped indicates where to focus next.

2. openclaw gateway status

Inspect the gateway runtime specifically. This is the most common failure point.

openclaw gateway status

Expected healthy output:

Runtime: running
RPC probe: ok

If Runtime shows stopped or RPC probe shows fail, the gateway needs attention. Proceed to openclaw logs for details.

3. openclaw logs --follow

Stream live logs to observe errors as they occur. This is essential for capturing transient failures and startup crashes.

openclaw logs --follow

Watch for connection errors, authentication failures, or stack traces. Press Ctrl+C to stop the stream.

4. openclaw doctor

Run the comprehensive automated health check. This validates Node.js version, port availability, config syntax, API key reachability, daemon registration, and gateway responsiveness.

openclaw doctor

To attempt automatic repair of any detected issues:

openclaw doctor --fix

The --fix flag restarts the daemon, regenerates corrupt config files, re-binds ports, and repairs file permissions where possible.

5. openclaw channels status --probe

Test each configured channel individually. The --probe flag sends a lightweight test message through each channel to verify end-to-end connectivity.

openclaw channels status --probe

Channels reporting probe: fail have a connectivity or authentication problem. Route to channel-specific troubleshooting below.

For detailed output interpretation, expected vs. error states, and log patterns for each command, read ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/diagnostic-commands.md.

---

Quick Fixes for Common Issues

These five problems account for the majority of OpenClaw support requests.

Issue	Fix
openclaw: command not found	Add npm global bin to PATH: export PATH="$(npm prefix -g)/bin:$PATH"
Gateway ECONNREFUSED	openclaw gateway restart or openclaw doctor --fix
Port 18789 in use	sudo lsof -i :18789 to find the culprit, then kill the process or change gateway.port in ~/.openclaw/config.yaml
Docker permission denied	sudo chown -R 1000:1000 ~/.openclaw then restart the container
Config validation error	openclaw configure to re-run the configuration wizard

openclaw: command not found

The binary is not on PATH. This commonly happens after npm global installs or when using Node version managers.

• npm global installs: Find the prefix with npm config get prefix, then add <prefix>/bin to the shell profile.
• nvm/fnm users: NODE_PATH may not propagate correctly across shell sessions. Verify with which openclaw after switching Node versions. Re-run npm install -g openclaw@latest under the active Node version.
• Shell-specific PATH configuration:
  • bash: append to ~/.bashrc
  • zsh: append to ~/.zshrc
  • fish: use fish_add_path (npm prefix -g)/bin

Gateway ECONNREFUSED

The gateway process is not listening on the expected port. Common causes:

• The daemon is not running. Restart with openclaw gateway restart.
• The gateway crashed on startup. Run openclaw gateway start --foreground to see the error output directly.
• Confirm gateway.mode is set to "local" in ~/.openclaw/config.yaml. Remote mode disables the local listener.

Port 18789 Already in Use

Another process holds the default gateway port.

sudo lsof -i :18789

Either stop the conflicting process or edit ~/.openclaw/config.yaml to set a different gateway.port value, then restart with openclaw gateway restart.

Docker Permission Denied

Container file ownership does not match the host user. The OpenClaw container runs as UID 1000 by default.

sudo chown -R 1000:1000 ~/.openclaw

Restart the container after fixing permissions.

Config Validation Error

The config file contains invalid YAML or unrecognized keys. Re-run the configuration wizard to regenerate a valid config:

openclaw configure

This preserves existing API keys and channel definitions while fixing structural issues.

For expanded troubleshooting steps, environment-specific workarounds, and edge cases for each of these issues, read ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/common-issues.md.

---

Channel-Specific Issues

Each messaging channel has unique failure modes. Diagnose the affected channel first with openclaw channels status --probe, then apply the relevant fix below.

Telegram

• Webhook vs. polling: Webhook mode requires a publicly reachable HTTPS endpoint. If behind NAT or a firewall without port forwarding, switch to polling mode in the channel config (mode: polling).
• Webhook SSL errors: Ensure the TLS certificate is valid and not self-signed (unless Telegram's self-signed certificate upload feature is used).

Discord

• Message Content Intent: Discord requires the "Message Content" privileged intent to be enabled in the bot's application settings at discord.com/developers. Without this, the bot receives empty message bodies and cannot respond.
• Bot permissions: Verify the bot has Send Messages, Read Message History, and View Channel permissions in the target server and channel.

Slack

• Socket Mode connection drops: Socket Mode connections are long-lived WebSockets. Drops indicate network instability or Slack-side rate limiting. Check openclaw logs --follow for reconnection attempts. If drops are frequent, verify no proxy or firewall is terminating idle WebSocket connections.
• App-level tokens: Socket Mode requires an app-level token (starts with xapp-), not a bot token. Verify the correct token type is configured.

Signal

• Registration complexity: Signal requires a registered phone number and the signal-cli daemon. Registration involves receiving an SMS or voice verification code. Follow the guided setup with openclaw channels add signal rather than manual configuration.
• Linked device expiry: Signal linked devices expire after 30 days of inactivity. Re-link if the channel stops responding.

WhatsApp

• QR code re-scan needed: WhatsApp Web sessions expire periodically. When the channel shows disconnected, re-scan the QR code by running openclaw channels reconnect whatsapp and scanning with the WhatsApp mobile app.
• Multi-device limitations: Only one WhatsApp Web session is supported per phone number. Disconnect other Web sessions before reconnecting OpenClaw.

"No Replies" From Bot (Any Channel)

When the bot connects but never responds, check these in order:

1. Routing policies: Verify at least one routing rule matches the incoming channel in ~/.openclaw/config.yaml.
2. Pairing status: Run openclaw channels status and confirm the channel shows paired: true.
3. Allowlist: If an allowlist is configured, ensure the sender's ID is included.
4. Mention requirements: Some channel configs require the bot to be @mentioned before responding. Check the require_mention setting.
5. Blocked senders: Check the blocklist in the channel config for accidental entries.

For per-channel setup guides, authentication walkthroughs, and detailed error message explanations, read ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/channel-issues.md.

---

Post-Upgrade Breakage

Upgrading OpenClaw can introduce breaking changes that disrupt a previously working installation. The three most common causes of post-upgrade failures:

1. Auth and URL Override Behavior Changes

Newer versions may change how authentication tokens are validated or how URL overrides resolve. Symptoms include 401 Unauthorized errors or requests routing to unexpected endpoints. Review the release notes for auth-related changes and update ~/.openclaw/config.yaml accordingly.

2. Stricter Bind and Auth Guardrails

Security improvements may enforce stricter bind address validation or reject previously accepted auth configurations. The gateway may refuse to start with errors about invalid bind addresses or insecure auth settings. Check openclaw logs --follow for specific rejection messages and update the config to comply.

3. Pairing and Device Identity State Changes

Channel pairing state or device identity formats may change between versions, causing channels to show as unpaired or unknown. Re-pair affected channels with openclaw channels reconnect <channel-name>.

Recovery Commands

Reinstall service metadata without losing configuration:

openclaw gateway install --force

This regenerates the systemd unit or launchd plist while preserving config.yaml and channel state.

Nix users -- roll back to the previous generation if the upgrade causes irrecoverable issues:

home-manager switch --rollback

Then pin the working OpenClaw version in home.nix before rebuilding.

For version-specific breaking changes, migration guides, and rollback procedures, read ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/post-upgrade.md.

---

Problem Category Routing

Use these guidelines to route problems to the correct reference file:

• Installation failures (command not found, npm errors, build failures) -- read ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/common-issues.md
• Gateway and connectivity (ECONNREFUSED, port conflicts, RPC probe failures, daemon issues) -- read ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/diagnostic-commands.md
• Channel-specific (Telegram, Discord, Slack, Signal, WhatsApp, or "no replies") -- read ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/channel-issues.md
• After updates (auth changes, stricter guardrails, broken pairings) -- read ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/post-upgrade.md

---

Reference Files

Load these resources for expanded detail on each topic:

• ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/diagnostic-commands.md -- Detailed output interpretation for each diagnostic command, expected vs. error states, log pattern matching, and advanced diagnostic flags.
• ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/common-issues.md -- Expanded troubleshooting for common problems including PATH issues across shell environments, NODE_PATH with version managers, permission errors, and config repair.
• ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/channel-issues.md -- Per-channel troubleshooting guides covering Telegram, Discord, Slack, Signal, WhatsApp, and generic "no replies" debugging.
• ${CLAUDE_PLUGIN_ROOT}/skills/troubleshooting/references/post-upgrade.md -- Post-upgrade breakage resolution including version-specific breaking changes, migration steps, service metadata reinstallation, and rollback procedures.