Diagnose Gateway
Diagnose Gateway, config, secrets, channels, and port failures with read-only one-liners.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Diagnose Gateway when an AI agent needs a reusable SKILL.md workflow for this job: Diagnose Gateway, config, secrets, channels, and port failures with read-only one-liners.
When not to use it
Skip Diagnose Gateway when the task is outside the creativity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/diagnose-gateway # Save SKILL.md to ~/.claude/skills/diagnose-gateway/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/diagnose-gateway/SKILL.md. For a shared project, commit the folder at .claude/skills/diagnose-gateway/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Diagnose Gateway skill for this task: Use Diagnose Gateway when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
68/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 68/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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
Intended uses
- Use Diagnose Gateway when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.