🔧 OpenClaw Troubleshooting

"Connection refused" after install

Browser shows ERR_CONNECTION_REFUSED when trying to open the dashboard.

Fix:

The gateway isn't running. Start it:

openclaw gateway start

Then open the dashboard URL again (usually http://localhost:18788).

Gateway token missing / unauthorized

Logs show "unauthorized" or gateway refuses to start claiming token is missing.

Fix:

The gateway token wasn't set or doesn't match. Run:

openclaw setup

This regenerates tokens and updates config. Restart the gateway after:

openclaw gateway restart

Docker build fails on Synology/NAS

Docker image fails to build, container crashes, or permission errors.

Fix:

• Use the official Docker image instead of building from source
• Ensure volume mounts have correct permissions (chown -R 1000:1000)
• For Synology, use Container Manager with the pre-built image from ghcr.io

docker pull ghcr.io/openclaw/openclaw:latest

Docker pull "access denied"

Docker compose fails with access denied or "repository does not exist".

Fix:

The image name may have changed. Use the current official image:

image: ghcr.io/openclaw/openclaw:latest

Shell/terminal startup slow after installing OpenClaw

Terminal takes several seconds to open after installing OpenClaw (especially with zsh).

Fix:

OpenClaw 2026.2.2+ auto-detects slow dynamic completion patterns and migrates them to cached files. Run openclaw doctor to check, or manually update: the cached completion scripts are stored in ~/.openclaw/ and sourced from your shell profile.

Mac sleep kills the bot

"My bot stops when my Mac sleeps"

Fix:

Use caffeinate -s to prevent sleep, or run OpenClaw as a launchd service (openclaw service install). For laptops: System Settings → Energy → Prevent automatic sleeping when display is off. For headless Mac minis: sudo pmset -a sleep 0 displaysleep 0.

Chrome extension "missing" after install

Installed OpenClaw but can't find the Chrome extension / "Bundled extension not generated"

Fix:

The Chrome extension ships with the npm package. Go to chrome://extensions, enable Developer mode, click "Load unpacked", and navigate to the extension directory (usually ~/.openclaw/chrome-extension/ or find it with openclaw which extension). If the directory is empty, run openclaw setup to regenerate it.

API keys: where are they stored?

Changed API key but old one still being used, or "where does OpenClaw store my keys?"

Fix:

API keys are in your OpenClaw config file (~/.openclaw/config.yaml or wherever openclaw config path points). Keys set via openclaw setup go there. Environment variables (e.g., ANTHROPIC_API_KEY) override config. After changing keys, restart: openclaw gateway restart. Check active key with openclaw status.

Tailscale "pairing required" (1008)

Remote access via Tailscale shows "pairing required" or error 1008

Fix:

The gateway needs to trust the Tailscale IP. Add your Tailscale subnet to gateway.trustedProxies in config. Also ensure the node is paired: run openclaw pair on the remote machine and approve it from the gateway. See the Tailscale guide for step-by-step setup.

Switching from Claude to DeepSeek

Want to use DeepSeek API instead of Claude to save costs.

Fix:

1. Set agents.defaults.model to deepseek/deepseek-chat
2. Add API key: llm.providers.deepseek.apiKey

DEEPSEEK_API_KEY=your-api-key-here

ChatGPT rate limits (ChatGPT Plus)

Getting rate limited messages even though "no response limit" was promised.

Fix:

Switch to API keys which have higher limits:

1. Get an API key from OpenAI
2. Remove OAuth profile: from config
3. Add: llm.providers.openai.apiKey

openclaw gateway restart

Removing ChatGPT to use only API

Set up ChatGPT initially but want to switch to API-only setup.

Fix:

Edit config and remove or empty the ChatGPT profile:

llm:
  providers:
    openai:
      apiKey: "sk-..."   # use API only
      # profile: chatgpt  # remove/comment this

Set your API keys under llm.providers and restart.

Gemini reasoning/metadata leaking into messages

When using Gemini 3 Pro (especially with high thinking), internal reasoning tokens or metadata appear in Telegram messages.

Fix:

Known issue with certain Gemini models. Workaround: use a lower thinking level (/reasoning low or off), or switch to Claude/GPT for sessions where this is disruptive. Being tracked upstream.

Cloudflare AI Gateway as a provider

Can I route API calls through Cloudflare AI Gateway?

Answer:

Yes, added in 2026.2.3. During onboarding (openclaw onboard), select Cloudflare AI Gateway as your provider. This lets you use Cloudflare's caching, rate limiting, and analytics on top of any model provider. See docs for setup details.

"Context Too Long" on first message

Fresh session, just said "hello" and got "context too long" error

Fix:

Usually caused by oversized workspace files (SOUL.md, AGENTS.md, MEMORY.md) being injected into context. Check total size: wc -c ~/clawd/*.md. Keep injected files under ~50KB combined. Also check if you have large files in the workspace root that are being auto-loaded. Move big files to subdirectories or add them to .openclawignore.

Setting up iMessage

Can't find how to add iMessage from the dashboard.

Fix:

iMessage requires macOS and Full Disk Access:

1. Open Full Disk Access in Terminal (System Settings → Privacy)
2. Grant access to the imsg provider and Terminal/iTerm
3. Set channels.imessage.enable: true in config

Note: iMessage requires active iCloud login with iMessage enabled.

Telegram bot not responding

Created Telegram bot but it doesn't reply to messages.

Fix:

• Check you're messaging the correct bot
• Ensure it was started with /start in Telegram
• Verify token matches BotFather exactly
• Check logs: openclaw gateway logs | grep telegram

Need the full walkthrough? See the Telegram setup guide and the Slash Commands QRG.

Second agent not responding on Telegram

Multi-agent setup where one agent works but another doesn't.

Fix:

Each agent needs its own Telegram bot. Create a new bot via @BotFather for each agent:

agents:
  main:
    channels:
      telegram:
        botToken: "BOT_TOKEN_MAIN"
  assistant:
    channels:
      telegram:
        botToken: "BOT_TOKEN_ASSISTANT"

Double/duplicate responses

Bot sends the same message twice or multiple times.

Fix:

Usually a webhook vs polling conflict:

• Pick one mode (polling is simpler for local setups)
• Check for duplicate channel entries in config
• Restart cleanly: openclaw gateway stop && openclaw gateway start

BlueBubbles is now the recommended iMessage integration

Setting up iMessage — the old imsg channel is now legacy.

Fix:

Use BlueBubbles instead. Install BlueBubbles server on a Mac, configure the OpenClaw bluebubbles channel. See openclaw docs channels/bluebubbles. The imsg channel still works but is no longer maintained.

Signal messages showing as <media:unknown>

Text messages from Signal appear as <media:unknown> instead of the actual text.

Fix:

Usually caused by zombie signal-cli processes. Kill all signal-cli processes: pkill -f signal-cli, then restart the gateway: openclaw gateway restart. If persistent, check that your signal-cli version is compatible (0.13.x recommended).

Feishu/Lark channel support

Can I use OpenClaw with Feishu or Lark?

Answer:

Yes! Feishu/Lark support was added in 2026.2.2. See the docs: openclaw docs channels/feishu. Configure your Feishu app credentials in the OpenClaw config under channels.feishu.

Discord "channels unresolved"

Discord bot connected but shows "channels unresolved" or doesn't respond in specific channels

Fix:

Discord requires numeric channel IDs, not names. Right-click the channel → Copy Channel ID (enable Developer Mode in Discord Settings → Advanced first). Use the numeric ID in config: channels.discord.channelIds: ["123456789"]. Restart after updating.

How to restart the bot

Bot is misbehaving or stuck.

Fix:

For a complete reset including sessions:

openclaw gateway restart

For a full session wipe:

openclaw gateway stop
rm -rf ~/.openclaw/agents/*/sessions/*
openclaw gateway start

Bot doing random/unwanted things

Bot performs actions you didn't ask for or seems confused.

Fix:

• Check SOUL.md and AGENTS.md for autonomous behaviors
• Review HEARTBEAT.md for scheduled tasks
• Restart gateway

"Antignify no longer supported" warning

Shows antignify/deprecation warnings after updating.

Fix:

Full update cycle:

npm cache clean --force
npm install -g openclaw
openclaw gateway stop
# using git install:
git pull
npm install
openclaw gateway start

Cron jobs not firing / not scheduling

Cron jobs appear configured but never execute. nextRunAtMs shows 0 or null.

Fix:

Several cron fixes landed in 2026.2.2-2026.2.3. Update to latest: npm install -g openclaw@latest. Also: one-shot (at) jobs now auto-delete after success by default. If your job disappeared, that's expected behavior. Use --keep-after-run if you want to retain it. Check openclaw cron list to verify jobs are registered.

Cron reminders not delivering to the right channel

Agent creates a cron reminder but it delivers to a different channel than where you asked for it.

Fix:

Known issue — cron reminders created by the agent may not inherit the originating channel. Workaround: explicitly specify the target in the reminder text, or set sessionTarget: "main" with payload.kind: "systemEvent". Being tracked upstream.

Context compaction breaks session (orphaned tool results)

After context compaction, the session becomes permanently broken — agent can't respond, errors about orphaned tool_result blocks.

Fix:

This is a known edge case tracked in GitHub issues #9672, #8967, #5497. Workaround: start a new session (/new in Telegram or Web UI). The team is actively fixing compaction edge cases. Update to latest for the best compaction behavior.

Web UI: Agents Dashboard

How do I manage agent files, skills, and cron from the browser?

Answer:

OpenClaw 2026.2.2+ includes an Agents Dashboard in the Web UI. Access it at your gateway URL (usually http://localhost:18788). You can manage agent files (SOUL.md, AGENTS.md, etc.), view/edit tools, skills, models, channels, and cron jobs — all from the browser. No terminal needed.

ClawHub skill upload CORS / 404 errors

Trying to upload a skill to ClawHub and getting CORS errors or 404 on auth.clawdhub.com.

Fix:

Known issue — the ClawHub auth domain may have a mismatch. Check that you're using the latest openclaw CLI version. If the issue persists, install skills locally instead: download the skill files and place them in ~/.openclaw/skills/<skill-name>/. Report the issue on Discord or GitHub.

Setting default subagent thinking level

How do I control the thinking/reasoning level for subagents?

Answer:

New in 2026.2.2: set agents.defaults.subagents.thinking in your config (e.g., "low", "medium", "high"). You can also set it per-agent via agents.list[].subagents.thinking. This prevents subagents from using expensive high-reasoning by default.

Docker path mismatch

Bot uses /home/openclaw/clawd instead of /workspace or can't find files

Fix:

The workspace volume mount must match what's configured. In docker-compose.yml, map your host path to /workspace: volumes: - ./clawd:/workspace. Then set agents.defaults.workspace: "/workspace" in config. Don't mix old Clawdbot paths with new OpenClaw ones.

Docker: skills don't work

Skills that use CLI tools (ffmpeg, yt-dlp, etc.) fail in Docker

Fix:

The default Docker image is minimal. Install needed tools in your Dockerfile or use the -full image tag: ghcr.io/openclaw/openclaw:latest-full. Alternatively, mount host binaries: volumes: - /usr/local/bin/ffmpeg:/usr/local/bin/ffmpeg.

Gateway GUI broken after update

"Disconnected from gateway" in Web UI after updating OpenClaw

Fix:

Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R). If that doesn't work, the WebSocket port may have changed. Check openclaw status for the current gateway URL. Also try: openclaw gateway stop && openclaw gateway start (full stop/start, not just restart).

"punycode module is deprecated" warning in logs

You see (node:XXXXX) [DEP0040] DeprecationWarning: The punycode module is deprecated in your OpenClaw logs.

Fix:

Node.js v21+ deprecated the built-in punycode module. Some OpenClaw dependencies still reference it. It's cosmetic — nothing is broken. Add NODE_OPTIONS=--no-deprecation to your environment:

• launchd (macOS service): Add to your plist's EnvironmentVariables dict:

  <key>NODE_OPTIONS</key>
  <string>--no-deprecation</string>

• Docker: Add -e NODE_OPTIONS=--no-deprecation to your run command.
• systemd: Add Environment=NODE_OPTIONS=--no-deprecation to your service file.

Then restart the gateway: openclaw gateway restart

QMD Memory "key unrecognized"

Setting up QMD memory backend and getting "key unrecognized" errors

Fix:

QMD memory was added in 2026.2.2. Ensure you're on the latest version. The config key is agents.defaults.memory.backend: "qmd". If you get "key unrecognized", your version may be too old — update with npm install -g openclaw@latest. Check supported backends with openclaw config schema | grep memory.

Exec tool not working with allowlist

Agent can't run commands even though exec is in the tools list

Fix:

The exec tool has a security allowlist. In config, set tools.exec.security: "full" for unrestricted access, or use tools.exec.security: "allowlist" with tools.exec.allowlist: ["git", "ls", "cat"] to whitelist specific commands. Default is restrictive. Restart after changing.

Web search without write permission

Web search fails in sandbox mode or when agent doesn't have write access

Fix:

Web search (Brave) needs network access but not file write. If running in sandbox mode, ensure tools.web_search is in your enabled tools list. The Brave API key goes in config: tools.web_search.braveApiKey: "BSA...". Sandbox mode restricts file writes, not network calls.

How to make bot proactive

"How do I make my bot check things automatically / send me updates?"

Fix:

Enable heartbeats in config: heartbeat.enable: true with heartbeat.intervalMs: 300000 (5 min). Create a HEARTBEAT.md in your workspace with tasks to check. The agent reads it each heartbeat and acts on items. For scheduled tasks, use cron: the agent can create cron jobs via the cron tool, or set them in config under cron.jobs. See the docs for examples.

Upgrading from Clawdbot to OpenClaw

Have Clawdbot installed, want to upgrade to OpenClaw.

Fix:

Your data is preserved automatically:

npm install -g openclaw

The ocl command replaces openclaw. Your config at ~/.openclaw is auto-migrated to ~/.openclaw on first run.

If you see "data migration skipped" warning, the new config will already exist. Check both directories and merge manually if needed.