Diagnostics Export: Create Gateway Diagnostic Bundles for Bug Reports

OpenClaw can generate a local diagnostics .zip archive for troubleshooting: it contains sanitized Gateway status, health data, logs, configuration structure, and recent stability events without payload content.

Treat a diagnostics bundle as sensitive material until you have reviewed it. Payloads and credentials are intentionally removed, but the archive still contains a summary of local Gateway logs and host-level runtime information.

Quick start

openclaw gateway diagnostics export

Displays the file path of the created zip. Specify where to save it:

openclaw gateway diagnostics export --output openclaw-diagnostics.zip

For use in scripts:

openclaw gateway diagnostics export --json

Chat command

Owners can use /diagnostics [note] in any chat to request a single Gateway export formatted as a support report ready to copy and paste:

1. Send /diagnostics, optionally including a brief message (/diagnostics bad tool choice).
2. OpenClaw sends a header and asks for explicit execution approval. That approval triggers openclaw gateway diagnostics export --json. Do not approve diagnostics through a catch-all rule.
3. Once approved, OpenClaw responds with the local bundle path, a manifest summary, privacy notes, and relevant session identifiers.

In group conversations, an owner can still invoke /diagnostics, but OpenClaw delivers the export result, approval requests, and Codex session or thread details to the owner in a private message. The group only sees a short note that diagnostics were sent privately. If no private owner channel is available, the command fails safely and tells the owner to run it from a direct message.

When the active session uses the native OpenAI Codex harness, the same execution approval also permits uploading OpenAI feedback for the Codex threads OpenClaw is aware of. That upload is separate from the local Gateway zip and occurs only for Codex harness sessions. The approval prompt states that approving also sends Codex feedback, without listing Codex session or thread identifiers. After approval, the response lists channels, OpenClaw session IDs, Codex thread IDs, and local resume commands for the threads sent to OpenAI. Refusing or ignoring the approval skips the export, the Codex feedback upload, and the Codex ID list.

This makes the Codex debugging cycle short: notice unexpected behavior in a channel, run /diagnostics, approve once, share the report, then execute the printed codex resume <thread-id> command locally if you want to examine the thread yourself. See Codex harness.

What the export contains

• summary.md: a human-readable overview meant for support.
• diagnostics.json: a machine-readable summary covering config, logs, status, health, and stability data.
• manifest.json: export metadata and a file listing.
• Sanitized config structure and non-secret configuration values.
• Sanitized log summaries and recent redacted log entries.
• Best-effort Gateway status and health snapshots.
• stability/latest.json: the most recent persisted stability bundle, if it exists.

The export remains useful even if the Gateway is unhealthy: when status or health requests fail, local logs, config structure, and the latest stability bundle are still collected when available.

Privacy model

Included: subsystem names, plugin IDs, provider IDs, channel IDs, configured modes, status codes, durations, byte counts, queue state, memory readings, sanitized log metadata, redacted operational messages, config structure, and non-secret feature settings.

Excluded or redacted: chat text, prompts, instructions, webhook bodies, tool outputs, credentials, API keys, tokens, cookies, secret values, raw request or response bodies, account IDs, message IDs, raw session IDs, hostnames, and local usernames.

When a log message appears to contain user, chat, prompt, or tool payload text, the export only records that a message was removed along with its byte count.

Stability recorder

By default, when diagnostics are enabled, the Gateway records a bounded, payload-free stability stream. It captures operational facts, not content.

The same heartbeat also checks liveness when the event loop or CPU appears saturated, producing diagnostic.liveness.warning events that include event-loop delay, event-loop utilization, CPU-core ratio, counts of active, waiting, and queued sessions, the current startup or runtime phase (when known), recent phase durations, and bounded work labels. These become Gateway warn-level log entries only when work is waiting or queued, or when active work overlaps with sustained event-loop delay. Otherwise they log at debug. Idle liveness samples are still recorded as diagnostic events but never trigger a warning on their own.

Startup phases emit diagnostic.phase.completed events with wall-clock and CPU timing. Stalled embedded-run diagnostics mark terminalProgressStale=true when the last bridge progress appeared terminal (for example a raw response item or response-completion event) but the Gateway still considers the embedded run active.

Inspect the live recorder:

openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --json

Inspect the most recent persisted bundle after a fatal exit, shutdown timeout, or restart startup failure:

openclaw gateway stability --bundle latest

Create a diagnostics zip from the most recent persisted bundle:

openclaw gateway stability --bundle latest --export

Persisted bundles are stored under ~/.openclaw/logs/stability/ when events exist.

Useful options

openclaw gateway diagnostics export \
  --output openclaw-diagnostics.zip \
  --log-lines 5000 \
  --log-bytes 1000000

Disable diagnostics

Diagnostics are turned on by default. To disable the stability recorder and diagnostic event collection:

{
  diagnostics: {
    enabled: false,
  },
}

Disabling diagnostics reduces the level of detail in bug reports but does not affect normal Gateway logging.

Memory pressure events record RSS, heap, threshold, and growth information (rss_threshold, heap_threshold, rss_growth) without performing a file-system scan or writing a pre-OOM snapshot.

Related

• Health checks
• Gateway CLI
• Gateway protocol
• Logging
• OpenTelemetry export - a separate flow for streaming diagnostics to a collector