OpenClaw Model Manager: uma GUI para eu parar de editar à mão o JSON de roteamento de modelos

Uma vez eu digitei errado o id de um modelo num arquivo JSON, e o agente que o usava simplesmente ficou quieto. Sem erro, sem crash. Ele ficou ali conversando com um modelo que não existia enquanto eu caçava um bug bem mais interessante. Este app é o meu nunca-mais.

O que você ganha

Primeiro, as capturas de tela. Elas vêm de uma cópia isolada rodando contra uma configuração fictícia num HOME descartável. App de verdade, dados falsos, nenhuma das minhas chaves.

A janela principal responde à pergunta que eu costumava resolver dando grep em JSON: qual modelo está rodando onde, e quanto custa? Cada agente, os padrões de toda a stack, o override de subagente, tarefas cron, até os modelos de um agente de e-mail irmão. Cada entrada recebe um selo colorido: Local (este PC), Remote (o segundo PC), ou Cloud (o que aparece na fatura).

Por que isso existe

O OpenClaw é a stack multiagente que rodo em casa: vários agentes de IA, cada um apontado para um modelo, alguns locais e gratuitos, outros na nuvem e cobrados. Todo o roteamento vive em um único arquivo, ~/.openclaw/openclaw.json: catálogo de modelos, atribuições primário/fallback por agente, configurações de provedor, e até o próprio token de autenticação do gateway. Editar isso à mão sempre dava errado de duas formas.

Primeiro, um id de modelo errado falha em silêncio. Um padrão obsoleto certa vez apontou um agente para vllm/google/gemma-4-31b-qat, um modelo que o provedor nunca serviu. Uma gravação malformada é pior ainda: uma edição ruim e o gateway inteiro entra em crash loop.

Segundo, trocar o backend da CLI do Claude Code é uma cirurgia invisível de variáveis de ambiente. O OpenClaw invoca o Claude Code para tarefas de código, e para onde essas requisições vão — e quem paga a conta — é definido pelas variáveis de ambiente ANTHROPIC_* na unidade systemd do gateway. Alternar entre local gratuito, DeepSeek barato e Anthropic de verdade significava escrever à mão um drop-in do systemd toda vez. Exatamente o tipo de coisa que eu erro às 23h.

O caminho do salvar

A parte em que eu preciso confiar é o que acontece quando você clica em Salvar. É isto, em ordem:

Duas etapas carregam o peso. A validação recusa qualquer id de modelo que o provedor não anuncie, o que torna o bug de digitação da introdução estruturalmente impossível em vez de algo que eu preciso lembrar de conferir. E a gravação atômica existe porque o openclaw.json guarda o token de autenticação do gateway e precisa continuar chmod 600: o arquivo temporário recebe as permissões do original antes de qualquer conteúdo ser escrito, depois é feito fsync e o rename sobre o original. Se der crash no meio do salvamento, o arquivo antigo fica intocado.

Uma gravação ruim está a um rename de distância de ser desfeita, e você mantém cinco gerações de histórico em vez de uma só.

O drop-in do Coding Helper

Redirecionar a CLI do Claude Code é um fluxo separado porque nunca toca no openclaw.json. Ele escreve um drop-in do systemd que sobrescreve o ambiente do gateway antes de o gateway invocar o Claude Code.

Quatro modos, um único menu suspenso: LM Studio (gratuito, local), DeepSeek via seu endpoint compatível com Anthropic (barato), Anthropic Cloud (o padrão: nenhum drop-in, nada sobrescrito), ou Disabled, que aponta a CLI para http://127.0.0.1:9/blocked para que toda chamada falhe rápido em vez de travar. Também há um teste ao vivo de um clique que dispara um ping real no formato Anthropic para o LM Studio ou o DeepSeek e relata qual modelo realmente respondeu. Você não está confiando numa tela de configuração — está confiando numa requisição que acabou de acontecer.

Mantendo a chave de API fora do arquivo de unidade

O modo DeepSeek precisa de uma chave de API, e um arquivo de unidade systemd é um péssimo lugar para guardá-la: qualquer coisa escrita ali diretamente fica em texto puro no disco e na saída de systemctl show. Então o drop-in nunca contém a chave. Em vez disso, ele escreve isto:

ExecStart=/usr/bin/bash -c 'export ANTHROPIC_API_KEY="$$DEEPSEEK_API_KEY"; exec <gateway cmd>'

O truque é o $$. Em um arquivo de unidade, $$ escapa um $ literal. Sem isso, o systemd expandiria a variável ele mesmo ao montar a linha de comando, e a chave real acabaria no argv do processo, onde o ps consegue ler. Com o cifrão duplo, o bash recebe um $DEEPSEEK_API_KEY literal e o expande em tempo de execução a partir do EnvironmentFile do gateway (~/.openclaw/gateway.systemd.env, chmod 600). O segredo nunca aparece no arquivo de unidade, no systemctl show, nem em uma listagem de processos — só dentro do próprio ambiente do bash, para aquele único processo. A pasta examples/ do zip documenta o padrão com placeholders CHANGE_ME.

Instalação

Do README que vem no zip:

# 1. Install GTK4 + libadwaita + PyGObject from your distro's packages
#    (one dnf/apt line — see README-SETUP.md for the exact package names)

# 2. Install the app and its launcher
install -Dm755 openclaw-model-manager ~/.local/bin/openclaw-model-manager
# .desktop file goes to ~/.local/share/applications/

# 3. If you don't already have an OpenClaw config:
cp examples/openclaw.json.example ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/openclaw.json
# then replace every CHANGE_ME placeholder inside it

# 4. Optional — API keys, both chmod 600, examples provided:
#    ~/.openclaw/.env
#    ~/.openclaw/gateway.systemd.env

Nenhuma instalação via pip além do PyGObject; todo o resto é biblioteca padrão do Python 3.11+, tomllib incluso. O pacote inteiro é um único script executável (164KB, 3.570 linhas), um lançador .desktop, um README, uma licença MIT e quatro configurações de exemplo. Zipado, fica em 49KB.

Pegadinhas

• Modo Cloud significa "sem drop-in", não "com certeza a minha conta Anthropic". Nada é sobrescrito, então o que já estava configurado na unidade continua rodando. O app avisa quando o modo escolhido não tem uma chave funcional, mas confira mesmo assim.
• O drop-in sobrepõe sua chave real da Anthropic, de propósito. O modo Local define ANTHROPIC_API_KEY=lm-studio para tudo que o gateway invoca. Na minha máquina, isso redirecionou em silêncio meus aliases interativos da CLI claude para o LM Studio — o Claude Code continuava "funcionando", só que as respostas vinham de um modelo local. Se o Claude começar a soar estranho, rode systemctl --user cat openclaw-gateway.service e procure um drop-in antes de culpar o modelo.
• Depois que openclaw update muda o ExecStart do gateway, selecione o modo DeepSeek de novo para reembrulhar o novo comando. O app lê o ExecStart canônico a partir do fragmento de unidade e detecta seu próprio wrapper (ele se baseia em index.js mais a ausência de $$DEEPSEEK_API_KEY), então nunca embrulha em dobro — mas também não corrige sozinho um comando que não foi mandado olhar de novo.
• reasoning: true é o padrão seguro para modelos locais. Um modelo que emite reasoning_content enquanto está configurado com reasoning: false parece travado para o gateway: cerca de 390 segundos de silêncio, depois um kill. É inofensivo deixar ligado em modelos que não pensam, então o diálogo de adicionar modelo já vem com isso ativado por padrão. Este aqui custou um tempo de depuração de verdade.
• Um plugins.allow não vazio é uma lista de permissão estrita. enabled: true numa entrada de plugin não faz nada a menos que o id também esteja em allow. O app lê isso corretamente e deliberadamente nunca escreve em plugins.*, então, se um plugin se comportar mal, esta não é a ferramenta que vai explicar o porquê.
• O gateway reescreve o openclaw.json por conta própria (reconciliação de identidade, openclaw update). O app acompanha o mtime do arquivo e avisa antes de sobrescrever uma edição externa, e o backup pré-gravação preserva o que realmente estava no disco.
• Ids de modelo são provider/raw-id. Um id sem barra resolve pelo endpoint local do LM Studio. Não é um erro, só uma convenção que vale a pena conhecer antes de sair procurando um campo de provider que não existe.

Downloads

• Baixar o código-fonte do OpenClaw Model Manager (zip) 48 KB

Gratuito para uso pessoal. Se isso te economizar uma tarde, o botão do café está logo ali.