OpenClaw diagnostics: collect a safe Gateway support bundle
OpenClaw diagnostics is the right first step when a Gateway has failed, stalled, or restarted and you need evidence without dumping chat history or credentials into a support ticket. Run openclaw gateway diagnostics export, review the resulting ZIP locally, then share only the bundle that matches the incident. It combines sanitized status, health, log, configuration-shape, and stability information so a report starts with facts rather than a guess about the last error.
A restart is often the point where teams lose the useful context. The process comes back, the original symptom has vanished, and someone starts copying fragments from a terminal. OpenClaw’s diagnostics path is meant to preserve a bounded operational record instead. The v2026.7.1 release also added a stable repair path for repeatedly failing Gateways, which makes captured evidence more useful than repeatedly restarting the same service.
Contents
- What an OpenClaw diagnostics bundle contains
- Use the smallest diagnostic command that answers the question
- Review before you share
- Diagnose the failure layer before changing the system
- FAQ
What an OpenClaw diagnostics bundle contains
The export is a local ZIP built for a support or incident handoff. It can include a human-readable summary, machine-readable diagnostics, a manifest, sanitized configuration shape, Gateway status and health snapshots, sanitized log metadata, and the latest persisted stability bundle when one exists.
| Artifact | What it helps answer | What it should not become |
|---|---|---|
summary.md | What happened at a glance | A replacement for the original incident report |
diagnostics.json | Structured status, health, configuration, log, and stability evidence | A raw transcript archive |
manifest.json | Which files were included | Proof that every local state file was inspected |
| Status and health snapshots | Whether the Gateway and channels were reachable at collection time | Evidence that a specific user request completed |
| Sanitized logs and stability data | Startup, liveness, queue, payload-size, and recovery signals | A place for message text, tokens, cookies, or API keys |
OpenClaw’s documentation says the export omits or redacts chat text, prompts, webhook bodies, tool outputs, credentials, API keys, cookies, secret values, raw request or response bodies, account identifiers, message identifiers, raw session identifiers, hostnames, and local usernames. That is a useful default, not permission to attach the bundle blindly to a public issue. The bundle still describes local runtime state and deserves a quick review.
For the wider distinction between a reachable control plane and an agent that can actually complete work, see AI agent Gateway health. Health can look fine while a specific route, approval, or queued task still needs attention.
Use the smallest diagnostic command that answers the question
Start with a read-only health check when you only need to know whether the running Gateway is available. Use an export when you have a reproducible failure, a restart loop, or a support handoff that needs more than one screen of output.
# Quick, local Gateway summary
openclaw status
# Force a live health probe and print connection details
openclaw health --verbose
# Create a local support bundle
openclaw gateway diagnostics export
# Ask for machine-readable export metadata in automation
openclaw gateway diagnostics export --jsonThese commands have different jobs. openclaw status summarizes the local system. openclaw health --verbose forces a live probe and reports Gateway connection details. The diagnostics export collects the supporting evidence that remains useful after the immediate state changes.
If the Gateway has already exited, the export can still collect local logs, configuration shape, and the latest stability bundle when they are available. That matters for failures that disappear on restart. The stability recorder persists the newest snapshot after fatal exits, shutdown timeouts, and restart startup failures; inspect it with openclaw gateway stability --bundle latest before deciding that the only answer is another restart.
Do not turn every routine monitor into an agent request. OpenClaw recommends the dedicated GET /health endpoint for external uptime checks. Calling /v1/chat/completions for a simple liveness probe creates an agent session and can consume model work for no diagnostic value.
Review before you share
A support bundle should answer a narrow question: what was the Gateway doing when the incident occurred? Make the handoff useful by adding a short operator note outside the ZIP:
- State the symptom in plain language, including when it began.
- Record the affected channel, Gateway profile, or task type without pasting message content.
- Say whether the Gateway was restarted, and when.
- Attach the reviewed diagnostics bundle and identify the command that created it.
- Keep the original bundle locally until the issue is resolved.
The command can write a chosen path when you need an incident folder:
openclaw gateway diagnostics export --output openclaw-diagnostics.zipKeep that output out of a repository and out of a shared downloads folder. A sanitized bundle has fewer secrets than raw logs, but it can still reveal provider IDs, channel configuration state, timing, queue state, memory readings, and the shape of the local runtime. For the wider design question of which surfaces are allowed to record a credential at all, see keeping diagnostics from leaking credentials.
For recurring jobs, the same principle applies: preserve the run result and the failure boundary, then decide whether a retry is safe. OpenClaw cron jobs are easier to repair when a failed run has a clear owner and a bounded retry policy rather than an unexplained rerun.
Diagnose the failure layer before changing the system
A useful bundle does not remove the need to reason about the fault. It gives you a better starting point. Work from the narrowest layer that matches the symptom.
| Symptom | First check | Avoid doing first |
|---|---|---|
| Gateway is unreachable | openclaw gateway status, then openclaw health --verbose if reachable | Changing the model or resending the original task |
| A channel is silent | openclaw channels status --probe and the health snapshot | Assuming stored sessions prove live channel connectivity |
| Gateway keeps restarting | openclaw gateway stability --bundle latest, then diagnostics export | Repeating an unbounded restart loop |
| A task ended strangely after tool work | Review the task and diagnostic timestamps | Re-running a side effect before checking whether it already happened |
| A startup repair fails on a host path | Capture diagnostics, then inspect the specific startup error | Broad permission changes that conceal the cause |
The last row is deliberately cautious. A filesystem or service failure can tempt an operator into a broad repair. The safer approach is to retain the evidence, identify the named path or service owner, and apply the smallest fix. The OpenClaw WSL permission errors guide is an example of why an EROFS condition and an overly broad permission repair should not be treated as the same incident.
This is also good GEO structure: a direct answer, a command ladder, and a symptom table make the page easy to extract without turning it into a vague list of best practices. More importantly, they make a midnight incident less dependent on memory.
FAQ
What does OpenClaw diagnostics export?
OpenClaw diagnostics export creates a local ZIP with a summary, structured diagnostics, manifest, sanitized configuration shape, sanitized log information, status and health snapshots, and the latest stability bundle when available. It is designed for troubleshooting and support handoffs rather than raw transcript collection.
Does an OpenClaw diagnostics bundle contain API keys or chat messages?
The documented privacy model omits or redacts chat text, prompts, tool outputs, credentials, API keys, cookies, secret values, raw request and response bodies, and several identifiers. Review the bundle before sharing because it still contains operational metadata about the local Gateway.
When should I use openclaw health instead of diagnostics export?
Use openclaw health for a current Gateway health snapshot, especially with --verbose when you need a live probe. Use diagnostics export when an incident needs a reviewable handoff, when the service restarted, or when you need logs, configuration shape, and stability evidence together.
Can diagnostics help after a Gateway crash?
Often, yes. The export can collect local logs, configuration shape, and the latest persisted stability bundle even when live status and health calls fail. Its usefulness depends on what was available locally at collection time.
Keep the evidence, then change one thing
OpenClaw diagnostics gives an operator a better incident record than a copied stack trace or a hopeful restart. Capture the bundle, review it, identify whether the fault is reachability, channel readiness, startup, queue state, or task ownership, and change one thing at a time. That preserves the evidence needed to tell a recovery from a repeated failure.
Sources: