Tutorial passo a passo: conecte todos os agentes com uma única chave usando o gateway de API de acesso unificado e de código aberto magpie (com Claude Code, Codex, Pi e Hermes como exemplos)

Nota do autor: este é um tutorial que você pode seguir do começo ao fim. Depois de ler e colocar tudo em prática, você terá uma configuração em que “uma chave, um endereço de gateway; conecte quantos Agents quiser”. Da próxima vez que trocar de modelo ou rotacionar a chave, basta alterar um único lugar.

Antes de começar, entenda o que você vai fazer

• Objetivo: fazer com que todos os Agents de programação da sua máquina usem a mesma chave API e o mesmo endereço upstream. Neste tutorial, vamos usar Claude Code, Codex, Pi e Hermes como exemplos. Conecte quantos tiver instalados.
• Duração: cerca de 30 minutos, sem contar o tempo para criar a conta e baixar os arquivos.
• Pré-requisitos: um token da APIYI (também pode ser uma chave oficial ou de qualquer serviço proxy de API compatível com OpenAI ou Anthropic), um computador que execute comandos e pelo menos um Agent instalado.
• Dificuldade: ★★☆☆☆. Basta saber clicar algumas vezes e copiar e colar. Você não precisará digitar nenhum comando durante o tutorial.

Roteiro do tutorial

Entenda em três minutos: o que o magpie faz no meio do caminho

Se você só quer “fazer igual e pronto”, pode pular esta seção. Mas vale a pena gastar três minutos aqui: isso vai agilizar bastante a investigação de problemas depois.

Cada Agent tem requisitos bem diferentes para o modelo upstream. Se você configurar tudo manualmente, vai acabar mantendo várias configurações — uma para cada ferramenta instalada. Veja quatro exemplos comuns:

O magpie (repositório github.com/yetone/magpie, com o lema “Every agent’s model. One place.”) resolve justamente isso: reúne em um só lugar a configuração de qual modelo cada Agent usa e qual chave API ele lê. Depois, altera as configurações nativas de cada ferramenta.

Em resumo:

• O magpie gerencia a distribuição: decide qual modelo o Claude Code e o Codex vão usar
• O gateway gerencia os protocolos: encaminha solicitações nos formatos Anthropic, OpenAI e Gemini para os provedores de modelos correspondentes

Por isso, é melhor que seu gateway upstream suporte vários protocolos

A combinação ideal é “o magpie gerencia a distribuição, e o gateway gerencia os protocolos”. Se o gateway só aceitar o formato compatível com OpenAI, o Claude Code vai precisar de uma camada extra de conversão de protocolo. Isso deixa o fluxo mais longo e aumenta a chance de haver incompatibilidades no formato das chamadas de ferramentas.

A APIYI permite usar um único token com três protocolos populares: OpenAI compatível, Anthropic nativo e formato Gemini podem ser acessados com a mesma chave API (consulte o painel para ver o escopo exato do suporte). Assim, basta configurar um único upstream no magpie, e todos os Agents podem se conectar diretamente, sem precisar manter contas e faturas de vários provedores.

Como escolher entre as três opções

A configuração manual é a opção mais direta, mas, quando você usa muitas ferramentas, as chaves ficam espalhadas por vários arquivos, o que aumenta bastante o custo de rotação e de investigação de problemas. Um script com variáveis de ambiente não tem dependências e pode ser feito em poucas dezenas de linhas, mas não permite atribuir modelos diferentes a cada Agent. Para algo como “Claude Code com Claude, Codex com GPT e Hermes com um modelo mais barato”, uma solução de gerenciamento centralizado como o magpie é bem mais prática.

Etapa 1: gere uma chave e copie

1.1 Crie um token no painel da APIYI

Acesse o painel da APIYI (apiyi.com), crie um token e copie-o.

Nesta etapa, você não precisa digitar nenhum comando. Durante todo o processo, essa chave só será usada uma vez: cole-a no painel de «Fornecedores» do magpie (etapa 3). Depois de colar, o próprio magpie configura os arquivos de cada Agent. Você não precisa usar export para definir variáveis de ambiente nem alterar arquivos como config.toml ou settings.json.

🚀 Ainda não tem um token? Você pode se cadastrar na APIYI em apiyi.com e receber créditos para testes. Use um único token para testar as ferramentas que pretende usar regularmente e, depois, decida quais modelos quer manter.

1.2 Deixe estes dois endereços à mão

Na etapa 3, você vai escolher qual endereço usar ao configurar o fornecedor:

✅ Confira se deu certo: o token está na área de transferência e você sabe qual endereço usar na etapa 3.

Etapa 2: instale o magpie e conheça estas duas páginas

O código-fonte, as instruções de instalação e o formato de configuração do magpie estão descritos no README do repositório oficial (github.com/yetone/magpie). Como o projeto recebe atualizações frequentes, os comandos de instalação e os nomes dos campos podem mudar conforme a versão. As capturas de tela e a sequência de ações mostradas abaixo são a parte que continua válida por mais tempo.

Depois de instalar e iniciar o programa, você verá uma janela com um menu de navegação à esquerda. Neste tutorial, vamos usar apenas duas páginas: Agent (qual modelo cada ferramenta usa) e Fornecedores (onde a chave fica configurada).

① Agent, no menu à esquerda, é o painel central de controle de todos os seus Agents:

Figura 1 · Página Agent: cada ferramenta aparece em uma linha; o botão à direita controla a conexão com o magpie, e o menu suspenso ao lado permite escolher o modelo

Nesta página, você precisa identificar três elementos:

② Fornecedores, no menu à esquerda, é onde você configura a chave do serviço upstream (vamos explicar em detalhes na próxima seção).

Se quiser entender como são os arquivos de configuração do magpie, dê uma olhada na estrutura providers / agents do README oficial. Em resumo, você dá um nome ao serviço upstream, informa base_url e a chave, e depois escolhe um modelo para cada Agent. Mas no dia a dia, basta clicar na janela: o magpie configura os arquivos nativos de cada ferramenta para você, o que é muito mais seguro do que editar YAML manualmente.

✅ Confira se deu certo: a janela abre e você vê as opções Agent e Fornecedores no menu à esquerda.

Etapa 3: adicione sua chave em “Provedores”

3.1 Acesse a página de provedores

Clique em Provedores no menu à esquerda (① no quadro vermelho da figura 2). Na página, clique em + Adicionar provedor, no canto superior direito (② no quadro vermelho):

Figura 2 · Página de provedores: acesse “Provedores” pelo menu à esquerda. “+ Adicionar provedor”, no canto superior direito, é a única opção.

Os provedores adicionados aparecem aqui em formato de cartão. Na segunda linha do cartão, você verá o endereço e a quantidade de modelos disponíveis (por exemplo, api.apiyi.com · 11 modelos). Para confirmar se está tudo funcionando, confira se essa linha mostra um número.

3.2 Qual tipo de provedor escolher

Ao clicar em “+ Adicionar provedor”, você verá um painel com várias categorias (figura 3):

Figura 3 · Painel para adicionar um provedor: cinco tipos de origem — assinatura, provedor, proxy, local e magpie em outro computador

As categorias do painel correspondem a cinco tipos diferentes de chave:

Se você usa a APIYI: o endpoint compatível com OpenAI segue o formato padrão de proxy. Escolha a opção correspondente na categoria Proxy. Se você tem uma chave personalizada compatível com OpenAI ou Anthropic, clique em + Provedor personalizado, na parte inferior (quadro vermelho da figura 3), e preencha o endereço e a chave. Use https://api.apiyi.com/v1 como endereço; para solicitações no formato nativo da Anthropic, use https://api.apiyi.com.

