Skip to content

README.es.md

Latest commit

 

History

History
306 lines (256 loc) · 13.5 KB

README.es.md

File metadata and controls

306 lines (256 loc) · 13.5 KB

Claudex

Gestor multi-instancia de Claude Code con proxy de traducción inteligente

CI Release Licencia Última versión

Documentación

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Русский | Français | Português do Brasil | Español | Italiano | Deutsch | Polski

Claudex es un proxy unificado que permite a Claude Code trabajar de forma transparente con múltiples proveedores de IA mediante traducción automática de protocolos.

Características

  • Proxy multi-proveedor — Reenvío directo DirectAnthropic + traducción Anthropic <-> OpenAI Chat Completions + traducción Anthropic <-> Responses API
  • Más de 20 proveedores — Anthropic, OpenRouter, Grok, OpenAI, DeepSeek, Kimi, GLM, Groq, Mistral, Together AI, Perplexity, Cerebras, Azure OpenAI, Google Vertex AI, Ollama, LM Studio y más
  • Traducción en streaming — Traducción completa de flujos SSE con soporte para llamadas a herramientas
  • Circuit breaker + conmutación por error — Fallback automático a proveedores de respaldo con umbrales configurables
  • Enrutamiento inteligente — Enrutamiento automático basado en intención mediante clasificador local
  • Motor de contexto — Compresión de conversaciones, compartición entre perfiles, RAG local con embeddings
  • Suscripciones OAuth — ChatGPT/Codex, Claude Max, GitHub Copilot, GitLab Duo, Google Gemini, Qwen, Kimi
  • Conjuntos de configuración — Instala y gestiona conjuntos de configuración reutilizables de Claude Code desde repositorios git
  • Panel TUI — Estado de perfiles en tiempo real, métricas, registros y lanzamiento rápido
  • Actualización automática — claudex update descarga la última versión desde GitHub

Instalación

# Una línea (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/StringKe/claudex/main/install.sh | bash

# Desde el código fuente
cargo install --git https://github.com/StringKe/claudex

# O descarga desde GitHub Releases
# https://github.com/StringKe/claudex/releases

Requisitos del sistema

  • macOS (Intel / Apple Silicon) o Linux (x86_64 / ARM64)
  • Claude Code instalado
  • Windows: descarga el binario precompilado desde Releases

Inicio rápido

# 1. Inicializar la configuración
claudex config init

# 2. Agregar un perfil de proveedor de forma interactiva
claudex profile add

# 3. Probar la conectividad
claudex profile test all

# 4. Ejecutar Claude Code con un proveedor específico
claudex run grok

# 5. O usar el enrutamiento inteligente para seleccionar automáticamente el mejor proveedor
claudex run auto

Cómo funciona

claudex run openrouter-claude
    │
    ├── Iniciar proxy (si no está en ejecución) → 127.0.0.1:13456
    │
    └── exec claude con variables de entorno:
        ANTHROPIC_BASE_URL=http://127.0.0.1:13456/proxy/openrouter-claude
        ANTHROPIC_AUTH_TOKEN=claudex-passthrough
        ANTHROPIC_MODEL=anthropic/claude-sonnet-4
        ANTHROPIC_DEFAULT_HAIKU_MODEL=...
        ANTHROPIC_DEFAULT_SONNET_MODEL=...
        ANTHROPIC_DEFAULT_OPUS_MODEL=...

El proxy intercepta las solicitudes y gestiona la traducción de protocolos:

  • DirectAnthropic (Anthropic, MiniMax, Vertex AI) → reenvío con las cabeceras correctas
  • OpenAICompatible (Grok, OpenAI, DeepSeek, etc.) → Anthropic → OpenAI Chat Completions → traduce la respuesta de vuelta
  • OpenAIResponses (suscripciones ChatGPT/Codex) → Anthropic → Responses API → traduce la respuesta de vuelta

Compatibilidad de proveedores

