diagnose-gateway

Files (1)

• SKILL.md

SKILL.md (first lines)

# Diagnose the Gateway

This playbook is read-only: no config writes, no service restarts, no `doctor --fix`, no killing listeners. Never print secret values; report only redacted SecretRef owner state. Every run ends with the observable Prove result or an exact explanation of why it could not be proven.

## Gather

```
openclaw doctor --lint
openclaw gateway status --deep
openclaw config validate
openclaw channels status
openclaw models status
openclaw channels logs --channel <id>
```

`doctor --lint` is read-only and can exit `1` for findings: read the report and continue the remaining checks. Do not substitute ordinary `doctor` or `doctor --non-interactive`; they can copy legacy config and migrate state without `--fix`.

On managed installs, bounded recent logs: `./scripts/clawlog.sh` (repo checkout) or the log path printed at gateway startup (`/tmp/openclaw/openclaw-<date>.log` by default).

Check these signatures without guessing:

- invalid config or schema errors (`config validate` names the exact key and line);
- degraded SecretRef owners — report the owner, never ids or values;
- expired or rejected channel authentication (`channels status` per account);
- `EADDRINUSE`, a second gateway listener, or service/config port mismatch (`lsof -nP -iTCP:<port> -sTCP:LISTEN`);
- gateway crash loops: read the last startup stack in the gateway log; a schema-valid config that still crashes startup is a bug — capture the stack and report it.

Correlate timestamps and identify the first owner-boundary failure.

## Mutate

Nothing. Do not change config, migrate state, or alter services. Diagnostic commands may still produce incidental logs or cache bookkeeping.

## Repair

Translate each finding into the next action, naming the responsible skill when one exists: `configure-channel`, `add-model-provider`, or `cloud-image-bake`. Recommend `openclaw doctor --fix --non-interactive` only as a separately approved step.

## Prove

Repeat the smallest read-only check that exposes the condition and record its output, for example:

```
openclaw gateway status --deep
openclaw channels status --probe
```

If access, logs, or the gateway are unavailable, report that exact blocker rather than declaring a cause.

## Report

Findings in causal order with evidence for each; current gateway/config/SecretRef/channel/port state; one recommended next skill or operator action. State explicitly that no config/service repairs or state migrations were performed.

Further reference: https://docs.openclaw.ai/gateway/troubleshooting

From openclaw/openclaw, MIT.

More from openclaw/openclaw