DEV Community

Preecha
Preecha

Posted on

How to Fix OpenClaw Errors: 15 Common Issues and Solutions

TL;DR

OpenClaw troubleshooting typically involves connection drops, authentication failures, routing errors, and performance issues. Most problems come from network instability, incorrect API keys, or misconfigured channels. Use this guide to diagnose and fix the 15 most common OpenClaw errors.

Try Apidog today

Start with these three commands before changing your configuration:

openclaw gateway status
openclaw gateway inspect
tail -f ~/.openclaw/gateway.log
Enter fullscreen mode Exit fullscreen mode

They show whether the Gateway is running, which components are unhealthy, and what error occurred most recently.

Installation and setup issues

Node.js version mismatch

Symptom: The openclaw command is missing or fails with an "unsupported Node version" error.

Cause: OpenClaw requires Node.js 22 or later.

Check your installed version:

node --version
Enter fullscreen mode Exit fullscreen mode

If it is earlier than version 22, upgrade with nvm:

nvm install 22
nvm use 22
Enter fullscreen mode Exit fullscreen mode

Alternatively, install a current version from nodejs.org.

Reinstall OpenClaw after upgrading Node.js:

npm install -g openclaw@latest
Enter fullscreen mode Exit fullscreen mode

Verify both versions:

node --version
openclaw --version
Enter fullscreen mode Exit fullscreen mode

Permission denied during installation

Symptom: npm install -g openclaw fails with an EACCES or permission error.

Cause: npm is trying to write to a system directory without the required permissions.

Avoid installing with sudo. Configure a user-owned directory instead:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
Enter fullscreen mode Exit fullscreen mode

Add the directory to PATH in ~/.zshrc or ~/.bashrc:

export PATH=~/.npm-global/bin:$PATH
Enter fullscreen mode Exit fullscreen mode

Reload your shell:

# zsh
source ~/.zshrc

# bash
source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode

Install and verify OpenClaw:

npm install -g openclaw@latest
openclaw --version
Enter fullscreen mode Exit fullscreen mode

Config file not found

Symptom: OpenClaw cannot find ~/.openclaw/config.json after installation.

Cause: The onboarding wizard did not run or failed before creating the configuration.

Run onboarding manually:

openclaw onboard
Enter fullscreen mode Exit fullscreen mode

If that fails, create the configuration directory and a minimal config:

mkdir -p ~/.openclaw

cat > ~/.openclaw/config.json << 'EOF'
{
  "version": "1.0.0",
  "providers": {},
  "agents": {},
  "channels": {},
  "routing": []
}
EOF
Enter fullscreen mode Exit fullscreen mode

Run onboarding again:

openclaw onboard
Enter fullscreen mode Exit fullscreen mode

Channel connection problems

WhatsApp QR code will not scan

Symptom: The QR code appears, but WhatsApp reports an invalid code or does not respond.

Cause: The QR code expired, or the phone cannot connect to OpenClaw over the network.

Work through these steps:

  1. Connect your phone and computer to the same network.
  2. Log out of the current WhatsApp session.
  3. Generate a new QR code.
  4. Scan it within 30 seconds. 
openclaw channels logout whatsapp
openclaw channels login whatsapp
Enter fullscreen mode Exit fullscreen mode

If scanning still fails, check your firewall.

On macOS:

sudo /usr/libexec/ApplicationFirewall/socketfilterfw \
  --add /usr/local/bin/node
Enter fullscreen mode Exit fullscreen mode

On Linux with UFW:

sudo ufw allow 18789/tcp
Enter fullscreen mode Exit fullscreen mode

WhatsApp disconnects after a few hours

Symptom: WhatsApp connects successfully but disconnects after two to four hours.

Cause: Network changes or sleep mode interrupt the periodic heartbeat required by WhatsApp's protocol.

Enable automatic reconnection:

openclaw channels config whatsapp \
  --auto-reconnect true \
  --reconnect-interval 300
Enter fullscreen mode Exit fullscreen mode

This checks the connection every five minutes and reconnects when necessary.

If OpenClaw runs on a laptop, prevent the system from sleeping.

On macOS:

caffeinate -i openclaw gateway
Enter fullscreen mode Exit fullscreen mode

On Linux:

systemd-inhibit --what=sleep openclaw gateway
Enter fullscreen mode Exit fullscreen mode

