Saltar al contenido principal

Comandos CLI

secrets

Usa openclaw secrets para gestionar SecretRefs y mantener saludable la instantánea activa del entorno de ejecución. Roles de los comandos:

  • reload: RPC de la puerta de enlace (secrets.reload) que vuelve a resolver las referencias e intercambia la instantánea del entorno de ejecución solo en caso de éxito total (sin escrituras de configuración).
  • audit: escaneo de solo lectura de los almacenes de configuración/autenticación/modelos generados y residuos heredados en busca de texto plano, referencias no resueltas y desviación de precedencia.
  • configure: planificador interactivo para la configuración del proveedor, mapeo de objetivos y verificación previa (se requiere TTY).
  • apply: ejecuta un plan guardado (--dry-run solo para validación) y luego limpia los residuos de texto plano objetivo.

Bucle operativo recomendado:

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 el código de salida para CI/compuertas:

  • audit --check devuelve 1 si encuentra problemas.
  • las referencias no resueltas devuelven 2.

Relacionado:

Recargar instantánea del entorno de ejecución​

Vuelve a resolver las referencias secretas e intercambia atómicamente la instantánea del entorno de ejecución.

openclaw secrets reload
openclaw secrets reload --json

Notas:

  • Utiliza el método RPC de la puerta de enlace secrets.reload.
  • Si la resolución falla, la puerta de enlace mantiene la última instantánea buena 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 no resueltas
  • desviación de precedencia (credenciales de auth-profiles.json que ocultan referencias de openclaw.json)
  • residuos generados en agents/*/agent/models.json (valores apiKey del proveedor y encabezados sensibles del proveedor)
  • residuos heredados (entradas del almacén de autenticación heredado, recordatorios de OAuth)

Nota sobre residuos en encabezados:

  • La detección de encabezados sensibles del proveedor se basa en heurísticas de nombres (nombres comunes de encabezados 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 distinto de cero si encuentra problemas.
  • las referencias no resueltas salen con un código de error de mayor prioridad.

Aspectos destacados de la forma del informe:

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

Configurar (asistente interactivo)​

Construye cambios de proveedor y SecretRef de forma interactiva, ejecuta la verificación previa 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 del proveedor (add/edit/remove para alias de secrets.providers).
  • Segundo, mapeo de credenciales (selecciona campos y asigna referencias {source, provider, id}).
  • Por último, verificación previa y aplicación opcional.

Banderas:

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

Notas:

  • Requiere una TTY interactiva.
  • No se pueden combinar --providers-only con --skip-provider-setup.
  • configure se dirige a campos que contienen secretos en openclaw.json más auth-profiles.json para el ámbito del agente seleccionado.
  • configure admite la creación de nuevos mapeos en auth-profiles.json directamente en el flujo del selector.
  • Superficie compatible canónica: Superficie de Credenciales SecretRef.
  • Realiza una resolución de verificación previa antes de aplicar.
  • Los planes generados tienen habilitadas por defecto las opciones de limpieza (scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson).
  • La ruta de aplicación es unidireccional para los valores en texto plano limpiados.
  • Sin --apply, la CLI aún pregunta ¿Aplicar este plan ahora? después de la verificación previa.
  • Con --apply (y sin --yes), la CLI solicita una confirmación irreversible adicional.

Nota de seguridad del proveedor exec:

  • Las instalaciones de Homebrew a menudo exponen binarios con enlaces simbólicos bajo /opt/homebrew/bin/*.
  • Establece allowSymlinkCommand: true solo cuando sea necesario para rutas confiables del gestor de paquetes, 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 cerrado. Solo para rutas confiables, establece allowInsecurePath: true en ese proveedor para omitir las comprobaciones de seguridad de ruta.

Aplicar un plan guardado​

Aplica o realiza una verificación previa de un plan generado anteriormente:

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):

Lo que apply puede actualizar:

  • openclaw.json (objetivos SecretRef + inserciones/eliminaciones de proveedor)
  • auth-profiles.json (limpieza de objetivos del proveedor)
  • residuos heredados de auth.json
  • ~/.openclaw/.env claves secretas conocidas cuyos valores fueron migrados

Por qué no hay copias de seguridad para revertir​

secrets apply intencionalmente no escribe copias de seguridad de reversión que contengan los antiguos valores en texto plano. La seguridad proviene de una verificación previa estricta + una aplicación casi atómica con restauración en memoria de mejor esfuerzo en caso de fallo.

Ejemplo​

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

Si audit --check aún reporta hallazgos en texto plano, actualiza las rutas objetivo restantes reportadas y vuelve a ejecutar la auditoría.

CLI Sandboxseguridad