OpenCode 配置 APIMaster.ai

在 OpenCode Desktop 中添加 OpenAI 兼容自定义 Provider，接入 apimaster.ai，并配置 Reasoning 档位（opencode.jsonc）。

OpenCode Desktop 是 OpenCode 的图形界面客户端（当前 Beta），支持本地 Agent 会话、文件编辑与终端执行。APIMaster.ai 提供 OpenAI 兼容 接口，可在 设置 → 提供商 中添加 自定义提供商 接入。

开始前请获取 API Key。下文 Key 均用占位符 你的_apimaster_key，截图中已打码。

前置条件

已安装 OpenCode Desktop（opencode.ai/download）。
- Windows：下载 opencode-desktop-win-x64.exe 安装。
- macOS：brew install --cask opencode-desktop，或下载对应 .dmg。
- Linux：.deb / .rpm / AppImage。
已从 APIMaster 控制台复制 API Key。

第 1 步：打开提供商设置

启动 OpenCode Desktop，打开或新建一个工作区。
点击左下角 齿轮（设置）。
在设置侧栏选择 「提供商」（Providers）。
在列表底部找到 「自定义提供商」（通过基础 URL 添加与 OpenAI 兼容的提供商）。
点击右侧 「+ 连接」。

设置 → 提供商 → 自定义提供商

第 2 步：填写自定义提供商

在 自定义提供商 表单中填写：

字段	填写内容
提供商 ID	`apimaster`（小写字母、数字、连字符或下划线）
显示名称	`APIMaster.ai`（模型列表中的分组名，可自定）
基础 URL	`https://apimaster.ai/v1`（必须带 `/v1`）
API 密钥	粘贴你的 APIMaster Key

自定义提供商表单

请求头 一般留空；若你通过 Header 认证，可留空 Key 并在请求头里填 Authorization: Bearer …。
填完后继续下一步（添加模型）。

第 3 步：添加模型并提交

下一页为 模型映射：左侧为 OpenCode 内显示名，右侧为发给 APIMaster 的 model id（建议两边填相同，与模型广场一致）。

示例（可按账户实际开通情况增减）：

左侧（显示）	右侧（model id）
`gpt-5.4`	`gpt-5.4`
`claude-sonnet-4-6`	`claude-sonnet-4-6`

点 「+ 添加模型」 增加行。
勾选或填写需要的 model id。
请求头（可选） 通常留空。
点 「提交」 保存。

添加模型映射并提交

模型 ID 怎么选？ 与广场上的 id 完全一致，如 gpt-5.5、claude-opus-4-8、deepseek-v4-pro 等。不要选纯图像模型（如 gpt-image-2）用于 Agent 对话。

第 4 步：在对话里选择模型

回到主界面，新建会话 或打开已有会话。
点击输入框下方的 模型下拉（可能显示当前模型名，如 gpt-5.4）。
在列表中找到 APIMaster.ai 分组，点选要用的模型（如 claude-sonnet-4-6 或 gpt-5.4）。

模型下拉中选择 APIMaster.ai

第 5 步：发送测试消息

在输入框输入 hello 或简单任务（例如「写一个命令行天气小工具」）。
若 Assistant 开始回复、探索文件或执行 Shell，说明 APIMaster 接入成功。

对话测试示例

进阶：配置文件与 Reasoning 档位

上文 设置 → 提供商 适合快速接入。若需要为同一模型配置 Reasoning / thinking effort 档位（如 low / high / max），推荐编辑 OpenCode 配置文件 opencode.jsonc。

配置文件位置

系统	路径
macOS / Linux	`~/.config/opencode/opencode.jsonc`
Windows	`C:\Users\<用户名>\.config\opencode\opencode.jsonc`

若文件不存在，可新建；保存后需 重启 OpenCode Desktop 或 新开一个会话 才会加载。

配置 API Key（不要写进 jsonc）

API Key 不应写入 opencode.jsonc，避免明文落盘。

推荐方式：

终端执行 /connect，按提示连接 APIMaster；或
使用上文 设置 → 提供商 → 连接提供商（Connect Provider）图形界面配置。

jsonc 里只写 Provider、模型与 Reasoning；鉴权由 OpenCode 单独管理。

配置 APIMaster Provider

在 opencode.jsonc 中 Provider ID 可命名为 apimaster，npm 包使用 @ai-sdk/openai-compatible。

baseURL 必须是：

https://apimaster.ai/v1

为什么不能写成 https://apimaster.ai/？ OpenCode 会自动拼接 /chat/completions。若 baseURL 是网站根地址，实际请求会变成 https://apimaster.ai/chat/completions，返回 404 Not Found。带 /v1 才会正确命中 https://apimaster.ai/v1/chat/completions。

完整示例（含 Reasoning variants）可直接下载，覆盖到 OpenCode 配置路径即可使用：

下载 opencode.jsonc
覆盖到（或保存为）：
- macOS / Linux：~/.config/opencode/opencode.jsonc
- Windows：C:\Users\<用户名>\.config\opencode\opencode.jsonc
用 /connect 或 UI 连接提供商 配置 API Key（Key 不要写进 jsonc）。
重启 OpenCode Desktop 或新建会话。

若你已有 opencode.jsonc，覆盖前建议先备份；也可只把示例里的 provider.apimaster 段合并进原文件。

