Conecte o Zed ao Claude por meio do gateway

Zed é rápido e seu assistente é realmente útil, mas a forma de configurar um endpoint personalizado do Claude não está onde a maioria das pessoas procura primeiro. O provedor nativo da Anthropic não permite substituir a URL base, então o caminho mais direto para o gateway passa pelo bloco openai_compatible do Zed.

Por que não usar o provedor Anthropic

Zed inclui um provedor nativo da Anthropic, e o impulso natural é apontá-lo para o gateway. O problema é que esse provedor não tem uma configuração api_url, portanto não há um campo compatível que permita redirecioná-lo para fora do host padrão da Anthropic.

Essa única limitação explica por que tantas pessoas ficam sem conseguir avançar. Em vez de tentar contorná-la à força, encaminhe o Claude pelo mecanismo genérico openai_compatible, que disponibiliza a URL base e foi criado justamente para endpoints de terceiros.

Ajuda pensar no provedor nativo como fixo em um único destino e no provedor openai_compatible como a opção configurável. Para um gateway multimodelo, o caminho configurável já é o mais adequado, pois o mesmo bloco pode dar acesso ao Claude e a qualquer outro modelo disponibilizado pelo gateway por meio de uma única api_url. Isso mantém toda a configuração de modelos do editor em um só lugar, em vez de dividi-la entre dois mecanismos de provedor com regras diferentes. Essa decisão orienta o restante da configuração, então vale a pena entendê-la antes de editar qualquer coisa. Depois que você entende que o bloco openai_compatible é o caminho compatível, basta preencher os campos.

Adicione um bloco openai_compatible

Em settings.json, dentro de language_models.openai_compatible, adicione um provedor com nome. Defina sua api_url como o endereço do gateway com /v1 no final; Zed usa /chat/completions abaixo desse caminho, de modo que a interface compatível com OpenAI do gateway responde às solicitações.

O nome escolhido é livre e se torna o rótulo no menu de modelos do Zed. Um único bloco pode disponibilizar vários modelos Claude, cada um declarado na próxima etapa.

O sufixo /v1 é essencial aqui: Zed monta o caminho de chat completions diretamente abaixo do valor fornecido em api_url, então a ausência de /v1 envia as solicitações para o lugar errado, e uma barra no final pode duplicar o caminho. Defina exatamente o host seguido de /v1 para que o roteamento funcione corretamente. Recarregar rapidamente as configurações após a edição confirma que Zed interpretou o bloco sem erros. Se o provedor não aparecer, a primeira coisa a verificar é um erro de sintaxe JSON no bloco.

Declare available_models

Zed não descobre modelos automaticamente em um endpoint personalizado, então liste-os manualmente em available_models. Cada entrada precisa de um name que corresponda ao ID do gateway, um display_name para o menu e um valor max_tokens adequado ao modelo.

Use claude-sonnet-4-5 para assistência de rotina e adicione claude-opus-4-8 como segunda entrada para as tarefas mais difíceis. Como você os lista explicitamente, o menu mostra exatamente o conjunto desejado, sem outros modelos.

O campo name deve corresponder ao ID do gateway caractere por caractere, enquanto display_name é apenas visual e pode ter o texto que você preferir no menu. Um name incorreto costuma ser a causa de um modelo que aparece, mas retorna um erro ao ser usado, então copie o ID diretamente do gateway em vez de digitá-lo de memória. Listar apenas os modelos que você realmente usa mantém o menu curto e torna a escolha óbvia no trabalho diário. Adicionar um modelo depois exige editar apenas uma linha, portanto não é necessário declarar tudo de antemão.

Onde a chave fica

A chave de API não fica em settings.json. Zed a armazena no gerenciador de credenciais do sistema operacional ou a lê de uma variável de ambiente cujo nome corresponde ao provedor, como AIPRIME_API_KEY, mantendo o segredo fora da configuração sincronizada.

Depois de salvar, abra o assistente, escolha seu provedor no menu e informe a chave quando solicitado. A partir daí, Zed usa o gerenciador de credenciais para autenticação, e seu arquivo de configurações permanece sem credenciais.

Essa separação é realmente útil se você sincroniza as configurações do Zed entre máquinas ou as versiona em um repositório de dotfiles: a configuração pode circular livremente porque não contém nenhum segredo, e cada máquina fornece sua própria chave pelo gerenciador de credenciais ou pelo ambiente. É uma abordagem mais organizada do que a de ferramentas que incorporam a chave ao arquivo de configuração. É também por isso que compartilhar uma configuração do Zed com um colega é seguro — ele usa a própria chave, e a sua nunca é compartilhada. O mesmo vale para incluir as configurações em um repositório de dotfiles.

O caminho nativo via ACP

Se você quer especificamente o comportamento nativo da Anthropic em vez da interface compatível com OpenAI, Zed oferece suporte ao Agent Client Protocol com Claude Code. Você executa Claude Code como agente, e Zed se comunica com ele por ACP.

Nessa configuração, Claude Code usa seu próprio ANTHROPIC_BASE_URL apontado para o gateway, então Zed nunca precisa de uma api_url da Anthropic própria. É a forma mais direta de obter o verdadeiro comportamento nativo de Messages dentro do editor.

A contrapartida é que ACP oferece o ciclo completo de agente do Claude Code em vez do assistente integrado mais leve do Zed, proporcionando mais recursos, mas também uma experiência mais pesada. Escolha o caminho openai_compatible para ajuda rápida diretamente no código e o caminho ACP quando quiser um agente completo conduzindo edições em várias etapas de dentro do editor. A maioria das pessoas começa pelo caminho mais leve e só adota ACP quando quer um agente completo no editor. Você pode manter ambos disponíveis e usar o que a tarefa exigir.

// Zed settings.json
{
  "language_models": {
    "openai_compatible": {
      "aiprime": {
        "api_url": "https://aiprimetech.io/v1",
        "available_models": [
          { "name": "claude-sonnet-4-5",
            "display_name": "Claude Sonnet",
            "max_tokens": 200000 }
        ]
      }
    }
  }
}
// Key goes in the keychain / AIPRIME_API_KEY env var, NOT this file.

Perguntas frequentes

AI Prime Tech é um gateway de API independente. Não tem afiliação com a Anthropic, não é endossado por ela e não é seu revendedor. Claude e os nomes dos modelos relacionados são marcas comerciais de seus respectivos proprietários.