OpenClaw

Uma entrada models.providers em ~/.openclaw/openclaw.json — baseUrl https://api.kunavo.com, api "anthropic-messages" — coloca um agente OpenClaw sempre ativo no Claude; cacheRetention é definido ao lado dela, pois um endpoint Anthropic personalizado não recebe marcadores de cache até que isso seja configurado.

// ~/.openclaw/openclaw.json — merge into the file you already have
{
  models: {
    mode: "merge",
    providers: {
      kunavo: {
        baseUrl: "https://api.kunavo.com",   // origin — no /v1 on this wire
        apiKey: "${KUNAVO_API_KEY}",         // from the environment or ~/.openclaw/.env
        api: "anthropic-messages",
        models: [
          {
            id: "claude-sonnet-5",
            name: "Claude Sonnet 5",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1000000,
            contextTokens: 200000,           // optional: compact here, not at 1M
            maxTokens: 32000,
          },
          {
            id: "claude-haiku-4-5",
            name: "Claude Haiku 4.5",
            input: ["text", "image"],
            contextWindow: 200000,
            maxTokens: 16000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "kunavo/claude-sonnet-5" },
      models: {
        // Required for caching: a custom Anthropic endpoint gets no cache
        // markers from OpenClaw until cacheRetention is set explicitly.
        "kunavo/claude-sonnet-5": { params: { cacheRetention: "short" } },
        "kunavo/claude-haiku-4-5": { params: { cacheRetention: "short" } },
      },
    },
  },
}

Passo a passo

1. Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
2. Forneça a chave ao Gateway: adicione KUNAVO_API_KEY=sk-kn-... a ~/.openclaw/.env ou exporte-a no ambiente em que o Gateway é iniciado. Ao carregar a configuração, o valor de ${KUNAVO_API_KEY} no bloco é substituído pelo valor definido ali.
3. Mescle o bloco em ~/.openclaw/openclaw.json, preservando os provedores, agentes e canais que você já tem. O arquivo é JSON5, então os comentários podem permanecer.
4. Execute openclaw config validate. O OpenClaw se recusa a iniciar quando o arquivo contém uma configuração que não reconhece, então é melhor encontrar um erro de digitação aqui do que na próxima reinicialização.
5. Execute openclaw models list --provider kunavo e confira se os dois IDs aparecem na lista. Se um Gateway em execução ainda não tiver aplicado a alteração, execute openclaw gateway restart.
6. Abra uma nova sessão com /new — uma sessão existente mantém o modelo que já estava usando —, envie duas mensagens e depois consulte /usage tokens: o segundo turno deve mostrar cacheRead.

Verificado em Referência de provedores personalizados do OpenClaw em 5 de outubro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em OpenClaw.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

A interface compatível com OpenAI

A mesma chave dá acesso a todas as outras famílias de modelos por meio de /v1/chat/completions. Cadastre-a como uma segunda entrada de provedor para manter as duas interfaces separadas e referencie os modelos como kunavo-openai/<id>:

// ~/.openclaw/openclaw.json — a second entry, beside "kunavo"
{
  models: {
    providers: {
      "kunavo-openai": {
        baseUrl: "https://api.kunavo.com/v1",   // this wire keeps /v1
        apiKey: "${KUNAVO_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gpt-6-sol",
            name: "GPT-6 Sol",
            reasoning: true,
            input: ["text"],
            contextWindow: 1050000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

// then: /model kunavo-openai/gpt-6-sol

Há três diferenças em relação ao bloco no início. A URL base mantém /v1, seguindo o formato usado nos próprios exemplos de provedores personalizados do OpenClaw. api é openai-completions — também é o valor que o OpenClaw assume quando um provedor personalizado informa um baseUrl, mas não informa um api. E, na prática, maxTokens deixa de ser opcional: quando o limite de saída de um modelo é desconhecido, o OpenClaw não envia nenhum limite nesta interface, e a Kunavo encerra uma resposta do Claude em 4.096 tokens.

Os IDs do Claude também funcionam aqui; esta é a interface a usar se você quiser uma única entrada para tudo. Para eles, duas coisas mudam: os níveis de raciocínio não são encaminhados para o Claude em chat completions, e os pontos de quebra do cache são inseridos pela Kunavo, não pelo OpenClaw.

Cache de prompts em cada interface

Na interface Anthropic, o próprio OpenClaw insere os pontos de quebra do cache, mas, em um endpoint personalizado, só quando cacheRetention está definido. A referência de cache de prompts do OpenClaw é específica sobre isso: o valor padrão short é predefinido somente para os provedores anthropic e anthropic-vertex, e todas as outras rotas da família Anthropic precisam de um valor explícito. O endpoint /v1/messages da Kunavo encaminha o corpo da solicitação como foi enviado e não adiciona nenhum ponto de quebra; portanto, sem essas linhas na configuração, nada será armazenado em cache.

short solicita a entrada de cinco minutos e long, a de uma hora. A Kunavo encaminha qualquer um dos marcadores e cobra a gravação à mesma taxa. Vale a pena confirmar no seu próprio uso se uma entrada de uma hora ainda estará disponível quando chegar o próximo heartbeat, antes de planejar uma frequência com base nisso: um turno que mostra cacheRead manteve o cache; um que mostra cacheWrite novamente não o manteve. /usage tokens e /status exibem os dois contadores.

Na interface compatível com OpenAI, ocorre o contrário. O OpenClaw não envia dicas de cache a um endpoint proxy, e a Kunavo insere por conta própria os pontos de quebra para modelos Claude — no prompt de sistema, nas definições de ferramentas e no fim da conversa — quando o prompt é longo o bastante para ser armazenado em cache. Não é necessário configurar nada, e o fornecedor armazena implicitamente em cache os modelos GPT.

Não importa qual lado insere os pontos de quebra, a cobrança é a mesma. Em Claude Sonnet 5 uma leitura de cache custa $0.14 por 1M tokens, contra $1.40 para entrada nova, e uma gravação de cache custa $1.75 — o adicional cobrado pelo Claude sobre a entrada, aplicado à mesma taxa quando a entrada solicita uma duração de uma hora. Uma entrada dura cinco minutos e cada leitura renova esse prazo; por isso, o valor pago por um agente depende menos do modelo do que de a próxima solicitação chegar dentro desse intervalo. As taxas de cache de todos os modelos estão na página de cache de prompts.

O OpenClaw pode exibir o mesmo cálculo localmente. O resumo /usage cost e a linha de custo em /status precisam de um objeto cost em cada linha de modelo; sem ele, mostram zero, embora a Kunavo continue cobrando normalmente. Estas linhas são geradas com base no catálogo atualizado:

// merge into the rows of models.providers.kunavo.models — USD per 1M tokens
{ id: "claude-sonnet-5", cost: { input: 1.4, output: 7, cacheRead: 0.14, cacheWrite: 1.75 } },
{ id: "claude-haiku-4-5", cost: { input: 0.7, output: 3.5, cacheRead: 0.07, cacheWrite: 0.875 } },
{ id: "claude-opus-5-5", cost: { input: 2.8, output: 14, cacheRead: 0.14, cacheWrite: 3.5 } },
{ id: "claude-fable-5", cost: { input: 7, output: 35, cacheRead: 0.7, cacheWrite: 8.75 } },

Quanto custa por dia manter um agente sempre ativo

Um agente do OpenClaw gera cobranças mesmo quando ninguém está interagindo com ele, por causa do heartbeat: uma execução agendada do agente que, por padrão, ocorre a cada 30 minutos, ou seja, 48 por dia. Se não houver outra configuração, ela ocorre na sessão principal e reenvia a conversa — a documentação de referência do OpenClaw estima cerca de 100.000 tokens para uma execução desse tipo, e alguns milhares quando ela é isolada. Trinta minutos é mais do que a janela de cache de cinco minutos; por isso, cada execução cobra novamente o prompt inteiro: pela tarifa de entrada ou, se houver um ponto de interrupção, pela tarifa de gravação mais alta. A tabela calcula o preço de um dia sem atividade usando a tarifa de entrada e 5.000 tokens para a execução isolada:

O bloco abaixo mostra o cenário mais econômico da tabela: heartbeats no Haiku, em uma sessão isolada, sem os arquivos de inicialização do workspace e somente durante o período em que você está acordado. Todas as configurações apresentadas vêm da documentação de referência do heartbeat do OpenClaw. Um intervalo every maior é a outra opção, e "0m" desativa a execução recorrente.

// ~/.openclaw/openclaw.json — what decides the cost of an idle day
{
  agents: {
    defaults: {
      utilityModel: "kunavo/claude-haiku-4-5",   // titles and other short internal tasks
      heartbeat: {
        every: "30m",                            // the default with an API key
        model: "kunavo/claude-haiku-4-5",        // wake-ups on the cheapest tier
        isolatedSession: true,                   // a fresh session, not the whole conversation
        lightContext: true,                      // skip the workspace bootstrap files
        activeHours: { start: "08:00", end: "24:00" },
      },
    },
  },
}

As horas em que o agente está realmente trabalhando são a outra metade da conta, e é aí que o cache faz diferença. Faça 100 solicitações consecutivas, cada uma reenviando um contexto de 100.000 tokens, acrescentando 2.000 tokens novos e retornando 800 tokens de saída. Em Claude Sonnet 5, isso custa cerca de $2.31 enquanto o contexto é lido do cache, e cerca de $14.84 quando o contexto é cobrado como entrada nova em cada solicitação. Mesmo trabalho, mesmo modelo: a diferença é se os pontos de interrupção estão presentes e se as solicitações são feitas com menos de cinco minutos de intervalo.

Para ter uma referência baseada em medições, não em suposições: entre as contas da Kunavo que mantêm um agente sempre ativo, um dia ativo mediano custou $12.67, e um dia no percentil 90 custou cerca de $163. Esses valores são os custos diários faturados até 5 de outubro de 2026, às tarifas vigentes em cada dia. Como se trata de um grupo pequeno, considere-os como a amplitude da faixa, não como uma previsão para o seu agente.

Quando o saldo acaba

O Kunavo é pré-pago: cada chamada é paga com o saldo da carteira, e um agente que trabalha enquanto você dorme esvazia esse saldo enquanto você dorme. Uma solicitação que a carteira não consegue cobrir é recusada com HTTP 402 e o código insufficient_balance, em qualquer um dos protocolos, sem cobrança. A recusa ocorre antes de o saldo chegar a zero: cada solicitação primeiro reserva seu custo máximo, que inclui o prompt e a maior resposta permitida. Assim, quanto maior o limite de saída solicitado pelo agente, mais cedo suas chamadas começam a ser recusadas. O erro informa o valor que faltou, em balance_usd e needed_usd.

O OpenClaw determina o significado de um 402 a partir da mensagem. De acordo com as regras do OpenClaw 2026.9.8, a recusa por saldo insuficiente é uma falha de cobrança, e a documentação de referência sobre failover descreve o que acontece em seguida: a credencial é desativada por dez minutos, a execução passa para o próximo modelo em agents.defaults.model.fallbacks e a recarga não encerra esse período — assim, após uma recarga, o agente pode continuar sem usar kunavo/… até o período terminar. A recusa devido ao limite mensal de uma chave é interpretada de outra forma. A mensagem menciona um limite que será redefinido e, segundo as mesmas regras, isso é tratado como um limite de taxa: o OpenClaw tenta novamente e, em seguida, coloca a credencial em espera por 30 segundos inicialmente, podendo chegar a no máximo cinco minutos. openclaw models status mostra as credenciais desativadas e quando elas serão reativadas.

Duas configurações evitam que um agente sem supervisão chegue a essa situação, e cada uma tem uma função diferente:

• Recarga automática, em Cobrança. Salve um cartão uma vez e defina três valores: o saldo abaixo do qual será feita uma recarga, o valor a adicionar a cada recarga e um limite mensal. A carteira será recarregada em poucos segundos após uma chamada que faça o saldo ficar abaixo do limite. Uma solicitação que chegar enquanto o saldo da carteira ainda estiver insuficiente aguardará a cobrança e, em seguida, será atendida em vez de recusada. Um 402 ainda será retornado quando não for possível fazer a cobrança — por exemplo, se o cartão for recusado ou se o limite mensal tiver sido atingido — ou quando uma solicitação reservar mais do que a carteira terá após a recarga. É necessário usar um cartão ou o Link — Alipay, WeChat Pay, Pix e outros métodos de pagamento locais não podem ser cobrados automaticamente.
• Um limite mensal para a chave, em Chaves de API. Dê ao agente uma chave própria e defina o valor máximo que essa chave poderá gastar em um mês-calendário. Acima desse valor, as chamadas dessa chave serão recusadas com um 402 e nenhuma cobrança será feita, enquanto suas outras chaves continuarão funcionando. Esse é o limite necessário para conter um loop descontrolado, algo que a carteira não pode oferecer, pois todas as chaves usam a mesma carteira.

Defina o limite de recarga acima do valor reservado por uma única solicitação e escolha o valor da recarga com base em um dia de uso do agente, não no mínimo: a menor recarga é de $10, e o custo mediano de um dia com o agente sempre ativo, mencionado acima, é de $12.67. Os limites da recarga automática estão na página de cobrança, e o corpo completo do erro está na página de erros.

Guias relacionados

• Melhor API para o OpenClaw — como escolher um provedor e um modelo para cada tipo de tarefa.
• Preços do OpenClaw — o custo operacional completo: software, hospedagem, modelos e ferramentas.
• OpenClaw com vários agentes e modelos — como direcionar cada agente ao próprio modelo e atribuir custos por rota.
• Hermes vs. OpenClaw — e a mesma configuração para o outro agente, na página do Hermes Agent.