Claude Desktop com uma API de terceiros: Configure Third-Party Inference e solução de problemas

Wokey Team · 2026-09-24

Resposta curta: o app desktop do Claude tem exatamente uma forma de usar uma API de terceiros: Developer → Configure Third-Party Inference. Ele não lê ANTHROPIC_BASE_URL nem ~/.claude/settings.json, então uma configuração que funciona no seu terminal não faz nada no app desktop. Este guia passa pelos problemas que as pessoas encontram: menu ausente, configurações que não têm efeito, lista de modelos vazia e recursos que simplesmente não existem no modo de terceiros. Para a configuração inicial completa, veja o guia de configuração do Claude Desktop.

A ordem certa

1. Abra o app desktop e não entre com uma conta da Anthropic.

2. Abra Help → Troubleshooting → Enable Developer Mode.

3. Abra Developer → Configure Third-Party Inference….

4. Em Connection, defina Inference provider como Gateway e depois preencha Gateway credentials:

   Campo	Valor
   Gateway base URL	https://api.wokey.ai (sem /v1)
   Gateway API key	Sua chave de API da Wokey
   Credential kind	Static API key
   Gateway auth scheme	Bearer (a Wokey também aceita x-api-key; mantenha o padrão)

5. Clique em Apply Changes e depois em Save & Restart.

Requisitos do sistema:

• macOS: 14 (Sonoma) ou posterior, em Apple silicon ou Intel.
• Windows: Windows 10 build 19041 ou posterior, em x64 ou Arm64.

O menu Developer não aparece

O menu Developer só aparece depois que o modo de desenvolvedor é ativado: Help → Troubleshooting → Enable Developer Mode. Se esse item também não estiver no menu Help, atualize o app para a versão mais recente; versões antigas não têm as configurações de inferência de terceiros.

A janela de configuração está somente leitura

Se a máquina já tem uma configuração enviada por um administrador, como um perfil MDM da sua empresa, a janela abre somente leitura e você não consegue alterá-la localmente. Fale com seu administrador ou use uma máquina não gerenciada.

Variáveis de ambiente não têm efeito

Esse é o erro mais comum. O app desktop pega as configurações do gateway só da configuração de inferência de terceiros. Ele não lê ANTHROPIC_BASE_URL nem settings.json.

A aba Code do app desktop se comporta do mesmo jeito. Ela roda o mesmo motor do Claude Code que a CLI, mas o endereço do gateway e a credencial vêm direto da configuração do desktop. Configurações de nível de usuário em ~/.claude/settings.json não conseguem sobrescrevê-las.

O contrário também vale: a configuração do desktop não afeta o claude no seu terminal. Configure cada um separadamente; para o terminal, veja o guia de base URL do Claude Code.

A lista de modelos está vazia ou faltam modelos

Sem uma lista de modelos própria, o app requisita GET /v1/models do gateway e mantém apenas modelos cujos IDs são reconhecidos como Claude. Por isso, com a Wokey, a descoberta automática mostra modelos como claude-opus-5 e claude-sonnet-5, e filtra GPT, Grok e outros modelos. Isso é esperado.

Para fixar a lista ou escolher o modelo padrão, digite os IDs completos dos modelos na lista de modelos da janela de configuração (Model list, a chave inferenceModels):

• A primeira entrada é o padrão, e as sessões novas na aba Code também começam nele.
• Quando todas as entradas são IDs completos, o app pula a requisição a /v1/models.
• Se /v1/models falhar e a lista estiver vazia, o seletor fica vazio.

Erros

Gateway was unreachable: o app não consegue alcançar o gateway. Confira se há erro de digitação na Gateway base URL e depois teste no terminal com curl:

curl -X POST https://api.wokey.ai/v1/messages \
  -H "Authorization: Bearer your Wokey API key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

Se o curl funciona e o app não, a causa costuma ser um proxy: o terminal passa por um e o app não, ou o contrário.

401 com code igual a invalid_api_key: a requisição chegou à Wokey, mas a chave está ausente ou errada. A Wokey aceita os dois esquemas de autenticação, então não é preciso mudar essa configuração. Cole a chave de novo.

invalid x-api-key: a requisição foi para a Anthropic, então a configuração de terceiros não está em vigor. Normalmente o Save & Restart não foi clicado, ou depois foi escolhido o login da Anthropic na tela de login. Veja o guia de invalid x-api-key.

Para mais detalhes: exporte um relatório com Help → Troubleshooting → Generate Diagnostic Report. Três arquivos dele são úteis:

• managed-config.txt: a configuração em vigor.
• provider-status.txt: o status da conexão com o gateway.
• deployment-mode.txt: o modo atual.

Os logs ficam em:

• macOS: ~/Library/Logs/Claude-3p/main.log
• Windows: %LOCALAPPDATA%\Claude-3p\Logs\main.log

Recursos indisponíveis no modo de terceiros

Estes dependem de uma conta da Anthropic ou dos serviços em nuvem da Anthropic, então não ficam disponíveis com um gateway. Isso não é um problema de configuração:

• Acesso pelo celular e pela web do claude.ai
• Modo de voz
• Compartilhamento de projetos e plugins
• Claude Design, Claude Security e Claude Tag
• Computer use
• Remote Control e ambientes em nuvem hospedados pela Anthropic

Outros dois ficam desativados por padrão:

• Busca de ferramentas e recursos beta experimentais. O app os desativa para manter compatibilidade com gateways rigorosos. Reative a busca de ferramentas com toolSearchEnabled.
• Sessões remotas via SSH. Estão em beta no modo de terceiros e exigem que um administrador configure uma lista de hosts permitidos.

Voltando para sua conta da Anthropic

Escolha a opção de login da Anthropic na tela de login para voltar ao app desktop padrão do Claude.