Nota do autor: distinga as três rotas de Agent do Zed, depois use os dois tipos de Provider personalizado — OpenAI-compatible e Anthropic-compatible — para conectar a APIYI ao Zed, e entenda Base URL, ID do modelo, preço e pontos-chave de solução de problemas.
Você usa o painel Agent ou o Inline Assistant no Zed para escrever código, quer trocar para outro modelo, mas descobre que a página de configurações tem várias entradas — LLM Providers, External Agents, threads de terminal — e não sabe onde colocar a Key. O caso mais comum é ter preenchido um gateway de terceiros e ficar recebendo 404 ou falha de autenticação. Este artigo apresenta a abordagem completa para conectar gateways de modelos de terceiros usando Providers personalizados do Zed (OpenAI-compatible / Anthropic-compatible), usando a APIYI como exemplo para percorrer todo o fluxo de configuração.
Este não é mais um guia rápido de “copie e cole a configuração e pronto”. O artigo primeiro esclarece os limites de acesso a modelos de cada uma das três rotas de IA do Zed, e depois apresenta duas rotas que você pode seguir. Quando adicionar /v1 à Base URL e quando não adicionar — o detalhe que mais causa erros — será explicado em separado.
Valor central: depois de ler este artigo, você consegue identificar em qual camada de configuração precisa mexer, e em 5 minutos fazer o Agent do Zed usar modelos como claude-opus-5-5, claude-sonnet-5-5. Se algo der errado, também vai saber qual item verificar primeiro.
Pontos principais para trocar o modelo no Zed: primeiro diferencie os três caminhos de Agent
Zed é um editor colaborativo multiusuário de alto desempenho criado pela equipe original do Atom / Tree-sitter. Em 2026-11-13, o repositório zed-industries/zed no GitHub tinha cerca de 94,884 estrelas (observação da GitHub API). A página oficial de releases mostra que a versão estável de 2026-11-11 é 1.28.1, e o Preview do mesmo dia é 1.29.1. macOS, Linux e Windows podem ser baixados diretamente; a versão Web ainda não está oficialmente disponível.
Antes de trocar o modelo no Zed, é preciso entender uma coisa: a documentação oficial divide os recursos de IA em três caminhos, e cada caminho tem uma forma diferente de conectar modelos e de autenticar. Se você preencher no lugar errado, a configuração não terá efeito, e a chave também não será lida por outro caminho.
| Caminho | De onde vem o modelo | Quem gerencia a autenticação | Uso típico |
|---|---|---|---|
| Zed Agent | LLM Providers (hospedado pela Zed, chave do fornecedor, assinatura, gateway, modelo local) | O próprio Zed; a chave fica no chaveiro do sistema | Painel do Agent, Inline Assistant, ferramentas internas / profiles / skills / MCP |
| External Agents (ACP) | O próprio Agent externo escolhe o modelo | O próprio Agent externo gerencia | Executar Claude Agent, Codex, OpenCode, Copilot, Cursor etc. em threads do Zed |
| Terminal Threads | Definido pelo CLI / TUI que você executa | Configuração do próprio CLI | Executar vários Agent CLIs diretamente em threads de terminal |
Limites de integração entre Zed Agent e External Agent
“Trocar o modelo do Zed Agent” significa configurar LLM Providers, ou seja, a camada de API Access; esse é o fio condutor deste artigo. Os fornecedores de primeira classe suportados oficialmente são Anthropic, OpenAI, Google AI, Mistral, DeepSeek, xAI e OpenCode; além disso, há dois tipos de endpoint personalizado: Anthropic-compatible e OpenAI-compatible. É por esses dois tipos de endpoint personalizado que os gateways de terceiros se conectam.
Se você só quer usar Claude Agent ou OpenCode no painel, isso pertence aos External Agents e passa pelo Agent Client Protocol (ACP). Nesse caso, a thread é gerenciada pelo Zed, enquanto runtime, autenticação e escolha de modelo geralmente ficam a cargo do Agent externo. A chave que você preenche em LLM Providers não é compartilhada automaticamente com ele; o Claude Agent precisa executar /login na própria thread. Agents externos podem ser instalados abrindo o registro na paleta de comandos com zed: acp registry. De acordo com a documentação oficial, o Zed não cobra separadamente pelos External Agents; a cobrança fica com o provedor do Agent.
Pontos-chave da configuração de provedor personalizado no Zed
A diferença entre os dois tipos de endpoint personalizado está basicamente no formato da requisição. O modo OpenAI-compatible usa Chat Completions; o Anthropic-compatible usa a Messages API (/v1/messages). Essa diferença define diretamente como a Base URL deve ser escrita e também se é possível usar a cobrança do Prompt Cache.
| Item de configuração | OpenAI-compatible | Anthropic-compatible |
|---|---|---|
| Formato da requisição | /v1/chat/completions |
/v1/messages |
| api_url na APIYI | https://api.apiyi.com/v1 |
https://api.apiyi.com (sem /v1) |
| Campo de modelo | available_models[].name + max_tokens |
available_models |
| Opções de capacidade | Padrão: tools=true, images=false, chat_completions=true | Configurável: capabilities.prompt_caching |
| Cobrança de cache | A documentação da APIYI diz que não tem efeito | Funciona no formato Messages nativo |
| Cenários indicados | Usar um único provedor para vários modelos | Quando o foco é Claude, contexto longo ou necessidade de cache |
Por que uma Base URL leva /v1 e a outra não
Segundo o FAQ de Base URL da APIYI (verificado na documentação em 2026-11-13), clientes compatíveis com OpenAI concatenam /chat/completions diretamente depois do api_url, então o api_url precisa chegar até o nível /v1. Já os clientes do lado Anthropic concatenam /v1/messages por conta própria, então só se pode informar o domínio raiz. Se você escrever https://api.apiyi.com/v1, a requisição final vira /v1/v1/messages e retorna 404 na hora.
Há ainda dois pontos de atenção. A API Key do Zed fica no keychain do sistema e não é gravada no settings.json; se a variável de ambiente correspondente não estiver vazia, ela tem prioridade sobre o keychain. Além disso, modelos que só suportam a interface Responses precisam definir capabilities.chat_completions como false; caso contrário, o Zed faz a chamada via Chat Completions.
Integração rápida do Zed com a APIYI
Você pode escolher apenas uma das duas rotas abaixo, ou configurar as duas e alternar no seletor de modelos. Antes de começar, prepare a chave.
🚀 Início rápido: após fazer login, crie um token na página de tokens da APIYI
api.apiyi.com/token. Recomendo criar um token separado para o Zed, para facilitar a consulta de uso e permitir revogá-lo a qualquer momento. A documentação de início rápido docs.apiyi.com/getting-started também oferece skill.md / llms.txt, o que ajuda o Agent a ler as instruções da plataforma.
Rota A: integrar o Zed via endpoint OpenAI-compatible
- Abra as configurações do Agent: execute
agent: open settingsna paleta de comandos. O nome do item de menu pode variar um pouco entre versões; use como referência o bloco LLM Providers na página de configurações de AI / Agent. - No bloco LLM Providers, clique em Add Provider e selecione o tipo OpenAI-compatible.
- Dê um nome ao Provider, por exemplo
apiyi, que corresponde alanguage_models.openai_compatible.apiyino settings.json. - No campo API URL, preencha
https://api.apiyi.com/v1. O/v1é obrigatório aqui; é o formato indicado na página de compatibilidade com OpenAI da APIYI. - Cole no campo API Key o token recém-criado; o Zed vai armazená-lo no keychain do sistema.
- Adicione um modelo: no campo name, informe o ID real da tabela geral de modelos da APIYI, por exemplo
claude-opus-5-5,claude-sonnet-5-5; você também pode adicionarclaude-fable-5-2. Preenchamax_tokensconforme a documentação do modelo; se não tiver certeza, comece com um valor conservador e aumente depois que tudo estiver funcionando. - Deixe as opções de capacidade no padrão (tools=true). Ative manualmente images apenas quando precisar enviar imagens.
- Volte ao painel do Agent e pesquise
apiyiou o nome do modelo no seletor de modelos. As versões recentes do seletor de modelos já suportam busca aproximada; depois de selecionar, envie uma mensagem para validar.
A vantagem dessa rota é que um único Provider pode conectar vários modelos. A documentação da APIYI explica que, no endpoint compatível com OpenAI /v1/chat/completions, basta alterar a string do modelo em um único lugar para trocar de modelo.
Rota B: endpoint compatível com Anthropic no Zed
- Vá também em LLM Providers → Add Provider e escolha o tipo Anthropic-compatible.
- No campo API URL, coloque
https://api.apiyi.com, apenas o domínio raiz, sem /v1. As requisições reais vão cair no endpoint nativo Anthropic do APIYI:https://api.apiyi.com/v1/messages. - Cole o mesmo token ou crie um token dedicado só para isso.
- Em available_models, adicione IDs como
claude-opus-5-5,claude-sonnet-5-5e outros. - Se você quer que conversas de contexto longo aproveitem o cache, ative
capabilities.prompt_caching. Segundo a página de capacidades do Claude na APIYI, a cobrança de cache só funciona no formato nativo Messages. - Selecione o modelo no seletor de modelos e envie uma mensagem para testar.
💡 Sugestão de escolha: se o seu dia a dia é dominado pelo Claude, as sessões são longas e você relê os mesmos arquivos com frequência, a Rota B compensa mais. Se você precisa alternar entre vários modelos o tempo todo, a Rota A é mais prática. As duas rotas podem usar o mesmo token APIYI, alternando conforme a tarefa no seletor de modelos do Zed.
Referência de preços dos modelos Claude (data de referência dos dados: 2026-11-13)
Os dados abaixo vêm da tabela mestre de modelos da APIYI, verificados na documentação em 2026-11-13. A unidade é USD / 1 milhão de tokens, com cobrança conforme o uso.
| ID do modelo | Entrada | Saída | Leitura de cache | Endpoints compatíveis | Plataforma disponível |
|---|---|---|---|---|---|
claude-opus-5-5 |
$4 | $20 | $0,2 | chat + messages | APIYI apiyi.com |
claude-opus-5-5-thinking |
Igual ao opus-5-5 | Igual ao opus-5-5 | Igual ao opus-5-5 | Conforme a tabela mestre | APIYI apiyi.com |
claude-sonnet-5-5 |
$2 | $10 | $0,1 | Conforme a tabela mestre | APIYI apiyi.com |
claude-fable-5-2 |
$8 | $40 | $0,2 | Conforme a tabela mestre | APIYI apiyi.com |
Modelos e preços estão sujeitos à lista de modelos da plataforma. Antes de configurar, você pode abrir docs.apiyi.com/models para conferir os números e grupos do dia. Na tabela mestre, a linha de claude-opus-5-5 inclui grupos como ClaudeCode, Claude_Reverse, Claude_Enterprise, Default e SVIP.
Sobre os limites de uso do claude-opus-5-5, a atualização de lançamento da APIYI (2026-09-23) menciona três pontos: o modo de raciocínio (thinking) não pode ser definido como disabled; definir tool_choice como any / tool retorna 400; o effort padrão é medium. Se o Zed Agent retornar 400 ao chamar ferramentas, verifique esses itens primeiro.
Resolução de erros comuns em endpoints personalizados do Zed
Quando um Provider personalizado falha, a maioria dos problemas está em três lugares: URL, Key e nome do modelo. A tabela abaixo está ordenada por frequência de ocorrência — dá para conferir item por item.
| Sintoma | Causa comum | Como resolver |
|---|---|---|
| 404 Not Found | No Anthropic-compatible foi colocado /v1, então o caminho virou /v1/v1/messages |
Volte ao domínio raiz https://api.apiyi.com |
| 404 / caminho errado | No OpenAI-compatible faltou o /v1 |
Mude para https://api.apiyi.com/v1 |
| 401 / falha de autenticação | Token errado, já excluído, ou variável de ambiente sobrescrevendo o keychain | Confira novamente em api.apiyi.com/token e limpe as variáveis de ambiente conflitantes |
| Modelo não existe | ID com erro de digitação ou uso de alias | Copie o ID original em docs.apiyi.com/models |
| 400 (chamada de ferramenta) | tool_choice definido como any / tool, ou tentativa de desativar o raciocínio |
Ajuste conforme as observações dinâmicas de lançamento |
| Imagem inválida | OpenAI-compatible tem images=false por padrão | Ative images em capabilities |
| Erro em modelos que só suportam Responses | Ainda chamando como Chat Completions | Defina capabilities.chat_completions como false |
🎯 Dica de troubleshooting: se aparecer 404, primeiro compare palavra por palavra o api_url nas configurações do Zed com o FAQ de Base URL do APIYI (docs.apiyi.com/faq/base-url-config). A maioria dos problemas é só um
/v1escrito a mais ou a menos.
Aviso de riscos ao usar Provider personalizado no Zed
- Hospedagem não oficial: os Providers personalizados OpenAI-compatible / Anthropic-compatible são uma capacidade genérica de integração oferecida pelo Zed; gateways de terceiros não são serviços oficialmente hospedados pelo Zed. Se houver problemas de serviço, é preciso procurar o provedor do gateway.
- Chave e cobrança são sua responsabilidade: o token e a cobrança por uso ficam na sua própria conta. Recomendo criar um token separado para o Zed, conferir o uso regularmente e não escrever a chave no settings.json para depois commitar no repositório. O Zed usa o keychain do sistema por padrão, o que já reduz esse risco.
- Os termos dos External Agents ficam com o fornecedor: assinatura, cota e termos de uso de Agents externos como Claude Agent e Codex são definidos por cada fornecedor e são independentes da configuração de Provider do Zed Agent.
- Diferenças entre versões: as descrições de interface neste artigo se baseiam na documentação oficial e nas informações de releases das versões 1.28.x / 1.29.x (data de observação: 2026-11-13). Os nomes dos menus podem mudar em versões posteriores.
Perguntas frequentes (FAQ)
Q1: O que é o endpoint compatível com OpenAI do Zed?
É um tipo de Provider personalizado dentro de LLM Providers. Desde que o servidor implemente a interface Chat Completions, dá para conectar ao Zed Agent usando api_url e a lista de modelos, sem esperar pela adaptação oficial do Zed.
Q2: A chave preenchida em LLM Providers pode ser usada diretamente pelo Claude Agent?
Não. O Claude Agent é um External Agent, e a autenticação é gerenciada por ele mesmo; é preciso executar `/login` na thread dele. A chave em LLM Providers serve apenas para o Zed Agent.
Q3: Qual escolher: OpenAI-compatible ou Anthropic-compatible?
Escolha Anthropic-compatible se você usa Claude como principal e precisa de cobrança com cache; escolha OpenAI-compatible se quiser conectar vários modelos a um único Provider. Conforme a documentação da APIYI, a cobrança com cache só funciona no formato nativo Messages.
Q4: Qual ID de modelo devo preencher?
Preencha o ID original da tabela geral de modelos da plataforma, por exemplo `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-fable-5-2`. Recomendo copiar direto de docs.apiyi.com/models para evitar erro de digitação e o temido “modelo inexistente”.
Q5: Configurei tudo e continuo recebendo 404. Como investigar?
Primeiro, confira o `/v1`: OpenAI-compatible precisa incluí-lo, Anthropic-compatible não pode incluí-lo. Se o caminho estiver certo, verifique se o ID do modelo bate com a lista de modelos da APIYI.
Q6: Onde a chave API fica armazenada? Ela será sincronizada com o repositório?
O Zed guarda a chave no keychain do sistema e não a escreve em settings.json; portanto, ao compartilhar o arquivo de configuração, a chave não vai junto. Atenção: se existir uma variável de ambiente com o mesmo nome e valor não vazio, ela terá prioridade sobre o keychain. Ao investigar um 401, não esqueça de checar as variáveis de ambiente.
Q7: Quais são as limitações conhecidas dessa configuração?
O OpenAI-compatible não ativa suporte a imagens por padrão; no `claude-opus-5-5`, o raciocínio não pode ser desativado, e definir `tool_choice` como any / tool retorna 400. Além disso, o Provider personalizado não é um serviço oficialmente hospedado pelo Zed; a estabilidade depende do gateway.
Zed integrado à APIYI: principais pontos
- Primeiro, separe os caminhos: o Zed Agent usa LLM Providers; o External Agent gerencia a própria autenticação.
- Dois tipos de endpoint: OpenAI-compatible usa chat; Anthropic-compatible usa messages.
- Regra de URL: para compatibilidade com OpenAI, preencha
/v1; no Claude nativo, informe apenas o domínio raiz. - ID do modelo: copie o ID original, como
claude-opus-5-5, da tabela geral de modelos da APIYI. - Cobrança de cache: quando precisar de cache, use Anthropic-compatible e ative
prompt_caching. - Ordem de solução de problemas: verifique, nesta ordem,
/v1, o token, o ID do modelo e os parâmetros da ferramenta. - Como começar: crie um token dedicado em api.apiyi.com/token e conclua a configuração em 5 minutos.
Resumo
No Zed, para trocar o modelo, o ponto crítico é confirmar qual camada você quer alterar:
- Trocar o modelo do Zed Agent: em LLM Providers, use Add Provider para adicionar um endpoint OpenAI-compatible ou Anthropic-compatible.
- External Agent: Claude Agent, OpenCode e similares gerenciam a própria autenticação; a Key não é compartilhada com o Zed Agent.
- Base URL: para compatibilidade com OpenAI, preencha
https://api.apiyi.com/v1; para compatibilidade com Anthropic, preenchahttps://api.apiyi.com. Escrever/v1a mais ou a menos resultará em 404.
Antes de configurar, recomendo verificar os modelos e preços do dia em docs.apiyi.com/models e depois criar uma Key dedicada ao Zed na página de tokens. Comece rodando com claude-sonnet-5-5 e depois alterne para claude-opus-5-5 conforme a tarefa. Você pode usar o mesmo token nos dois Providers por meio da APIYI apiyi.com para comparar os resultados.
📚 Referências
- Repositório GitHub do Zed: observação do código-fonte e do número de stars (2026-11-13)
- Link:
github.com/zed-industries/zed -
Descrição: licença predominante GPL-3.0-or-later, com componentes Apache-2.0
-
Zed AI Overview: descrição oficial das três abordagens de IA
- Link:
zed.dev/docs/ai/overview -
Descrição: limites entre Zed Agent, External Agents e Terminal Threads
-
Zed Use API Access: configuração de Provider personalizado
- Link:
zed.dev/docs/ai/use-api-access -
Descrição: campos OpenAI-compatible / Anthropic-compatible e armazenamento no keychain
-
Zed External Agents: Agent externo via ACP
- Link:
zed.dev/docs/ai/external-agents -
Descrição: formas de integração de Claude Agent, Codex, OpenCode etc.
-
Zed Releases: registro de atualizações de versão
- Link:
zed.dev/releases/stable -
Descrição: conteúdo das atualizações da versão estável 1.28.1 e do Preview
-
Tabela geral de modelos APIYI: IDs de modelo e preços
- Link:
docs.apiyi.com/models.md -
Descrição: preços de entrada / saída / leitura de cache, conforme a lista do dia
-
FAQ de configuração do Base URL do APIYI: regras do /v1
- Link:
docs.apiyi.com/faq/base-url-config.md -
Descrição: diferenças entre a sintaxe do Base URL compatível com OpenAI e do Base URL nativo do Claude
-
Página de recursos do Claude no APIYI: endpoints nativos e compatíveis
- Link:
docs.apiyi.com/api-capabilities/claude.md -
Descrição: o faturamento de cache só entra em vigor no formato Messages
-
Anúncio de lançamento do claude-opus-5-5 no APIYI: limites de uso
- Link:
docs.apiyi.com/live/2026-09/claude-opus-5-5.md - Descrição: explicação dos valores padrão de thinking, tool_choice e effort
Autor: Equipe técnica da APIYI
Contato técnico: Se tiver problemas de configuração, consulte a central de documentação em docs.apiyi.com ou fale conosco pela página inicial do site oficial da APIYI