Este é o painel completo de um provedor. Para você, só importam quatro linhas:

Figura 4 · Página de configuração do provedor APIYI: em Base URL, escolha o protocolo e informe o endereço; em Accounts, adicione a chave; em Models, selecione os modelos que quer disponibilizar para os agentes.

A imagem mostra na prática o que quisemos dizer antes com “um token, vários protocolos”: o endereço é sempre https://api.apiyi.com. Escolha Anthropic compatível para usar o endpoint nativo que o Claude Code exige, OpenAI compatível para usar o endpoint /v1 com Codex, Pi ou Hermes, e Gemini compatível para o Gemini. Assim, você não precisa manter três provedores e três chaves.

Depois de preencher tudo, salve e volte à lista de provedores para conferir duas coisas: o cartão mostra a quantidade de modelos na segunda linha e a chave está ativada. Se aparecer · N modelos, a chave e o endereço estão funcionando — essa etapa já serve como verificação, sem precisar executar nenhum comando.

✅ Verificação desta etapa: seu cartão aparece na lista de provedores e mostra algo como · N modelos, em vez de “Não configurado”.

Etapa 4: conecte um por um os agentes instalados

Volte à página Agent e repita as mesmas três ações para cada ferramenta que você instalou. Essa página lista todos os agentes que o magpie pode conectar (a lista continua crescendo; os que não estão instalados aparecem como “CLI não encontrado”). Conecte todos os que você instalou. A tabela abaixo usa apenas quatro exemplos comuns:

1. Ative a chave à direita (ela muda de cinza para acesa).
2. Escolha um modelo à direita da chave (se não escolher, será usado o padrão; o modelo selecionado será gravado na configuração da própria ferramenta).
3. Reabra a ferramenta quando solicitado (na maioria dos casos, Codex, Claude Code, Pi e Hermes precisam reiniciar o processo para carregar a nova configuração).

Figura 5 · Abra a lista suspensa de modelos. A primeira opção, “Padrão”, faz o agente usar o modelo próprio, sem passar pelo magpie. Todas as opções seguintes estão marcadas como “via magpie”. Ao escolher uma delas, o agente usará o modelo correspondente do provedor.

Veja alguns estados comuns. Se aparecerem, você está no caminho certo:

• Conectado: a configuração foi gravada e entrará em vigor quando você reabrir a ferramenta.
• Não conectado · usando as próprias configurações de XXX: a chave não foi ativada ou nenhum modelo foi selecionado.
• Só pode usar os próprios modelos de XXX; não é possível conectar ao magpie: essa ferramenta (como o Cursor) só permite usar os próprios modelos. É uma limitação de projeto, não um erro de configuração.
• CLI não encontrado: a ferramenta não está instalada ou não está no PATH. Instale-a ou ajuste o PATH e tente novamente.

💡 Quer usar modelos diferentes em cada agente (Claude no Claude Code, GPT no Codex e um modelo mais barato no Hermes)? Basta escolher um modelo para cada um nesta etapa. Essa é uma das principais vantagens do magpie em relação aos scripts de variáveis de ambiente.

✅ Verificação desta etapa: as chaves dos agentes instalados estão ativadas, e o status não aparece mais como “Não conectado”.

Etapa 5: valide cada Agent com uma tarefa simples

Terminar a configuração não basta: é preciso testar. Envie a tarefa mais simples possível em cada ferramenta:

Para confirmar que as solicitações estão realmente passando pelo gateway, o jeito mais simples é conferir o uso e os logs desse token no console da APIYI. Se houver novos registros de chamadas, isso confirma que as solicitações de todos os Agents estão chegando à mesma chave.

✅ Critério de conclusão desta etapa: todos os Agents respondem normalmente e o console mostra os registros de chamadas correspondentes.

Anexo: como escolher um modelo (se estiver em dúvida, comece por aqui)