核心结构示例：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apimaster": {
      "name": "APIMaster.ai",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://apimaster.ai/v1"
      },
      "models": {
        "gpt-5.4": {
          "name": "gpt-5.4",
          "variants": {
            "low": { "reasoningEffort": "low" },
            "high": { "reasoningEffort": "high" }
          }
        }
      }
    }
  }
}

Reasoning 配置原则

OpenCode 的 variants 为同一 model id 提供多档 Reasoning 选项，在 UI 里表现为同一模型下的子档位。
对 OpenAI-compatible 接口，OpenCode 会把 reasoningEffort 转成请求体里的 reasoning_effort。
variant 名称应与实际参数一致（例如 variant 叫 high 就写 "reasoningEffort": "high"），避免用户不知道真实发送了什么。
不同模型支持的档位不同，应按各模型官方文档配置，不做隐藏映射。

各模型 Reasoning 档位

模型	Reasoning variants	说明
`gpt-5.4`	`low`, `medium`, `high`, `xhigh`	GPT reasoning 模型
`gpt-5.5`	`low`, `medium`, `high`, `xhigh`	GPT reasoning 模型
`deepseek-v4-flash`	`high`, `max`	DeepSeek thinking mode 推荐档位
`deepseek-v4-pro`	`high`, `max`	DeepSeek thinking mode 推荐档位
`claude-sonnet-4-6`	`low`, `medium`, `high`, `max`	Claude Sonnet effort 档位
`claude-opus-4-7`	`low`, `medium`, `high`, `xhigh`, `max`	Claude Opus effort 档位
`claude-opus-4-8`	`low`, `medium`, `high`, `xhigh`, `max`	Claude Opus effort 档位
`claude-haiku-4-5`	不配置	不强行暴露未确认的 reasoning effort
`minimax-m3`	不配置	不强行暴露未确认的 reasoning effort

完整 variants 定义见 opencode.jsonc。

在 OpenCode 中切换 Reasoning

保存 opencode.jsonc 后 重启 OpenCode Desktop，或 新建会话。
在输入框下方的 模型 / Reasoning 下拉 中选择模型及档位（如 gpt-5.4 / high）。
若当前版本支持，可用 Ctrl + Shift + D 在 Reasoning 档位间循环切换。

常见问题

UI 接入

情况	做法
401 / 鉴权失败	核对 Key 是否完整；到控制台作废泄露 Key 并重新生成
模型不存在	确认基础 URL 为 `https://apimaster.ai/v1`，model id 与广场一致
列表里没有 APIMaster 模型	回到设置 → 提供商，编辑 `APIMaster.ai`，补全模型映射后重新提交
回复很慢或中断	换用广场中标注稳定的模型；用 API 连通性测试单独验证 Key

Reasoning / jsonc

为什么 DeepSeek 只有 high 和 max？
DeepSeek thinking mode 在 OpenAI-compatible 接口上官方支持的 effort 档位是 high 与 max。不建议配置 low / medium / xhigh 等会被兼容层重新映射、且用户难以预期的值。

为什么 Claude Sonnet 用 max 而不是 xhigh？
Sonnet 的高档位应使用官方支持的 max；xhigh 主要用于 Opus 系列（如 claude-opus-4-7 / claude-opus-4-8）。

为什么 Claude Haiku 和 MiniMax M3 没有 variants？
没有明确可用于 OpenCode reasoningEffort 的官方档位时，不建议强行配置。模型仍可正常对话，只是 UI 不显示 Reasoning 子档位。

配置后仍然报 400 怎么办？

检查 baseURL 是否为 https://apimaster.ai/v1（不是根域名）。
检查模型 ID 拼写是否与模型广场一致。
确认 API Key 已通过 /connect 或 UI 连接提供商 正确配置。
临时删除该模型的 variants，确认普通请求是否成功。
若普通请求成功、带 Reasoning 失败，说明该模型或当前 provider 不支持 所选的 reasoning_effort 值，请换档位或换模型。

安全注意事项

不要把 API Key 发到群聊、公开截图或未打码的文档。
Key 若曾出现在截图或聊天记录中，请到控制台 作废并重新生成，再在 OpenCode 里更新 Provider。
OpenCode 会在本机工作区读写文件、执行命令，请只在可信目录中使用。

配置检查清单

OpenCode Desktop 已安装并能打开工作区
设置 → 提供商 → 自定义提供商 已连接（或 opencode.jsonc 已配置 apimaster provider）
提供商 ID = apimaster，显示名称 = APIMaster.ai
基础 URL / baseURL = https://apimaster.ai/v1（不是 https://apimaster.ai/）
API Key 通过 /connect 或 UI 配置（未写入 jsonc）
至少添加一个对话类 model id
模型下拉中可选 APIMaster.ai 下的模型
（可选）Reasoning variants 已按模型官方档位配置
发送测试消息有正常回复

总结

APIMaster 作为 OpenAI-compatible provider 接入 OpenCode 时，关键是 baseURL（https://apimaster.ai/v1）、模型 ID、API Key（通过 /connect 或 UI，不写 jsonc）、以及可选的 Reasoning variants。
Reasoning 的 variant 名称应与 reasoning_effort 实际值一致，便于用户在 UI 中知道发送了什么参数。
不同模型按官方支持的档位配置，不做隐藏映射；无明确档位的模型（如 Haiku、MiniMax M3）可不配 variants。