Client Guide · OpenAI Compatible

OpenCode

在 OpenCode 中新增 MuxLLM Provider，使用 OpenAI 兼容协议、环境变量凭证和模型广场中的精确模型 ID。

查看完整配置核对模型标签

协议标签

openai

Base URL

https://api.muxllm.com/v1

模型引用

muxllm/MODEL_NAME

Scope & Evidence

本页只覆盖 OpenAI 兼容路线

目标模型必须显示 openai 标签。OpenCode 还支持其他 Provider，但本页不把 Claude、Gemini 或 Responses 协议混入同一配置。

等级	状态	说明
E1	公开元数据已核对	Base URL 与 `openai` 模型标签有运行态依据。
E2	官方配置规则已核对	Provider、Schema、环境变量引用和模型命名依据 OpenCode 官方文档。
E3	本批未执行	没有安装 OpenCode 或发送真实请求。

最后核验日期：2026-07-18。

Install

安装前保存现有 Provider

从 OpenCode 官方安装页选择当前系统支持的安装方式，不使用不明二进制镜像。
已有安装先记录版本和执行路径，升级后重新检查配置 Schema。
备份用户级 ~/.config/opencode/opencode.json 和项目级 opencode.json。
决定配置作用域：个人 Provider 放用户级；项目文件只能保存不含秘密的可共享设置。

官方 npm 安装方式

npm install -g opencode-ai
opencode --version

Credential & Model

Key 与配置文件分离

在 MuxLLM 控制台创建仅供 OpenCode 使用的独立 Key，限制额度和有效期。
从模型广场复制带 openai 标签的精确 MODEL_NAME。
在 Shell 中设置专用变量 MUXLLM_OPENCODE_KEY，避免覆盖其他 OpenAI 客户端。
配置通过 {env:MUXLLM_OPENCODE_KEY} 引用，不出现真实 Key。

临时环境变量

export MUXLLM_OPENCODE_KEY="YOUR_API_KEY"

Provider Config

声明 OpenAI Compatible Provider

~/.config/opencode/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": "{env:MUXLLM_OPENCODE_KEY}"
      },
      "models": {
        "MODEL_NAME": {
          "name": "MODEL_NAME"
        }
      }
    }
  }
}

provider.muxllm自定义 Provider ID；模型选择时使用该前缀。

baseURL写到 /v1，不追加具体端点。

models键名与 name 都替换为模型广场精确 ID。

$schema保留官方 Schema 地址，不替换成 MuxLLM 域名。

合并而非覆盖如果文件已有 Provider、MCP、Agent 或权限设置，只新增 provider.muxllm；不要用示例覆盖整个文件。

Acceptance

选择模型并做最小请求

01静态解析
启动时没有 JSON 或 Schema 错误。
02模型可见
模型列表出现 muxllm/MODEL_NAME。
03短文本请求
不启用 Agent 工具，只请求一个短文本回复。
04用量核对
确认独立 Key、模型与计费符合预期。

若通过命令选择模型，使用 OpenCode 当前版本提供的模型选择器或 /models，不要假设旧版快捷键仍然有效。

E3 未执行第 3、4 步会产生真实调用。本批没有运行 OpenCode，不能把候选配置标为已实测。

Rollback

恢复原配置和模型

退出 OpenCode，恢复配置文件备份，或只删除 provider.muxllm。
把当前模型切回记录下来的 PREVIOUS_PROVIDER/PREVIOUS_MODEL。
清理 MUXLLM_OPENCODE_KEY 及其持久注入位置。
确认没有其他程序依赖后，在 MuxLLM 控制台停用测试 Key。

清理当前 Shell

unset MUXLLM_OPENCODE_KEY

Troubleshooting

从变量、路径和模型三层排查

现象	原因	处理
401	环境变量未加载、引用语法错误或 Key 无效	新开终端，核对变量名与 Key 状态，不打印真实值。
404	重复 `/v1`、客户端拼接错误或模型不支持 OpenAI 兼容协议	恢复标准 Base URL，重新核对 `openai` 标签。
429	额度、余额、并发或上游限速	停止自动重试，查看控制台与错误中的等待信息。
模型不出现	JSON 层级、模型键或 Provider 作用域错误	用官方 Schema 校验，并确认当前进程读取的配置路径。
工具失败	模型能力或 OpenAI Compatible 工具 Schema 差异	先保持纯文本验证，单独设计最小工具调用测试。

Security

配置作用域与工具授权

真实 Key 只存在于安全环境或秘密管理器，不写入用户/项目 JSON。
项目级配置可以共享 Provider 结构，但不得提交个人凭证或敏感绝对路径。
首次验证关闭自动执行、Shell、文件写入和不必要的 MCP 服务。
分享日志时遮盖 Key、提示词、文件内容、账户信息和签名 URL。
疑似泄露先停用 Key，再检查 Shell 历史、配置备份和同步目录。

Official Sources

执行前复核官方配置

OpenCode 文档安装、配置和模型选择 Providers自定义 Provider 与凭证引用 MuxLLM 模型广场核对 openai 标签与精确模型 ID

Next Guide

继续配置 Trae

Trae 的设置入口随版本变化，应以最终请求 URL 和供应商协议作为验收标准。

下一篇：Trae 上一篇：OpenClaw