OpenClaw ganha guia completo em russo sobre config JSON5, CLI e configuração segura

O Habr publicou um guia detalhado do OpenClaw, plataforma em que quase toda a configuração operacional depende de um único arquivo, o openclaw.json, e de uma CLI extensa. O material reúne num só lugar o que antes era preciso garimpar na ajuda oficial, nas issues do GitHub e em posts da comunidade.

O que há no config

O autor explica como é organizado o nível superior da configuração e por que o OpenClaw exige cuidado na edição manual. O arquivo usa JSON5, então aceita comentários e vírgulas finais, mas o esquema é validado de forma muito rígida na inicialização. Se você adicionar uma chave desconhecida, o gateway simplesmente não sobe. O guia descreve separadamente gateway, env, agents, models, auth, channels, session, cron, tools, sandbox e logging, além de como funciona o recarregamento a quente sem reinício completo.

• gateway: porta, modo bind, token de acesso e comportamento do hot reload
• agents e models: configurações básicas, fallbacks e escolha de provedores
• auth e channels: troca de perfis, Telegram, Discord e outros canais
• session e cron: isolamento de conversas, resets por tempo e tarefas em segundo plano
• env e secrets: precedência das variáveis, SecretRef e armazenamento de dados sensíveis

O principal valor do material é que ele vai além de uma lista de campos. O texto explica como os diferentes níveis de configuração se relacionam, onde valem os valores padrão, quando as mudanças são aplicadas sem reiniciar e quais parâmetros é melhor não mexer manualmente. Para quem roda o OpenClaw não localmente, mas num VPS ou em ambiente de trabalho, isso deixa de ser uma referência e vira um operational playbook completo.

Onde a configuração quebra

O bloco mais útil trata não do happy path, mas das falhas típicas. O guia ressalta que alguns parâmetros funcionam apenas em agents.defaults e são ignorados silenciosamente se movidos para as configurações de um agente específico. Por isso, o config pode parecer correto e, ainda assim, o comportamento desejado não é ativado. A recomendação é simples: usar com mais frequência os comandos openclaw config get, set e unset em vez de editar diretamente, e rodar o diagnóstico após cada mudança.

openclaw doctor é o comando mais útil de toda a CLI.

O guia também trata do problema do inchaço de contexto. O OpenClaw usa dois mecanismos distintos: o pruning remove resultados antigos de ferramentas antes da chamada ao modelo, enquanto a compaction comprime o histórico quando a janela de contexto está quase cheia. Como exemplo, cita-se um caso em que 35 mensagens viraram um arquivo de sessão de 2,9 MB e um contexto de 208.467 tokens, fazendo o sistema parar de responder com um limite do modelo de 200 mil tokens.

CLI para administradores

A CLI é descrita por cenários de trabalho, e não em ordem alfabética, o que torna o guia prático. Num só lugar estão os comandos para iniciar o gateway, ver o status do daemon, gerenciar canais, logs, tarefas cron, plugins, skills, sessões e atualizações. Para os comandos de infraestrutura, os modos seguros aparecem à parte: health funciona mesmo sem o daemon em execução, security audit verifica o config em busca de riscos e secrets audit ajuda a flagrar vazamentos de credenciais antes da produção.

O último bloco importante trata de variáveis de ambiente e controle de versão. O guia fixa a ordem de precedência: primeiro o ambiente do processo, depois o .env local, em seguida o .env global no diretório do OpenClaw e só então as env.vars embutidas. Para segredos, recomenda usar referências a variáveis ou SecretRef em vez de valores no openclaw.json, e commitar no repositório apenas um modelo de configuração, deixando de fora .env, pastas de sessões, arquivos de memória e estado temporário.

O que isso significa

O OpenClaw passa a ser uma ferramenta não só para entusiastas dispostos a ler o código-fonte, mas também para equipes que precisam de um operational playbook claro. Se o projeto depende de vários modelos, canais e automações, um guia assim reduz o risco de falhas silenciosas, vazamento de segredos e comportamento instável após atualizações.