SecretRef credential surface

This page defines the canonical SecretRef credential surface.

Scope intent:

• In scope: strictly user-supplied credentials that OpenClaw does not mint or rotate.
• Out of scope: runtime-minted or rotating credentials, OAuth refresh material, and session-like artifacts.

Supported credentials

text

Copy

openclaw.json

targets (

text

Copy

secrets configure

+

text

Copy

secrets apply

+

text

Copy

secrets audit

)

• text

  Copy

  models.providers.*.apiKey
• text

  Copy

  models.providers.*.headers.*
• text

  Copy

  models.providers.*.request.auth.token
• text

  Copy

  models.providers.*.request.auth.value
• text

  Copy

  models.providers.*.request.headers.*
• text

  Copy

  models.providers.*.request.proxy.tls.ca
• text

  Copy

  models.providers.*.request.proxy.tls.cert
• text

  Copy

  models.providers.*.request.proxy.tls.key
• text

  Copy

  models.providers.*.request.proxy.tls.passphrase
• text

  Copy

  models.providers.*.request.tls.ca
• text

  Copy

  models.providers.*.request.tls.cert
• text

  Copy

  models.providers.*.request.tls.key
• text

  Copy

  models.providers.*.request.tls.passphrase
• text

  Copy

  skills.entries.*.apiKey
• text

  Copy

  agents.defaults.memorySearch.remote.apiKey
• text

  Copy

  agents.list[].tts.providers.*.apiKey
• text

  Copy

  agents.list[].memorySearch.remote.apiKey
• text

  Copy

  talk.providers.*.apiKey
• text

  Copy

  messages.tts.providers.*.apiKey
• text

  Copy

  tools.web.fetch.firecrawl.apiKey
• text

  Copy

  plugins.entries.acpx.config.mcpServers.*.env.*
• text

  Copy

  plugins.entries.brave.config.webSearch.apiKey
• text

  Copy

  plugins.entries.exa.config.webSearch.apiKey
• text

  Copy

  plugins.entries.google.config.webSearch.apiKey
• text

  Copy

  plugins.entries.xai.config.webSearch.apiKey
• text

  Copy

  plugins.entries.moonshot.config.webSearch.apiKey
• text

  Copy

  plugins.entries.perplexity.config.webSearch.apiKey
• text

  Copy

  plugins.entries.firecrawl.config.webSearch.apiKey
• text

  Copy

  plugins.entries.minimax.config.webSearch.apiKey
• text

  Copy

  plugins.entries.tavily.config.webSearch.apiKey
• text

  Copy

  plugins.entries.voice-call.config.realtime.providers.*.apiKey
• text

  Copy

  plugins.entries.voice-call.config.streaming.providers.*.apiKey
• text

  Copy

  plugins.entries.voice-call.config.tts.providers.*.apiKey
• text

  Copy

  plugins.entries.voice-call.config.twilio.authToken
• text

  Copy

  tools.web.search.apiKey
• text

  Copy

  gateway.auth.password
• text

  Copy

  gateway.auth.token
• text

  Copy

  gateway.remote.token
• text

  Copy

  gateway.remote.password
• text

  Copy

  cron.webhookToken
• text

  Copy

  channels.telegram.botToken
• text

  Copy

  channels.telegram.webhookSecret
• text

  Copy

  channels.telegram.accounts.*.botToken
• text

  Copy

  channels.telegram.accounts.*.webhookSecret
• text

  Copy

  channels.slack.botToken
• text

  Copy

  channels.slack.appToken
• text

  Copy

  channels.slack.userToken
• text

  Copy

  channels.slack.signingSecret
• text

  Copy

  channels.slack.accounts.*.botToken
• text

  Copy

  channels.slack.accounts.*.appToken
• text

  Copy

  channels.slack.accounts.*.userToken
• text

  Copy

  channels.slack.accounts.*.signingSecret
• text

  Copy

  channels.discord.token
• text

  Copy

  channels.discord.pluralkit.token
• text

  Copy

  channels.discord.voice.tts.providers.*.apiKey
• text

  Copy

  channels.discord.accounts.*.token
• text

  Copy

  channels.discord.accounts.*.pluralkit.token
• text

  Copy

  channels.discord.accounts.*.voice.tts.providers.*.apiKey
• text

  Copy

  channels.irc.password
• text

  Copy

  channels.irc.nickserv.password
• text

  Copy

  channels.irc.accounts.*.password
• text

  Copy

  channels.irc.accounts.*.nickserv.password
• text

  Copy

  channels.bluebubbles.password
• text

  Copy

  channels.bluebubbles.accounts.*.password
• text

  Copy

  channels.feishu.appSecret
• text

  Copy

  channels.feishu.encryptKey