Proveedor Tipo Traducción Autenticación Modelo de ejemplo
Anthropic DirectAnthropic Ninguna API Key claude-sonnet-4-20250514
MiniMax DirectAnthropic Ninguna API Key claude-sonnet-4-20250514
OpenRouter OpenAICompatible Anthropic <-> OpenAI API Key anthropic/claude-sonnet-4
Grok (xAI) OpenAICompatible Anthropic <-> OpenAI API Key grok-3-beta
OpenAI OpenAICompatible Anthropic <-> OpenAI API Key gpt-4o
DeepSeek OpenAICompatible Anthropic <-> OpenAI API Key deepseek-chat
Kimi OpenAICompatible Anthropic <-> OpenAI API Key kimi-k2-0905-preview
GLM (Zhipu) OpenAICompatible Anthropic <-> OpenAI API Key glm-4-plus
Groq OpenAICompatible Anthropic <-> OpenAI API Key llama-3.3-70b
Mistral OpenAICompatible Anthropic <-> OpenAI API Key mistral-large-latest
Together AI OpenAICompatible Anthropic <-> OpenAI API Key meta-llama/...
Perplexity OpenAICompatible Anthropic <-> OpenAI API Key sonar-pro
Cerebras OpenAICompatible Anthropic <-> OpenAI API Key llama-3.3-70b
Azure OpenAI OpenAICompatible Anthropic <-> OpenAI cabecera api-key gpt-4o
Google Vertex AI DirectAnthropic Ninguna Bearer (gcloud) claude-sonnet-4@...
Ollama OpenAICompatible Anthropic <-> OpenAI Ninguna qwen2.5:72b
LM Studio OpenAICompatible Anthropic <-> OpenAI Ninguna modelo local
Suscripción ChatGPT/Codex OpenAIResponses Anthropic <-> Responses OAuth (PKCE/Device) gpt-5.3-codex
Claude Max sub DirectAnthropic Ninguna OAuth (archivo) claude-sonnet-4
GitHub Copilot OpenAICompatible Anthropic <-> OpenAI OAuth (Device+Bearer) gpt-4o
GitLab Duo OpenAICompatible Anthropic <-> OpenAI GITLAB_TOKEN claude-sonnet-4

Configuración

Claudex busca archivos de configuración en este orden:

  1. Variable de entorno $CLAUDEX_CONFIG
  2. ./claudex.toml o ./claudex.yaml (directorio actual)
  3. ./.claudex/config.toml
  4. Directorios padre (hasta 10 niveles)
  5. ~/.config/claudex/config.toml (global, recomendado)

Admite los formatos TOML y YAML. Consulta config.example.toml para la referencia completa.

Referencia de CLI

Comando Descripción
claudex run <profile> Ejecutar Claude Code con un proveedor específico
claudex run auto Enrutamiento inteligente — selección automática del mejor proveedor
claudex run <profile> -m <model> Sobreescribir el modelo para una sesión
claudex profile list Listar todos los perfiles configurados
claudex profile add Asistente interactivo de configuración de perfiles
claudex profile show <name> Mostrar detalles del perfil
claudex profile remove <name> Eliminar un perfil
claudex profile test <name|all> Probar la conectividad del proveedor
claudex proxy start [-p port] [-d] Iniciar el proxy (opcionalmente como demonio)
claudex proxy stop Detener el demonio del proxy
claudex proxy status Mostrar el estado del proxy
claudex dashboard Lanzar el panel TUI
claudex config show [--raw] [--json] Mostrar la configuración cargada
claudex config init [--yaml] Crear configuración en el directorio actual
claudex config edit [--global] Abrir la configuración en $EDITOR
claudex config validate [--connectivity] Validar la configuración
claudex config get <key> Obtener un valor de configuración
claudex config set <key> <value> Establecer un valor de configuración
claudex config export --format <fmt> Exportar la configuración (json/toml/yaml)
claudex update [--check] Actualización automática desde GitHub Releases
claudex auth login <provider> Inicio de sesión OAuth
claudex auth login github --enterprise-url <domain> GitHub Enterprise Copilot
claudex auth status Mostrar el estado del token OAuth
claudex auth logout <profile> Eliminar el token OAuth
claudex auth refresh <profile> Forzar la renovación del token OAuth
claudex sets add <source> [--global] Instalar un conjunto de configuración
claudex sets remove <name> Eliminar un conjunto de configuración
claudex sets list [--global] Listar los conjuntos instalados
claudex sets update [name] Actualizar los conjuntos a la última versión

Suscripciones OAuth

Usa suscripciones existentes en lugar de claves de API:

# Suscripción de ChatGPT (detecta automáticamente las credenciales del Codex CLI)
claudex auth login chatgpt --profile codex-sub

