Troubleshooting Guide

• Restart your terminal
• Add npm to PATH: export PATH="$PATH:$(npm bin -g)"
• Use npx: npx openclaw init
• Check npm prefix: npm config get prefix

• Fix npm permissions: mkdir ~/.npm-global && npm config set prefix '~/.npm-global'
• Use nvm (Node Version Manager)
• Or run with sudo (not recommended)

• Check version: node --version
• Update Node.js: npm install -g n && n latest
• Or use nvm to manage versions
• Minimum required: Node.js 18+

• Port conflict: Check port isn't in use
• Docker not running: Start Docker daemon
• Missing volumes: Create required directories
• Pull image manually: docker pull openclaw/openclaw

• Inconsistent indentation (use spaces, not tabs)
• Missing colons after keys
• Unquoted special characters
• Duplicate keys

• Validate YAML: npm install -g yaml-lint && yaml-lint gateway.yaml
• Use an online YAML validator
• Check for hidden characters

• API key is correct and not expired
• No extra spaces in config
• Key format matches provider (sk-..., anthropic-..., etc.)
• API key has sufficient credits
• Environment variable is set correctly

• Check model name format (provider/model-id)
• Verify model is available in your region
• Update to latest OpenClaw version
• Check provider's model list

model: "openai/gpt-4o"
model: "anthropic/claude-3-5-sonnet-20241022"
model: "google/gemini-pro"

• Channel name is correct (lowercase)
• Channel is enabled in OpenClaw
• Credentials are properly formatted

1. Run with verbose: openclaw start --verbose
2. Check logs for error messages
3. Verify config loads: openclaw config validate
4. Try minimal config (just one channel)

# Find process
lsof -i :3000

# Kill it
kill -9 [PID]

# Or use different port
openclaw start --port 3001

• Reduce context window in config
• Clear memory database
• Restart the gateway
• Add swap space
• Use smaller models
• Limit concurrent requests

• Reduce max_tokens setting
• Clear session memory
• Shorter system prompt
• Use model with larger context
• Enable aggressive forgetting in memory config

• Wait 60 seconds and retry
• Reduce message frequency
• Add delay between requests

• Upgrade your API plan
• Use a provider with higher limits
• Implement request caching
• Consider local LLM for high-volume

• Check internet connection
• Verify API endpoint is reachable
• Check firewall/proxy settings
• Try different network
• Check provider status pages

• Generate new invite link with correct permissions
• Check bot is not already in server
• Verify you have admin rights to add bots
• Check Discord's bot requirements

• Read Messages
• Send Messages
• Embed Links
• Attach Files
• Use Slash Commands
• Manage Threads (for thread support)

openclaw connect whatsapp --reset

• Phone is connected to internet
• Session is still active
• Not in "last seen" restricted mode
• Recipient hasn't blocked you

• Bot token is correct
• Bot is not blocked by user
• Started with /start command
• Bot is in the group (if group chat)

openclaw telegram getUpdates

1. Go to Slack App configuration
2. Click "Install to Workspace"
3. Authorize with admin account
4. Copy the OAuth token
5. Add to gateway config

• Valid phone number
• Signal account already registered
• CAPTCHA may be required

memory:
  enabled: true
  provider: "pinecone"

• Vector database credentials are correct
• Database/index exists
• Network connectivity to DB

• Verify API key/credentials
• Check endpoint URL
• Ensure project/index exists
• Check network access
• Verify firewall rules

• File path is correct
• File format is supported
• Files are readable
• Size is reasonable (not too large)

• TTS provider API key is valid
• Voice ID exists for provider
• ffmpeg is installed
• Audio output device is configured

which ffmpeg
ffmpeg -version

• Microphone permissions granted
• STT provider configured
• Audio format is correct
• API key has credits

• Use closer TTS/STT provider
• Reduce audio quality
• Check network latency
• Use local TTS/STT
• Enable push-to-talk mode

openclaw install @skill-name --verbose

• Check skill name is correct
• Verify internet connection
• Clear npm cache: npm cache clean --force
• Check skill compatibility with your OpenClaw version

• Skill is added to config
• Restart gateway after install
• Check skill has required dependencies
• Verify skill version compatibility

docker logs [container_id]

• Config error (crashes on startup)
• Missing environment variables
• Out of memory
• Invalid volume paths

• Port is open in firewall
• Router port forwarding configured
• Using correct external IP/DDNS
• HTTPS certificate valid

• Domain DNS points to server
• Port 80 is accessible
• Domain is valid

sudo certbot --nginx -d yourdomain.com

• Large context: Clear memory or reduce history
• Slow API: Use faster model or provider
• Network: Check connection speed
• Too many skills: Disable unused skills
• Server load: Check CPU/memory

• Limiting concurrent requests
• Using lighter models
• Disabling unused features
• Checking for infinite loops in custom skills

• Official Docs
• Discord Community
• GitHub Issues
• FAQ Page

• OpenClaw version
• Your config (without secrets)
• Error messages
• Steps to reproduce