Skip to content

README.pt-BR.md

Latest commit

 

History

History
306 lines (256 loc) · 13.3 KB

README.pt-BR.md

File metadata and controls

306 lines (256 loc) · 13.3 KB

Claudex

Gerenciador multi-instância do Claude Code com proxy de tradução inteligente

CI Release License Latest Release

Documentação

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

Claudex é um proxy unificado que permite ao Claude Code trabalhar de forma transparente com múltiplos provedores de IA por meio de tradução automática de protocolos.

Funcionalidades

  • Proxy multi-provedor — Passthrough DirectAnthropic + tradução Anthropic <-> OpenAI Chat Completions + tradução Anthropic <-> Responses API
  • Mais de 20 provedores — Anthropic, OpenRouter, Grok, OpenAI, DeepSeek, Kimi, GLM, Groq, Mistral, Together AI, Perplexity, Cerebras, Azure OpenAI, Google Vertex AI, Ollama, LM Studio e mais
  • Tradução de streaming — Tradução completa de stream SSE com suporte a chamadas de ferramentas
  • Circuit breaker + failover — Fallback automático para provedores de backup com thresholds configuráveis
  • Roteamento inteligente — Roteamento automático baseado em intenção via classificador local
  • Motor de contexto — Compressão de conversa, compartilhamento entre perfis, RAG local com embeddings
  • Assinaturas OAuth — ChatGPT/Codex, Claude Max, GitHub Copilot, GitLab Duo, Google Gemini, Qwen, Kimi
  • Conjuntos de configuração — Instale e gerencie conjuntos reutilizáveis de configuração do Claude Code a partir de repositórios git
  • Dashboard TUI — Saúde dos perfis em tempo real, métricas, logs e inicialização rápida
  • Auto-atualização — claudex update baixa a versão mais recente do GitHub

Instalação

# Instalação em uma linha (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/StringKe/claudex/main/install.sh | bash

# A partir do código-fonte
cargo install --git https://github.com/StringKe/claudex

# Ou baixe diretamente do GitHub Releases
# https://github.com/StringKe/claudex/releases

Requisitos do Sistema

  • macOS (Intel / Apple Silicon) ou Linux (x86_64 / ARM64)
  • Claude Code instalado
  • Windows: baixe o binário pré-compilado em Releases

Início Rápido

# 1. Inicializar configuração
claudex config init

# 2. Adicionar um perfil de provedor interativamente
claudex profile add

# 3. Testar conectividade
claudex profile test all

# 4. Executar o Claude Code com um provedor específico
claudex run grok

# 5. Ou usar roteamento inteligente para selecionar automaticamente o melhor provedor
claudex run auto

Como Funciona

claudex run openrouter-claude
    │
    ├── Inicia proxy (se não estiver em execução) → 127.0.0.1:13456
    │
    └── executa claude com variáveis de ambiente:
        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=...

O proxy intercepta as requisições e realiza a tradução de protocolo:

  • DirectAnthropic (Anthropic, MiniMax, Vertex AI) → encaminha com os headers corretos
  • OpenAICompatible (Grok, OpenAI, DeepSeek, etc.) → Anthropic → OpenAI Chat Completions → traduz resposta de volta
  • OpenAIResponses (assinaturas ChatGPT/Codex) → Anthropic → Responses API → traduz resposta de volta

Compatibilidade de Provedores

Provedor Tipo Tradução Autenticação Modelo de Exemplo
Anthropic DirectAnthropic Nenhuma API Key claude-sonnet-4-20250514
MiniMax DirectAnthropic Nenhuma 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 header api-key gpt-4o
Google Vertex AI DirectAnthropic Nenhuma Bearer (gcloud) claude-sonnet-4@...
Ollama OpenAICompatible Anthropic <-> OpenAI Nenhuma qwen2.5:72b
LM Studio OpenAICompatible Anthropic <-> OpenAI Nenhuma modelo local
Assinatura ChatGPT/Codex OpenAIResponses Anthropic <-> Responses OAuth (PKCE/Device) gpt-5.3-codex
Assinatura Claude Max DirectAnthropic Nenhuma OAuth (arquivo) claude-sonnet-4
GitHub Copilot OpenAICompatible Anthropic <-> OpenAI OAuth (Device+Bearer) gpt-4o
GitLab Duo OpenAICompatible Anthropic <-> OpenAI GITLAB_TOKEN claude-sonnet-4

Configuração

O Claudex busca arquivos de configuração na seguinte ordem:

  1. Variável de ambiente $CLAUDEX_CONFIG
  2. ./claudex.toml ou ./claudex.yaml (diretório atual)
  3. ./.claudex/config.toml
  4. Diretórios pai (até 10 níveis)
  5. ~/.config/claudex/config.toml (global, recomendado)

Suporta os formatos TOML e YAML. Consulte config.example.toml para a referência completa.

