GitHubDiscord

Frequently Asked Questions

Quick answers to common questions about OpenClaw. Based on official documentation.

🚀Getting Started💬Chat Channels🤖Models & AI⚙️Configuration🔧Troubleshooting🔒Security

🚀Getting Started

What is OpenClaw?
OpenClaw is an open-source AI assistant framework that connects to chat platforms like Telegram, Discord, WhatsApp, Slack, and more. It's designed for developers and power users who want full control over their AI assistant.

Unlike closed AI services, you own your data, can self-host, and customize everything. Run it locally or in the cloud.→ See full guide
How do I install OpenClaw?
macOS/Linux:
curl -fsSL https://openclaw.ai/install.sh | bash
Windows (PowerShell):
iwr -useb https://openclaw.ai/install.ps1 | iex
Then run the wizard:
openclaw onboard --install-daemon
The wizard configures auth, gateway settings, and optional channels.→ See full guide
What are the prerequisites?
Node.js 22+ - Check with: node --version

API Key - Get from Anthropic (recommended), OpenAI, Google, MiniMax, or others

Optional: A chat platform account (Telegram bot, Discord app, WhatsApp)→ See full guide
How do I start chatting?
Fastest method - No channel needed:
openclaw dashboard
Opens the Control UI at http://127.0.0.1:18789

With a channel: After running openclaw onboard, message your connected Telegram/Discord/WhatsApp bot.→ See full guide
How do I run the gateway in the foreground?
Useful for testing or debugging:
openclaw gateway --port 18789
This runs the Gateway without installing as a service.
How do I send a test message?
Requires a configured channel:
openclaw message send --target +15555550123 --message "Hello from OpenClaw"
Works with Telegram user IDs, Discord channel IDs, or phone numbers.

💬Chat Channels

What chat platforms are supported?
Core channels:
  • WhatsApp (via Baileys, QR pairing)
  • Telegram (bot API via grammY)
  • Discord (Bot API + Gateway)
  • Slack (Bolt SDK)
  • IRC (classic IRC servers)
Plugins: Signal, Google Chat, Mattermost, Microsoft Teams, LINE, Matrix, Nostr, Twitch, and more.

See all channels at the official docs.→ See full guide
How do I connect Telegram?
1. Open Telegram, search for @BotFather
2. Send /newbot and follow prompts
3. Copy your bot token
4. Run: openclaw channels login --channel telegram
5. Paste your token when prompted

Your bot will respond to mentions and DMs.→ See full guide
How do I connect Discord?
1. Go to discord.com/developers
2. Create Application → Bot → Reset Token
3. Enable "Message Content Intent" in Bot settings
4. Copy token, run: openclaw channels login --channel discord
5. Invite bot to your server→ See full guide
How do I connect WhatsApp?
Run: openclaw channels login --channel whatsapp

Scan the QR code with your WhatsApp app. The session persists until you explicitly log out.

Note: One device at a time - logging in elsewhere will log out the previous session.→ See full guide
Can I use multiple channels at once?
Yes! Run openclaw channels login for each platform. All connected channels route to your AI.

You can also set up different agents per channel using bindings.→ See full guide
How do groups work?
Group behavior varies by channel:
  • Telegram: Bot can be added to groups, respond to mentions or keywords
  • Discord: Respond to mentions or in specific channels
  • WhatsApp: Limited group support
Configure group policies in your config to require mentions or keywords to trigger the bot.→ See full guide

🤖Models & AI

Which model should I use?
Best Value: MiniMax M2.5 - ~$0.40/M tokens, excellent coding
Best Overall: Claude Sonnet 4.5 - great reasoning at reasonable price
Best for Coding: Claude Opus 4.6 or Qwen 2.5 Coder (local)
Free Option: Ollama with Llama 3.3 (local, no API costs)

See our Models page for full comparison.→ See full guide
How do I change the model?
List available models:
openclaw models list
Set a new model:
openclaw models set anthropic/claude-sonnet-4-5
Or edit your config directly to set fallbacks.→ See full guide
Can I run models locally?
Yes! Install Ollama from ollama.ai, then:
ollama pull llama3.3 ollama pull mistral ollama pull qwen2.5-coder
OpenClaw auto-detects Ollama at http://localhost:11434→ See full guide
How does API key rotation work?
Set multiple keys:
OPENAI_API_KEYS="sk-key1,sk-key2,sk-key3"
OpenClaw automatically rotates to the next key when hitting rate limits. Only rate-limit errors (429) trigger rotation.→ See full guide
What model providers are supported?
Built-in: OpenAI, Anthropic, Google Gemini, MiniMax, OpenRouter, Groq, Cerebras, Mistral, xAI, Hugging Face, and more.

Self-hosted: Ollama, vLLM, LM Studio, any OpenAI-compatible API.

See official docs for full list.→ See full guide

⚙️Configuration

How do I configure multiple users?
Set DM isolation in your config:
{"session": {"dmScope": "per-peer"}}
Use allowFrom to whitelist specific users:
{"channels": {"telegram": {"dmPolicy": "allowlist", "allowFrom": ["123456789"]}}}
→ See full guide
How do I set up a reverse proxy?
We have guides for both Nginx and Caddy. Key settings:
  • Enable WebSocket support
  • Set timeout to 24h+ (OpenClaw uses long-lived connections)
  • Configure SSL/TLS
See Nginx and Caddy guides for step-by-step instructions.→ See full guide
Where is the config file?
Default: ~/.config/openclaw.json

Custom path:
export OPENCLAW_CONFIG_PATH=/path/to/config.json
View current config: openclaw configure
What environment variables are available?
  • OPENCLAW_HOME - Home directory for path resolution
  • OPENCLAW_STATE_DIR - State directory override
  • OPENCLAW_CONFIG_PATH - Config file path override
  • ANTHROPIC_API_KEY, OPENAI_API_KEY, etc. - Provider API keys
See official docs for full list.

🔧Troubleshooting

Gateway won't start - what to check?
Run the diagnostic tool:
openclaw doctor
Common issues:
  • No API key - run openclaw onboard
  • Port in use - check other processes on 18789
  • Docker not running - start Docker daemon
  • Invalid API key - verify in provider dashboard
→ See full guide
Why am I getting rate limited?
Solutions:
  1. Set fallback models in config
  2. Enable API key rotation with multiple keys
  3. Use a faster model (Haiku, GPT-4o Mini)
  4. Add delay between requests
Rate limits reset typically within 1 minute.→ See full guide
Messages not being received?
Check channel status:
openclaw channels status
Verify:
  • Bot is in the channel/chat
  • Bot has required permissions
  • Webhook/connection is active
  • Check openclaw logs for errors
→ See full guide
High memory usage?
Common causes:
  1. Large context/memory files - run openclaw memory trim
  2. Many concurrent sessions - reduce maxConcurrent
  3. Long conversation history - adjust contextTokens limit
See Gateway Memory guide for optimization tips.→ See full guide

🔒Security

How do I secure my OpenClaw?
Quick security audit:
openclaw security audit
Essential tips:
  1. Don't share your API keys
  2. Use allowlists to restrict channel access
  3. Run behind a reverse proxy with auth
  4. Never commit .env files to git
  5. Enable HTTPS in production
  6. Use DM isolation for multi-user
→ See full guide
What's the hardened security baseline?
Start with this baseline config:
{"gateway": {"mode": "local", "bind": "loopback", "auth": {"mode": "token"}}, "session": {"dmScope": "per-channel-peer"}, "tools": {"profile": "messaging"}}
This keeps the Gateway local-only, isolates DMs, and uses minimal tools.
Is my data secure?
You control your data:
  • Self-host on your own infrastructure
  • All data stays in your workspace
  • Choose which data to share with AI providers
  • Clear memory/conversations anytime
No telemetry or data collection by default.
How do credentials get stored?
  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegram bot token: config/env or channels.telegram.tokenFile
  • Discord bot token: config/env
  • Pairing allowlists: ~/.openclaw/credentials/<channel>-allowFrom.json
  • Model auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Can't find your answer? Ask on GitHub or Discord