{"id":635,"date":"2026-03-21T22:52:58","date_gmt":"2026-03-21T14:52:58","guid":{"rendered":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/reference-secretref-credential-surface\/"},"modified":"2026-03-22T00:41:45","modified_gmt":"2026-03-21T16:41:45","slug":"reference-secretref-credential-surface","status":"publish","type":"post","link":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/reference-secretref-credential-surface\/","title":{"rendered":"SecretRef Credential Surface"},"content":{"rendered":"<h1>SecretRef Credential Surface<\/h1>\n<h1>SecretRef credential surface<\/h1>\n<p>This page defines the canonical SecretRef credential surface.<\/p>\n<p>Scope intent:<\/p>\n<ul>\n<li>In scope: strictly user-supplied credentials that OpenClaw does not mint or rotate.<\/li>\n<li>Out of scope: runtime-minted or rotating credentials, OAuth refresh material, and session-like artifacts.<\/li>\n<\/ul>\n<h2>Supported credentials<\/h2>\n<h3><code>openclaw.json<\/code> targets (<code>secrets configure<\/code> + <code>secrets apply<\/code> + <code>secrets audit<\/code>)<\/h3>\n<ul>\n<li><code>models.providers.*.apiKey<\/code><\/li>\n<li><code>models.providers.*.headers.*<\/code><\/li>\n<li><code>skills.entries.*.apiKey<\/code><\/li>\n<li><code>agents.defaults.memorySearch.remote.apiKey<\/code><\/li>\n<li><code>agents.list[].memorySearch.remote.apiKey<\/code><\/li>\n<li><code>talk.apiKey<\/code><\/li>\n<li><code>talk.providers.*.apiKey<\/code><\/li>\n<li><code>messages.tts.elevenlabs.apiKey<\/code><\/li>\n<li><code>messages.tts.openai.apiKey<\/code><\/li>\n<li><code>tools.web.fetch.firecrawl.apiKey<\/code><\/li>\n<li><code>plugins.entries.brave.config.webSearch.apiKey<\/code><\/li>\n<li><code>plugins.entries.google.config.webSearch.apiKey<\/code><\/li>\n<li><code>plugins.entries.xai.config.webSearch.apiKey<\/code><\/li>\n<li><code>plugins.entries.moonshot.config.webSearch.apiKey<\/code><\/li>\n<li><code>plugins.entries.perplexity.config.webSearch.apiKey<\/code><\/li>\n<li><code>plugins.entries.firecrawl.config.webSearch.apiKey<\/code><\/li>\n<li><code>plugins.entries.tavily.config.webSearch.apiKey<\/code><\/li>\n<li><code>tools.web.search.apiKey<\/code><\/li>\n<li><code>tools.web.search.gemini.apiKey<\/code><\/li>\n<li><code>tools.web.search.grok.apiKey<\/code><\/li>\n<li><code>tools.web.search.kimi.apiKey<\/code><\/li>\n<li><code>tools.web.search.perplexity.apiKey<\/code><\/li>\n<li><code>gateway.auth.password<\/code><\/li>\n<li><code>gateway.auth.token<\/code><\/li>\n<li><code>gateway.remote.token<\/code><\/li>\n<li><code>gateway.remote.password<\/code><\/li>\n<li><code>cron.webhookToken<\/code><\/li>\n<li><code>channels.telegram.botToken<\/code><\/li>\n<li><code>channels.telegram.webhookSecret<\/code><\/li>\n<li><code>channels.telegram.accounts.*.botToken<\/code><\/li>\n<li><code>channels.telegram.accounts.*.webhookSecret<\/code><\/li>\n<li><code>channels.slack.botToken<\/code><\/li>\n<li><code>channels.slack.appToken<\/code><\/li>\n<li><code>channels.slack.userToken<\/code><\/li>\n<li><code>channels.slack.signingSecret<\/code><\/li>\n<li><code>channels.slack.accounts.*.botToken<\/code><\/li>\n<li><code>channels.slack.accounts.*.appToken<\/code><\/li>\n<li><code>channels.slack.accounts.*.userToken<\/code><\/li>\n<li><code>channels.slack.accounts.*.signingSecret<\/code><\/li>\n<li><code>channels.discord.token<\/code><\/li>\n<li><code>channels.discord.pluralkit.token<\/code><\/li>\n<li><code>channels.discord.voice.tts.elevenlabs.apiKey<\/code><\/li>\n<li><code>channels.discord.voice.tts.openai.apiKey<\/code><\/li>\n<li><code>channels.discord.accounts.*.token<\/code><\/li>\n<li><code>channels.discord.accounts.*.pluralkit.token<\/code><\/li>\n<li><code>channels.discord.accounts.*.voice.tts.elevenlabs.apiKey<\/code><\/li>\n<li><code>channels.discord.accounts.*.voice.tts.openai.apiKey<\/code><\/li>\n<li><code>channels.irc.password<\/code><\/li>\n<li><code>channels.irc.nickserv.password<\/code><\/li>\n<li><code>channels.irc.accounts.*.password<\/code><\/li>\n<li><code>channels.irc.accounts.*.nickserv.password<\/code><\/li>\n<li><code>channels.bluebubbles.password<\/code><\/li>\n<li><code>channels.bluebubbles.accounts.*.password<\/code><\/li>\n<li><code>channels.feishu.appSecret<\/code><\/li>\n<li><code>channels.feishu.encryptKey<\/code><\/li>\n<li><code>channels.feishu.verificationToken<\/code><\/li>\n<li><code>channels.feishu.accounts.*.appSecret<\/code><\/li>\n<li><code>channels.feishu.accounts.*.encryptKey<\/code><\/li>\n<li><code>channels.feishu.accounts.*.verificationToken<\/code><\/li>\n<li><code>channels.msteams.appPassword<\/code><\/li>\n<li><code>channels.mattermost.botToken<\/code><\/li>\n<li><code>channels.mattermost.accounts.*.botToken<\/code><\/li>\n<li><code>channels.matrix.password<\/code><\/li>\n<li><code>channels.matrix.accounts.*.password<\/code><\/li>\n<li><code>channels.nextcloud-talk.botSecret<\/code><\/li>\n<li><code>channels.nextcloud-talk.apiPassword<\/code><\/li>\n<li><code>channels.nextcloud-talk.accounts.*.botSecret<\/code><\/li>\n<li><code>channels.nextcloud-talk.accounts.*.apiPassword<\/code><\/li>\n<li><code>channels.zalo.botToken<\/code><\/li>\n<li><code>channels.zalo.webhookSecret<\/code><\/li>\n<li><code>channels.zalo.accounts.*.botToken<\/code><\/li>\n<li><code>channels.zalo.accounts.*.webhookSecret<\/code><\/li>\n<li><code>channels.googlechat.serviceAccount<\/code> via sibling <code>serviceAccountRef<\/code> (compatibility exception)<\/li>\n<li><code>channels.googlechat.accounts.*.serviceAccount<\/code> via sibling <code>serviceAccountRef<\/code> (compatibility exception)<\/li>\n<\/ul>\n<h3><code>auth-profiles.json<\/code> targets (<code>secrets configure<\/code> + <code>secrets apply<\/code> + <code>secrets audit<\/code>)<\/h3>\n<ul>\n<li><code>profiles.*.keyRef<\/code> (<code>type: \"api_key\"<\/code>)<\/li>\n<li><code>profiles.*.tokenRef<\/code> (<code>type: \"token\"<\/code>)<\/li>\n<\/ul>\n<p>Notes:<\/p>\n<ul>\n<li>Auth-profile plan targets require <code>agentId<\/code>.<\/li>\n<li>Plan entries target <code>profiles.*.key<\/code> \/ <code>profiles.*.token<\/code> and write sibling refs (<code>keyRef<\/code> \/ <code>tokenRef<\/code>).<\/li>\n<li>Auth-profile refs are included in runtime resolution and audit coverage.<\/li>\n<li>For SecretRef-managed model providers, generated <code>agents\/*\/agent\/models.json<\/code> entries persist non-secret markers (not resolved secret values) for <code>apiKey<\/code>\/header surfaces.<\/li>\n<li>Marker persistence is source-authoritative: OpenClaw writes markers from the active source config snapshot (pre-resolution), not from resolved runtime secret values.<\/li>\n<li>For web search:<\/li>\n<li>In explicit provider mode (<code>tools.web.search.provider<\/code> set), only the selected provider key is active.<\/li>\n<li>In auto mode (<code>tools.web.search.provider<\/code> unset), only the first provider key that resolves by precedence is active.<\/li>\n<li>In auto mode, non-selected provider refs are treated as inactive until selected.<\/li>\n<li>Legacy <code>tools.web.search.*<\/code> provider paths still resolve during the compatibility window, but the canonical SecretRef surface is <code>plugins.entries.&lt;plugin&gt;.config.webSearch.*<\/code>.<\/li>\n<\/ul>\n<h2>Unsupported credentials<\/h2>\n<p>Out-of-scope credentials include:<\/p>\n<ul>\n<li><code>commands.ownerDisplaySecret<\/code><\/li>\n<li><code>channels.matrix.accessToken<\/code><\/li>\n<li><code>channels.matrix.accounts.*.accessToken<\/code><\/li>\n<li><code>hooks.token<\/code><\/li>\n<li><code>hooks.gmail.pushToken<\/code><\/li>\n<li><code>hooks.mappings[].sessionKey<\/code><\/li>\n<li><code>auth-profiles.oauth.*<\/code><\/li>\n<li><code>discord.threadBindings.*.webhookToken<\/code><\/li>\n<li><code>whatsapp.creds.json<\/code><\/li>\n<\/ul>\n<p>Rationale:<\/p>\n<ul>\n<li>These credentials are minted, rotated, session-bearing, or OAuth-durable classes that do not fit read-only external SecretRef resolution.<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>SecretRef Credential Surface SecretRef credential surfa [&hellip;]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-635","post","type-post","status-publish","format-standard","hentry","category-docs"],"_links":{"self":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/635","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/comments?post=635"}],"version-history":[{"count":3,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/635\/revisions"}],"predecessor-version":[{"id":1123,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/635\/revisions\/1123"}],"wp:attachment":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/media?parent=635"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/categories?post=635"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/tags?post=635"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}