SecretRef 凭证表面

SecretRef 凭证表面（Credential Surface）定义了哪些凭证路径支持通过 SecretRef 进行外部引用解析。它严格限定为用户供应的凭证 — 即 OpenClaw 不会自行铸造（mint）或轮换（rotate）的凭证。

范围界定

• 在范围内：用户手动提供的、静态的 API Key、Token、密码等
• 不在范围内：运行时铸造或轮换的凭证、OAuth 刷新材料、会话类 artifact

支持的 openclaw.json 目标路径

以下是 openclaw.json 配置文件中支持 SecretRef 引用的所有凭证路径。

模型 Provider

路径	说明
models.providers.*.apiKey	模型 Provider 的 API Key

技能（Skills）

路径	说明
skills.entries.*.apiKey	Skill 条目的 API Key

Agent 内存搜索

路径	说明
agents.defaults.memorySearch.remote.apiKey	默认远程内存搜索 API Key
agents.list[].memorySearch.remote.apiKey	特定 Agent 的远程内存搜索 API Key

语音（Talk）

路径	说明
talk.apiKey	通用语音 API Key
talk.providers.*.apiKey	语音 Provider 的 API Key

TTS（文字转语音）

路径	说明
messages.tts.elevenlabs.apiKey	ElevenLabs TTS API Key
messages.tts.openai.apiKey	OpenAI TTS API Key

网页搜索工具

路径	说明
tools.web.search.apiKey	通用网页搜索 API Key
tools.web.search.gemini.apiKey	Gemini 搜索 API Key
tools.web.search.grok.apiKey	Grok 搜索 API Key
tools.web.search.kimi.apiKey	Kimi 搜索 API Key
tools.web.search.perplexity.apiKey	Perplexity 搜索 API Key

网页搜索密钥激活模式

• 显式 Provider 模式（tools.web.search.provider 已设置）：仅选定 Provider 的密钥生效
• 自动模式（tools.web.search.provider 未设置）：tools.web.search.apiKey 和各 Provider 专用密钥均生效

Gateway 认证

路径	说明
gateway.auth.password	Gateway 认证密码
gateway.auth.token	Gateway 认证 Token
gateway.remote.token	Gateway 远程连接 Token
gateway.remote.password	Gateway 远程连接密码

定时任务

路径	说明
cron.webhookToken	Cron Webhook Token

Telegram 渠道

路径	说明
channels.telegram.botToken	Telegram Bot Token
channels.telegram.webhookSecret	Telegram Webhook Secret
channels.telegram.accounts.*.botToken	多账号 Telegram Bot Token
channels.telegram.accounts.*.webhookSecret	多账号 Telegram Webhook Secret

Slack 渠道

路径	说明
channels.slack.botToken	Slack Bot Token
channels.slack.appToken	Slack App Token
channels.slack.userToken	Slack User Token
channels.slack.signingSecret	Slack Signing Secret
channels.slack.accounts.*.botToken	多账号 Slack Bot Token
channels.slack.accounts.*.appToken	多账号 Slack App Token
channels.slack.accounts.*.userToken	多账号 Slack User Token
channels.slack.accounts.*.signingSecret	多账号 Slack Signing Secret

Discord 渠道

路径	说明
channels.discord.token	Discord Token
channels.discord.pluralkit.token	Discord PluralKit Token
channels.discord.voice.tts.elevenlabs.apiKey	Discord 语音 ElevenLabs API Key
channels.discord.voice.tts.openai.apiKey	Discord 语音 OpenAI API Key
channels.discord.accounts.*.token	多账号 Discord Token
channels.discord.accounts.*.pluralkit.token	多账号 PluralKit Token
channels.discord.accounts.*.voice.tts.elevenlabs.apiKey	多账号语音 ElevenLabs API Key
channels.discord.accounts.*.voice.tts.openai.apiKey	多账号语音 OpenAI API Key

IRC 渠道

路径	说明
channels.irc.password	IRC 密码
channels.irc.nickserv.password	IRC NickServ 密码
channels.irc.accounts.*.password	多账号 IRC 密码
channels.irc.accounts.*.nickserv.password	多账号 NickServ 密码

BlueBubbles 渠道

路径	说明
channels.bluebubbles.password	BlueBubbles 密码
channels.bluebubbles.accounts.*.password	多账号 BlueBubbles 密码

飞书渠道

路径	说明
channels.feishu.appSecret	飞书 App Secret
channels.feishu.verificationToken	飞书 Verification Token
channels.feishu.accounts.*.appSecret	多账号飞书 App Secret
channels.feishu.accounts.*.verificationToken	多账号飞书 Verification Token

Microsoft Teams 渠道

路径	说明
channels.msteams.appPassword	MS Teams App Password

Mattermost 渠道

路径	说明
channels.mattermost.botToken	Mattermost Bot Token
channels.mattermost.accounts.*.botToken	多账号 Mattermost Bot Token

Matrix 渠道

路径	说明
channels.matrix.password	Matrix 密码
channels.matrix.accounts.*.password	多账号 Matrix 密码

Nextcloud Talk 渠道

路径	说明
channels.nextcloud-talk.botSecret	Nextcloud Talk Bot Secret
channels.nextcloud-talk.apiPassword	Nextcloud Talk API Password
channels.nextcloud-talk.accounts.*.botSecret	多账号 Nextcloud Bot Secret
channels.nextcloud-talk.accounts.*.apiPassword	多账号 Nextcloud API Password

Zalo 渠道

路径	说明
channels.zalo.botToken	Zalo Bot Token
channels.zalo.webhookSecret	Zalo Webhook Secret
channels.zalo.accounts.*.botToken	多账号 Zalo Bot Token
channels.zalo.accounts.*.webhookSecret	多账号 Zalo Webhook Secret

Google Chat 渠道

路径	说明
channels.googlechat.serviceAccount	通过 serviceAccountRef 兼容引用（兼容性例外）
channels.googlechat.accounts.*.serviceAccount	多账号 Google Chat Service Account（兼容性例外）

支持的 auth-profiles.json 目标路径

Auth profiles 文件中支持以下 SecretRef 目标：

路径	Auth Profile 类型	说明
profiles.*.keyRef	type: "api_key"	API Key 引用
profiles.*.tokenRef	type: "token"	Token 引用

agentId 必填

Auth profile 类型的 plan target 必须包含 agentId 字段。

Plan 条目逻辑： Plan 条目通过 profiles.*.key / profiles.*.token 定位目标，并写入对应的 sibling ref（keyRef / tokenRef）。

运行时覆盖： Auth profile 中的 ref（keyRef / tokenRef）包含在运行时解析和审计覆盖范围内。

不受支持的凭证类型

以下凭证类型不支持 SecretRef，因为它们属于运行时铸造（minted）、自动轮换（rotated）、会话绑定（session-bearing）或 OAuth 持久类凭证，不适合只读的外部 SecretRef 解析：

路径	原因
commands.ownerDisplaySecret	运行时铸造/轮换
channels.matrix.accessToken	运行时铸造/轮换
channels.matrix.accounts.*.accessToken	运行时铸造/轮换
hooks.token	运行时铸造/轮换
hooks.gmail.pushToken	运行时铸造/轮换
hooks.mappings[].sessionKey	会话绑定
auth-profiles.oauth.*	OAuth 持久类
discord.threadBindings.*.webhookToken	运行时铸造/轮换
whatsapp.creds.json	运行时铸造/会话绑定

为什么不支持？

这些凭证由 OpenClaw 在运行时自动铸造、轮换或通过 OAuth 流程获取，其生命周期由系统管理，不适合外部 SecretRef 这种只读引用机制。

相关文档

• 密钥管理 — Gateway 密钥存储与管理
• Secrets Apply Plan 合约 — openclaw secrets apply 的验证规则
• CLI 引导参考 — 引导向导中的凭证存储选项