OpenClaw Gateway Troubleshooting: 8 Common Errors and How to Fix Them

# Find what is using port 18789
lsof -i :18789

# Kill the process using that port
kill $(lsof -ti:18789)

# If it refuses to die, force kill
kill -9 $(lsof -ti:18789)

# Now start the gateway
openclaw gateway start

# Option 1: Add to your shell profile (~/.zshrc or ~/.bashrc)
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
export OPENAI_API_KEY="sk-your-key-here"

# Reload your shell
source ~/.zshrc

# Option 2: Add to your OpenClaw config
# Create or edit ~/.openclaw/.env
echo 'ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.openclaw/.env
echo 'OPENAI_API_KEY=sk-your-key-here' >> ~/.openclaw/.env

# Option 3: For systemd services, add to the unit file
# Edit /etc/systemd/system/openclaw.service
# Under [Service], add:
# Environment=ANTHROPIC_API_KEY=sk-ant-your-key-here
# Then reload: sudo systemctl daemon-reload && sudo systemctl restart openclaw

# Option 4: For Docker, pass as environment variables
docker run -d \
  --name openclaw-gateway \
  -e ANTHROPIC_API_KEY=sk-ant-your-key-here \
  -e OPENAI_API_KEY=sk-your-key-here \
  -p 18789:18789 \
  openclaw-gateway

# Check file ownership
ls -la ~/.openclaw/agents/

# Fix permissions (replace 'youruser' with your actual username)
chown -R youruser:youruser ~/.openclaw/

# Check disk space
df -h

# If disk is full, clear old session files
# WARNING: This deletes conversation history
rm -rf ~/.openclaw/agents/*/sessions/sessions.json

# Check if the sessions directory exists
ls -la ~/.openclaw/agents/orion/sessions/

# If it does not exist, create it
mkdir -p ~/.openclaw/agents/orion/sessions/

# Step 1: Verify your bot token is correct
# Test it directly with the Telegram API
curl https://api.telegram.org/bot[YOUR_BOT_TOKEN]/getMe

# Step 2: Check if a webhook is already set (from a previous setup)
curl https://api.telegram.org/bot[YOUR_BOT_TOKEN]/getWebhookInfo

# Step 3: If webhook URL is set but you are running locally, clear it
curl https://api.telegram.org/bot[YOUR_BOT_TOKEN]/deleteWebhook

# Step 4: For local development, use polling mode
# In your agent config, set:
# "telegram": { "mode": "polling", "token": "YOUR_BOT_TOKEN" }

# Step 5: For production with a public URL, set the webhook
curl -X POST https://api.telegram.org/bot[YOUR_BOT_TOKEN]/setWebhook \
  -d "url=https://yourdomain.com:18789/telegram/webhook"

# Step 6: Restart the gateway
openclaw gateway stop
openclaw gateway start

# Check container exit reason
docker inspect openclaw-gateway --format='{{.State.OOMKilled}}'

# Run with adequate memory (1GB recommended)
docker run -d \
  --name openclaw-gateway \
  --restart unless-stopped \
  --memory=1g \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw-gateway

# Common volume mount issues:
# WRONG - mounts empty directory, gateway has no config
docker run -v /nonexistent/path:/root/.openclaw ...

# RIGHT - mount your actual config directory
docker run -v ~/.openclaw:/root/.openclaw ...

# Check container logs for the real error
docker logs openclaw-gateway

# If the container keeps restarting, check logs immediately
docker logs --tail 50 openclaw-gateway

# Step 1: Confirm the gateway is running
openclaw gateway status

# Step 2: Check your agent's heartbeat config
# In your agent's config.json, verify the heartbeat section:
# {
#   "heartbeat": {
#     "interval": "0 */6 * * *",
#     "message": "Check for new tasks and report status"
#   }
# }

# Step 3: Verify cron syntax is valid
# Use crontab.guru to validate your expression
# Common mistake: "every 6 hours" is "0 */6 * * *", NOT "*/6 * * * *"
# "*/6 * * * *" means every 6 MINUTES

# Step 4: Check gateway health to confirm it can reach the agent
openclaw gateway health

# Step 5: Manually trigger the heartbeat to test
openclaw agent --agent orion --message "heartbeat test"

# Step 6: If the gateway was not running, start it as a daemon
pm2 start "openclaw gateway start" --name openclaw

# Check if session files exist
ls -la ~/.openclaw/agents/orion/sessions/

# Check if WORKING.md exists and has content
cat ~/.openclaw/agents/orion/WORKING.md

# Verify the session key is consistent
# Each CLI call should use the same session key
# If you are calling from different terminals, specify the session explicitly
openclaw agent --agent orion --session "main" --message "Hello"

# Check that SOUL.md instructs the agent to read WORKING.md
# Your SOUL.md should contain something like:
# "At the start of every session, read WORKING.md for context"

# Check file permissions
ls -la ~/.openclaw/agents/orion/WORKING.md
# The gateway user must have read AND write access

# If WORKING.md is empty or missing, create it
echo "# Agent Working Memory" > ~/.openclaw/agents/orion/WORKING.md

# Check current heartbeat interval
# In your agent's config.json:
# "heartbeat": { "interval": "*/5 * * * *" }
# This fires every 5 MINUTES - that is 288 API calls per day per agent!

# Better: every 6 hours
# "heartbeat": { "interval": "0 */6 * * *" }
# That is 4 API calls per day

# Even better: use a cheaper model for routine heartbeat tasks
# In SOUL.md, specify model routing:
# "For heartbeat/routine checks, use claude-3-haiku"
# "For complex tasks, use claude-sonnet-4-20250514"

# Disable heartbeat entirely if you do not need it
# Remove the "heartbeat" section from config.json

# Monitor costs by checking token usage in gateway logs
openclaw gateway status

# Use local models (Ollama) for non-critical agents
# See: /blog/openclaw-ollama-local-agents

# 1. Check gateway status and uptime
openclaw gateway status
# Shows: running/stopped, uptime, port, number of active agents

# 2. Test gateway health endpoint
openclaw gateway health
# Tests: HTTP endpoint, API key validity, agent configs loaded

# 3. Deep diagnostic probe
openclaw gateway probe
# Tests: port binding, API connectivity, file permissions,
#        session directory access, Telegram webhook status,
#        disk space, memory usage

# Additional useful commands:

# Check what is using the gateway port
lsof -i :18789

# View gateway logs in real-time
# (depends on how you run the gateway)
pm2 logs openclaw              # pm2
sudo journalctl -u openclaw -f # systemd
docker logs -f openclaw-gateway # Docker

# Test a specific agent without going through Telegram
openclaw agent --agent orion --message "ping"

# Clear all sessions (nuclear option)
rm -rf ~/.openclaw/agents/*/sessions/sessions.json

# Restart the gateway cleanly
openclaw gateway stop && openclaw gateway start