Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
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-execseja definido).configure: planejador interativo para configuração de provider, mapeamento de destino e preflight (TTY obrigatório).apply: executa um plano salvo (--dry-runapenas 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-execseja definido), depois limpa resíduos de texto simples dos destinos selecionados.
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 --checkretorna1quando há achados.- refs não resolvidas retornam
2.
- Guia de segredos: Gerenciamento de segredos
- Superfície de credenciais: Superfície de credenciais SecretRef
- Guia de segurança: Segurança
Recarregar snapshot de runtime
Resolva novamente refs de segredos e troque atomicamente o snapshot de runtime.- 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.
--url <url>--token <token>--timeout <ms>--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.jsonsobrescrevendo refs deopenclaw.json) - resíduos gerados em
agents/*/agent/models.json(valoresapiKeyde providers e cabeçalhos sensíveis de provider) - resíduos legados (entradas do armazenamento legado de auth, lembretes de OAuth)
- 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,passwordecredential).
--checksai com código diferente de zero quando há achados.- refs não resolvidas saem com código diferente de zero de prioridade mais alta.
status:clean | findings | unresolvedresolution:refsChecked,skippedExecRefs,resolvabilityCompletesummary:plaintextCount,unresolvedRefCount,shadowedRefCount,legacyResidueCount- códigos de achado:
PLAINTEXT_FOUNDREF_UNRESOLVEDREF_SHADOWEDLEGACY_RESIDUE
Configurar (helper interativo)
Crie interativamente mudanças de provider e SecretRef, execute preflight e, opcionalmente, aplique:- Primeiro configuração do provider (
add/edit/removepara aliases emsecrets.providers). - Depois mapeamento de credenciais (selecionar campos e atribuir refs
{source, provider, id}). - Por fim preflight e apply opcional.
--providers-only: configura apenassecrets.providers, ignora mapeamento de credenciais.--skip-provider-setup: ignora configuração de provider e mapeia credenciais para providers existentes.--agent <id>: limita a descoberta de destinos e gravações deauth-profiles.jsona um armazenamento de agente.--allow-exec: permite verificações de SecretRef exec durante preflight/apply (pode executar comandos do provider).
- Exige um TTY interativo.
- Você não pode combinar
--providers-onlycom--skip-provider-setup. configuretem como alvo campos que contêm segredos emopenclaw.jsone tambémauth-profiles.jsonpara o escopo de agente selecionado.configureoferece suporte à criação de novos mapeamentos emauth-profiles.jsondiretamente no fluxo de seleção.- Superfície canônica compatível: Superfície de credenciais SecretRef.
- Ele executa resolução de preflight antes do apply.
- Se o preflight/apply incluir refs exec, mantenha
--allow-execdefinido nas duas etapas. - Planos gerados ativam por padrão opções de limpeza (
scrubEnv,scrubAuthProfilesForProviderTargets,scrubLegacyAuthJsontodos ativados). - O caminho de apply é unidirecional para valores em texto simples limpos.
- Sem
--apply, a CLI ainda perguntaApply this plan now?após o preflight. - Com
--apply(e sem--yes), a CLI pede uma confirmação extra irreversível. --jsonimprime o plano + relatório de preflight, mas o comando ainda exige um TTY interativo.
- Instalações do Homebrew frequentemente expõem binários com links simbólicos em
/opt/homebrew/bin/*. - Defina
allowSymlinkCommand: trueapenas quando necessário para caminhos confiáveis de gerenciador de pacotes e combine isso comtrustedDirs(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: truenesse provider para ignorar verificações de segurança de caminho.
Aplicar um plano salvo
Aplique ou execute preflight de um plano gerado anteriormente:--dry-runvalida 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-execseja definido. - Use
--allow-execpara optar por verificações/execução de provider exec em qualquer modo.
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/.envcujos 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
audit --check ainda relatar achados de texto simples, atualize os caminhos de destino restantes informados e execute a auditoria novamente.