OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

Secretos

openclaw secrets

Gestiona las SecretRefs y mantén en buen estado la instantánea activa del entorno de ejecución.

Comando Función
reload RPC del Gateway (secrets.reload): vuelve a resolver las referencias y sustituye la instantánea del entorno de ejecución solo si todo se completa correctamente (sin escribir en la configuración)
audit Análisis de solo lectura de los almacenes de configuración, autenticación y modelos generados, así como de residuos heredados, para detectar texto sin formato, referencias sin resolver y desviaciones de precedencia (se omiten las referencias exec salvo que se use --allow-exec)
configure Planificador interactivo para configurar proveedores, asignar destinos y realizar la comprobación previa (requiere una TTY)
apply Ejecuta un plan guardado (--dry-run solo valida y omite de forma predeterminada las comprobaciones exec; el modo de escritura rechaza los planes que contienen exec salvo que se use --allow-exec) y después elimina los residuos de texto sin formato seleccionados

Ciclo recomendado para operadores:

bash
openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets audit --checkopenclaw secrets reload

Si tu plan incluye SecretRefs o proveedores exec, pasa --allow-exec tanto al comando apply de simulación como al de escritura.

Códigos de salida para CI y controles:

  • audit --check devuelve 1 cuando se detectan hallazgos.
  • Las referencias sin resolver devuelven 2 (independientemente de --check).

Relacionado: Gestión de secretos · Superficie de credenciales SecretRef · Seguridad

Recargar la instantánea del entorno de ejecución

bash
openclaw secrets reloadopenclaw secrets reload --jsonopenclaw secrets reload --url ws://127.0.0.1:18789 --token <token>

Utiliza el método RPC del Gateway secrets.reload. Si falla la resolución, 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

Analiza el estado de OpenClaw para detectar:

  • almacenamiento de secretos en texto sin formato
  • referencias sin resolver
  • desviación de precedencia (credenciales de auth-profiles.json que prevalecen sobre las referencias de openclaw.json)
  • residuos de archivos agents/*/agent/models.json generados (valores apiKey de proveedores y encabezados sensibles de proveedores)
  • residuos heredados (entradas del almacén de autenticación heredado y recordatorios de OAuth)

La detección de encabezados sensibles de proveedores se basa en una heurística de nombres: marca los encabezados cuyo nombre coincide con fragmentos habituales de autenticación o credenciales (authorization, x-api-key, token, secret, password, credential).

bash
openclaw secrets auditopenclaw secrets audit --checkopenclaw secrets audit --jsonopenclaw secrets audit --allow-exec

Estructura del informe:

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

Configuración (asistente interactivo)

Crea de forma interactiva cambios en proveedores y SecretRefs, ejecuta la comprobación previa y, opcionalmente, los aplica:

bash
openclaw secrets configureopenclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.jsonopenclaw secrets configure --apply --yesopenclaw secrets configure --providers-onlyopenclaw secrets configure --skip-provider-setupopenclaw secrets configure --agent opsopenclaw secrets configure --json

Flujo: primero se configuran los proveedores (añadir, editar o eliminar alias de secrets.providers), después se asignan las credenciales (seleccionar campos y asignar referencias {source, provider, id}) y, por último, se realiza la comprobación previa y la aplicación opcional.

Opciones:

  • --providers-only: configura únicamente secrets.providers y omite la asignación de credenciales
  • --skip-provider-setup: omite la configuración de proveedores y asigna las credenciales a proveedores existentes
  • --agent <id>: limita la detección de destinos y las escrituras de auth-profiles.json al almacén de un agente
  • --allow-exec: permite comprobaciones de SecretRefs exec durante la comprobación previa o la aplicación (puede ejecutar comandos de proveedores)

--providers-only y --skip-provider-setup no pueden combinarse.

Notas:

  • Requiere una TTY interactiva.
  • Selecciona campos que contienen secretos en openclaw.json, además de auth-profiles.json para el ámbito de agente elegido; superficie canónica compatible: Superficie de credenciales SecretRef.
  • Permite crear nuevas asignaciones de auth-profiles.json directamente en el flujo del selector.
  • Ejecuta una resolución previa antes de aplicar los cambios.
  • Los planes generados activan de forma predeterminada las opciones de depuración (scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson). La aplicación es irreversible para los valores en texto sin formato eliminados.
  • Sin --apply, la CLI sigue mostrando la pregunta Apply this plan now? después de la comprobación previa.
  • Con --apply (y sin --yes), la CLI solicita una confirmación adicional para la migración irreversible.
  • --json imprime el plan y el informe de comprobación previa, pero sigue requiriendo una TTY interactiva.

Seguridad de los proveedores exec

Las instalaciones de Homebrew suelen exponer binarios mediante enlaces simbólicos en /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 la ruta de un proveedor, OpenClaw adopta una política de rechazo seguro; únicamente para rutas de confianza, establece allowInsecurePath: true en ese proveedor para omitir la comprobación de seguridad de la ruta.

Aplicar un plan guardado

bash
openclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

--dry-run valida la comprobación previa sin escribir archivos; las comprobaciones de SecretRefs exec se omiten de forma predeterminada durante la simulación. El modo de escritura rechaza los planes que contienen SecretRefs o proveedores exec salvo que se use --allow-exec. Usa --allow-exec para aceptar explícitamente las comprobaciones o la ejecución de proveedores exec en cualquiera de los modos.

Elementos que apply puede actualizar:

  • openclaw.json (destinos SecretRef, además de inserciones, actualizaciones y eliminaciones de proveedores)
  • auth-profiles.json (eliminación de datos en destinos de proveedores)
  • residuos del archivo auth.json heredado
  • claves de secretos conocidas de ~/.openclaw/.env cuyos valores se hayan migrado

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

Por qué no hay copias de seguridad para revertir cambios

secrets apply no escribe deliberadamente copias de seguridad para revertir cambios que contengan valores antiguos en texto sin formato. La seguridad procede de una comprobación previa estricta y de una aplicación casi atómica, con un restablecimiento en memoria sujeto al mejor esfuerzo en caso de fallo.

Ejemplo

bash
openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets audit --check

Si audit --check sigue notificando hallazgos de texto sin formato, actualiza las rutas de destino restantes indicadas y vuelve a ejecutar la auditoría.

Temas relacionados

Was this useful?
On this page

On this page