Mux 自定义 API 教程：Xum 更名、协议格式与配置优先级

本文对应 Coder 的编码 Agent 工具 Mux。2026 年 9 月 30 日读取的官方文档已使用 Xum 名称，并明确保留 Mux 兼容入口；它不是同名的视频平台。以下核验针对官方配置流程，未向占位服务发过请求。

Mux 接入关系原创示意图，非运行截图，不代表已联通

图中连线用于说明配置关系，不是接口测试结果。

先确认版本和配置目录

当前官方推荐从 Settings → Providers 管理提供商，高级配置位于 ~/.xum/providers.jsonc。更名文档说明旧 ~/.mux 会在正常迁移中指向新目录；如果两者已经是独立目录，不会自动合并。不要盲目覆盖其中任何一份。

旧 Mux 和新 Xum 不应同时读写同一批会话。需要切换版本时，先结束另一版本的进程。

用独立 provider 描述网关

官方支持命名自定义提供商，不必把内置 OpenAI 的默认地址改成私人网关。以下是可合并到 JSONC 的示意片段，地址仅为占位；本站没有提供该真实接口、密钥创建或充值服务。

{
  "tutorial-gateway": {
    "providerType": "openai-compatible",
    "baseUrl": "https://80321.cn/v1",
    "apiKey": "YOUR_API_KEY",
    "models": ["YOUR_MODEL_ID"]
  }
}

真实 Key 属于私密配置，不能提交进项目仓库。提供商 ID 应使用小写字母、数字、下划线或连字符，并避免与内置名称冲突。

协议选择不要沿用默认猜测

openai-compatible 使用 Chat Completions；openai-responses 使用 Responses；anthropic-messages 使用 Messages。内置 OpenAI 的默认 wire format 是 Responses，只有 Chat 接口的网关应明确选择相应格式。

地址不要携带查询参数或片段。不同格式对 /v1 的补全规则不同，先确认服务方给的是基础地址还是完整请求路径，再保存；不得把密钥放进 URL。

验证时看实际执行位置

保存后选择自定义提供商的精确模型，先发短文本，再在测试项目做一次只读任务。官方说明 Base URL 从后端进程所在机器解析：桌面模式通常是本机，server 模式则要从服务端检查网络。

如果改了环境变量却没有生效，检查设置页是否仍保存旧值。官方将环境变量作为未在设置中配置提供商时的回退来源，不能认为新变量一定覆盖界面设置。

限制与停止条件

自定义提供商是直接路由，不会自动继承内置提供商的账号功能或参与网关路由。模型能回复也不证明工具、图片和长上下文都兼容。发现配置目录冲突、协议无法确定或模型 ID 没有正式依据时，应暂停调用，先完成版本和地址核对。

首次验证只给测试工作区权限。日志与会话导出要脱敏，尤其不要把整个 provider 文件作为排错附件。