# Troubleshooting Common Issues

Canonical: https://clawdocx.com/docs/troubleshooting
Author: Sam Okafor
Difficulty: BEGINNER
Published: 2026-02-24
Updated: 2026-09-19

> Solutions for common OpenClaw problems: unresponsive agents, permission errors, skill installation failures, gateway crashes, and messaging connection drops.

## First Steps: openclaw doctor

When something goes wrong, `openclaw doctor` is your starting point. It runs a comprehensive diagnostic of your entire OpenClaw installation and reports issues with suggested fixes.

```bash
openclaw doctor
```

Example output:

```
OpenClaw Doctor
===============

System:
  [PASS] Node.js v22.4.0
  [PASS] Operating system: macOS 15.3 (arm64)
  [PASS] Disk space: 45 GB available
  [PASS] Memory: 16 GB (14.2 GB available)

Configuration:
  [PASS] openclaw.json valid
  [PASS] SOUL.md present (2.4 KB)
  [WARN] API key for OpenAI not configured
  [PASS] API key for Anthropic configured

API Connectivity:
  [PASS] Anthropic API: connected (234ms)
  [SKIP] OpenAI API: not configured
  [PASS] ClawHub: reachable (189ms)

Gateway:
  [PASS] Gateway running (PID 1234, port 3420)
  [PASS] Uptime: 3 days 14 hours
  [PASS] Memory usage: 187 MB

Channels:
  [PASS] Telegram: connected
  [FAIL] Discord: disconnected (invalid token)
  [SKIP] WhatsApp: not configured

Skills:
  [PASS] 15 skills loaded
  [WARN] 1 skill has security warnings

Summary: 1 failure, 2 warnings
Run 'openclaw doctor --fix' to attempt automatic repairs.
```

### Automatic Fixes

```bash
openclaw doctor --fix
```

The `--fix` flag attempts to automatically resolve common issues:
- Regenerating corrupted configuration files
- Restarting the gateway if it is stuck
- Reinstalling broken skills
- Fixing file permissions
- Reconnecting messaging channels

> **Note**
>
> `openclaw doctor --fix` only fixes safe, reversible issues. It will not modify your SOUL.md, delete skills, or change API keys. It always reports what it changed.

---

## Agent Not Responding

This is the most common issue. Your agent is running but does not reply to messages.

### Diagnostic Steps

### Step 1: Check if the gateway is running

Run `openclaw health`. If the Gateway shows 'Not running', start it with `openclaw gateway start`.

### Step 2: Check API connectivity

Run `openclaw doctor`. Look at the 'API Connectivity' section. If your provider shows an error, your API key may be invalid, expired, or rate-limited.

### Step 3: Check the messaging channel

Look at the 'Channels' section in `openclaw doctor` output. If your channel shows 'disconnected', the token or credentials may be wrong.

### Step 4: Check the logs

Run `openclaw logs --follow` and send a test message. Watch for error messages in the log output. There is no `openclaw gateway logs` subcommand; logs are a top-level command.

### Step 5: Verify allowed users

Check openclaw.json to make sure your user ID is in the `allowed_users` list for your messaging channel. If it is missing, the agent ignores your messages.

### Common Causes and Fixes

| Cause | Symptom | Fix |
|-------|---------|-----|
| Gateway not running | `openclaw health` shows no gateway | `openclaw gateway start` |
| Invalid API key | 401 errors in logs | Regenerate key on provider dashboard |
| Rate limited | 429 errors in logs | Wait, or switch to fallback model |
| Expired token | Channel disconnected | Regenerate bot token |
| Wrong user ID | No errors, but no response | Check `allowed_users` in config |
| Port conflict | Gateway fails to start | Change port in config or stop conflicting service |

---

## Permission Errors

### macOS: "Operation not permitted"

OpenClaw needs Full Disk Access and Accessibility permissions on macOS. If you see "Operation not permitted" in the logs:

1. Open **System Settings > Privacy & Security > Full Disk Access**
2. Add the OpenClaw binary (`which openclaw` to find the path)
3. Also check **Accessibility** and add OpenClaw there
4. Restart the gateway: `openclaw gateway restart`

> **Warning**
>
> After macOS updates, permissions sometimes get reset. If your agent stops working after a system update, re-check the Privacy & Security settings.

### Linux: File Permission Denied

If OpenClaw cannot read or write files:

```bash
sudo chown -R openclaw:openclaw ~/.openclaw
```

```bash
chmod -R u+rw ~/.openclaw
```

### Linux: Systemd Service Permission Issues

If the systemd service fails with permission errors:

```bash
journalctl --user -u openclaw --no-pager -n 20
```

Common fixes:
- Ensure the service runs as the correct user
- Verify `loginctl enable-linger` is set for the user
- Check that the `WorkingDirectory` in the service file exists and is accessible

---

## Skill Installation Failures

### "Skill not found on ClawHub"

```bash
openclaw skills search <partial-name>
```

The skill name might be different from what you expect. Search for it to find the exact name.

### "Version conflict"

If a skill requires a newer version of OpenClaw:

```bash
openclaw update
```

Then retry the installation:

```bash
openclaw skills install <skill-name>
```

### "Security audit failed"

The built-in security scanner blocked the skill. There is no `openclaw security review`; the one documented subcommand is the audit, and `--deep` "adds best-effort live Gateway probes and plugin-owned security audit collectors":

```bash
openclaw security audit --deep
```

If you trust the skill after reviewing it, there is no `--skip-audit` flag either. The documented way past an install policy warning is to acknowledge it:

```bash
openclaw skills install @<publisher>/<slug> --acknowledge-install-policy-warning
```

> **Danger**
>
> Only acknowledge an install policy warning after you have personally reviewed the SKILL.md content and understood the risks. Never wave one through for a skill from an unknown author.

### "Skill failed to load"

There is no `openclaw skills validate`. The documented readiness command is `check`, which "reports missing prerequisites independently of agent exclusion":

```bash
openclaw skills check
```

Common YAML frontmatter issues:
- Missing required fields (name, version, author, description)
- Invalid YAML syntax (wrong indentation, missing quotes around special characters)
- Duplicate field names

---

## Gateway Crashes

### Gateway Keeps Crashing and Restarting

Check the crash logs. `openclaw logs` will "Tail Gateway file logs over RPC", and the page size flag is `--limit`, not `--last`:

```bash
openclaw logs --limit 100
```

Look for:
- **Out of memory**: Too many skills loaded, or context window too large. Reduce `max_context_tokens` in config.
- **Unhandled exception**: Usually a bug. Update OpenClaw to the latest version.
- **SIGKILL**: The OS killed the process (likely out of memory). Increase available RAM or reduce resource usage.

### Gateway Will Not Start

```bash
openclaw gateway start --verbose
```

The `--verbose` flag provides detailed startup information. Common issues:

**Port already in use:**
```
Error: EADDRINUSE: address already in use :::3420
```

Find what is using the port:

```bash
lsof -i :3420
```

Kill the conflicting process or change the port in `openclaw.json`.

**Corrupted configuration:**
```
Error: Failed to parse openclaw.json
```

Validate the JSON:

```bash
python3 -m json.tool ~/.openclaw/openclaw.json
```

If the JSON is corrupted, restore from the rotated backup. There is no `backups/` directory: "Any config write (including a `--fix` repair) rotates a backup to `~/.openclaw/openclaw.json.bak` (with a numbered `.bak.1`..`.bak.4` ring)", so the most recent good copy sits beside the live file.

```bash
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
```

**Missing dependencies:**
```
Error: Cannot find module 'xxx'
```

Reinstall OpenClaw:

```bash
npm install -g openclaw@latest
```

---

## Messaging Connection Drops

### Telegram Connection Drops Periodically

Telegram uses long-polling, which can be disrupted by network issues. Increase resilience:

```json
{
  "channels": {
    "telegram": {
      "polling_timeout": 30,
      "retry_delay": 5000,
      "max_retries": -1
    }
  }
}
```

`max_retries: -1` means infinite retries.

### Discord Bot Goes Offline

Discord bots can disconnect due to:
- Rate limiting (too many messages)
- Invalid intents configuration
- WebSocket connection timeouts

Check Discord-specific logs. There is no `--filter` flag on `openclaw logs`, so narrow the output yourself:

```bash
openclaw logs --limit 500 --plain | grep discord
```

Ensure your bot has the "Message Content Intent" enabled in the Discord Developer Portal under Bot > Privileged Gateway Intents.

### WhatsApp Webhook Stops Receiving

WhatsApp webhooks can silently fail if:
- Your webhook URL becomes unreachable (server restart, IP change)
- The webhook verification fails
- Meta deactivates the webhook due to errors

Verify your webhook is working:

```bash
openclaw doctor --channel whatsapp
```

### iMessage Stops Working After macOS Update

macOS updates can change the Messages database schema or reset permissions:

1. Re-grant Full Disk Access to OpenClaw
2. Restart the Messages app
3. Restart the OpenClaw Gateway
4. If still broken, check the OpenClaw GitHub issues for macOS version-specific fixes

---

## Heartbeat Issues

### Heartbeat Not Firing

There is no `openclaw heartbeat` command group and no `--last` flag. The documented reader is `openclaw system heartbeat last`, whose siblings are `enable` and `disable`, and which "always print the raw RPC JSON payload".

```bash
openclaw system heartbeat last
```

If no heartbeat cycles appear:
- Check that `heartbeat.enabled` is `true` in config
- Verify the gateway is running
- Check if active hours are configured and you are outside them
- Look for API errors in the logs

### Heartbeat Using Wrong Model

Read the value from the CLI rather than hunting through the file. There is no `openclaw config edit`, but `openclaw config get` reads one key by path:

```bash
openclaw config get agents.defaults.heartbeat.model
```

The command reports the path as unset rather than printing nothing: "A schema-valid but unset path explains that the runtime default applies", and "Optional fields with no runtime value are reported as unset". An unset heartbeat model means the heartbeat runs on the agent's own model. `model` is one of the heartbeat block's supported fields, so set it with `openclaw config set agents.defaults.heartbeat.model "<provider/model>"`, or run `openclaw config file`, which "Prints the active config file path", and edit that file by hand.

### Cron Jobs Not Executing

Cron jobs depend on the heartbeat. If the heartbeat is disabled, cron jobs will not run.

```bash
openclaw cron list
```

Check that:
- The cron job is enabled (not paused)
- The schedule syntax is valid
- The timezone is correct
- The heartbeat is enabled and running

---

## Performance Issues

### Slow Response Times

If your agent takes a long time to respond:

1. **Check API latency**: `openclaw health --test-api anthropic`
2. **Check context size**: Large conversation histories slow down processing. Reduce `max_history_messages`.
3. **Check skill count**: Too many active skills increase prompt size. Disable unused skills.
4. **Check the model**: Opus 4.6 is slower than Sonnet 4.6, which is slower than Haiku 4.
5. **Check system resources**: `top` or `htop` to see if the machine is overloaded.

### High Memory Usage

The Gateway should use 150-250 MB. If it uses more:

- Too many skills loaded (each adds to memory)
- Memory leak (update to latest OpenClaw version)
- Large data files cached in memory

Restart the gateway to reclaim memory:

```bash
openclaw gateway restart
```

---

## Resetting Your Agent

If all else fails, you can reset various components:

### Soft Reset (Keep Configuration)

Restart the gateway and clear caches:

```bash
openclaw gateway restart --clear-cache
```

### Reset Conversation History

```bash
openclaw reset --conversations
```

This clears all conversation history while keeping your configuration, skills, and SOUL.md.

### Reset Skills to Defaults

```bash
openclaw reset --skills
```

This removes all community and custom skills, keeping only built-in skills. Your SOUL.md and configuration are preserved.

### Full Reset

> **Danger**
>
> A full reset deletes all data, configuration, skills, and conversation history. Your agent will be as if freshly installed. Back up `~/.openclaw/` before doing this.

There is no `--full` flag. The scope is a value: `--scope` takes `config`, `config+creds+sessions`, or `full`, and `--dry-run` will "print actions without removing files" first.

```bash
openclaw reset --dry-run
```

```bash
openclaw reset --scope full
```

After a full reset, run the onboarding wizard again:

```bash
npx openclaw@latest
```

---

## Getting Help

### Check the Logs

The gateway logs contain detailed information about every action:

```bash
openclaw logs --follow
```

Filter for errors yourself, since the documented flags are `--limit`, `--max-bytes`, `--follow`, `--interval`, `--json`, `--plain`, `--no-color`, `--local-time` and `--utc`:

```bash
openclaw logs --limit 50 --plain | grep -i error
```

### Community Resources

- **GitHub Issues**: [github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues), Search for your issue or file a new one
- **Discord Community**: The OpenClaw Discord server has active support channels
- **ClawHub Forums**: [clawhub.ai/forums](https://clawhub.ai/forums), Community discussions and skill-specific help

### Filing a Bug Report

When reporting an issue, include:

1. OpenClaw version (`openclaw --version`)
2. Operating system and version
3. Node.js version (`node --version`)
4. Output of `openclaw doctor`
5. Relevant log entries (`openclaw logs --limit 50`)
6. Steps to reproduce the issue
7. Expected vs actual behavior

---

## Quick Reference: Common Fixes

| Problem | Quick Fix |
|---------|-----------|
| Agent not responding | `openclaw gateway restart` |
| API errors | Check/regenerate API key |
| Channel disconnected | Verify token, `openclaw gateway restart` |
| Skill not loading | `openclaw skills check` |
| Gateway won't start | Check port conflict: `lsof -i :3420` |
| Permission denied (macOS) | Re-grant Full Disk Access |
| Permission denied (Linux) | `sudo chown -R $USER:$USER ~/.openclaw` |
| Config corrupted | `cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json` |
| Everything broken | `openclaw doctor --fix` |
| Truly everything broken | `openclaw reset --scope full` |

---

## Next Steps

- **[Security Hardening](/docs/security-hardening)**: prevent issues caused by security misconfigurations
- **[Heartbeat & Cron](/docs/heartbeat-config)**: fix heartbeat and scheduling issues
- **[Messaging Channels](/docs/messaging-channels)**: resolve channel-specific problems
- **[Cost Optimization](/docs/cost-optimization)**: when cost limits cause unexpected behavior

## Sources

- [OpenClaw: Config](https://docs.openclaw.ai/cli/config)
- [OpenClaw: Other checks and repairs](https://docs.openclaw.ai/cli/doctor/checks)
- [OpenClaw: Skills CLI](https://docs.openclaw.ai/cli/skills)
- [OpenClaw: System](https://docs.openclaw.ai/cli/system)
- [OpenClaw: Reset](https://docs.openclaw.ai/cli/reset)
- [OpenClaw: Logs](https://docs.openclaw.ai/cli/logs)
- [OpenClaw: Security CLI](https://docs.openclaw.ai/cli/security)
- [OpenClaw: Configuration: agent heartbeat, compaction, and streaming](https://docs.openclaw.ai/gateway/config-agents/heartbeat-compaction-and-streaming)