OpenCode / opencode 接入

第 1 步：安装并准备

macOS
Windows
Linux

在终端（Bash / Zsh）运行：

curl -fsSL https://opencode.ai/install | bash
opencode --version

原生 Windows：先安装 Node.js / npm，在 PowerShell 运行：

npm install -g opencode-ai
opencode --version

官方推荐 WSL 以获得更完整的终端体验；使用 WSL 时，在其 Linux 终端按 Linux 栏安装，后续 Key、配置和启动也都在 WSL 中完成。

在 Bash 终端运行（也适用于 WSL）：

curl -fsSL https://opencode.ai/install | bash
opencode --version

从 ABCRelay 开始使用准备 API Key 和当前 Key 可用的模型 ID。下文的 YOUR_ABCRELAY_API_KEY、YOUR_MODEL_ID 分别替换为这两个实际值。

第 2 步：配置 ABCRelay

按系统打开下方完整路径的用户配置。文件不存在时请新建此文件，文件名保持 opencode.json；已有 opencode.jsonc 或设置了 OPENCODE_CONFIG 时，改用实际文件，见 FAQ。将后面的 JSON 合并到该文件，把 options.apiKey 直接替换成真实 Key。

macOS
Windows
Linux

默认完整路径（可粘贴到编辑器的「打开」窗口；macOS 也可用 Finder → 前往 → 前往文件夹）：

~/.config/opencode/opencode.json

默认完整路径（可粘贴到资源管理器地址栏或编辑器的「打开」窗口）：

%USERPROFILE%\.config\opencode\opencode.json

默认完整路径（可粘贴到编辑器的「打开」窗口）：

~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "abcrelay": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ABCRelay",
      "options": {
        "baseURL": "https://www.abcrelay.com/v1",
        "apiKey": "YOUR_ABCRELAY_API_KEY"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "ABCRelay Model"
        }
      }
    }
  },
  "model": "abcrelay/YOUR_MODEL_ID"
}

两处 YOUR_MODEL_ID 替换为相同的实际 ID。本例用于 Chat Completions；保留已有 provider 和其他设置。Key 已保存在这个用户文件中，无需设置 shell 环境变量。不要将含真实 Key 的用户文件复制进项目或提交到仓库。 地址要带 /v1： 本页 @ai-sdk/openai-compatible 的 options.baseURL 填 https://www.abcrelay.com/v1；适配器追加 /chat/completions，最终请求为 https://www.abcrelay.com/v1/chat/completions。三个系统相同，不填完整接口路径。

第 3 步：发消息验证

保存后，新开终端运行（macOS / Linux 的 Bash 或 Zsh、Windows 的 PowerShell 命令相同）：

opencode models abcrelay
opencode

用 /models 选择 abcrelay/YOUR_MODEL_ID，发送「只回复 OK，不读取文件或运行工具」。收到回复后，到 ABCRelay 控制台核对同一时间、Key 和模型的请求记录。

常见问题与详细说明

连接失败或模型没出现怎么办？

现象	检查与处理
`401` / key 为空	检查用户配置中的 `options.apiKey` 已替换并保存，令牌是否过期或撤销。使用 `/connect` 备选方式时检查 ID 是否为 `abcrelay`，并删除旧 `options.apiKey`。
模型不出现在列表	检查 JSON 语法、文件位置、`provider.abcrelay` 与 `model` 前缀、两处模型 ID；检查 `enabled_providers` / `disabled_providers` 是否过滤了它。
`404` / 返回网页	`baseURL` 应为 `https://www.abcrelay.com/v1`；再核对适配器使用的 Chat Completions / Responses 接口是否已在渠道开放。
模型不存在 / 无权限	使用准确 API ID，核对令牌模型限制、分组和渠道；配置文件列出模型不会自动开通它。
`400` / 字段或响应格式不匹配	确认 `npm` 与协议一致，以及模型支持所发送的参数；不要仅靠换模型显示名称处理。
流式输出中断 / 工具执行失败	核对模型与渠道的工具、流式兼容性，以及反向代理是否缓冲 SSE；查看官方排障中的日志位置。分享日志前删除凭据。
额度不足 / `429`	检查账户、令牌预算与渠道限流，根据返回错误和控制台记录处理。
新终端失效 / 配置被覆盖	本页配置已持久保存；检查是否编辑了实际用户文件，以及项目级配置、自定义配置目录是否覆盖了它。

通用错误说明见故障排查；其他客户端见客户端接入目录。

不同适配器的地址要不要带 /v1？

OpenCode 官方对自定义 provider 的说明如下；不能仅凭本站使用 new-api 就假定每个渠道都支持两种接口。

模型实际使用的接口	配置中的 `npm`	基础地址
Chat Completions：`/v1/chat/completions`	`@ai-sdk/openai-compatible`	`https://www.abcrelay.com/v1`
Responses：`/v1/responses`	`@ai-sdk/openai`	`https://www.abcrelay.com/v1`
Anthropic Messages：`/v1/messages`	`@ai-sdk/anthropic`	`https://www.abcrelay.com/v1`

