Configuration Reference

Config File Location

Claudex uses layered configuration via figment. Sources merge in this order (later overrides earlier):

1. Programmatic defaults
2. Global config (~/.config/claudex/config.toml or .yaml)
3. Project config (claudex.toml/.claudex/config.toml in CWD or parents, or $CLAUDEX_CONFIG)
4. Environment variables (CLAUDEX_ prefix, __ separator)

Both TOML and YAML formats are supported.

See Configuration for setup details.

Global Settings

# Path to claude binary (default: "claude" from PATH)
claude_binary = "claude"

# Proxy server bind port
proxy_port = 13456

# Proxy server bind address
proxy_host = "127.0.0.1"

# Log level: trace, debug, info, warn, error
log_level = "info"

# Terminal hyperlinks (OSC 8): "auto" | true | false
hyperlinks = "auto"

Field	Type	Default	Description
claude_binary	string	"claude"	Path to the Claude Code CLI binary
proxy_port	integer	13456	Port the translation proxy listens on
proxy_host	string	"127.0.0.1"	Address the proxy binds to
log_level	string	"info"	Minimum log level
hyperlinks	string/bool	"auto"	Terminal hyperlinks: "auto" (detect), true (force on), false (force off)

Model Aliases

Define shorthand names for model identifiers:

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

Use aliases with -m:

claudex run grok -m grok3

Profile Configuration

[[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" (default) or "oauth"
# oauth_provider = "openai"        # required when auth_type = "oauth"
backup_providers = ["deepseek"]
custom_headers = {}
extra_env = {}
priority = 100
enabled = true
max_tokens = 16384                  # optional: cap output tokens
strip_params = "auto"               # "auto" | "none" | ["temperature", "top_p"]

# URL query parameters (e.g., Azure api-version)
[profiles.query_params]
# api-version = "2024-12-01-preview"

# Model slot mapping (optional)
[profiles.models]
haiku = "grok-3-mini-beta"
sonnet = "grok-3-beta"
opus = "grok-3-beta"

Field	Type	Default	Description
name	string	required	Unique profile identifier
provider_type	string	"DirectAnthropic"	"DirectAnthropic", "OpenAICompatible", or "OpenAIResponses"
base_url	string	required	Provider API endpoint URL
api_key	string	""	API key in plaintext
api_key_keyring	string	—	OS keychain entry name (overrides api_key)
default_model	string	required	Model identifier to use by default
auth_type	string	"api-key"	Authentication method: "api-key" or "oauth"
oauth_provider	string	—	OAuth provider name. One of: claude, openai, google, qwen, kimi, github, gitlab
backup_providers	string[]	[]	Profile names for failover, tried in order
custom_headers	map	{}	Additional HTTP headers sent with every request
extra_env	map	{}	Environment variables set when launching Claude
priority	integer	100	Priority weight for smart routing (higher = preferred)
enabled	boolean	true	Whether this profile is active
max_tokens	integer	—	Cap max output tokens sent to provider. When set, overrides the max_tokens in requests
strip_params	string/array	"auto"	Parameters to strip from requests. "auto" detects known endpoints; "none" sends all; array strips specific params

Query Parameters

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

Field	Type	Description
query_params	map	Key-value pairs appended as URL query parameters to every request

Used primarily for Azure OpenAI (api-version), but works with any provider.

Model Slot Mapping

The optional [profiles.models] table maps Claude Code’s /model switcher slots to provider-specific model names. When you switch models inside Claude Code (e.g., /model opus), Claudex translates the request to the mapped model.

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

Field	Type	Description
haiku	string	Model to use when Claude Code selects haiku
sonnet	string	Model to use when Claude Code selects sonnet
opus	string	Model to use when Claude Code selects opus

Tip

If a slot is not defined, the profile’s default_model is used as fallback. Slots are also exposed as environment variables: ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL.

Provider Examples

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

# MiniMax (DirectAnthropic — no translation)
[[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 — needs translation)
[[profiles]]
name = "openrouter"
provider_type = "OpenAICompatible"
base_url = "https://openrouter.ai/api/v1"
api_key = "..."
default_model = "anthropic/claude-sonnet-4"

# Grok (OpenAICompatible — needs translation)
[[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 — needs translation)
[[profiles]]
name = "chatgpt"
provider_type = "OpenAICompatible"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."
default_model = "gpt-4o"

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

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

# GLM / 智谱 (OpenAICompatible — needs translation)
[[profiles]]
name = "glm"
provider_type = "OpenAICompatible"
base_url = "https://api.z.ai/api/paas/v4"
api_key = "..."
default_model = "glm-4.6"

# Groq (OpenAICompatible — fast inference)
[[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 — needs translation)
[[profiles]]
name = "mistral"
provider_type = "OpenAICompatible"
base_url = "https://api.mistral.ai/v1"
api_key = "..."
default_model = "mistral-large-latest"

# Together AI (OpenAICompatible — needs translation)
[[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 — online search + LLM)
[[profiles]]
name = "perplexity"
provider_type = "OpenAICompatible"
base_url = "https://api.perplexity.ai"
api_key = "pplx-..."
default_model = "sonar-pro"

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

# Azure OpenAI (OpenAICompatible — api-key header + 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, no API key needed)
[[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

OAuth Profile Examples

# Claude Max (skips proxy, uses Claude's native OAuth from ~/.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"

# ChatGPT/Codex subscription (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"

Caution

For the claude OAuth provider, Claudex skips the proxy and lets Claude Code use its own OAuth directly. For all other OAuth providers, the proxy handles token management and refresh.

Smart Router

[router]
enabled = false
profile = "local-qwen"    # reuse a profile's base_url + api_key
model = "qwen2.5:3b"      # override model (optional)

Field	Type	Default	Description
enabled	boolean	false	Enable smart routing
profile	string	""	Profile name to reuse for classification (uses its base_url + api_key)
model	string	""	Model override for classification (defaults to profile’s default_model)

Routing Rules

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

Key	Description
code	Profile for coding tasks
analysis	Profile for analysis and reasoning
creative	Profile for creative writing
search	Profile for search and research
math	Profile for math and logic
default	Fallback when intent is unclassified

Context Engine

Compression

[context.compression]
enabled = false
threshold_tokens = 50000
keep_recent = 10
profile = "local-qwen"    # reuse a profile's base_url + api_key
model = "qwen2.5:3b"      # override model (optional)

Field	Type	Default	Description
enabled	boolean	false	Enable conversation compression
threshold_tokens	integer	50000	Compress when token count exceeds this
keep_recent	integer	10	Always keep the last N messages uncompressed
profile	string	""	Profile name to reuse for summarization
model	string	""	Model override for summarization

Cross-Profile Sharing

[context.sharing]
enabled = false
max_context_size = 2000

Field	Type	Default	Description
enabled	boolean	false	Enable cross-profile context sharing
max_context_size	integer	2000	Max tokens to inject from other profiles

Local RAG

[context.rag]
enabled = false
index_paths = ["./src", "./docs"]
profile = "local-qwen"              # reuse a profile's base_url + api_key
model = "nomic-embed-text"           # embedding model
chunk_size = 512
top_k = 5

Field	Type	Default	Description
enabled	boolean	false	Enable local RAG
index_paths	string[]	[]	Directories to index
profile	string	""	Profile name to reuse for embeddings
model	string	""	Embedding model name
chunk_size	integer	512	Text chunk size in tokens
top_k	integer	5	Number of results to inject