Back to Articles
AI Systems10 min read
Why OpenClaw Is Not Responding: Full Fix Guide (2026)
Your OpenClaw agent won't respond? Here is the complete troubleshooting guide covering gateway issues, authentication failures, and silent message drops.
Your OpenClaw agent won't respond? Here is the complete troubleshooting guide covering gateway issues, authentication failures, and silent message drops.
If you self-host an OpenClaw agent, you have probably experienced that sinking feeling: you send a message through Telegram, WhatsApp, or Discord, and nothing comes back. The gateway status shows green, the logs look clean, but your agent is silent. This is one of the most frustrating problems in the OpenClaw ecosystem, and if you run a homelab setup, you already know the pain of debugging something that looks healthy but behaves dead.
I have been running OpenClaw on a small Proxmox LXC container for months, and the "not responding" issue has hit me more times than I care to count. The good news is that the vast majority of these cases break down into a handful of root causes. Based on the official OpenClaw documentation at docs.openclaw.ai, here is a structured, practical guide to figuring out why your agent is ignoring you and what to do about it.
OpenClaw operates as a gateway that sits between you and various AI providers, managing authentication, message routing, and session state. Understanding this architecture is not academic — it is the single most useful thing you can do for debugging. When your agent stops responding, the problem could be anywhere along this chain:
The absolute first thing you should reach for is openclaw doctor. This is the single most important diagnostic tool in the entire OpenClaw CLI. According to docs.openclaw.ai, the doctor command checks the Gateway, Channels, Skills, Plugins, and Memory search status in one sweep.
openclaw doctorIf you want it to attempt automatic repairs on top of diagnostics:
openclaw doctor --repairThe official documentation indicates that running openclaw doctor --repair audits and auto-repairs configuration drift — things like a missing gateway.mode setting, broken credential references, or incompatible plugin configurations.
If the doctor finds issues it cannot fix automatically, it will tell you exactly what is wrong. Write that down. That is your debugging roadmap.
It is easy to glance at openclaw gateway status and see a green light, then move on. Do not make that mistake. The official docs recommend using the --deep flag to add a system-level service scan:
openclaw gateway status --deepThis matters for homelab users because your gateway might be running inside a Docker container, a systemd service, or a LaunchAgent on macOS. The shallow status check only tells you the process is alive — the deep check adds a system-level service scan.
If the gateway reports as running but nothing responds on the gateway port, the official docs point to an authentication requirement as the likely cause. You can verify the gateway port and binding mode with:
openclaw config get gateway.port
openclaw config get gateway.bind
openclaw config get gateway.modeFor homelab setups where you might be running multiple OpenClaw instances or have port conflicts from other services, explicitly checking these values can save you an hour of head-scratching.
This is the most common hidden cause of non-responsiveness. The official troubleshooting docs at docs.openclaw.ai have a dedicated section for authentication issues, including an auth detail codes quick map. The key codes to know:
AUTH_TOKEN_MISMATCH — The shared token does not match the gateway auth tokengateway.auth.token — No token configured at allTo check your current auth token:
openclaw config get gateway.auth.tokenFor dashboard paths, you can also check the Control UI connectivity section in the official docs. If you recently updated OpenClaw, automatic updates can change your Node.js version, and the official documentation recommends verifying it:
node --versionFor refreshing provider credentials, refer to the official documentation for the correct authentication setup command.
A silent failure — messages that appear to send but never get a response — often traces back to the model configuration. The official docs recommend checking your primary model setting:
openclaw config get agents.defaults.modelsOr more specifically for the primary model:
openclaw config get agents.defaults.models.primaryIf you are running a local OpenAI-compatible backend (like Ollama or vLLM), the official troubleshooting guide at docs.openclaw.ai has a specific section titled "Local OpenAI-compatible backend passes direct probes but agent runs fail." The recommended approach is:
1. Test the backend directly with a small call to confirm it works
2. If tiny direct calls work but larger OpenClaw prompts crash the backend, treat it as an upstream model/server limitation
3. Refer to the deep runbook at /gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail
For homelab users running local models, this is a critically important distinction. Your local LLM might handle a single short prompt fine, but once OpenClaw wraps it in system prompts, tool definitions, and conversation history, the context window fills up fast. If your local model has a 4K context limit and OpenClaw is trying to send an 8K prompt, the backend crashes silently.
If the gateway is healthy and authentication passes, the problem might be your channel — the messaging app your agent uses. Official docs reference channel-specific troubleshooting at /channels/troubleshooting.
Check if your channels are connected:
openclaw channels listFor Telegram and Discord, the official docs mention a pairing process that requires a WebSocket connection. If you see gateway closed (1008): pairing required, your channel session needs to be re-paired.
Another common channel issue is the dmPolicy setting. If your agent is configured only to respond in group chats but you are sending a direct message (or vice versa), messages will flow into the gateway but never trigger a response. You can check this with:
openclaw config get agents.defaults.channelPoliciesOr if you have per-agent settings:
openclaw config get agents.<agent-name>.channelPoliciesIf your agent responds inconsistently — sometimes it works, sometimes it does not — the issue might be related to heartbeat intervals or cron job scheduling. The official docs have a dedicated troubleshooting section for cron and heartbeat delivery at /gateway/troubleshooting#cron-and-heartbeat-delivery.
Check your current heartbeat interval:
openclaw config get agents.defaults.heartbeat.everyFor homelab users running OpenClaw on less powerful hardware (Raspberry Pi, old NUC, low-end VPS), a too-aggressive heartbeat can cause the agent to fall behind on message processing. The default is typically reasonable, but if you have customized it, consider backing it off.
Port 18789 is the default gateway port. If you are running other services on your homelab server — and let us be honest, who is not? — you might have a conflict. The official GitHub issue tracker at github.com/openclaw/openclaw has documented cases where the gateway refused to start because port 18789 was already in use, yet no visible application appeared to be running.
You can change the port:
openclaw config set gateway.port 18790
openclaw gateway restartFor Docker-based installations, the official docs mention you can set the gateway mode via environment variable:
docker run -e OPENCLAW_GATEWAY_MODE=local openclaw-stackThis is useful if you want to isolate your OpenClaw instance from the host network entirely.
When all else fails, watch the logs in real time while you send a test message. The official CLI reference includes:
openclaw logs --followFor gateway-specific verbose logging when starting the gateway:
openclaw gateway --port 18789 --verboseThis gives you the raw WebSocket traffic and authentication handshake. If you see something like "no credentials" or "auth token mismatch," you know exactly which direction to dig.
One thing I genuinely appreciate about OpenClaw's architecture is that many configuration changes apply without restarting the gateway. According to the official config reference, these settings hot-apply:
dmPolicy, allowFrom)This is a big deal for homelab users because you can iterate on settings without disrupting active conversations. If you are testing a new model or tweaking rate limits, you do not need to bring the whole agent down.
Settings that do require a restart include changes to gateway.port, gateway.bind, gateway.mode, and gateway.auth.token.
Your entire OpenClaw configuration lives in a file called openclaw.json. The official docs confirm you can override its location with the OPENCLAW_CONFIG_PATH environment variable or the --profile <name> CLI flag, which isolates all state under a separate directory. This is useful for running multiple isolated instances on the same machine — something homelabbers frequently do when testing different agent configurations.
To read configuration values directly from the running gateway (not just the file):
openclaw config get <key>For example:
openclaw config get agents.defaults.maxConcurrentThe official docs note that settings that apply through agents.defaults should be set there rather than duplicated per-agent. If you have inconsistent behaviors between agents, run openclaw doctor --repair to find and remove orphaned settings.
Based on the official docs, here are the most relevant error codes you will encounter when OpenClaw is not responding:
| Code | Meaning | Fix |
|------|---------|-----|
| AUTH_TOKEN_MISMATCH | Shared token does not match gateway auth | Run openclaw config get gateway.auth.token and compare with provider config |
| gateway closed (1008): pairing required | Channel needs re-pairing | Re-run the channel pairing flow |
| Missing gateway.mode | Gateway mode not set | Run openclaw setup or set gateway.mode=local |
| Gateway probe warnings | Remote gateway unreachable | Run openclaw gateway probe --ssh user@gateway-host |
If your OpenClaw agent is not responding, do not panic, and do not start randomly changing settings. The debugging path is clear:
1. Run openclaw doctor --repair first
2. Run openclaw gateway status --deep to confirm the service is truly healthy
3. Check authentication with openclaw config get gateway.auth.token
4. Verify model configuration with openclaw config get agents.defaults.models
5. Inspect channel connectivity with openclaw channels list
6. Watch live logs with openclaw logs --follow
One honest caveat: the official docs are good, but they are still evolving. OpenClaw moves fast, and some sections of the troubleshooting tree reference pages that are thin on details. The deep runbook at /gateway/troubleshooting is the gold standard — bookmark it before you need it.
If you run OpenClaw in Docker, pay special attention to your port mappings and environment variables. If you run it natively on Linux, make sure your Node.js version is compatible. And if you are running local AI models, remember that OpenClaw is context-hungry — your 7B model might work for short queries but crash on longer conversations.
For my own homelab, I have settled on a pre-update ritual: take a backup of openclaw.json before any update, run openclaw doctor after the update, and keep a pinned Node.js version. This has cut my "not responding" incidents to nearly zero.