Configuracao

Descoberta do Arquivo de Configuracao

O Claudex usa o figment para configuracao em camadas. As fontes sao mescladas nesta ordem (fontes posteriores sobrescrevem as anteriores):

Valores padrao programaticos (fallbacks embutidos)
Configuracao global (~/.config/claudex/config.toml ou config.yaml)
Configuracao do projeto (claudex.toml ou claudex.yaml no diretorio atual ou diretorios pai ate 10 niveis, ou $CLAUDEX_CONFIG)
Variaveis de ambiente (prefixo CLAUDEX_, __ como separador)

Os formatos TOML e YAML sao suportados. O formato do arquivo e detectado pela extensao (.toml ou .yaml/.yml).

# Mostrar caminho do config carregado e todos os locais de busca
claudex config show

# Mostrar apenas o caminho do arquivo de configuracao
claudex config path

# Criar um novo config no diretorio atual
claudex config init

# Recriar config a partir do config.example.toml
claudex config recreate

# Abrir config no seu $EDITOR
claudex config edit

# Validar sintaxe do config e referencias de profiles
claudex config validate

# Obter um valor especifico de configuracao
claudex config get proxy_port

# Definir um valor especifico de configuracao
claudex config set proxy_port 8080

# Exportar configuracao atual para stdout
claudex config export

Configuracoes Globais

# Caminho para o binario claude (padrao: "claude" do PATH)
# claude_binary = "/usr/local/bin/claude"

# Configuracoes do proxy
proxy_port = 13456
proxy_host = "127.0.0.1"

# Nivel de log: trace, debug, info, warn, error
log_level = "info"

# Hyperlinks no terminal (OSC 8): "auto" | true | false
# "auto" detecta suporte do terminal; true/false forca ligado/desligado
hyperlinks = "auto"

