OpenClaw Troubleshooting

What this article covers

• Common post-installation errors.
• Gateway, provider, and model issues.
• Ollama connection errors and incorrect endpoints.
• Permissions, networking, and security.
• Diagnostic tools like openclaw doctor and openclaw security audit.

Introduction

OpenClaw is a powerful tool that gains deep system access. During installation and operation, various problems can arise: missing API keys, incorrect endpoints, permission errors, or an unreachable gateway. Knowing the most common error sources lets you quickly narrow down and fix issues.

This article provides a systematic approach to troubleshooting OpenClaw on Proxmox or other Linux systems.

Basic troubleshooting workflow

1. Check version: openclaw --version
2. Run doctor: openclaw doctor
3. View configuration: openclaw config list
4. Read logs: ~/.openclaw/logs/ or stderr
5. Minimal test: Single model with a simple prompt.
6. Expand gradually: Providers, gateway, skills, tools.

Installation errors

Installation fails

• Verify your Node.js version. OpenClaw requires a recent release.
• Use the official installer:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

• Ensure npm and curl are available.
• Check internet connectivity and DNS resolution.

Command not found

If openclaw is unavailable after installation:

which openclaw
/usr/bin/openclaw

If not in your PATH:

export PATH="$PATH:/usr/bin"

Onboarding issues

Wizard won’t start

openclaw onboard --classic

If interactive output is missing, check your terminal and whether stdin is available.

Provider not recognized

You may have chosen Skip for now during onboarding. Run onboarding again or configure the provider manually:

openclaw config set models.providers.anthropic.apiKey "YOUR_ANTHROPIC_API_KEY"

Gateway errors

Gateway unreachable

openclaw gateway install
openclaw gateway status

If the gateway isn’t running, check:

• Is the process active?
• Is the port in use?
• Was the correct bind parameter used?

Recommended:

openclaw config set gateway.bind "127.0.0.1"

Gateway on public interface

This is a security risk. Update your configuration:

openclaw config set gateway.bind "127.0.0.1"

For external access via Tailscale or SSH tunnels, avoid binding to 0.0.0.0.

Provider and model errors

Model not found

openclaw models list --provider anthropic
openclaw models list --provider ollama

• Verify the correct provider is configured.
• Check whether the model is downloaded in Ollama.
• Model names must match exactly, including tags.

Claude API key invalid

• Ensure the key is in the correct format.
• Check for account credit or rate limit issues.
• Set the key again:

export ANTHROPIC_API_KEY="NEW_KEY"
openclaw config set models.providers.anthropic.apiKey "$ANTHROPIC_API_KEY"

Ollama connection errors

Wrong endpoint

OpenClaw uses the native Ollama endpoint:

http://127.0.0.1:11434

Not:

http://127.0.0.1:11434/v1

openclaw config set models.providers.ollama.baseUrl "http://127.0.0.1:11434"
openclaw config set models.providers.ollama.apiKey "ollama-local"

Ollama unreachable

curl http://127.0.0.1:11434/api/tags

If this fails, check:

• Is Ollama running?
• Is the port correct?
• Are firewall or network isolation blocking it?
• In LXC, TUN isn’t required, but Ollama must be started.

Model exceeds available memory

• Ollama crashes or responds very slowly.
• Check RAM/VRAM with free -h or nvidia-smi.
• Switch to a smaller model or higher quantization.

Permission errors

OpenClaw running as root

OpenClaw should run under a dedicated user:

useradd -m -s /bin/bash openclaw
mv /root/.openclaw /home/openclaw/.openclaw
chown -R openclaw:openclaw /home/openclaw/.openclaw

Files not readable

ls -la /home/openclaw/.openclaw

Permissions should belong to the OpenClaw user.

Network and firewall issues

• No internet access: Required for installation and some skills.
• Proxmox firewall blocking ports: Allow only necessary ports between LXC containers.
• Tailscale unreachable: Check whether the node is online.
• Gateway not externally reachable: This is intentional if bound to loopback.

Security checks

openclaw security audit --deep
openclaw doctor --fix

security audit reveals risks like insecure permissions, open gateways, or outdated components. doctor checks installation health and can fix some issues automatically.

Common error messages

ECONNREFUSED

The target service is unreachable. Check the host, port, and firewall.

Unauthorized

API key is missing or invalid. Review provider settings.

Model not found

Model name is incorrect or the model isn’t installed. Use openclaw models list.

Permission denied

Filesystem permission issue. Verify user and file permissions.

Cannot find module

Installation may be incomplete. Reinstall or run openclaw doctor.

Further reading

• BotServ.de Installing OpenClaw on Proxmox
• BotServ.de OpenClaw with Ollama and Claude
• BotServ.de Managing Ollama
• BotServ.de Proxmox backups and restore

FAQ: OpenClaw troubleshooting

How do I restart OpenClaw? Stop the gateway and restart it, or reboot the entire LXC container.

Where are OpenClaw logs? Usually under ~/.openclaw/logs/, or check process output.

How do I verify my configuration? Use openclaw config list or openclaw doctor.

What should I do about ECONNREFUSED? Check the target host and port, start the service, allow it through the firewall.

Should OpenClaw run as root? No, a dedicated user is more secure.

References

• OpenClaw: https://openclaw.ai/
• Ollama Docs: https://github.com/ollama/ollama/blob/main/docs/
• Proxmox Troubleshooting: https://pve.proxmox.com/wiki/Troubleshooting

Summary

Most OpenClaw errors trace back to installation problems, incorrect provider settings, network issues, or permission misconfigurations. openclaw doctor and openclaw security audit aid diagnosis. Key practices include running a dedicated user, binding the gateway to loopback, using the correct Ollama endpoint, and performing regular security audits. Following a systematic approach and monitoring logs will resolve most issues quickly.