Vários agentes e modelos no OpenClaw: roteamento, isolamento e custo

Os vários agentes e os vários modelos do OpenClaw são duas camadas diferentes de um único arquivo de configuração: vários agentes são entradas identificadas por chave em agents.entries, cada uma com seu próprio workspace, diretório de estado e armazenamento de sessões, enquanto vários modelos são valores model por agente dentro dessas entradas. Duas outras camadas ficam ao lado delas — bindings decide qual agente responde, e uma cadeia de fallback decide o que um agente faz quando seu modelo falha. Editar a camada errada é o motivo mais comum para uma alteração parecer não fazer nada.

Executar mais agentes não custa nada em software. A visão geral da documentação do OpenClaw afirma que ele é desenvolvido abertamente pela "OpenClaw Foundation, uma organização independente 501(c)(3)" com "Nenhum plano pago, nenhuma telemetria por padrão além de uma verificação de versão que você pode desativar, nenhum laboratório é proprietário dele", e openclaw.ai acrescenta "Nenhuma assinatura. Nenhum plano hospedado. Nenhum token." O pacote npm openclaw é MIT, com latest em 2026.9.5 ao lado de um canal extended-stable em 2026.7.35 e engines.node de >=24.16.0 <25 || >=26.1.0 (registro do npm, verificado em 21 de setembro de 2026). O que um segundo agente acrescenta à sua conta são tokens.

Vários agentes no OpenClaw: quatro camadas e o sintoma de editar a camada errada

As quatro foram consultadas na própria documentação do OpenClaw em 21 de setembro de 2026: entries e vários agentes, agent bindings e model failover. Dois formatos de tutoriais antigos estão obsoletos: um roster em array agents.list é o formato legado que o Doctor migra, e um marcador default: true em uma entrada foi aposentado — a página de entries afirma claramente que "default foi aposentado" e que operações com vários agentes precisam de um binding ou de um destino explícito. O OpenClaw também usou dois nomes anteriores, portanto qualquer configuração da era Moltbot ou Clawdbot é anterior a este esquema.

Configuração de vários agentes no OpenClaw: configuração mínima com dois agentes e dois modelos

Este fragmento presume que você já tem um bloco models.providers funcional — melhor API para OpenClaw contém a configuração da Kunavo, incluindo api: "anthropic-messages" e a URL base publicada em URL base da Anthropic. O que segue é apenas a camada de agentes e roteamento.

{
  "agents": {
    "defaults": {
      "modelSelectionScope": "session",
      "model": {
        "primary": "kunavo/claude-haiku-4-5",
        "fallbacks": [
          "kunavo/claude-sonnet-5"
        ]
      }
    },
    "entries": {
      "ops": {
        "name": "Ops",
        "workspace": "~/.openclaw/workspace-ops",
        "agentDir": "~/.openclaw/agents/ops/agent",
        "model": "kunavo/claude-haiku-4-5",
        "modelPolicy": {
          "allow": [
            "kunavo/claude-haiku-4-5"
          ]
        }
      },
      "build": {
        "name": "Build",
        "workspace": "~/.openclaw/workspace-build",
        "agentDir": "~/.openclaw/agents/build/agent",
        "model": {
          "primary": "kunavo/claude-opus-5",
          "fallbacks": [
            "kunavo/claude-sonnet-5"
          ]
        },
        "utilityModel": "kunavo/claude-haiku-4-5"
      }
    }
  },
  "bindings": [
    {
      "agentId": "build",
      "match": {
        "channel": "discord",
        "accountId": "build"
      }
    },
    {
      "agentId": "ops",
      "match": {
        "channel": "discord",
        "accountId": "*"
      }
    }
  ]
}

Quatro coisas nesse bloco são essenciais. Cada agente tem seu próprio agentDir, porque a página de vários agentes alerta: "Nunca reutilize agentDir entre agentes — isso causa colisões no estado de autenticação/sessão." O agente ops usa a forma de string de model, que a página de entries define como "um modelo principal estrito por agente, sem fallback de modelo" — portanto uma falha é exibida em vez de mover silenciosamente o trabalho rotineiro para uma faixa mais cara. O agente build usa a forma de objeto com uma lista explícita fallbacks, que é como você habilita um agente; a página de failover acrescenta que um agente pode definir apenas model: { fallbacks: [...] } e continuar herdando o modelo principal compartilhado. E o binding específico fica acima do curinga, porque dentro de uma camada de correspondência "a primeira entrada de bindings correspondente vence."

Os padrões de workspace diferem entre o agente padrão e os demais e vale a pena defini-los explicitamente: o workspace do agente padrão é <stateDir>/workspace, enquanto os outros agentes assumem <stateDir>/workspace-<agentId>. A memória acompanha o workspace, pois o mecanismo integrado do OpenClaw "lembra das coisas escrevendo arquivos Markdown simples no workspace do seu agente" — portanto isolar os workspaces é o que isola a memória. Os modos de permissão de sessão são outro eixo: read-only, guarded, workspace e full, onde "full exige operator.admin. Os outros modos exigem operator.write" (modos de permissão, 21 de setembro de 2026). Um modelo barato em um agente permissivo ainda é um agente permissivo.

O que agentes separados separam — e o que não separam

Este é o limite que as tabelas de preços não mostram. Entradas separadas oferecem arquivos, memória, histórico, política de ferramentas e perfis de autenticação armazenados separados. Elas não, por si só, dão a cada agente sua própria chave de API para um provedor personalizado configurado pelo ambiente — o esquema documentado por agente não tem nenhum campo baseUrl, apiKey ou providers. A ausência na documentação não prova que o código proíba isso, portanto leia como não documentado; se precisar de separação rígida de chaves por tenant, execute Gateways separados. Um limite relacionado se aplica à identidade: o exemplo de divisão de DMs do WhatsApp do OpenClaw observa que "as respostas continuam vindo do mesmo número do WhatsApp — não há identidade de remetente por agente", e que "os chats diretos são recolhidos na chave de sessão principal do agente por padrão, portanto o isolamento verdadeiro exige um agente por pessoa." Essa frase é declarada para o WhatsApp; consulte a página do seu próprio canal antes de generalizá-la.

Um limite de capacidade a observar ao dividir funções: a Kunavo não oferece modelos de conversão de texto em fala, fala em texto ou embeddings, portanto um agente que precise de saída de voz ou de um índice vetorial terá de chamar um provedor externo para essa etapa.

Vários modelos no OpenClaw: estrito, fallback, política e a faixa utility

A seleção de modelos por agente tem quatro controles que vale a pena configurar deliberadamente. model como string é estrito. { primary, fallbacks: [...] } habilita o agente para failover. modelPolicy.allow é uma lista de permissões que "substitui a política padrão desse agente" — aceitando aliases, referências exatas e curingas finais —, que é como você impede que um agente rotineiro chegue a um modelo caro. E utilityModel é um modelo separado, geralmente mais barato, para "tarefas internas curtas, como títulos de sessões e threads gerados", com uma substituição por agente.

A lista documentada de gatilhos é específica. O OpenClaw avança em "falhas de autenticação, limites de taxa e esgotamento do período de espera, erros de provedor sobrecarregado/ocupado, erros de failover com formato de timeout, desativações de cobrança, model_not_found", e em outros erros não reconhecidos enquanto houver candidatos — mas não em erros de estouro de contexto, que permanecem na lógica de compactação e nova tentativa, nem em "cancelamentos explícitos que não têm formato de timeout/failover". Fora de conversas de grupo e canal, isso é visível: essas superfícies publicam um aviso de status no formato Model Fallback: <fallback> (selected <primary>; <reason>) e um aviso correspondente de limpeza, enquanto conversas de grupo e canal "suprimem os avisos visíveis mantendo o mesmo estado de fallback", portanto não conte com vê-lo em uma sala compartilhada. Uma seleção explícita de sessão — /model, o seletor de modelos, session_status(model=...) ou sessions.patch — é estrita: se esse modelo falhar antes de produzir uma resposta, o OpenClaw informa a falha em vez de responder usando um fallback configurado. O --model de um cron job não é um desses casos; a documentação o chama de modelo principal do job, que ainda usa os fallbacks configurados, a menos que o job defina payload.fallbacks: [].

Mais dois mecanismos determinam se sua intenção será preservada. Os parâmetros da solicitação são mesclados em quatro camadas, de agents.defaults.params a agents.entries.*.params, com as camadas posteriores substituindo por chave. E o paralelismo tem um teto calculado: agents.defaults.maxConcurrent assume max(8, available CPU parallelism * 4) por padrão entre sessões, enquanto cada sessão permanece serializada — duas mensagens para um agente não são executadas ao mesmo tempo. Para escolher qual modelo pertence a qual função, Opus vs Sonnet vs Haiku aborda o aspecto de capacidade.

Atribuição de custos por rota, não por agente

Como nenhum comando documentado informa os gastos por agente, atribua-os por rota. A aritmética abaixo é ilustrativa, não uma fatura medida nem um limite máximo. Ela pressupõe um mês de 30 dias, o padrão documentado de heartbeat 30m (1.440 execuções), 300 tokens de saída por heartbeat, nenhum acerto de cache e uma via de conversa principal com 8 milhões de tokens de entrada e 500 mil de saída. Os valores de contexto de ~100 mil e ~2–5 mil por execução são uma ilustração do próprio OpenClaw sobre o que isolatedSession remove, não algo medido aqui; 3.000 é o ponto médio. As tarifas são preços atuais do catálogo da Kunavo por milhão de tokens.

Claude Haiku 4.5 lista $0.70 / $3.50 e Claude Opus 5 lista $3.50 / $17.50 por milhão de tokens de entrada / saída no catálogo atual. A conclusão importante: sob essas premissas, a via agendada domina. Um heartbeat de sessão compartilhada no modelo mais robusto custa aproximadamente $511.56 por mês, contra $4.54 para a mesma cadência com isolatedSession: true no modelo barato. O próprio OpenClaw diz isso — "Heartbeats executam turnos completos do agente. Intervalos menores consomem mais tokens" — e aponta isolatedSession, lightContext, um model mais barato e target: "none" como alavancas.

O truque do heartbeat barato tem um modo de falha documentado, e é por isso que isolatedSession é uma alavanca melhor do que apenas trocar o modelo. Os heartbeats "preservam o modelo de execução existente da sessão compartilhada após a conclusão da execução", portanto um heartbeat que trocou uma sessão para um modelo menor pode deixá-lo ativo para o próximo turno da sessão principal, que então poderá informar estouro de contexto — a mensagem de recuperação do OpenClaw chama isso de vazamento do modelo do heartbeat. O exemplo trabalhado na documentação usa um modelo local com uma janela de 32 mil, portanto o tamanho do risco depende de quanto menor é a janela de contexto do modelo do heartbeat em relação ao que a sessão compartilhada exige. Uma observação sobre o agendamento: o intervalo padrão documentado é 30m, alterado para 1h somente quando o modo de autenticação resolvido é Anthropic OAuth/token; assim, uma rota simples com chave de API mantém 30m, a menos que você defina heartbeat.every manualmente. Verifique seu próprio valor antes de fazer o orçamento.

Duas ressalvas sobre os valores em dólares. O valor do catálogo da Kunavo é um piso de cobrança, não um teto: quando o upstream informa sua cobrança, a fatura é o maior entre o custo do catálogo e o custo do upstream multiplicado pela margem aplicável. Além disso, um provedor personalizado declarado sem um objeto cost por modelo torna a própria leitura do OpenClaw inútil — o padrão é cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, exibindo $0 enquanto o fornecedor cobra normalmente. Declare cost, contextWindow e maxTokens em cada modelo adicionado e faça a conciliação com o livro-caixa do provedor. A recarga mínima da Kunavo é $10 em crédito pré-pago — um mínimo de financiamento, não uma taxa por tarefa nem uma assinatura. Consulte detalhes de cobrança e otimização de custos de IA.

Qual rota de compra se adapta a um Gateway multiagente

Uma observação sobre dialetos, porque o cache é onde está o dinheiro. O bloco da Kunavo no guia relacionado declara api: "anthropic-messages", que o OpenClaw trata como um endpoint Anthropic não direto. Disso seguem duas consequências documentadas. Os cabeçalhos beta implícitos da Anthropic são suprimidos nesses endpoints, portanto recursos como o raciocínio intercalado precisam ser ativados por meio de um headers["anthropic-beta"] explícito, em vez de automaticamente. E o cache precisa ser solicitado: o OpenClaw define cacheRetention: "short" apenas para os provedores diretos anthropic e anthropic-vertex, enquanto "endpoints compatíveis com anthropic-messages personalizados" são compatíveis "quando cacheRetention é definido explicitamente" — portanto defina params.cacheRetention você mesmo, em vez de presumir um padrão (cache de prompts, 21 de setembro de 2026). Uma regra separada abrange o outro dialeto: uma rota openai-completions para um endpoint não nativo envia "nenhuma indicação de cache de prompts". Verifique o uso de cache informado na sua própria rota antes de orçar o contexto recorrente como acertos de cache. O cache de prompts cobre o lado das tarifas.

Verifique se foi aplicado onde você pretendia

openclaw config validate
openclaw gateway restart
openclaw agents list --bindings
openclaw models status --agent ops --json --check
openclaw models list --agent build

A validação da configuração verifica a estrutura, e o reinício do gateway a recarrega; nenhum dos dois comprova que uma solicitação cobrada foi bem-sucedida. openclaw agents list --bindings mostra o roteamento realmente carregado — prefira-o a --tree, que aparece nas páginas de conceitos, mas não na tabela de comandos da CLI. openclaw models status --agent <id> explica o padrão configurado desse agente, e models list --agent <id> mostra seu inventário. Se models set terminar com código diferente de zero para um provedor desconhecido, essa é a camada de modelos: o provedor precisa ser um plugin instalado ou estar declarado em models.providers. Se as mensagens não chegarem a nenhum agente, essa é a camada de roteamento. Se aparecerem execuções duplicadas quando vários agentes compartilharem um canal, o OpenClaw documenta as chaves de proteção contra loops de bots como salvaguarda — a documentação descreve prevenção, não uma causa-raiz; portanto, faça o diagnóstico antes de presumir.

Em seguida, execute uma tarefa limitada por agente e leia a cobrança registrada pela conta do seu provedor. A Kunavo não testou o OpenClaw em tempo de execução, com agente único ou múltiplos agentes: tudo acima foi extraído da documentação publicada do OpenClaw, e uma configuração publicada não é um teste de compatibilidade. Mantenha uma rota funcional disponível enquanto você testa. Comece pela configuração do provedor, compare a fatura operacional completa em preços do OpenClaw e crie uma conta Kunavo quando estiver pronto para financiar uma chave.

Perguntas frequentes

Documentação do OpenClaw, referência da CLI e entrada do registro npm verificadas em 21 de setembro de 2026 na versão 2026.9.5 do pacote; nenhum Gateway, agente, vínculo ou solicitação paga foi executado aqui. As tarifas de tokens da Kunavo foram obtidas do catálogo atual, e todos os valores em dólares nesta página são aritmética ilustrativa de tokens, não uma fatura medida.