• text

  Copy

  channels.feishu.verificationToken
• text

  Copy

  channels.feishu.accounts.*.appSecret
• text

  Copy

  channels.feishu.accounts.*.encryptKey
• text

  Copy

  channels.feishu.accounts.*.verificationToken
• text

  Copy

  channels.msteams.appPassword
• text

  Copy

  channels.mattermost.botToken
• text

  Copy

  channels.mattermost.accounts.*.botToken
• text

  Copy

  channels.matrix.accessToken
• text

  Copy

  channels.matrix.password
• text

  Copy

  channels.matrix.accounts.*.accessToken
• text

  Copy

  channels.matrix.accounts.*.password
• text

  Copy

  channels.nextcloud-talk.botSecret
• text

  Copy

  channels.nextcloud-talk.apiPassword
• text

  Copy

  channels.nextcloud-talk.accounts.*.botSecret
• text

  Copy

  channels.nextcloud-talk.accounts.*.apiPassword
• text

  Copy

  channels.zalo.botToken
• text

  Copy

  channels.zalo.webhookSecret
• text

  Copy

  channels.zalo.accounts.*.botToken
• text

  Copy

  channels.zalo.accounts.*.webhookSecret
• text

  Copy

  channels.googlechat.serviceAccount
  via sibling
  text

  Copy

  serviceAccountRef
  (compatibility exception)
• text

  Copy

  channels.googlechat.accounts.*.serviceAccount
  via sibling
  text

  Copy

  serviceAccountRef
  (compatibility exception)

text

Copy

auth-profiles.json

targets (

text

Copy

secrets configure

+

text

Copy

secrets apply

+

text

Copy

secrets audit

)

• text

  Copy

  profiles.*.keyRef
  (
  text

  Copy

  type: "api_key"
  ; unsupported when
  text

  Copy

  auth.profiles.<id>.mode = "oauth"
  )
• text

  Copy

  profiles.*.tokenRef
  (
  text

  Copy

  type: "token"
  ; unsupported when
  text

  Copy

  auth.profiles.<id>.mode = "oauth"
  )

Notes:

• Auth-profile plan targets require
  text

  Copy

  agentId
  .
• Plan entries target
  text

  Copy

  profiles.*.key
  /
  text

  Copy

  profiles.*.token
  and write sibling refs (
  text

  Copy

  keyRef
  /
  text

  Copy

  tokenRef
  ).
• Auth-profile refs are included in runtime resolution and audit coverage.
• In
  text

  Copy

  openclaw.json
  , SecretRefs must use structured objects such as
  text

  Copy

  {"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}
  . Legacy
  text

  Copy

  secretref-env:<ENV_VAR>
  marker strings are rejected on SecretRef credential paths; run
  text

  Copy

  openclaw doctor --fix
  to migrate valid markers.
• OAuth policy guard:
  text

  Copy

  auth.profiles.<id>.mode = "oauth"
  cannot be combined with SecretRef inputs for that profile. Startup/reload and auth-profile resolution fail fast when this policy is violated.
• For SecretRef-managed model providers, generated
  text

  Copy

  agents/*/agent/models.json
  entries persist non-secret markers (not resolved secret values) for
  text

  Copy

  apiKey
  /header surfaces.
• Marker persistence is source-authoritative: OpenClaw writes markers from the active source config snapshot (pre-resolution), not from resolved runtime secret values.
• For web search:
  • In explicit provider mode (
    text

    Copy

    tools.web.search.provider
    set), only the selected provider key is active.
  • In auto mode (
    text

    Copy

    tools.web.search.provider
    unset), only the first provider key that resolves by precedence is active.
  • In auto mode, non-selected provider refs are treated as inactive until selected.
  • Legacy
    text

    Copy

    tools.web.search.*
    provider paths still resolve during the compatibility window, but the canonical SecretRef surface is
    text

    Copy

    plugins.entries.<plugin>.config.webSearch.*
    .

Unsupported credentials

Out-of-scope credentials include:

• text

  Copy

  commands.ownerDisplaySecret
• text

  Copy

  hooks.token
• text

  Copy

  hooks.gmail.pushToken
• text

  Copy

  hooks.mappings[].sessionKey
• text

  Copy

  auth-profiles.oauth.*
• text

  Copy

  channels.discord.threadBindings.webhookToken
• text

  Copy

  channels.discord.accounts.*.threadBindings.webhookToken
• text

  Copy

  channels.whatsapp.creds.json
• text

  Copy

  channels.whatsapp.accounts.*.creds.json

Rationale:

• These credentials are minted, rotated, session-bearing, or OAuth-durable classes that do not fit read-only external SecretRef resolution.

Related

• Secrets management
• Auth credential semantics