OpenClaw SecretRef 設定指南：管理 API 金鑰與憑證

處理 API Key 或是各種 Token 總是很心累，尤其是當你的專案越來越大，憑證散落在各個設定檔的時候。為了幫你解決這個痛點，OpenClaw 透過 SecretRef 提供了一套標準化的憑證管理方式，讓你不用再把敏感資訊寫死在程式碼或設定檔裡。

這篇文章會幫你釐清哪些憑證可以透過 SecretRef 來管理，哪些則因為性質特殊而不在範圍內。

SecretRef 憑證介面

這頁定義了標準的 SecretRef 憑證範圍。

範圍定義：

納入範圍：嚴格限定為使用者提供的憑證，且 OpenClaw 不會自動生成或輪換這些內容。
不在範圍：執行時生成的憑證、OAuth 重新整理資料（refresh material）以及類似 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.providers.*.apiKey
tools.web.fetch.firecrawl.apiKey
plugins.entries.brave.config.webSearch.apiKey
plugins.entries.google.config.webSearch.apiKey
plugins.entries.xai.config.webSearch.apiKey
plugins.entries.moonshot.config.webSearch.apiKey
plugins.entries.perplexity.config.webSearch.apiKey
plugins.entries.firecrawl.config.webSearch.apiKey
plugins.entries.tavily.config.webSearch.apiKey
tools.web.search.apiKey
tools.web.x_search.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.providers.*.apiKey
channels.discord.accounts.*.token
channels.discord.accounts.*.pluralkit.token
channels.discord.accounts.*.voice.tts.providers.*.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.accessToken
channels.matrix.password
channels.matrix.accounts.*.accessToken
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 via sibling serviceAccountRef (compatibility exception)
channels.googlechat.accounts.*.serviceAccount via sibling serviceAccountRef (compatibility exception)

`auth-profiles.json` 目標 (`secrets configure` + `secrets apply` + `secrets audit`)

profiles.*.keyRef (type: "api_key"; unsupported when auth.profiles.<id>.mode = "oauth")
profiles.*.tokenRef (type: "token"; unsupported when auth.profiles.<id>.mode = "oauth")

備註：

Auth-profile 計畫目標需要 agentId。
計畫項目會指向 profiles.*.key / profiles.*.token 並寫入同級的引用（keyRef / tokenRef）。
Auth-profile 引用已包含在執行時解析與稽核範圍內。
OAuth 策略防護：auth.profiles.<id>.mode = "oauth" 不能與該設定檔的 SecretRef 輸入同時使用。如果違反這項策略，啟動、重新載入或進行 Auth-profile 解析時會直接報錯。
對於受 SecretRef 管理的模型供應商，產生的 agents/*/agent/models.json 項目會保留非秘密標記（而非解析後的秘密值）用於 apiKey 或 Header 介面。
標記持久化是以來源為準：OpenClaw 會從當前的來源設定快照寫入標記，而不是使用解析後的執行時秘密值。
關於網路搜尋：
- 在明確供應商模式下（已設定 tools.web.search.provider），只有被選中的供應商金鑰會生效。
- 在自動模式下（未設定 tools.web.search.provider），只有根據優先順序解析出的第一個供應商金鑰會生效。
- 在自動模式下，未被選中的供應商引用會被視為非活動狀態，直到被選中為止。
- 舊有的 tools.web.search.* 供應商路徑在相容期間仍可解析，但標準的 SecretRef 介面應為 plugins.entries.<plugin>.config.webSearch.*。

不支援的憑證

不屬於此範圍的憑證包括：

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

原因：

這些憑證屬於自動生成、輪換、帶有工作階段或 OAuth 持久性的類別，不適合唯讀的外部 SecretRef 解析機制。

想要更輕鬆地完成設定嗎？試試我們的 AI Setup Assistant。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。