Gestión de secretos en OpenClaw

Gestionar credenciales suele ser frustrante. Guardar API keys en texto plano dentro de tus archivos de configuración es un riesgo de seguridad, pero configurar sistemas externos a veces complica el despliegue o introduce latencia innecesaria. Necesitas una forma de proteger tus datos sensibles sin que cada petición dependa de la disponibilidad de un proveedor de secretos externo.

OpenClaw soluciona esto con SecretRefs. En lugar de escribir la clave directamente, apuntas a una fuente externa. El sistema resuelve estos valores al arrancar y los mantiene en una instantánea en memoria, asegurando que tus rutas críticas de peticiones no se vean afectadas por caídas del proveedor de secretos.

What You’ll Need

• Una instancia de OpenClaw en funcionamiento.
• Acceso a variables de entorno, archivos locales o scripts de ejecución (exec).

Quick Start

Configurar un secreto toma menos de 5 minutos. Aunque el texto plano sigue funcionando, te recomiendo usar SecretRefs por seguridad.

1. Elige tu fuente: Decide si usarás variables de entorno (env), un archivo JSON (file) o un comando externo (exec).
2. Define el objeto: Usa el formato estándar de SecretRef en tu configuración en lugar del string de la credencial.
3. Valida el inicio: Reinicia OpenClaw. El sistema fallará rápido si no puede resolver una referencia activa, evitando errores silenciosos.
4. Verifica el estado: Revisa los logs para confirmar que el secreto se ha cargado en la instantánea de memoria.

Aquí tienes el contrato único que debes usar en cualquier parte de la configuración:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

Formatos admitidos

source: “env”

Ideal para entornos Docker o despliegues rápidos.

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

• El provider debe seguir el patrón ^[a-z][a-z0-9_-]{0,63}$.
• El id debe seguir el patrón ^[A-Z][A-Z0-9_]{0,127}$.

source: “file”

Útil si prefieres leer valores desde un archivo JSON estructurado.

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

• El id debe ser un JSON pointer absoluto (/...).

source: “exec”

Para integraciones personalizadas con gestores como Vault.

{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

• El id admite caracteres como ., :, / y -.

Troubleshooting

El secreto no se carga o aparece como inactivo Si ves el código de diagnóstico SECRETS_REF_IGNORED_INACTIVE_SURFACE, OpenClaw ha detectado que la referencia está en una superficie inactiva (por ejemplo, una cuenta desactivada o un proveedor de búsqueda no seleccionado). En estos casos, el error no bloquea el arranque.

Conflictos en el Gateway Si configuras un SecretRef en gateway.auth.token pero también tienes definida la variable de entorno OPENCLAW_GATEWAY_TOKEN, el secreto será ignorado. Verás el log SECRETS_GATEWAY_AUTH_SURFACE con el estado inactive porque la variable de entorno tiene prioridad.

Fallo en el preflight durante el onboarding Si usas el modo interactivo y la validación falla, OpenClaw te avisará antes de guardar. Esto ocurre si la variable de entorno está vacía o si el JSON pointer en un archivo no es válido. Revisa que los nombres y rutas coincidan exactamente con tu sistema.

Para resolver dudas específicas sobre tu configuración, consulta al AI Setup Assistant.

What’s Next

• Configuración de Gateway
• Guía de proveedores de búsqueda web
• Uso de variables de entorno globales

¿Alguna vez has tenido que lidiar con secretos esparcidos por todos lados? Es un problema común cuando intentas que tu app sea segura pero terminas con un lío de variables de entorno y archivos locales difíciles de gestionar. Configurar bien tus providers te ayuda a mantener el orden y la seguridad sin complicaciones innecesarias.

Te recomiendo definir tus fuentes de forma clara desde el principio para evitar errores de resolución en producción.

Requisitos previos

• Acceso al archivo de configuración bajo la clave secrets.providers.
• Permisos de lectura en las rutas de archivos que planeas usar.
• Binarios con rutas absolutas si vas a usar el provider de ejecución.

Inicio rápido

Configura tus providers en el archivo principal. Aquí tienes un ejemplo con tres tipos de fuentes: entorno, archivo local y un ejecutable externo.

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // or "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
    resolution: {
      maxProviderConcurrency: 4,
      maxRefsPerProvider: 512,
      maxBatchBytes: 262144,
    },
  },
}

Env provider

Es la opción más directa. Puedes usar un allowlist opcional para limitar qué variables son accesibles. Ten en cuenta que si una variable falta o está vacía, la resolución fallará.

File provider

Este provider lee archivos locales desde la ruta definida en path. Tienes dos modos de operación:

• mode: "json": Espera un objeto JSON y resuelve el id como un puntero dentro de ese objeto.
• mode: "singleValue": Espera que el ref id sea "value" y devuelve todo el contenido del archivo.

La ruta debe pasar comprobaciones de propiedad y permisos. En Windows, si la verificación de ACL no está disponible, la resolución fallará por seguridad. Si usas rutas de confianza, puedes saltarte esto con allowInsecurePath: true.

Exec provider

Ejecuta un binario en una ruta absoluta sin usar shell. Por defecto, el command debe ser un archivo regular y no un symlink.

Si necesitas usar symlinks (por ejemplo, con Homebrew), activa allowSymlinkCommand: true. Te sugiero combinar esto con trustedDirs para rutas conocidas como ["/opt/homebrew"]. Este provider soporta límites de tiempo (timeout), límites de bytes de salida y listas de variables de entorno permitidas.

En Windows, al igual que con los archivos, si la verificación de ACL falla, la ejecución se detiene a menos que uses allowInsecurePath: true.

Request payload (stdin):

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

Response payload (stdout):

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

Si necesitas reportar errores específicos por ID:

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "message": "not found" } }
}

Solución de problemas

• Error de resolución en Env: Verifica que la variable no esté vacía en tu entorno actual.
• Fallo de ACL en Windows: Comprueba los permisos de la ruta o usa la flag allowInsecurePath: true si la ruta es segura.
• Comando no encontrado en Exec: Asegúrate de que command sea una ruta absoluta y no un symlink, o activa allowSymlinkCommand.
• Timeout en Exec: Revisa si el binario externo requiere interacción del usuario o si el límite de tiempo configurado es demasiado bajo.

Para resolver dudas específicas sobre tu configuración, prueba el AI Setup Assistant.

Próximos pasos

• Secret resolution lifecycle
• Security best practices

¿Te ha pasado que tienes tus secretos esparcidos por todos lados? Gestionar API keys manualmente es un riesgo y una pérdida de tiempo. Lo mejor es centralizar todo en herramientas que ya usas, permitiendo que tu configuración obtenga los valores automáticamente sin exponerlos en texto plano.

Si ya utilizas herramientas de línea de comandos para gestionar tus credenciales, no deberías copiarlas y pegarlas en tus archivos de configuración cada vez que rotan. La integración exec te permite extraer esos valores directamente desde tu CLI de confianza de forma segura y eficiente.

Requisitos previos

• Configuración de secrets definida en tu archivo de proveedores.
• Las herramientas CLI instaladas en tu sistema (como op, vault o sops).

Inicio rápido

Para empezar a usar secretos dinámicos, debes configurar el source como exec dentro de tus providers. Aquí tienes los ejemplos más comunes para implementar esta solución en pocos minutos.

1Password CLI

Si usas 1Password, puedes extraer valores específicos usando su ruta de referencia. Es importante definir los trustedDirs para que la ejecución sea segura.

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
      },
    },
  },
}

HashiCorp Vault CLI

Para entornos que dependen de Vault, puedes configurar el comando para que consulte el motor de secretos KV (Key-Value). Asegúrate de pasar las variables de entorno necesarias para la autenticación.

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "vault_openai", id: "value" },
      },
    },
  },
}

sops

Si prefieres mantener tus secretos cifrados en archivos dentro de tu repositorio, sops es la opción ideal. Puedes extraer una llave específica de un archivo JSON cifrado indicando la ruta exacta.

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "sops_openai", id: "value" },
      },
    },
  },
}

Solución de problemas

El comando falla al intentar ejecutar binarios de Homebrew Si estás en macOS y usas Homebrew, los binarios suelen ser symlinks. Para que funcionen, debes establecer allowSymlinkCommand: true y añadir el path /opt/homebrew a la lista de trustedDirs.

Faltan permisos o variables de entorno Si tu CLI requiere autenticación (como VAULT_TOKEN o HOME para 1Password), verifica que estas variables estén incluidas en el array passEnv. Sin ellas, el proceso exec no tendrá el contexto necesario para ejecutarse.

¿Necesitas ayuda con una configuración específica? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Configuración avanzada de Secrets
• Gestión de Model Providers

---
title: Gestión de credenciales mediante SecretRef en el Gateway
description: Aprende cómo OpenClaw maneja la resolución de secretos, las reglas de precedencia y el comportamiento del sistema ante fallos de activación.
---

Gestionar secretos y credenciales suele ser un dolor de cabeza constante. Siempre está ese miedo de que una rotación de claves rompa la producción o de que una configuración en texto plano termine donde no debe, creando conflictos difíciles de rastrear.

