OpenClaw secret storage and diagnostic redaction: a practical security map

June 17, 2026 · Security

A support request often begins with a simple question: can you send the OpenClaw configuration or a few log lines? The unsafe answer is to assume that a local file is harmless, or that a redaction feature makes every diagnostic artifact safe to upload.

OpenClaw's documentation takes a wider view. Anything under ~/.openclaw/, or the directory selected by OPENCLAW_STATE_DIR, may contain secrets or private data. Logs and transcripts are separate surfaces, and a support bundle can still describe the host and runtime even after payloads and credentials are removed. The storage guidance is therefore a useful starting point for an inventory, not a promise that one directory contains every possible copy.

The config file is only one surface

A SecretRef can remove an inline value from the field that points to it. It does not remove the credential from the system. The Gateway still has to resolve the value from an environment variable, file, command, plugin, or shared store, and the provider still has to use it at an egress boundary.

Before collecting diagnostics, identify the actual Gateway host, active profile, state directory, enabled channels and providers, installed plugins, and the intended audience for the report. Also check whether a credential is stored as a protected secret or as an agent-readable env value. If those answers are unclear, stop at a status summary and resolve the storage map first.

A map of normal storage paths

The same OpenClaw storage page recommends tight permissions, including mode 700 for the state directory and mode 600 for the main configuration file. Those permissions reduce accidental local access. They do not prevent a permitted process from reading a credential or a tool from printing one.

SecretRef reduces exposure, but it does not erase it

OpenClaw's shared secret store has two different behaviors. A protected secret entry is write-only after saving. Listings do not reveal it, and there is no ordinary reveal operation. An env entry is intentionally readable and can be returned by the store commands or injected as plaintext into Gateway-hosted commands. The documentation explicitly says an agent can print, transmit, or persist an env value.

This distinction changes the decision. Use an agent-readable environment value only when the workflow accepts that the command can see the credential. If the agent needs to call a provider without receiving the plaintext, the optional egress proxy can place an opaque sentinel in the subprocess environment and substitute the value immediately before an allowed HTTPS request. The proxy is default-off, requires exact host bindings, and is not a replacement for process isolation. A permitted destination can still mishandle or reflect a credential, and bytes already sent upstream cannot be recalled. These limits are described in the shared store and egress documentation.

There is also a storage tradeoff. The shared secret store keeps values unencrypted in state/openclaw.sqlite, protected by filesystem permissions. Operators who need stronger custody are directed toward external providers such as a vault or an exec-backed resolver. Moving the value out of openclaw.json changes the custody boundary; it does not remove the need to protect the resolver host and its output.

The separate OpenClaw secrets tool protects one particularly important path. The operator enters a credential through a protected prompt, and the value is written to the store without entering the chat, session transcript, tool result, or model context. A normal chat message, a pasted shell command, or a command that reads a secret file does not automatically inherit that same guarantee.

What the text redactor covers

OpenClaw's logging reference describes redaction as a set of sink-specific protections. Sensitive values are masked before text reaches console output, file logs, OTLP log records, or persisted session-transcript text. The current documentation says sensitive-value redaction is always enabled and cannot be disabled through configuration.

The matching rules are broader than a simple search for the word token. They cover registered secret values, structured credential fields, authorization headers, URL credentials, known token formats, common assignments, command-line flags, bearer headers, PEM blocks, and several payment-credential fields. OpenClaw recommends registering the actual secret values instead of relying only on field names.

Masking is not always the same as deletion. For ordinary string matches of at least 18 characters, the logging reference describes a mask that can retain the first six and last four characters. Shorter values become ***, while structured credential fields use full masks. A partial token is still a token-shaped identifier. It is not a reason to publish an otherwise private log.

Use logging.redactPatterns for a recognizable organization-specific format, such as the fictional pattern below:

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

The same reference describes this setting as a regex list that replaces the default string list while built-in structural protections remain. Verify that behavior after upgrades instead of assuming every custom configuration is additive. Test with synthetic values, and keep the test data out of production logs.

The model-facing tool path has another boundary. OpenClaw masks finalized tool-result text after middleware, including exec output and tool errors, before it enters live model context. The documentation also says that media bytes and original execution arguments remain intact. In other words, text masking does not rewrite every related artifact created by a command.

Some surfaces are treated as safety boundaries and always redact, including Control UI tool-call events, sessions_history output, diagnostics exports, provider errors, exec-approval displays, and Gateway WebSocket logs. That is useful protection, but it is still different from a promise that the underlying file, process argument, attachment, or external system never held the value.

How to prepare diagnostic output

The safest review policy starts with the smallest artifact that answers the question.

1. Prefer the supported export. For a support case, begin with openclaw gateway diagnostics export --json. The diagnostics documentation says the bundle contains a manifest, sanitized configuration shape, sanitized log summaries, redacted operational lines, and best-effort status and health snapshots. It omits or redacts chat text, prompts, instructions, webhook bodies, tool outputs, credentials, cookies, raw request and response bodies, hostnames, and local usernames.
2. Bound raw logs when the export is not enough. The logs reference supports explicit limits such as --limit and --max-bytes, as well as plain and UTC output. Use those limits for a local review. Avoid --verbose unless the incident specifically requires it, because Gateway verbose mode prints all WebSocket request and response traffic.
3. Review values, not only field names. Inspect URLs, query strings, command arguments, local paths, usernames, plugin messages, file snippets, and copied terminal output. A value can be private without matching a familiar name such as API_KEY. The storage docs warn that transcripts can contain pasted secrets and file contents, while the logging docs describe broader masking for direct dotenv reads than for arbitrary source files.
4. Separate operational facts from payloads. A reviewer may need subsystem names, provider identifiers, channel identifiers, status codes, durations, queue state, or memory readings. They usually do not need the message body, prompt, tool output, raw webhook, account identifier, or a complete transcript. Keep those categories separate when writing the ticket.
5. Run the at-rest audit separately. openclaw secrets audit --check scans for plaintext storage, unresolved references, precedence drift, duplicated store values, generated residues, and legacy material. The Secrets CLI reference also notes that sensitive provider-header detection is heuristic. The audit is useful evidence about storage; it is not a sanitizer for a log file you already collected.
6. Keep the bundle private until review is finished. OpenClaw says to treat diagnostics bundles like secrets because they still summarize local Gateway logs and host runtime state. Restrict the output file, inspect its contents locally, and share only the smallest reviewed artifact. Do not use a screenshot of an unreviewed terminal as a shortcut.

Failure paths and residual risk

A protected credential was replaced by a normal command

If a tool reads a secret file or an environment variable and prints it, the protected secrets flow no longer describes what happened. Sink redaction may mask the text in a log or tool result, but the original command arguments, file, process environment, or external destination may still matter. Do not infer that a masked line proves the value was never available to the process.

The diagnostics ZIP is clean but still too revealing

A sanitized export can omit payloads and credentials while retaining plugin identifiers, provider identifiers, channel identifiers, status codes, timings, queue state, and local stability information. Those details can reveal deployment structure or operational timing. The documentation calls the bundle useful for support, not universally safe for public publication.

A custom pattern misses a variant

Organization-specific credentials often appear in more than one representation: a header, a URL parameter, a JSON field, a command argument, or an encoded value. Add patterns for stable synthetic shapes, register actual secrets where OpenClaw supports registration, and review the result manually. Do not put the real credential into a pattern example, issue, screenshot, or test fixture.

A live credential appears in a shared artifact

At that point, the question changes from redaction to incident response. The official incident-response guidance says to assume compromise when secrets leaked. Rotate Gateway authentication, remote-client secrets, provider and API credentials, channel credentials, and model-auth material implicated by the artifact. Then review logs, transcripts, configuration changes, and plugin state before rerunning the deep audit.

The practical rule

Use a protected secret flow when the model should not receive a credential. Use a SecretRef or external provider when inline configuration is the wrong custody boundary. Use a sanitized diagnostics export when a support report is enough, and bound raw logs only when they answer a specific unanswered question. Redaction reduces accidental disclosure; it does not change who could read the original value, what a process received, or what has already left the host.

Sources

• Secrets, storage, and logs — storage paths, credential locations, workspace dotenv behavior, transcripts, logs, and filesystem permissions. Accessed 2026-09-13.
• Gateway logging — redaction sinks, masking behavior, custom patterns, tool-result handling, and WebSocket logging. Accessed 2026-09-13.
• Diagnostics export — bundle contents, omitted fields, payload handling, and privacy limits. Accessed 2026-09-13.
• Secrets CLI — protected and readable store entries, safe input paths, storage audits, and heuristic detection. Accessed 2026-09-13.
• Secrets — protected credential prompts and the boundary between stored values and model context. Accessed 2026-09-13.
• Shared secret store and egress proxy — unencrypted store values, opaque sentinels, exact host bindings, and egress limits. Accessed 2026-09-13.
• Operator incident response — containment, credential rotation, audit, and collection guidance after a leak. Accessed 2026-09-13.
• Logs — bounded log options, remote collection, and redacted error output. Accessed 2026-09-13.