Custo e configuração da API ZeroClaw: runtime gratuito, provedores personalizados e custo real dos tokens

O runtime do ZeroClaw custa $0: ele é de código aberto, duplamente licenciado sob MIT OU Apache-2.0, e o FAQ do próprio zeroclaw.com afirma que não há assinatura nem assento hospedado — você paga apenas os custos do seu próprio provedor de LLM, ou nada se executar um modelo local com Ollama. A documentação de filosofia do projeto é ainda mais direta: "Não é um SaaS. Não há versão hospedada, sistema de contas nem cobrança." Portanto, na prática, "preços do ZeroClaw" significa outras duas contas — tokens do modelo no endpoint para o qual você aponta um alias e a máquina em que o daemon é executado. Ambos verificados em 21 de setembro de 2026.

Duas coisas custarão dinheiro ou tempo se você ignorá-las. O ZeroClaw Labs não publica nenhum preço mensal, portanto uma assinatura mensal de "ZeroClaw" que você já tenha visto é produto de outra pessoa. E o próprio registro de custos do ZeroClaw informará gasto zero em um gateway de terceiros até que você digite manualmente as tarifas, porque o slot de provedor custom não tem um catálogo de preços por trás dele. Ambos os pontos são abordados abaixo.

Preços do ZeroClaw: quanto o software custa e o que realmente gera cobrança

A última linha é o ponto de referência errado em que uma busca por "preços do zeroclaw" pode cair. O README do ZeroClaw nomeia github.com/zeroclaw-labs/zeroclaw como o único repositório oficial e afirma que qualquer outro repositório, organização, domínio ou pacote que alegue ser o ZeroClaw não é autorizado nem afiliado. Um segundo valor mensal por agente circula nos snippets de busca de zeroclaw.live; esse site retornou um erro, e não uma página, em 21 de setembro de 2026, portanto o número não pôde ser lido na página e deliberadamente não é reproduzido aqui. Separadamente, trate os números de marketing com cuidado até mesmo em domínios usados pelo próprio projeto: as landing pages de zeroclaw.dev, zeroclaw.org e zeroclaw.net anunciam todas um binário de 3.4MB, enquanto a própria página de filosofia do projeto diz que um build de release típico chega a cerca de 26 MiB. Essa é uma diferença entre documentação e landing page, não uma evidência de personificação — o próprio README direciona os relatos de segurança para um endereço em zeroclaw.dev. ZeroClaw vs OpenClaw examina detalhadamente esse problema de identificação.

Uma observação de escopo, pois os dois fatos parecem contraditórios. "Sem cobrança" é verdade para o runtime do ZeroClaw e falso para o ZeroClaw Labs como organização: a mesma organização no GitHub oferece o ZeroRouter, um gateway AGPL cuja descrição do repositório menciona cobrança pré-paga via Stripe, acessível pelo ZeroClaw por meio de seu próprio slot zerorouter. É um produto diferente em beta, não uma assinatura do ZeroClaw, e seus preços hospedados representam o estado atual do gateway, não uma lista de preços publicada.

A estrutura de configuração a ser escrita hoje: schema 3, não o trecho plano

A documentação oficial está atualizada; grande parte da configuração do ZeroClaw que você encontrará nos resultados de busca não está. A versão atual do schema de configuração é 3 — CURRENT_SCHEMA_VERSION: u32 = 3 em crates/zeroclaw-config/src/migration.rs na tag de release v0.8.5, com uma cadeia de migração de V1 para V2 e para V3. A estrutura plana que circula em tutoriais antigos é o schema 1. Um arquivo de configuração sem schema_version é tratado como versão 1 e migrado em memória durante o carregamento, portanto o arquivo no disco não é reescrito pelo próprio carregamento.

Observe a nomenclatura: "ZeroClaw V3" não é um release. O release mais recente é v0.8.5, publicado em 5 de setembro de 2026 (API do GitHub, verificada em 21 de setembro de 2026); o schema 3 é o formato de configuração dentro dele. Os dois números não têm relação.

Nomes de campos do schema 1 lidos da lente de migração V1 na v0.8.5; as linhas do schema 2 vêm dos comentários de documentação da lente V2 no master, ambos em 21 de setembro de 2026. Essas lentes são a forma como um arquivo antigo é analisado durante a migração, razão pela qual são boas evidências dos nomes de campos antigos. Na última linha, duas fontes de datas diferentes divergem: a lente V2 registra que a V3 descartou cost.prices e moveu os preços para dentro de cada provedor de modelo, enquanto a atual documentação de acompanhamento de custos chama o campo pricing embutido por alias de legado e nomeia [cost.rates.*] como a superfície voltada para o futuro que prevalece em caso de conflito. Escreva [cost.rates.*].

No schema 3, cada provedor de modelo fica em [providers.models.<type>.<alias>], em que o tipo é um slot de família canônico — "Há um slot por fornecedor, sem sinônimos" — e o alias é definido por você. A visão geral dos provedores é explícita ao afirmar que "não há uma opção de 'provedor padrão' ou 'modelo padrão' global" e que Config::validate() falha explicitamente na inicialização se alguma referência não for resolvida. Um trecho copiado do schema 1 não é rejeitado por ser antigo — a cadeia de migração reúne seu api_key, api_url e default_model do nível superior em uma entrada de provedor nomeada por default_provider, e a lente V1 substitui openrouter quando essa chave está ausente; assim, um trecho plano contendo apenas uma chave e uma URL termina em uma entrada openrouter, e não no gateway pretendido. O modo de falha é uma referência não resolvida, não um nome de campo antigo.

Provedor personalizado do ZeroClaw: apontando um alias para uma API compatível com OpenAI

Um endpoint que fala chat-completions da OpenAI deve ser colocado no slot custom, e a página de provedor personalizado na v0.8.5 diz que esta é uma alteração apenas de configuração: "O slot custom exige uri (o enum de endpoints da família não tem um valor padrão)." Um endpoint que fala o protocolo Anthropic Messages deve ser colocado no slot anthropic, com uri definido como override — e não em custom. A Kunavo oferece os dois formatos de protocolo em https://api.kunavo.com/v1 com uma única chave, portanto, em princípio, qualquer um dos dois slots serve. O trecho abaixo combina os campos documentados do slot personalizado com a estrutura de quatro cabeçalhos do exemplo prático da própria documentação; é uma adaptação, não um bloco oficial copiado.

# Four section headers is the smallest config that loads clean.
[providers.models.custom.kunavo]
uri     = "https://api.kunavo.com/v1"   # REQUIRED: the custom family has no default endpoint
model   = "claude-sonnet-4-6"
api_key = "sk-kn-..."                   # or the secrets store, op://, or a ZEROCLAW_ env override

[agents.assistant]
model_provider  = "custom.kunavo"       # there is no global default provider
risk_profile    = "supervised"
runtime_profile = "resident"

[risk_profiles.supervised]
level                            = "supervised"
workspace_only                   = true
require_approval_for_medium_risk = true
block_high_risk_commands         = true

[runtime_profiles.resident]
max_actions_per_hour   = 10             # example values from the docs, not defaults
max_cost_per_day_cents = 100
max_tool_iterations    = 4
agentic_timeout_secs   = 120

Quatro observações práticas. As credenciais podem ser fornecidas de quatro formas — api_key embutido, uma referência do 1Password op://vault/item/field, o armazenamento criptografado em ~/.zeroclaw/secrets ou a substituição genérica de ambiente ZEROCLAW_providers__models__custom__kunavo__api_key, na qual um sublinhado duplo mapeia para um ponto. Um nome de shell padrão do ecossistema, como $ANTHROPIC_API_KEY, não é lido diretamente, a menos que a família do provedor documente sua própria ponte de ambiente nativa — a documentação orienta você a expandi-lo manualmente para o nome espelhado no schema — e uma variável de ambiente espelhada no schema é uma injeção em tempo de execução que nunca se torna configuração persistente. O slot custom usa por padrão o protocolo chat-completions, e wire_api é respeitado nas famílias de endpoints próprios (openai, llamacpp, custom), enquanto os slots de fornecedores com marca têm um protocolo fixo e o ignoram, com opencode nomeado como a única exceção. Se o seu gateway rejeitar um campo temperature, deixe-o sem definir: a documentação afirma que um temperature não definido é totalmente omitido do corpo da solicitação. E uma inicialização limpa prova menos do que parece — o aquecimento da conexão é um GET que consome o corpo e aceita códigos de status que não indicam sucesso, portanto o daemon inicia de qualquer maneira; a página de provedor personalizado no master o documenta como GET {base_url}/models, enquanto o código da v0.8.5 aquece a URL de chat-completions.

Valide na ordem documentada, todos os três na v0.8.5: zeroclaw config list carrega a configuração e imprime falhas de validação em stderr, zeroclaw models refresh --model-provider custom.kunavo lista o que o endpoint anuncia e zeroclaw agent -a assistant -m "hello" faz um smoke test do agente. O próprio /v1/models da Kunavo responde HTTP 401 sem uma chave (verificado em 21 de setembro de 2026), o que não é um bloqueio: o comando de atualização envia a chave do alias. A Kunavo não testou o ZeroClaw em runtime — tudo nesta seção é uma revisão dos documentos-fonte do ZeroClaw; portanto, execute sua própria tarefa limitada antes de confiar na rota.

A Kunavo não oferece nenhum modelo de embeddings, conversão de texto em fala ou conversão de fala em texto; portanto, um agente que precise dessas etapas deve apontá-las para um endpoint diferente, independentemente do slot do ZeroClaw em que o modelo de chat esteja.

O medidor de custos lê $0 até você escrever a tabela de tarifas

O ZeroClaw mede seu próprio gasto e, em um gateway de terceiros, esse medidor começa incorreto. O acompanhamento de custos é controlado por cost.enabled, e os registros vão para um ledger somente de acréscimos em <workspace>/state/costs.jsonl, com um objeto JSON por linha. O problema é a origem dos preços. Em catalog.rs na v0.8.5, catalog_source_for não retorna uma chave models.dev nem um prefixo de fornecedor OpenRouter para a família custom — a maioria dos slots com marca tem pelo menos um dos dois, embora vários (zerorouter, telnyx, nearai) não tenham nenhum dos dois. A opção live_pricing fica desativada por padrão e, quando ativada, lê primeiro a listagem /models do próprio endpoint e recorre ao models.dev usando como chave o nome models.dev da família; a família custom não tem essa chave, portanto, nesse slot, a listagem do próprio endpoint é a única fonte. A listagem da Kunavo não contém um campo de preço por token, lido da origem da rota, e não de uma resposta de produção autenticada. Assim, um alias de slot personalizado registra cost_usd = 0 com unpriced_tokens acima de zero até que você digite as tarifas por conta própria.

[cost]
enabled = true

# Keyed by the UPSTREAM model id as it appears in usage telemetry,
# not by your alias. USD per 1M tokens.
[cost.rates.providers.models.custom.claude-sonnet-4-6]
input        = 2.1
output       = 10.5
cached_input = 0.21

Três comportamentos decorrem disso, todos da documentação de acompanhamento de custos, verificada em 21 de setembro de 2026. As entradas de tarifas usam como chave o ID do modelo upstream conforme aparece na telemetria de uso, não o seu alias. As comparações de orçamento usam o cost_usd registrado; portanto, um total diário ou mensal abaixo do limite não é garantia de segurança enquanto o mês contiver tokens sem preço. E as linhas existentes do ledger nunca são recalculadas: "não há recálculo retroativo de preços", portanto as tarifas se aplicam apenas às solicitações feitas depois que você as configura. A aplicação tem três modos — warn (o padrão), block e route_down, que substitui por um route_down_model mais barato — além de allow_override, que usa false por padrão e permite que uma solicitação ignore block com um token de substituição na CLI.

Uma estimativa prática usando o próprio limite diário do ZeroClaw

Isto é uma aritmética ilustrativa de tokens, não um custo medido de tarefa nem um teto de cobrança. O exemplo prático da documentação com [runtime_profiles] limita um agente a max_actions_per_hour = 10 e max_cost_per_day_cents = 100 — valores de exemplo para um modelo local pequeno, não padrões. Considere esse teto literalmente por oito horas ativas por dia: 80 turnos por dia, cada um enviando 6.000 tokens de entrada não armazenados em cache e retornando 500 tokens de saída. As tarifas são os preços atuais do catálogo da Kunavo por milhão de tokens.

A interpretação útil não é o ranking, mas a interação com o limite. Um perfil escrito para um modelo local pequeno coloca um modelo de fronteira sob os mesmos limites: max_actions_per_hour restringe o volume de turnos, e o limite diário de custo recusa uma solicitação somente quando enforcement.mode é block. Com warn, o padrão, o limite não bloqueia nada — ele registra o evento e permite a solicitação. (warn_at_percent, 80% por padrão, é uma opção separada: controla quando o gateway exibe um banner de aviso antes do limite rígido.) Pior: se você nunca escreveu a tabela de tarifas acima, nada disso é acionado, porque o limite não consegue enxergar tokens sem preço. Dimensione a tabela pela sua própria quantidade de turnos e proporção de entrada e saída antes de tratá-la como orçamento; ela exclui cobranças de cache, chamadas de ferramentas e novas tentativas, e pressupõe que o modelo mais barato conclua o trabalho sem tentativas adicionais.

O valor do catálogo da Kunavo é um piso de cobrança, não um limite: quando o upstream informa sua cobrança, o valor faturado é o maior entre o custo do catálogo e o custo do upstream multiplicado pelo markup aplicável. O recarregamento mínimo é $10 em crédito pré-pago, o que representa um mínimo de financiamento, não uma tarifa por tarefa nem uma assinatura — consulte detalhes de cobrança.

Melhor modelo e melhor API para o ZeroClaw: o que o projeto dirá e não dirá

O ZeroClaw não publica nenhum modelo recomendado e se recusa a fazê-lo oficialmente. Sua página de configuração multimodelo afirma que "esse fluxo de trabalho não estabelece uma lista de modelos verificada pelo ZeroClaw" e que "evidências de um build, modelo, quantização e configuração de contexto não verificam outras combinações". Essa é a resposta honesta para "melhor modelo para o ZeroClaw": não há um ranking oficial a citar; portanto, escolha com base em duas propriedades testáveis.

A primeira é a chamada nativa de ferramentas, e a mesma página estabelece um critério rigoroso para isso: "Inspecione a execução em busca de uma chamada de ferramenta real, seu resultado executado e uma continuação do assistente que use esse resultado. Uma resposta plausível ou apenas uma marcação de chamada de ferramenta impressa não é um teste de ferramenta aprovado." A opção de perfil de runtime strict_tool_parsing trata texto de fallback com aparência de XML ou JSON como texto comum do assistente, a menos que o provedor retorne chamadas de ferramentas reais; portanto, um modelo que apenas descreva uma chamada de ferramenta parecerá estar funcionando e nunca agirá. A segunda é saber se o modelo conclui sua tarefa sem tentativas adicionais — por isso, o menor preço listado e o menor custo para concluir são afirmações diferentes.

Vale fazer um orçamento para dois comportamentos antes de ativar o failover. O streaming tem o contrato mais restrito: a página do ciclo de vida do roteamento de provedores diz que o wrapper “escolhe a primeira entrada ordenada que oferece suporte às capacidades de streaming solicitadas e não está em período de espera” e então “abre esse stream uma vez” e “não troca de entrada depois que o stream foi iniciado” — embora um stream que falhe antes de qualquer saída ser confirmada seja tentado novamente pelo caminho sem streaming, que percorre novamente todo o fluxo de confiabilidade sobre fallback_models e fallback. Essas tentativas sem streaming abrangem timeout, erro de conexão, 429 e 503, e explicitamente não abrangem 400, falha permanente de autenticação ou erros na saída do modelo. Além disso, uma entrada de fallback pode transferir o trabalho para outra faixa de preço, portanto defina um orçamento para ela primeiro. Para uma comparação mais ampla das rotas de gateway, consulte o guia da API compatível com OpenAI e as alternativas à OpenRouter.

Trabalho contínuo: perfis de risco, limites e o serviço que o reinicia

A autonomia é por agente, não global. A página de autonomia na v0.8.5 aceita exatamente três níveis — readonly, supervised e full — e rejeita read_only com sublinhado no carregamento da configuração. No supervised padrão, ferramentas de baixo risco são executadas automaticamente, ferramentas de risco médio exibem uma solicitação de aprovação ao operador e ferramentas de alto risco são bloqueadas. As solicitações de aprovação expiram após o approval_timeout_secs do canal, 120 segundos na maioria dos canais, e um timeout conta como uma recusa — portanto, um agente sem supervisão falha de forma segura, em vez de ficar em fila.

Há dois limites no trabalho contínuo. O comportamento de reinicialização não é uniforme entre as plataformas: a unidade de usuário instalada do systemd define Restart=always com RestartSec=3 e nenhuma lista de códigos de saída permitidos, portanto um daemon que falhe rapidamente por causa de uma configuração inválida ficará reiniciando continuamente; o LaunchAgent do macOS define RunAtLoad e KeepAlive; e, no Windows, zeroclaw service install registra uma tarefa do Agendador de Tarefas ONLOGON que inicia o daemon no logon, sem adicionar uma política de reinicialização em caso de falha. O próprio trabalho agendado é declarativo e indexado por alias em [cron.<alias>], separado das próprias opções da seção [scheduler]. Além disso, o mecanismo determinístico de SOP é marcado como experimental pela própria matriz de recursos do projeto — os gatilhos de periféricos e calendário são definidos e correspondidos, mas ainda não são encaminhados para uma fonte ativa — portanto, ainda não projete um fluxo de trabalho sem supervisão com base nele.

Configure e confira a primeira cobrança

A Kunavo não publica uma página de integração específica do ZeroClaw e não testou o cliente em runtime, portanto trate a configuração acima como uma rota baseada no documento-fonte, não como um resultado de compatibilidade. A sequência prática é curta: crie uma chave, faça o complemento mínimo, escreva os quatro cabeçalhos, execute os três comandos de validação na ordem e depois escreva o bloco [cost.rates.*] antes da primeira execução longa, para que o ledger tenha algo a registrar. Comece pelo início rápido para obter a URL base e o formato da chave, consulte a referência de chat-completions para saber qual protocolo o slot custom utiliza e crie uma conta na Kunavo quando estiver pronto para adicionar saldo a uma. Se o seu agente usar o protocolo Anthropic, o documento da URL base da Anthropic cobre a rota do slot anthropic.

Perguntas frequentes

Verificado em 21 de setembro de 2026. Releia diretamente para esta página: a FAQ do zeroclaw.com, o README do repositório, a API do GitHub para o status do repositório e a versão v0.8.5, migration.rs, schema/v1.rs, catalog.rs, compatible.rs, providers/custom.md, security/autonomy.md e ops/service.md na tag v0.8.5 e, no master, a visão de migração V2, providers/overview.md, providers/configuration.md, providers/catalog.md, providers/routing.md, providers/custom.md, architecture/provider-routing-lifecycle.md, ops/cost-tracking.md, getting-started/multi-model-setup.md, philosophy/minimal.md, philosophy/what-this-isnt.md e reference/feature-matrix.md, além do repositório do zerorouter, dos sites de terceiros e de páginas de destino mencionados acima e de um GET não autenticado para /v1/models da Kunavo. Qualquer informação citada do master é documentação da branch de desenvolvimento e pode estar à frente da versão estável. A Kunavo não testou o ZeroClaw em runtime: não foi realizada instalação, nem config list, nem execução de agente; portanto, streaming, chamadas nativas de ferramentas e visão por essa rota não foram verificados aqui. As tarifas de tokens da Kunavo são lidas do catálogo ativo, e todo valor em dólares nesta página é uma aritmética ilustrativa de tokens.