For production deployments, run OpenClaw on an always-on server instead of a laptop.

Telegram bot does not receive messages

Symptom: The bot appears online but does not respond.

Cause: The bot token is invalid, or the bot does not have the required permissions.

Test the token directly against the Telegram API:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"
Enter fullscreen mode Exit fullscreen mode

If the request returns an error:

  1. Open Telegram and message @BotFather.
  2. Send /mybots.
  3. Select your bot.
  4. Choose API Token → Regenerate Token.
  5. Update OpenClaw: 
openclaw channels update telegram --token NEW_TOKEN
Enter fullscreen mode Exit fullscreen mode

For group chats, add the bot as an administrator with permission to read messages.

Discord bot shows as offline

Symptom: The bot appears offline in the Discord server list.

Cause: The bot is missing the Message Content Intent, or its token is invalid.

Enable the required intent:

  1. Open the Discord Developer Portal.
  2. Select your application.
  3. Open the Bot tab.
  4. Find Privileged Gateway Intents.
  5. Enable Message Content Intent.
  6. Save your changes.

Restart the Gateway:

openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

If the bot remains offline, test the channel:

openclaw channels test discord
Enter fullscreen mode Exit fullscreen mode

If the test fails, regenerate the token in the Developer Portal and update the OpenClaw channel configuration.

iMessage bridge does not work on macOS

Symptom: The iMessage channel reports disconnected or does not receive messages.

Cause: The terminal lacks accessibility permissions, the Messages app is not running, or the bridge process stopped.

Grant the required permission:

  1. Open System Settings → Privacy & Security → Accessibility.
  2. Add Terminal or your preferred terminal application.
  3. Restart OpenClaw: 
openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Make sure the Messages app is running and signed in, then test the integration by sending yourself a message.

Check whether the bridge process is running:

ps aux | grep openclaw-imessage-bridge
Enter fullscreen mode Exit fullscreen mode

If it is not running, restart the channel:

openclaw channels restart imessage
Enter fullscreen mode Exit fullscreen mode

Authentication and API errors

Invalid API key

Symptom: Logs contain Authentication failed or Invalid API key.

Cause: The configured key is incorrect, expired, or missing required permissions.

Test an Anthropic key:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 10,
    "messages": [
      {
        "role": "user",
        "content": "Hi"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Test an OpenAI key:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {
        "role": "user",
        "content": "Hi"
      }
    ],
    "max_tokens": 10
  }'
Enter fullscreen mode Exit fullscreen mode

If the direct API request fails, create a new key in the provider's dashboard.

Update OpenClaw and restart the Gateway:

openclaw config set --provider anthropic --api-key NEW_KEY
openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Rate limit exceeded

Symptom: Requests fail with Rate limit exceeded or Too many requests.

Cause: OpenClaw is sending more requests than the AI provider allows.

Check recent usage:

openclaw stats --period 1h
Enter fullscreen mode Exit fullscreen mode

Configure an application-level limit:

openclaw limits set --max-requests 50 --window 3600
Enter fullscreen mode Exit fullscreen mode

This limits OpenClaw to 50 requests per hour. Adjust the values to match your provider's limits.

For burst traffic, enable request queuing:

openclaw config set \
  --enable-queue true \
  --queue-max-size 100
Enter fullscreen mode Exit fullscreen mode

Messages will remain queued until request capacity becomes available.

Model not found

Symptom: Requests fail with Model not found or Invalid model.

Cause: The configured model does not exist or is unavailable to your account.

List Anthropic models:

curl https://api.anthropic.com/v1/models \
  -H "x-api-key: YOUR_KEY"
Enter fullscreen mode Exit fullscreen mode

List OpenAI models:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY"
Enter fullscreen mode Exit fullscreen mode

Update the agent to use an available model:

openclaw agents update default --model claude-sonnet-4-6
openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Insufficient credits

Symptom: Requests fail with Insufficient credits or Payment required.

Cause: The provider account has no remaining credits or has reached a billing limit.

Check your provider's billing dashboard:

Add credits or update the payment method.

To keep processing messages while resolving billing, route requests to a local model:

openclaw agents add fallback \
  --provider ollama \
  --model llama2

openclaw routing add --fallback fallback
Enter fullscreen mode Exit fullscreen mode

