Você já encontrou este erro ao rodar o modelo Claude no OpenClaw?
400 ... ValidationException: Operation not allowed
O chat funciona perfeitamente, mas no momento em que uma chamada de ferramenta (tool use) é acionada, tudo trava — esse é quase um rito de passagem para todo usuário do OpenClaw ao integrar a Claude API.
A causa raiz é apenas uma: você usou o formato de API errado.
O OpenClaw oferece duas opções de formato para conectar à Claude: openai-completions e anthropic-messages. Ao usar o modo de compatibilidade OpenAI, o chat simples funciona, mas ao entrar em chamadas de ferramentas de múltiplas voltas (tool_calls → tool_result → tool loop), a solicitação é rejeitada. Somente ao mudar para o formato anthropic-messages as chamadas de ferramentas funcionam de forma estável.
Este artigo, baseado em configurações validadas em testes reais, ensinará passo a passo como usar a APIYI apiyi.com como seu serviço proxy de API para concluir a configuração correta da Claude API no OpenClaw em 5 etapas.
Análise do problema central na conexão do OpenClaw com a Claude API
Antes de apresentar a solução, vamos entender por que o erro ocorre.
O que é o OpenClaw
O OpenClaw é um dos frameworks de Agente de IA de código aberto mais populares de 2025-2026, desenvolvido por Peter Steinberger (fundador da PSPDFKit). Suas principais características incluem:
- Suporte multiplataforma: Signal, Telegram, Discord, WhatsApp, iMessage
- Integração de múltiplos modelos: Claude, GPT, DeepSeek e outros modelos principais
- Capacidade de chamada de ferramentas: Mais de 50 integrações integradas, suportando execução de código, busca na web, casa inteligente, etc.
- Execução local: As configurações e o histórico de conversas são armazenados localmente, protegendo a privacidade.
| Característica Principal do OpenClaw | Descrição |
|---|---|
| Desenvolvedor | Peter Steinberger (Fundador da PSPDFKit) |
| Licença | Código aberto e gratuito |
| Plataformas Suportadas | Signal / Telegram / Discord / WhatsApp / iMessage |
| Modelos Suportados | Claude / GPT / DeepSeek, etc. |
| Formatos de API | openai-completions / anthropic-messages |
| Integração de Ferramentas | 50+ integrações nativas |
| Armazenamento de Dados | Armazenamento local, privacidade controlada |
Diferenças fundamentais entre os dois formatos de API
O OpenClaw suporta duas formas de acessar a Claude API:
| Dimensão de Comparação | openai-completions | anthropic-messages |
|---|---|---|
| Caminho do Endpoint | /v1/chat/completions |
/v1/messages |
| Chat de Texto Simples | ✅ Normal | ✅ Normal |
| Chamada de Ferramenta (tool use) | ❌ Erro 400 | ✅ Estável e disponível |
| Loop de Ferramentas Multivoltas | ❌ Erro | ✅ Estável e disponível |
| Cache de Comandos (Prompt Caching) | ❌ Não suportado | ✅ Suportado |
| Pensamento Estendido (Extended Thinking) | ⚠️ Incompleto | ✅ Suporte completo |
| Requisitos de Header | Sem requisitos especiais | Requer anthropic-version |
🎯 Sugestão Técnica: Ao conectar o OpenClaw à Claude API, você deve usar o formato
anthropic-messagespara utilizar as funções de chamada de ferramentas de forma estável. Recomendamos usar a APIYI apiyi.com como provedor de serviço proxy, pois a plataforma oferece suporte total ao formato nativo Messages API da Anthropic.
Por que a chamada de ferramenta falha no formato openai-completions
Quando o OpenClaw usa o formato openai-completions para invocar o Claude, acontece o seguinte:
- Conversão de Formato: O OpenClaw envia os campos
tool_callsefunctionno formato OpenAI. - Incompatibilidade de Protocolo: O Claude usa nativamente os formatos
tool_useetool_result. - Conflito Multivoltas: O loop de ferramentas (tool loop) precisa manter a consistência do
tool_use_identre várias solicitações; essas informações são facilmente perdidas durante a conversão de formato. - Rejeição de Validação: O serviço proxy ou a API original detecta a incompatibilidade de formato e retorna
400 ValidationException.
Configuração completa do OpenClaw com a API do Claude: 5 passos simples
A configuração abaixo foi validada em testes reais, utilizando a APIYI (apiyi.com) como serviço proxy de API para o Claude.
Passo 1: Configurar o Provider (Configuração Principal)
No arquivo openclaw.json, adicione a seguinte configuração em models.providers:
{
"models": {
"providers": {
"apiyi": {
"baseUrl": "https://api.apiyi.com",
"apiKey": "sk-YOUR_APIYI_KEY",
"api": "anthropic-messages",
"headers": {
"anthropic-version": "2023-06-01",
"anthropic-beta": ""
},
"models": [
{
"id": "claude-opus-4-6",
"name": "claude-opus-4-6",
"reasoning": false,
"input": ["text"],
"contextWindow": 200000,
"maxTokens": 16384
},
{
"id": "claude-sonnet-4-6-thinking",
"name": "claude-sonnet-4-6-thinking",
"reasoning": false,
"input": ["text"],
"contextWindow": 200000,
"maxTokens": 16384
}
]
}
}
}
}
Detalhes importantes da configuração:
| Item de Configuração | Valor Correto | Descrição |
|---|---|---|
baseUrl |
https://api.apiyi.com |
Não inclua /v1, caso contrário, o caminho será montado como .../v1/v1/messages |
api |
"anthropic-messages" |
Deve ser este, não use openai-completions |
anthropic-version |
"2023-06-01" |
Obrigatório, caso contrário a requisição será negada |
anthropic-beta |
"" (string vazia) |
Desativa obrigatoriamente as funções beta para evitar erro 400 |
reasoning |
false |
Desativa o campo thinking para evitar o erro ValidationException |
streaming |
Sugerido desativar | Em cenários de proxy, desativar o streaming é mais estável |
💡 Dica Importante: Nunca escreva o
baseUrlcomohttps://api.apiyi.com/v1. Ao usar o formatoanthropic-messages, o OpenClaw concatena automaticamente/v1/messages. Se o seu baseUrl já contiver/v1, o caminho final da requisição será/v1/v1/messages, resultando em erro 404.
Passo 2: Registrar os modelos na lista de permissões (allowlist)
Adicione os modelos em agents.defaults.models. Caso contrário, o OpenClaw informará que o modelo "não está registrado/permitido" e fará um fallback silencioso para outro modelo — essa é uma armadilha bem comum e difícil de notar.
{
"agents": {
"defaults": {
"models": {
"apiyi/claude-opus-4-6": { "streaming": false },
"apiyi/claude-sonnet-4-6-thinking": { "streaming": false }
}
}
}
}
Passo 3: Configurar o Agent
Usando o agent de tarefas (tasks) como exemplo:
{
"agents": {
"list": [
{
"id": "tasks",
"model": "apiyi/claude-opus-4-6",
"tools": {
"profile": "coding",
"alsoAllow": ["group:web"]
}
}
]
}
}
Passo 4: Lidar com Sessions existentes (Muito fácil de esquecer)
Este é o passo mais ignorado. Mesmo que você altere a configuração, as sessões de canal (sessions) existentes podem manter o modelProvider/model antigo salvo, fazendo com que pareça que a nova configuração não surtiu efeito.
Existem duas formas de resolver:
Método A: Fazer Patch do modelo na Session atual
openclaw gateway call sessions.patch \
--params '{"key":"agent:tasks:discord:channel:<CHANNEL_ID>","model":"apiyi/claude-opus-4-6"}'
Método B: Resetar a Session (limpa o histórico de conversa)
openclaw gateway call sessions.reset \
--params '{"key":"agent:tasks:discord:channel:<CHANNEL_ID>","reason":"reset"}'
🚀 Início Rápido: Após criar sua conta na plataforma APIYI (apiyi.com), você poderá obter sua chave API. Substitua
sk-YOUR_APIYI_KEYna configuração acima pela sua chave real para concluir a integração do OpenClaw com a API do Claude.
Passo 5: Verificar se a configuração está funcionando
Execute os comandos abaixo para confirmar se tudo está correto:
# Verificar status do modelo
openclaw models status --agent tasks
# Enviar mensagem de teste
openclaw agent --agent tasks --message "Responda apenas pong" --json
No JSON de retorno, verifique se meta.agentMeta.provider e meta.agentMeta.model correspondem ao esperado:
{
"meta": {
"agentMeta": {
"provider": "apiyi",
"model": "claude-opus-4-6"
}
}
}
Se o provider ou o model não forem os valores que você configurou, o problema de sobreposição da session ainda não foi resolvido. Volte ao Passo 4.
Erros comuns e solução de problemas na integração do OpenClaw com a API do Claude
Durante a configuração, você pode se deparar com os seguintes problemas:
Erro 1: 400 ValidationException: Operation not allowed
400 ... ValidationException: Operation not allowed
Causa: A requisição contém os campos thinking ou output_config. Alguns modelos Claude 4.6 não suportam esses parâmetros em certas rotas de proxy.
Solução:
- Garanta que a configuração do modelo tenha
reasoning: false. - Garanta que o cabeçalho tenha
anthropic-beta: ""(string vazia). - Verifique se a versão do OpenClaw está enviando campos relacionados a thinking.
Erro 2: 404 Not Found
Causa: Erro no baseUrl, geralmente por incluir o /v1 extra.
Solução: Altere o baseUrl para https://api.apiyi.com (sem o /v1).
Erro 3: Fallback silencioso do modelo
Sintoma: O estilo da resposta muda subitamente ou o modelo afirma não ser o Claude.
Causa: O modelo não foi adicionado à allowlist, e o OpenClaw alternou automaticamente para o modelo padrão.
Solução: Registre todos os modelos que pretende usar em agents.defaults.models.
Erro 4: Falha no loop de chamada de ferramenta (tool call)
Sintoma: A primeira chamada de ferramenta funciona, mas ocorre um erro ao retornar o tool_result subsequente.
Causa: Uso do formato openai-completions, onde o tool_use_id do loop de ferramentas se perde na conversão de formato.
Solução: Mude para o formato api: "anthropic-messages".
Por que escolher a APIYI como o serviço proxy de API do Claude para o OpenClaw
Ao escolher um provedor de serviço proxy, existem vários fatores cruciais a serem considerados.
Comparativo de Opções para Proxy de API do Claude
| Critério de Avaliação | Conexão Direta Anthropic | APIYI (apiyi.com) | Outros Proxies |
|---|---|---|---|
| Formato Anthropic Messages | ✅ Suporte Nativo | ✅ Suporte Completo | ⚠️ Suporte Parcial |
| Chamada de Ferramentas (tool use) | ✅ Suportado | ✅ Suporte Estável | ⚠️ Pode ser instável |
| Cache de Comandos (Prompt Caching) | ✅ Suportado | ✅ Suportado | ❌ A maioria não suporta |
| Conexão Direta de Rede | ❌ Requer Proxy/VPN | ✅ Conexão Direta Disponível | ✅ Alguns permitem |
| Interface Unificada Multimodelo | ❌ Apenas Claude | ✅ Claude + GPT + outros | ✅ Suporte Parcial |
| Cobrança por Uso | ✅ Preço Oficial | ✅ Cobrança Flexível | ⚠️ Preços não transparentes |
| Validação Real com OpenClaw | – | ✅ Verificado | ⚠️ Não verificado |
💰 Otimização de Custos: A APIYI (apiyi.com) suporta o formato nativo da API de Messages da Anthropic. Isso significa que, ao usá-la no OpenClaw, suas requisições podem aproveitar os descontos do Claude Prompt Caching — o custo dos Tokens de entrada que atingem o cache é de apenas 10% do preço base.
3 Vantagens Principais do Serviço Proxy APIYI
1. Suporte Completo ao Formato Nativo da Anthropic
A plataforma APIYI não faz apenas um encaminhamento simples para o formato OpenAI; ela oferece suporte total à API de Messages da Anthropic (endpoint /v1/messages), incluindo:
- Parâmetros de controle de cache
cache_control - Formatos nativos de chamada de ferramenta
tool_use/tool_result - Cabeçalho de requisição
anthropic-version - Pensamento Estendido (Extended Thinking)
2. Validado em Testes Reais com OpenClaw
Todas as configurações deste artigo foram validadas em testes reais na plataforma APIYI, garantindo que:
- Ciclos de chamadas de ferramentas em múltiplas rodadas funcionem de forma estável
- O
tool_use_idseja transmitido corretamente entre múltiplas requisições - Não haja perda de contexto em cenários de conversas longas
3. Gerenciamento Unificado de Múltiplos Modelos
Com apenas uma chave API, você pode realizar a invocação do modelo Claude, GPT, DeepSeek e muitos outros. No OpenClaw, é possível configurar modelos diferentes para diferentes Agents, alternando com flexibilidade.
Dicas de Configuração Avançada para o Claude API no OpenClaw
Após dominar a configuração básica, as dicas a seguir podem te ajudar a otimizar ainda mais o uso.
Dica 1: Configurar Diferentes Modelos para Diferentes Agents
{
"agents": {
"list": [
{
"id": "tasks",
"model": "apiyi/claude-opus-4-6",
"tools": { "profile": "coding" }
},
{
"id": "chat",
"model": "apiyi/claude-sonnet-4-6-thinking",
"tools": { "profile": "default" }
}
]
}
}
- Agent de tarefas (tasks): Usa o Opus 4.6 para lidar com tarefas complexas e geração de código.
- Agent de chat: Usa o Sonnet 4.6 para conversas cotidianas, com custo reduzido.
Dica 2: Aproveitar o Prompt Caching para Reduzir Custos
Como a APIYI suporta o formato nativo da Anthropic, o comando de sistema (system prompt) do OpenClaw pode ser armazenado em cache automaticamente. Para agents com comandos de sistema longos, o custo de entrada após o acerto no cache é de apenas 10%.
Dica 3: Observações de Segurança
- Nunca exponha sua chave API em canais públicos do Discord.
- As chaves no arquivo
openclaw.jsonsão armazenadas em texto simples; certifique-se de que as permissões do arquivo estejam corretas. - Se a chave for exposta, realize a rotação imediatamente no painel da APIYI (apiyi.com).
FAQ: Integração do OpenClaw com a API do Claude
Q1: É obrigatório usar um serviço proxy para usar o Claude no OpenClaw?
Não é obrigatório, mas para usuários que enfrentam restrições de conexão, é fortemente recomendado. A conexão direta com a API da Anthropic exige um ambiente de rede internacional, enquanto através do serviço proxy de API da APIYI (apiyi.com), você pode fazer a chamada do modelo diretamente, aproveitando todo o suporte à API de Messages da Anthropic.
Q2: Por que mudei a configuração, mas o comportamento do OpenClaw não mudou?
Este é o problema mais comum. Em 99% dos casos, o motivo é que a sessão atual (session) armazenou a configuração antiga no cache. Use os comandos sessions.patch ou sessions.reset para atualizar a sessão ou teste em um novo canal. Consulte o passo 4 para os comandos específicos.
Q3: A função "thinking" do Claude 4.6 funciona no OpenClaw?
Atualmente, em algumas rotas de proxy, os campos de pensamento (thinking / output_config) podem disparar um erro 400 ValidationException. Recomendamos definir reasoning: false e acompanhar o status de suporte à função "thinking" através das atualizações na plataforma APIYI (apiyi.com).
Q4: Posso usar uma única chave API da APIYI para vários agentes do OpenClaw ao mesmo tempo?
Sim. A chave API da APIYI não limita o número de agentes simultâneos. Você pode configurar a mesma chave para diferentes agentes, como tasks, chat ou coder, e a cobrança será feita com base no consumo real de tokens.
Q5: O atraso (delay) na chamada de ferramentas do Claude no OpenClaw é normal?
A chamada de ferramentas envolve múltiplas rodadas de requisições à API (enviar solicitação → obter tool_use → executar ferramenta → retornar tool_result → obter resposta final), por isso é naturalmente mais lenta que um chat comum. Através da infraestrutura de baixa latência da APIYI (apiyi.com), é possível manter o atraso de cada invocação do modelo dentro de limites aceitáveis.
Resumo: 3 pontos-chave para conectar o OpenClaw à API do Claude
Com base nos testes de configuração deste artigo, lembre-se destes pontos essenciais ao conectar o OpenClaw ao Claude:
- Use obrigatoriamente o formato anthropic-messages: Configure
api: "anthropic-messages". Este é o pré-requisito para que a chamada de ferramentas funcione de forma estável. O formatoopenai-completionscostuma gerar erros 400 em chamadas de ferramentas de múltiplas rodadas. - 3 armadilhas comuns:
baseUrlincluindo/v1por engano, não desativaranthropic-betaereasoning, e lidar com o cache de sessões existentes. - Escolha o provedor de proxy certo: A APIYI (apiyi.com) oferece suporte completo à API nativa de Messages da Anthropic. Validamos em testes com o OpenClaw que tanto a chamada de ferramentas quanto o Prompt Caching funcionam de forma estável.
Recomendamos utilizar a APIYI (apiyi.com) para configurar rapidamente o acesso do OpenClaw à API do Claude. Em apenas 5 minutos, você terá suas chamadas de ferramentas funcionando perfeitamente.
Referências
-
Documentação Oficial do OpenClaw – Model Providers: Instruções de configuração de provedores de modelos
- Link:
docs.openclaw.ai/concepts/model-providers
- Link:
-
Documentação Oficial da Anthropic – Messages API: Formato de chamada nativa da API Claude
- Link:
platform.claude.com/docs/en/api/messages
- Link:
-
Documentação Oficial da Anthropic – Compatibilidade com SDK da OpenAI: Limitações de funcionalidades do modo de compatibilidade
- Link:
platform.claude.com/docs/en/api/openai-sdk
- Link:
-
Repositório GitHub do OpenClaw: Código aberto e discussões de Issues
- Link:
github.com/openclaw/openclaw
- Link:
📝 Autor: Equipe APIYI | Time Técnico APIYI, especializada em integração de APIs de Modelos de Linguagem Grandes e compartilhamento de conhecimento técnico. Acesse apiyi.com para mais tutoriais técnicos e chaves API.
