How to collect bounded OpenClaw logs after a delivery failure without leaking credentials

May 17, 2026 · Tutorial

The message never arrived. The Gateway still says it is running. The easy response is to copy the whole log directory and send it to whoever is helping. That is also how an ordinary delivery incident becomes a credential-handling incident.

OpenClaw gives operators a smaller path: a pasteable status summary, a live channel probe, a capped log tail, and an optional diagnostics archive. The current security documentation still warns that logs may contain tool summaries, errors, and URLs, while transcripts can contain pasted secrets, file contents, command output, and links. Redaction is a protection layer, not permission to share raw state.

What the packet should answer

A useful delivery report should let another operator place the failure in the Gateway path without receiving the message body or a secret. Record:

• which Gateway profile and host were involved;
• whether the Gateway was reachable and healthy;
• which channel and account were probed;
• the UTC time of one reproduction attempt;
• the result, error code, event identifier, or attempt age when OpenClaw exposes one.

This separates transport failure from policy failure and from an agent run that completed without a visible reply. It also gives the reader a stopping point. A bounded packet is easier to inspect than a complete day of activity.

Prepare a small evidence workspace

Use a directory outside a Git working tree when possible. If you must work inside one, make sure the directory cannot be committed accidentally and restrict its permissions before collecting anything.

EVIDENCE_DIR=./openclaw-evidence-2026-05-17
mkdir -p $EVIDENCE_DIR
chmod 700 $EVIDENCE_DIR

Write down the profile, channel, account, and UTC start time in a short text note. Do not put a bot token, Gateway token, provider key, cookie, or password in that note. OpenClaw’s secrets guidance says never to put plaintext credentials in commands, arguments, URLs, logs, or chat.

For a proposed reproduction, use one harmless message in a private test channel or an account where a duplicate reply has no consequence. Do not repeatedly retry an outbound action merely to create more logs. Repeated sends can change the incident you are trying to understand.

Start with health summaries

Run the read-only summaries first. They provide context before you look at a log line.

openclaw status --all
openclaw health --json
openclaw gateway status
openclaw channels status --probe --channel <channel>

The health-check documentation marks openclaw status --all as read-only and safe to paste for debugging. It also distinguishes the broader status view from the live health and channel checks. openclaw gateway status should show a running runtime, successful connectivity, and a capability line when the Gateway is healthy.

channels status --probe is the important channel step. On a reachable Gateway, it can report transport state and probe results such as works, probe failed, audit ok, or audit failed. If the Gateway cannot be reached, the command falls back to configuration summaries. That fallback is useful, but it is not proof that the channel is live.

Save the output locally if another operator needs the exact values:

openclaw status --all > $EVIDENCE_DIR/status.txt
openclaw health --json > $EVIDENCE_DIR/health.json
openclaw channels status --probe --channel <channel> > $EVIDENCE_DIR/channel-probe.txt

Review these files before sharing them. The documentation calls the status output pasteable, not universally private in every installation or extension.

Capture a bounded log slice

OpenClaw’s CLI reads Gateway file logs over RPC and works in remote mode. The default log file is a daily JSONL file under /tmp/openclaw/; named profiles use a profile-specific filename, and logging.file can change the destination. The active file rotates at a configured size and keeps numbered archives.

Use explicit limits even though the CLI already documents defaults of 200 lines and 250,000 bytes:

openclaw logs --plain --utc --limit 200 --max-bytes 250000 > $EVIDENCE_DIR/gateway.log.txt 2> $EVIDENCE_DIR/gateway.stderr.txt

--plain removes terminal styling and --utc makes timestamps easier to compare across machines. The byte limit controls how much of the log file is read. It does not make every field safe to publish.

When the failure needs a live reproduction, start a short tail, send one test message, then stop the tail:

openclaw logs --follow --plain --utc

Do not add --verbose casually. OpenClaw documents normal WebSocket logging as a narrow stream of errors, slow calls, and parse errors. Verbose mode prints all WebSocket request and response traffic. Even with redaction, that is more context than a delivery report normally needs.

There is a subtle remote-mode limit. An implicit local Gateway connection can fall back to the configured file log in some failure cases. An explicit --url target does not use that fallback and may require an explicit token. Prefer the configured target for collection. Never paste a token into a command line, URL, or support transcript just to make a remote tail work.

Add channel-specific evidence

If the problem is isolated to one connector, use the channel log surface instead of widening the capture:

openclaw channels logs --channel <channel> --lines 80

The channels CLI reference documents the positive line limit and channel filtering. Keep the result local until you have checked the values. A channel-specific view reduces volume, but it does not turn arbitrary plugin output into safe public data.

For an inbound event that may have exhausted its retry policy, inspect the dead-letter list in text mode:

openclaw channels dead-letters list --channel telegram --account default

