Pontente de Endpoint de API Personalizado para Claude Code: Configuração de Gateway de Terceiros com Modelos Open-Source Chinês

O Claude Code pode ser configurado para comunicar-se com um endpoint compatível com Anthropic em vez de usar diretamente um endpoint de provedor. Isso permite testar um fluxo de trabalho gerenciado por gateway com IDs de modelo expostos pelo gateway, incluindo modelos open-source chineses disponíveis no catálogo atual do ECAIX.

Este guia trata de um fluxo de trabalho específico de provedor, compatível com terceiros. A documentação oficial do gateway de Claude Code da Anthropic explica que a Anthropic não suporta rotear o Claude Code para modelos não-Claude através de um gateway. O ECAIX não faz afirmações de que este fluxo de trabalho é oficialmente suportado pela Anthropic, e um modelo não-Claude pode não fornecer todas as capacidades do Claude Code.

Início Rápido

Se já entende os limites de compatibilidade, siga este caminho rápido:

1. Abra o atual catálogo de modelos do ECAIX e escolha um ID de modelo ativo.
2. Crie uma chave de API do ECAIX e mantenha-a fora do controle de versão.
3. Defina ANTHROPIC_BASE_URL para https://ecaix.com/api/ai/v1/anthropic.
4. Envie a solicitação de diagnóstico abaixo e registre o código HTTP.
5. Execute o Claude Code em um projeto de teste em apenas leitura com claude -p.
6. Teste ferramentas, fluxo de dados, limites de contexto e permissões separadamente.

Status de validação na publicação

Esta tabela é intencional: um exemplo de configuração não é o mesmo que um resultado de compatibilidade medido.

O que este setup altera

O setup possui quatro partes separadas:

1. Claude Code é o cliente que cria tarefas de codificação e envia solicitações.
2. O gateway compatível com Anthropic recebe solicitações em um endpoint estilo Anthropic.
3. O ID de modelo seleciona o modelo de origem exposto pelo gateway.
4. A chave de API autentica a solicitação e determina o usuário, quota e permissões.

Alterar o endpoint não transforma um modelo não-Claude em Claude. Ele apenas muda qual superfície de API compatível recebe a solicitação. O uso de ferramentas, manejo de contexto, aliases de modelos, comportamento de fluxo de dados e fluxos de permissão podem variar conforme a versão do cliente e a implementação do gateway.

Antes de começar

Você precisa:

• Uma instalação do Claude Code que suporte configuração baseada em ambiente ou configurações de endpoint.
• Uma chave de API do ECAIX.
• Um ID de modelo que atualmente existe no catálogo de modelos do ECAIX.
• Um terminal onde possa executar uma pequena solicitação de teste sem colocar a chave de API no controle de versão.

O catálogo muda com o tempo. Antes de copiar um ID de modelo em um arquivo de configuração, abra o diretório de modelos do ECAIX e confirme que o modelo está ativo e disponível para o estilo de API que planeja usar.

Configurar o endpoint do gateway

O Claude Code armazena configurações em ~/.claude/settings.json em muitas instalações. O esquema de configurações exato pode mudar, então trate o seguinte como um padrão inicial e compare-o com a documentação da sua versão instalada.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ecaix.com/api/ai/v1/anthropic",
    "ANTHROPIC_API_KEY": "YOUR_ECAIX_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT": "1"
  },
  "model": "deepseek-v4.1-flash"
}

Não cometa este arquivo em um repositório público se ele contiver uma chave de API real. Prefira uma variável de ambiente local, um gerenciador de segredos ou o mecanismo de credenciais recomendado pela sua instalação do Claude Code.

Também pode configurar o endpoint em uma sessão de shell enquanto testa:

export ANTHROPIC_BASE_URL="https://ecaix.com/api/ai/v1/anthropic"
export ANTHROPIC_API_KEY="YOUR_ECAIX_API_KEY"
export ANTHROPIC_MODEL="deepseek-v4.1-flash"

Os nomes das variáveis e configurações suportadas por uma versão específica do Claude Code podem mudar. Se o cliente ignorar ANTHROPIC_MODEL, use o campo de modelo ou o mecanismo de alias de modelo documentado pela sua versão. O gateway ainda precisa reconhecer o ID final do modelo.

Verificar o endpoint compatível com Anthropic primeiro

Antes de iniciar uma sessão de codificação interativa, envie uma pequena solicitação. Isso separa problemas de endpoint, autenticação e ID de modelo dos comportamentos específicos do Claude Code.

O comando abaixo salva separadamente os cabeçalhos de resposta e o corpo da resposta, e imprime o código HTTP. Use uma chave de vida real apenas em sua shell local; nunca cole-a em um artigo, problema ou histórico de shell compartilhado.

