Proxy de traduccion

El proxy de traduccion es el nucleo de Claudex. Se situa entre Claude Code y tus proveedores de IA, convirtiendo de forma transparente entre la API de Mensajes de Anthropic y la API de Chat Completions de OpenAI (o la API de Responses).

Como funciona

Claude Code → Anthropic Messages API request
    │
    └── Claudex Proxy (127.0.0.1:13456)
        │
        ├── DirectAnthropic provider → forward with headers
        │
        ├── OpenAICompatible provider
        │   ├── Translate request: Anthropic → OpenAI Chat Completions
        │   ├── Apply query_params, strip_params, custom_headers
        │   ├── Forward to provider
        │   └── Translate response: OpenAI → Anthropic
        │
        └── OpenAIResponses provider
            ├── Translate request: Anthropic → OpenAI Responses API
            ├── Forward to provider
            └── Translate response: Responses → Anthropic

Adaptadores de proveedor

Claudex usa un trait ProviderAdapter para gestionar las diferencias entre las APIs de los proveedores. Se implementan tres adaptadores:

Adaptador	Traduccion	Usado por
DirectAnthropic	Ninguna (passthrough)	Anthropic, MiniMax, Vertex AI
ChatCompletions	Traduccion completa Anthropic a 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 a API de Responses de OpenAI	Suscripciones ChatGPT/Codex

Que se traduce

Traduccion de solicitudes (Anthropic a OpenAI)

Anthropic	OpenAI
Campo `system`	Mensaje de sistema en el array `messages`
Bloques `messages[].content` (text, image, tool_use, tool_result)	`messages[].content` + `tool_calls`
Array `tools` (JSON Schema con `input_schema`)	Array `tools` (formato funcion con `parameters`)
`tool_choice` (`auto`, `any`, `{name}`)	`tool_choice` (`auto`, `required`, `{function: {name}}`)
`max_tokens`	`max_tokens` (limitado por el ajuste `max_tokens` del perfil si se establece)
`temperature`, `top_p`	Mapeo directo (eliminados si `strip_params` coincide)

Traduccion de respuestas (OpenAI a Anthropic)

OpenAI	Anthropic
`choices[0].message.content`	Bloques `content` (type: text)
`choices[0].message.tool_calls`	Bloques `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`

Compatibilidad de nombres de herramientas

Claude Code puede generar nombres de herramientas que superan 64 caracteres (por ejemplo, mcp__server-name__very-long-tool-name-that-exceeds-the-limit). OpenAI y muchos proveedores imponen un limite de 64 caracteres.

Claudex automaticamente:

Trunca nombres que superan 64 caracteres en las solicitudes salientes
Construye una tabla de mapeo de nombres truncados a nombres originales
Restaura los nombres originales en las respuestas del proveedor

Este viaje de ida y vuelta es completamente transparente.

Traduccion en streaming

Claudex soporta completamente el streaming SSE (Server-Sent Events), traduciendo fragmentos del stream de OpenAI a eventos del stream de Anthropic en tiempo real:

OpenAI SSE	Anthropic SSE
Primer fragmento	`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`

El traductor de streaming mantiene una maquina de estados para gestionar correctamente la acumulacion de llamadas a herramientas y los limites de bloques de contenido.

Soporte para Azure OpenAI

Azure OpenAI usa un esquema diferente de autenticacion y URLs:

Autenticacion: cabecera api-key en lugar de Authorization: Bearer
Formato de URL: https://{resource}.openai.azure.com/openai/deployments/{deployment}
Version de API: obligatoria via query_params

Claudex detecta automaticamente Azure comprobando si base_url contiene openai.azure.com y ajusta la autenticacion correspondentemente.

Proveedores soportados

Proveedor	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`
ChatGPT/Codex sub	OpenAIResponses	`https://chatgpt.com/backend-api/codex`

Endpoint de modelos

El proxy expone un endpoint /v1/models que lista todos los perfiles habilitados. Cada entrada incluye campos personalizados:

x-claudex-profile: nombre del perfil
x-claudex-provider: tipo de proveedor (anthropic, openai-compatible, openai-responses)

Claude Code consulta este endpoint para descubrir los modelos disponibles.

Gestion del proxy

# Iniciar el proxy como daemon
claudex proxy start -d

# Comprobar el estado del proxy
claudex proxy status

# Detener el daemon del proxy
claudex proxy stop

# Iniciar en un puerto personalizado
claudex proxy start -p 8080

Cuando ejecutas claudex run <profile>, el proxy se inicia automaticamente en segundo plano si no esta ya en ejecucion.