# OpenClaw Gateway Diagnostic Routine

## Step-by-Step Troubleshooting

When OpenClaw gateway communication fails, follow this ordered diagnostic:

### 1. Health Check
```bash
openclaw health
```
Look for: Telegram configured, Gateway event loop status, Agents listed.

### 2. Gateway Status
```bash
openclaw gateway status
```
Check: Service enabled, port binding, runtime status, connectivity probe.

### 3. API Health
```bash
curl -s http://127.0.0.1:18789/health
```
Expected: `{"ok":true,"status":"live"}`

### 4. Process Check
```bash
ps aux | grep openclaw | grep -v grep
```
Should show openclaw and openclaw-mcp processes.

### 5. If Gateway Stopped/Restarted
```bash
openclaw gateway start    # Repairs service if version mismatch
openclaw sessions cleanup  # Fix hung sessions after restart
sleep 3
openclaw agent -m "Test" --agent main  # Retry
```

### 6. Session Cleanup
```bash
openclaw sessions cleanup
```
After restart, sessions may be corrupted. This fixes it.

### 7. ACP Scope Approval
```bash
openclaw acp client
```
If "scope upgrade pending approval" — check `openclaw approvals get`.

### 8. Version Mismatch
If `openclaw gateway start` reports "service was installed by [older version]" — the systemd service auto-repairs.

## Common Error Table

| Symptom | Likely Cause | Fix |
|---------|-------------|-----|
| `openclaw agent` hangs 120s | Gateway crashed or sessions stuck | `openclaw sessions cleanup` + restart gateway |
| `openclaw acp client` fails with "scope upgrade pending approval" | ACP scope not approved | Check `openclaw approvals get` |
| `openclaw gateway start` reports version mismatch | Service file outdated | `openclaw gateway start` auto-repairs |
| `curl` returns connection refused | Gateway not running | `openclaw gateway start` |
| `openclaw agent --to telegram:...` hangs | Wrong parameter | Use `--agent main` instead |
| Gateway event loop "degraded" | High CPU utilization | Normal if under load — check `openclaw health` |