OpenClaw Not Working? 10 Common Errors and How to Fix Them

OpenClaw is powerful, but it has sharp edges. If you're self-hosting and something has gone wrong, you're probably staring at one of a handful of well-known issues. This guide covers the 10 most common OpenClaw errors and exactly how to fix each one.

Error 1: Gateway Shows "Active" But Agent Doesn't Respond

Symptom: systemctl --user is-active openclaw-gateway returns "active" but messages to your bot get no reply. openclaw channels status returns "Gateway not reachable."

Cause: OpenClaw's gateway can enter a zombie state. The Node.js process is alive (so systemd thinks it's running), but the internal WebSocket server has crashed silently.

Fix:

openclaw gateway restart

Long-term fix: Install a watchdog cron that checks the real gateway status every minute and restarts it when dead:

crontab -e
# Add:
* * * * * OPENCLAW_GATEWAY_TOKEN=your_token /usr/bin/openclaw channels status | grep -q 'running' || /usr/bin/openclaw gateway restart

---

Error 2: Agent Sends Empty Responses

Symptom: Your agent replies instantly with a blank message, or its responses become increasingly short until they're empty.

Cause: Session token bloat. OpenClaw accumulates the full conversation history in a session file. After many messages, the session grows past the model's context window and the agent can no longer generate a valid response.

Fix: Clear the session file and restart:

echo '[]' > ~/.openclaw/agents/main/sessions/$(ls ~/.openclaw/agents/main/sessions/*.jsonl | head -1)
echo '{}' > ~/.openclaw/agents/main/sessions/sessions.json
openclaw gateway restart

---

Error 3: "Unknown channel: telegram"

Symptom: Running openclaw channels add --channel telegram returns "Unknown channel: telegram".

Cause: A regression introduced in OpenClaw beta versions (v2026.2.22+) broke the channels add command.

Fix: Pin to the last stable version:

npm install -g openclaw@2026.2.17

Then use config set directly instead of channels add:

openclaw config set channels.telegram.botToken "YOUR_TOKEN"
openclaw config set channels.telegram.allowFrom '["*"]'
openclaw config set channels.telegram.dmPolicy open

---

Error 4: "model expects object, not string"

Symptom: Running openclaw config set agents.defaults.model "google/gemini-2.0-flash" throws a validation error.

Cause: The model config field expects an object, not a string. You need to set model.primary.

Fix:

openclaw config set agents.defaults.model.primary "google/gemini-2.0-flash"

---

Error 5: Authentication Failure / API Key Not Working

Symptom: Agent starts but immediately fails with authentication errors, or responses suggest the model isn't being reached.

Cause: OpenClaw does not read API keys from environment variables at runtime. The key must be written to a specific JSON file.

Fix: Write the key to:

nano ~/.openclaw/agents/main/agent/auth-profiles.json

Format:

{
  "version": 1,
  "profiles": {
    "anthropic:default": {
      "type": "api_key",
      "provider": "anthropic",
      "key": "sk-ant-..."
    }
  }
}

Use "google:default" for Gemini, "openai:default" for GPT-4o.

---

Error 6: "pairing required" When Opening the Web UI

Symptom: Opening the Web UI Gateway in a browser shows "disconnected (1008): pairing required".

Cause: OpenClaw's Web UI requires device pairing by default. In setups without a properly bootstrapped CLI device, there's no operator to approve pairings.

Fix:

openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true
openclaw gateway restart

---

Error 7: "dmPolicy open" Validation Error

Symptom: Running openclaw config set channels.telegram.dmPolicy open throws a validation error.

Cause: OpenClaw validates that allowFrom is configured before it will accept an open DM policy.

Fix: Always set allowFrom first:

openclaw config set channels.telegram.allowFrom '["*"]'
openclaw config set channels.telegram.dmPolicy open

---

Error 8: Gateway Doesn't Start After Server Reboot

Symptom: Everything works until your server reboots. After reboot, the agent is offline.

Cause: User-level systemd services don't start automatically unless lingering is enabled.

Fix:

loginctl enable-linger root
systemctl --user enable openclaw-gateway
systemctl --user daemon-reload

---

Error 9: npm Install Fails with EACCES Permission Error

Symptom: npm install -g openclaw fails with EACCES: permission denied.

Cause: npm's global prefix is owned by root, but you're running as a non-root user (or vice versa — permissions are misconfigured).

Fix:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g openclaw

Add the export PATH line to your ~/.bashrc or ~/.zshrc to make it permanent.

---

Error 10: Build Tools Missing — Native Module Compilation Fails

Symptom: npm install of OpenClaw (or its dependencies) fails with errors like node-gyp failed or make: not found.

Cause: OpenClaw has dependencies that need to be compiled from source, which requires build tools not installed by default on minimal Ubuntu.

Fix:

sudo apt-get install -y build-essential python3 git
npm install -g openclaw

---

Skip All of This

Every error on this list is something SimplifyClaw handles at deploy time. The watchdog, the auth-profiles format, the correct config order, the systemd lingering — all of it is set up automatically in the 60-second deployment.

If you're spending time debugging self-hosted OpenClaw instead of using it, SimplifyClaw is worth a look.