Configuração da API personalizada OpenClaw: Execute o GLM, Kimi e DeepSeek sem o custo das grandes empresas

O OpenClaw foi desenvolvido para ser agnóstico quanto ao provedor, o que é seu superpoder silencioso. Ele suporta os nomes usuais como OpenAI e Anthropic, mas também permite que você conecte qualquer API compatível com OpenAI como um provedor personalizado (OpenClaw docs, 2026). Essa simples escolha de design é o que permite manter o agente de sua preferência enquanto o executa em modelos de pesos abertos muito mais baratos, do tipo que custa uma fração dos preços de modelos de fronteira por token. O problema é que a configuração possui uma etapa que quase todos ignoram, e errá-la gera uma mensagem de erro que leva as pessoas para o caminho errado. Este guia percorre a configuração completa de uma API personalizada no OpenClaw da maneira correta: como funciona nos bastidores, a configuração exata para copiar, o detalhe da lista de permissões e como verificar a conexão. Reserve cerca de cinco minutos.

Por que fazer uma configuração de API personalizada no OpenClaw?

A razão honesta é o custo. Ferramentas de agentes como o OpenClaw reenviam o contexto acumulado a cada etapa de raciocínio, então eles consomem de 10 a 100 vezes mais tokens do que uma janela de chat para a mesma tarefa (LeanOps, 2026). Esse multiplicador é o motivo pelo qual as contas dos agentes sobem tão rápido, com usuários intensivos em modelos de fronteira atingindo cerca de USD13 por desenvolvedor por dia ativo (CloudZero, 2026). Uma configuração de API personalizada no OpenClaw ataca a fatura onde ela realmente pesa: o preço por token. Aponte o agente para um modelo de pesos abertos em vez de um de fronteira e o custo unitário cai drasticamente, muitas vezes em 70% ou mais em trabalhos rotineiros, enquanto a diferença de qualidade na codificação do dia a dia permanece pequena. Você mantém o fluxo de trabalho do OpenClaw que já conhece e simplesmente altera o que responde às solicitações. Há uma segunda razão que importa para equipes fora das regiões atendidas diretamente por um determinado fornecedor. Um provedor personalizado oferece uma maneira estável e compatível de executar o agente sem depender do faturamento, cronograma de lançamento ou disponibilidade regional de uma única empresa.

Como funciona a configuração de API personalizada no OpenClaw: As duas etapas que as pessoas perdem

Antes de colar a configuração, entenda o modelo que o OpenClaw usa, pois ele explica o único erro que todos cometem. Um provedor personalizado é definido em dois lugares, e ambos são obrigatórios. Primeiro, você descreve o provedor em si na seção models.providers: sua URL base, chave de API, protocolo de comunicação (openai-completions para qualquer endpoint compatível com OpenAI) e a lista de modelos que ele serve. Segundo, e esta é a parte que as pessoas perdem, você deve adicionar o modelo exato à lista de permissões em agents.defaults.models, usando o identificador totalmente qualificado nome-do-provedor/nome-do-modelo (OpenClaw docs, 2026). Definir um provedor não torna seus modelos utilizáveis automaticamente. O OpenClaw rejeitará qualquer coisa que não esteja na lista de permissões. Isso é proposital. A lista de permissões é o que permite definir um grande catálogo de provedores e modelos, mas expor apenas os específicos que você realmente deseja que o agente utilize. Uma vez que você entende que provedores e lista de permissões são camadas separadas, o restante da configuração da API personalizada do OpenClaw é mecânico.

Configuração de API personalizada no OpenClaw, passo a passo

O exemplo abaixo usa o Atlas Cloud como provedor, porque ele expõe um endpoint compatível com OpenAI que oferece os principais modelos de pesos abertos por trás de uma única chave. Isso mantém a configuração curta e permite que você troque de modelo posteriormente sem registrar nada novo. Os mesmos passos se aplicam a qualquer provedor compatível; apenas a URL base e a chave mudam.

Passo 1: Obtenha seu endpoint e chave de API

Ao final desta etapa, você terá duas strings: uma URL base e uma chave.

1. Crie uma conta com seu provedor e abra a seção de chave de API.
2. Gere uma chave com escopo para uso em codificação. No Atlas Cloud, você seleciona Coding Plan como o tipo de chave, o que a vincula à cota de codificação baseada em créditos, em vez do pagamento conforme o uso geral.
3. Anote a URL base. Para clientes compatíveis com OpenAI como o OpenClaw, o Atlas Cloud usa https:​//api.atlascloud.ai/v1 (o sufixo /v1 é importante aqui).

Passo 2: Execute o assistente de integração, a maneira mais rápida de configurar a API personalizada do OpenClaw

Ao final desta etapa, a conexão estará ativa, da maneira fácil. Em um terminal, inicie o assistente guiado:

BashCopy
1openclaw onboard

