OpenClaw SecretRefs: fix the plaintext-secret config warning

What a SecretRef looks like

If your agent’s own script cannot use a credential you already saved, start with Protected secret versus Agent-readable environment. Choosing how a script receives a value is a different problem from replacing plaintext in a configuration field.

{
  "source": "store",
  "provider": "default",
  "id": "TELEGRAM_BOT_TOKEN"
}

This object says where OpenClaw should resolve the credential; it contains no token itself. The SecretRef contract also supports environment, file and executable-backed sources. With the standard store defaults, the built-in store needs no extra provider definition. If you have changed the default store alias, use that alias instead.

Move a Telegram token out of the config

Run the following on the Gateway host, using the same OpenClaw state directory as the running service. Enter the existing token at the masked prompt; do not put the token in the command line or an ordinary agent message.

openclaw secrets store set TELEGRAM_BOT_TOKEN --kind secret

The current secrets CLI also accepts a protected input file or standard input via --value-file -. Secret-kind entries are write-only through the CLI; environment-kind entries are not equivalent.

Replace the token at channels.telegram.botToken with the reference object above. For an account-specific channel configuration, change the token field in that account instead. Then run:

openclaw secrets reload
openclaw secrets audit --check

Read both results, then send the Telegram bot a message and confirm its reply. An audit without plaintext findings is useful, but the round trip proves the active channel can still authenticate. Provider API keys follow the same idea at their supported credential paths; check the supported-field reference before replacing a string with an object.

Not every warning means a leaked credential

As of OpenClaw 2026.9.1, Doctor’s check also flags the llama.cpp provider’s llama-cpp-local marker in an API-key field. That marker is not a remote-service credential. Classify the value before changing it: a real bot token should move; a provider’s non-secret placeholder should not be deleted just to silence a warning.

Likewise, not every setting accepts a SecretRef. In particular, hooks.token is a string-only setting in the current webhook configuration reference. Pasting the object there can make the config invalid. The n8n webhook guide covers that separate token.

What the move does and does not protect

The built-in store keeps credentials out of ordinary configuration and refuses to reveal secret-kind entries through its read command. As of 2026.9.1, the underlying local SQLite store is not encrypted. Anyone with sufficient access to the Gateway’s files still has access to sensitive state.

Older config copies and backups may also retain the original value. Protect those alongside the current state; moving a token does not revoke it or erase old copies. If the token has actually been exposed, rotate it with its issuer and update the stored value. For many credentials, the CLI’s interactive openclaw secrets configure flow can prepare and validate a migration rather than editing each reference by hand.