Gestión de secretos

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

Objetivos y modelo de runtime

Los secretos se resuelven en una instantánea de runtime en memoria.

• La resolución es ansiosa durante la activación, no diferida en las rutas de solicitud.
• El arranque falla rápido cuando un SecretRef efectivamente activo no puede resolverse.
• La recarga usa intercambio atómico: éxito completo, o se conserva la última instantánea válida conocida.
• Las infracciones de la 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 runtime.
• Las solicitudes de runtime leen únicamente desde la instantánea activa en memoria.
• Después de la primera activación/carga correcta de la configuración, las rutas de código de runtime siguen leyendo esa instantánea activa en memoria hasta que una recarga correcta la intercambia.
• Las rutas de entrega saliente también leen desde esa instantánea activa (por ejemplo, la entrega de respuestas/hilos de Discord y los envíos de acciones de Telegram); no vuelven a resolver SecretRefs en cada envío.

Esto mantiene las interrupciones del proveedor de secretos fuera de las rutas críticas de solicitud.

Límite de acceso del agente

Los SecretRefs protegen las credenciales para que no se persistan en la configuración compatible y en las superficies de modelos generadas, pero no son un límite de aislamiento de procesos. Si una credencial en texto sin formato permanece en disco en una ruta que el agente puede leer, el agente puede eludir la redacción a nivel de API usando herramientas de archivo o de shell para inspeccionar ese archivo.

Para despliegues de producción donde los archivos accesibles por el agente están dentro del alcance, considera la migración de SecretRef completa solo cuando todo esto sea cierto:

• las credenciales compatibles usan SecretRefs en lugar de valores en texto sin formato
• el residuo heredado en texto sin formato se ha eliminado de openclaw.json, auth-profiles.json, .env y los archivos models.json generados
• openclaw secrets audit --check queda limpio después de la migración
• cualquier credencial restante no compatible o rotativa está protegida por aislamiento del sistema operativo, aislamiento de contenedores o un proxy de credenciales externo

Por eso el flujo de auditoría/configuración/aplicación es una puerta de migración de seguridad, no solo un asistente de conveniencia.

Filtrado de superficies activas

Los SecretRefs se validan solo en superficies efectivamente activas.

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

Diagnósticos de superficie de autenticación del Gateway

Cuando se configura un SecretRef en gateway.auth.token, gateway.auth.password, gateway.remote.token o gateway.remote.password, el arranque/la recarga del gateway registra explícitamente el estado de la superficie:

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

Estas entradas se registran con SECRETS_GATEWAY_AUTH_SURFACE e incluyen el motivo usado por la política de superficie activa, para que puedas ver por qué una credencial se trató como activa o inactiva.

Preflight de referencia durante la incorporación

Cuando la incorporación se ejecuta en modo interactivo y eliges almacenamiento SecretRef, OpenClaw ejecuta una validación preflight antes de guardar:

• Referencias env: 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 del valor resuelto.
• Ruta de reutilización de quickstart: cuando gateway.auth.token ya es un SecretRef, la incorporación lo resuelve antes del arranque de la prueba/dashboard (para refs env, file y exec) usando la misma puerta de fallo rápido.

Si la validación falla, la incorporación muestra el error y te permite reintentarlo.

Contrato de SecretRef

Usa una 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 del proveedor

Define proveedores bajo 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": { "message": "not found" } }}

Claves de API respaldadas por archivos

No coloques cadenas file:... en el bloque env de la configuración. El bloque env es literal y no sobrescribe, así que file:... no se resuelve.

Usa un SecretRef de archivo en un campo de credencial compatible en su lugar:

{  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", usa un puntero JSON absoluto como "/providers/xai/apiKey".

Consulta Superficie de credenciales SecretRef para ver los campos de configuración que aceptan SecretRefs.

Ejemplos de integración exec

{  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 admiten SecretInput. Esto mantiene las claves de API y los tokens fuera de la configuración en texto plano:

{  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 plano 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. 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 sandbox

El backend de sandbox ssh del núcleo también admite SecretRefs para 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 sandbox, no de forma diferida durante 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 inicio.

Superficie de credenciales admitida

Las credenciales canónicas admitidas y no admitidas se enumeran en:

• Superficie de credenciales de SecretRef

Comportamiento requerido y precedencia

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

Señales de advertencia y auditoría:

• SECRETS_REF_OVERRIDES_PLAINTEXT (advertencia de 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)

Comportamiento de compatibilidad de Google Chat:

• serviceAccountRef tiene prioridad sobre serviceAccount en texto plano.
• El valor en texto plano se ignora cuando se establece la referencia hermana.

Activadores de activación

La activación de secretos se ejecuta en:

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

Contrato de activación:

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

Señales degradadas y recuperadas

Cuando la activación en tiempo de recarga falla después de un estado saludable, OpenClaw entra en estado de secretos degradado.

Códigos de evento del sistema de una sola vez y de registro:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Comportamiento:

• Degradado: el tiempo de ejecución conserva la última instantánea buena 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 los eventos.
• El fallo rápido al inicio no emite eventos degradados porque el tiempo de ejecución nunca llegó a estar activo.

Resolución de rutas de comandos

Las rutas de comandos pueden optar por la resolución SecretRef admitida mediante RPC de instantánea del Gateway.

Hay dos comportamientos generales:

Otras notas:

• La actualización de la 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 trabajo de auditoría y configuración

Flujo predeterminado del operador:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

No trates la migración como completa hasta que la nueva auditoría esté limpia. Si la auditoría todavía informa valores en texto sin formato en reposo, el riesgo de acceso del agente sigue presente incluso cuando las API del runtime devuelven valores redactados.

Si guardas un plan en lugar de aplicarlo durante configure, aplica ese plan guardado con openclaw secrets apply --from <plan-path> antes de volver a auditar.

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 runtime se valida antes de confirmar
• apply actualiza archivos mediante reemplazo atómico de archivos y restauración de mejor esfuerzo en caso de fallo

Notas de compatibilidad de autenticación heredada

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

• La fuente de credenciales del runtime es la instantánea resuelta en memoria.
• Las entradas api_key estáticas heredadas se eliminan cuando se descubren.
• 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 modo de editor sin procesar que en modo de formulario.

Relacionado

• Autenticación — configuración de autenticación
• CLI: secretos — comandos de CLI
• Variables de entorno — precedencia del entorno
• Superficie de credenciales SecretRef — superficie de credenciales
• Contrato de plan de aplicación de secretos — detalles del contrato del plan
• Seguridad — postura de seguridad