curl -sS -D /tmp/ecaix-anthropic-headers.txt \
  -o /tmp/ecaix-anthropic-response.json \
  -w '\nHTTP %{http_code}\n' \
  "${ANTHROPIC_BASE_URL}/messages" \
  -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "max_tokens": 128,
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ]
  }'

Interpretação esperada:

• 200: inspecione a forma da resposta e confirme os campos retornados de modelo ou uso.
• 401 ou 403: verifique a chave, cabeçalho, escopo do usuário e permissão antes de alterar o prompt.
• 404: verifique a URL base, o sufixo /messages e a implantação do endpoint.
• 400: reduza a solicitação ao corpo mais pequeno válido e verifique os campos específicos do modelo.
• 5xx ou timeout: registre o tempo de solicitação e o corpo da resposta, então separe o comportamento de timeout do gateway, do provedor de origem e do cliente.

Uma resposta bem-sucedida confirma que a chave, o endpoint, a forma da solicitação e o ID de modelo funcionaram juntos para essa solicitação. Não prova que todas as funcionalidades do Claude Code funcionarão.

Escolher um ID de modelo

O catálogo do ECAIX contém famílias de modelos de provedores chineses. O modelo ideal depende da tarefa, não apenas do nome do modelo.

Desenvolvimento e codificação geral

Comece com um modelo atual DeepSeek, Qwen, GLM ou Seed que é visível no catálogo e capaz de codificação. Por exemplo, um catálogo pode expor IDs como deepseek-v4.1-flash, qwen3.8-flash, glm-5.3 ou seed-2.0-code. A disponibilidade e capacidades podem mudar, então sempre verifique a página atual do modelo antes de publicar uma configuração.

Trabalho com contexto longo e repositórios

Para grandes repositórios ou documentos técnicos longos, compare a extensão de contexto mostrada na página do modelo. Uma janela de contexto maior não significa automaticamente melhores resultados de repositório: a estrutura do prompt, o suporte de ferramentas, limites de saída e os limites de solicitação do gateway também importam.

Trabalhos de chamadas de ferramentas e fluxos de agentes

Se o fluxo de trabalho precisar de chamadas de função ou ferramentas, verifique a documentação do modelo e do endpoint. Alguns provedores expõem chamadas de ferramentas através de APIs compatíveis com OpenAI, enquanto outros expõem nomes de campos diferentes ou suportam apenas um subconjunto do comportamento de ferramentas. Comece com um teste de chamada de ferramenta simples antes de dar ao modelo acesso a um repositório real ou sistema externo.

Trabalhos de desenvolvimento em chinês

Modelos open-source chineses podem ser úteis quando a base de código, documentação, rastreamento de problemas ou fluxo de trabalho da equipe contém material em chinês. Avalie o modelo com seus próprios prompts e amostras de repositório, em vez de depender apenas de classificações gerais.

Testar o Claude Code após a solicitação de API funcionar

Uma vez que a solicitação direta tenha sido bem-sucedida, comece com uma tarefa de leitura apenas ou de baixo risco:

claude -p "Explain what this repository does without editing files."

Em seguida, teste uma tarefa de escopo estreito. Por exemplo:

claude -p "List the likely entry points for the web application. Do not modify files."

Use testes progressivamente mais exigentes:

1. Resposta em texto puro.
2. Explicação curta de código.
3. Navegação de repositório.
4. Edição controlada em uma ramificação descartável.
5. Uso de ferramentas ou tarefa multi-etapa.
6. Comportamento de fluxo de dados e contexto longo.

Não assuma que uma resposta bem-sucedida em texto prova que os prompts de permissão, chamadas de ferramentas, fluxo de dados, limites de contexto ou edição de arquivos se comportam de forma idêntica a uma sessão com Claude.

Escolher o caminho correto da API

O Claude Code é apenas um fluxo de trabalho de cliente. O caminho correto da API depende do cliente e do conjunto de recursos que você precisa:

Para o ECAIX, use a documentação do Anthropic Messages para o caminho estilo Anthropic e a documentação do Chat Completions para clientes compatíveis com OpenAI. Use o diretório de modelos para confirmar o modelo atual e a página de preços para os preços exibidos atualmente.

Matriz de compatibilidade

A seguinte matriz é um limite de evidência na data de publicação, não uma afirmação de que todas as funcionalidades são suportadas:

Esta distinção evita apresentar uma solicitação mínima bem-sucedida como uma certificação completa de compatibilidade do Claude Code.

Páginas de detalhes de modelos e IDs atuais

Use as páginas de detalhes de modelos em vez de copiar um nome de modelo antigo de um blog:

• DeepSeek v4.1 Flash
• Qwen 3.8 Flash
• GLM 5.3
• Kimi K3

Estas são as entradas para verificar o ID atual do modelo, informações de contexto e detalhes de nível de página. A disponibilidade pode mudar após a publicação.

Após um erro, use este ordem em vez de alterar várias variáveis ao mesmo tempo:

1. Salve o código HTTP e o corpo da resposta.