OpenClaw Troubleshooting: Proven 5-Command Fix for Channel Errors

Table of Contents

• TLDR
• Introduction
• The Diagnostic Ladder (Run These First, Every Time)
• Gateway Crashes and Startup Failures
• Pairing Failures: The Most Silent Failure
• Allowlist and DM Policy Issues
• Group and Channel Access Issues
• Memory and Context Problems
• Node Connection Problems
• Quick Reference: Error to Fix
• FAQ
• Sources
• Conclusion

TLDR

Run these five commands in order before you do anything else:

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

Healthy output shows Runtime: running, your channel connected, and no pending pairing codes you forgot about. Four causes explain nearly all OpenClaw channel failures: gateway not started, pairing code not approved, channel not in the allowlist, or the group policy blocking messages. This guide covers all four.

Introduction

OpenClaw supports over 20 messaging platforms, and the symptoms of failure look different on each one. Telegram silently ignores DMs. Discord shows the bot online but never replies in servers. Slack responds to some people but not others. Each one feels like a different problem.

It's rarely a channel-specific bug. That's the pattern worth knowing.

Under the hood, every OpenClaw channel runs on the same access control system: DM pairing, allowlists, group policies, and the gateway runtime. The channels overview lists all 20+ platforms, and every single one passes through those same four gates. Fix the gates, fix the channel.

This guide is the catch-all diagnostic layer. It's where every channel-specific troubleshooting guide points when the channel-specific fixes don't work. For building AI-powered workflows once things are running, OpenClaw Second Brain: 7 Proven Steps for Faster Recall on EmergentWeirdness shows what OpenClaw looks like when it's working correctly.

The Diagnostic Ladder (Run These First, Every Time)

Run these commands in this order. Don't skip ahead. Each one narrows the problem space before the next.

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

openclaw status gives you the gateway runtime state. If this shows anything other than Runtime: running, the gateway itself is the problem. Stop here and see the gateway crash section below.

openclaw gateway status gives you more detail: uptime, memory, active connections. Useful for confirming the gateway has been running long enough to process your test message.

openclaw logs --follow opens the live log stream. Send a test message in your channel while this is running. You'll see exactly what happened: whether the message arrived, why it was dropped, or what error occurred. This one command resolves more issues than anything else on this list. Key log patterns to look for:

• drop dm (pairing required) - sender not yet paired
• drop dm (not in allowlist) - sender not in allowFrom
• drop group (not in allowlist) - group/guild not configured
• drop group message (missing-mention) - mention gating blocked it
• channel connect error - authentication or network issue

openclaw doctor runs the built-in config validator. It checks for common misconfigurations like usernames where numeric IDs are required, missing required fields, and deprecated config patterns. Run openclaw doctor --fix to automatically resolve the issues it finds.

openclaw channels status --probe makes a live API call to each configured channel. It tells you whether the connection is healthy right now, not just whether the config exists. This catches authentication failures, expired tokens, and network issues that status alone won't show.

What healthy baseline looks like:

Runtime: running
RPC probe: ok
Channel: telegram [connected]
Channel: discord [connected]

If any channel shows [error] or [disconnected], that's your starting point. If the channel shows [connected] and messages still aren't working, keep reading. Connection and response are two different things.

Gateway Crashes and Startup Failures

If openclaw status shows the gateway is not running, nothing else matters. The gateway must be running for any channel to function.

Port conflict: The gateway defaults to port 18789. If something else is using that port:

ss -tlnp | grep 18789

Running that shows what process owns the port. Then:

openclaw config set gateway.port 18790
openclaw gateway restart

Missing or corrupted config: If openclaw doctor reports config errors:

openclaw doctor --fix

That auto-fixes what it can. For errors it can't fix, the output tells you exactly which field needs attention.

Permission errors: OpenClaw stores session data in ~/.openclaw/. Check that the process user has read/write access to that directory.