Referência de Comandos CLI

Comando Descrição
claudex run <profile> Executar o Claude Code com um provedor específico
claudex run auto Roteamento inteligente — seleciona automaticamente o melhor provedor
claudex run <profile> -m <model> Sobrescrever o modelo para uma sessão
claudex profile list Listar todos os perfis configurados
claudex profile add Assistente interativo de configuração de perfil
claudex profile show <name> Exibir detalhes do perfil
claudex profile remove <name> Remover um perfil
claudex profile test <name|all> Testar conectividade do provedor
claudex proxy start [-p port] [-d] Iniciar proxy (opcionalmente como daemon)
claudex proxy stop Parar daemon do proxy
claudex proxy status Exibir status do proxy
claudex dashboard Abrir dashboard TUI
claudex config show [--raw] [--json] Exibir configuração carregada
claudex config init [--yaml] Criar configuração no diretório atual
claudex config edit [--global] Abrir configuração no $EDITOR
claudex config validate [--connectivity] Validar configuração
claudex config get <key> Obter um valor de configuração
claudex config set <key> <value> Definir um valor de configuração
claudex config export --format <fmt> Exportar configuração (json/toml/yaml)
claudex update [--check] Auto-atualização a partir do GitHub Releases
claudex auth login <provider> Login OAuth
claudex auth login github --enterprise-url <domain> GitHub Enterprise Copilot
claudex auth status Exibir status do token OAuth
claudex auth logout <profile> Remover token OAuth
claudex auth refresh <profile> Forçar renovação do token OAuth
claudex sets add <source> [--global] Instalar um conjunto de configuração
claudex sets remove <name> Remover um conjunto de configuração
claudex sets list [--global] Listar conjuntos instalados
claudex sets update [name] Atualizar conjuntos para a versão mais recente

Assinaturas OAuth

Use assinaturas existentes em vez de chaves de API:

# Assinatura ChatGPT (detecta automaticamente credenciais existentes do Codex CLI)
claudex auth login chatgpt --profile codex-sub

# ChatGPT com login forçado pelo navegador
claudex auth login chatgpt --profile codex-sub --force

# ChatGPT sem interface gráfica (SSH/sem 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 (lê a variável de ambiente GITLAB_TOKEN)
claudex auth login gitlab --profile gitlab-duo

# Verificar status
claudex auth status

# Executar com assinatura
claudex run codex-sub

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

Mapeamento de Slots de Modelo

Mapeie o seletor /model do Claude Code (haiku/sonnet/opus) para os modelos de qualquer provedor:

[[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"

Arquitetura

src/
├── main.rs
├── cli.rs
├── update.rs
├── util.rs
├── config/
│   ├── mod.rs          # Descoberta e parsing de configuração (figment)
│   ├── cmd.rs          # Subcomandos config get/set/export/validate
│   └── profile.rs      # CRUD de perfil + teste de conectividade
├── process/
│   ├── mod.rs
│   ├── launch.rs       # Inicializador do processo Claude
│   └── daemon.rs       # Arquivo PID + gerenciamento de processos
├── oauth/
│   ├── mod.rs          # AuthType, OAuthProvider, OAuthToken
│   ├── source.rs       # Camada 1: fontes de credenciais (env/arquivo/keyring)
│   ├── exchange.rs     # Camada 2: troca de tokens (PKCE/device code/refresh)
│   ├── manager.rs      # Camada 3: cache + deduplicação concorrente + retry 401
│   ├── handler.rs      # trait OAuthProviderHandler
│   ├── providers.rs    # Lógica CLI de login/refresh/status
│   ├── server.rs       # Servidor de callback OAuth + polling de device code
│   └── token.rs        # Re-exports
├── proxy/
│   ├── mod.rs          # Servidor Axum + ProxyState
│   ├── handler.rs      # Roteamento de requisições + circuit breaker + retry 401
│   ├── adapter/        # Adaptadores específicos por provedor
│   │   ├── mod.rs      # trait ProviderAdapter + factory
│   │   ├── direct.rs   # DirectAnthropic (passthrough)
│   │   ├── chat_completions.rs  # OpenAI Chat Completions
│   │   └── responses.rs         # OpenAI Responses API
│   ├── translate/      # Tradução de protocolo
│   │   ├── 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/               # Gerenciamento de conjuntos de configuração
│   ├── mod.rs
│   ├── schema.rs
│   ├── source.rs
│   ├── install.rs
│   ├── lock.rs
│   ├── conflict.rs
│   └── mcp.rs
├── terminal/           # Detecção de terminal + hyperlinks
│   ├── mod.rs
│   ├── detect.rs
│   ├── osc8.rs
│   └── pty.rs
└── tui/
    ├── mod.rs
    ├── dashboard.rs
    ├── input.rs
    └── widgets.rs

Licença

MIT