> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose and fix common gateway, channel, and provider issues.

# Troubleshooting

Start here when something is not working. Most issues are diagnosed in two commands:

```bash theme={"dark"}
openclaw doctor         # config, health, and repair
openclaw status --deep  # gateway + channel probe
```

See [Doctor](https://docs.wednesdayai.dev/next/admin/doctor.md) for the full check list, and [Health checks](https://docs.wednesdayai.dev/next/admin/gateway/health-checks.md) for status commands.

## Failure signatures

Match the symptom to the likely cause before digging deeper:

| Symptom | Likely cause | First step |
| - | - | - |
| Gateway won't start, exits immediately | Unknown/invalid config key | `openclaw doctor --fix` |
| Gateway won't start, "address in use" | Port collision | `lsof -i :18789`, change port |
| Channel stopped working after an upgrade | Service on Bun or version-managed Node | `openclaw doctor` (offers Node migration) |
| WhatsApp logged out / status 409-515 | Conflicting WhatsApp Web session | Relink (see below) |
| Bot ignores DMs | `dmPolicy: "disabled"` or sender not in `allowFrom` | Check `channels.<channel>.dmPolicy` |
| Bot ignores group messages | `groupPolicy` / missing mention | Check `groups` + `requireMention` |
| "No credentials found" | Provider key not in `~/.openclaw/.env` | Add key, restart daemon |
| 429 / rate limit | Single key over quota | Add rotation keys |
| Browser WebSocket 1008 Unauthorized | Browser can't pass bearer token | Tailscale/trusted-proxy auth |
| Tool blocked unexpectedly | Sandbox or tool policy | `openclaw sandbox explain` |

## Gateway not starting

> [accordion] Port already in use
>
> ```bash theme={"dark"}
> lsof -i :18789
> ```
>
> Change the port in `~/.openclaw/openclaw.json`:
>
> ```json5 theme={"dark"}
> { gateway: { port: 18790 } }
> ```
>
> Then restart: `systemctl --user restart openclaw-gateway` (Linux) or `openclaw gateway start` (macOS/manual).

> [accordion] Unknown config keys
>
> The gateway refuses to start with unrecognised top-level keys:
>
> ```bash theme={"dark"}
> openclaw doctor --fix   # removes unknown keys, fills missing defaults
> ```
>
> Review the diff before restarting.

> [accordion] Systemd service installed but not running
>
> ```bash theme={"dark"}
> systemctl --user status openclaw-gateway
> journalctl --user -u openclaw-gateway -n 50
> systemctl --user start openclaw-gateway
> ```
>
> If it keeps crashing, run in the foreground to see the error: `openclaw gateway --port 18789`.

> [accordion] Channels broke after an upgrade (Node vs Bun)
>
> WhatsApp and Telegram require a stable system **Node**, not Bun. Version-managed Node paths (nvm, fnm, volta, asdf) can break a background service after upgrades because the service does not load your shell init.
>
> ```bash theme={"dark"}
> openclaw doctor   # warns and offers to migrate to a system Node install
> ```

## Gateway restart preflight gate

`openclaw gateway restart` (and `gateway start`) runs checks before it touches the service. When a check blocks, no restart happens — the running gateway keeps its current config. The command exits non-zero with the reason.

What the preflight checks, in order:

| Check | Blocking? | What it does |
| - | - | - |
| Service loaded | Yes (soft) | If the systemd/launchctl service is not loaded, the command reports `not-loaded` with start hints instead of restarting |
| Config validity | **Yes** | Reads a snapshot of `~/.openclaw/openclaw.json`. An invalid config blocks the restart entirely |
| Token drift | No | Compares the `OPENCLAW_GATEWAY_TOKEN` baked into the service environment against the token resolved from config. A mismatch prints a ⚠️ warning, then the restart proceeds |
| Post-restart health | **Yes** | After restarting, waits up to 60 s (500 ms × 120 attempts) for the gateway port to become healthy |

When the config validity gate blocks, the output looks like:

```text theme={"dark"}
Cannot restart Gateway: config is invalid

File: ~/.openclaw/openclaw.json
Problem:
  - <issue lines>
...
The Gateway is still running on its current config. No restart was performed.
```

Fix it with:

```bash theme={"dark"}
openclaw config validate   # see the issues without changing anything
openclaw doctor --fix      # removes unknown keys, fills missing defaults
openclaw gateway restart   # retry
```

If the post-restart health check times out, the CLI first looks for stale gateway processes (leftover PIDs from a previous run holding or competing for the port), terminates them, and retries the restart once. If it still cannot reach a healthy port within 60 s, it fails with port diagnostics — including "Gateway process is running but port is still free" when the process is up but never bound the port (startup hang, crash loop, or a very slow VM) — plus these next steps:

```bash theme={"dark"}
openclaw gateway status --deep
openclaw doctor
```

> [!NOTE]
>
> With `--json`, the preflight failures and health warnings are emitted as structured JSON (`action: "restart"`, `ok: false`, `warnings: [...]`) instead of terminal text — useful for scripts and automation.

## `openclaw` command not found

```bash theme={"dark"}
node -v         # should be v24+
npm prefix -g   # should be in your PATH
```

```bash theme={"dark"}
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
openclaw --version
```

## Channel issues

> [accordion] WhatsApp: logged out or not receiving messages
>
> ```bash theme={"dark"}
> openclaw status --deep
> ls -l ~/.openclaw/credentials/whatsapp/*/creds.json
> ```
>
> If credentials are stale or missing, relink (the phone holding the account must be online):
>
> ```bash theme={"dark"}
> openclaw channels logout --channel whatsapp
> openclaw channels login --channel whatsapp --verbose
> ```

> [accordion] WhatsApp: status codes 409-515 in logs
>
> A conflicting WhatsApp Web session is open. Close all other WhatsApp Web sessions, then relink. Status 515 auto-retries once after pairing — this is normal.

> [accordion] Telegram / Discord / Slack: bot not responding
>
> 1. Confirm the bot token is still valid (not revoked in the provider console)
> 2. `openclaw channels status --channel telegram`
> 3. Check the allowlist: `channels.telegram.allowFrom` must include the sender
> 4. `openclaw channels logs --channel telegram --follow`

> [accordion] Bot ignores me in a group
>
> 1. `groupPolicy` must be `open` or `allowlist` with the group allowlisted
> 2. The bot usually requires an @mention — set `requireMention: false` on the group to disable
> 3. Telegram: disable Privacy Mode in BotFather so the bot sees group messages
> 4. The sender must be in `groupAllowFrom` (or `allowFrom` as fallback)

> [accordion] No inbound messages from any channel
>
> 1. `openclaw gateway status` — is it running?
> 2. Check `dmPolicy` — `"disabled"` means no DM replies
> 3. Check `allowFrom`
> 4. `openclaw security audit` — open DM policies are flagged

## AI provider issues

> [accordion] No credentials found / provider not responding
>
> ```bash theme={"dark"}
> openclaw models status
> openclaw doctor
> ```
>
> If the key is in your shell but the daemon can't find it, it must be in `~/.openclaw/.env`:
>
> ```bash theme={"dark"}
> echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.openclaw/.env
> systemctl --user restart openclaw-gateway
> ```

> [accordion] Rate limit errors
>
> Configure key rotation:
>
> ```bash theme={"dark"}
> # ~/.openclaw/.env
> ANTHROPIC_API_KEYS=sk-ant-key1,sk-ant-key2
> ```
>
> The gateway retries with the next key on 429 responses.

> [accordion] Anthropic: 'credential only authorized for Claude Code'
>
> Use an API key instead of the subscription setup-token:
>
> ```bash theme={"dark"}
> echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.openclaw/.env
> systemctl --user restart openclaw-gateway
> ```

> [accordion] 'Model is not allowed'
>
> If `agents.defaults.models` is set, it is the allowlist for `/model`. Either add the model, clear the allowlist, or pick one from `openclaw models list`.

## Control panel / web UI

> [accordion] Control panel not loading
>
> 1. `openclaw gateway status`
> 2. Open `http://127.0.0.1:18789/` directly — if that works but another URL doesn't, check your remote access config
> 3. `openclaw dashboard` opens the correct URL automatically

> [accordion] WebSocket 1008 Unauthorized from browser
>
> Browsers can't pass bearer tokens in WebSocket handshakes. Use Tailscale Serve with `gateway.auth.allowTailscale: true`, [trusted-proxy auth](https://docs.wednesdayai.dev/next/admin/gateway/authentication.md), or connect via the macOS app / CLI.

## Tools blocked unexpectedly

If an agent says a tool is blocked, inspect the effective policy:

```bash theme={"dark"}
openclaw sandbox explain
openclaw sandbox explain --json
```

This prints the sandbox mode, whether the session is sandboxed, the effective tool allow/deny and where it came from, and the elevated gates. See [Sandboxing](https://docs.wednesdayai.dev/next/admin/sandboxing.md).

## Logs and diagnostics

```bash theme={"dark"}
openclaw logs --follow
openclaw logs --json
journalctl --user -u openclaw-gateway -f      # Linux
openclaw channels logs --channel whatsapp --follow
```

For more detail:

```bash theme={"dark"}
OPENCLAW_LOG_LEVEL=debug openclaw gateway --port 18789
```

## Still stuck?

```bash theme={"dark"}
openclaw doctor --deep   # comprehensive scan including extra gateway installs
```

Read the output carefully — doctor usually identifies the fix. If not:

* Check [GitHub Issues](https://github.com/ExpansionX/WednesdayAI-core/issues)
* Ask in [Discord](https://discord.gg/clawd)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.