配置

配置文件发现

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

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

同时支持 TOML 和 YAML 格式。文件格式通过扩展名（.toml 或 .yaml/.yml）自动检测。

# 显示已加载的配置路径和所有搜索位置
claudex config show

# 仅显示配置文件路径
claudex config path

# 在当前目录创建新配置
claudex config init

# 从 config.example.toml 重新创建配置
claudex config recreate

# 在 $EDITOR 中打开配置
claudex config edit

# 验证配置语法和 profile 引用
claudex config validate

# 获取特定配置值
claudex config get proxy_port

# 设置特定配置值
claudex config set proxy_port 8080

# 导出当前配置到标准输出
claudex config export

全局设置

# claude 二进制文件路径（默认：PATH 中的 "claude"）
# claude_binary = "/usr/local/bin/claude"

# 代理设置
proxy_port = 13456
proxy_host = "127.0.0.1"

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

# 终端超链接（OSC 8）："auto" | true | false
# "auto" 自动检测终端支持；true/false 强制开启/关闭
hyperlinks = "auto"

# 模型别名（简称 → 完整模型名）
[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"

Profile

每个 profile 代表一个 AI 提供商连接。有三种提供商类型：

DirectAnthropic

用于原生支持 Anthropic Messages API 的提供商。请求以最小修改直接转发。

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

兼容提供商：Anthropic、MiniMax、Google Vertex AI

OpenAICompatible

用于使用 OpenAI Chat Completions API 的提供商。Claudex 自动在 Anthropic 和 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

兼容提供商：Grok (xAI)、OpenAI、DeepSeek、Kimi/Moonshot、GLM (智谱)、OpenRouter、Groq、Mistral、Together AI、Perplexity、Cerebras、Azure OpenAI、GitHub Copilot、GitLab Duo、Ollama、vLLM、LM Studio

OpenAIResponses

用于使用 OpenAI Responses API 的提供商（例如 ChatGPT/Codex 订阅）。Claudex 在 Anthropic Messages API 和 OpenAI Responses API 之间翻译。

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

兼容提供商：ChatGPT/Codex 订阅（通过 Codex CLI）

Profile 字段

字段	默认值	说明
`name`	必填	唯一的 profile 标识符
`provider_type`	`DirectAnthropic`	`DirectAnthropic`、`OpenAICompatible` 或 `OpenAIResponses`
`base_url`	必填	提供商 API 端点
`api_key`	`""`	API 密钥（明文）
`api_key_keyring`	—	从操作系统密钥链读取 API 密钥
`default_model`	必填	默认使用的模型
`auth_type`	`"api-key"`	`"api-key"` 或 `"oauth"`
`oauth_provider`	—	OAuth 提供商（`claude`、`openai`、`google`、`qwen`、`kimi`、`github`、`gitlab`）。`auth_type = "oauth"` 时必填
`backup_providers`	`[]`	故障转移 profile 名称
`custom_headers`	`{}`	额外的 HTTP 请求头
`extra_env`	`{}`	Claude 的额外环境变量
`priority`	`100`	智能路由优先级
`enabled`	`true`	是否启用此 profile
`max_tokens`	—	限制发送给提供商的最大输出 token 数（可选）
`strip_params`	`"auto"`	`"auto"`、`"none"` 或 `["temperature", "top_p"]`。自动检测不支持的参数（例如 ChatGPT Codex 端点）
`[profiles.query_params]`	`{}`	URL 查询参数（例如 Azure 的 `api-version`）
`[profiles.models]`	—	模型槽位映射表（`haiku`、`sonnet`、`opus` 字段）

交互式设置

添加 profile 最简单的方式是使用交互式向导：

claudex profile add

它会引导你完成提供商选择、API 密钥输入（可选密钥链存储）、模型选择和连接测试。

密钥链集成

将 API 密钥安全地存储在操作系统密钥链中，避免明文存放在配置文件中：

[[profiles]]
name = "grok"
api_key_keyring = "grok-api-key"   # 从操作系统密钥链读取

支持的后端：

macOS：Keychain
Linux：Secret Service（GNOME Keyring / KDE Wallet）

OAuth 订阅认证

除了 API 密钥，你还可以通过 OAuth 使用现有的提供商订阅进行认证。这对于拥有 Claude Pro/Team、ChatGPT Plus 或其他订阅计划的用户很有用。

设置

将 profile 的 auth_type 设为 "oauth" 并指定 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"

使用 auth 命令登录：

claudex auth login openai

查看认证状态：

claudex auth status

支持的提供商

提供商	`oauth_provider`	Token 来源
Claude	`claude`	读取 `~/.claude/.credentials.json`（Claude Code 的原生配置）
ChatGPT	`openai`	浏览器 PKCE 或 Device Code，回退到 `~/.codex/auth.json`（Codex CLI）
Google	`google`	读取 Gemini CLI 凭证
Qwen	`qwen`	Device Code 流程
Kimi	`kimi`	读取 Kimi CLI 凭证
GitHub	`github`	Device Code 流程，回退到 `~/.config/github-copilot/`
GitLab	`gitlab`	`GITLAB_TOKEN` 环境变量

各提供商 OAuth 流程的详细说明请参阅 OAuth 订阅认证。

网关认证模式

使用 OAuth profile 时，Claudex 在启动 Claude Code 时设置 ANTHROPIC_AUTH_TOKEN（非 ANTHROPIC_API_KEY）。这可以防止与 Claude Code 内部使用 ANTHROPIC_API_KEY 的订阅登录机制产生冲突。

代理会在 OAuth token 过期前自动刷新。你也可以手动刷新：

claudex auth refresh openai

查询参数

某些提供商需要 URL 查询参数（例如 Azure OpenAI 的 api-version）。使用 [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"

Claudex 会将这些参数附加到该 profile 的每个请求 URL 上。Azure OpenAI 通过 base_url 中包含 openai.azure.com 自动检测，并使用 api-key 请求头进行认证（取代 Authorization: Bearer）。

参数剥离

某些提供商不支持特定参数（例如 ChatGPT Codex 端点拒绝 temperature、top_p）。strip_params 字段控制在发送前移除哪些参数：

strip_params = "auto"       # 自动检测并剥离不支持的参数（默认）
strip_params = "none"       # 原样发送所有参数
strip_params = ["temperature", "top_p", "top_k"]  # 剥离指定参数

设为 "auto" 时，Claudex 检测已知端点（例如 chatgpt.com）并剥离会导致错误的参数。

模型槽位映射

Claude Code 内置 /model 切换器，有三个槽位：haiku、sonnet 和 opus。详见模型槽位映射。

工具名称兼容

某些提供商（特别是 OpenAI）对工具（函数）名称有 64 字符的长度限制。Claude Code 可能生成超过此限制的工具名称。

Claudex 在向 OpenAI 兼容提供商发送请求时自动截断超过 64 字符的工具名称，并在处理响应时透明恢复原始名称。这一往返过程完全透明。

非交互模式

Claudex 支持一次性（非交互）执行，适用于 CI/CD 流水线、脚本和自动化：

# 输出响应并退出
claudex run grok "Explain this codebase" --print

# 跳过所有权限提示（用于完全自动化的流水线）
claudex run grok "Fix lint errors" --print --dangerously-skip-permissions

非交互模式下，日志写入每个实例的日志文件 ~/Library/Caches/claudex/proxy-{timestamp}-{pid}.log（取代 stderr），保持 stdout 输出干净以便管道和自动化使用。

终端超链接

Claudex 支持终端输出中的 OSC 8 可点击超链接。详见终端超链接。

# "auto" 自动检测终端支持；true/false 强制开启/关闭
hyperlinks = "auto"

配置集

安装可复用的规则、技能和 MCP 服务器包。详见配置集。

claudex sets add ./my-set
claudex sets list

完整示例

参见 config.example.toml 获取包含所有提供商和选项的完整配置文件。

各提供商的分步设置说明（包括 API 密钥链接和 OAuth 流程），请参阅提供商设置指南。