openclaw secrets
Gestiona SecretRefs y mantiene saludable la instantánea activa del runtime.
| Comando | Rol |
|---|---|
reload | RPC de Gateway (secrets.reload): vuelve a resolver refs y reemplaza la instantánea del runtime solo si todo tiene éxito (sin escrituras de configuración) |
audit | Escaneo de solo lectura de almacenes de config/auth/generated-model y residuos heredados en busca de texto sin formato, refs sin resolver y desviaciones de precedencia (las refs exec se omiten salvo que se use --allow-exec) |
configure | Planificador interactivo para configuración de proveedores, mapeo de destinos y preflight (requiere una TTY) |
apply | Ejecuta un plan guardado (--dry-run solo valida y omite las comprobaciones exec de forma predeterminada; el modo de escritura rechaza planes que contienen exec salvo que se use --allow-exec) y luego limpia residuos de texto sin formato seleccionados |
exec, pasa --allow-exec tanto en los comandos apply de dry-run como de escritura.
Códigos de salida para CI/compuertas:
audit --checkdevuelve1si hay hallazgos.- Las refs sin resolver devuelven
2(independientemente de--check).
Recargar instantánea del runtime
secrets.reload. Si la resolución falla, el Gateway conserva su última instantánea válida conocida y devuelve un error (sin activación parcial). La respuesta JSON incluye warningCount.
Opciones: --url <url>, --token <token>, --timeout <ms>, --json.
Auditoría
Escanea el estado de OpenClaw en busca de:- almacenamiento de secretos en texto sin formato
- refs sin resolver
- desviación de precedencia (credenciales de
auth-profiles.jsonque eclipsan refs deopenclaw.json) - residuos generados de
agents/*/agent/models.json(valoresapiKeyde proveedores y encabezados sensibles de proveedores) - residuos heredados (entradas heredadas del almacén auth, recordatorios OAuth)
authorization, x-api-key, token, secret, password, credential).
status:clean | findings | unresolvedresolution:refsChecked,skippedExecRefs,resolvabilityCompletesummary:plaintextCount,unresolvedRefCount,shadowedRefCount,legacyResidueCount- códigos de hallazgos:
PLAINTEXT_FOUND,REF_UNRESOLVED,REF_SHADOWED,LEGACY_RESIDUE
Configurar (ayudante interactivo)
Crea cambios de proveedores y SecretRef de forma interactiva, ejecuta preflight y, opcionalmente, aplica:secrets.providers), luego mapeo de credenciales (seleccionar campos, asignar refs {source, provider, id}), después preflight y aplicación opcional.
Flags:
--providers-only: configura solosecrets.providers, omite el mapeo de credenciales--skip-provider-setup: omite la configuración de proveedores, asigna credenciales a proveedores existentes--agent <id>: limita el descubrimiento de destinos y las escrituras deauth-profiles.jsona un almacén de agente--allow-exec: permite comprobaciones exec de SecretRef durante preflight/apply (puede ejecutar comandos de proveedores)
--providers-only y --skip-provider-setup no se pueden combinar.
Notas:
- Requiere una TTY interactiva.
- Apunta a campos que contienen secretos en
openclaw.jsonmásauth-profiles.jsonpara el alcance de agente seleccionado; superficie canónica admitida: Superficie de credenciales SecretRef. - Permite crear nuevos mapeos de
auth-profiles.jsondirectamente en el flujo del selector. - Ejecuta resolución de preflight antes de aplicar.
- Los planes generados activan de forma predeterminada las opciones de limpieza (
scrubEnv,scrubAuthProfilesForProviderTargets,scrubLegacyAuthJson). Apply es unidireccional para valores de texto sin formato limpiados. - Sin
--apply, la CLI aun así preguntaApply this plan now?después de preflight. - Con
--apply(y sin--yes), la CLI solicita una confirmación adicional de migración irreversible. --jsonimprime el plan + informe de preflight, pero aun así requiere una TTY interactiva.
Seguridad de proveedores exec
Las instalaciones de Homebrew suelen exponer binarios enlazados simbólicamente bajo/opt/homebrew/bin/*. Configura allowSymlinkCommand: true solo cuando sea necesario para rutas confiables de gestores de paquetes, junto con trustedDirs (por ejemplo ["/opt/homebrew"]). En Windows, si la verificación de ACL no está disponible para una ruta de proveedor, OpenClaw falla cerrado; solo para rutas confiables, configura allowInsecurePath: true en ese proveedor para omitir la comprobación de seguridad de ruta.
Aplicar un plan guardado
--dry-run valida preflight sin escribir archivos; las comprobaciones exec de SecretRef se omiten de forma predeterminada en dry-run. El modo de escritura rechaza planes que contienen SecretRefs/proveedores exec salvo que se use --allow-exec. Usa --allow-exec para optar por comprobaciones/ejecución de proveedores exec en cualquiera de los modos.
Qué puede actualizar apply:
openclaw.json(destinos SecretRef + inserciones/actualizaciones/eliminaciones de proveedores)auth-profiles.json(limpieza de destinos de proveedores)- residuos heredados de
auth.json - claves secretas conocidas de
~/.openclaw/.envcuyos valores se migraron
Por qué no hay copias de seguridad para rollback
secrets apply intencionadamente no escribe copias de seguridad de rollback que contengan valores antiguos de texto sin formato. La seguridad proviene de un preflight estricto más una aplicación casi atómica, con restauración en memoria de mejor esfuerzo en caso de fallo.
Ejemplo
audit --check aún informa hallazgos de texto sin formato, actualiza las rutas de destino restantes informadas y vuelve a ejecutar la auditoría.