La idea es que tus credenciales funcionen de forma predecible, ya sea durante el arranque del Gateway o cuando necesitas consultar el estado de tus canales desde la CLI. Aquí te explico cómo OpenClaw maneja estas superficies de credenciales para que no tengas que adivinar qué valor se está usando.

## Requisitos previos

- Tener claro cuáles son las [Superficies de credenciales SecretRef](/docs/reference/secretref-credential-surface) soportadas.
- Acceso a la CLI de OpenClaw.
- Un Gateway configurado con archivos `openclaw.json` o `auth-profiles.json`.

## Inicio rápido

Para poner en marcha la resolución de secretos en menos de 5 minutos, sigue estas reglas:

1.  **Prioriza los Refs**: Si un campo tiene un `ref` y un valor en texto plano, el `ref` siempre ganará en las rutas de precedencia soportadas.
2.  **Configuración en Google Chat**: Usa `serviceAccountRef`. Si lo configuras, el sistema ignorará automáticamente cualquier valor que pongas en `serviceAccount` (texto plano).
3.  **Carga de cambios**: Si rotas un secreto en el backend, ejecuta el comando de recarga manual:
    ```bash
    openclaw secrets reload

4. Verificación de estado: Ejecuta openclaw status para comprobar si el snapshot activo tiene los secretos disponibles.

Comportamiento y Precedencia

El sistema sigue reglas estrictas para decidir qué credencial usar. Si un campo no tiene un ref, se queda como está. Pero si hay un ref presente, este es obligatorio en las superficies activas durante la activación.

Ten cuidado con las señales de auditoría:

• SECRETS_REF_OVERRIDES_PLAINTEXT: Una advertencia en runtime que te avisa que el ref está mandando sobre el texto plano.
• REF_SHADOWED: Esto ocurre cuando las credenciales de auth-profiles.json tienen prioridad sobre los refs definidos en openclaw.json.

Activación de Secretos

La activación de secretos no ocurre solo una vez. El Gateway la ejecuta en estos momentos:

• Al iniciar (validación preflight y activación final).
• Al hacer un hot-apply de la configuración.
• Durante las comprobaciones de reinicio por cambio de config.
• Cuando usas el método RPC secrets.reload.

Si la activación tiene éxito, el snapshot se cambia de forma atómica. Si falla al arrancar, el Gateway se detiene por seguridad. Si falla durante una recarga en runtime, el sistema mantiene el último snapshot conocido que funcionaba bien (last-known-good).

Resolución en comandos de la CLI

Los comandos de la CLI se comportan de dos formas distintas según lo que intentes hacer:

Rutas estrictas

Comandos como openclaw memory (rutas de memoria remota) o openclaw qr --remote leen directamente del snapshot activo. Si un SecretRef requerido no está disponible, el comando fallará inmediatamente.

Rutas de solo lectura

Comandos como openclaw status, openclaw status --all, openclaw channels status o openclaw channels resolve son más flexibles:

• Intentan leer del snapshot activo del Gateway.
• Si el Gateway no está disponible, buscan un fallback local específico.
• Si aun así no encuentran el secreto, el comando no se detiene; muestra un mensaje de diagnóstico indicando que el secreto está “configurado pero no disponible en esta ruta de comando”.

Solución de problemas

Si encuentras problemas con la recarga de secretos, busca estos códigos en los logs:

• SECRETS_RELOADER_DEGRADED: El sistema entra en estado degradado si una recarga falla después de haber estado en un estado saludable. El runtime seguirá usando el último snapshot válido.
• SECRETS_RELOADER_RECOVERED: Aparece una sola vez cuando el sistema logra una activación exitosa después de haber estado degradado.

Recuerda que si el sistema ya está degradado y las recargas siguen fallando, verás advertencias en los logs, pero no se generarán eventos repetidos para evitar el spam.

¿Necesitas ayuda para configurar tus SecretRef? Prueba nuestro AI Setup Assistant.

Próximos pasos

• SecretRef Credential Surface
• Configuración de auth-profiles.json
• Guía de rotación de secretos
• Referencia de la CLI de OpenClaw

```mdx
---
title: Auditoría y configuración del flujo de trabajo de secretos
description: Guía técnica para auditar, configurar y aplicar secretos de forma segura en OpenClaw utilizando la CLI.
---

¿Alguna vez has revisado tus archivos de configuración y has encontrado una clave de API en texto plano que olvidaste borrar? Es un riesgo común que puede comprometer la seguridad de tu proyecto. Gestionar credenciales no debería ser un proceso manual propenso a errores.