Em seguida, siga as instruções: escolha Yes, selecione QuickStart e selecione Custom Provider. O assistente solicitará a URL base da API (https:​//api.atlascloud.ai/v1), a chave de API que você copiou e o ID do modelo. Certifique-se de escolher o protocolo OpenAI-compatible quando solicitado. Quando exibir Verification successful, o endpoint está funcionando. Finalize dando ao endpoint um ID e um nome amigável. A vantagem oculta do assistente: ele escreve tanto a definição do provedor quanto a entrada na lista de permissões do modelo para você e reinicia o gateway, para que você ignore completamente o modo de falha mais comum.

Passo 3: Ou edite o arquivo de configuração diretamente

Ao final desta etapa, você entenderá o que o assistente realmente escreveu, o que importa quando você quiser adicionar mais modelos posteriormente. A configuração fica em ~/.openclaw/openclaw.json (OpenClaw docs, 2026). Defina o provedor:

JSONCopy
1{
2  "models": {
3    "mode": "merge",
4    "providers": {
5      "atlascloud": {
6        "baseUrl": "https://api.atlascloud.ai/v1",
7        "apiKey": "your-atlas-api-key",
8        "api": "openai-completions",
9        "models": [
10          { "id": "zai-org/glm-5.1", "name": "glm-5.1", "contextWindow": 200000 }
11        ]
12      }
13    }
14  }
15}

O "mode": "merge" mantém seus provedores existentes intactos em vez de substituí-los. Para provedores personalizados, campos como reasoning, cost e maxTokens são opcionais e recorrem a padrões sensatos, então você não precisa preencher tudo para começar.

Passo 4: Adicione o modelo à lista de permissões

Ao final desta etapa, o OpenClaw permitirá que você use o modelo. Esta é a etapa que as pessoas pulam. Adicione o identificador totalmente qualificado à lista de permissões:

JSONCopy
1{
2  "agents": {
3    "defaults": {
4      "models": {
5        "atlascloud/zai-org/glm-5.1": { "alias": "glm" }
6      }
7    }
8  }
9}

A chave é o nome do seu provedor seguido pelo ID do modelo exatamente como você o definiu. O alias é apenas um atalho que você pode digitar em vez do caminho completo. Sem este bloco, o provedor existe, mas cada solicitação é rejeitada.

Passo 5: Verifique sua configuração de API personalizada no OpenClaw

Ao final desta etapa, você saberá que funciona. Inicie o OpenClaw, selecione seu modelo (ou seu alias) e dê a ele uma tarefa trivial, como explicar um arquivo. Uma resposta normal significa que as solicitações estão fluindo para o seu endpoint. Se você vir "model not allowed", revise o Passo 4; a chave da lista de permissões quase certamente não corresponde exatamente aos nomes do provedor e do modelo. Se você receber um erro de autenticação, a chave está errada ou tem um espaço extra. Se não conseguir conectar, verifique novamente a URL base e o sufixo /v1.

Escolhendo um modelo para sua configuração de API personalizada no OpenClaw

Escolher o modelo é onde a economia é decidida. O padrão inteligente é usar um modelo aberto, forte e barato como padrão para o trabalho diário e manter um mais caro na reserva para o raciocínio mais difícil. A capacidade é real: no SWE-Bench Pro, os principais modelos abertos pontuam na faixa dos 70 altos contra cerca de 91 para os principais modelos de fronteira (Codersera, 2026), uma lacuna significativa nos problemas mais difíceis, mas pequena para trabalho rotineiro de recursos e refatorações. Em um gateway baseado em crédito, cada modelo carrega um multiplicador que mapeia o uso de tokens para créditos, o que torna o custo relativo fácil de comparar:

Fonte: Regras de crédito do Atlas Cloud Coding Plan. Custo em crédito = tokens de entrada × multiplicador de entrada + tokens de saída × multiplicador de saída. Um padrão sensato: execute GLM-5.1 ou Kimi K2.6 para codificação interativa, mude para o DeepSeek V4 Flash para trabalhos de alto volume ou em segundo plano e só recorra a um modelo de fronteira na tarefa ocasional que um modelo aberto não consegue resolver. Como tudo fica atrás de um único provedor, trocar é uma mudança de uma linha no alias que você chama.

Um endpoint para OpenClaw, Claude Code e Codex

O endpoint que alimenta sua configuração do OpenClaw não se limita ao OpenClaw. A maioria dos desenvolvedores executa mais de um agente, e apontar cada um para um fornecedor diferente significa lidar com chaves separadas, painéis separados e faturas separadas. Consolidar em um único endpoint compatível com OpenAI reduz tudo isso a um pool de crédito e um lugar para alterar modelos. Como o Atlas Cloud expõe a mesma URL base em várias ferramentas, a configuração do OpenClaw acima tem equivalentes diretos em outros lugares. O Claude Code lê seu backend em ~/.claude/settings.json usando ANTHROPIC_BASE_URL definido como https:​//api.atlascloud.ai (nota: não use /v1 especificamente para o Claude Code). O Codex usa ~/.codex/config.toml com base_url apontando para https:​//api.atlascloud.ai/v1. Cursor, OpenCode e clientes estilo Copilot usam o mesmo endpoint /v1. Uma chave, um orçamento, todas as ferramentas. Essa consolidação também corrige o controle de gastos. Um plano que renova uma franquia diária fixa de créditos à meia-noite coloca um teto estrutural em um loop de agente descontrolado, enquanto os pacotes de pagamento conforme o uso absorvem o pico ocasional. Os planos do Atlas Cloud começam em USD10 por mês, os pacotes de pagamento conforme o uso carregam um desconto de 41% e as atualizações no meio do ciclo são proporcionais, então uma mudança de nível pode custar apenas a diferença, em vez de um novo plano.

Erros comuns na configuração de API personalizada do OpenClaw

A maioria das configurações falhas remonta a uma pequena lista de erros, e quase todos eles residem na configuração, e não em algo mais profundo. Esquecer a lista de permissões. O erro mais comum. Definir o provedor é apenas metade do trabalho. Se você vir "model not allowed", o modelo está faltando em agents.defaults.models ou a chave não corresponde (haimaker, 2026). Chave da lista de permissões incompatível. A chave da lista de permissões deve ser nome-do-provedor/nome-do-modelo usando as strings exatas que você definiu. Um erro de digitação em qualquer uma das partes produz a mesma rejeição que omiti-la completamente. Caminho de URL base incorreto. Ferramentas compatíveis com OpenAI como o OpenClaw esperam o caminho /v1. Deixá-lo de fora, ou adicioná-lo onde uma determinada ferramenta não o deseja, causa erros de conexão. Sobrescrever em vez de mesclar. Se você editar a configuração manualmente sem "mode": "merge", você pode apagar seus outros provedores. Mantenha o modo de mesclagem, a menos que pretenda substituir tudo.

Perguntas frequentes: Configuração de API personalizada no OpenClaw

É difícil fazer uma configuração de API personalizada no OpenClaw?

Não. O caminho mais rápido é o assistente openclaw onboard, que escreve a definição do provedor e a lista de permissões do modelo para você e leva cerca de cinco minutos. O caminho manual envolve duas pequenas edições em JSON. O único obstáculo conceitual é lembrar que definir um provedor e colocar um modelo na lista de permissões são etapas separadas.

Qual é o erro de configuração de API personalizada do OpenClaw mais comum?

A rejeição "model not allowed", que quase sempre significa que o modelo está faltando na lista de permissões em agents.defaults.models, ou a chave nome-do-provedor/nome-do-modelo tem um erro de digitação. Falhar em adicionar à lista de permissões é a causa número um deste erro (haimaker, 2026), que é exatamente por isso que o assistente de integração cuida disso automaticamente.

Qual modelo devo escolher para minha configuração de API personalizada no OpenClaw?

Para codificação interativa, um modelo aberto geral forte como o GLM-5.1 ou Kimi K2.6 é um bom padrão. Para trabalho de alto volume ou em segundo plano, um modelo mais barato como o DeepSeek V4 Flash faz sentido. Mantenha um modelo de fronteira de prontidão apenas para tarefas que um modelo aberto realmente não consegue resolver.

Quanto uma API personalizada pode realmente me economizar?

Depende do modelo, mas a diferença é grande. O DeepSeek V4 Flash custa perto de USD0.14 por milhão de tokens de entrada, contra vários dólares para modelos de fronteira (Codersera, 2026), então direcionar o trabalho rotineiro para um modelo aberto geralmente reduz a fatura por token em 70% ou mais sem mudar a forma como você trabalha.

Posso voltar ao meu provedor original mais tarde?

Sim. Provedores personalizados são aditivos quando você mantém "mode": "merge", então seus provedores originais permanecem definidos. Alternar é apenas uma questão de selecionar um modelo ou alias diferente no OpenClaw, e você pode remover um bloco de provedor a qualquer momento.

Conclusão

Uma configuração de API personalizada no OpenClaw é uma das mudanças de cinco minutos de maior alavancagem que um desenvolvedor pode fazer em 2026. O agente permanece o mesmo, mas o backend e a fatura não. Defina o provedor, adicione o modelo à lista de permissões, aponte-o para uma opção de pesos abertos e você manterá o fluxo de trabalho do OpenClaw que conhece enquanto paga uma fração dos preços de fronteira. Se você quiser sob uma única chave e um orçamento que também cubra o Claude Code e o Codex, você pode configurá-lo através do console do Atlas Cloud Coding Plan e trocar de modelo sempre que a tarefa mudar.