設定

設定檔探索

Claudex 使用 figment 進行分層設定。來源按以下順序合併（後者覆寫前者）：

程式內建預設值（內建的 fallback）
全域設定 (~/.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

# 匯出當前設定到 stdout
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"

Profiles

每個 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 (Zhipu)、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]`	—	模型 slot 映射表（`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 訂閱認證。

Gateway Auth 模式

使用 OAuth profile 時，Claudex 啟動 Claude Code 時會設定 ANTHROPIC_AUTH_TOKEN（而非 ANTHROPIC_API_KEY）。這可防止與 Claude Code 自身的訂閱登入機制衝突，因為 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）並移除會導致錯誤的參數。

模型 Slot 映射

Claude Code 有內建的 /model 切換器，包含三個 slot：haiku、sonnet 和 opus。詳見模型 Slot 映射。

工具名稱相容

部分提供商（特別是 OpenAI）對工具（function）名稱有 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 流程），請參閱提供商設定指南。