MuxLLM
开始使用

Client Setup

常用客户端配置

客户端界面会随版本变化，但连接逻辑保持一致：先选协议，再填写匹配的 Base URL、API Key 和精确模型名。

选择配置 查看模型广场

Chooser

按客户端能力选择协议

客户端优先协议模型端点标签Base URL
Claude CodeClaude 原生anthropichttps://api.muxllm.com
CodexResponsesopenai-responsehttps://api.muxllm.com/v1
Gemini CLIGemini 原生geminihttps://api.muxllm.com
Chatbox按模型选择openai / anthropic / gemini按协议填写
Cherry Studio / TraeOpenAI 兼容openaihttps://api.muxllm.com/v1
CC Switch / OpenCode按目标工具选择与供应商类型一致按协议填写

Before Setup

开始前完成四项检查

  1. 01创建独立 Key

    为客户端单独创建凭证，便于核对用量和单独停用。

  2. 02复制模型名

    从模型广场复制精确名称，不自行添加厂商前缀。

  3. 03确认端点

    模型标签必须与客户端供应商类型一致。

  4. 04最小化测试

    先关闭额外工具和插件，用短对话验证连接。

配置截图排查时可以提供字段名称、错误文本和最终 Base URL，但应遮盖完整 API Key、账户信息和其他敏感内容。
01

Terminal

Claude Code

使用 Claude 原生协议，目标模型需要显示 anthropic 标签。

  1. 在终端环境中设置 MuxLLM 根地址、API Key 和精确模型名。
  2. 重新打开终端或在当前 Shell 中加载变量，然后启动 Claude Code。
  3. 若出现认证错误，确认当前进程读取的是 ANTHROPIC_API_KEY，并检查是否有旧变量覆盖配置。
Shell 环境变量
export ANTHROPIC_BASE_URL="https://api.muxllm.com"
export ANTHROPIC_API_KEY="YOUR_API_KEY"
export ANTHROPIC_MODEL="MODEL_NAME"

claude

Shell 配置文件中的变量会长期生效；临时测试可只在当前终端导出。不要把包含真实 Key 的配置文件提交到仓库。

02

Terminal

Codex

Codex 自定义供应商使用 Responses 协议，目标模型必须显示 openai-response 标签。

  1. 把 API Key 放入自定义环境变量，例如 MUXLLM_API_KEY。
  2. 在用户级 ~/.codex/config.toml 中添加供应商；项目级 .codex/config.toml 不适合存放模型供应商和认证配置。
  3. 供应商 ID 不要使用保留的 openai，示例使用 muxllm。
Shell
export MUXLLM_API_KEY="YOUR_API_KEY"
~/.codex/config.toml
model = "MODEL_NAME"
model_provider = "muxllm"

[model_providers.muxllm]
name = "MuxLLM"
base_url = "https://api.muxllm.com/v1"
env_key = "MUXLLM_API_KEY"
wire_api = "responses"

Codex 当前自定义供应商的 wire_api 仅支持 responses；密钥应通过 env_key 指向环境变量，不直接写进 TOML。

03

Terminal

Gemini CLI

使用 Gemini 原生协议，目标模型需要显示 gemini 标签。

  1. 配置 Gemini API Key 和自定义 API 根地址。
  2. 在 CLI 的模型选择中使用模型广场中的精确模型名。
  3. 若当前版本忽略自定义根地址，先升级客户端并检查其供应商或环境变量说明。
Shell 环境变量
export GEMINI_API_KEY="YOUR_API_KEY"
export GOOGLE_GEMINI_BASE_URL="https://api.muxllm.com"

gemini
版本差异Gemini CLI 的认证与自定义端点选项可能随版本变化。最终请求应指向 https://api.muxllm.com/v1beta/models/MODEL_NAME:generateContent。
04

Desktop

Chatbox

Chatbox 可按模型分别配置 OpenAI、Claude 或 Gemini 供应商。不要用一个供应商类型承载三套协议。

