Cómo gestionar SecretRefs con openclaw secrets

Gestionar credenciales suele ser un proceso manual y propenso a errores. Es común terminar con claves en texto plano esparcidas en archivos de configuración o sufrir interrupciones porque un cambio en los secretos no se sincronizó correctamente con el servicio activo.

openclaw secrets resuelve esto permitiéndote auditar, configurar y aplicar cambios de forma segura. Este comando ayuda a que tu Gateway mantenga un estado saludable mediante el uso de SecretRefs, evitando fugas de información sensible.

Requisitos previos

• Acceso a la CLI de openclaw.
• Una terminal interactiva (TTY) para el asistente de configuración.
• Archivos de configuración locales (openclaw.json o auth-profiles.json).
• Permisos de escritura en el sistema de archivos para aplicar cambios.

Inicio rápido

Usa este flujo de trabajo recomendado para auditar tu estado actual, mapear secretos y actualizar el Gateway en 5 minutos:

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

Comandos principales

• audit: Escanea archivos de configuración y almacenes de autenticación en busca de texto plano, referencias sin resolver o conflictos de precedencia.
• configure: Un planificador interactivo para configurar providers y mapear credenciales.
• apply: Ejecuta un plan guardado y elimina los residuos de texto plano detectados.
• reload: Ejecuta una llamada RPC (secrets.reload) al Gateway para actualizar los secretos en memoria sin reiniciar el proceso.

Detalles de los comandos

Audit

Este comando busca riesgos de seguridad como el almacenamiento de secretos en texto plano o el “precedence drift” (cuando las credenciales en auth-profiles.json ocultan a las de openclaw.json).

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json

Notas sobre códigos de salida:

• --check devuelve 1 si encuentra problemas.
• Si existen referencias sin resolver, devuelve 2.

Configure (Asistente interactivo)

Crea planes para cambios en providers y SecretRefs. Este comando requiere una terminal interactiva (TTY).

openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --agent ops

Flags útiles:

• --providers-only: Configura solo los alias en secrets.providers.
• --skip-provider-setup: Salta la creación de providers y mapea credenciales a los existentes.
• --agent <id>: Limita el descubrimiento y escritura a un agente específico.

Apply

Aplica un plan generado previamente. Es un proceso de una sola vía para los valores que se limpian (scrubbed).

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

apply puede actualizar openclaw.json, auth-profiles.json, archivos .env conocidos y eliminar residuos en auth.json.

Reload

Actualiza el snapshot del runtime de forma atómica. Si la resolución de secretos falla, el Gateway mantiene el último snapshot conocido como bueno y devuelve un error.

openclaw secrets reload

Seguridad en entornos específicos

Para providers de tipo exec, ten en cuenta lo siguiente:

• Homebrew (macOS): Si usas binarios en /opt/homebrew/bin/, activa allowSymlinkCommand: true y añade la ruta a trustedDirs.
• Windows: Si la verificación de ACL no está disponible, el sistema fallará por seguridad. Puedes usar allowInsecurePath: true solo en rutas de confianza para omitir esta verificación.

Solución de problemas

• Hallazgos de texto plano persistentes: Si después de ejecutar apply, el comando audit --check sigue reportando problemas, debes actualizar manualmente las rutas de los archivos indicados en el reporte y repetir la auditoría.
• Fallas en Reload: Revisa el conteo de warningCount en la respuesta JSON. Si el Gateway no puede resolver una referencia, no activará el nuevo snapshot para evitar estados inconsistentes.
• Backups: secrets apply no crea copias de seguridad con los valores antiguos en texto plano por diseño. La seguridad se basa en el preflight estricto antes de la aplicación.

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

Próximos pasos

• Secrets Management
• SecretRef Credential Surface
• Security Guide
• Secrets Apply Plan Contract