Command ladder
Run in this order:openclaw gateway statusshowsRuntime: running,Connectivity probe: ok, and aCapability: ...line.openclaw doctorreports no blocking config/service issues.openclaw channels status --probeshows live per-account transport status and, where supported,worksoraudit ok.
Symptom index
This page is an index. The runbook sections are documented on six pages, grouped by symptom area. Open the page that matches what you are seeing.Where each section moved
Every anchor this page used to publish is kept here, so an existing link such as/gateway/troubleshooting#gateway-rejected-invalid-config still resolves. Each entry points at
the page that now holds the content.
- After an update
- Prepared model runtime publication timeout
- Split brain installs and newer config guard
- Fix PATH
- Reinstall the gateway service
- Remove stale wrappers
- Protocol mismatch after rollback
- Skill symlink skipped as path escape
- Anthropic 429 extra usage required for long context
- Use a standard context window
- Use an eligible credential
- Configure fallback models
- Upstream 403 blocked responses
- Local OpenAI-compatible backend passes direct probes but agent runs fail
- Common signatures (local backend)
- Fix options (local backend)
- Agent run failed with a storage error
- No replies
- Dashboard control UI connectivity
- Connect / auth signatures
- Auth detail codes quick map
- Wait for connect.challenge
- Sign the payload
- Send the device nonce
- Gateway service not running
- Common signatures (gateway service)
- macOS gateway silently stops responding, then resumes when you touch the dashboard
- macOS launchd supervisor loop with duplicate gateway/node LaunchAgents
- Gateway exits during high memory use
- Gateway rejected invalid config
- What happened
- Inspect and repair
- Common signatures (invalid config)
- Fix options (invalid config)
- Gateway probe warnings
- Channel connected, messages not flowing
- Cron and heartbeat delivery
- Common signatures (cron and heartbeat)
- Node paired, tool fails
- Browser tool fails
- Plugin / executable signatures
- Chrome MCP / existing-session signatures
- Element / screenshot / upload signatures
If you upgraded and something suddenly broke
Most post-upgrade breakage is config drift or stricter defaults now being enforced.1. Auth and URL override behavior changed
1. Auth and URL override behavior changed
- If
gateway.mode=remote, CLI calls may be targeting remote while your local service is fine. - Explicit
--urlcalls do not fall back to stored credentials.
gateway connect failed:→ wrong URL target.unauthorized→ endpoint reachable but wrong auth.
2. Bind and auth guardrails are stricter
2. Bind and auth guardrails are stricter
- Non-loopback binds (
lan,tailnet,custom) need a valid gateway auth path: shared token/password auth, or a correctly configured non-loopbacktrusted-proxydeployment. - Old keys like
gateway.tokendo not replacegateway.auth.token.
refusing to bind gateway ... without auth→ non-loopback bind without a valid gateway auth path.Connectivity probe: failedwhile runtime is running → gateway alive but inaccessible with current auth/url.
3. Pairing and device identity state changed
3. Pairing and device identity state changed
- Pending device approvals for dashboard/nodes.
- Pending DM pairing approvals after policy or identity changes.
device identity required→ device auth not satisfied.pairing required→ sender/device must be approved.