# Aliases de modelo (abreviacao → nome completo do modelo)
[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"

Profiles

Cada profile representa uma conexao com um provedor de IA. Existem tres tipos de provedor:

DirectAnthropic

Para provedores que suportam nativamente a API Anthropic Messages. As requisicoes sao encaminhadas com modificacoes minimas.

[[profiles]]
name = "anthropic"
provider_type = "DirectAnthropic"
base_url = "https://api.anthropic.com"
api_key = "sk-ant-..."
default_model = "claude-sonnet-4-20250514"
priority = 100
enabled = true

Provedores compativeis: Anthropic, MiniMax, Google Vertex AI

OpenAICompatible

Para provedores que usam a API OpenAI Chat Completions. O Claudex traduz automaticamente entre os protocolos Anthropic e OpenAI.

[[profiles]]
name = "grok"
provider_type = "OpenAICompatible"
base_url = "https://api.x.ai/v1"
api_key = "xai-..."
default_model = "grok-3-beta"
backup_providers = ["deepseek"]
priority = 100
enabled = true

Provedores compativeis: Grok (xAI), OpenAI, DeepSeek, Kimi/Moonshot, GLM (Zhipu), OpenRouter, Groq, Mistral, Together AI, Perplexity, Cerebras, Azure OpenAI, GitHub Copilot, GitLab Duo, Ollama, vLLM, LM Studio

OpenAIResponses

Para provedores que usam a API OpenAI Responses (ex: assinaturas ChatGPT/Codex). O Claudex traduz entre a API Anthropic Messages e a API OpenAI Responses.

[[profiles]]
name = "codex-sub"
provider_type = "OpenAIResponses"
base_url = "https://chatgpt.com/backend-api/codex"
default_model = "gpt-5.3-codex"
auth_type = "oauth"
oauth_provider = "openai"

Provedores compativeis: Assinaturas ChatGPT/Codex (via Codex CLI)

Campos do Profile

Campo	Padrao	Descricao
`name`	obrigatorio	Identificador unico do profile
`provider_type`	`DirectAnthropic`	`DirectAnthropic`, `OpenAICompatible` ou `OpenAIResponses`
`base_url`	obrigatorio	Endpoint da API do provedor
`api_key`	`""`	Chave API (texto simples)
`api_key_keyring`	—	Ler chave API do keychain do SO
`default_model`	obrigatorio	Modelo padrao a ser usado
`auth_type`	`"api-key"`	`"api-key"` ou `"oauth"`
`oauth_provider`	—	Provedor OAuth (`claude`, `openai`, `google`, `qwen`, `kimi`, `github`, `gitlab`). Obrigatorio quando `auth_type = "oauth"`
`backup_providers`	`[]`	Nomes de profiles para failover
`custom_headers`	`{}`	Headers HTTP extras
`extra_env`	`{}`	Variaveis de ambiente extras para o Claude
`priority`	`100`	Prioridade para roteamento inteligente
`enabled`	`true`	Se este profile esta ativo
`max_tokens`	—	Limite de tokens de saida enviados ao provedor (opcional)
`strip_params`	`"auto"`	`"auto"`, `"none"` ou `["temperature", "top_p"]`. Detecta automaticamente parametros nao suportados (ex: endpoint ChatGPT Codex)
`[profiles.query_params]`	`{}`	Parametros de query da URL (ex: Azure `api-version`)
`[profiles.models]`	—	Tabela de mapeamento de slots de modelo (`haiku`, `sonnet`, `opus`)

Configuracao Interativa

A maneira mais facil de adicionar um profile e usando o assistente interativo:

claudex profile add

Ele guia voce pela selecao de provedor, entrada de chave API (com armazenamento opcional no keyring), selecao de modelo e teste de conectividade.

Integracao com Keyring

Armazene chaves API de forma segura no keychain do SO em vez de texto simples no config:

[[profiles]]
name = "grok"
api_key_keyring = "grok-api-key"   # le do keychain do SO

Backends suportados:

macOS: Keychain
Linux: Secret Service (GNOME Keyring / KDE Wallet)

Autenticacao OAuth por Assinatura

Em vez de chaves API, voce pode autenticar com sua assinatura existente do provedor via OAuth. Isso e util se voce tem um plano Claude Pro/Team, ChatGPT Plus ou outra assinatura.

Configuracao

Defina o auth_type do profile como "oauth" e especifique o oauth_provider:

[[profiles]]
name = "codex-sub"
provider_type = "OpenAIResponses"
base_url = "https://chatgpt.com/backend-api/codex"
default_model = "gpt-5.3-codex"
auth_type = "oauth"
oauth_provider = "openai"

Faca login com o comando auth:

claudex auth login openai

Verifique seu status de autenticacao:

claudex auth status

Provedores Suportados

Provedor	`oauth_provider`	Origem do Token
Claude	`claude`	Le de `~/.claude/.credentials.json` (configuracao nativa do Claude Code)
ChatGPT	`openai`	PKCE via navegador ou Device Code, fallback para `~/.codex/auth.json` (Codex CLI)
Google	`google`	Le das credenciais do Gemini CLI
Qwen	`qwen`	Device Code flow
Kimi	`kimi`	Le das credenciais do Kimi CLI
GitHub	`github`	Device Code flow, fallback para `~/.config/github-copilot/`
GitLab	`gitlab`	Variavel de ambiente `GITLAB_TOKEN`

Para detalhes sobre o fluxo OAuth de cada provedor, consulte Assinaturas OAuth.

Modo Gateway Auth

Ao usar profiles OAuth, o Claudex define ANTHROPIC_AUTH_TOKEN (e nao ANTHROPIC_API_KEY) ao lancar o Claude Code. Isso evita conflitos com o mecanismo de login por assinatura do proprio Claude Code, que usa ANTHROPIC_API_KEY internamente.

O proxy atualiza automaticamente os tokens OAuth antes de expirarem. Voce tambem pode atualizar manualmente com:

claudex auth refresh openai

Parametros de Query

Alguns provedores exigem parametros de query na URL (ex: api-version do Azure OpenAI). Use a tabela [profiles.query_params]:

[[profiles]]
name = "azure-openai"
provider_type = "OpenAICompatible"
base_url = "https://YOUR_RESOURCE.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT"
api_key = "YOUR_AZURE_KEY"
default_model = "gpt-4o"

[profiles.query_params]
api-version = "2024-12-01-preview"

O Claudex adiciona estes parametros a cada URL de requisicao do profile. O Azure OpenAI e detectado automaticamente quando a base_url contem openai.azure.com e usa o header api-key para autenticacao em vez de Authorization: Bearer.

Remocao de Parametros

Alguns provedores nao suportam certos parametros (ex: o endpoint ChatGPT Codex rejeita temperature, top_p). O campo strip_params controla quais parametros sao removidos antes do envio:

strip_params = "auto"       # detecta e remove automaticamente parametros nao suportados (padrao)
strip_params = "none"       # envia todos os parametros como estao
strip_params = ["temperature", "top_p", "top_k"]  # remove parametros especificos

Quando definido como "auto", o Claudex detecta endpoints conhecidos (ex: chatgpt.com) e remove parametros que causariam erros.

Mapeamento de Slots de Modelo

O Claude Code tem um seletor /model embutido com tres slots: haiku, sonnet e opus. Consulte Mapeamento de Slots de Modelo para detalhes.

Compatibilidade de Nomes de Ferramentas

Alguns provedores (notadamente OpenAI) impoem um limite de 64 caracteres em nomes de ferramentas (funcoes). O Claude Code pode gerar nomes de ferramentas que excedem esse limite.

O Claudex trunca automaticamente nomes de ferramentas com mais de 64 caracteres ao enviar requisicoes para provedores compativeis com OpenAI e restaura de forma transparente os nomes originais ao processar respostas. Essa traducao de ida e volta e totalmente transparente.

Modo Nao-Interativo

O Claudex suporta execucao one-shot (nao-interativa) para uso em pipelines CI/CD, scripts e automacao:

# Imprime resposta e encerra
claudex run grok "Explain this codebase" --print

# Pula todas as solicitacoes de permissao (para pipelines totalmente automatizados)
claudex run grok "Fix lint errors" --print --dangerously-skip-permissions

No modo nao-interativo, os logs sao escritos em arquivos de log por instancia em ~/Library/Caches/claudex/proxy-{timestamp}-{pid}.log em vez do stderr, mantendo a saida stdout limpa para piping e automacao.

Hyperlinks no Terminal

O Claudex suporta hyperlinks clicaveis OSC 8 na saida do terminal. Consulte Hyperlinks no Terminal para detalhes.

# "auto" detecta suporte do terminal; true/false forca ligado/desligado
hyperlinks = "auto"

Conjuntos de Configuracao

Instale pacotes reutilizaveis de regras, skills e servidores MCP. Consulte Conjuntos de Configuracao para detalhes.

claudex sets add ./my-set
claudex sets list

Exemplo Completo

Consulte config.example.toml para um arquivo de configuracao completo com todos os provedores e opcoes.

Para instrucoes passo a passo de configuracao de cada provedor (incluindo links para chaves API e fluxos OAuth), consulte o Guia de Configuracao de Provedores.