OOM kills on low-resource VPS: If you are running OpenClaw on a small VPS alongside other services, the gateway may be killed by the OOM killer. Check with dmesg | grep -i oom. If this is happening, reduce historyLimit in your channel configs or upgrade your server.

For installation-level issues that prevent the gateway from starting at all, see the fix OpenClaw installation errors guide. For VPS-level configuration including firewall rules and process management, the DigitalOcean VPS setup guide covers persistent gateway setup with systemd.

After fixing any startup issue, always restart cleanly:

openclaw gateway stop
openclaw gateway start
openclaw channels status --probe

Pairing Failures: The Most Silent Failure

This is the one that burns people. Everything looks healthy. Gateway running, channel connected, no errors anywhere. But a new user messages your bot and gets absolute silence.

Here's what actually happened: the default DM policy is pairing. OpenClaw saw that new sender, generated a one-time approval code, and is sitting there waiting for you to authorize it. Until you do, the sender gets nothing. Not even an error.

The pairing code is printed in the gateway logs. If you were not watching logs when someone first messaged, you missed it. Pairing codes expire after one hour.

Check for pending pairing codes:

openclaw pairing list telegram
openclaw pairing list discord
openclaw pairing list slack

Use whichever channel you are debugging.

Approve a pending code:

openclaw pairing approve telegram <CODE>

If the code has expired: Have the sender message the bot again. A new code generates automatically.

To skip pairing for users you trust, add them to allowFrom:

{
  "channels": {
    "telegram": {
      "allowFrom": ["123456789"]
    }
  }
}

To disable pairing entirely and allow all DMs (use with caution):