Message routing failures

Messages go to the wrong agent

Symptom: Messages are handled by the wrong agent despite configured routing rules.

Cause: Rules conflict or use incorrect priorities.

List the active rules:

openclaw routing list
Enter fullscreen mode Exit fullscreen mode

Rules with higher priorities match first. For example:

Priority 5:  channel=whatsapp    → agent=default
Priority 10: sender=+1234567890  → agent=vip
Enter fullscreen mode Exit fullscreen mode

A WhatsApp message from +1234567890 goes to vip because priority 10 wins.

Remove conflicting rules:

openclaw routing remove <rule-id>
Enter fullscreen mode Exit fullscreen mode

Recreate the rules with explicit priorities:

openclaw routing add \
  --channel whatsapp \
  --agent default \
  --priority 1

openclaw routing add \
  --sender +1234567890 \
  --agent vip \
  --priority 10
Enter fullscreen mode Exit fullscreen mode

Test the result without sending a live message:

openclaw routing test \
  --channel whatsapp \
  --sender +1234567890 \
  --message "test"
Enter fullscreen mode Exit fullscreen mode

Keyword routing does not work

Symptom: Messages containing expected keywords do not reach the configured agent.

Cause: Keyword matching is case-sensitive, or the message does not contain the exact keyword.

Create a case-insensitive rule:

openclaw routing add \
  --keyword "debug" \
  --agent debugging \
  --case-insensitive
Enter fullscreen mode Exit fullscreen mode

Use a regular expression for multiple terms:

openclaw routing add \
  --pattern "debug|error|bug" \
  --agent debugging
Enter fullscreen mode Exit fullscreen mode

Test the match:

openclaw routing test \
  --message "I found a debug issue"
Enter fullscreen mode Exit fullscreen mode

Custom routing function throws errors

Symptom: A custom routing function fails or does not execute.

Cause: Common causes include syntax errors, missing return values, unsupported asynchronous code, or unavailable dependencies.

Test the routing file directly:

openclaw routing test-custom \
  ~/.openclaw/routing.js \
  --message "test"
Enter fullscreen mode Exit fullscreen mode

A valid synchronous routing function should always return an agent name:

module.exports = function route(message) {
  if (message.channel === "whatsapp") {
    return "whatsapp-agent";
  }

  return "default";
};
Enter fullscreen mode Exit fullscreen mode

Do not use an asynchronous function:

// Do not use this pattern.
module.exports = async function route(message) {
  const result = await someAsyncOperation();
  return result;
};
Enter fullscreen mode Exit fullscreen mode

Custom routing functions must be synchronous.

Fallback agent is not triggered

Symptom: Messages do not reach the fallback agent when the primary agent fails.

Cause: No fallback is configured, or the primary agent is not reporting a failure.

Configure a fallback:

openclaw routing set-fallback backup-agent
Enter fullscreen mode Exit fullscreen mode

Test it by temporarily disabling the primary agent:

openclaw agents disable default
openclaw routing test --message "test"
Enter fullscreen mode Exit fullscreen mode

The routing test should select the fallback agent.

Re-enable the primary agent after testing:

openclaw agents enable default
Enter fullscreen mode Exit fullscreen mode

Performance and memory issues

High memory usage

Symptom: OpenClaw uses more than 2 GB of RAM, and usage continues to grow.

Cause: Session data accumulates without being cleaned up.

Inspect memory usage:

openclaw stats --memory
Enter fullscreen mode Exit fullscreen mode

Delete sessions older than seven days:

openclaw sessions clear --older-than 7d
Enter fullscreen mode Exit fullscreen mode

Reduce the session timeout to 30 minutes:

openclaw config set --session-timeout 1800
Enter fullscreen mode Exit fullscreen mode

Enable hourly cleanup:

openclaw config set \
  --auto-cleanup true \
  --cleanup-interval 3600
Enter fullscreen mode Exit fullscreen mode

Slow response times

Symptom: Responses take longer than 30 seconds or time out.

Cause: The request queue is backed up, the network is slow, or the AI provider is responding slowly.

Check the queue:

openclaw queue status
Enter fullscreen mode Exit fullscreen mode

If the queue contains more than 50 messages, increase concurrency:

