Proxy de Traducao

O proxy de traducao e o nucleo do Claudex. Ele se posiciona entre o Claude Code e seus provedores de IA, convertendo de forma transparente entre a API Anthropic Messages e a API OpenAI Chat Completions (ou API Responses).

Como Funciona

Claude Code → requisicao da API Anthropic Messages
    │
    └── Proxy Claudex (127.0.0.1:13456)
        │
        ├── Provedor DirectAnthropic → encaminhar com headers
        │
        ├── Provedor OpenAICompatible
        │   ├── Traduzir requisicao: Anthropic → OpenAI Chat Completions
        │   ├── Aplicar query_params, strip_params, custom_headers
        │   ├── Encaminhar para o provedor
        │   └── Traduzir resposta: OpenAI → Anthropic
        │
        └── Provedor OpenAIResponses
            ├── Traduzir requisicao: Anthropic → API OpenAI Responses
            ├── Encaminhar para o provedor
            └── Traduzir resposta: Responses → Anthropic

Adaptadores de Provedor

O Claudex usa um trait ProviderAdapter para lidar com diferencas entre APIs de provedores. Tres adaptadores sao implementados:

Adaptador	Traducao	Usado Por
DirectAnthropic	Nenhuma (passthrough)	Anthropic, MiniMax, Vertex AI
ChatCompletions	Traducao completa Anthropic ↔ OpenAI	Grok, OpenAI, DeepSeek, Kimi, GLM, OpenRouter, Groq, Mistral, Together AI, Perplexity, Cerebras, Azure OpenAI, GitHub Copilot, GitLab Duo, Ollama, vLLM, LM Studio
Responses	Anthropic ↔ API OpenAI Responses	Assinaturas ChatGPT/Codex

O que e Traduzido

Traducao de Requisicao (Anthropic → OpenAI)

Anthropic	OpenAI
Campo `system`	Mensagem de sistema no array `messages`
Blocos `messages[].content` (text, image, tool_use, tool_result)	`messages[].content` + `tool_calls`
Array `tools` (JSON Schema com `input_schema`)	Array `tools` (formato function com `parameters`)
`tool_choice` (`auto`, `any`, `{name}`)	`tool_choice` (`auto`, `required`, `{function: {name}}`)
`max_tokens`	`max_tokens` (limitado pela configuracao `max_tokens` do profile, se definida)
`temperature`, `top_p`	Mapeamento direto (removidos se `strip_params` corresponder)

Traducao de Resposta (OpenAI → Anthropic)

OpenAI	Anthropic
`choices[0].message.content`	Blocos `content` (type: text)
`choices[0].message.tool_calls`	Blocos `content` (type: tool_use)
`finish_reason: stop`	`stop_reason: end_turn`
`finish_reason: tool_calls`	`stop_reason: tool_use`
`usage.prompt_tokens` / `completion_tokens`	`usage.input_tokens` / `output_tokens`

Compatibilidade de Nomes de Ferramentas

O Claude Code pode gerar nomes de ferramentas com mais de 64 caracteres (ex: mcp__server-name__very-long-tool-name-that-exceeds-the-limit). O OpenAI e muitos provedores impoem um limite de 64 caracteres.

O Claudex automaticamente:

Trunca nomes que excedem 64 caracteres nas requisicoes de saida
Cria uma tabela de mapeamento de nomes truncados → originais
Restaura os nomes originais nas respostas do provedor

Essa traducao de ida e volta e totalmente transparente.

Traducao em Streaming

O Claudex suporta completamente SSE (Server-Sent Events) em streaming, traduzindo chunks do stream OpenAI em eventos do stream Anthropic em tempo real:

OpenAI SSE	Anthropic SSE
Primeiro chunk	`message_start` + `content_block_start`
`choices[0].delta.content`	`content_block_delta` (text_delta)
`choices[0].delta.tool_calls`	`content_block_delta` (input_json_delta)
`finish_reason` presente	`content_block_stop` + `message_delta` + `message_stop`

O tradutor de streaming mantem uma maquina de estados para tratar corretamente o acumulo de chamadas de ferramentas e os limites de blocos de conteudo.

Suporte ao Azure OpenAI

O Azure OpenAI usa um esquema diferente de autenticacao e URL:

Autenticacao: header api-key em vez de Authorization: Bearer
Formato da URL: https://{resource}.openai.azure.com/openai/deployments/{deployment}
Versao da API: obrigatoria via query_params

O Claudex detecta automaticamente o Azure verificando se a base_url contem openai.azure.com e ajusta a autenticacao conforme necessario.

Provedores Suportados

Provedor	Tipo	URL Base
Anthropic	DirectAnthropic	`https://api.anthropic.com`
MiniMax	DirectAnthropic	`https://api.minimax.io/anthropic`
Google Vertex AI	DirectAnthropic	`https://REGION-aiplatform.googleapis.com/v1/projects/...`
OpenRouter	OpenAICompatible	`https://openrouter.ai/api/v1`
Grok (xAI)	OpenAICompatible	`https://api.x.ai/v1`
OpenAI	OpenAICompatible	`https://api.openai.com/v1`
DeepSeek	OpenAICompatible	`https://api.deepseek.com`
Kimi/Moonshot	OpenAICompatible	`https://api.moonshot.ai/v1`
GLM (Zhipu)	OpenAICompatible	`https://api.z.ai/api/paas/v4`
Groq	OpenAICompatible	`https://api.groq.com/openai/v1`
Mistral AI	OpenAICompatible	`https://api.mistral.ai/v1`
Together AI	OpenAICompatible	`https://api.together.xyz/v1`
Perplexity	OpenAICompatible	`https://api.perplexity.ai`
Cerebras	OpenAICompatible	`https://api.cerebras.ai/v1`
Azure OpenAI	OpenAICompatible	`https://{resource}.openai.azure.com/...`
GitHub Copilot	OpenAICompatible	`https://api.githubcopilot.com`
GitLab Duo	OpenAICompatible	`https://gitlab.com/api/v4/ai/llm/proxy`
Ollama	OpenAICompatible	`http://localhost:11434/v1`
vLLM	OpenAICompatible	`http://localhost:8000/v1`
LM Studio	OpenAICompatible	`http://localhost:1234/v1`
Assinatura ChatGPT/Codex	OpenAIResponses	`https://chatgpt.com/backend-api/codex`

Endpoint Models

O proxy expoe um endpoint /v1/models que lista todos os profiles habilitados. Cada entrada inclui campos personalizados:

x-claudex-profile: nome do profile
x-claudex-provider: tipo do provedor (anthropic, openai-compatible, openai-responses)

O Claude Code consulta este endpoint para descobrir modelos disponiveis.

Gerenciamento do Proxy

# Iniciar proxy como daemon
claudex proxy start -d

# Verificar status do proxy
claudex proxy status

# Parar daemon do proxy
claudex proxy stop

# Iniciar em uma porta personalizada
claudex proxy start -p 8080

Quando voce executa claudex run <profile>, o proxy e iniciado automaticamente em segundo plano se ainda nao estiver em execucao.