Troubleshooting

Symptom When executing the openclaw start or openclaw serve command, the program fails immediately and outputs the following error message: Error: listen EADDRINUSE :::3000 at Server.setupListenHandler [as _listeningListener] (node:net:1465:14) at ListenAndServe (node:net:1398:7) at ListenAndServe (net:http:1801:9) ... This indicates that the port OpenClaw is trying to bind to (default 3000) is already occupied by another process. Root Cause Analysis Port Conflict: Another service on the local computer (such as a Node.js app, Apache, Nginx, or another OpenClaw instance) is already using port 3000. Zombie Process: A previous OpenClaw process might not have terminated properly and is still holding the port. Configuration Error: The user might have set an already occupied port in the configuration file. Solution Method 1: Find and terminate the process occupying the port macOS / Linux: ...

Symptom When deploying OpenClaw using Docker, the container exits immediately after starting. Checking the logs reveals the following error: docker: Error response from daemon: OCI runtime create failed: container_linux.go:345: starting container process caused: exec: /usr/local/bin/docker-entrypoint.sh: permission denied: unknown. Or: Error: ENOENT: no such file or directory, stat '/app/config/openclaw.config.js' Root Cause Analysis File Permission Issues: The ENTRYPOINT script in the Dockerfile lacks execution permissions. Incorrect Mount Paths: The configuration file is not correctly mounted to the specified path inside the container. Improper Working Directory Setup: The working directory (WORKDIR) of the container is not set correctly. Missing Environment Variables: Required environment variables are not passed in the docker run command. Solution 1. Check and Fix the Dockerfile Ensure the Dockerfile correctly sets the entry script permissions: ...

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 --- title: "Chrome Extension Relay Authentication Failing with 401 - Valid HMAC Token Rejected" date: 2026-03-03 description: "The OpenClaw Chrome extension relay server rejects valid HMAC-SHA256 derived authentication tokens with 401 Unauthorized, preventing the browser extension from connecting despite correct configuration." tags: ["chrome-extension", "authentication", "hmac", "relay", "401", "browser-control"] sources: - platform: "GitHub Issue" id: "openclaw#32449" url: "https://github.com/openclaw/openclaw/issues/32449" openclaw_version: "2026.3.1" --- ## Symptom When using the OpenClaw Chrome extension to connect to the browser control server, authentication fails with a **401 Unauthorized** error, even when: - The HMAC-SHA256 token is correctly derived using the formula: `HMAC(gatewayToken, "openclaw-extension-relay-v1:{port}")` - The gateway token matches the configured token in `~/.openclaw/openclaw.json` - The correct relay port (18791) is being used **Error Response:** Derived relay token: 31ef63af71285c00acf36a78a3a33619a34b947fa99c4d8b149f5566b22d219f Response status: 401 Response body: Unauthorized ...

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 --- title: "Docker Image Shows False 'Update Available' Banner Due to Version Mismatch" date: 2026-03-10 description: "Docker images for 2026.3.1 and 2026.3.1-beta.1 share identical digest but the binary reports beta.1, causing the Control UI to incorrectly display an update notification." tags: ["docker", "update", "version", "control-ui", "false-positive"] sources: - platform: "GitHub Issue" id: "openclaw#32488" url: "https://github.com/openclaw/openclaw/issues/32488" openclaw_version: "2026.3.1" --- ## Symptom After pulling and running the Docker image `ghcr.io/openclaw/openclaw:2026.3.1`, the Control UI displays a persistent "Update available" banner showing: Update available: v2026.3.1 (running v2026.2.26) ...

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 --- title: "CLI Slack JSON Manifest Contains Pipe Characters That Break Copy-Paste Functionality" date: 2026-03-15 description: "When adding a Slack channel via CLI, the JSON manifest is framed with vertical pipe characters, making it invalid JSON and preventing direct copy-paste." tags: ["bug", "cli", "channels", "slack", "json", "ux"] sources: - platform: "GitHub Issue" id: "openclaw#32493" url: "https://github.com/openclaw/openclaw/issues/32493" openclaw_version: "2026.3.1" --- ## Symptom When adding a Slack channel through the OpenClaw CLI using the command `openclaw channels add`, the JSON manifest provided for faster setup is displayed with vertical pipe characters (│) framing the content. This makes the JSON appear formatted for visual display in the terminal, but produces invalid JSON that cannot be directly copied and used. The output looks similar to this: │ { │ │ “key”: “value” │ │ } │ ...

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 --- title: "Slack requireMention: true Is Bypassed for Thread Replies After Prior Bot Participation" date: 2026-03-25 description: "OpenClaw replies to untagged messages in Slack threads after it has previously participated in that thread, bypassing the requireMention setting." tags: ["bug", "bug:behavior", "slack", "mention-gating", "thread-participation"] sources: - platform: "GitHub Issue" id: "openclaw#64277" url: "https://github.com/openclaw/openclaw/issues/64277" openclaw_version: "2026.3.23-2" --- ## Symptom When a Slack channel is configured with `requireMention: true`, OpenClaw should only reply when explicitly mentioned in a message. However, users observe that: - OpenClaw correctly replies when the bot is explicitly mentioned in a thread - After OpenClaw has replied once in a thread, **subsequent messages in the same thread trigger responses even without mentioning the bot** - This behavior creates unnecessary noise in Slack threads as the bot responds to messages where it was not tagged ### Steps to Reproduce 1. Configure a Slack channel with `requireMention: true` 2. Start a thread and explicitly mention the bot in the first message 3. Wait for OpenClaw to reply 4. Send another reply in the same thread **without** mentioning the bot 5. Observe that OpenClaw still replies despite not being mentioned ## Root Cause Analysis The issue stems from how OpenClaw determines whether it has been "implicitly mentioned" in a thread. The code in the Slack integration treats thread participation as an implicit mention, which bypasses the `requireMention` gating. ### Code Flow Analysis **1. Implicit Mention Detection:** ```javascript const implicitMention = Boolean( !isDirectMessage && ctx.botUserId && message.thread_ts && ( message.parent_user_id === ctx.botUserId || hasSlackThreadParticipation(account.accountId, message.channel, message.thread_ts) ) ); 2. Mention Gate Resolution: ...

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 --- title: "Agent Timeout Does Not Surface Error to UI - UI Hangs Indefinitely" date: 2026-04-09 description: "When an LLM request times out during agent execution, the Web UI hangs indefinitely showing a loading spinner instead of displaying a timeout error message." tags: ["timeout", "agent", "web-ui", "websocket", "bug:behavior"] sources: - platform: "GitHub Issue" id: "openclaw#64793" url: "https://github.com/openclaw/openclaw/issues/64793" openclaw_version: "2026.4.9" --- ## Symptom When an LLM request exceeds the agent timeout threshold, the following behavior is observed: - **Agent logs** correctly log the timeout event: decision=surface_error reason=timeout ...