openclaw config set --max-concurrent-requests 10
Enter fullscreen mode Exit fullscreen mode

This processes up to 10 messages simultaneously instead of the default three.

Check network latency:

# Anthropic
ping api.anthropic.com

# OpenAI
ping api.openai.com
Enter fullscreen mode Exit fullscreen mode

If latency is consistently higher than 200 ms, consider using another provider or a local model.

Configure a 30-second timeout:

openclaw config set --request-timeout 30000
Enter fullscreen mode Exit fullscreen mode

Requests that exceed the timeout will fail and retry.

Gateway becomes unresponsive

Symptom: The Gateway stops responding to messages or API calls.

Cause: Possible causes include a deadlock, infinite loop, or resource exhaustion.

Check the current status:

openclaw gateway status
Enter fullscreen mode Exit fullscreen mode

If the process is frozen, request a thread dump:

kill -SIGUSR1 $(pgrep -f "openclaw gateway")
Enter fullscreen mode Exit fullscreen mode

The dump is written to:

~/.openclaw/gateway.log
Enter fullscreen mode Exit fullscreen mode

Inspect the log for stuck operations, then restart the Gateway:

openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Enable health checks:

openclaw config set --health-check-interval 60
Enter fullscreen mode Exit fullscreen mode

The Gateway will check its health every 60 seconds and restart if it becomes unresponsive.

CPU usage spikes

Symptom: OpenClaw continuously uses 100% CPU.

Cause: A message flood, excessive logging, or an infinite loop may be consuming resources.

Inspect the process:

top -p $(pgrep -f "openclaw gateway")
Enter fullscreen mode Exit fullscreen mode

Reduce logging overhead:

openclaw config set --log-level warn
Enter fullscreen mode Exit fullscreen mode

Check recent message volume:

openclaw stats --messages --period 1h
Enter fullscreen mode Exit fullscreen mode

If a WhatsApp channel receives more than 1,000 messages per hour, configure a per-channel rate limit:

openclaw channels config whatsapp \
  --rate-limit 100 \
  --rate-window 3600
Enter fullscreen mode Exit fullscreen mode

Gateway crashes and restarts

Gateway crashes on startup

Symptom: openclaw gateway exits immediately without a useful error.

Cause: The configuration may be corrupted, dependencies may be missing, or the configured port may already be in use.

Run the Gateway in debug mode:

openclaw gateway --debug
Enter fullscreen mode Exit fullscreen mode

If the config is corrupted, back it up and reset it:

cp ~/.openclaw/config.json \
  ~/.openclaw/config.json.backup

openclaw config reset
openclaw onboard
Enter fullscreen mode Exit fullscreen mode

If dependencies are missing, reinstall OpenClaw:

npm uninstall -g openclaw
npm install -g openclaw@latest
Enter fullscreen mode Exit fullscreen mode

If port 18789 is already in use, start the Gateway on another port:

openclaw gateway --port 18790
Enter fullscreen mode Exit fullscreen mode

Gateway crashes during operation

Symptom: The Gateway runs successfully for a while, then exits unexpectedly.

Cause: Possible causes include an unhandled exception, memory leak, or an external process terminating it.

Inspect the most recent log entries:

tail -100 ~/.openclaw/gateway.log
Enter fullscreen mode Exit fullscreen mode

Look for stack traces or error messages immediately before the crash.

Enable crash dumps:

openclaw config set --enable-crash-dumps true
Enter fullscreen mode Exit fullscreen mode

Future dumps will be written to:

~/.openclaw/crashes/
Enter fullscreen mode Exit fullscreen mode

Run the Gateway with automatic restart:

openclaw gateway --auto-restart
Enter fullscreen mode Exit fullscreen mode

For production, use a process manager such as PM2:

npm install -g pm2
pm2 start openclaw -- gateway
pm2 save
pm2 startup
Enter fullscreen mode Exit fullscreen mode

Session data is lost after restart

Symptom: Conversations reset whenever the Gateway restarts.

Cause: Sessions are not persisted, the session file is corrupted, or the disk is full.

Enable persistence:

openclaw config set \
  --persist-sessions true \
  --session-file ~/.openclaw/sessions.db
Enter fullscreen mode Exit fullscreen mode

Sessions will be written to disk every 30 seconds.

Check the session database:

ls -lh ~/.openclaw/sessions.db
Enter fullscreen mode Exit fullscreen mode

If the file is missing or has a size of zero bytes, check available disk space:

df -h ~
Enter fullscreen mode Exit fullscreen mode

After freeing disk space, restart the Gateway.

To restore a backup:

cp ~/.openclaw/sessions.db.backup \
  ~/.openclaw/sessions.db

openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Platform-specific problems

macOS: openclaw cannot be opened

Symptom: macOS blocks OpenClaw with an "unidentified developer" warning.

Cause: Gatekeeper quarantined the executable.

Remove the quarantine attribute:

xattr -d com.apple.quarantine "$(which openclaw)"
Enter fullscreen mode Exit fullscreen mode

Alternatively, open System Settings → Privacy & Security and click Allow Anyway next to the OpenClaw warning.

Linux: Permission denied for inotify

Symptom: OpenClaw reports:

ENOSPC: System limit for number of file watchers reached
Enter fullscreen mode Exit fullscreen mode

Cause: The Linux file watcher limit is too low.

Increase it:

echo fs.inotify.max_user_watches=524288 \
  | sudo tee -a /etc/sysctl.conf

sudo sysctl -p
Enter fullscreen mode Exit fullscreen mode

Restart OpenClaw:

openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Windows: Command not found

Symptom: Windows does not recognize the openclaw command.

Cause: npm's global binary directory is not included in PATH.

Find the global npm directory:

npm config get prefix
Enter fullscreen mode Exit fullscreen mode

Add that directory to your user PATH:

  1. Open System Properties → Environment Variables.
  2. Edit Path under User variables.
  3. Add C:\Users\YourName\AppData\Roaming\npm, or the path returned by npm.
  4. Save the changes.
  5. Restart your terminal.

Verify the installation:

openclaw --version
Enter fullscreen mode Exit fullscreen mode

Docker network issues

Symptom: OpenClaw runs in Docker but cannot connect to messaging platforms.

Cause: Docker network isolation prevents the required connections.

On platforms that support it, run with host networking:

docker run --network host \
  openclaw/openclaw gateway
Enter fullscreen mode Exit fullscreen mode

Alternatively, expose the Gateway port:

docker run -p 18789:18789 \
  openclaw/openclaw gateway
Enter fullscreen mode Exit fullscreen mode

For WhatsApp QR code scanning, expose the additional port:

docker run \
  -p 18789:18789 \
  -p 3000:3000 \
  openclaw/openclaw gateway
Enter fullscreen mode Exit fullscreen mode

Debugging tools and logs

Enable debug logging

Enable detailed logs and restart the Gateway:

openclaw config set --log-level debug
openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Logs are written to:

~/.openclaw/gateway.log
Enter fullscreen mode Exit fullscreen mode

Watch them in real time:

tail -f ~/.openclaw/gateway.log
Enter fullscreen mode Exit fullscreen mode

After troubleshooting, reduce the log level to avoid unnecessary I/O:

openclaw config set --log-level warn
openclaw gateway restart
Enter fullscreen mode Exit fullscreen mode

Test individual components

Test each channel independently:

openclaw channels test whatsapp
openclaw channels test telegram
openclaw channels test discord
Enter fullscreen mode Exit fullscreen mode

Test an agent without going through a messaging channel:

openclaw agents test default --message "Hello"
Enter fullscreen mode Exit fullscreen mode

Test routing separately:

openclaw routing test \
  --channel whatsapp \
  --sender +1234567890 \
  --message "debug issue"
Enter fullscreen mode Exit fullscreen mode

This workflow helps isolate the failing layer:

  1. If the channel test fails, debug the channel.
  2. If the agent test fails, debug the provider, key, or model.
  3. If both pass but routing fails, inspect routing priorities and patterns.

Inspect Gateway state

Run:

openclaw gateway inspect
Enter fullscreen mode Exit fullscreen mode

The output includes:

  • Active channels and their status
  • Configured agents and their health
  • Routing rules and priorities
  • Queue size and pending messages
  • Memory usage and uptime

Export diagnostics

Generate a diagnostic report:

openclaw diagnostics export \
  > openclaw-diagnostics.json
Enter fullscreen mode Exit fullscreen mode

The report includes:

  • Configuration with API keys redacted
  • Recent logs
  • Error counts
  • Performance metrics
  • System information

