How to Create an OpenClaw Diagnostics Bundle

A diagnostics bundle is the fastest way to turn a vague OpenClaw failure into a useful bug report. Instead of pasting random log fragments, the Gateway can export a local zip with sanitized health, status, config shape, log summaries, and stability events. It is designed to be shareable, but still worth reviewing before it leaves your machine.

30-second answer

Run openclaw gateway diagnostics export. Use --output openclaw-diagnostics.zip if you want a specific file path, or --json for automation. The export includes a human summary, machine-readable diagnostics, a manifest, sanitized config shape, redacted log summaries, best-effort health/status snapshots, and the newest stability bundle when available.

When this pays off

Use this after crashes, restart loops, stuck sessions, memory pressure, oversized payloads, channel failures, or confusing model/runtime behavior. For business operators, this matters because debugging time is revenue time. A clean bundle lets support or a teammate inspect the right operational facts without needing access to your private messages or credentials.

Operator runbook

1. Start with the direct CLI export. Run openclaw gateway diagnostics export from the Gateway host. If the Gateway is unhealthy, the command is still useful because it can collect local logs, config shape, and the latest stability bundle even when live status or health calls fail.
2. Choose an output path for repeatable workflows. The documented --output option writes the zip where you want it. For CI, automation, or support portals, use --json so your script can read the generated path and manifest details without scraping human text.
3. Increase log bounds only when needed. Options such as --log-lines and --log-bytes let you include more sanitized history. Use them for intermittent issues, but do not blindly max them out. Bigger bundles are slower to review and may include more operational metadata than the bug needs.
4. Use the chat command for real conversation failures. Owners can send /diagnostics with a short note. OpenClaw asks for explicit exec approval and keeps group chats from receiving the private diagnostic details. That is safer than posting technical traces into a shared room.
5. Review the privacy model before sharing. The docs say payloads, prompts, tool outputs, credentials, cookies, raw account/message identifiers, hostnames, and local usernames are omitted or redacted. Still, treat the bundle like sensitive operational data until you have inspected the summary and manifest.
6. Attach the whole zip, not screenshots. The bundle contains summary.md, diagnostics.json, manifest.json, and stability data that tools can parse. Screenshots lose structure, miss context, and often expose more UI detail than a sanitized bundle.

Verification

The export command should print a written zip path. Open the zip locally and confirm summary.md and manifest.json exist. If you used --json, parse the output and confirm the path exists on disk. For a bug report, include the issue note, OpenClaw version, reproduction steps, and the diagnostics zip rather than mixing several partial evidence sources.

Common mistakes

Do not approve diagnostics through a broad allow-all rule just to save a click. The docs call for one explicit exec approval in chat. Do not paste raw logs when a sanitized export exists. And do not assume redaction means public; operational metadata can still reveal plugin names, modes, and runtime shape.

Turn it into a repeatable operating system

The OpenClaw Playbook treats diagnostics as part of production discipline. When do you export, where do you store bundles, who is allowed to read them, and what checklist turns a support artifact into a fix? Those routines are what make an AI gateway maintainable instead of mysterious.

Before rollout

Before rollout, decide where diagnostics bundles are stored, how long they are retained, and who can share them externally. A bundle is safer than raw logs, but it is still operational evidence. Treat it like a support artifact with an owner, ticket link, and deletion path.