OpenCode AI API密钥设置 — 兼容OpenAI的配置指南

了解如何通过APIMaster.ai的自定义API密钥配置OpenCode AI。在opencode.jsonc中将APIMaster添加为兼容OpenAI的提供商，即可访问Claude、GPT-5.5和DeepSeek，支持图片输入（Vision）与可选推理层级。

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 对话。

需要图片识别（Vision）？ gpt-5.5、claude-sonnet-4-6、claude-opus-4-7、claude-opus-4-8、claude-haiku-4-5 等模型支持读取图片输入，但在 OpenCode 里还需额外声明能力，见配置 GPT 和 Claude 的图片输入能力。

第 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。

也不要写成 https://api.apimaster.ai/v1：该带 api. 前缀的地址在测试中可能出现 TLS / 连接失败。正确域名是 https://apimaster.ai/v1。

完整示例（含 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.5": {
          "name": "gpt-5.5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "high": { "reasoningEffort": "high" }
          }
        }
      }
    }
  }
}

上面 gpt-5.5 里的 attachment 与 modalities 用于启用图片输入（Vision），详见下方配置 GPT 和 Claude 的图片输入能力。仅需文字对话时可省略这两个字段。

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-fable-5`	`low`, `medium`, `high`, `xhigh`, `max`	Fable 5（Opus 4.8 升级款）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 档位间循环切换。

配置 GPT 和 Claude 的图片输入能力

APIMaster.ai 的 gpt-5.5、claude-sonnet-4-6、claude-opus-4-7、claude-opus-4-8、claude-haiku-4-5 等模型都支持图片输入 / Vision：可以读取截图、照片、图表等做识别、描述、OCR、看图写代码。

关键：模型支持图片 ≠ OpenCode 会把图片传给模型。 即使 APIMaster.ai 的模型本身支持图像识别，也必须在 opencode.jsonc 中为该模型声明能力。否则 OpenCode 可能不会把图片内容作为多模态输入发送，而只是把附件名 / 文件名塞进 prompt，导致模型回复类似「当前模型不支持读取图片输入」。

需要声明的两个字段

为每个要用于图片的模型加上：

"attachment": true,
"modalities": {
  "input": ["text", "image"],
  "output": ["text"]
}

attachment: true：告诉 OpenCode 这个模型允许发送附件。
modalities.input 包含 "image"：告诉 OpenCode 这个模型支持图片输入，OpenCode 才会把图片转成多模态 image_url 内容发出。

完整示例（覆盖 GPT 和 Claude）

可直接下载 opencode.jsonc（已内置以下字段），或把下面 provider.apimaster 段合并进你现有配置：

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": [],
  "provider": {
    "apimaster": {
      "name": "APIMaster.ai",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://apimaster.ai/v1"
      },
      "models": {
        "gpt-5.5": {
          "name": "gpt-5.5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" }
          }
        },
        "claude-sonnet-4-6": {
          "name": "claude-sonnet-4-6",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-opus-4-7": {
          "name": "claude-opus-4-7",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-opus-4-8": {
          "name": "claude-opus-4-8",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-haiku-4-5": {
          "name": "claude-haiku-4-5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

说明：

只想启用 gpt-5.5 的图片输入，就只给 gpt-5.5 加 attachment 和 modalities；其它模型可不动。
只想启用 Claude，就只给 Claude 模型加这些字段。
保留各模型原有的 Reasoning variants（low / medium / high / xhigh / max），图片字段与 Reasoning 互不冲突。
修改 opencode.jsonc 后必须完全退出并重启 OpenCode，或至少新建一个会话，让配置重新加载。
API Key 不要写进这个文件，仍通过 /connect 或 UI 连接提供商 配置（见下方安全说明）。

关于图片来源：优先本地上传 / base64

推荐在 OpenCode 里上传本地 PNG / JPG。理想情况下 OpenCode 会把图片转成 base64 data URL（data:image/png;base64,...）再传给 APIMaster——这是已验证成功的方式。
直接传公网图片 URL 可能失败。APIMaster / 上游在下载公网图片时可能因网络、格式、大小、MIME、反盗链等原因返回：
```
Error while downloading file. Upstream status code: 400.
```
遇到此类报错，请改用 base64 data URL 或本地图片上传，不要依赖模型端去下载公网 URL。

测试图片识别是否生效

方式一：在 OpenCode 中测试

在模型下拉里切换到 apimaster/gpt-5.5 或 apimaster/claude-sonnet-4-6。
上传一张 PNG / JPG 图片。

输入：

请描述这张图片的主要内容。

配置正确时，模型应能描述图片内容。
若模型只提到文件名 / 附件名，或回复「不支持读取图片输入」，通常说明 OpenCode 没有把图片内容真正传给模型——回去检查该模型的 attachment 与 modalities 字段，并重启 OpenCode。

方式二：用 API 直接测试

用于区分「APIMaster 模型问题」还是「OpenCode 适配层问题」。请勿写入真实 Key，用环境变量。

Linux / macOS：

export APIMASTER_API_KEY="你的 APIMaster API Key"

curl https://apimaster.ai/v1/chat/completions \
  -H "Authorization: Bearer $APIMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "请描述这张图片。" },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,这里放图片base64"
            }
          }
        ]
      }
    ],
    "max_tokens": 1000
  }'

把 model 换成 claude-sonnet-4-6 即可用同样方式测试 Claude（已验证返回 HTTP 200 且能识别图片）。

Windows PowerShell：

$env:APIMASTER_API_KEY = "你的 APIMaster API Key"
# 将本地图片转成 base64 后，作为 data:image/png;base64,... 放入 image_url.url
# 再用相同 JSON 请求体调用 https://apimaster.ai/v1/chat/completions

返回 200 且能描述图片，说明 APIMaster 侧图片输入正常；此时若 OpenCode 内仍不识别，问题在 OpenCode 的 attachment / modalities 配置或未重启。

常见问题

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 值，请换档位或换模型。

图片输入 / Vision

为什么 OpenCode 里提示「当前模型不支持读取图片」？

APIMaster.ai 的 gpt-5.5 和部分 Claude 模型本身支持图片输入，这个提示通常说明 OpenCode 没有把图片作为多模态输入传给模型。

检查 opencode.jsonc 里对应模型是否配置了：

"attachment": true,
"modalities": {
  "input": ["text", "image"],
  "output": ["text"]
}

确认改配置后已重启 OpenCode。
确认 baseURL 为 https://apimaster.ai/v1。
确认 APIMaster API Key 有效。
若用公网图片 URL 失败，改用 base64 data URL 或本地图片上传。

为什么模型只看到附件名、看不到图片内容？

通常是 OpenCode 没有把附件读取并转成图片输入，而是只把附件名 / 文件名放进 prompt。
请启用 attachment: true 和 modalities.input: ["text", "image"]，并使用支持图片输入的模型。

为什么公网图片 URL 报错？

APIMaster 或上游下载公网图片时可能受网络、格式、文件大小、MIME、反盗链或代理限制。
若出现 Error while downloading file. Upstream status code: 400.，请改用 base64 data URL。

配置了 attachment 后还是不生效怎么办？

完全退出并重启 OpenCode。
新建一个会话再测试。
检查当前会话实际使用的 model 是否就是已配置图片字段的那个模型。
检查 API Key 是否有效。
检查 OpenCode 日志是否有 401 / 400 / unsupported image / invalid content type 等错误。
用方式二：API 直接测试 base64 图片，区分是 APIMaster 模型问题还是 OpenCode 适配层问题。

安全注意事项

不要把 APIMaster API Key 写入 opencode.jsonc；该文件只放 Provider、模型、图片能力与 Reasoning。
不要把 Key 贴到聊天、截图、issue、公开文档或代码仓库。
Key 若曾出现在截图或聊天记录中，请立即到控制台 作废并重新生成，再在 OpenCode 里更新 Provider。
推荐通过 OpenCode 的 /connect 连接流程、环境变量或本地凭据存储管理 API Key。
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 已按模型官方档位配置
发送测试消息有正常回复

图片输入检查清单

baseURL 为 https://apimaster.ai/v1（不是 https://api.apimaster.ai/v1）
使用支持图片输入的模型，例如 gpt-5.5 或支持 Vision 的 Claude 模型
对应模型已配置 attachment: true
对应模型的 modalities.input 包含 "image"
修改 opencode.jsonc 后已重启 OpenCode
API Key 有效
测试图片为常见格式（PNG / JPG）
若公网图片 URL 失败，已改用 base64 data URL

总结

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。