> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Segredos # `openclaw secrets` Use `openclaw secrets` para gerenciar SecretRefs e manter o snapshot ativo de runtime íntegro. Funções dos comandos: * `reload`: RPC do gateway (`secrets.reload`) que resolve novamente refs e troca o snapshot de runtime apenas em caso de sucesso completo (sem gravações na configuração). * `audit`: varredura somente leitura de armazenamentos de configuração/auth/modelos gerados e resíduos legados em busca de texto simples, refs não resolvidas e deriva de precedência (refs de exec são ignoradas a menos que `--allow-exec` seja definido). * `configure`: planejador interativo para configuração de provider, mapeamento de destino e preflight (TTY obrigatório). * `apply`: executa um plano salvo (`--dry-run` apenas para validação; dry-run ignora verificações de exec por padrão, e o modo de gravação rejeita planos com exec, a menos que `--allow-exec` seja definido), depois limpa resíduos de texto simples dos destinos selecionados. Loop recomendado para operadores: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw secrets audit --check openclaw secrets configure openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run openclaw secrets apply --from /tmp/openclaw-secrets-plan.json openclaw secrets audit --check openclaw secrets reload ``` Se o seu plano incluir providers/SecretRefs `exec`, passe `--allow-exec` tanto nos comandos de apply em dry-run quanto nos de gravação. Observação sobre código de saída para CI/validações: * `audit --check` retorna `1` quando há achados. * refs não resolvidas retornam `2`. Relacionado: * Guia de segredos: [Gerenciamento de segredos](/pt-BR/gateway/secrets) * Superfície de credenciais: [Superfície de credenciais SecretRef](/pt-BR/reference/secretref-credential-surface) * Guia de segurança: [Segurança](/pt-BR/gateway/security) ## Recarregar snapshot de runtime Resolva novamente refs de segredos e troque atomicamente o snapshot de runtime. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw secrets reload openclaw secrets reload --json openclaw secrets reload --url ws://127.0.0.1:18789 --token ``` Observações: * Usa o método RPC do gateway `secrets.reload`. * Se a resolução falhar, o gateway mantém o último snapshot válido conhecido e retorna um erro (sem ativação parcial). * A resposta JSON inclui `warningCount`. Opções: * `--url ` * `--token ` * `--timeout ` * `--json` ## Auditar Examine o estado do OpenClaw em busca de: * armazenamento de segredos em texto simples * refs não resolvidas * deriva de precedência (credenciais em `auth-profiles.json` sobrescrevendo refs de `openclaw.json`) * resíduos gerados em `agents/*/agent/models.json` (valores `apiKey` de providers e cabeçalhos sensíveis de provider) * resíduos legados (entradas do armazenamento legado de auth, lembretes de OAuth) Observação sobre resíduos em cabeçalhos: * A detecção de cabeçalhos sensíveis de provider é baseada em heurística de nome (nomes e fragmentos comuns de cabeçalhos de autenticação/credencial, como `authorization`, `x-api-key`, `token`, `secret`, `password` e `credential`). ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw secrets audit openclaw secrets audit --check openclaw secrets audit --json openclaw secrets audit --allow-exec ``` Comportamento de saída: * `--check` sai com código diferente de zero quando há achados. * refs não resolvidas saem com código diferente de zero de prioridade mais alta. Destaques do formato do relatório: * `status`: `clean | findings | unresolved` * `resolution`: `refsChecked`, `skippedExecRefs`, `resolvabilityComplete` * `summary`: `plaintextCount`, `unresolvedRefCount`, `shadowedRefCount`, `legacyResidueCount` * códigos de achado: * `PLAINTEXT_FOUND` * `REF_UNRESOLVED` * `REF_SHADOWED` * `LEGACY_RESIDUE` ## Configurar (helper interativo) Crie interativamente mudanças de provider e SecretRef, execute preflight e, opcionalmente, aplique: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw secrets configure openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json openclaw secrets configure --apply --yes openclaw secrets configure --providers-only openclaw secrets configure --skip-provider-setup openclaw secrets configure --agent ops openclaw secrets configure --json ``` Fluxo: * Primeiro configuração do provider (`add/edit/remove` para aliases em `secrets.providers`). * Depois mapeamento de credenciais (selecionar campos e atribuir refs `{source, provider, id}`). * Por fim preflight e apply opcional. Flags: * `--providers-only`: configura apenas `secrets.providers`, ignora mapeamento de credenciais. * `--skip-provider-setup`: ignora configuração de provider e mapeia credenciais para providers existentes. * `--agent `: limita a descoberta de destinos e gravações de `auth-profiles.json` a um armazenamento de agente. * `--allow-exec`: permite verificações de SecretRef exec durante preflight/apply (pode executar comandos do provider). Observações: * Exige um TTY interativo. * Você não pode combinar `--providers-only` com `--skip-provider-setup`. * `configure` tem como alvo campos que contêm segredos em `openclaw.json` e também `auth-profiles.json` para o escopo de agente selecionado. * `configure` oferece suporte à criação de novos mapeamentos em `auth-profiles.json` diretamente no fluxo de seleção. * Superfície canônica compatível: [Superfície de credenciais SecretRef](/pt-BR/reference/secretref-credential-surface). * Ele executa resolução de preflight antes do apply. * Se o preflight/apply incluir refs exec, mantenha `--allow-exec` definido nas duas etapas. * Planos gerados ativam por padrão opções de limpeza (`scrubEnv`, `scrubAuthProfilesForProviderTargets`, `scrubLegacyAuthJson` todos ativados). * O caminho de apply é unidirecional para valores em texto simples limpos. * Sem `--apply`, a CLI ainda pergunta `Apply this plan now?` após o preflight. * Com `--apply` (e sem `--yes`), a CLI pede uma confirmação extra irreversível. * `--json` imprime o plano + relatório de preflight, mas o comando ainda exige um TTY interativo. Observação de segurança para provider exec: * Instalações do Homebrew frequentemente expõem binários com links simbólicos em `/opt/homebrew/bin/*`. * Defina `allowSymlinkCommand: true` apenas quando necessário para caminhos confiáveis de gerenciador de pacotes e combine isso com `trustedDirs` (por exemplo `["/opt/homebrew"]`). * No Windows, se a verificação de ACL não estiver disponível para um caminho de provider, o OpenClaw falha de forma fechada. Apenas para caminhos confiáveis, defina `allowInsecurePath: true` nesse provider para ignorar verificações de segurança de caminho. ## Aplicar um plano salvo Aplique ou execute preflight de um plano gerado anteriormente: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json ``` Comportamento de exec: * `--dry-run` valida o preflight sem gravar arquivos. * Verificações de SecretRef exec são ignoradas por padrão em dry-run. * O modo de gravação rejeita planos que contenham SecretRefs/providers exec, a menos que `--allow-exec` seja definido. * Use `--allow-exec` para optar por verificações/execução de provider exec em qualquer modo. Detalhes do contrato do plano (caminhos de destino permitidos, regras de validação e semântica de falha): * [Contrato de plano de apply de segredos](/pt-BR/gateway/secrets-plan-contract) O que `apply` pode atualizar: * `openclaw.json` (destinos de SecretRef + upserts/exclusões de provider) * `auth-profiles.json` (limpeza de destinos de provider) * resíduos legados em `auth.json` * chaves de segredo conhecidas em `~/.openclaw/.env` cujos valores foram migrados ## Por que não há backups para rollback `secrets apply` intencionalmente não grava backups de rollback contendo valores antigos em texto simples. A segurança vem de preflight rigoroso + apply quase atômico com restauração em memória em melhor esforço em caso de falha. ## Exemplo ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw secrets audit --check openclaw secrets configure openclaw secrets audit --check ``` Se `audit --check` ainda relatar achados de texto simples, atualize os caminhos de destino restantes informados e execute a auditoria novamente. ## Relacionado * [Referência da CLI](/pt-BR/cli) * [Gerenciamento de segredos](/pt-BR/gateway/secrets)