Pular para o conteúdo principal
OpenClaw oferece suporte a SecretRefs aditivos para que credenciais compatíveis não precisem ser armazenadas como texto simples na configuração.
Texto simples ainda funciona. SecretRefs são opcionais por credencial.
Credenciais em texto simples continuam legíveis pelo agente se forem armazenadas em arquivos que o agente possa inspecionar, incluindo openclaw.json, auth-profiles.json, .env ou arquivos agents/*/agent/models.json gerados. SecretRefs reduzem esse raio de impacto local somente depois que todas as credenciais compatíveis tiverem sido migradas e openclaw secrets audit --check não relatar nenhum resíduo de segredo em texto simples.

​
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.
SecretRefs não tornam seguros arquivos arbitrários legíveis. Backups, configurações copiadas, catálogos de modelos gerados antigos e classes de credenciais sem suporte devem ser tratados como segredos de produção até serem excluídos, movidos para fora do limite de confiança do agente ou protegidos por uma camada de isolamento separada.

​
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.
  • Entradas de canal/conta desabilitadas.
  • Credenciais de canal de nível superior que nenhuma conta habilitada herda.
  • Superfícies de ferramenta/recurso desabilitadas.
  • Chaves específicas de provedor de busca na web que não são selecionadas por tools.web.search.provider. No modo automático (provedor não definido), as chaves são consultadas por precedência para autodetecção de provedor até que uma seja resolvida. Após a seleção, chaves de provedores não selecionados são tratadas como inativas até serem selecionadas.
  • Material de autenticação SSH do sandbox (agents.defaults.sandbox.ssh.identityData, certificateData, knownHostsData, além de substituições por agente) fica ativo somente quando o backend efetivo do sandbox é ssh para o agente padrão ou um agente habilitado.
  • SecretRefs de gateway.remote.token / gateway.remote.password ficam ativos se uma destas condições for verdadeira:
    • gateway.mode=remote
    • gateway.remote.url está configurado
    • gateway.tailscale.mode é serve ou funnel
    • Em modo local sem essas superfícies remotas:
      • gateway.remote.token fica ativo quando a autenticação por token pode vencer e nenhum token de env/auth está configurado.
      • gateway.remote.password fica ativo somente quando a autenticação por senha pode vencer e nenhuma senha de env/auth está configurada.
  • O SecretRef de gateway.auth.token fica inativo para resolução de autenticação na inicialização quando OPENCLAW_GATEWAY_TOKEN está definido, porque a entrada de token por env vence para esse runtime.

​
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" }
Campos SecretInput compatíveis também aceitam abreviações de string exatas:
"${OPENAI_API_KEY}"
"$OPENAI_API_KEY"
Validação:
  • provider deve corresponder a ^[a-z][a-z0-9_-]{0,63}$
  • id deve corresponder a ^[A-Z][A-Z0-9_]{0,127}$

​
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,
    },
  },
}
  • Allowlist opcional via allowlist.
  • Valores de env ausentes/vazios falham a resolução.
  • Lê o arquivo local de path.
  • mode: "json" espera um payload de objeto JSON e resolve id como ponteiro.
  • mode: "singleValue" espera o id de ref "value" e retorna o conteúdo do arquivo.
  • O caminho deve passar pelas verificações de propriedade/permissão.
  • Observação de falha fechada no Windows: se a verificação de ACL estiver indisponível para um caminho, a resolução falha. Somente para caminhos confiáveis, defina allowInsecurePath: true nesse provedor para contornar verificações de segurança de caminho.
  • Executa o caminho absoluto do binário configurado, sem shell.
  • Por padrão, command deve apontar para um arquivo regular (não um symlink).
  • Defina allowSymlinkCommand: true para permitir caminhos de comando symlink (por exemplo, shims do Homebrew). O OpenClaw valida o caminho de destino resolvido.
  • Combine allowSymlinkCommand com trustedDirs para caminhos de gerenciadores de pacotes (por exemplo, ["/opt/homebrew"]).
  • Oferece suporte a timeout, timeout sem saída, limites de bytes de saída, allowlist de env e diretórios confiáveis.
  • Observação de falha fechada no Windows: se a verificação de ACL estiver indisponível para o caminho do comando, a resolução falha. Somente para caminhos confiáveis, defina allowInsecurePath: true nesse provedor para contornar verificações de segurança de caminho.
  • Provedores exec gerenciados por Plugin podem usar pluginIntegration em vez de command/args copiados. O OpenClaw resolve os detalhes do comando atual a partir do manifesto do Plugin instalado durante a inicialização/recarregamento. Se o Plugin estiver desabilitado, removido, não confiável ou não declarar mais a integração, SecretRefs ativos que usam esse provedor falham fechados.
Payload de requisição (stdin):
{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }
Payload de resposta (stdout):
{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret
Erros opcionais por id:
{
  "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" },
      },
    },
  },
}
Use um wrapper de resolução quando quiser que os ids de SecretRef sejam mapeados para chaves de item do Bitwarden Secrets Manager. O repositório inclui scripts/secrets/openclaw-bws-resolver.mjs; instale-o ou copie-o para um caminho absoluto confiável no host que executa o Gateway.Requisitos:
  • CLI do Bitwarden Secrets Manager (bws) instalado no host do Gateway.
  • BWS_ACCESS_TOKEN disponível para o serviço Gateway.
  • PATH passado para o resolvedor, ou BWS_BIN definido como o caminho absoluto do binário bws.
  • BWS_SERVER_URL deve ser definido no ambiente ao usar uma instância auto-hospedada do Bitwarden.
{
  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",
        },
      },
    },
  },
}
O resolvedor agrupa os ids solicitados, executa bws secret list e retorna valores para campos key de segredos correspondentes. Use chaves que satisfaçam o contrato de id SecretRef de exec, como openclaw/providers/openai/apiKey; chaves no estilo de variáveis de ambiente com sublinhados são rejeitadas antes da execução do resolvedor. Se mais de um segredo visível do Bitwarden tiver a mesma chave solicitada, o resolvedor falhará esse id como ambíguo em vez de escolher um. Depois de atualizar a configuração, verifique o caminho do resolvedor:
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" },
      },
    },
  },
}
Use um pequeno wrapper de resolução quando quiser que ids de SecretRef sejam mapeados diretamente para entradas pass. Salve-o como executável em um caminho absoluto que passe nas verificações de caminho do seu provedor exec, por exemplo /usr/local/bin/openclaw-pass-resolver. O shebang #!/usr/bin/env node resolve node a partir do PATH do processo do resolvedor, então inclua PATH em passEnv. Se pass não estiver nesse PATH, defina PASS_BIN no ambiente pai e também o inclua em passEnv:
#!/usr/bin/env node
const { 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 }));
});
Em seguida, configure o provedor exec e aponte apiKey para o caminho da entrada pass:
{
  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",
        },
      },
    },
  },
}
Mantenha o segredo na primeira linha da entrada pass, ou personalize o wrapper se quiser retornar a saída completa de pass show. Depois de atualizar a configuração, verifique tanto a auditoria estática quanto o caminho do resolvedor exec:
openclaw secrets audit --check
openclaw 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:
Credenciais emitidas em tempo de execução ou rotativas e material de atualização OAuth são intencionalmente excluídos da resolução SecretRef somente leitura.

​
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:
Por exemplo, caminhos de memória remota de openclaw memory e openclaw qr --remote quando ele precisa de refs de segredo compartilhado remoto. Eles leem a partir do snapshot ativo e falham rapidamente quando uma SecretRef obrigatória está indisponível.
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:
1

Auditar o estado atual

openclaw secrets audit --check
2

Configurar e aplicar SecretRefs

openclaw secrets configure --apply
3

Auditar novamente

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.
As descobertas incluem:
  • valores em texto claro em repouso (openclaw.json, auth-profiles.json, .env e agents/*/agent/models.json gerado)
  • resíduos de cabeçalho sensível de provedor em texto claro em entradas geradas de models.json
  • refs não resolvidas
  • sombreamento de precedência (auth-profiles.json tendo prioridade sobre refs de openclaw.json)
  • resíduos legados (auth.json, lembretes de OAuth)
Observação sobre exec:
  • Por padrão, a auditoria ignora verificações de resolução de SecretRef exec para evitar efeitos colaterais de comando.
  • Use openclaw secrets audit --allow-exec para executar provedores exec durante a auditoria.
Observação sobre resíduos de cabeçalho:
  • A detecção de cabeçalhos sensíveis de provedor é baseada em heurística de nomes (nomes e fragmentos comuns de cabeçalhos de autenticação/credenciais, como authorization, x-api-key, token, secret, password e credential).
Auxiliar interativo que:
  • configura primeiro secrets.providers (env/file/exec, adicionar/editar/remover)
  • permite selecionar campos compatíveis que contêm segredos em openclaw.json mais auth-profiles.json para um escopo de agente
  • pode criar um novo mapeamento de auth-profiles.json diretamente no seletor de destino
  • captura detalhes da SecretRef (source, provider, id)
  • executa resolução de preflight
  • pode aplicar imediatamente
Observação sobre exec:
  • O preflight ignora verificações de SecretRef exec a menos que --allow-exec esteja definido.
  • Se você aplicar diretamente a partir de configure --apply e o plano incluir refs/provedores exec, mantenha --allow-exec definido também para a etapa de aplicação.
Modos úteis:
  • openclaw secrets configure --providers-only
  • openclaw secrets configure --skip-provider-setup
  • openclaw secrets configure --agent <id>
Padrões de aplicação de configure:
  • limpar credenciais estáticas correspondentes de auth-profiles.json para provedores direcionados
  • limpar entradas estáticas legadas de api_key de auth.json
  • limpar linhas conhecidas de segredo correspondentes de <config-dir>/.env
Aplicar um plano salvo:
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
Observação sobre exec:
  • dry-run ignora verificações de exec a menos que --allow-exec esteja definido.
  • o modo de gravação rejeita planos contendo SecretRefs/provedores exec a menos que --allow-exec esteja definido.
Para detalhes do contrato estrito de destino/caminho e regras exatas de rejeição, consulte Contrato de plano do Secrets Apply.

​
Política de segurança unidirecional

OpenClaw intencionalmente não grava backups de rollback contendo valores históricos de segredo em texto claro.
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