Configura SecretRef en OpenClaw: Guía de credenciales

Gestionar secretos siempre es un dolor de cabeza. No quieres dejar claves expuestas en el código ni complicar tus archivos de configuración con valores que cambian constantemente. Si buscas una forma clara de manejar tus claves de API y tokens, entender cómo funciona SecretRef en OpenClaw te ayudará a mantener todo bajo control.

Esta página define la superficie de credenciales canónica de SecretRef.

Propósito del alcance:

• Dentro del alcance: estrictamente credenciales proporcionadas por el usuario que OpenClaw no genera ni rota.
• Fuera del alcance: credenciales generadas en tiempo de ejecución, material de refresco OAuth, artefactos de sesión y claves rotativas.

Credenciales soportadas

Objetivos de 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)

Objetivos de auth-profiles.json (secrets configure + secrets apply + secrets audit)

• profiles.*.keyRef (type: "api_key"; no soportado cuando auth.profiles.<id>.mode = "oauth")
• profiles.*.tokenRef (type: "token"; no soportado cuando auth.profiles.<id>.mode = "oauth")

Notas:

• Los objetivos del plan de auth-profile requieren agentId.
• Las entradas del plan apuntan a profiles.*.key / profiles.*.token y escriben referencias hermanas (keyRef / tokenRef).
• Las referencias de auth-profile se incluyen en la resolución en tiempo de ejecución y en la cobertura de auditoría.
• Guardia de política OAuth: auth.profiles.<id>.mode = "oauth" no se puede combinar con entradas SecretRef para ese perfil. El inicio/recarga y la resolución de auth-profile fallan rápido cuando se viola esta política.
• Para los proveedores de modelos gestionados por SecretRef, las entradas generadas en agents/*/agent/models.json mantienen marcadores que no son secretos (no los valores resueltos) para las superficies de apiKey o encabezados.
• La persistencia de marcadores depende de la fuente de autoridad: OpenClaw escribe marcadores desde la captura de configuración de la fuente activa (antes de la resolución), no desde los valores de secretos resueltos en tiempo de ejecución.
• Para la búsqueda web:
  • En el modo de proveedor explícito (con tools.web.search.provider configurado), solo la clave del proveedor seleccionado está activa.
  • En modo automático (sin tools.web.search.provider), solo la primera clave de proveedor que se resuelva por precedencia está activa.
  • En modo automático, las referencias de proveedores no seleccionados se tratan como inactivas hasta que se seleccionen.
  • Las rutas de proveedor heredadas tools.web.search.* todavía se resuelven durante la ventana de compatibilidad, pero la superficie canónica de SecretRef es plugins.entries.<plugin>.config.webSearch.*.

Credenciales no soportadas

Las credenciales fuera de alcance incluyen:

• 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

Razón:

• Estas credenciales se generan, rotan, contienen información de sesión o son clases duraderas de OAuth que no encajan con la resolución externa de solo lectura de SecretRef.

AI Setup Assistant

Pasos siguientes

• Configuración de secretos
• Auditoría de credenciales