上面的配置示例用于 Chat Completions。只有在管理员确认所选模型支持 Responses 时，才把 npm 改为 @ai-sdk/openai。不要把 /chat/completions、/responses 或 /messages 写进 baseURL，适配器会追加路径。OpenCode 的 Anthropic 适配器也要带 /v1：AI SDK 追加的是 /messages，与 Claude Code CLI 追加 /v1/messages 的方式不同。切换模型品牌本身不会替你切换适配器；先确认模型支持所选接口。更多客户端见API 地址对照表。

可以让 OpenCode 单独保存 Key 吗？

可以。第 2 步直接把 Key 持久保存在用户配置；若希望凭据和 provider 配置分开，改用 OpenCode 内的 /connect → Other，provider ID 填 abcrelay，再输入自己的 ABCRelay API Key。随后从用户配置中删除 options.apiKey，保留 baseURL、npm、models 和 model，重新启动。/connect 只保存凭据，不会替你配置地址和模型。默认凭据文件是 ~/.local/share/opencode/auth.json，Windows 资源管理器路径为 %USERPROFILE%\.local\share\opencode\auth.json，PowerShell 路径为 $env:USERPROFILE\.local\share\opencode\auth.json；由客户端维护，无需手工改写。设置了 XDG_DATA_HOME 时，凭据文件位于该目录的 opencode/auth.json。不要提交或分享它。选定一种凭据方式，避免旧 options.apiKey 覆盖 /connect 保存的新 Key。

还有哪些安装方式？

macOS、Linux、WSL：在 Bash 或 Zsh 中使用官方脚本。

curl -fsSL https://opencode.ai/install | bash

已安装 Node.js / npm 时，macOS、Linux 和原生 Windows（PowerShell 或 CMD）都可用：

npm install -g opencode-ai

Windows 官方推荐 WSL；原生 Windows 也可用 choco install opencode 或 scoop install opencode。macOS / Linux 可用 brew install anomalyco/tap/opencode。更多平台包和二进制下载见官方安装入口。不要在 PowerShell / CMD 中直接粘贴 Bash 脚本命令。运行 opencode --version 确认安装；找不到命令时重开终端并检查安装路径是否在 PATH 中。WSL 的配置和凭据与原生 Windows 分开保存。

配置为什么被覆盖？桌面应用能共用吗？

本页配置 OpenCode CLI / TUI。用户文件不依赖某个终端，但远程服务与其他系统用户可能读取不同目录。若旧配置仍有 {env:ABCRELAY_API_KEY}，按第 2 步替换为实际 Key；不要混用旧变量引用和新凭据。相对于项目根目录的 ./opencode.json 会覆盖冲突的用户设置，自定义路径与管理员配置也可能影响结果；修改后重启并检查配置优先级。用户配置的另一种完整路径是 ~/.config/opencode/opencode.jsonc（Windows 资源管理器：%USERPROFILE%\.config\opencode\opencode.jsonc）。如果已有此文件，请直接编辑该文件，不要另建一份 JSON。OPENCODE_CONFIG 指定自定义文件，OPENCODE_CONFIG_DIR 指定配置目录，使用实际设置的路径。设置了 XDG_CONFIG_HOME 时，用户目录为 $XDG_CONFIG_HOME/opencode（PowerShell：$env:XDG_CONFIG_HOME\opencode）。真实 Key 不要写入项目配置。

聊天成功后，编码功能还要验证什么？

模型列表只说明客户端加载了配置。编码任务还需核对模型的工具调用、流式输出及真实上下文限制。small_model、自定义 agent 和命令可以另外选模型；它们失败时检查对应配置。不要照搬其他模型的上下文和输出上限。

Windows 的路径写法为什么不同？

PowerShell 的用户目录变量是 $env:USERPROFILE；%USERPROFILE% 是资源管理器 / CMD 的写法。Key 直接保存在第 2 步的用户 JSON 中，不需要 PowerShell 或 CMD 的环境变量命令。使用 WSL 时，按 Linux 路径保存配置；原生 Windows 与 WSL 的文件及登录环境分开。

资料来源与验证范围

官方文档核对日期：2026-09-10。本页尚未完成 OpenCode 对本站的客户端实测。请先确认令牌、模型及渠道支持的协议，再按对应方式配置。

开始使用

官方桌面应用

图形聊天

终端编程

编辑器与插件

代理系统

帮助

OpenCode / opencode 接入

第 1 步：安装并准备

第 2 步：配置 ABCRelay

第 3 步：发消息验证

常见问题与详细说明

​第 1 步：安装并准备

​第 2 步：配置 ABCRelay

​第 3 步：发消息验证

​常见问题与详细说明

第 1 步：安装并准备

第 2 步：配置 ABCRelay

第 3 步：发消息验证

常见问题与详细说明