openclaw secrets

Usa openclaw secrets para gestionar SecretRefs y mantener saludable la instantánea activa del runtime.

Roles de los comandos:

• reload: RPC del gateway (secrets.reload) que vuelve a resolver las referencias y reemplaza la instantánea del runtime solo si todo se resuelve correctamente (sin escrituras de configuración).
• audit: escaneo de solo lectura de los almacenes de configuración/autenticación/modelos generados y residuos legacy en busca de texto plano, referencias sin resolver y desviación de precedencia.
• configure: planificador interactivo para la configuración de proveedores, mapeo de destinos y preflight (requiere TTY).
• apply: ejecuta un plan guardado (--dry-run para solo validación), luego limpia los residuos de texto plano seleccionados.

Ciclo recomendado para operadores:

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

Nota sobre códigos de salida para CI/gates:

• audit --check devuelve 1 si hay hallazgos.
• Las referencias sin resolver devuelven 2.

Relacionado:

• Guía de secretos: Secrets Management
• Superficie de credenciales: SecretRef Credential Surface
• Guía de seguridad: Security

Recargar instantánea del runtime

Vuelve a resolver las referencias de secretos y reemplaza la instantánea del runtime de forma atómica.

openclaw secrets reload
openclaw secrets reload --json

Notas:

• Usa el método RPC del gateway secrets.reload.
• Si la resolución falla, el gateway mantiene la última instantánea válida conocida y devuelve un error (sin activación parcial).
• La respuesta JSON incluye warningCount.

Auditoría

Escanea el estado de OpenClaw en busca de:

• almacenamiento de secretos en texto plano
• referencias sin resolver
• desviación de precedencia (credenciales en auth-profiles.json que ocultan las referencias de openclaw.json)
• residuos generados en agents/*/agent/models.json (valores de apiKey de proveedor y encabezados sensibles del proveedor)
• residuos legacy (entradas del almacén de autenticación legacy, recordatorios OAuth)

Nota sobre residuos de encabezados:

• La detección de encabezados sensibles del proveedor se basa en heurísticas de nombre (nombres de encabezados comunes de autenticación/credenciales y fragmentos como authorization, x-api-key, token, secret, password y credential).

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

Comportamiento de salida:

• --check sale con código no cero si hay hallazgos.
• Las referencias sin resolver salen con un código no cero de mayor prioridad.

Aspectos destacados del formato del informe:

• status: clean | findings | unresolved
• summary: plaintextCount, unresolvedRefCount, shadowedRefCount, legacyResidueCount
• códigos de hallazgo:
  • PLAINTEXT_FOUND
  • REF_UNRESOLVED
  • REF_SHADOWED
  • LEGACY_RESIDUE

Configure (asistente interactivo)

Construye cambios de proveedor y SecretRef de forma interactiva, ejecuta preflight y opcionalmente aplica:

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

Flujo:

• Primero configuración de proveedores (add/edit/remove para los alias de secrets.providers).
• Segundo mapeo de credenciales (seleccionar campos y asignar referencias {source, provider, id}).
• Por último preflight y aplicación opcional.

Flags:

• --providers-only: configura solo secrets.providers, omite el mapeo de credenciales.
• --skip-provider-setup: omite la configuración de proveedores y mapea credenciales a proveedores existentes.
• --agent <id>: limita el descubrimiento y las escrituras de destinos de auth-profiles.json a un almacén de agente.

Notas:

• Requiere un TTY interactivo.
• No se puede combinar --providers-only con --skip-provider-setup.
• configure apunta a campos que contienen secretos en openclaw.json más auth-profiles.json para el alcance de agente seleccionado.
• configure soporta la creación de nuevos mapeos de auth-profiles.json directamente en el flujo del selector.
• Superficie soportada canónica: SecretRef Credential Surface.
• Realiza resolución de preflight antes de aplicar.
• Los planes generados tienen las opciones de limpieza activadas por defecto (scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson todos activados).
• La ruta de aplicación es irreversible para los valores de texto plano limpiados.
• Sin --apply, el CLI aún pregunta Apply this plan now? después del preflight.
• Con --apply (y sin --yes), el CLI solicita una confirmación adicional irreversible.

Nota de seguridad del proveedor exec:

• Las instalaciones de Homebrew a menudo exponen binarios enlazados simbólicamente bajo /opt/homebrew/bin/*.
• Establece allowSymlinkCommand: true solo cuando sea necesario para rutas de gestores de paquetes de confianza, y combínalo con trustedDirs (por ejemplo ["/opt/homebrew"]).
• En Windows, si la verificación de ACL no está disponible para una ruta de proveedor, OpenClaw falla de forma cerrada. Solo para rutas de confianza, establece allowInsecurePath: true en ese proveedor para omitir las verificaciones de seguridad de ruta.

Aplicar un plan guardado

Aplica o realiza preflight de un plan generado previamente:

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

Detalles del contrato del plan (rutas de destino permitidas, reglas de validación y semántica de fallos):

• Secrets Apply Plan Contract

Lo que apply puede actualizar:

• openclaw.json (destinos SecretRef + upserts/deletes de proveedor)
• auth-profiles.json (limpieza de destinos de proveedor)
• residuos legacy de auth.json
• claves secretas conocidas en ~/.openclaw/.env cuyos valores fueron migrados

Por qué no hay backups de rollback

secrets apply intencionalmente no escribe backups de rollback que contengan valores anteriores en texto plano.

La seguridad viene de un preflight estricto + aplicación cuasi-atómica con restauración best-effort en memoria en caso de fallo.

Ejemplo

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

Si audit --check sigue reportando hallazgos de texto plano, actualiza las rutas de destino reportadas restantes y vuelve a ejecutar la auditoría.