Referencia de Configuracao

Localizacao do Arquivo de Configuracao

O Claudex usa configuracao em camadas via figment. As fontes sao mescladas nesta ordem (posterior sobrescreve anterior):

1. Valores padrao programaticos
2. Configuracao global (~/.config/claudex/config.toml ou .yaml)
3. Configuracao do projeto (claudex.toml/.claudex/config.toml no CWD ou diretorios pai, ou $CLAUDEX_CONFIG)
4. Variaveis de ambiente (prefixo CLAUDEX_, separador __)

Os formatos TOML e YAML sao suportados.

Consulte Configuracao para detalhes de configuracao.

Configuracoes Globais

# Caminho para o binario claude (padrao: "claude" do PATH)
claude_binary = "claude"

# Porta de escuta do servidor proxy
proxy_port = 13456

# Endereco de escuta do servidor proxy
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
hyperlinks = "auto"

Campo	Tipo	Padrao	Descricao
claude_binary	string	"claude"	Caminho para o binario da CLI do Claude Code
proxy_port	integer	13456	Porta em que o proxy de traducao escuta
proxy_host	string	"127.0.0.1"	Endereco ao qual o proxy se vincula
log_level	string	"info"	Nivel minimo de log
hyperlinks	string/bool	"auto"	Hyperlinks no terminal: "auto" (detectar), true (forcar ativacao), false (forcar desativacao)

Aliases de Modelo

Defina nomes abreviados para identificadores de modelos:

[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"
claude = "claude-sonnet-4-20250514"

Use aliases com -m:

claudex run grok -m grok3

Configuracao de Profile

[[profiles]]
name = "grok"
provider_type = "OpenAICompatible"
base_url = "https://api.x.ai/v1"
api_key = "xai-..."
# api_key_keyring = "grok-api-key"
default_model = "grok-3-beta"
auth_type = "api-key"              # "api-key" (padrao) ou "oauth"
# oauth_provider = "openai"        # obrigatorio quando auth_type = "oauth"
backup_providers = ["deepseek"]
custom_headers = {}
extra_env = {}
priority = 100
enabled = true
max_tokens = 16384                  # opcional: limitar tokens de saida
strip_params = "auto"               # "auto" | "none" | ["temperature", "top_p"]

# Parametros de query da URL (ex: Azure api-version)
[profiles.query_params]
# api-version = "2024-12-01-preview"

# Mapeamento de slots de modelo (opcional)
[profiles.models]
haiku = "grok-3-mini-beta"
sonnet = "grok-3-beta"
opus = "grok-3-beta"

Campo	Tipo	Padrao	Descricao
name	string	obrigatorio	Identificador unico do profile
provider_type	string	"DirectAnthropic"	"DirectAnthropic", "OpenAICompatible" ou "OpenAIResponses"
base_url	string	obrigatorio	URL do endpoint da API do provedor
api_key	string	""	Chave API em texto simples
api_key_keyring	string	—	Nome da entrada no keychain do SO (substitui api_key)
default_model	string	obrigatorio	Identificador do modelo usado por padrao
auth_type	string	"api-key"	Metodo de autenticacao: "api-key" ou "oauth"
oauth_provider	string	—	Nome do provedor OAuth. Um de: claude, openai, google, qwen, kimi, github, gitlab
backup_providers	string[]	[]	Nomes de profiles para failover, tentados em ordem
custom_headers	map	{}	Headers HTTP adicionais enviados com cada requisicao
extra_env	map	{}	Variaveis de ambiente definidas ao iniciar o Claude
priority	integer	100	Peso de prioridade para roteamento inteligente (maior = preferido)
enabled	boolean	true	Se este profile esta ativo
max_tokens	integer	—	Limite de tokens de saida enviados ao provedor. Quando definido, substitui o max_tokens das requisicoes
strip_params	string/array	"auto"	Parametros a remover das requisicoes. "auto" detecta endpoints conhecidos; "none" envia tudo; array remove parametros especificos

Parametros de Query

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

Campo	Tipo	Descricao
query_params	map	Pares chave-valor adicionados como parametros de query da URL em cada requisicao

Usado principalmente para Azure OpenAI (api-version), mas funciona com qualquer provedor.

Mapeamento de Slots de Modelo

A tabela opcional [profiles.models] mapeia os slots do seletor /model do Claude Code para nomes de modelos especificos do provedor. Quando voce muda modelos dentro do Claude Code (ex: /model opus), o Claudex traduz a requisicao para o modelo mapeado.

[profiles.models]
haiku = "grok-3-mini-beta"    # mapeia /model haiku
sonnet = "grok-3-beta"        # mapeia /model sonnet
opus = "grok-3-beta"          # mapeia /model opus

Campo	Tipo	Descricao
haiku	string	Modelo a usar quando o Claude Code seleciona haiku
sonnet	string	Modelo a usar quando o Claude Code seleciona sonnet
opus	string	Modelo a usar quando o Claude Code seleciona opus

Dica

Se um slot nao estiver definido, o default_model do profile e usado como fallback. Os slots tambem sao expostos como variaveis de ambiente: ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL.

Exemplos de Provedores

# Anthropic (DirectAnthropic — sem traducao)
[[profiles]]
name = "anthropic"
provider_type = "DirectAnthropic"
base_url = "https://api.anthropic.com"
api_key = "sk-ant-..."
default_model = "claude-sonnet-4-20250514"

# MiniMax (DirectAnthropic — sem traducao)
[[profiles]]
name = "minimax"
provider_type = "DirectAnthropic"
base_url = "https://api.minimax.io/anthropic"
api_key = "..."
default_model = "claude-sonnet-4-20250514"
backup_providers = ["anthropic"]

# OpenRouter (OpenAICompatible — precisa de traducao)
[[profiles]]
name = "openrouter"
provider_type = "OpenAICompatible"
base_url = "https://openrouter.ai/api/v1"
api_key = "..."
default_model = "anthropic/claude-sonnet-4"

# Grok (OpenAICompatible — precisa de traducao)
[[profiles]]
name = "grok"
provider_type = "OpenAICompatible"
base_url = "https://api.x.ai/v1"
api_key = "xai-..."
default_model = "grok-3-beta"
backup_providers = ["deepseek"]

# OpenAI (OpenAICompatible — precisa de traducao)
[[profiles]]
name = "chatgpt"
provider_type = "OpenAICompatible"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."
default_model = "gpt-4o"

# DeepSeek (OpenAICompatible — precisa de traducao)
[[profiles]]
name = "deepseek"
provider_type = "OpenAICompatible"
base_url = "https://api.deepseek.com"
api_key = "..."
default_model = "deepseek-chat"
backup_providers = ["grok"]

# Kimi / Moonshot (OpenAICompatible — precisa de traducao)
[[profiles]]
name = "kimi"
provider_type = "OpenAICompatible"
base_url = "https://api.moonshot.ai/v1"
api_key = "..."
default_model = "kimi-k2-0905-preview"

# GLM / Zhipu (OpenAICompatible — precisa de traducao)
[[profiles]]
name = "glm"
provider_type = "OpenAICompatible"
base_url = "https://api.z.ai/api/paas/v4"
api_key = "..."
default_model = "glm-4.6"

# Groq (OpenAICompatible — inferencia rapida)
[[profiles]]
name = "groq"
provider_type = "OpenAICompatible"
base_url = "https://api.groq.com/openai/v1"
api_key = "gsk_..."
default_model = "llama-3.3-70b-versatile"

# Mistral AI (OpenAICompatible — precisa de traducao)
[[profiles]]
name = "mistral"
provider_type = "OpenAICompatible"
base_url = "https://api.mistral.ai/v1"
api_key = "..."
default_model = "mistral-large-latest"

# Together AI (OpenAICompatible — precisa de traducao)
[[profiles]]
name = "together"
provider_type = "OpenAICompatible"
base_url = "https://api.together.xyz/v1"
api_key = "..."
default_model = "meta-llama/Llama-3.3-70B-Instruct-Turbo"

# Perplexity (OpenAICompatible — busca online + LLM)
[[profiles]]
name = "perplexity"
provider_type = "OpenAICompatible"
base_url = "https://api.perplexity.ai"
api_key = "pplx-..."
default_model = "sonar-pro"

# Cerebras (OpenAICompatible — inferencia rapida)
[[profiles]]
name = "cerebras"
provider_type = "OpenAICompatible"
base_url = "https://api.cerebras.ai/v1"
api_key = "..."
default_model = "llama-3.3-70b"

# Azure OpenAI (OpenAICompatible — header api-key + 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"

# Google Vertex AI (DirectAnthropic)
[[profiles]]
name = "vertex-ai"
provider_type = "DirectAnthropic"
base_url = "https://us-east5-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/us-east5/publishers/anthropic/models"
api_key = "YOUR_GCLOUD_TOKEN"
default_model = "claude-sonnet-4@20250514"

# Ollama (local, sem chave API)
[[profiles]]
name = "local-qwen"
provider_type = "OpenAICompatible"
base_url = "http://localhost:11434/v1"
api_key = ""
default_model = "qwen2.5:72b"
enabled = false

# vLLM / LM Studio (local)
[[profiles]]
name = "local-llama"
provider_type = "OpenAICompatible"
base_url = "http://localhost:8000/v1"
api_key = ""
default_model = "llama-3.3-70b"
enabled = false

Exemplos de Profiles OAuth

# Claude Max (pula proxy, usa OAuth nativo do Claude de ~/.claude)
[[profiles]]
name = "claude-max"
provider_type = "DirectAnthropic"
base_url = "https://api.claude.ai"
default_model = "claude-sonnet-4-20250514"
auth_type = "oauth"
oauth_provider = "claude"

[profiles.models]
haiku = "claude-haiku-4-20250514"
sonnet = "claude-sonnet-4-20250514"
opus = "claude-opus-4-20250514"

# Assinatura ChatGPT/Codex (OpenAIResponses)
[[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"

[profiles.models]
haiku = "codex-mini-latest"
sonnet = "gpt-5.3-codex"
opus = "gpt-5.3-codex"

# Google Gemini via OAuth
[[profiles]]
name = "gemini-sub"
provider_type = "OpenAICompatible"
base_url = "https://generativelanguage.googleapis.com/v1beta/openai"
default_model = "gemini-2.5-pro"
auth_type = "oauth"
oauth_provider = "google"

# Kimi via OAuth
[[profiles]]
name = "kimi-oauth"
provider_type = "OpenAICompatible"
base_url = "https://api.moonshot.cn/v1"
default_model = "moonshot-v1-128k"
auth_type = "oauth"
oauth_provider = "kimi"

# Qwen via OAuth
[[profiles]]
name = "qwen-oauth"
provider_type = "OpenAICompatible"
base_url = "https://chat.qwen.ai/api"
default_model = "qwen3-235b-a22b"
auth_type = "oauth"
oauth_provider = "qwen"

# GitHub Copilot via OAuth
[[profiles]]
name = "copilot"
provider_type = "OpenAICompatible"
base_url = "https://api.githubcopilot.com"
default_model = "gpt-4o"
auth_type = "oauth"
oauth_provider = "github"

# GitLab Duo via GITLAB_TOKEN
[[profiles]]
name = "gitlab-duo"
provider_type = "OpenAICompatible"
base_url = "https://gitlab.com/api/v4/ai/llm/proxy"
default_model = "claude-sonnet-4-20250514"
auth_type = "oauth"
oauth_provider = "gitlab"

Cuidado

Para o provedor OAuth claude, o Claudex pula o proxy e deixa o Claude Code usar seu proprio OAuth diretamente. Para todos os outros provedores OAuth, o proxy gerencia tokens e refresh.

Roteador Inteligente

[router]
enabled = false
profile = "local-qwen"    # reutilizar base_url + api_key de um profile
model = "qwen2.5:3b"      # substituir modelo (opcional)

Campo	Tipo	Padrao	Descricao
enabled	boolean	false	Habilitar roteamento inteligente
profile	string	""	Nome do profile a reutilizar para classificacao (usa sua base_url + api_key)
model	string	""	Substituicao de modelo para classificacao (padrao: default_model do profile)

Regras de Roteamento

[router.rules]
code = "deepseek"
analysis = "grok"
creative = "chatgpt"
search = "kimi"
math = "deepseek"
default = "grok"

Chave	Descricao
code	Profile para tarefas de programacao
analysis	Profile para analise e raciocinio
creative	Profile para escrita criativa
search	Profile para busca e pesquisa
math	Profile para matematica e logica
default	Fallback quando a intencao nao e classificada

Motor de Contexto

Compressao

[context.compression]
enabled = false
threshold_tokens = 50000
keep_recent = 10
profile = "local-qwen"    # reutilizar base_url + api_key de um profile
model = "qwen2.5:3b"      # substituir modelo (opcional)

Campo	Tipo	Padrao	Descricao
enabled	boolean	false	Habilitar compressao de conversa
threshold_tokens	integer	50000	Comprimir quando a contagem de tokens exceder este valor
keep_recent	integer	10	Sempre manter as ultimas N mensagens sem comprimir
profile	string	""	Nome do profile a reutilizar para resumo
model	string	""	Substituicao de modelo para resumo

Compartilhamento Entre Profiles

[context.sharing]
enabled = false
max_context_size = 2000

Campo	Tipo	Padrao	Descricao
enabled	boolean	false	Habilitar compartilhamento de contexto entre profiles
max_context_size	integer	2000	Maximo de tokens a injetar de outros profiles

RAG Local

[context.rag]
enabled = false
index_paths = ["./src", "./docs"]
profile = "local-qwen"              # reutilizar base_url + api_key de um profile
model = "nomic-embed-text"           # modelo de embedding
chunk_size = 512
top_k = 5

Campo	Tipo	Padrao	Descricao
enabled	boolean	false	Habilitar RAG local
index_paths	string[]	[]	Diretorios para indexar
profile	string	""	Nome do profile a reutilizar para embeddings
model	string	""	Nome do modelo de embedding
chunk_size	integer	512	Tamanho do chunk de texto em tokens
top_k	integer	5	Numero de resultados a injetar