Gerenciamento de segredos

OpenClaw oferece suporte a SecretRefs aditivos para que credenciais compatíveis não precisem ser armazenadas como texto simples na configuração.

Objetivos e modelo de runtime

Segredos são resolvidos em um snapshot de runtime em memória.

• A resolução é ansiosa durante a ativação, não preguiçosa em caminhos de requisição.
• A inicialização falha rapidamente quando um SecretRef efetivamente ativo não pode ser resolvido.
• O recarregamento usa troca atômica: sucesso total, ou mantém o último snapshot comprovadamente bom.
• Violações da política de SecretRef (por exemplo, perfis de autenticação em modo OAuth combinados com entrada SecretRef) falham a ativação antes da troca de runtime.
• Requisições de runtime leem apenas do snapshot ativo em memória.
• Depois da primeira ativação/carga de configuração bem-sucedida, os caminhos de código de runtime continuam lendo esse snapshot ativo em memória até que um recarregamento bem-sucedido o substitua.
• Caminhos de entrega de saída também leem desse snapshot ativo (por exemplo, entrega de resposta/thread do Discord e envios de ações do Telegram); eles não resolvem SecretRefs novamente a cada envio.

Isso mantém indisponibilidades de provedores de segredo fora dos caminhos quentes de requisição.

Limite de acesso do agente

SecretRefs protegem credenciais contra persistência em configuração compatível e superfícies de modelo geradas, mas não são um limite de isolamento de processo. Se uma credencial em texto simples permanecer em disco em um caminho que o agente possa ler, o agente poderá contornar a redação em nível de API usando ferramentas de arquivo ou shell para inspecionar esse arquivo.

Para implantações de produção em que arquivos acessíveis pelo agente estejam no escopo, trate a migração para SecretRef como concluída somente quando tudo isto for verdadeiro:

• credenciais compatíveis usam SecretRefs em vez de valores em texto simples
• resíduos legados em texto simples foram removidos de openclaw.json, auth-profiles.json, .env e arquivos models.json gerados
• openclaw secrets audit --check está limpo após a migração
• quaisquer credenciais restantes sem suporte ou rotativas estão protegidas por isolamento do sistema operacional, isolamento de contêiner ou um proxy externo de credenciais

É por isso que o fluxo de auditoria/configuração/aplicação é um gate de migração de segurança, não apenas um auxiliar de conveniência.

Filtragem de superfície ativa

SecretRefs são validados apenas em superfícies efetivamente ativas.

• Superfícies habilitadas: refs não resolvidas bloqueiam inicialização/recarregamento.
• Superfícies inativas: refs não resolvidas não bloqueiam inicialização/recarregamento.
• Refs inativas emitem diagnósticos não fatais com o código SECRETS_REF_IGNORED_INACTIVE_SURFACE.

Diagnósticos da superfície de autenticação do Gateway

Quando um SecretRef é configurado em gateway.auth.token, gateway.auth.password, gateway.remote.token ou gateway.remote.password, a inicialização/recarregamento do Gateway registra explicitamente o estado da superfície:

• active: o SecretRef faz parte da superfície de autenticação efetiva e deve ser resolvido.
• inactive: o SecretRef é ignorado para este runtime porque outra superfície de autenticação vence, ou porque a autenticação remota está desabilitada/não ativa.

Essas entradas são registradas com SECRETS_GATEWAY_AUTH_SURFACE e incluem o motivo usado pela política de superfície ativa, para que você possa ver por que uma credencial foi tratada como ativa ou inativa.

Pré-validação de referência no onboarding

Quando o onboarding é executado em modo interativo e você escolhe armazenamento SecretRef, o OpenClaw executa validação prévia antes de salvar:

• Refs de env: valida o nome da variável de env e confirma que um valor não vazio está visível durante a configuração.
• Refs de provedor (file ou exec): valida a seleção do provedor, resolve id e verifica o tipo do valor resolvido.
• Caminho de reutilização do quickstart: quando gateway.auth.token já é um SecretRef, o onboarding o resolve antes do bootstrap de probe/dashboard (para refs env, file e exec) usando o mesmo gate de falha rápida.

Se a validação falhar, o onboarding mostra o erro e permite tentar novamente.

Contrato de SecretRef

Use um formato de objeto em todos os lugares:

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

Configuração de provedor

Defina provedores em 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" } }}

Chaves de API baseadas em arquivo

Não coloque strings file:... no bloco env da configuração. O bloco env é literal e não substitutivo, então file:... não é resolvido.

Use um SecretRef de arquivo em um campo de credencial compatível:

{  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", o id do SecretRef é "value". Para mode: "json", use um ponteiro JSON absoluto como "/providers/xai/apiKey".

Consulte Superfície de credenciais SecretRef para os campos de configuração que aceitam SecretRefs.

Exemplos de integração 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" },      },    },  },}

Variáveis de ambiente do servidor MCP

Variáveis de ambiente do servidor MCP configuradas via plugins.entries.acpx.config.mcpServers oferecem suporte a SecretInput. Isso mantém chaves de API e tokens fora da configuração em texto simples:

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

Valores de string em texto simples ainda funcionam. Referências de modelo de ambiente como ${MCP_SERVER_API_KEY} e objetos SecretRef são resolvidos durante a ativação do Gateway antes que o processo do servidor MCP seja iniciado. Como em outras superfícies SecretRef, referências não resolvidas só bloqueiam a ativação quando o Plugin acpx está efetivamente ativo.

Material de autenticação SSH do sandbox

O backend de sandbox ssh do núcleo também oferece suporte a SecretRefs para material de autenticação 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" },        },      },    },  },}

Comportamento em tempo de execução:

• O OpenClaw resolve essas refs durante a ativação do sandbox, não preguiçosamente durante cada chamada SSH.
• Valores resolvidos são gravados em arquivos temporários com permissões restritivas e usados na configuração SSH gerada.
• Se o backend de sandbox efetivo não for ssh, essas refs permanecem inativas e não bloqueiam a inicialização.

Superfície de credenciais compatível

Credenciais canônicas compatíveis e incompatíveis são listadas em:

• Superfície de Credenciais SecretRef

Comportamento obrigatório e precedência

• Campo sem uma ref: inalterado.
• Campo com uma ref: obrigatório em superfícies ativas durante a ativação.
• Se tanto texto simples quanto ref estiverem presentes, ref tem precedência nos caminhos de precedência compatíveis.
• O sentinela de redação __OPENCLAW_REDACTED__ é reservado para redação/restauração interna de configuração e é rejeitado como dados literais de configuração enviados.

Sinais de aviso e auditoria:

• SECRETS_REF_OVERRIDES_PLAINTEXT (aviso em tempo de execução)
• REF_SHADOWED (constatação de auditoria quando credenciais de auth-profiles.json têm precedência sobre refs de openclaw.json)

Comportamento de compatibilidade do Google Chat:

• serviceAccountRef tem precedência sobre serviceAccount em texto simples.
• O valor em texto simples é ignorado quando a ref irmã está definida.

Acionadores de ativação

A ativação de segredos é executada em:

• Inicialização (preflight mais ativação final)
• Caminho de aplicação a quente de recarregamento de configuração
• Caminho de verificação de reinicialização de recarregamento de configuração
• Recarregamento manual via secrets.reload
• Preflight de RPC de gravação de configuração do Gateway (config.set / config.apply / config.patch) para resolubilidade de SecretRef em superfície ativa dentro do payload de configuração enviado antes de persistir edições

Contrato de ativação:

• Sucesso troca o snapshot atomicamente.
• Falha na inicialização aborta a inicialização do Gateway.
• Falha no recarregamento em tempo de execução mantém o último snapshot sabidamente válido.
• Falha no preflight de RPC de gravação rejeita a configuração enviada e mantém tanto a configuração em disco quanto o snapshot de runtime ativo inalterados.
• Fornecer um token de canal explícito por chamada para uma chamada de helper/ferramenta de saída não aciona a ativação de SecretRef; os pontos de ativação permanecem inicialização, recarregamento e secrets.reload explícito.

Sinais degradados e recuperados

Quando a ativação em tempo de recarregamento falha após um estado íntegro, o OpenClaw entra em estado de segredos degradado.

Evento único do sistema e códigos de log:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Comportamento:

• Degradado: o runtime mantém o último snapshot sabidamente válido.
• Recuperado: emitido uma vez após a próxima ativação bem-sucedida.
• Falhas repetidas enquanto já degradado registram avisos, mas não geram eventos em excesso.
• Falha rápida na inicialização não emite eventos degradados porque o runtime nunca se tornou ativo.

Resolução de caminho de comando

Caminhos de comando podem optar pela resolução SecretRef compatível via RPC de snapshot do Gateway.

Há dois comportamentos gerais:

Outras observações:

• A atualização do snapshot após a rotação de segredo no backend é tratada por openclaw secrets reload.
• Método RPC do Gateway usado por estes caminhos de comando: secrets.resolve.

Fluxo de trabalho de auditoria e configuração

Fluxo padrão do operador:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Não trate a migração como concluída até que a nova auditoria esteja limpa. Se a auditoria ainda relatar valores em texto claro em repouso, o risco de acesso por agentes ainda estará presente mesmo quando as APIs de runtime retornarem valores redigidos.

Se você salvar um plano em vez de aplicar durante configure, aplique esse plano salvo com openclaw secrets apply --from <plan-path> antes da nova auditoria.

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 segurança unidirecional

Modelo de segurança:

• o preflight deve ser bem-sucedido antes do modo de gravação
• a ativação do runtime é validada antes do commit
• a aplicação atualiza arquivos usando substituição atômica de arquivo e restauração de melhor esforço em caso de falha

Observações de compatibilidade de autenticação legada

Para credenciais estáticas, o runtime não depende mais do armazenamento legado de autenticação em texto claro.

• A origem das credenciais de runtime é o snapshot resolvido em memória.
• Entradas estáticas legadas de api_key são limpas quando descobertas.
• O comportamento de compatibilidade relacionado a OAuth permanece separado.

Observação sobre a Web UI

Algumas uniões de SecretInput são mais fáceis de configurar no modo de editor bruto do que no modo de formulário.

Relacionado

• Autenticação — configuração de autenticação
• CLI: secrets — comandos da CLI
• Variáveis de ambiente — precedência de ambiente
• Superfície de credenciais SecretRef — superfície de credenciais
• Contrato de plano do Secrets Apply — detalhes do contrato do plano
• Segurança — postura de segurança