工具集成/OpenCode 接入

通过 OpenAI 兼容 provider，把 UniGateway 接入 OpenCode。

OpenCode 接入

OpenCode 是一款专为终端设计的 AI 编程智能体。通过将 OpenCode 接入 UniGateway，你可以通过单一统一端点访问多种模型，实现集中密钥管理、自动回退，且无需修改任何上游 SDK。

兼容性说明

UniGateway 完全支持 OpenAI Chat Completions 协议，可以通过 OpenAI 兼容提供者无缝接入 OpenCode。配置使用 @ai-sdk/openai-compatible npm 包，并将 baseURL 指向 UniGateway 端点。

注意 baseURL 必须以 /v1 结尾 — 完整 URL 为 https://api.unigateway.ai/v1。OpenCode 会自动拼接后续路径（如 /chat/completions），因此请不要省略 /v1 后缀，也不要重复添加。

OpenCode 依赖工具调用（function calling）完成多步编程工作流。请确保所选模型支持工具使用 — UniGateway 上大多数模型都支持，详情参见 接口兼容矩阵。

配置

第一步：安装 OpenCode

OpenCode 提供多种安装方式，你可以根据自己的系统环境选择合适的方法：

  • 快速安装（推荐） — 运行以下命令：
curl -fsSL https://opencode.ai/install | bash
  • npm / pnpm / yarn / bun — 全局安装：
npm i -g opencode-ai@latest
  • Homebrew（macOS 和 Linux）：
brew install sst/tap/opencode
  • Scoop / Chocolatey（Windows）：
scoop bucket add extras
scoop install extras/opencode

choco install opencode

更多安装选项和说明，请参考 OpenCode 官方文档。

第二步：配置 OpenCode

找到或创建 OpenCode 配置文件（opencode.json），将以下内容粘贴进去：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "unigateway": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.unigateway.ai/v1"
      },
      "models": {
        "gpt-5.5": {
          "name": "gpt-5.5"
        }
      }
    }
  }
}

重要： models 字段中的模型名称（如 gpt-5.5）应与 GET /v1/models 返回的模型 ID 一致 — 参见 模型列表。你可以随时切换到其他支持的模型。

模型推荐

建议添加不同能力和价格梯度的模型以适应各种使用场景：

  • 高复杂度任务（多文件重构、调试、复杂逻辑）：claude-sonnet-4-6、gpt-5.2
  • 均衡任务（通用编程、解释）：gemini-2.5-pro、gpt-4.1
  • 快速迭代（简单编辑、问答）：gpt-4.1-mini、deepseek-chat

第三步：登录 UniGateway

运行以下命令开始登录流程：

opencode auth login

在提供商选择界面选择 Other，输入提供商 ID unigateway，然后输入你的 UniGateway API Key。

重要： 你必须选择 Other（而非预列出的提供商），并输入 unigateway 作为提供商 ID。

获取 API Key

你可以在 UniGateway 控制台 中获取或创建你的 API Key。

第四步：开始对话

启动 OpenCode，输入一条简单的消息验证连接：

opencode

输入消息确认收到回复。使用 /models 命令随时查看和切换可用模型。

验证清单

检查项需要确认
认证正常OpenCode 接受你的 API Key，未触发 401/403 错误
聊天正常OpenCode 对提示返回非空响应
模型可用配置的模型出现在模型选择列表中
工具调用正常OpenCode 能读取文件、运行命令、编写代码

使用体验

配置完成后，OpenCode 作为由 UniGateway 模型驱动的终端编程智能体工作：

  • 终端编程 — 直接在终端中与 AI 交互完成编程任务
  • 工具调用 — 模型可以使用工具与文件系统、终端和浏览器交互
  • 模型切换 — 使用 /models 随时在模型间切换
  • 自动回退 — 配合 模型选择与回退，请求在备用模型上自动重试

工具调用兼容性

不同模型的工具调用支持程度不同。当模型不支持工具调用时，OpenCode 将回退到纯文本模式。参见 接口兼容矩阵 了解各模型对工具使用的支持情况。

故障排除

API Key 错误

问题： OpenCode 提示 API Key 无效或未授权。

解决方案：

  • 检查 API Key 是否复制正确，避免多余空格或换行
  • 确认 API Key 已激活且账户余额充足
  • 验证 API Key 格式
  • 重新运行 opencode auth login 并重新配置

配置文件未找到

问题： OpenCode 无法找到或读取配置文件。

解决方案：

  • 确保 opencode.json 位于正确位置（项目根目录或主目录）
  • 检查 JSON 语法是否正确 — 可使用 JSON 验证器检查
  • 确保 $schema、provider 和 models 字段均已填写

模型不可用

问题： 配置的模型无响应或返回 404。

解决方案：

  • 确认 opencode.json 中的模型 ID 与 GET /v1/models 返回的完全一致 — 一个字符的差异会导致 404
  • 验证 baseURL 设置为 https://api.unigateway.ai/v1（注意 /v1 后缀）
  • 在 OpenCode 中使用 /models 检查当前可用的模型

认证提供商错误

问题： opencode auth login 中提供商选择步骤无法完成。

解决方案：

  • 确保你选择了 Other（而非预列出的提供商），并输入了 unigateway 作为提供商 ID
  • 确认 opencode.json 中的 provider.unigateway 部分正确使用了 @ai-sdk/openai-compatible npm 包
  • 重新运行 opencode auth login 并仔细遵循提供商选择步骤

工具调用不工作

问题： OpenCode 能返回文本，但无法执行工具（文件读取、命令运行等）。

解决方案：

  • 确认模型支持工具使用 — 并非所有模型都支持函数调用
  • 切换到已知支持工具调用的模型（如 claude-sonnet-4-6、gpt-4.1）
  • 参见 接口兼容矩阵 查看支持工具的模型列表

流式响应异常

问题： 响应被截断或流式行为异常。

解决方案：

  • 检查模型是否支持流式响应 — 参见 流式响应
  • 在 OpenCode 日志中检查原始请求/响应的错误详情
  • 如果输出被截断，检查 token 限制设置

参见