模型类型供应商类型API Host / Base URL端点标签
OpenAI 模型OpenAI API / 自定义 OpenAIhttps://api.muxllm.com/v1openai
Claude 模型Claude API / Anthropichttps://api.muxllm.comanthropic
Gemini 模型Gemini APIhttps://api.muxllm.comgemini

OpenAI 模型

  1. 打开设置中的模型供应商，选择 OpenAI API 或自定义 OpenAI。
  2. API Key 填写自己的 MuxLLM Key，API Host 填写 https://api.muxllm.com/v1。
  3. 手动添加模型广场中的精确模型名，并确认显示 openai 标签。

Claude 模型

  1. 新建 Claude API / Anthropic 供应商，不要继续使用 OpenAI 供应商类型。
  2. API Host 填写 https://api.muxllm.com，不要在末尾额外添加 /v1。
  3. 添加显示 anthropic 标签的精确模型名，然后执行连接测试。

Gemini 模型

  1. 新建 Gemini API 供应商并填写 MuxLLM Key。
  2. API Host 填写 https://api.muxllm.com，由客户端拼接 Gemini 原生路径。
  3. 只添加显示 gemini 标签的精确模型名。
界面差异Chatbox 不同版本可能把字段命名为 API Host、Base URL 或 API 域名。判断标准是最终请求路径，而不是字段名称。
05

Desktop

Cherry Studio

优先使用 OpenAI 兼容供应商接入常规对话模型。

  1. 进入模型服务设置，新增 OpenAI 或 OpenAI 兼容供应商。
  2. API 地址填写 https://api.muxllm.com/v1，API Key 填写 YOUR_API_KEY。
  3. 手动添加显示 openai 标签的 MODEL_NAME。
  4. 连接测试失败时，先检查最终地址是否重复出现 /v1，再检查模型分组与余额。
06

Provider Switcher

CC Switch

CC Switch 用于管理多个工具的供应商配置，每个目标工具应建立独立配置。

目标工具协议Base URL模型要求
Claude CodeAnthropic 原生https://api.muxllm.comanthropic
CodexResponseshttps://api.muxllm.com/v1openai-response
Gemini CLIGemini 原生https://api.muxllm.comgemini
  1. 为每个工具新建 MuxLLM 供应商，避免复用错误协议。
  2. 将 API Key、Base URL 和默认模型填入对应工具配置。
  3. 切换后重启目标 CLI，并确认它读取的是新配置而非旧环境变量。
07

Terminal

OpenCode

可使用 OpenAI Compatible 供应商配置。示例中的模型需要显示 openai 标签。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "muxllm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "MuxLLM",
      "options": {
        "baseURL": "https://api.muxllm.com/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "MODEL_NAME": { "name": "MODEL_NAME" }
      }
    }
  }
}
凭证管理如果配置文件会进入版本控制，请改用 OpenCode 当前版本支持的环境变量或密钥引用方式，不要提交包含真实 API Key 的 JSON。
08

IDE

Trae

在支持自定义模型供应商的版本中，使用 OpenAI 兼容方式配置 MuxLLM。

  1. 打开 AI 模型或自定义供应商设置，选择 OpenAI Compatible。
  2. Base URL 填写 https://api.muxllm.com/v1，API Key 填写自己的 MuxLLM Key。
  3. 模型名填写模型广场中的 MODEL_NAME，并确认显示 openai 标签。
  4. 若当前版本没有自定义 Base URL 入口，则该版本无法按本教程接入，需要升级或改用支持自定义供应商的客户端。

Troubleshooting

客户端连接排查

现象常见原因检查方式
测试按钮立即失败Base URL 或认证头不匹配对照供应商类型检查是否带 /v1
模型不存在模型名拼写或分组不匹配从模型广场重新复制精确名称
401Key 无效、变量未加载、旧凭证覆盖重开客户端并检查当前进程环境
404客户端重复拼接版本或路径查看最终请求 URL，而不是只看配置字段
部分功能不可用模型不支持工具、视觉或目标协议用最小文本请求验证，再逐项开启能力

Need Details?

先用 API 请求验证协议

客户端错误难以定位时，用同一模型和 Key 发送最小 cURL 请求，可快速区分平台问题与客户端拼接问题。

查看 API 参考