The text view reports event identifiers, failure reasons, attempt counts, and failure ages. The same command with --json can include the retained payload and metadata. That JSON form may be useful for local diagnosis, but it is the wrong default for a shared report. Use an explicit account name in multi-account installations. Do not pass an empty shell variable and assume OpenClaw will choose the account you intended.

Do not use stored session rows as proof that a provider socket is healthy. OpenClaw’s health and channel documentation separates conversation state from live channel connectivity.

Prefer a local diagnostics bundle when one file is needed

For a support case, OpenClaw can create a local ZIP containing sanitized Gateway status, health, log summaries, config shape, and recent payload-free stability events:

openclaw gateway diagnostics export \\
  --output $EVIDENCE_DIR/openclaw-diagnostics.zip \\
  --log-lines 200 \\
  --log-bytes 250000

The diagnostics export documentation says the export has bounded log flags. Its defaults are larger than this example, so set the limits deliberately for a delivery incident. If the Gateway has crashed or failed during startup, keep the stability bundle. If this is a normal channel failure and the extra crash context is unnecessary, --no-stability-bundle is an available reduction.

The export keeps operational facts such as subsystem names, provider identifiers, status codes, durations, queue state, and sanitized metadata. It omits or redacts chat text, prompts, tool outputs, credentials, cookies, raw request and response bodies, hostnames, usernames, and several identifiers. It can still summarize local runtime state, so the documentation says to treat the ZIP like a secret until it has been reviewed.

Run the shell export when you want a local file. The chat command /diagnostics has a different approval path. In a native Codex harness session, the same approval can also cover a feedback upload. That is a separate decision from creating a local Gateway archive.

Review the packet before sharing

First inspect the archive’s file list without extracting it into a broad directory:

unzip -l $EVIDENCE_DIR/openclaw-diagnostics.zip

For a local review, extract it into another directory with restrictive permissions. Then run a filename-only screening pass so the terminal does not print possible secret values:

rg -l -i 'api[_-]?key|token|secret|password|authorization|cookie|bearer|private key|https?://[^[:space:]]+@' $EVIDENCE_DIR

This is a screening aid, not a proof of safety. It can miss an organization-specific token and it can flag harmless words. OpenClaw’s logging documentation says built-in sensitive-value masking is always enabled and supports deployment-specific logging.redactPatterns. It also says to register actual secrets rather than relying only on field names.

If your environment has a recognizable internal token shape, add a pattern for that shape before the next incident. Keep the example fictional and do not put the secret itself in configuration:

{
  logging: {
    redactPatterns: ['corp-[A-Za-z0-9]{32}']
  }
}

Custom patterns are a second line of defense. They do not remove the need to inspect URLs, query parameters, account names, internal hostnames, user messages, and file paths. If a real credential appears in a log, transcript, archive, terminal capture, or command history, stop the transfer. Rotate the affected credential and collect a new packet after the replacement is active. OpenClaw’s incident-response guidance treats leaked secrets as a reason to rotate Gateway, remote-client, provider, and channel credentials.

A closed GitHub issue opened on March 11, 2026 reported a custom email-redaction pattern failing on OpenClaw v2026.3.11. The page does not establish current behavior or identify a fix version. It is historical evidence for a cautious rule: never treat a redaction feature as permission to upload an unreviewed transcript.

Read failures without overreading them

The general troubleshooting runbook places status, Gateway status, logs, doctor, and channel probes in a command ladder. Use it to classify the layer, then stop collecting once the report answers the support question. If the Gateway never reached its normal logger, host supervisor logs may be needed, but those files can contain startup paths and command details. Apply the same review process.

Define the stop condition

A delivery-failure packet is ready when it contains the profile and time window, health summaries, the affected channel probe, a short channel or Gateway log slice, and a reviewed diagnostics archive if one was requested. It should not contain a full transcript, environment dump, resolved configuration, raw webhook body, provider response, token, cookie, or unreviewed terminal screenshot.

This process does not guarantee a root cause. It gives another operator enough evidence to distinguish an unreachable Gateway from a failed probe, a blocked channel, an exhausted retry, or a reply that never reached its destination. The useful boundary is small: collect what answers the question, inspect it locally, and stop before diagnosis becomes another way to export credentials.

Sources

1. OpenClaw Docs: Logs. Accessed 2026-09-13.
2. OpenClaw Docs: Gateway logging. Accessed 2026-09-13.
3. OpenClaw Docs: Health checks. Accessed 2026-09-13.
4. OpenClaw Docs: Channels CLI. Accessed 2026-09-13.
5. OpenClaw Docs: Diagnostics export. Accessed 2026-09-13.
6. OpenClaw Docs: Secrets, storage, and logs. Accessed 2026-09-13.
7. OpenClaw Docs: Secrets. Accessed 2026-09-13.
8. OpenClaw Docs: Troubleshooting. Accessed 2026-09-13.
9. OpenClaw Docs: Operator incident response. Accessed 2026-09-13.
10. OpenClaw GitHub issue #42982: redact logging not working properly. Accessed 2026-09-13.