# Como configurar o OpenClaw com a OmniaKey: Provider e allowlist > Adicione a OmniaKey como Provider compatível com OpenAI no OpenClaw. Configure openclaw.json, a allowlist de modelos, o doctor e o erro model not allowed. - Canonical HTML: https://omniakey.com/pt-BR/blog/openclaw-setup - Markdown: https://omniakey.com/pt-BR/blog/openclaw-setup.md - Published: 2026-05-19 (updated 2026-10-30) - Author: Kiki, COO at OmniaKey - Language: pt-BR - Category: Guide - Reading time: 5 min - All posts: https://omniakey.com/blog/llms.txt --- Atualizado em 30 de outubro de 2026: quatro erros comuns de configuração estão abaixo, cada um com o sintoma, a causa e a solução da documentação do OpenClaw. Quem pesquisa **configurar OpenClaw API** precisa separar duas etapas: definir o Provider e autorizar os modelos. O OpenClaw fornece o loop do agente e as ferramentas; o Provider fornece o modelo que responde. ## Adicionar a OmniaKey como Provider A configuração do OpenClaw com a OmniaKey fica em `~/.openclaw/openclaw.json`. Adicione a OmniaKey em `models.providers`: ```json { "models": { "mode": "merge", "providers": { "omniakey": { "baseUrl": "https://api.omniakey.com/v1", "apiKey": "your-omniakey-api-key", "api": "openai-completions", "models": [ { "id": "claude-opus-4-8" }, { "id": "gpt-5.5" }, { "id": "gemini-3.1-pro-preview" }, { "id": "grok-4.5" } ] } } } } ``` `mode: merge` adiciona o Provider sem substituir a configuração existente. Use sua chave real, mas não a commite nem a compartilhe. Um único Provider compatível com OpenAI cobre quatro famílias de modelos: a OmniaKey procura o modelo pelo ID, então `claude-opus-4-8`, `gpt-5.5`, `gemini-3.1-pro-preview` e `grok-4.5` passam todos pela mesma entrada. ## A etapa que muita gente esquece: allowlist do modelo Definir o Provider não basta. O OpenClaw também exige que o modelo esteja na allowlist. No mesmo arquivo, adicione `agents` no mesmo nível de `models`: ```json { "agents": { "defaults": { "models": ["omniakey/claude-opus-4-8", "omniakey/gpt-5.5", "omniakey/gemini-3.1-pro-preview", "omniakey/grok-4.5"], "model": "omniakey/claude-opus-4-8" } } } ``` O corpo da requisição leva o model ID; `provider/model-id` é a referência interna do OpenClaw. As duas entradas são necessárias. Sem a allowlist, o erro pode ser `model not allowed` mesmo com a chave correta. ## Verificar ```bash openclaw doctor ``` O `doctor` verifica arquivo, Provider, formato da chave, conexão ao vivo e acesso ao modelo. Depois você pode definir `omniakey/gpt-5.5` em `agents.defaults`. > Não edite manualmente `~/.openclaw/agents/main/agent/models.json`; ele é recriado a partir do `openclaw.json`. ## Erros comuns de configuração - `Model override "provider/model" is not allowed by agents.defaults.modelPolicy.allow.` A referência escolhida não está numa lista `agents.defaults.modelPolicy.allow` não vazia, e é essa lista que o OpenClaw confere em `/model`, nas trocas dentro da sessão e em `--model`. Inclua a referência exata ou um curinga de Provider como `omniakey/*`, esvazie a lista, ou escolha um modelo de `/model list` ([FAQ de modelos do OpenClaw](https://docs.openclaw.ai/help/faq-models#why-do-i-see-model-is-not-allowed-and-then-no-reply)). - `model_not_found` ou um 404, embora uma chamada direta com o mesmo model ID funcione. Uma entrada personalizada só é resolvida quando `baseUrl` termina em `/v1`, `api` é `"openai-completions"` e o catálogo mantém o ID sem prefixo enquanto você o seleciona com o prefixo do Provider. Confira esses três pontos, selecione o modelo uma vez com o prefixo e repita a mesma requisição ([solução de problemas de backend local](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers#local-openai-compatible-backend-passes-direct-checks-but-agent-runs-fail)). - Um 403 seco com "Your request was blocked" no corpo da resposta. Esse texto costuma vir de uma camada de segurança na frente do endpoint — CDN, WAF, regra anti-bot ou proxy reverso — e não do `openclaw.json`; o `openclaw logs --follow` mostra se vários modelos do mesmo Provider falham do mesmo jeito. Corrija primeiro o lado do Provider com uma regra de permissão que cubra só o caminho que o OpenClaw chama, e mantenha a proteção no resto do site ([solução de problemas do 403 na origem](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers#upstream-403-blocked-responses)). - `messages[...].content: invalid type: sequence, expected a string` em toda execução do agente. O backend recusa as partes de conteúdo estruturadas no estilo OpenAI. Defina `compat.requiresStringContent: true` na entrada desse modelo e repita a mesma requisição. ## Por que usar o OpenClaw com a OmniaKey Uma chave e um saldo para Claude, GPT, Gemini e Grok, com cobrança por token. O ID autorizado é o que executa; não há troca silenciosa por um modelo “equivalente”. O [catálogo de modelos](https://omniakey.com/pt-BR/models) lista todos os ids que você pode permitir, e [preços](https://omniakey.com/pt-BR/pricing) mostra a tarifa por token. - **OpenAI-compatible**: - **Anthropic-native**: - **Gemini-native**: O [guia de agentes de programação](https://docs.omniakey.com/pt-BR/coding) cobre as outras ferramentas. Para a configuração passo a passo, veja os guias [Configurar o Hermes Agent](https://omniakey.com/pt-BR/blog/hermes-setup), [Chave API personalizada no Cline](https://omniakey.com/pt-BR/blog/cline-custom-api-key) e [Configurar o Claude Code](https://omniakey.com/pt-BR/blog/claude-code-setup). ## Perguntas frequentes ### Onde fica o bloco de Provider da OmniaKey? Em `~/.openclaw/openclaw.json`, dentro de `models.providers`. Mantenha `"mode": "merge"` para o bloco ser somado aos Providers que você já tem, em vez de substituí-los. ### Por que o OpenClaw diz que um modelo não é permitido? O Provider está definido, mas a referência do modelo não está na allowlist do OpenClaw, então a execução falha mesmo com a chave correta. Inclua a referência completa `omniakey/model-id` e rode `openclaw doctor`. ### Uma chave da OmniaKey roda Claude, GPT, Gemini e Grok no OpenClaw? Sim. Uma entrada de Provider com `api: "openai-completions"` alcança as quatro famílias, e o model ID da requisição decide qual delas executa. ### Como conferir se o OpenClaw alcança a OmniaKey? `openclaw doctor` confere o arquivo de configuração, o Provider, o formato da chave, uma conexão ao vivo e o acesso ao modelo. Depois, `openclaw models list` mostra os modelos da OmniaKey que você autorizou. ### Preciso editar o \~/.openclaw/agents/main/agent/models.json? Não. Esse arquivo é recriado a partir do `openclaw.json`, então faça as mudanças de Provider e allowlist no `openclaw.json`. ## Fontes verificadas - [OpenClaw: Perguntas frequentes sobre modelos e autenticação](https://docs.openclaw.ai/help/faq-models) - [OpenClaw: Skills e Providers de modelos](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers)