MuxLLM
开始使用

Client Guide · Provider Switcher

CC Switch

用一个桌面工具管理多套 CLI Provider，但 Claude Code、Codex 和 Gemini CLI 仍然使用三种不同协议。每个目标工具都要独立创建、切换和验收。

查看三套配置核对模型标签

Scope & Evidence

CC Switch 只负责管理，不能改变协议兼容性

CC Switch 会写入各 CLI 的配置，但模型是否可用仍由目标 CLI、MuxLLM 端点标签和上游能力共同决定。Universal Provider 不能把三种协议自动变成完全等价。

等级状态说明
E1MuxLLM 端点已核对三种 CLI 所需标签和地址已根据公开运行态区分。
E2CC Switch 官方说明已核对支持工具、Provider 切换、备份目录和恢复官方登录有官方依据。
E3本批未执行没有安装 CC Switch、导入配置、切换 Provider 或启动任何 CLI。

最后核验日期：2026-07-18。CC Switch 与三种 CLI 都会升级，执行前需同时核对四方版本。

Install & Backup

安装前保存三种 CLI 的当前状态

  1. 从 CC Switch 官方站点或 GitHub Releases 下载当前系统版本；macOS 也可使用官方 Homebrew Cask。
  2. 记录 Claude Code、Codex、Gemini CLI 的版本、当前 Provider、默认模型和配置路径。
  3. 分别备份 ~/.claude 相关设置、~/.codex/config.toml、~/.gemini/settings.json 与相关环境文件。
  4. 首次启动时仅导入现有配置作为默认 Provider，不立即覆盖或启用新 Provider。
  5. 使用 CC Switch 的导出/备份能力额外保存一次；备份中可能包含凭证，应按敏感文件保护。
macOS Homebrew
brew install --cask cc-switch
本地数据CC Switch 官方说明的数据库位于 ~/.cc-switch/cc-switch.db，自动备份位于 ~/.cc-switch/backups/。不要假设数据库中的 Provider 数据天然适合公开或云同步。

Credential Plan

建议三种 CLI 使用三个独立 Key

  1. 分别创建 MuxLLM Claude Code、MuxLLM Codex、MuxLLM Gemini CLI 三个 Provider。
  2. 每个 Provider 使用独立 Key、额度和有效期，出现异常时可只停用一个工具。
  3. 模型从模型广场复制精确 ID；每个 Key 的模型和分组权限应满足对应标签。
  4. 导出配置、截图或提交问题时只保留 YOUR_API_KEY 与 MODEL_NAME 占位符。

Protocol Matrix

三套配置不可合并

目标工具Provider 类型模型标签Base URL关键规则
Claude CodeAnthropic / Claudeanthropichttps://api.muxllm.com不追加 /v1
CodexOpenAI Responses / Codexopenai-responsehttps://api.muxllm.com/v1wire_api = responses
Gemini CLIGemini API Keygeminihttps://api.muxllm.com使用 Gemini 原生路线

Claude Code Provider

单独创建 Anthropic 配置

  1. 在 Claude Code 标签页选择 Add Provider / 添加供应商，创建自定义 Provider。
  2. 名称填写 MuxLLM Claude Code，类型选择 Anthropic 或 Claude Code。
  3. API Key 填写该工具独立 Key，Base URL 填写 https://api.muxllm.com。
  4. 默认模型填写带 anthropic 标签的 MODEL_NAME。
  5. 保存后检查预览或生成配置，确保对应 ANTHROPIC_BASE_URL、凭证和模型，没有 OpenAI 字段。
  6. 点击 Enable / 启用前关闭当前 Claude Code 会话，便于后续明确验证新配置。
ToolClaude Code
Base URLhttps://api.muxllm.com
Endpointanthropic

Codex Provider

单独创建 Responses 配置

  1. 切换到 Codex 标签页，新建 MuxLLM Codex Provider，不复用 Claude 条目。
  2. Base URL 填写 https://api.muxllm.com/v1，认证使用 Codex 独立 Key。
  3. 协议或 Wire API 选择 Responses；生成配置必须等价于 wire_api = "responses"。
  4. 模型只选带 openai-response 标签的 MODEL_NAME。
  5. 不要推荐当前仅有 openai 标签的 gpt-5.3-codex*；名称中含 codex 不是兼容证据。
  6. 检查 Provider ID 不使用 Codex 保留的内置 ID，且 Key 没有明文进入可共享项目配置。
ToolCodex
Base URLhttps://api.muxllm.com/v1
Wire APIresponses
切换后重启关闭正在运行的 Codex，再从新终端启动。项目级 .codex/config.toml 不能替代用户级 Provider 与认证配置。

Gemini CLI Provider

单独创建 Gemini API Key 配置

  1. 在 Gemini CLI 标签页新增 MuxLLM Gemini CLI Provider。
  2. 认证方式选择 Gemini API Key，不选择 Google 登录或 Vertex AI。
  3. API Key 填写该工具独立 Key，Base URL 填写 https://api.muxllm.com。
  4. 默认模型只填写带 gemini 标签的 MODEL_NAME。
  5. 检查生成配置等价于 GEMINI_API_KEY 与 GOOGLE_GEMINI_BASE_URL，不能出现 GOOGLE_VERTEX_BASE_URL。
  6. 启用后关闭旧 Gemini CLI 进程，从新终端启动，避免继续读取旧环境。
ToolGemini CLI
Base URLhttps://api.muxllm.com
Endpointgemini

Acceptance

每次只启用并验证一个 CLI

  1. 01切换一项

    启用一个 Provider，另外两项保持原状态。

  2. 02检查落盘

    核对目标 CLI 配置文件、Base URL 和模型，不展示 Key。

  3. 03最短请求

    重启目标 CLI，发送短文本，不启用工具。

  4. 04控制台核对

    确认请求归属对应独立 Key，再测试下一项。

  1. Claude Code 最终应走 Anthropic Messages 路线。
  2. Codex 最终应走 /v1/responses 路线。
  3. Gemini CLI 最终应走 /v1beta/models/... 原生路线。
  4. 任何一项失败时停止，不要同时修改三套 Provider，否则无法确定根因。
E3 未执行本批没有切换 Provider、读取本机 CLI 配置或发送真实请求，三项均不应标记为已实测。

Rollback

使用原 Provider 或官方登录预设恢复

  1. 停止目标 CLI，会话中未完成的操作先安全结束。
  2. 在对应工具标签页切回首次导入的原 Provider；不要删除当前正在启用的唯一 Provider。
  3. 需要恢复官方登录时，添加并启用 CC Switch 官方登录预设，再按目标 CLI 的退出/登录流程操作。
  4. 若切换结果异常，恢复三种 CLI 的手工备份；CC Switch 自动备份只作为第二恢复来源。
  5. 停用不再使用的 MuxLLM 独立 Key，保留脱敏的切换时间与结果记录。

Troubleshooting

先判断是切换失败还是目标 CLI 请求失败

现象检查点处理
启用后仍走旧 Provider目标 CLI 进程未重启、旧环境变量优先级更高退出 CLI，新开终端，核对落盘配置与环境来源。
401Key 填错工具、被清空或目标进程未读取核对 Provider 与独立 Key 对应关系，必要时轮换该 Key。
404三套 Base URL 或协议模板混用按协议矩阵重建单个 Provider，检查最终请求路径。
429独立 Key 额度、余额、并发或上游限制停止连续连接测试，在控制台核对该 Key 用量。
插件/MCP 消失新 Provider 没有包含共享配置片段从原 Provider 提取 Shared Config，再精确写入新 Provider；不要覆盖认证字段。
配置文件损坏应用与手工编辑同时写入或导入内容不完整退出所有相关应用，恢复执行前备份，再单项导入。

Security

把 CC Switch 数据目录视为敏感资产

  • 数据库、导出文件、自动备份和云同步副本都可能包含 Provider 与凭证信息，设置最小文件权限。
  • 不要把 ~/.cc-switch 上传到公共仓库、工单或不受控同步盘。
  • 三种 CLI 使用独立 Key；异常时只撤销受影响的凭证，不扩大业务中断。
  • 首次切换关闭 MCP、Shell、文件写入和自动批准，先验证协议与计费。
  • 卸载 CC Switch 不代表其管理过的 CLI 配置和 Key 已删除；需逐项复核并撤销。

Directory

返回客户端渠道目录

需要配置其他客户端时，先从协议标签和 Base URL 开始，不复用不匹配的模板。

客户端目录上一篇：Trae