配置

配置文件发现

Claudex 按以下顺序搜索配置文件：

1. $CLAUDEX_CONFIG 环境变量
2. ./claudex.toml（当前目录）
3. ./.claudex/config.toml（当前目录）
4. 父目录（最多向上 10 级），检查上述两种模式

注意

# 查看加载的配置路径和搜索顺序
claudex config

# 在当前目录创建本地配置
claudex config --init

提示

项目级配置（./claudex.toml）优先于全局配置，可以为不同项目定制提供商。

全局设置

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

# 模型别名（简称 → 完整模型名）
[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

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、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-4o"
auth_type = "oauth"
oauth_provider = "openai"

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

提示

此类型主要用于 OAuth 订阅。详细的 Codex CLI 配置步骤请参见 Provider 配置指南。

Profile 字段

字段	默认值	说明
name	必填	唯一标识名
provider_type	DirectAnthropic	DirectAnthropic、OpenAICompatible 或 OpenAIResponses
base_url	必填	提供商 API 端点
api_key	""	API 密钥（明文）
api_key_keyring	—	从 OS 钥匙链读取 API 密钥
default_model	必填	默认使用的模型
auth_type	"api-key"	"api-key" 或 "oauth"
oauth_provider	—	OAuth 提供商（claude、openai、google、qwen、kimi、github）。auth_type = "oauth" 时必填
backup_providers	[]	故障转移 profile 名列表
custom_headers	{}	额外 HTTP 请求头
extra_env	{}	启动 Claude 时的额外环境变量
priority	100	智能路由优先级
enabled	true	是否启用
[profiles.models]	—	模型 slot 映射表（haiku、sonnet、opus 字段）

交互式设置

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

claudex profile add

它会引导你完成提供商选择、API 密钥输入（支持 keyring 存储）、模型选择和连通性测试。

密钥环集成

将 API 密钥安全存储在 OS 钥匙链中，而非明文配置：

[[profiles]]
name = "grok"
api_key_keyring = "grok-api-key"   # 从 OS 钥匙链读取

支持的后端：

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

OAuth 订阅认证

除了 API 密钥，你还可以通过 OAuth 使用现有的提供商订阅进行认证。适用于 Claude Pro/Team、ChatGPT Plus 或其他订阅方案。

设置

1. 将 profile 的 auth_type 设为 "oauth" 并指定 oauth_provider：

[[profiles]]
name = "chatgpt-oauth"
provider_type = "OpenAICompatible"
base_url = "https://api.openai.com/v1"
default_model = "gpt-4o"
auth_type = "oauth"
oauth_provider = "openai"

2. 使用 auth 命令登录：

claudex auth login openai

3. 检查认证状态：

claudex auth status

支持的提供商

提供商	oauth_provider	Token 来源
Claude	claude	从 ~/.claude 读取（Claude Code 原生配置）
OpenAI	openai	从 ~/.codex/auth.json 读取（Codex CLI）
Google	google	OAuth 设备码流程
Qwen	qwen	OAuth 设备码流程
Kimi	kimi	OAuth 设备码流程
GitHub	github	OAuth 设备码流程

提示

对于 OpenAI，请确保已安装 Codex CLI 并已登录（codex auth）。Claudex 自动从 ~/.codex/auth.json 读取 token。Profile 应使用 provider_type = "OpenAIResponses" 以通过 Responses API 通信。

提示

对于 Claude，Claudex 读取已有的 Claude Code OAuth 会话（~/.claude）。如果你已登录 Claude Code，无需额外登录步骤。

Gateway 认证模式

使用 OAuth profile 时，Claudex 启动 Claude Code 时设置 ANTHROPIC_AUTH_TOKEN（而非 ANTHROPIC_API_KEY）。这可以避免与 Claude Code 自身订阅登录机制冲突，因为 Claude Code 内部使用 ANTHROPIC_API_KEY。

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

claudex auth refresh openai

模型 Slot 映射

Claude Code 内置 /model 切换器，包含三个 slot：haiku、sonnet 和 opus。默认映射到 Anthropic 模型，但通过 Claudex 可以将它们映射到任意提供商的模型。

配置

在任意 profile 中添加 [profiles.models] 表：

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

[profiles.models]
haiku = "grok-3-mini-beta"
sonnet = "grok-3-beta"
opus = "grok-3-beta"

在 Claude Code 中输入 /model sonnet 时，Claudex 会将请求翻译为使用 grok-3-beta。/model opus 命令映射到 grok-3-beta，以此类推。

常见提供商示例

# OpenAI 模型映射
[profiles.models]
haiku = "gpt-4o-mini"
sonnet = "gpt-4o"
opus = "o1"

# DeepSeek 模型映射
[profiles.models]
haiku = "deepseek-chat"
sonnet = "deepseek-chat"
opus = "deepseek-reasoner"

# Google Gemini 模型映射
[profiles.models]
haiku = "gemini-2.0-flash"
sonnet = "gemini-2.5-pro"
opus = "gemini-2.5-pro"

注意

未配置的模型 slot 将回退到 profile 的 default_model。

工具名兼容

部分提供商（尤其是 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

警告

--dangerously-skip-permissions 会禁用所有安全提示。仅在受信任的自动化环境中使用。

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

每实例日志文件

每个 Claudex 代理实例将日志写入独立文件：

~/Library/Caches/claudex/proxy-{timestamp}-{pid}.log

这避免了多实例运行时的日志交错，并在 claudex run 期间（尤其是非交互模式下）保持 stderr 干净。日志内容包括代理启动、请求翻译、OAuth token 刷新事件和断路器状态变化。

完整示例

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

每个提供商的详细配置步骤（包括 API 密钥获取链接和 OAuth 流程），请参见 Provider 配置指南。