#What is SecretRef and how does it work?

1 messages · Page 1 of 1 (latest)

forest linden
#

What is SecretRef and how does it work? Can I use it for storing provider auth keys?

undone shoreBOT
plain pierBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

undone shoreBOT
ancient fableBOT
#

SecretRef is basically a pointer to a secret, not the secret itself.

How it works:

  • You put a ref object in config, like:
    { source: "env", provider: "default", id: "OPENAI_API_KEY" }
  • OpenClaw resolves that at startup or openclaw secrets reload
  • The resolved value lives in the in-memory runtime snapshot
  • If an active SecretRef cannot be resolved, startup/reload fails fast instead of silently running half-broken

Supported sources:

  • env
  • file
  • exec (good for 1Password, Vault, custom resolver scripts)

Yes, you can use it for provider auth keys, with an important distinction:

#
  • Yes for static API keys and tokens, including:
    • models.providers.*.apiKey
    • auth-profiles.json via keyRef / tokenRef
    • various channel tokens and gateway token/password
  • No for OAuth/session-style creds like auth-profiles.oauth.*, WhatsApp creds, and other runtime-minted tokens

So the short answer is: yes for API keys, no for OAuth refresh/session material.

If you want the safest/simple path, I’d usually recommend env-backed refs first. Then use:

  • openclaw secrets configure
  • openclaw secrets audit
  • openclaw secrets reload

Docs: