Multi-model routing no OpenClaw: como usar vários modelos via OpenRouter

Você configurou o OpenClaw com Claude Opus 4.6, está funcionando bem — mas cada heartbeat (verificação automática periódica), cada sub-agent (tarefa rodando em segundo plano), cada classificação trivial queima tokens (as unidades de texto que o modelo processa — cada palavra gasta alguns) do Opus a $15 por milhão. É como pagar Uber Black para ir na padaria.

O problema não é usar o Opus. É usar o Opus para tudo, sem distinção.

TL;DR

Tarefa	Modelo	Custo (input/M)	Por que
Planejamento, arquitetura	`anthropic/claude-opus-4-6`	$15.00	Raciocínio complexo
Codificação, sub-agents	`openrouter/moonshotai/kimi-k2.5`	$0.45	Top em coding benchmarks, 262k contexto
Heartbeat, classificação	`openrouter/stepfun/step-3.5-flash:free`	$0.00	Modelo otimizado que usa só parte do cérebro por vez, grátis

O que é multi-model routing

Em vez de um único modelo para tudo, o OpenClaw deixa você atribuir modelos diferentes por função. Há três pontos de configuração independentes: o modelo principal (o que você conversa diretamente), o modelo do heartbeat (checagens periódicas automáticas), e o modelo dos sub-agents (tarefas paralelas em segundo plano).

sua conversa
    │
    ├── modelo principal ──→ anthropic/claude-opus-4-6
    │
    ├── heartbeat ──────────→ openrouter/stepfun/step-3.5-flash:free
    │
    └── sub-agents ─────────→ openrouter/moonshotai/kimi-k2.5

O OpenRouter funciona como uma porta de entrada única para mais de 200 modelos de provedores diferentes. Você configura uma chave de API (a ponte que conecta o OpenClaw ao modelo de IA) do OpenRouter e usa qualquer modelo com o prefixo openrouter/provider/modelo. Não precisa criar conta em cada provedor separadamente.

Modelos gratuitos usam o sufixo :free. Modelos pagos não têm sufixo.

Configurar o OpenRouter

Crie uma conta em openrouter.ai e gere uma API key em Keys. A key começa com sk-or-.

Para autenticar via onboard, abra o terminal (a tela preta onde você digita comandos) e rode:

# Configura a chave do OpenRouter no OpenClaw
openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"

Ou adicione diretamente no openclaw.json (um arquivo de configuração — como uma lista de instruções que o OpenClaw lê):

{
  env: {
    // Substitua pelo valor real da sua chave
    OPENROUTER_API_KEY: "sk-or-v1-...",
  },
}

A partir daí, qualquer modelo no catálogo do OpenRouter fica disponível com o formato openrouter/provider/modelo. O provider é o prefixo do provedor no OpenRouter (ex: anthropic, moonshotai, stepfun), seguido do nome do modelo.

Modelo principal: o que realmente precisa de Opus

O modelo principal é onde você interage diretamente. É onde você descreve um problema, pede uma arquitetura, revisa um plano. Aqui a qualidade do raciocínio importa, e Opus justifica o preço.

{
  defaults: {
    // Modelo padrão para suas conversas diretas
    model: "anthropic/claude-opus-4-6",
    // fallback: plano B — se o principal falhar, usa outro
    fallbacks: [
      "openrouter/anthropic/claude-sonnet-4-6",
    ],
  },
}

O campo fallbacks define a cadeia de fallback. Se o Opus estiver com latência alta ou indisponível, o OpenClaw tenta o próximo da lista automaticamente. Não precisa de nenhuma intervenção manual.

Guarde o Opus para quando você está de fato no loop: revisando código, planejando uma sprint, depurando algo difícil. Para o resto, os outros dois tiers resolvem com fração do custo.

Heartbeat: o modelo grátis que funciona

O heartbeat (verificação automática periódica) faz rondas periódicas — lê o HEARTBEAT.md, verifica condições, decide se precisa avisar você. A tarefa é simples por design: checklist curto, sem geração criativa, sem raciocínio encadeado.

O step-3.5-flash:free é suficiente para isso. É um modelo otimizado que usa só parte do cérebro por vez, com contexto de 256 mil tokens (palavras), limite de 50 requisições por minuto, e custo zero — tanto na entrada quanto na saída.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",         // roda a cada 30 minutos
        model: "openrouter/stepfun/step-3.5-flash:free",
        target: "last",
        activeHours: {
          start: "08:00",     // começa às 8h
          end: "22:00",       // para às 22h
          timezone: "America/Sao_Paulo",
        },
      },
    },
  },
}

A matemática é direta. 48 heartbeats por dia com Opus a $15/M custam alguma coisa, dependendo do tamanho do HEARTBEAT.md e do contexto carregado. Com o Step Flash, custam zero. O comportamento é idêntico para essa tarefa.

Se precisar de mais detalhes sobre como o heartbeat funciona internamente, veja o post dedicado: Heartbeat no OpenClaw: monitoramento automático com custo zero.

Sub-agents: Kimi K2.5 para codificar

Sub-agents são tarefas que o OpenClaw delega para rodar em paralelo — pesquisa, geração de código, análise de logs, revisão de arquivos. Eles não precisam de raciocínio tão profundo quanto o agente principal, mas precisam ser bons em código.

O Kimi K2.5 da Moonshot AI tem janela de contexto de 262 mil tokens e é competitivo nos benchmarks de resolução de código. O preço é $0.45 por milhão de tokens de entrada — 33x mais barato que Opus.

{
  subagents: {
    // Modelo padrão para todas as tarefas em segundo plano
    model: "openrouter/moonshotai/kimi-k2.5",
    fallbacks: [
      "openrouter/anthropic/claude-sonnet-4-6",
    ],
  },
}

Para criar um sub-agent especificando o modelo diretamente:

# Cria um sub-agent do tipo "researcher" com o Kimi K2.5
openclaw subagents spawn researcher "Analise os endpoints da API" --model openrouter/moonshotai/kimi-k2.5

O subagents.model na configuração define o padrão para todos os sub-agents. O --model no comando sobrescreve para aquele sub-agent específico, sem alterar o padrão global.

Config completo

Tudo junto em um único openclaw.json:

{
  // Chave do OpenRouter (acessa todos os modelos abaixo)
  env: {
    OPENROUTER_API_KEY: "sk-or-v1-...",
  },

  // Modelo principal: Opus para conversas diretas
  defaults: {
    model: "anthropic/claude-opus-4-6",
    fallbacks: [
      "openrouter/anthropic/claude-sonnet-4-6",
    ],
  },

  // Sub-agents: Kimi K2.5 para codificação e pesquisa
  subagents: {
    model: "openrouter/moonshotai/kimi-k2.5",
    fallbacks: [
      "openrouter/anthropic/claude-sonnet-4-6",
    ],
  },

  // Aliases para troca rápida com /model (atalhos de nome)
  modelAliases: {
    opus: "anthropic/claude-opus-4-6",
    kimi: "openrouter/moonshotai/kimi-k2.5",
    flash: "openrouter/stepfun/step-3.5-flash:free",
  },

  agents: {
    defaults: {
      // Heartbeat: modelo gratuito para checagens periódicas
      heartbeat: {
        every: "30m",
        model: "openrouter/stepfun/step-3.5-flash:free",
        target: "last",
        activeHours: {
          start: "08:00",
          end: "22:00",
          timezone: "America/Sao_Paulo",
        },
      },
    },
  },
}

Com os aliases configurados, você pode trocar de modelo no meio de uma sessão (a conversa ativa entre você e o agente):

/model kimi

Isso troca o modelo da sessão atual sem alterar o padrão global.

Quanto você economiza

Não dá para dar um número exato sem saber seu uso. A forma mais útil de pensar é pela fórmula:

custo com routing = (heartbeats × $0) + (sub-agents × $0.45/M) + (conversa principal × $15/M)

custo sem routing = (heartbeats × $15/M) + (sub-agents × $15/M) + (conversa principal × $15/M)

A economia vem de dois lugares: heartbeats a zero e sub-agents a 3% do preço do Opus. Para quem usa sub-agents com frequência, essa segunda parte tende a ser a maior diferença.

Perfil	Uso estimado	Economia aproximada
Leve	5-10 sub-agents/dia, heartbeat 1h	80-90% vs tudo-Opus
Médio	20-30 sub-agents/dia, heartbeat 30m	90-93% vs tudo-Opus
Intenso	50+ sub-agents/dia, heartbeat 15m	93-95% vs tudo-Opus

Os percentuais assumem sub-agents com contexto médio de 50k tokens e heartbeats com HEARTBEAT.md de ~200 tokens. Seu caso pode variar.

Troubleshooting

model_not_found

O prefixo openrouter/ é obrigatório para modelos via OpenRouter. moonshotai/kimi-k2.5 sem o prefixo vai buscar nos provedores diretos e não encontrar.

errado: moonshotai/kimi-k2.5
certo:  openrouter/moonshotai/kimi-k2.5

429 rate_limited no modelo gratuito

O Step Flash tem rate limit (limite de uso — quantas vezes por minuto você pode chamar o modelo) de 50 RPM no tier gratuito. Se o heartbeat estiver configurado com intervalo muito curto e você tiver muitos agentes rodando ao mesmo tempo, pode atingir o limite. Adicione um fallback pago:

heartbeat: {
  model: "openrouter/stepfun/step-3.5-flash:free",
  fallbacks: [
    // modelo pago como plano B se o gratuito travar
    "openrouter/anthropic/claude-haiku-4-5",
  ],
}

Sub-agent herdando o modelo errado

Se um sub-agent está usando o modelo principal em vez do subagents.model, verifique se o subagents.model está configurado no nível certo. A config de defaults.model é o fallback global — subagents.model sobrescreve especificamente para sub-agents e precisa estar no bloco subagents, não dentro de defaults.

insufficient_credits no OpenRouter

O saldo do OpenRouter está zerado. Modelos gratuitos continuam funcionando, mas modelos pagos (incluindo Kimi K2.5) param. Recarregue em openrouter.ai/credits.

Kimi não está sendo usado nos sub-agents

Rode um sub-agent com --verbose para ver qual modelo está sendo selecionado:

# --verbose mostra detalhes da execução, incluindo qual modelo foi usado
openclaw subagents spawn test "ping" --verbose

A saída mostra o modelo resolvido antes de executar a tarefa.