Gateway
Troubleshooting
This is the deep runbook. Start at /help/troubleshooting for the fast triage flow first.
Command ladder
Run in this order:
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probeHealthy signals:
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.
| Page | Read it when |
|---|---|
| Updates and rollbacks | An update, downgrade, or split-brain install left the Gateway down or mismatched. |
| Skills and model providers | A skill root is skipped, or provider calls fail with 429, 403, or silent agent-run errors. |
| Agent replies and Control UI | A run fails with a storage error, no reply arrives, or the Control UI will not connect. |
| Gateway service and process | The service will not run or stay up, macOS supervision misbehaves, or memory forces an exit. |
| Config validation and probes | The Gateway rejected a config, or probe warnings appear in status and doctor output. |
| Channel delivery and tools | A channel connects but does not deliver, or a node or browser tool call fails. |
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
openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.modeWhat to check:
- 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.
Common signatures:
gateway connect failed:→ wrong URL target.unauthorized→ endpoint reachable but wrong auth.
2. Bind and auth guardrails are stricter
openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --followWhat to check:
- 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.
Common signatures:
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
openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctorWhat to check:
- Pending device approvals for dashboard/nodes.
- Pending DM pairing approvals after policy or identity changes.
Common signatures:
device identity required→ device auth not satisfied.pairing required→ sender/device must be approved.
If the service config and runtime still disagree after checks, reinstall service metadata from the same profile/state directory:
openclaw gateway install --forceopenclaw gateway restartRelated:
Related
Was this useful?
