配置参考

配置文件位置

Claudex 使用 figment 实现分层配置。配置源按以下顺序合并（后者覆盖前者）：

程序内置默认值
全局配置（~/.config/claudex/config.toml 或 .yaml）
项目配置（当前目录或父目录中的 claudex.toml/.claudex/config.toml，或 $CLAUDEX_CONFIG）
环境变量（CLAUDEX_ 前缀，__ 分隔符）

同时支持 TOML 和 YAML 格式。

参见配置了解设置详情。

全局设置

# Claude 二进制文件路径（默认：从 PATH 中查找 "claude"）
claude_binary = "claude"

# 代理服务器监听端口
proxy_port = 13456

# 代理服务器绑定地址
proxy_host = "127.0.0.1"

# 日志级别：trace, debug, info, warn, error
log_level = "info"

# 终端超链接（OSC 8）："auto" | true | false
hyperlinks = "auto"

字段	类型	默认值	说明
`claude_binary`	string	`"claude"`	Claude Code CLI 二进制文件路径
`proxy_port`	integer	`13456`	翻译代理监听端口
`proxy_host`	string	`"127.0.0.1"`	代理绑定地址
`log_level`	string	`"info"`	最低日志级别
`hyperlinks`	string/bool	`"auto"`	终端超链接：`"auto"`（检测）、`true`（强制开启）、`false`（强制关闭）

模型别名

为模型标识定义简称：

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

使用别名：

claudex run grok -m grok3

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"（默认）或 "oauth"
# oauth_provider = "openai"        # auth_type = "oauth" 时必填
backup_providers = ["deepseek"]
custom_headers = {}
extra_env = {}
priority = 100
enabled = true
max_tokens = 16384                  # 可选：限制输出 token 数
strip_params = "auto"               # "auto" | "none" | ["temperature", "top_p"]

# URL 查询参数（例如 Azure api-version）
[profiles.query_params]
# api-version = "2024-12-01-preview"

# 模型槽位映射（可选）
[profiles.models]
haiku = "grok-3-mini-beta"
sonnet = "grok-3-beta"
opus = "grok-3-beta"

字段	类型	默认值	说明
`name`	string	必填	唯一的 profile 标识符
`provider_type`	string	`"DirectAnthropic"`	`"DirectAnthropic"`、`"OpenAICompatible"` 或 `"OpenAIResponses"`
`base_url`	string	必填	提供商 API 端点 URL
`api_key`	string	`""`	明文 API 密钥
`api_key_keyring`	string	—	OS 密钥链条目名（覆盖 `api_key`）
`default_model`	string	必填	默认模型标识
`auth_type`	string	`"api-key"`	认证方式：`"api-key"` 或 `"oauth"`
`oauth_provider`	string	—	OAuth 提供商名称。可选：`claude`、`openai`、`google`、`qwen`、`kimi`、`github`、`gitlab`
`backup_providers`	string[]	`[]`	故障转移 profile 名，按顺序尝试
`custom_headers`	map	`{}`	每个请求附带的额外 HTTP 头
`extra_env`	map	`{}`	启动 Claude 时设置的环境变量
`priority`	integer	`100`	智能路由优先级权重（越高越优先）
`enabled`	boolean	`true`	是否激活此 profile
`max_tokens`	integer	—	限制发送给提供商的最大输出 token 数。设置时覆盖请求中的 `max_tokens`
`strip_params`	string/array	`"auto"`	从请求中剥离的参数。`"auto"` 检测已知端点；`"none"` 发送全部；数组指定特定参数

查询参数

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

字段	类型	说明
`query_params`	map	作为 URL 查询参数附加到每个请求的键值对

主要用于 Azure OpenAI（api-version），但适用于任何提供商。

模型槽位映射

可选的 [profiles.models] 表将 Claude Code 的 /model 切换器槽位映射到提供商特定的模型名。当你在 Claude Code 中切换模型（例如 /model opus）时，Claudex 会将请求翻译为映射的模型。

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

字段	类型	说明
`haiku`	string	Claude Code 选择 `haiku` 时使用的模型
`sonnet`	string	Claude Code 选择 `sonnet` 时使用的模型
`opus`	string	Claude Code 选择 `opus` 时使用的模型

提供商示例

# Anthropic（DirectAnthropic -- 无需翻译）
[[profiles]]
name = "anthropic"
provider_type = "DirectAnthropic"
base_url = "https://api.anthropic.com"
api_key = "sk-ant-..."
default_model = "claude-sonnet-4-20250514"

