​

Gestión de secretos

​

Objetivos y modelo de tiempo de ejecución

• La resolución es anticipada durante la activación, no diferida en las rutas de solicitud.
• El arranque falla rápidamente cuando un SecretRef efectivamente activo no puede resolverse.
• La recarga usa intercambio atómico: éxito completo o conservación de la última instantánea válida conocida.
• Las infracciones de política de SecretRef (por ejemplo, perfiles de autenticación en modo OAuth combinados con entrada SecretRef) hacen fallar la activación antes del intercambio de la instantánea de tiempo de ejecución.
• Las solicitudes de tiempo de ejecución leen solo desde la instantánea activa en memoria.
• Después de la primera activación/carga correcta de configuración, las rutas de código de tiempo de ejecución siguen leyendo esa instantánea activa en memoria hasta que una recarga correcta la reemplace.
• Las rutas de entrega saliente también leen de esa instantánea activa (por ejemplo, entrega de respuestas/hilos de Discord y envíos de acciones de Telegram); no vuelven a resolver SecretRef en cada envío.

​

Filtrado de superficies activas

• Superficies habilitadas: las referencias no resueltas bloquean el arranque/la recarga.
• Superficies inactivas: las referencias no resueltas no bloquean el arranque/la recarga.
• Las referencias inactivas emiten diagnósticos no fatales con el código SECRETS_REF_IGNORED_INACTIVE_SURFACE.

• Entradas de canal/cuenta deshabilitadas.
• Credenciales de canal de nivel superior que ninguna cuenta habilitada hereda.
• Superficies de herramientas/funciones deshabilitadas.
• Claves específicas de proveedor de búsqueda web que no están seleccionadas por tools.web.search.provider. En modo automático (sin proveedor definido), las claves se consultan por precedencia para la detección automática de proveedor hasta que una se resuelve. Después de la selección, las claves de proveedores no seleccionados se tratan como inactivas hasta ser seleccionadas.
• El material de autenticación SSH del sandbox (agents.defaults.sandbox.ssh.identityData, certificateData, knownHostsData, más los reemplazos por agente) está activo solo cuando el backend efectivo del sandbox es ssh para el agente predeterminado o un agente habilitado.
• gateway.remote.token / gateway.remote.password SecretRef están activos si se cumple una de estas condiciones:
  • gateway.mode=remote
  • gateway.remote.url está configurado
  • gateway.tailscale.mode es serve o funnel
  • En modo local sin esas superficies remotas:
    • gateway.remote.token está activo cuando la autenticación por token puede ganar y no hay token de entorno/autenticación configurado.
    • gateway.remote.password está activo solo cuando la autenticación por contraseña puede ganar y no hay contraseña de entorno/autenticación configurada.
• gateway.auth.token SecretRef está inactivo para la resolución de autenticación de arranque cuando OPENCLAW_GATEWAY_TOKEN está definido, porque la entrada de token de entorno tiene prioridad para ese tiempo de ejecución.

​

Diagnósticos de la superficie de autenticación del gateway

• active: el SecretRef forma parte de la superficie efectiva de autenticación y debe resolverse.
• inactive: el SecretRef se ignora para este tiempo de ejecución porque gana otra superficie de autenticación, o porque la autenticación remota está deshabilitada/no activa.

​

Comprobación previa de referencias en la incorporación

• Referencias de entorno: valida el nombre de la variable de entorno y confirma que un valor no vacío sea visible durante la configuración.
• Referencias de proveedor (file o exec): valida la selección del proveedor, resuelve id y comprueba el tipo de valor resuelto.
• Ruta de reutilización Quickstart: cuando gateway.auth.token ya es un SecretRef, la incorporación lo resuelve antes del arranque de sonda/dashboard (para referencias env, file y exec) usando la misma barrera de fallo rápido.

​

Contrato de SecretRef

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

​

source: "env"

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

• provider debe coincidir con ^[a-z][a-z0-9_-]{0,63}$
• id debe coincidir con ^[A-Z][A-Z0-9_]{0,127}$

​

source: "file"

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

• provider debe coincidir con ^[a-z][a-z0-9_-]{0,63}$
• id debe ser un puntero JSON absoluto (/...)
• Escape RFC6901 en segmentos: ~ => ~0, / => ~1

​

source: "exec"

{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

• provider debe coincidir con ^[a-z][a-z0-9_-]{0,63}$
• id debe coincidir con ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• id no debe contener . ni .. como segmentos de ruta delimitados por barra (por ejemplo, a/../b se rechaza)

​

Configuración del proveedor

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // o "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
    resolution: {
      maxProviderConcurrency: 4,
      maxRefsPerProvider: 512,
      maxBatchBytes: 262144,
    },
  },
}

​

Proveedor env