Review the report for sensitive data before sharing it with support.

Debug network connectivity

Test access to each provider:

openclaw network test anthropic
openclaw network test openai
Enter fullscreen mode Exit fullscreen mode

These commands check:

  • DNS resolution
  • TLS handshakes
  • API endpoint reachability
  • Network latency

If any check fails, troubleshoot the network before changing agent or routing configuration.

FAQ

Why does OpenClaw use so much memory?

OpenClaw keeps session history in memory for fast access. Each session stores its conversation context. For example, 100 active sessions with 50 messages each represent 5,000 messages in memory.

Reduce memory usage by lowering the session timeout, enabling cleanup, and limiting context length:

openclaw config set \
  --session-timeout 1800 \
  --auto-cleanup true \
  --max-context-length 50
Enter fullscreen mode Exit fullscreen mode

Can I run OpenClaw without internet?

Yes, if you use a local AI model. Install Ollama and configure OpenClaw to use it:

# Install Ollama
curl https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama2

# Configure OpenClaw
openclaw agents add local \
  --provider ollama \
  --model llama2 \
  --endpoint http://localhost:11434
Enter fullscreen mode Exit fullscreen mode

AI inference runs locally, but internet-based messaging platforms still require a network connection.

How do I migrate OpenClaw to a new machine?

Export the current configuration:

openclaw config export > openclaw-backup.json
Enter fullscreen mode Exit fullscreen mode

Copy openclaw-backup.json to the new machine, then install OpenClaw:

npm install -g openclaw@latest
Enter fullscreen mode Exit fullscreen mode

Import the configuration:

openclaw config import openclaw-backup.json
Enter fullscreen mode Exit fullscreen mode

Reconnect channels because QR sessions and tokens do not transfer automatically:

openclaw channels login whatsapp
openclaw channels update telegram --token YOUR_TOKEN
Enter fullscreen mode Exit fullscreen mode

Why do messages arrive out of order?

OpenClaw processes messages concurrently. Messages sent close together may reach the AI provider in a different order because of network timing.

To preserve message order, process one request at a time:

openclaw config set --max-concurrent-requests 1
Enter fullscreen mode Exit fullscreen mode

This reduces throughput but guarantees sequential processing.

Can I use OpenClaw in production?

Yes, but apply the following operational controls:

  • Run OpenClaw on a server instead of a laptop.
  • Use a process manager such as PM2 or systemd.
  • Enable session persistence.
  • Configure monitoring and alerts.
  • Apply channel and provider rate limits.
  • Put the Control UI behind a reverse proxy such as Nginx.
  • Enable HTTPS.
  • Back up configuration and session data regularly.

Example systemd unit:

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/bin/openclaw gateway --port 18789
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
Enter fullscreen mode Exit fullscreen mode

Save the file as /etc/systemd/system/openclaw.service, then enable it:

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw
sudo systemctl status openclaw
Enter fullscreen mode Exit fullscreen mode

How do I report bugs?

Generate a diagnostic report:

openclaw diagnostics export > diagnostics.json
Enter fullscreen mode Exit fullscreen mode

Open an issue on GitHub and include:

  • OpenClaw version: 
  openclaw --version
Enter fullscreen mode Exit fullscreen mode
  • Node.js version: 
  node --version
Enter fullscreen mode Exit fullscreen mode
  • Operating system
  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Relevant log output
  • Diagnostic report

Review and redact sensitive data before uploading logs or diagnostics.

Conclusion

Most OpenClaw failures come from network problems, incorrect configuration, invalid credentials, or platform-specific restrictions.

Use this troubleshooting order:

  1. Check ~/.openclaw/gateway.log.
  2. Run openclaw gateway inspect.
  3. Test channels, agents, and routing independently.
  4. Enable debug logging when the standard logs are insufficient.
  5. Export diagnostics before reporting a bug.
  6. Restart only after collecting the relevant error output.

If you are building API workflows alongside OpenClaw, Apidog can provide API design, testing, and documentation capabilities alongside OpenClaw's conversational interface.

Next steps:

  • Bookmark this guide for quick reference.
  • Set up monitoring to detect failures early.
  • Join the OpenClaw Discord for real-time help.
  • Contribute fixes back to the project on GitHub.

Top comments (0)