Gestión de secretos

OpenClaw admite SecretRefs aditivas para que las credenciales compatibles no tengan que almacenarse como texto sin formato en la configuración.

Modelo de ejecución

• Los secretos se resuelven en una instantánea de ejecución en memoria, de forma anticipada durante la activación, no de forma diferida en las rutas de solicitudes.
• El inicio en frío del Gateway aísla un fallo reintentable de SecretRef en un propietario conocido ajeno al Gateway cuando ese propietario admite el aislamiento. Las clases de propietarios asignadas incluyen proveedores de modelos y Skills, proveedores de medios/TTS/cron, perfiles de autenticación aptos, memoria por agente, SSH del entorno aislado, cuentas de canales y rutas de Plugin declaradas en el manifiesto. El Gateway se inicia, registra al propietario como configurado pero no disponible y emite una advertencia de degradación redactada. La autenticación de entrada del Gateway, las referencias o los valores resueltos estructuralmente no válidos, los propietarios con cierre seguro y las referencias cuyo propietario de ejecución no está asignado siguen impidiendo el inicio.
• La recarga valida cada propietario asignado de forma independiente y después publica una única instantánea atómica. Los propietarios en buen estado se actualizan. Un propietario apto que falle conserva su último valor válido conocido y solo pasa a estar obsoleto cuando las identidades de sus referencias, las definiciones de los proveedores y el contrato completo no secreto del propietario permanecen sin cambios; un propietario nuevo o modificado que falle pasa a estar en frío. Un fallo estricto rechaza la recarga y conserva la instantánea activa.
• Las infracciones de políticas (por ejemplo, un perfil de autenticación en modo OAuth combinado con una entrada SecretRef) impiden la activación antes de sustituir el entorno de ejecución.
• Las solicitudes de ejecución solo leen la instantánea activa en memoria. Las credenciales SecretRef de proveedores de modelos pasan por el almacenamiento de autenticación y las opciones de transmisión como centinelas locales del proceso hasta la salida. Las rutas de entrega saliente (entrega de respuestas/hilos de Discord y envíos de acciones de Telegram) también leen esa instantánea y no vuelven a resolver las referencias en cada envío.

Esto evita que las interrupciones de los proveedores de secretos afecten a las rutas críticas de solicitudes.

La protección de entrada del Gateway, la configuración o los valores resueltos estructuralmente no válidos, las infracciones de políticas y la propiedad desconocida siguen provocando un cierre seguro. Los propietarios aislados nunca recurren a una fuente de credenciales de menor precedencia.

Inyección en el momento de la salida (centinelas)

Para las credenciales de proveedores de modelos respaldadas por SecretRefs, OpenClaw genera un centinela opaco y local del proceso durante la resolución de la autenticación del modelo. Por tanto, el almacenamiento de autenticación, las opciones de transmisión, la configuración del SDK, los registros, los objetos de error y la mayor parte de la introspección del entorno de ejecución ven un valor como oc-sent-v1-..., no la credencial del proveedor. La obtención protegida del modelo y las sondas administradas de estado de proveedores locales sustituyen los centinelas conocidos en los valores de URL y cabeceras inmediatamente antes de que cada solicitud salga del proceso.

Los valores desconocidos con forma de centinela provocan un cierre seguro antes de cualquier actividad de red. OpenClaw se niega a enviar la solicitud en lugar de reenviar a un proveedor un centinela sin resolver. Los valores secretos resueltos también se registran para la redacción exacta de valores en los registros como medida de defensa en profundidad.

Los adaptadores de proveedores utilizan el punto de inyección más tardío que admite su SDK:

• Los SDK con una opción de obtención personalizada reciben la función de obtención protegida de OpenClaw, por lo que el SDK conserva el centinela.
• Los SDK sin una opción de obtención personalizada desenvuelven el centinela inmediatamente antes de construir el cliente. Las transmisiones de proveedores propiedad de Plugins y los entornos de agentes lo desenvuelven en la transferencia final propiedad del núcleo porque esos transportes no comparten la función de obtención protegida de OpenClaw.

Los centinelas reducen la exposición del texto sin formato a lo largo de la cadena de llamadas al modelo, pero no proporcionan aislamiento de procesos. El valor real sigue existiendo en la memoria del mismo proceso y aparece en el límite final del adaptador. Las credenciales de entorno en texto sin formato que no estén configuradas mediante SecretRefs permanecen como texto sin formato y quedan fuera de este mecanismo.