• Allowlist opcional mediante allowlist.
• Los valores de entorno faltantes o vacíos hacen fallar la resolución.

​

Proveedor file

• Lee un archivo local desde path.
• mode: "json" espera una carga de objeto JSON y resuelve id como puntero.
• mode: "singleValue" espera el id de referencia "value" y devuelve el contenido del archivo.
• La ruta debe pasar comprobaciones de propiedad/permisos.
• Nota de cierre por fallo en Windows: si la verificación de ACL no está disponible para una ruta, la resolución falla. Solo para rutas de confianza, establece allowInsecurePath: true en ese proveedor para omitir las comprobaciones de seguridad de la ruta.

​

Proveedor exec

• Ejecuta la ruta binaria absoluta configurada, sin shell.
• De forma predeterminada, command debe apuntar a un archivo normal (no un symlink).
• Define allowSymlinkCommand: true para permitir rutas de comando symlink (por ejemplo, shims de Homebrew). OpenClaw valida la ruta del destino resuelto.
• Combina allowSymlinkCommand con trustedDirs para rutas del gestor de paquetes (por ejemplo ["/opt/homebrew"]).
• Admite tiempo de espera, tiempo de espera sin salida, límites de bytes de salida, allowlist de entorno y directorios de confianza.
• Nota de cierre por fallo en Windows: si la verificación de ACL no está disponible para la ruta del comando, la resolución falla. Solo para rutas de confianza, establece allowInsecurePath: true en ese proveedor para omitir las comprobaciones de seguridad de la ruta.

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "message": "not found" } }
}

​

Ejemplos de integración exec

​

1Password CLI

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // requerido para binarios con symlink de Homebrew
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
      },
    },
  },
}

​

HashiCorp Vault CLI

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // requerido para binarios con symlink de Homebrew
        trustedDirs: ["/opt/homebrew"],
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "vault_openai", id: "value" },
      },
    },
  },
}

​

sops

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // requerido para binarios con symlink de Homebrew
        trustedDirs: ["/opt/homebrew"],
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "sops_openai", id: "value" },
      },
    },
  },
}

​

Variables de entorno del servidor MCP

{
  plugins: {
    entries: {
      acpx: {
        enabled: true,
        config: {
          mcpServers: {
            github: {
              command: "npx",
              args: ["-y", "@modelcontextprotocol/server-github"],
              env: {
                GITHUB_PERSONAL_ACCESS_TOKEN: {
                  source: "env",
                  provider: "default",
                  id: "MCP_GITHUB_PAT",
                },
              },
            },
          },
        },
      },
    },
  },
}

​

