Gerenciamento de segredos

O OpenClaw oferece suporte a SecretRefs aditivas, para que as credenciais compatíveis não precisem permanecer como texto simples na configuração.

Modelo de runtime

• Os segredos são resolvidos em um snapshot de runtime na memória, antecipadamente durante a ativação, não de forma tardia nos caminhos de solicitação.
• A inicialização falha imediatamente quando uma SecretRef efetivamente ativa não pode ser resolvida.
• O recarregamento é uma troca atômica: sucesso completo ou manutenção do último snapshot válido conhecido.
• Violações de política (por exemplo, um perfil de autenticação no modo OAuth combinado com uma entrada SecretRef) fazem a ativação falhar antes da troca do runtime.
• As solicitações de runtime leem apenas o snapshot ativo na memória. As credenciais SecretRef dos provedores de modelo passam pelo armazenamento de autenticação e pelas opções de streaming como sentinelas locais ao processo até a saída. Os caminhos de entrega de saída (entrega de respostas/threads no Discord, envios de ações no Telegram) também leem esse snapshot e não resolvem novamente as referências a cada envio.

Isso mantém as indisponibilidades dos provedores de segredos fora dos caminhos críticos de solicitação.

Injeção no momento da saída (sentinelas)

Para credenciais de provedores de modelo respaldadas por SecretRefs, o OpenClaw gera uma sentinela opaca e local ao processo durante a resolução da autenticação do modelo. Portanto, o armazenamento de autenticação, as opções de streaming, a configuração do SDK, os logs, os objetos de erro e a maior parte da introspecção do runtime veem um valor como oc-sent-v1-..., não a credencial do provedor. A busca protegida do modelo e as sondagens de integridade gerenciadas dos provedores locais substituem as sentinelas conhecidas nos valores de URL e cabeçalho imediatamente antes que cada solicitação saia do processo.

Valores desconhecidos com formato de sentinela falham de forma segura antes de qualquer atividade de rede. O OpenClaw se recusa a enviar a solicitação em vez de encaminhar uma sentinela não resolvida a um provedor. Os valores de segredos resolvidos também são registrados para ocultação de valores exatos nos logs como medida de defesa em profundidade.

Os adaptadores de provedor usam o ponto de injeção mais tardio compatível com seus SDKs:

• SDKs com uma opção de busca personalizada recebem a busca protegida do OpenClaw, para que o SDK mantenha a sentinela.
• SDKs sem uma opção de busca personalizada desembrulham a sentinela imediatamente antes da criação do cliente. Os streams de provedores pertencentes a Plugins e os harnesses de agentes desembrulham no ponto final de transferência pertencente ao núcleo, pois esses transportes não compartilham a busca protegida do OpenClaw.

As sentinelas reduzem a exposição de texto simples em toda a cadeia de chamada do modelo, mas não constituem isolamento de processo. O valor real ainda existe na memória do mesmo processo e aparece no limite final do adaptador. Credenciais simples de ambiente que não estejam configuradas por meio de SecretRefs permanecem como texto simples e ficam fora desse mecanismo.

Defina OPENCLAW_SECRET_SENTINELS=off (também aceita 0 ou false, sem diferenciar maiúsculas de minúsculas) para desabilitar a geração de sentinelas durante a resposta a incidentes ou a solução de problemas de compatibilidade. O mecanismo de desativação não desabilita o registro de ocultação por valor exato.

Limite de acesso do agente

As SecretRefs impedem que credenciais sejam persistidas na configuração e nos arquivos de modelo gerados, mas não constituem um limite de isolamento de processo. Uma credencial em texto simples deixada no disco em um caminho que o agente possa ler continua legível por ferramentas de arquivo ou shell, contornando a ocultação no nível da API.

Em implantações de produção nas quais arquivos acessíveis pelo agente estejam no escopo, considere a migração concluída somente quando todas estas condições forem atendidas:

• As credenciais compatíveis usam SecretRefs em vez de valores em texto simples.
• O resíduo legado em texto simples foi removido de openclaw.json, auth-profiles.json, .env e dos arquivos models.json gerados.
• openclaw secrets audit --check não apresenta problemas após a migração.
• Quaisquer credenciais restantes, sem suporte ou rotativas, são protegidas por isolamento do sistema operacional, isolamento de contêiner ou um proxy externo de credenciais.

Por isso, o fluxo de auditoria/configuração/aplicação é uma barreira de migração de segurança, não apenas um recurso auxiliar de conveniência.

Filtragem de superfícies ativas

As SecretRefs são validadas apenas em superfícies efetivamente ativas:

• Superfícies habilitadas: referências não resolvidas bloqueiam a inicialização/o recarregamento.
• Superfícies inativas: referências não resolvidas não bloqueiam a inicialização/o recarregamento; elas emitem um diagnóstico não fatal SECRETS_REF_IGNORED_INACTIVE_SURFACE.

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

Quando uma SecretRef é definida em gateway.auth.token, gateway.auth.password, gateway.remote.token ou gateway.remote.password, a inicialização/o recarregamento do Gateway registra o estado da superfície sob o código SECRETS_GATEWAY_AUTH_SURFACE:

• active: a SecretRef faz parte da superfície efetiva de autenticação e deve ser resolvida.
• inactive: outra superfície de autenticação prevalece, ou a autenticação remota está desabilitada/inativa.

A entrada de log inclui o motivo usado pela política de superfície ativa.

Pré-verificação de referências durante a integração inicial

Na integração inicial interativa, escolher o armazenamento por SecretRef executa uma validação preliminar antes de salvar:

• Referências de ambiente: valida o nome da variável de ambiente e confirma que um valor não vazio está visível durante a configuração.
• Referências de provedor (file ou exec): valida a seleção do provedor, resolve id e verifica o tipo do valor resolvido.
• Fluxo de início rápido: quando gateway.auth.token já é uma SecretRef, a integração inicial a resolve antes da sondagem/inicialização do painel (para referências env, file e exec) usando a mesma barreira de falha imediata.

Uma falha de validação exibe o erro e permite tentar novamente.

Contrato de SecretRef

Um único 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 provedores

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

Chaves de API armazenadas em arquivos

Não coloque strings file:... no bloco env da configuração. Esse bloco é literal e não substitui valores existentes, portanto file:... nunca é resolvido nele.

Em vez disso, use uma 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 da SecretRef é "value". Para mode: "json", use um ponteiro JSON absoluto, como "/providers/xai/apiKey".

Consulte Superfície de credenciais da SecretRef para ver os campos que aceitam SecretRefs.

Exemplos de integração exec

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // obrigatório para binários do Homebrew vinculados por links simbólicos        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, // obrigatório para binários do Homebrew vinculados por links simbólicos        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(`Falha ao analisar a solicitação: ${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 encerrou com o status ${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, // obrigatório para binários do Homebrew vinculados por links simbólicos        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

As variáveis de ambiente do servidor MCP configuradas por meio de plugins.entries.acpx.config.mcpServers aceitam SecretInput, mantendo 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 continuam funcionando. 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. Assim como em outras superfícies de 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 é compatível com 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 referências durante a ativação do sandbox, não de forma adiada a cada chamada SSH.
• Os valores resolvidos são gravados em um diretório temporário com permissões de arquivo restritivas (0o600) e usados na configuração SSH gerada.
• Se o backend de sandbox efetivo não for ssh (ou o modo de sandbox for off), essas referências permanecerão inativas e não bloquearão a inicialização.

Superfície de credenciais compatível

As credenciais canônicas compatíveis e não compatíveis estão listadas em Superfície de credenciais da SecretRef.

Comportamento obrigatório e precedência

• Campo sem referência: inalterado.
• Campo com referência: obrigatório em superfícies ativas durante a ativação.
• Se houver texto simples e referência, a referência terá precedência nos caminhos de precedência compatíveis.
• O sentinela de redação __OPENCLAW_REDACTED__ é reservado para redação/restauração interna da configuração e é rejeitado como dado literal enviado na configuração.

Sinais de aviso e auditoria:

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

Compatibilidade com o Google Chat: serviceAccountRef tem precedência sobre serviceAccount em texto simples; o valor em texto simples é ignorado assim que a referência irmã é definida.

Acionadores de ativação

A ativação de segredos é executada em:

• Inicialização (pré-verificação mais ativação final)
• Caminho de aplicação dinâmica de recarregamento da configuração
• Caminho de verificação de reinicialização do recarregamento da configuração
• Recarregamento manual por meio de secrets.reload
• Pré-verificação de RPC de gravação da configuração do Gateway (config.set / config.apply / config.patch), verificando a capacidade de resolução das SecretRefs de superfícies ativas dentro da carga de configuração enviada antes de persistir as edições

Contrato de ativação:

• Em caso de sucesso, o snapshot é substituído atomicamente.
• Uma falha na inicialização interrompe a inicialização do gateway.
• Uma falha de recarregamento em tempo de execução mantém o último snapshot válido conhecido.
• Uma falha na pré-verificação da RPC de gravação rejeita a configuração enviada; tanto a configuração em disco quanto o snapshot ativo em tempo de execução permanecem inalterados.
• Fornecer um token de canal explícito por chamada a uma chamada de ferramenta/auxiliar de saída não aciona a ativação de SecretRef; os pontos de ativação continuam sendo a inicialização, o recarregamento e secrets.reload explícito.

Sinais de degradação e recuperação

Quando a ativação durante o recarregamento falha após um estado íntegro, o OpenClaw entra em um estado degradado de segredos, emitindo eventos de sistema de ocorrência única e códigos de log:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Comportamento:

• Degradado: o runtime mantém o último snapshot válido conhecido.
• Recuperado: emitido uma vez após a próxima ativação bem-sucedida.
• Falhas repetidas enquanto já estiver degradado registram avisos, mas não emitem o evento novamente.
• Uma falha imediata na inicialização nunca emite um evento de degradação, porque o runtime nunca chegou a ficar ativo.

Resolução de caminhos de comandos

Os caminhos de comandos podem optar pela resolução de SecretRef compatível por meio de uma RPC de snapshot do Gateway. Aplicam-se dois comportamentos gerais:

Outras observações:

• A atualização do snapshot após a rotação de segredos no backend é realizada por openclaw secrets reload.
• Método RPC do Gateway usado por esses caminhos de comandos: secrets.resolve.

Fluxo de auditoria e configuração

Fluxo padrão do operador:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Não considere a migração concluída até que a nova auditoria não apresente problemas. Se a auditoria ainda relatar valores em texto simples armazenados, o risco de acesso pelo agente permanecerá mesmo quando as APIs do runtime retornarem valores ocultados.

Se você salvar um plano em vez de aplicá-lo 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:

• A pré-verificação deve ser bem-sucedida antes do modo de gravação.
• A ativação do runtime é validada antes da confirmação.
• A aplicação atualiza os arquivos usando substituição atômica e tenta restaurá-los em caso de falha.

Observações sobre compatibilidade com autenticação legada

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

• A fonte de credenciais do runtime é o snapshot resolvido em memória.
• As entradas estáticas legadas de api_key são removidas quando detectadas.
• O comportamento de compatibilidade relacionado ao OAuth permanece separado.

Observação sobre a interface Web

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

Relacionados

• Autenticação - configuração de autenticação
• CLI: segredos - comandos da CLI
• SecretRefs do Vault - configuração do provedor HashiCorp Vault
• Variáveis de ambiente - precedência de ambiente
• Superfície de credenciais SecretRef - superfície de credenciais
• Contrato do plano de aplicação de segredos - detalhes do contrato do plano
• Segurança - postura de segurança