Establezca OPENCLAW_SECRET_SENTINELS=off (también acepta 0 o false, sin distinguir entre mayúsculas y minúsculas) para desactivar la generación de centinelas durante la respuesta a incidentes o la resolución de problemas de compatibilidad. El interruptor de emergencia no desactiva el registro para la redacción exacta de valores.

Límite de acceso del agente

Las SecretRefs evitan que las credenciales se conserven en la configuración y en los archivos de modelos generados, pero no constituyen un límite de aislamiento de procesos. Una credencial en texto sin formato que permanezca en el disco en una ruta que el agente pueda leer sigue siendo accesible mediante herramientas de archivos o del shell, eludiendo la redacción a nivel de API.

En implementaciones de producción en las que se incluyan archivos accesibles para el agente, considere que la migración está completa solo cuando se cumplan todas estas condiciones:

• Las credenciales compatibles utilizan SecretRefs en lugar de valores en texto sin formato.
• Los residuos heredados de texto sin formato se han eliminado de openclaw.json, auth-profiles.json, .env y los archivos models.json generados.
• openclaw secrets audit --check no detecta problemas después de la migración.
• Todas las credenciales restantes que no sean compatibles o estén en rotación están protegidas mediante aislamiento del sistema operativo, aislamiento de contenedores o un proxy externo de credenciales.

Por este motivo, el flujo de auditoría/configuración/aplicación es una barrera de migración de seguridad, no solo una herramienta auxiliar práctica.

Filtrado de superficies activas

Las SecretRefs solo se validan en superficies que están activas de forma efectiva:

• Superficies habilitadas: los fallos reintentables de propietarios asignados y aislables entran en degradación fría u obsoleta. Los fallos estrictos, con cierre seguro, necesarios para el Gateway o sin asignar bloquean el inicio o la recarga.
• Superficies inactivas: las referencias sin resolver no bloquean el inicio ni la recarga; emiten un diagnóstico SECRETS_REF_IGNORED_INACTIVE_SURFACE no fatal.

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

Cuando se establece una SecretRef en gateway.auth.token, gateway.auth.password, gateway.remote.token o gateway.remote.password, el inicio o la recarga del Gateway registra el estado de la superficie con el código SECRETS_GATEWAY_AUTH_SURFACE:

• active: la SecretRef forma parte de la superficie de autenticación efectiva y debe resolverse.
• inactive: prevalece otra superficie de autenticación o la autenticación remota está deshabilitada/inactiva.

La entrada del registro incluye el motivo utilizado por la política de superficies activas.

Comprobación previa de referencias durante la incorporación

En la incorporación interactiva, al elegir el almacenamiento mediante SecretRef se ejecuta una validación previa antes de guardar:

• Referencias de entorno: valida el nombre de la variable de entorno y confirma que haya un valor no vacío visible durante la configuración.
• Referencias de proveedores (file o exec): valida la selección del proveedor, resuelve id y comprueba el tipo del valor resuelto.
• Flujo de inicio rápido: cuando gateway.auth.token ya es una SecretRef, la incorporación la resuelve antes de la sonda/inicialización del panel (para referencias env, file y exec) mediante la misma barrera de fallo rápido.

Un fallo de validación muestra el error y permite volver a intentarlo.

Contrato de SecretRef

Una única estructura de objeto en todas partes:

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

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

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

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

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

Configuración de proveedores

Defina los proveedores en secrets.providers:

{  secrets: {    providers: {      default: { source: "env" },      filemain: {        source: "file",        path: "~/.openclaw/secrets.json",        mode: "json", // or "singleValue"      },      vault: {        source: "exec",        command: "/usr/local/bin/openclaw-vault-resolver",        args: ["--profile", "prod"],        passEnv: ["PATH", "VAULT_ADDR"],        jsonOnly: true,      },      "team-secrets": {        source: "exec",        pluginIntegration: {          pluginId: "acme-secrets",          integrationId: "secret-store",        },      },    },    defaults: {      env: "default",      file: "filemain",      exec: "vault",    },  },}

{ "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": { "code": "NOT_FOUND" } }}

Claves de API respaldadas por archivos

No coloque cadenas file:... en el bloque env de la configuración. Ese bloque es literal y no permite sobrescrituras, por lo que file:... nunca se resuelve allí.

En su lugar, use una SecretRef de archivo en un campo de credenciales compatible:

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

Para mode: "singleValue", el id de SecretRef es "value". Para mode: "json", use un puntero JSON absoluto como "/providers/xai/apiKey".

Consulte Superficie de credenciales SecretRef para conocer los campos que aceptan SecretRefs.

Ejemplos de integración exec

Para consultar una guía específica de 1Password que abarca las cuentas de servicio, la skill de agente incluida y la solución de problemas, consulte 1Password.

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        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" },      },    },  },}

{  secrets: {    providers: {      bws: {        source: "exec",        command: "/usr/local/bin/openclaw-bws-resolver.mjs",        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "bws",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --allow-exec

{  secrets: {    providers: {      vault_openai: {        source: "exec",        command: "/opt/homebrew/bin/vault",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        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" },      },    },  },}

#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process"); let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => {  stdin += chunk;});process.stdin.on("error", (err) => {  process.stderr.write(`${err.message}\n`);  process.exit(1);});process.stdin.on("end", () => {  let request;  try {    request = JSON.parse(stdin || "{}");  } catch (err) {    process.stderr.write(`Failed to parse request: ${err.message}\n`);    process.exit(1);  }   const passBin = process.env.PASS_BIN || "pass";  const values = {};  const errors = {};   for (const id of request.ids ?? []) {    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });    if (result.status === 0) {      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";    } else {      errors[id] = { message: (result.stderr || `pass exited ${result.status}`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

{  secrets: {    providers: {      pass_store: {        source: "exec",        command: "/usr/local/bin/openclaw-pass-resolver",        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "pass_store",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  secrets: {    providers: {      sops_openai: {        source: "exec",        command: "/opt/homebrew/bin/sops",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        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

Las variables de entorno del servidor MCP configuradas mediante plugins.entries.acpx.config.mcpServers aceptan SecretInput, lo que mantiene las claves de API y los tokens fuera de la configuración en texto sin formato:

{  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",                },              },            },          },        },      },    },  },}

Los valores de cadena en texto sin formato siguen funcionando. Las referencias de plantilla de entorno como ${MCP_SERVER_API_KEY} y los objetos SecretRef se resuelven durante la activación del Gateway, antes de que se genere el proceso del servidor MCP. Al igual que con otras superficies SecretRef, las referencias sin resolver solo bloquean la activación cuando el plugin acpx está efectivamente activo.

Material de autenticación SSH del entorno aislado

El backend de entorno aislado principal ssh también admite SecretRefs para el material de autenticación SSH:

{  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" },        },      },    },  },}

Comportamiento en tiempo de ejecución:

• OpenClaw resuelve estas referencias durante la activación del entorno aislado, no de forma diferida en cada llamada SSH.
• Los valores resueltos se escriben en un directorio temporal con permisos de archivo restrictivos (0o600) y se utilizan en la configuración SSH generada.
• Si el backend efectivo del entorno aislado no es ssh (o el modo del entorno aislado es off), estas referencias permanecen inactivas y no bloquean el inicio.

Superficie de credenciales compatible

Las credenciales compatibles y no compatibles canónicas se enumeran en Superficie de credenciales de SecretRef.

Comportamiento requerido y precedencia

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

Señales de advertencia y auditoría:

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

Google Chat serviceAccount acepta JSON insertado o una SecretRef. Doctor mueve el elemento hermano retirado serviceAccountRef a este campo canónico cuando no está definido.

Desencadenadores de activación

La activación de secretos se ejecuta durante:

• El inicio (comprobación previa más activación final)
• La ruta de aplicación en caliente de la recarga de configuración
• La ruta de comprobación de reinicio de la recarga de configuración
• La recarga manual mediante secrets.reload
• La comprobación previa de la RPC de escritura de configuración del Gateway (config.set / config.apply / config.patch), que valida las SecretRefs de las superficies activas dentro de la carga útil de configuración enviada antes de guardar los cambios

Contrato de activación:

• En caso de éxito, la instantánea se sustituye de forma atómica.
• Un fallo estricto durante el inicio interrumpe el inicio del Gateway.
• Durante un inicio en frío, un fallo de resolución reintentable de un propietario no perteneciente al Gateway, asignado y aislable, puede publicar la instantánea con ese propietario exacto configurado como no disponible. Las solicitudes para el propietario fallan con SECRET_SURFACE_UNAVAILABLE; los propietarios de proveedores de modelos no recurren a credenciales del entorno ni del perfil de autenticación después de que falle una referencia explícita.
• La recarga y la comprobación de reinicio aíslan a los propietarios asignados aptos. Las identidades de referencia sin cambios, con definiciones de proveedor sin cambios y un contrato completo no secreto del propietario sin cambios, conservan sus valores exactos válidos más recientes como obsoletos; las referencias no resueltas modificadas o recién configuradas se publican en frío solo para ese propietario. Un fallo estricto de recarga conserva la instantánea activa anterior.
• config.set, config.apply y config.patch aceptan referencias no resueltas sintácticamente válidas para propietarios aislables y devuelven un informe degradedSecretOwners censurado. La autenticación de entrada del Gateway, la configuración o los valores resueltos estructuralmente no válidos, las infracciones de políticas y los propietarios desconocidos siguen rechazándose antes de modificar el disco.
• Los propietarios hermanos en buen estado se resuelven y publican con normalidad incluso cuando otro propietario está en frío u obsoleto.
• Proporcionar un token de canal explícito por llamada a una llamada de herramienta o auxiliar de salida no desencadena la activación de SecretRef; los puntos de activación siguen siendo el inicio, la recarga y el secrets.reload explícito.

Señales de degradación y recuperación

Cuando la activación durante la recarga falla después de un estado en buen funcionamiento, OpenClaw entra en un estado de secretos degradado y emite eventos del sistema de una sola vez y códigos de registro:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Comportamiento:

• Degradado: los propietarios en buen estado se actualizan, los propietarios obsoletos conservan el último valor válido conocido y los propietarios en frío permanecen no disponibles.
• Recuperado: se emite una vez después de la siguiente activación correcta.
• Los fallos repetidos mientras el sistema ya está degradado registran advertencias, pero no vuelven a emitir el evento.
• Un fallo estricto durante el inicio nunca emite un evento de degradación, porque el entorno de ejecución nunca llegó a estar activo. Un inicio correcto con propietarios en frío registra la degradación del propietario, pero no emite un evento del recargador.
• Los fallos de inicio y recarga limitados a referencias emiten una advertencia estructurada SECRETS_DEGRADED para cada propietario afectado. Las interrupciones limitadas al proveedor emiten una advertencia SECRETS_PROVIDER_DEGRADED con el proveedor y la lista completa de propietarios afectados, en lugar de repetir el fallo del proveedor para cada propietario. Las advertencias incluyen un motivo censurado, el estado del propietario cold o stale y la sugerencia de reintento openclaw secrets reload. Nunca incluyen valores resueltos ni identificadores de SecretRef.
• openclaw doctor enumera los propietarios en frío y obsoletos con sus rutas de configuración afectadas, el motivo censurado y las instrucciones para reintentar.

Resolución de rutas de comandos

Las rutas de comandos pueden habilitar la resolución de SecretRef compatible mediante una RPC de instantánea del Gateway. Se aplican dos comportamientos generales:

Otras notas:

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

Flujo de trabajo de auditoría y configuración

Flujo predeterminado del operador:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

No se debe considerar que la migración está completa hasta que la nueva auditoría no detecte problemas. Si la auditoría sigue informando de valores en texto sin formato almacenados, el riesgo de acceso por parte del agente permanece incluso cuando las API del entorno de ejecución devuelven valores censurados.

Si se guarda un plan en lugar de aplicarlo durante configure, se debe aplicar ese plan guardado con openclaw secrets apply --from <plan-path> antes de volver a realizar la auditoría.

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-exec

Política de seguridad unidireccional

Modelo de seguridad:

• La comprobación previa debe completarse correctamente antes del modo de escritura.
• La activación del entorno de ejecución se valida antes de confirmar los cambios.
• La aplicación actualiza los archivos mediante sustitución atómica y restauración de mejor esfuerzo en caso de fallo.

Notas sobre la compatibilidad con la autenticación heredada

Para las credenciales estáticas, el entorno de ejecución ya no depende del almacenamiento de autenticación heredado en texto sin formato.

• La fuente de credenciales del entorno de ejecución es la instantánea resuelta en memoria.
• Las entradas estáticas heredadas api_key se eliminan al detectarse.
• El comportamiento de compatibilidad relacionado con OAuth se mantiene separado.

Nota sobre la interfaz web

Algunas uniones SecretInput son más fáciles de configurar en el modo de editor sin formato que en el modo de formulario.

Contenido relacionado

• Autenticación - configuración de autenticación
• CLI: secretos - comandos de la CLI
• SecretRefs de Vault - configuración del proveedor HashiCorp Vault
• Variables de entorno - precedencia del entorno
• Superficie de credenciales de SecretRef - superficie de credenciales
• Contrato del plan de aplicación de secretos - detalles del contrato del plan
• Seguridad - postura de seguridad