Skip to main content

Frequently Asked Questions (FAQ)

Here are the most common questions and troubleshooting tips for OpenClaw.

General Information​

1. What is OpenClaw?​

OpenClaw (formerly Clawdbot and Moltbot) is an open-source, self-hosted personal AI assistant. It acts as a centralized gateway connecting various messaging platforms (like WhatsApp, Telegram, Discord, Slack) to an AI agent powered by Large Language Models (LLMs). It allows you to run your own AI assistant on your own hardware or server.

2. Is it safe to run OpenClaw locally?​

While powerful, OpenClaw should be used with caution. Because it creates an agent capable of executing code and accessing the file system, it is recommended to run it in a sandboxed environment (like a Docker container), a dedicated machine, or a cloud server, rather than directly on a personal workstation containing sensitive data.

3. How do I improve OpenClaw's memory and persistence?​

By default, OpenClaw might lose context after a fresh install. To maintain long-term memory and establish Standard Operating Procedures (SOPs), you can connect it to a dedicated GitHub repository where it can store "memories" and learned behaviors.

4. What are the hardware requirements?​

OpenClaw itself is lightweight, but the LLMs it connects to can be resource-intensive. If running a local LLM, you'll need significant RAM and GPU power (requirements vary by model). For OpenClaw's gateway operations, a standard VPS or a modern laptop is sufficient. For complex tasks, models with large context windows (e.g., 64k tokens) are recommended.

Installation & Setup​

5. How do I fix "Container Stops Immediately"?​

This usually happens due to an invalid configuration or port 18789 being occupied.

  • Check Logs: Run docker compose logs openclaw-gateway.
  • Check Port: Ensure port 18789 is not in use.
  • Verify Config: Ensure your openclaw.json (or moltbot.json) is correctly mounted.

6. How do I fix "Gateway Fails to Start"?​

Common causes:

  • Node.js Version: Requires Node.js 22+.
  • Port Conflict: Another service is using port 18789.
  • Syntax Errors: Check your JSON config for trailing commas or missing brackets.

7. How do I fix Unraid installation issues (Token URL)?​

When setting up on Unraid, you must manually append the token to the Web UI URL.

  • Solution: Access the UI at http://<IP>:18789/?token=YOUR_TOKEN.

8. How do I fix Docker build "Error relocating /usr/bin/node"?​

This usually indicates an architecture mismatch (e.g., running an x86 image on ARM/Raspberry Pi) or an issue with the base Alpine image in the Dockerfile.

  • Solution: Ensure you use the correct Docker image tag for your architecture.

9. How do I fix "EVP_MD_CTX_get_size_ex: symbol not found"?​

This is typically a library compatibility issue in Alpine Linux-based containers, often related to OpenSSL versions.

  • Solution: Try updating the Docker image to the latest version or pinning it to a stable version known to work with your host kernel.

10. How do I fix permission errors on macOS?​

OpenClaw requires specific permissions to interact with the OS.

  • Solution: Go to System Settings > Privacy & Security. Grant "Screen Recording," "Accessibility," and "Full Disk Access" to the terminal or app running OpenClaw. Restart the gateway.

Configuration​

11. Where is my configuration file?​

Depending on your version and OS, it's usually at:

  • ~/.openclaw/openclaw.json
  • ~/.clawdbot/moltbot.json
  • ~/.config/openclaw/config.json You can run openclaw config path (or moltbot config path) to find the exact location.

12. How do I fix "No API Key Found"?​

  • Check Key: Verify the apiKey exists in your config file.
  • Check Env Vars: If referencing environment variables, ensure OPENAI_API_KEY, etc., are set.
  • Provider Match: Ensure the key matches the provider (e.g., don't put an Anthropic key in an OpenAI slot).

13. How do I fix "No API key found for anthropic" when not using Anthropic?​

OpenClaw often defaults to Anthropic/Claude. If you use another provider (like OpenAI or Ollama), you must explicitly set the default model in your configuration to one that doesn't use Anthropic.

14. How do I fix "Model Not Supported"?​

OpenClaw limits unsafe or outdated models.

  • Solution: Run openclaw models list to see supported models and update your config to use one of them.

15. How do I fix "Validation failed for tool 'exec'"?​

This often happens with local LLMs (like Ollama) that strictly validate tool-call JSON schemas.

  • Solution: Ensure the tool definition in your config matches the schema expected by the LLM exactly. This is often a property name mismatch (e.g., cmd vs command).

16. How do I validate my config file?​

Run the command:

openclaw config validate

This checks for syntax errors and missing required fields.

Troubleshooting Errors​

17. How do I fix API Key 401 Unauthorized errors?​

  • Invalid Key: You likely copied the key incorrectly or it has expired.
  • Formatting: Ensure it starts with the correct prefix (e.g., sk-...).
  • Account: Check that your API provider account is active and has credits.

18. How do I fix Model Not Found (404) errors?​

  • Typo: Check the model ID in your config (e.g., gpt-4o vs gpt-4-0).
  • Access: Your API key might not have access to that specific model.

19. How do I fix Rate Limited (429) errors?​

  • Slow Down: Requests are being sent too quickly.
  • Quota: Use a paid plan or request a higher rate limit from the provider.

20. How do I fix Internal Server Error (500)?​

This is usually an issue on the API provider's end. Wait a few minutes and try again. If it persists, check the OpenClaw logs for more specific error details.

21. How do I fix "Connection refused" errors?​

  • Base URL: Check that the baseUrl in your config is correct.
  • Service Down: If using a local model (Ollama/LM Studio), ensure that service is running.
  • Network: Check your internet connection.

22. How do I fix "Connection refused" specific to BaseURL?​

If connecting to a local service (like Ollama) inside a Docker container, localhost refers to the container, not the host.

  • Solution: Use host.docker.internal instead of localhost in your config baseUrl.

23. How do I fix "OpenClaw Not Responding"?​

  • Gateway Status: Run openclaw gateway status.
  • Restart: Run openclaw gateway restart.
  • LLM Hang: The model might be processing a very long context.

24. How do I fix "DNS Label Length Error"?​

This causes the service to crash.

  • Cause: Hostname is too long for mDNS (max 63 bytes).
  • Solution: Rename your host or container to a shorter name.

Usage & Connectivity​

25. How do I fix "Messaging Channel Not Connecting"?​

  • Credentials: Double-check the tokens/keys for that platform (Discord/Slack/Telegram).
  • Webhooks: Ensure your webhook URL is accessible from the internet (local testing might require a tunnel like Cloudflare or Ngrok).

26. How do I fix "Messages Not Triggering Responses"?​

  • Logs: Check logs to see if messages are being received.
  • Privacy Mode: For Telegram, disable "Group Privacy" in BotFather so the bot can see messages.
  • Permissions: Ensure the bot has permission to post in that channel.

27. How do I fix "Extra Workspace Folders Detected"?​

To avoid state conflicts, OpenClaw recommends keeping only one active workspace.

  • Solution: Archive or delete old workspace folders from your configured workspace directory.

28. How should I interact with OpenClaw for best results?​

Treat it like a remote intern. Be specific with instructions. Use the "Heartbeat Rule" (ask it to report status periodically). For security, use "disposable" or restricted credentials for any services you allow it to access.

29. How do I secure OpenClaw with Nginx?​

If exposing OpenClaw to the web:

  • Trusted Proxy: Configure Nginx to recognize trusted proxies.
  • Authentication: Secure your auth-profiles.json.
  • SSL: Always use HTTPS (Let's Encrypt).

30. How do I run diagnostics?​

Run the doctor command to check system and config health:

openclaw doctor