跳转至

SecretRef 凭据接口

本页定义了规范的 SecretRef 凭据面：哪些凭据字段接受 SecretRef（基于 env/file/exec/store 的引用）而不是原始密钥值。

范围：

  • 范围内：严格由用户提供的凭据，OpenClaw 不会签发或轮换。
  • 范围外：运行时签发或轮换的凭据、OAuth 刷新材料，以及类似会话的产物。

以下列表由源目标注册表生成，并在 CI 中对照 docs/reference/secretref-user-supplied-credentials-matrix.json 进行检查；请勿手动编辑条目。

如果已存在的渠道 secret-contract 工件无法加载，源生成将失败，而不是发布不完整的列表。没有该可选工件的插件不会贡献任何渠道目标。此生成检查不会改变运行时 SecretRef 所有者隔离行为。

支持的凭据

openclaw.json 目标（secrets configure + secrets apply + secrets audit）

agents

  • agents.entries.*.memory.search.remote.apiKey
  • agents.entries.*.tts.personas.*.providers.*.apiKey
  • agents.entries.*.tts.providers.*.apiKey

channels

  • channels.buzz.accounts.*.authTag
  • channels.buzz.accounts.*.privateKey
  • channels.buzz.authTag
  • channels.buzz.privateKey
  • channels.clickclack.accounts.*.token
  • channels.clickclack.token
  • channels.discord.accounts.*.pluralkit.token
  • channels.discord.accounts.*.token
  • channels.discord.accounts.*.voice.realtime.providers.*.apiKey
  • channels.discord.accounts.*.voice.tts.personas.*.providers.*.apiKey
  • channels.discord.accounts.*.voice.tts.providers.*.apiKey
  • channels.discord.pluralkit.token
  • channels.discord.token
  • channels.discord.voice.realtime.providers.*.apiKey
  • channels.discord.voice.tts.personas.*.providers.*.apiKey
  • channels.discord.voice.tts.providers.*.apiKey
  • channels.feishu.accounts.*.appSecret
  • channels.feishu.accounts.*.encryptKey
  • channels.feishu.accounts.*.verificationToken
  • channels.feishu.appSecret
  • channels.feishu.encryptKey
  • channels.feishu.verificationToken
  • channels.googlechat.accounts.*.serviceAccount
  • channels.googlechat.serviceAccount
  • channels.irc.accounts.*.nickserv.password
  • channels.irc.accounts.*.password
  • channels.irc.nickserv.password
  • channels.irc.password
  • channels.matrix.accessToken
  • channels.matrix.accounts.*.accessToken
  • channels.matrix.accounts.*.password
  • channels.matrix.password
  • channels.mattermost.accounts.*.botToken
  • channels.mattermost.botToken
  • channels.msteams.appPassword
  • channels.nextcloud-talk.accounts.*.apiPassword
  • channels.nextcloud-talk.accounts.*.botSecret
  • channels.nextcloud-talk.apiPassword
  • channels.nextcloud-talk.botSecret
  • channels.nostr.privateKey
  • channels.qqbot.accounts.*.clientSecret
  • channels.qqbot.clientSecret
  • channels.slack.accounts.*.appToken
  • channels.slack.accounts.*.botToken
  • channels.slack.accounts.*.relay.authToken
  • channels.slack.accounts.*.signingSecret
  • channels.slack.accounts.*.userToken
  • channels.slack.appToken
  • channels.slack.botToken
  • channels.slack.relay.authToken
  • channels.slack.signingSecret
  • channels.slack.userToken
  • channels.sms.accounts.*.authToken
  • channels.sms.authToken
  • channels.telegram.accounts.*.botToken
  • channels.telegram.accounts.*.webhookSecret
  • channels.telegram.botToken
  • channels.telegram.webhookSecret
  • channels.zalo.accounts.*.botToken
  • channels.zalo.accounts.*.webhookSecret
  • channels.zalo.botToken
  • channels.zalo.webhookSecret

cron

  • cron.webhookToken

gateway

  • gateway.auth.password
  • gateway.auth.token
  • gateway.remote.password
  • gateway.remote.token

memory

  • memory.search.remote.apiKey

models

  • models.providers.*.apiKey
  • models.providers.*.headers.*
  • models.providers.*.request.auth.token
  • models.providers.*.request.auth.value
  • models.providers.*.request.headers.*
  • models.providers.*.request.proxy.tls.ca
  • models.providers.*.request.proxy.tls.cert
  • models.providers.*.request.proxy.tls.key
  • models.providers.*.request.proxy.tls.passphrase
  • models.providers.*.request.tls.ca
  • models.providers.*.request.tls.cert
  • models.providers.*.request.tls.key
  • models.providers.*.request.tls.passphrase

