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 falla de inmediato cuando no se puede resolver una SecretRef efectivamente activa.
• La recarga es un intercambio atómico: se completa correctamente en su totalidad o se conserva la última instantánea válida conocida.
• Las infracciones de políticas (por ejemplo, un perfil de autenticación en modo OAuth combinado con una entrada SecretRef) provocan que la activación falle antes del intercambio de la instantánea de ejecución.
• Las solicitudes de ejecución solo leen la instantánea activa en memoria. Las credenciales SecretRef de proveedores de modelos atraviesan 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, 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.

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 lo 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 en tiempo de ejecución ven un valor como oc-sent-v1-..., no la credencial del proveedor. La solicitud fetch protegida del modelo y las sondas de estado de proveedores locales administrados 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 fallo seguro antes de cualquier actividad de red. OpenClaw se niega a enviar la solicitud en lugar de reenviar un centinela sin resolver a un proveedor. Los valores de secretos resueltos también se registran para su ocultación en los registros mediante coincidencia exacta, 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 fetch personalizada reciben la solicitud fetch protegida de OpenClaw, por lo que el SDK conserva el centinela.
• Los SDK sin una opción fetch personalizada desenvuelven el centinela inmediatamente antes de construir el cliente. Las transmisiones de proveedores propiedad de plugins y los entornos de ejecución de agentes lo desenvuelven en la transferencia final controlada por el núcleo, porque esos transportes no comparten la solicitud fetch protegida de OpenClaw.

Los centinelas reducen la exposición de texto sin formato en toda 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 se configuran 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 desactivación no deshabilita el registro para la ocultación mediante coincidencia exacta de valores.

Límite de acceso del agente

Las SecretRefs impiden que las credenciales persistan 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 seguirá siendo accesible mediante herramientas de archivos o del shell, lo que elude la ocultación en el nivel de la API.

En implementaciones de producción donde los archivos accesibles para el agente estén dentro del alcance, 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 informa de problemas después de la migración.
• Las credenciales restantes que no sean compatibles o que roten están protegidas mediante aislamiento del sistema operativo, aislamiento de contenedores o un proxy de credenciales externo.

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

Filtrado de superficies activas

Las SecretRefs solo se validan en superficies efectivamente activas:

• Superficies habilitadas: las referencias sin resolver bloquean el inicio o la recarga.
• Superficies inactivas: las referencias sin resolver no bloquean el inicio ni la recarga; emiten un diagnóstico no fatal SECRETS_REF_IGNORED_INACTIVE_SURFACE.

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

Durante 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 iniciar la sonda o el panel (para referencias env, file y exec) mediante la misma puerta de fallo inmediato.

Si la validación falla, se muestra el error y se permite volver a intentarlo.

Contrato de SecretRef

Una única forma 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",    },    resolution: {      maxProviderConcurrency: 4,      maxRefsPerProvider: 512,      maxBatchBytes: 262144,    },  },}

{ "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 de SecretRef para conocer los campos que aceptan SecretRefs.

Ejemplos de integración con exec

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // obligatorio para binarios de Homebrew enlazados simbólicamente        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, // obligatorio para binarios de Homebrew enlazados simbólicamente        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(`No se pudo analizar la solicitud: ${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 finalizó con ${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, // obligatorio para binarios de Homebrew enlazados simbólicamente        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 de SecretRef, las referencias no resueltas solo bloquean la activación cuando el plugin acpx está realmente activo.

Material de autenticación SSH del entorno aislado

El backend principal ssh del entorno aislado 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 usan 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 valor 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 de auth-profiles.json tienen precedencia sobre las referencias de openclaw.json)

Compatibilidad con Google Chat: serviceAccountRef tiene precedencia sobre serviceAccount en texto sin formato; el valor en texto sin formato se ignora una vez establecida la referencia del mismo nivel.

Desencadenadores de activación

La activación de secretos se ejecuta en:

• Inicio (comprobación previa más activación final)
• Ruta de aplicación en caliente de la recarga de configuración
• Ruta de comprobación de reinicio de la 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), que comprueba que las SecretRefs de superficies activas puedan resolverse dentro de la carga útil de configuración enviada antes de conservar las modificaciones

Contrato de activación:

• En caso de éxito, sustituye la instantánea de forma atómica.
• Un fallo de inicio interrumpe el inicio del gateway.
• Un fallo de recarga en tiempo de ejecución conserva la última instantánea válida conocida.
• Un fallo de la comprobación previa de RPC de escritura rechaza la configuración enviada; tanto la configuración en disco como la instantánea activa en tiempo de ejecución permanecen sin cambios.
• Proporcionar un token de canal explícito por llamada a una llamada saliente de un ayudante o una herramienta no desencadena la activación de SecretRef; los puntos de activación siguen siendo el inicio, la recarga y secrets.reload explícito.

Señales de degradación y recuperación

Cuando la activación durante una recarga falla después de un estado correcto, 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: el entorno de ejecución conserva la última instantánea válida conocida.
• Recuperado: se emite una vez tras la siguiente activación correcta.
• Los fallos repetidos mientras ya se encuentra en estado degradado registran advertencias, pero no vuelven a emitir el evento.
• El fallo rápido durante el inicio nunca emite un evento de degradación, porque el entorno de ejecución nunca llegó a estar activo.

Resolución de rutas de comandos

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

Otras notas:

• La actualización de la instantánea tras 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 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 completada la migración hasta que la nueva auditoría no detecte problemas. Si la auditoría sigue indicando valores de 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 la nueva 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 preliminar debe realizarse 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 hace todo lo posible por restaurarlos en caso de fallo.

Notas de 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 de api_key se eliminan al detectarse.
• El comportamiento de compatibilidad relacionado con OAuth permanece 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.

Temas relacionados

• Autenticación - configuración de la 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