Mantener tus secretos limpios y referenciados correctamente es vital para que tu Gateway funcione sin exponer datos sensibles en el sistema de archivos.

### What You'll Need

- CLI de OpenClaw instalada y configurada.
- Archivos de configuración locales (`openclaw.json`, `auth-profiles.json` o `.env`).
- Acceso a la terminal en el directorio de tu proyecto.

### Quick Start

Puedes limpiar y asegurar tu entorno en menos de 5 minutos siguiendo este flujo de trabajo estándar:

```bash
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

secrets audit

Este comando analiza tu configuración en busca de vulnerabilidades. Los hallazgos incluyen:

• Valores en texto plano en reposo (openclaw.json, auth-profiles.json, .env y el archivo generado agents/*/agent/models.json).
• Residuos de headers de proveedores sensibles en las entradas de models.json.
• Referencias sin resolver (unresolved refs).
• Conflictos de precedencia (por ejemplo, cuando auth-profiles.json tiene prioridad sobre las referencias de openclaw.json).
• Residuos de sistemas antiguos (auth.json, recordatorios de OAuth).

Nota sobre residuos de headers: La detección de headers sensibles se basa en una heurística de nombres. Busca fragmentos comunes como authorization, x-api-key, token, secret, password y credential.

secrets configure

Es un asistente interactivo que te ayuda a organizar tus credenciales. Sus funciones principales son:

• Configura primero secrets.providers (env, file o exec).
• Te permite seleccionar campos que contienen secretos en openclaw.json y auth-profiles.json para el alcance de un agent.
• Puede crear un nuevo mapeo en auth-profiles.json directamente desde el selector.
• Captura los detalles de SecretRef (source, provider, id).
• Ejecuta una resolución de prueba (preflight) y permite aplicar los cambios de inmediato.

Puedes usar estos modos según lo que necesites:

• openclaw secrets configure --providers-only
• openclaw secrets configure --skip-provider-setup
• openclaw secrets configure --agent <id>

Al aplicar los cambios, el comando realiza estas acciones por defecto:

1. Elimina las credenciales estáticas que coincidan en auth-profiles.json.
2. Borra entradas estáticas antiguas de api_key en auth.json.
3. Limpia las líneas de secretos conocidos en el archivo <config-dir>/.env.

secrets apply

Si prefieres trabajar con planes guardados, usa este comando para ejecutar las modificaciones:

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

Para conocer los detalles exactos del contrato de rutas y las reglas de rechazo, consulta el Secrets Apply Plan Contract.

Política de seguridad de una sola vía

OpenClaw no escribe copias de seguridad (rollbacks) que contengan valores históricos de secretos en texto plano. Es una decisión de diseño para proteger tus datos.

El modelo de seguridad funciona así:

• La fase de preflight debe tener éxito antes de entrar en modo de escritura.
• La activación en runtime se valida antes de confirmar los cambios (commit).
• Los archivos se actualizan mediante reemplazo atómico y se intenta restaurar el estado anterior solo en caso de fallo técnico durante la escritura.

Notas de compatibilidad con auth antiguo

Para las credenciales estáticas, el runtime ya no depende del almacenamiento de autenticación antiguo en texto plano.

• La fuente de credenciales en runtime es una instantánea resuelta en memoria.
• Las entradas api_key estáticas heredadas se eliminan en cuanto se detectan.
• El comportamiento de compatibilidad relacionado con OAuth se mantiene por separado.

Nota sobre la Web UI

Ten en cuenta que algunas uniones de SecretInput son más sencillas de configurar usando el modo de edición de código (raw editor) que mediante los formularios de la interfaz.

Troubleshooting

• Unresolved refs: Si secrets audit detecta referencias sin resolver, verifica que el provider esté correctamente definido en tu configuración de secretos.
• Precedence shadowing: Si los cambios no surten efecto, comprueba si auth-profiles.json está sobrescribiendo los valores de openclaw.json.
• Header residue: Si aparecen alertas de headers en models.json, ejecuta secrets configure para limpiar los restos de credenciales en los archivos generados.
• Legacy residues: Si aún ves archivos como auth.json, el comando configure te ayudará a eliminarlos de forma segura.

Si necesitas ayuda personalizada con tu configuración, consulta al AI Setup Assistant.

What’s Next

• CLI commands: secrets
• Plan contract details: Secrets Apply Plan Contract
• Credential surface: SecretRef Credential Surface
• Auth setup: Authentication
• Security posture: Security
• Environment precedence: Environment Variables