plugins

  • plugins.entries.acpx.config.mcpServers.*.env.*
  • plugins.entries.brave.config.webSearch.apiKey
  • plugins.entries.codex.config.appServer.authToken
  • plugins.entries.codex.config.appServer.headers.*
  • plugins.entries.comfy.config.headers.*
  • plugins.entries.exa.config.webSearch.apiKey
  • plugins.entries.facetime.config.realtime.providers.*.apiKey
  • plugins.entries.firecrawl.config.webFetch.apiKey
  • plugins.entries.firecrawl.config.webSearch.apiKey
  • plugins.entries.google-meet.config.realtime.providers.*.apiKey
  • plugins.entries.google.config.webSearch.apiKey
  • plugins.entries.google.config.webSearch.headers.*
  • plugins.entries.imap.config.accounts.*.password
  • plugins.entries.minimax.config.webSearch.apiKey
  • plugins.entries.moonshot.config.webSearch.apiKey
  • plugins.entries.parallel.config.webSearch.apiKey
  • plugins.entries.perplexity.config.webSearch.apiKey
  • plugins.entries.tavily.config.webSearch.apiKey
  • plugins.entries.team-reports.config.discord.token
  • plugins.entries.team-reports.config.github.token
  • plugins.entries.typesafe.config.apiKey
  • plugins.entries.voice-call.config.realtime.providers.*.apiKey
  • plugins.entries.voice-call.config.streaming.providers.*.apiKey
  • plugins.entries.voice-call.config.tts.providers.*.apiKey
  • plugins.entries.voice-call.config.twilio.authToken
  • plugins.entries.xai.config.webSearch.apiKey

skills

  • skills.entries.*.apiKey

talk

  • talk.providers.*.apiKey
  • talk.realtime.providers.*.apiKey

tts

  • tts.personas.*.providers.*.apiKey
  • tts.providers.*.apiKey

SQLite 认证配置目标（secrets configure + secrets apply + secrets audit）

  • profiles.*.keyRef（type: "api_key"；当 auth.profiles.<id>.mode = "oauth" 时不受支持）
  • profiles.*.tokenRef（type: "token"；当 auth.profiles.<id>.mode = "oauth" 时不受支持）

节点主机连接目标

  • gateway.cloudflareAccess.clientId
  • gateway.cloudflareAccess.clientSecret

这些字段位于节点主机的规范 nodeHost.config SQLite 机器状态值中， 而不是 openclaw.json。它们接受相同的 SecretInput 形式，并在节点启动时通过 已配置的 SecretRef 提供者进行解析。传统的 CF_ACCESS_CLIENT_ID / CF_ACCESS_CLIENT_SECRET 回退机制会自动为 这些字段持久化 env 引用。它们不是 secrets configure 或 secrets apply 的目标。

说明：

  • store 引用使用匹配 ^[A-Z][A-Z0-9_]{0,127}$ 的名称，并且仅从 Gateway 范围的团队作用域解析；不存在其他 store 作用域。典型引用为 {"source":"store","provider":"default","id":"OPENAI_API_KEY"}。
  • 认证配置计划目标需要 agentId；计划条目指向 profiles.*.key / profiles.*.token，并写入同级引用（keyRef / tokenRef）。认证配置引用包含在运行时解析和审计覆盖范围内。
  • 在 openclaw.json 中，SecretRef 必须使用结构化对象，例如 {"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}。在 SecretRef 凭据路径上会拒绝旧版 secretref-env:<ENV_VAR> 标记字符串；运行 openclaw doctor --fix 以迁移有效标记。
  • OAuth 策略保护：auth.profiles.<id>.mode = "oauth" 不能与该配置文件的 SecretRef 输入组合使用。当违反此策略时，启动/重新加载和认证配置解析会快速失败。
  • 对于由 SecretRef 管理的模型提供者，生成的 agents/*/agent/models.json 条目会为 apiKey/header 表面持久化非机密标记（而不是已解析的机密值）。标记持久化以源为权威：OpenClaw 从活动源配置快照（解析前）写入标记，而不是从已解析的运行时机密值写入。
  • 冷 Gateway 启动可以隔离可重试的解析失败，针对已映射的非 Gateway 所有者。当前已映射类别包括模型提供者和技能、媒体/TTS/cron 提供者、符合条件的认证配置、按 agent 的内存、沙箱 SSH、频道账户以及清单声明的插件路由。启动会在运行时快照中保留每个失败所有者的显式引用，通过 status 和 doctor 报告该所有者，并拒绝针对该所有者的请求，而不尝试较低优先级的凭据。重新加载和配置写入预检使用相同的基于所有者的策略：健康的所有者会刷新；符合条件的失败所有者仅在其引用身份、提供者定义和完整的非机密所有者契约未改变时保持陈旧；新的或已改变的失败会变为冷状态。Gateway 入口认证、结构无效的引用或值、fail-closed 所有者以及当前未映射的所有者仍保持严格。
  • 对于网络搜索：在显式提供者模式（设置了 tools.web.search.provider）下，只有所选提供者密钥处于活动状态。在自动模式（未设置 tools.web.search.provider）下，只有按优先级解析的第一个提供者密钥处于活动状态，未选中的提供者引用在选中之前被视为非活动。提供者凭据使用 plugins.entries.<plugin>.config.webSearch.*。
  • Slack identity: "user" 使用 channels.slack.userToken，Socket Mode 搭配 channels.slack.appToken，HTTP mode 搭配 channels.slack.signingSecret。相同配对也适用于 channels.slack.accounts.*；此身份不需要 bot token。

不支持的凭据

这些凭据属于铸造、轮换、会话承载或 OAuth 持久类别，不适合只读外部 SecretRef 解析：

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw