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, de forma antecipada durante a ativação, e 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 somente o snapshot ativo na memória. As credenciais SecretRef de provedores de modelos 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 do Discord e envios de ações do 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 modelos respaldadas por SecretRefs, o OpenClaw cria uma sentinela opaca e local ao processo durante a resolução da autenticação do modelo. Dessa forma, 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-..., e não a credencial do provedor. A busca protegida do modelo e as sondagens gerenciadas de integridade de provedores locais substituem sentinelas conhecidas nos valores de URL e cabeçalho imediatamente antes de cada solicitação sair 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 valor exato nos logs como medida de defesa em profundidade.

Os adaptadores de provedores usam o ponto de injeção mais tardio compatível com seu SDK:

• SDKs com uma opção de busca personalizada recebem a busca protegida do OpenClaw, portanto o SDK mantém a sentinela.
• SDKs sem uma opção de busca personalizada desembrulham a sentinela imediatamente antes da criação do cliente. Streams de provedores pertencentes a Plugins e ambientes de agentes desembrulham no último ponto 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 chamadas 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 em texto simples e estão fora desse mecanismo.

Defina OPENCLAW_SECRET_SENTINELS=off (também aceita 0 ou false, sem distinção entre maiúsculas e minúsculas) para desativar a criaçã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 para ocultação de valores exatos.

Limite de acesso do agente

As SecretRefs impedem que as credenciais sejam persistidas na configuração e nos arquivos de modelos 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 ainda pode ser acessada por ferramentas de arquivo ou shell, contornando a ocultação no nível da API.

Para implantações de produção em que 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.
• Os resíduos legados de texto simples foram removidos 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.
• Todas as credenciais restantes, incompatíveis ou rotativas, sã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 é uma barreira de segurança para a migração, e não apenas um recurso auxiliar de conveniência.

Filtragem de superfícies ativas

As SecretRefs são validadas somente 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 com 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ícies ativas.

Verificação preliminar de referências na integração inicial

Na integração inicial interativa, escolher o armazenamento 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 provedores (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", // ou "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: segredo da lista de permissões

{"protocolVersion": 1,"values": {},"errors": { "providers/openai/apiKey": { "code": "NOT_FOUND" } }}

Chaves de API armazenadas em arquivo

Não coloque strings file:... no bloco env da configuração. Esse bloco é literal e não permite substituição, 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", a id da SecretRef é "value". Para mode: "json", use um ponteiro JSON absoluto, como "/providers/xai/apiKey".

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

Exemplos de integração exec

Para consultar um guia dedicado do 1Password que aborda contas de serviço, a skill de agente incluída e solução de problemas, consulte 1Password.

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // obrigatório para binários do Homebrew com 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 com 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 com 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 somente bloqueiam a ativação quando o plugin acpx está efetivamente ativo.

Material de autenticação SSH do sandbox

O backend de sandbox principal ssh 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 referências durante a ativação do sandbox, não de forma tardia 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 efetivo do sandbox não for ssh (ou o modo do sandbox for off), essas referências permanecem inativas e não bloqueiam 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 SecretRef.

Comportamento obrigatório e precedência

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

Sinais de aviso e auditoria:

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

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

Gatilhos de ativação

A ativação de segredos é executada em:

• Inicialização (pré-verificação e ativação final)
• Caminho de aplicação dinâmica do 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 da RPC de gravação da configuração do Gateway (config.set / config.apply / config.patch), que verifica a capacidade de resolução de SecretRefs das superfícies ativas na carga útil de configuração enviada antes de persistir as alteraçõ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 auxiliar/ferramenta 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 no estado de segredos degradado, emitindo eventos de sistema únicos e códigos de log:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Comportamento:

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

Resolução de caminhos de comando

Os caminhos de comando podem optar pela resolução SecretRef compatível por meio de uma RPC de snapshot do Gateway. Dois comportamentos gerais se aplicam:

Outras observações:

• A atualização do snapshot após a rotação de segredos do backend é realizada por openclaw secrets reload.
• Método RPC do Gateway usado por esses caminhos de comando: 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 de tempo de execução 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 em tempo de execução é validada antes da confirmação.
• A aplicação atualiza os arquivos usando substituição atômica de arquivos e restauração de melhor esforço em caso de falha.

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

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

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

Observação sobre a interface Web

Algumas uniões 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 da autenticação
• CLI: segredos - comandos da CLI
• SecretRefs do Vault - configuração do provedor HashiCorp Vault
• Variáveis de ambiente - precedência do 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