Skip to main content
Agent skill

Diagnose Gateway

Diagnose Gateway, config, secrets, channels, and port failures with read-only one-liners.

Get started

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?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/diagnose-gateway
# Save SKILL.md to ~/.claude/skills/diagnose-gateway/SKILL.md
  1. 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.
  2. 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.
  3. 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.

Starter prompt
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.