diagnose-gateway

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

388k|81.5k|Updated Nov 24, 2025
One-click install
npx skills add https://github.com/openclaw/openclaw --skill diagnose-gateway
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnose-gateway
Source: https://github.com/openclaw/openclaw/tree/main/custodian-skills/diagnose-gateway
Command: npx skills add https://github.com/openclaw/openclaw --skill diagnose-gateway

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Operators hit opaque failures in OpenClaw Gateway deployments—config schema errors, expired channel auth, port conflicts, SecretRef degradation, or crash loops—and need a safe, read-only way to pinpoint the root cause without changing state or leaking secrets.

Core Features & Use Cases

  • Read-only diagnostic playbook: Runs openclaw doctor, gateway status --deep, config validate, channels status, and models status to surface concrete failure signatures.
  • Evidence correlation: Identifies invalid config keys, degraded SecretRef owners, rejected channel authentication, EADDRINUSE collisions, and gateway crash stacks without printing secret values.
  • Use Case: A team gateway stops accepting messages after a config change. Run this skill to determine whether the failure stems from a schema error, an expired channel token, or a port conflict, then route the fix to the appropriate repair skill.

Quick Start

Run the diagnose-gateway skill to perform a read-only health check on the OpenClaw Gateway and report the first owner-boundary failure with evidence.

Frequently Asked Questions about diagnose-gateway

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I troubleshoot OpenClaw Gateway failures without restarting services?

Run `openclaw doctor --non-interactive`, `openclaw gateway status --deep`, and `openclaw config validate` to surface schema errors, port conflicts, and channel auth issues. The diagnose-gateway skill sequences these read-only probes and reports findings without restarting listeners.

What causes EADDRINUSE errors on the OpenClaw Gateway port?

EADDRINUSE occurs when another process holds the configured port or a second gateway listener is already running. Use `lsof -nP -iTCP:<port> -sTCP:LISTEN` to identify the conflicting process and compare the service port against the config port.

How do I check SecretRef owner state without exposing secret values?

Run `openclaw channels status` and `openclaw models status` to view SecretRef owner metadata. The diagnose-gateway skill reports only the owner identifier and degraded state, never the underlying secret ids or values.

Why does the OpenClaw Gateway crash loop after a config change?

A schema-valid config that still crashes startup indicates a gateway bug. Capture the last startup stack from the gateway log at `/tmp/openclaw/openclaw-<date>.log` and report it; the diagnose-gateway skill flags this as a non-config crash signature.

Can I run doctor --fix from the diagnose-gateway skill?

No. The skill is strictly read-only and never invokes `doctor --fix`, writes config, or restarts listeners. It only recommends `openclaw doctor --fix --non-interactive` as a separately approved follow-up step.