SecretRef 憑證介面

本頁面定義正規的 SecretRef 憑證介面。

範圍意圖：

範圍內：嚴格由使用者提供、OpenClaw 不鑄造或輪換的憑證。
範圍外：執行時鑄造或輪換的憑證、OAuth 更新材料，以及類 session 的產出物。

已支援的憑證

`openclaw.json` 目標（`secrets configure` + `secrets apply` + `secrets audit`）

models.providers.*.apiKey
models.providers.*.headers.*
skills.entries.*.apiKey
agents.defaults.memorySearch.remote.apiKey
agents.list[].memorySearch.remote.apiKey
talk.apiKey
talk.providers.*.apiKey
messages.tts.elevenlabs.apiKey
messages.tts.openai.apiKey
tools.web.fetch.firecrawl.apiKey
tools.web.search.apiKey
tools.web.search.gemini.apiKey
tools.web.search.grok.apiKey
tools.web.search.kimi.apiKey
tools.web.search.perplexity.apiKey
gateway.auth.password
gateway.auth.token
gateway.remote.token
gateway.remote.password
cron.webhookToken
channels.telegram.botToken
channels.telegram.webhookSecret
channels.telegram.accounts.*.botToken
channels.telegram.accounts.*.webhookSecret
channels.slack.botToken
channels.slack.appToken
channels.slack.userToken
channels.slack.signingSecret
channels.slack.accounts.*.botToken
channels.slack.accounts.*.appToken
channels.slack.accounts.*.userToken
channels.slack.accounts.*.signingSecret
channels.discord.token
channels.discord.pluralkit.token
channels.discord.voice.tts.elevenlabs.apiKey
channels.discord.voice.tts.openai.apiKey
channels.discord.accounts.*.token
channels.discord.accounts.*.pluralkit.token
channels.discord.accounts.*.voice.tts.elevenlabs.apiKey
channels.discord.accounts.*.voice.tts.openai.apiKey
channels.irc.password
channels.irc.nickserv.password
channels.irc.accounts.*.password
channels.irc.accounts.*.nickserv.password
channels.bluebubbles.password
channels.bluebubbles.accounts.*.password
channels.feishu.appSecret
channels.feishu.encryptKey
channels.feishu.verificationToken
channels.feishu.accounts.*.appSecret
channels.feishu.accounts.*.encryptKey
channels.feishu.accounts.*.verificationToken
channels.msteams.appPassword
channels.mattermost.botToken
channels.mattermost.accounts.*.botToken
channels.matrix.password
channels.matrix.accounts.*.password
channels.nextcloud-talk.botSecret
channels.nextcloud-talk.apiPassword
channels.nextcloud-talk.accounts.*.botSecret
channels.nextcloud-talk.accounts.*.apiPassword
channels.zalo.botToken
channels.zalo.webhookSecret
channels.zalo.accounts.*.botToken
channels.zalo.accounts.*.webhookSecret
channels.googlechat.serviceAccount 透過同級的 serviceAccountRef（相容例外）
channels.googlechat.accounts.*.serviceAccount 透過同級的 serviceAccountRef（相容例外）

`auth-profiles.json` 目標（`secrets configure` + `secrets apply` + `secrets audit`）

profiles.*.keyRef（type: "api_key"）
profiles.*.tokenRef（type: "token"）

說明：

Auth-profile 計畫目標需要 agentId。
計畫項目以 profiles.*.key / profiles.*.token 為目標，並寫入同級的 ref（keyRef / tokenRef）。
Auth-profile ref 包含在執行時解析和稽核覆蓋中。
對 SecretRef 管理的模型供應商，產生的 agents/*/agent/models.json 項目持久化非密鑰標記（非解析後的密鑰值）用於 apiKey/header 介面。
標記持久化以來源為權威：OpenClaw 從活躍來源設定快照（解析前）寫入標記，而非從解析後的執行時密鑰值。
網頁搜尋：
- 在明確供應商模式（tools.web.search.provider 已設定）中，僅選定的供應商金鑰為活躍。
- 在自動模式（tools.web.search.provider 未設定）中，僅依優先順序首先解析的供應商金鑰為活躍。
- 在自動模式中，未選定的供應商 ref 視為非活躍直到被選定。

不支援的憑證

範圍外的憑證包含：

commands.ownerDisplaySecret
channels.matrix.accessToken
channels.matrix.accounts.*.accessToken
hooks.token
hooks.gmail.pushToken
hooks.mappings[].sessionKey
auth-profiles.oauth.*
discord.threadBindings.*.webhookToken
whatsapp.creds.json

理由：

這些憑證為鑄造的、輪換的、帶 session 的或 OAuth 持久類別，不適合唯讀的外部 SecretRef 解析。