OpenClaw Help - Documentation, Support and Troubleshooting Guide

Getting stuck with OpenClaw is normal, especially during initial setup. The documentation is thorough but spread across a lot of pages, and some common problems have non-obvious solutions. Here's a guide to finding help, using the built-in diagnostic tools, and fixing the issues we see most often.

Official Documentation

The OpenClaw docs live at docs.openclaw.ai. They're organised into several sections:

Getting Started covers installation, the onboarding wizard, and basic setup. If you're new, start with the getting started guide.

Concepts explains how the platform works internally. The architecture page, agent runtime, session management, and multi-agent routing docs are the most useful for understanding what's happening under the hood.

Gateway has the technical reference for configuration, authentication, remote access, sandboxing, and secrets management. This is where you go when you need to configure something specific.

Tools covers skills, ClawHub, the exec tool, browser integration, sub-agents, and other agent capabilities.

Platforms has setup guides for macOS, iOS, Android, Windows (WSL2), and various cloud providers.

Install has platform-specific installation instructions for Docker, Node.js, Ansible, Nix, Podman, and cloud platforms like Fly.io, Railway, and Render.

Built-In Diagnostic Tools

OpenClaw has several commands specifically for troubleshooting. Use these before searching online or asking for help.

openclaw doctor

This is the first command to run when something isn't working:

openclaw doctor

It checks your installation, verifies gateway connectivity, tests model provider credentials, and reports any configuration issues. The output tells you exactly what's wrong and usually suggests how to fix it.

openclaw health

Quick check on whether the gateway is running and responsive:

openclaw health

For a more detailed check:

openclaw status --deep

This gives you gateway status, connected channels, active sessions, and node connections.

openclaw gateway status

Shows the gateway process status, port binding, and connection information:

openclaw gateway status

If the gateway isn't running, start it manually:

openclaw gateway --port 18789 --verbose

The --verbose flag gives you detailed logging, which is invaluable when debugging connection or channel issues.

openclaw secrets audit

If you're having authentication problems with AI model providers:

openclaw secrets audit --check

This scans for plaintext credentials, unresolved secret references, and configuration problems.

openclaw sandbox explain

If tool execution isn't working as expected:

openclaw sandbox explain

This shows the effective sandboxing configuration and tool policies for each agent.

Common Problems and Fixes

"openclaw: command not found"

The most common post-install issue. Your shell can't find the openclaw binary.

Fix: Check where npm installed it:

npm config get prefix

Add that path's bin directory to your PATH in ~/.zshrc or ~/.bashrc. If you use a version manager (nvm, fnm), make sure it's initialised in your shell startup file.

Gateway Won't Start

Usually one of three things:

1. Port already in use. Something else is running on 18789. Find it with lsof -i :18789 on macOS/Linux and either stop it or configure OpenClaw to use a different port.

2. Node version too old. OpenClaw needs Node 22+. Check with node --version.

3. Missing credentials. If your configuration references AI model API keys that aren't set, the gateway may fail to start. Run openclaw doctor to check.

Channel Won't Connect

WhatsApp issues are usually about the QR code pairing timing out or the session getting invalidated. Re-run openclaw channels login and scan the QR code within the timeout window. If you keep getting disconnected, check your phone's internet connection since WhatsApp Web sessions depend on the phone being online.

Telegram bot issues typically mean the bot token is wrong or expired. Create a new bot token through BotFather and update your configuration.

Discord connection problems are often permission-related. Make sure your bot has the right intents enabled in the Discord developer portal (Message Content intent is commonly missed).

Agent Not Responding

If the gateway is running but the agent isn't responding to messages:

1. Check the gateway logs for errors (openclaw logs)
2. Verify model provider credentials (openclaw models status)
3. Make sure the agent workspace exists and has valid configuration files
4. Check if the message sender is allowed (WhatsApp allowFrom, channel restrictions)
5. Try the Control UI at http://127.0.0.1:18789/ to test the agent directly

High API Costs

If your API costs are higher than expected:

/usage full

This shows per-message cost breakdowns. Common causes of high costs:

• Long conversation histories being sent as context (enable compaction)
• Media processing on every message (configure media handling)
• Web search running on queries that don't need it
• Using an expensive model for simple tasks

Getting Support

Community

The OpenClaw community is the primary support channel. Check the project's GitHub repository for issues, discussions, and pull requests. Searching existing issues often finds answers faster than posting new ones.

Professional Support

For businesses running OpenClaw in production, our OpenClaw managed service includes support as part of the package. We handle configuration, troubleshooting, and ongoing maintenance.

If you're not on the managed service but need help with a specific deployment issue, reach out and we can discuss consulting options. We've debugged enough OpenClaw deployments to know the common pitfalls and their fixes.

Useful CLI Commands Reference

Keep these handy:

Command	What it does
openclaw doctor	Full diagnostic check
openclaw health	Quick gateway health check
openclaw status --deep	Detailed system status
openclaw gateway status	Gateway process info
openclaw models status	AI provider credentials check
openclaw secrets audit --check	Security configuration audit
openclaw sandbox explain	Sandboxing policy review
openclaw logs	Gateway log output
openclaw nodes status	Connected device status
openclaw channels	Channel connection status
/status	In-chat status and costs
/usage full	Per-message cost breakdown

Making the Most of the Documentation

A few tips for navigating the docs effectively:

Use the search. The docs site has search functionality. It's faster than browsing through sections when you know what you're looking for.

Read the configuration reference. The configuration reference page is the single most useful page for anyone deploying OpenClaw. It lists every configuration option with descriptions and defaults.

Check the configuration examples. The configuration examples page shows real-world configurations for common deployment patterns. Copy and modify rather than building from scratch.

Look at the templates. OpenClaw provides template files for AGENTS.md, SOUL.md, TOOLS.md, and other bootstrap files. These give you a solid starting point for agent configuration.

If you need help beyond what the documentation and diagnostic tools provide, get in touch. We're happy to point you in the right direction.