Como configurar o OpenClaw com a OmniaKey: Provider e allowlist

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:

{
  "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:

{
  "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

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.

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).

• 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).

• 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).

• 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 lista todos os ids que você pode permitir, e preços mostra a tarifa por token.

O guia de agentes de programação cobre as outras ferramentas. Para a configuração passo a passo, veja os guias Configurar o Hermes Agent, Chave API personalizada no Cline e Configurar o Claude Code.

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
• OpenClaw: Skills e Providers de modelos