💡 Vale a pena executar a mesma tarefa em diferentes Agents e modelos. Com uma chave unificada, basta mudar o nome do modelo para alternar entre eles, o que facilita bastante a comparação de custos.

Etapa 6 (opcional): afinal, quais configurações o magpie escreve para você?

Esta seção não é necessária para fazer tudo funcionar. No uso do dia a dia, você não precisa mexer nesses arquivos: assim que você ativa a opção na etapa 4, o magpie já configura tudo isso. O objetivo aqui é apenas mostrar onde procurar se algo der errado e deixar um exemplo para você copiar caso um dia prefira não usar o magpie.

Claude Code: ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_BASE_URL="https://api.apiyi.com"   # Endpoint nativo da Anthropic
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"
# Opcional: especificar o modelo padrão (consulte a lista de modelos no console)
# export ANTHROPIC_MODEL="<nome do modelo Claude>"
claude

Você também pode adicionar essas configurações ao campo env de ~/.claude/settings.json. Assim, elas não dependem da sessão do terminal.

Codex: seção de provider em ~/.codex/config.toml

# ~/.codex/config.toml
model = "<nome de um modelo da série GPT>"
model_provider = "apiyi"

[model_providers.apiyi]
name = "APIYI"
base_url = "https://api.apiyi.com/v1"   # Endpoint compatível com OpenAI
env_key = "APIYI_API_KEY"
wire_api = "responses"                   # Se o modelo escolhido não for compatível com Responses, mude para "chat"

wire_api é o detalhe que mais costuma causar problemas: as versões mais recentes do Codex usam o protocolo Responses por padrão. Se o gateway disponibilizar apenas Chat Completions para esse modelo, você precisa mudar para chat.

Pi e Hermes: declarar um provider personalizado compatível com OpenAI

A ideia é a mesma: defina base_url como https://api.apiyi.com/v1 e use APIYI_API_KEY como chave. A estrutura varia entre versões; consulte a documentação oficial de cada ferramenta:

// Pi: declare um provider na configuração de modelos personalizados (a estrutura depende da documentação oficial do Pi)
{
  "providers": {
    "apiyi": {
      "baseUrl": "https://api.apiyi.com/v1",
      "api": "openai-completions",
      "apiKey": "APIYI_API_KEY",
      "models": [{ "id": "<nome do modelo>" }]
    }
  }
}

# Hermes: execute hermes model e selecione um endpoint personalizado compatível com OpenAI.
# Preencha as informações abaixo quando solicitado (ou adicione-as ao arquivo .env / config no diretório de configuração do Hermes)
#   Base URL : https://api.apiyi.com/v1
#   API Key  : $APIYI_API_KEY
#   Model    : <nome do modelo>

#!/usr/bin/env bash
# agents-env.sh — alternativa ao magpie: uma chave para todos os agentes
# Uso: source agents-env.sh
: "${APIYI_API_KEY:?Exporte APIYI_API_KEY antes de continuar}"

# Claude Code (protocolo Anthropic)
export ANTHROPIC_BASE_URL="https://api.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"

# Variáveis genéricas para ferramentas compatíveis com OpenAI, como Codex, Pi e Hermes
export OPENAI_BASE_URL="https://api.apiyi.com/v1"
export OPENAI_API_KEY="$APIYI_API_KEY"

# Verificação de conectividade
curl -s "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $APIYI_API_KEY" | head -c 300 && echo
echo "✅ Todos os agentes estão apontando para o mesmo gateway"

curl -s "https://api.apiyi.com/v1/models" \
  -H "Authorization: Bearer sk-seu-token" | head -c 300

Se algo der errado, confira estes quatro erros comuns

Sempre faça a verificação de baixo para cima: primeiro confirme se o gateway e a chave estão funcionando (veja se o cartão do provedor mostra · N modelos), depois confira a configuração nativa do agente e, por último, a camada de mapeamento do magpie. Com essas três etapas, você consegue identificar se o problema está no serviço upstream, na própria ferramenta ou na configuração unificada.

Perguntas frequentes

Consulta rápida em cinco minutos

• Divisão de tarefas: o magpie gerencia o mapeamento dos modelos; o gateway encaminha as solicitações de acordo com o protocolo. Cada um cuida de uma coisa.
• Um único token: escolha um provedor com suporte a vários protocolos para que todos os agentes usem a mesma chave e uma única conta de cobrança.
• Ordem para começar: crie um token no painel → cole-o em “Provedores” → ative o agente → teste cada um. Todo o processo é feito pela interface, sem precisar usar comandos.
• Ordem para solucionar problemas: gateway → configuração nativa do agente → camada de mapeamento do magpie, de baixo para cima.
• Dica para o Claude Code: use ANTHROPIC_AUTH_TOKEN e não acrescente /v1 ao base_url.
• Dica para o Codex: wire_api precisa corresponder ao protocolo compatível com o modelo.
• Alternativa: um script com variável de ambiente (agents-env.sh) também permite que todos os agentes usem a mesma chave.

Se você usa três ou mais agentes, vale a pena reservar meia hora para configurar tudo: depois, para trocar de modelo ou de chave, basta alterar um único ponto. Recomendamos resgatar créditos de teste em APIYI apiyi.com, testar primeiro as ferramentas que você usa com mais frequência e, em seguida, definir modelos diferentes para cada agente conforme as tarefas.

Leitura complementar

• 📘 O Workbuddy aceita chamadas no formato nativo do Claude? Testes práticos: 3 motivos e como investigar 6 tipos de erros de content: quer entender a diferença entre o formato nativo da Anthropic e o formato compatível com OpenAI? Confira este artigo. Ele também explica por que, na etapa 2 deste artigo, o Claude Code precisa usar o endpoint nativo.
• 📊 claude-sonnet-5-5 vs. claude-opus-5-5: o Opus é mais rápido e o Sonnet só é mais barato? 6 conjuntos de dados mostram a melhor combinação para agentes empresariais com contexto longo: antes de escolher modelos diferentes para cada agente na etapa 4, leia este artigo para decidir quem deve usar o Opus e quem pode ficar com um modelo mais barato.
• ⚠️ Qual é a concorrência do gemini-4-argon no AI Studio? 5 causas comuns de erros 429 e 6 etapas para resolvê-los: se vários agentes usarem a mesma chave ao mesmo tempo e atingirem o limite de requisições, siga estas 6 etapas de diagnóstico.
• 🧭 Erro “model not found” da OpenAI? O GPT-5.5 saiu do ChatGPT em 14 de outubro: 5 etapas de diagnóstico e alternativas: se aparecer a mensagem “modelo não encontrado” durante a verificação da etapa 5, confirme primeiro se esse nome de modelo ainda é válido.

📚 Referências

1. GitHub – magpie: repositório oficial do projeto
2. Link: github.com/yetone/magpie
3. Observação: consulte o README para ver as instruções de instalação, o formato de configuração e as atualizações de versão.
4. Documentação oficial do Claude Code: variáveis de ambiente e configurações de settings
5. Link: docs.anthropic.com/en/docs/claude-code
6. Observação: informações oficiais sobre variáveis como ANTHROPIC_BASE_URL.
7. Repositório do OpenAI Codex CLI: configurações de config.toml e model_providers
8. Link: github.com/openai/codex
9. Observação: informações sobre providers personalizados e o parâmetro wire_api.
10. Central de documentação da APIYI: endpoints de vários protocolos e lista de modelos
11. Link: docs.apiyi.com
12. Observação: instruções de integração para endpoints dos protocolos OpenAI, Anthropic e outros.

Autor: equipe técnica da APIYI
Discussão técnica: compartilhe suas experiências com a configuração do magpie nos comentários. Para consultar mais materiais de integração, acesse a central de documentação da APIYI em docs.apiyi.com.