SecretRef 凭证面（Credential Surface）

本页定义 SecretRef 的规范凭证范围：仅限用户提供的凭证，不包括运行时生成或轮换的凭证。

支持的凭证（openclaw.json）

主要类别：

• models.providers.*.apiKey 及相关 headers/TLS 配置
• skills.entries.*.apiKey
• agents.defaults.memorySearch.remote.apiKey
• talk.providers.*.apiKey
• gateway.auth.password / gateway.auth.token
• channels.telegram.botToken / webhookSecret
• channels.slack.botToken / appToken / signingSecret
• channels.discord.token
• channels.feishu.appSecret / encryptKey
• plugins.entries.brave/exa/google/xai/perplexity/tavily.config.webSearch.apiKey
• plugins.entries.voice-call.config.*.providers.*.apiKey

支持的凭证（auth-profiles.json）

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

不支持的凭证（超出范围）

以下凭证由运行时生成/轮换，不适用 SecretRef：

• commands.ownerDisplaySecret
• hooks.token
• auth-profiles.oauth.*
• channels.whatsapp.creds.json
• channels.discord.threadBindings.webhookToken

重要规则

• openclaw.json 中的 SecretRef 必须使用结构化对象：{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}
• 旧式 secretref-env:<ENV_VAR> 字符串已废弃，运行 openclaw doctor --fix 迁移
• OAuth 模式（auth.profiles.<id>.mode = "oauth"）不能与 SecretRef 输入混用

相关页面

• gateway-secrets
• ref-agents-default