A SecretRef is a pointer to a credential source, not a new password. OpenClaw supports env, file, exec, and store sources for supported credential surfaces. That distinction matters for recurring workflows: the agent can keep using the credential after migration, while the human still needs to know where the original value lives and how to rotate it.
Decide where the human will recover the secret
| Source | Human recovery path | Operational note |
|---|---|---|
| External vault via exec | Vault app or CLI | Keep vault access independent of the agent |
| File | Protected host file | Back up and restrict host access |
| Environment | Environment owner | Audit inherited process exposure |
| OpenClaw store | Replace or rotate value | Protected values are write-only in the UI |
The OpenClaw store is convenient for team-scoped values, but it should not be your only human copy of an irreplaceable credential. Its Protected secret mode is write-only in Settings. Agent-readable environment entries are deliberately different: Gateway-hosted commands may receive their plaintext and may print or persist it. Choose protected mode for credentials unless a command truly needs the raw value.
Migrate one workflow at a time
- Inventory the exact credential consumers, including model, channel, plugin, and scheduled job dependencies.
- Choose the credential source and verify the human recovery or rotation path.
- Configure the SecretRef for each supported consumer; do not assume one ref covers every surface.
- Run the secrets audit and resolve plaintext residues before calling migration complete.
- Reload secrets, then run a bounded smoke test of the affected workflow.
- Inspect the automation run and its business artifact, not just Gateway liveness.
OpenClaw documents `openclaw secrets audit --check`, `openclaw secrets configure --apply`, and `openclaw secrets reload` as separate operations. An audit can find old plaintext in config or generated files after the new ref works. Reload can retain a last-known-good snapshot for some unchanged references, so a passing unrelated request does not prove the changed credential is healthy. Exercise the actual owner that uses it.
What to record in the runbook
- Secret name and source, never the value.
- Who can rotate it and where the replacement is entered.
- Which scheduled jobs depend on it.
- The smoke-test command and expected non-secret artifact.
- The last successful test date and rollback or repair path.
A secret migration is done when the old plaintext is removed, the intended owner can resolve the ref, a real workflow completes, and a human can still rotate the credential later. Moving the string out of one JSON file is only the first step.
Frequently asked questions
Can I reveal a protected OpenClaw store secret later?
No. Treat protected store values as write-only. Keep a human-managed vault copy or plan to rotate the value.
Does a SecretRef automatically remove old plaintext?
No. Audit the supported credential surfaces and remove residues after applying the ref.
What should I test after a credential migration?
Test the specific model, plugin, channel, or automation that uses the credential, then verify its expected output artifact.