# MiniMax（DirectAnthropic -- 无需翻译）
[[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 -- 需要翻译）
[[profiles]]
name = "openrouter"
provider_type = "OpenAICompatible"
base_url = "https://openrouter.ai/api/v1"
api_key = "..."
default_model = "anthropic/claude-sonnet-4"

# Grok（OpenAICompatible -- 需要翻译）
[[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 -- 需要翻译）
[[profiles]]
name = "chatgpt"
provider_type = "OpenAICompatible"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."
default_model = "gpt-4o"

# DeepSeek（OpenAICompatible -- 需要翻译）
[[profiles]]
name = "deepseek"
provider_type = "OpenAICompatible"
base_url = "https://api.deepseek.com"
api_key = "..."
default_model = "deepseek-chat"
backup_providers = ["grok"]

# Kimi / Moonshot（OpenAICompatible -- 需要翻译）
[[profiles]]
name = "kimi"
provider_type = "OpenAICompatible"
base_url = "https://api.moonshot.ai/v1"
api_key = "..."
default_model = "kimi-k2-0905-preview"

# GLM / 智谱（OpenAICompatible -- 需要翻译）
[[profiles]]
name = "glm"
provider_type = "OpenAICompatible"
base_url = "https://api.z.ai/api/paas/v4"
api_key = "..."
default_model = "glm-4.6"

# Groq（OpenAICompatible -- 快速推理）
[[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 -- 需要翻译）
[[profiles]]
name = "mistral"
provider_type = "OpenAICompatible"
base_url = "https://api.mistral.ai/v1"
api_key = "..."
default_model = "mistral-large-latest"

# Together AI（OpenAICompatible -- 需要翻译）
[[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 -- 联网搜索 + LLM）
[[profiles]]
name = "perplexity"
provider_type = "OpenAICompatible"
base_url = "https://api.perplexity.ai"
api_key = "pplx-..."
default_model = "sonar-pro"

# Cerebras（OpenAICompatible -- 快速推理）
[[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 头 + 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（本地，无需 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（本地）
[[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 示例

# Claude Max（跳过代理，使用 Claude 原生 OAuth，从 ~/.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 订阅（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 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 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 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 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（通过 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"

智能路由

[router]
enabled = false
profile = "local-qwen"    # 复用此 profile 的 base_url + api_key
model = "qwen2.5:3b"      # 覆盖模型（可选）

字段	类型	默认值	说明
`enabled`	boolean	`false`	启用智能路由
`profile`	string	`""`	复用的 profile 名（使用其 `base_url` + `api_key`）
`model`	string	`""`	分类模型覆盖（默认用 profile 的 `default_model`）

路由规则

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

键	说明
`code`	编程任务对应的 profile
`analysis`	分析推理对应的 profile
`creative`	创意写作对应的 profile
`search`	搜索研究对应的 profile
`math`	数学逻辑对应的 profile
`default`	未分类时的默认 profile

上下文引擎

压缩

[context.compression]
enabled = false
threshold_tokens = 50000
keep_recent = 10
profile = "local-qwen"    # 复用此 profile 的 base_url + api_key
model = "qwen2.5:3b"      # 覆盖模型（可选）

字段	类型	默认值	说明
`enabled`	boolean	`false`	启用对话压缩
`threshold_tokens`	integer	`50000`	token 数超过此值时触发压缩
`keep_recent`	integer	`10`	始终保留最近 N 条消息不压缩
`profile`	string	`""`	复用的 profile 名（用于摘要生成）
`model`	string	`""`	摘要模型覆盖

跨 Profile 共享

[context.sharing]
enabled = false
max_context_size = 2000

字段	类型	默认值	说明
`enabled`	boolean	`false`	启用跨 profile 上下文共享
`max_context_size`	integer	`2000`	从其他 profile 注入的最大 token 数

本地 RAG

[context.rag]
enabled = false
index_paths = ["./src", "./docs"]
profile = "local-qwen"              # 复用此 profile 的 base_url + api_key
model = "nomic-embed-text"           # embedding 模型
chunk_size = 512
top_k = 5

字段	类型	默认值	说明
`enabled`	boolean	`false`	启用本地 RAG
`index_paths`	string[]	`[]`	要索引的目录
`profile`	string	`""`	复用的 profile 名（用于 embedding）
`model`	string	`""`	embedding 模型名称
`chunk_size`	integer	`512`	文本块大小（token）
`top_k`	integer	`5`	注入的结果数量