# ChatGPT forzar inicio de sesión en el navegador
claudex auth login chatgpt --profile codex-sub --force

# ChatGPT sin interfaz gráfica (SSH/sin navegador)
claudex auth login chatgpt --profile codex-sub --force --headless

# GitHub Copilot
claudex auth login github --profile copilot

# GitHub Copilot Enterprise
claudex auth login github --profile copilot-ent --enterprise-url company.ghe.com

# GitLab Duo (lee la variable de entorno GITLAB_TOKEN)
claudex auth login gitlab --profile gitlab-duo

# Comprobar estado
claudex auth status

# Ejecutar con suscripción
claudex run codex-sub

Compatible con: claude, chatgpt/openai, google, qwen, kimi, github/copilot, gitlab

Asignación de ranuras de modelos

Mapea el selector /model de Claude Code (haiku/sonnet/opus) a los modelos de cualquier proveedor:

[[profiles]]
name = "openrouter-deepseek"
provider_type = "OpenAICompatible"
base_url = "https://openrouter.ai/api/v1"
api_key = "sk-or-..."
default_model = "deepseek/deepseek-chat-v3-0324"

[profiles.models]
haiku = "deepseek/deepseek-chat-v3-0324"
sonnet = "deepseek/deepseek-chat-v3-0324"
opus = "deepseek/deepseek-r1"

Arquitectura

src/
├── main.rs
├── cli.rs
├── update.rs
├── util.rs
├── config/
│   ├── mod.rs          # Descubrimiento y análisis de configuración (figment)
│   ├── cmd.rs          # Subcomandos config get/set/export/validate
│   └── profile.rs      # CRUD de perfiles + prueba de conectividad
├── process/
│   ├── mod.rs
│   ├── launch.rs       # Lanzador del proceso de Claude
│   └── daemon.rs       # Archivo PID + gestión de procesos
├── oauth/
│   ├── mod.rs          # AuthType, OAuthProvider, OAuthToken
│   ├── source.rs       # Capa 1: fuentes de credenciales (env/archivo/keyring)
│   ├── exchange.rs     # Capa 2: intercambio de tokens (PKCE/device code/refresh)
│   ├── manager.rs      # Capa 3: caché + deduplicación concurrente + reintento 401
│   ├── handler.rs      # Trait OAuthProviderHandler
│   ├── providers.rs    # Lógica CLI de inicio de sesión/actualización/estado
│   ├── server.rs       # Servidor de callback OAuth + sondeo de device code
│   └── token.rs        # Re-exportaciones
├── proxy/
│   ├── mod.rs          # Servidor Axum + ProxyState
│   ├── handler.rs      # Enrutamiento de solicitudes + circuit breaker + reintento 401
│   ├── adapter/        # Adaptadores específicos por proveedor
│   │   ├── mod.rs      # Trait ProviderAdapter + fábrica
│   │   ├── direct.rs   # DirectAnthropic (reenvío directo)
│   │   ├── chat_completions.rs  # OpenAI Chat Completions
│   │   └── responses.rs         # OpenAI Responses API
│   ├── translate/      # Traducción de protocolos
│   │   ├── chat_completions.rs
│   │   ├── chat_completions_stream.rs
│   │   ├── responses.rs
│   │   └── responses_stream.rs
│   ├── context_engine.rs
│   ├── fallback.rs     # Circuit breaker
│   ├── health.rs
│   ├── metrics.rs
│   ├── models.rs
│   ├── error.rs
│   └── util.rs
├── router/
│   ├── mod.rs
│   └── classifier.rs
├── context/
│   ├── mod.rs
│   ├── compression.rs
│   ├── sharing.rs
│   └── rag.rs
├── sets/               # Gestión de conjuntos de configuración
│   ├── mod.rs
│   ├── schema.rs
│   ├── source.rs
│   ├── install.rs
│   ├── lock.rs
│   ├── conflict.rs
│   └── mcp.rs
├── terminal/           # Detección de terminal + hipervínculos
│   ├── mod.rs
│   ├── detect.rs
│   ├── osc8.rs
│   └── pty.rs
└── tui/
    ├── mod.rs
    ├── dashboard.rs
    ├── input.rs
    └── widgets.rs

Licencia

MIT