{
  "channels": {
    "telegram": {
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  }
}

The pairing system exists because your agent can access your files, tools, and potentially sensitive data. Your agent handles all routing internally, so whoever gets past the pairing gate can trigger anything your agent is allowed to do (OpenClaw gateway security docs). Before relaxing the DM policy, read the OpenClaw security guide on access control.

Allowlist and DM Policy Issues

OpenClaw's access control has two separate layers, and confusing them is behind most "works for me but not for anyone else" reports. Here's the full picture.

DM policies:

Group policies:

The allowlist trap: You set up the bot and added your user ID to allowFrom. It works for you. Someone else tries to message the bot and gets nothing. Their ID is not in allowFrom. Add them, use pairing mode so they can request access, or switch to open.

The Telegram username trap: If you added @yourusername to allowFrom and then upgraded OpenClaw, run openclaw doctor --fix to migrate those to numeric IDs automatically. If you're still seeing allowlist blocks after that, run openclaw logs --follow while sending a message to see exactly what sender ID is being checked.

Checking current DM config:

openclaw config get channels.telegram.dmPolicy
openclaw config get channels.telegram.allowFrom

Group and Channel Access Issues

Group messages failing is a completely separate problem from DM failures. This trips up nearly everyone on first setup. Two gates must open for a group message to get a response, and they're configured in different places.

Layer 1: Group allowlist. The channel itself must be in your config's group allowlist. For Discord, that means the guild ID. For Slack, the channel name or ID. For Telegram, the group ID. Until the group is explicitly listed, all messages from it are dropped.

Find the group ID in logs while a message is sent:

openclaw logs --follow

Then add it to config. Discord example:

openclaw config set channels.discord.guilds.YOUR_GUILD_ID.allow true

Layer 2: Mention gating. Even when a group is allowlisted, the default behavior is to only respond when the bot is @mentioned. This prevents the bot from responding to every message in a busy group.

If you see log entries like drop group message (missing-mention), the group is allowed but mention gating is blocking the response.

Disable mention requirement for a specific group:

{
  "channels": {
    "discord": {
      "guilds": {
        "YOUR_GUILD_ID": {
          "requireMention": false
        }
      }
    }
  }
}

Channel-specific group setup for Discord is covered in the OpenClaw Discord setup guide. For Slack, see the OpenClaw Slack setup guide.

Memory and Context Problems

If the bot responds but gives answers that ignore what you just told it, or seems to have forgotten the last ten minutes of conversation, the channel is fine. This is a context and memory issue.

Session isolation: Each channel, group, and DM thread gets its own isolated context. Messages sent in a Telegram group do not affect the context in a Discord DM. The agent will maintain separate histories per session, so tell your agent which channel it's supposed to be responding to if you're testing across multiple at once. This isolation is by design.

History limit: By default, OpenClaw keeps a limited number of messages in context per session. If conversations get very long, earlier messages get dropped.

Check the current limit:

openclaw config get channels.telegram.historyLimit

Increase it (source) to keep more context per session:

{
  "channels": {
    "telegram": {
      "historyLimit": 50
    }
  }
}

To reset context for a session: Use the /clear command in the channel if enabled, or restart the gateway. Restarting clears all in-memory context.

Context overflow errors appear in logs as API errors with "context too long" or similar messages. Reduce historyLimit or enable context summarization if available in your OpenClaw version.

Node Connection Problems

If you have paired nodes (remote devices connected to your OpenClaw instance), node connection failures show up as specific error patterns in the logs.

Symptoms of node issues: Commands that should use a node return "no node available." Node shows as paired but actions time out. Tools that depend on a node (camera, screen capture) fail consistently.

Check node status:

openclaw nodes status

Reconnect a node: Nodes connect outbound from the remote device to your gateway. If the node disconnects, restart the node host process on the device. The node re-registers automatically on reconnect.

Node address mismatch: If you changed your gateway port or host address, existing node configs point to the old address. Update the connection command on the device:

openclaw node run --host YOUR_GATEWAY_IP --port 18789

For server-level networking that affects node connectivity, the DigitalOcean VPS setup guide covers firewall configuration and port management.

Quick Reference: Error to Fix

FAQ

Where are the OpenClaw logs stored?

Live logs stream via openclaw logs --follow. For persistent log files, check ~/.openclaw/logs/ (location may vary by install). Log level can be increased with openclaw config set logging.level debug for more verbose output.

Do config changes require a gateway restart?

Some config changes may hot-reload without a restart. Exceptions include token changes, plugin loading changes, and some networking changes. When in doubt, run openclaw gateway restart and check openclaw channels status --probe after.

How do I completely reset pairing for a channel?

openclaw pairing clear telegram

To clear a single user:

openclaw pairing revoke telegram <USER_ID>

After clearing, the next message from any sender triggers a fresh pairing flow.

Can I run multiple channels simultaneously?

Yes. OpenClaw runs all configured channels at the same time through a single gateway. Each channel has its own config section, its own pairing state, and its own session contexts. Your agent can respond on Telegram, Discord, and Slack simultaneously without any extra configuration. Having one channel fail does not affect others.

Why does openclaw doctor say my config is valid but messages still fail?

openclaw doctor validates config syntax and structure. It does not make live API calls. For runtime failures that pass config validation, openclaw channels status --probe is the right tool. It actually calls each channel's API to verify live connectivity.

Sources

1. OpenClaw Channel Troubleshooting - Official cross-channel troubleshooting reference with failure signatures for all platforms
2. OpenClaw Channels Overview - Overview of all supported channels with setup complexity and status
3. OpenClaw Configuration Reference - Complete DM and group policy documentation
4. OpenClaw Gateway Security - Security and routing documentation covering what approved users can trigger through the gateway

Conclusion

Five commands. That's the whole diagnostic framework.

1. Run openclaw status and confirm the gateway is running
2. Run openclaw logs --follow and watch what happens when you send a test message
3. Run openclaw doctor to catch config problems automatically
4. Check pairing with openclaw pairing list <channel>
5. Verify your channel is in the group allowlist and that mention gating matches your expectations

If those five steps don't resolve your issue, the problem is channel-specific. See the dedicated setup guides for Telegram and Discord for channel-specific configuration help. For setting up new channels from scratch, the Telegram setup guide is the simplest entry point, while the Discord setup guide covers the most feature-rich option.