Material de autenticación SSH del sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        ssh: {
          target: "user@gateway-host:22",
          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

• OpenClaw resuelve estas referencias durante la activación del sandbox, no de forma diferida en cada llamada SSH.
• Los valores resueltos se escriben en archivos temporales con permisos restrictivos y se usan en la configuración SSH generada.
• Si el backend efectivo del sandbox no es ssh, estas referencias permanecen inactivas y no bloquean el arranque.

​

Superficie de credenciales compatible

• SecretRef Credential Surface

​

Comportamiento requerido y precedencia

• Campo sin referencia: sin cambios.
• Campo con referencia: obligatorio en superficies activas durante la activación.
• Si están presentes tanto texto sin formato como referencia, la referencia tiene prioridad en las rutas de precedencia compatibles.
• El centinela de redacción __OPENCLAW_REDACTED__ está reservado para redacción/restauración interna de configuración y se rechaza como dato literal enviado de configuración.

• SECRETS_REF_OVERRIDES_PLAINTEXT (advertencia en tiempo de ejecución)
• REF_SHADOWED (hallazgo de auditoría cuando las credenciales de auth-profiles.json tienen prioridad sobre las referencias de openclaw.json)

• serviceAccountRef tiene prioridad sobre serviceAccount en texto sin formato.
• El valor en texto sin formato se ignora cuando la referencia hermana está configurada.

​

Disparadores de activación

• Arranque (comprobación previa más activación final)
• Ruta de aplicación en caliente de recarga de configuración
• Ruta de verificación de reinicio de recarga de configuración
• Recarga manual mediante secrets.reload
• Comprobación previa de RPC de escritura de configuración del Gateway (config.set / config.apply / config.patch) para la resolubilidad de SecretRef en superficies activas dentro de la carga enviada de configuración antes de conservar las ediciones

• El éxito intercambia la instantánea de forma atómica.
• El fallo en el arranque aborta el arranque del gateway.
• El fallo en la recarga de tiempo de ejecución conserva la última instantánea válida conocida.
• El fallo en la comprobación previa de RPC de escritura rechaza la configuración enviada y mantiene sin cambios tanto la configuración en disco como la instantánea activa de tiempo de ejecución.
• Proporcionar un token de canal explícito por llamada a un helper/herramienta saliente no activa la activación de SecretRef; los puntos de activación siguen siendo arranque, recarga y secrets.reload explícito.

​

Señales de degradación y recuperación

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• Degradado: el tiempo de ejecución conserva la última instantánea válida conocida.
• Recuperado: se emite una vez después de la siguiente activación correcta.
• Los fallos repetidos mientras ya está degradado registran advertencias, pero no saturan con eventos.
• El fallo rápido en el arranque no emite eventos de degradación porque el tiempo de ejecución nunca llegó a activarse.

​

Resolución en la ruta de comandos

• Las rutas de comandos estrictas (por ejemplo las rutas de memoria remota de openclaw memory y openclaw qr --remote cuando necesita referencias remotas de secreto compartido) leen desde la instantánea activa y fallan rápidamente cuando un SecretRef requerido no está disponible.
• Las rutas de comandos de solo lectura (por ejemplo openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, openclaw security audit y los flujos de reparación de doctor/configuración de solo lectura) también prefieren la instantánea activa, pero se degradan en lugar de abortar cuando un SecretRef dirigido no está disponible en esa ruta de comando.

• Cuando el gateway está en ejecución, estos comandos leen primero desde la instantánea activa.
• Si la resolución del gateway es incompleta o el gateway no está disponible, intentan un respaldo local dirigido para la superficie específica del comando.
• Si un SecretRef dirigido sigue sin estar disponible, el comando continúa con salida degradada de solo lectura y diagnósticos explícitos como “configured but unavailable in this command path”.
• Este comportamiento degradado es solo local al comando. No debilita las rutas de arranque, recarga ni envío/autenticación del tiempo de ejecución.

• La actualización de instantánea después de la rotación de secretos del backend se gestiona con openclaw secrets reload.
• Método RPC del Gateway usado por estas rutas de comando: secrets.resolve.

​

Flujo de auditoría y configuración

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

​

secrets audit

• valores en texto sin formato en reposo (openclaw.json, auth-profiles.json, .env y agents/*/agent/models.json generado)
• residuos de encabezados sensibles de proveedores en texto sin formato en entradas generadas de models.json
• referencias no resueltas
• sombras de precedencia (auth-profiles.json tiene prioridad sobre referencias de openclaw.json)
• residuos heredados (auth.json, recordatorios OAuth)

• De forma predeterminada, audit omite las comprobaciones de resolubilidad de SecretRef exec para evitar efectos secundarios del comando.
• Usa openclaw secrets audit --allow-exec para ejecutar proveedores exec durante la auditoría.

• La detección de encabezados sensibles de proveedores 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).

​

secrets configure

• configura primero secrets.providers (env/file/exec, agregar/editar/eliminar)
• te permite seleccionar campos compatibles que contienen secretos en openclaw.json más auth-profiles.json para el alcance de un agente
• puede crear directamente un nuevo mapeo auth-profiles.json en el selector de destino
• captura detalles de SecretRef (source, provider, id)
• ejecuta resolución previa
• puede aplicar inmediatamente

• La comprobación previa omite las comprobaciones exec de SecretRef a menos que se defina --allow-exec.
• Si aplicas directamente desde configure --apply y el plan incluye referencias/proveedores exec, mantén --allow-exec también para el paso de aplicación.

• openclaw secrets configure --providers-only
• openclaw secrets configure --skip-provider-setup
• openclaw secrets configure --agent <id>

• limpia credenciales estáticas coincidentes de auth-profiles.json para los proveedores objetivo
• limpia entradas heredadas estáticas api_key de auth.json
• limpia líneas secretas conocidas coincidentes de <config-dir>/.env

​

secrets apply

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

• dry-run omite comprobaciones exec a menos que se defina --allow-exec.
• El modo de escritura rechaza planes que contengan referencias/proveedores exec a menos que se defina --allow-exec.

• Secrets Apply Plan Contract

​

Política de seguridad en un solo sentido

• la comprobación previa debe tener éxito antes del modo de escritura
• la activación en tiempo de ejecución se valida antes de confirmar
• apply actualiza archivos usando reemplazo atómico de archivos y restauración best-effort en caso de fallo

​

Notas de compatibilidad de autenticación heredada

• La fuente de credenciales en tiempo de ejecución es la instantánea resuelta en memoria.
• Las entradas heredadas estáticas api_key se limpian cuando se detectan.
• El comportamiento de compatibilidad relacionado con OAuth sigue siendo independiente.

​

Nota sobre la UI web

​

Documentación relacionada

• Comandos CLI: secrets
• Detalles del contrato del plan: Secrets Apply Plan Contract
• Superficie de credenciales: SecretRef Credential Surface
• Configuración de autenticación: Authentication
• Postura de seguridad: Security
• Precedencia de entorno: Environment Variables