在 OpenCode 中使用

OpenCode 是开源的终端编码助手，支持自由切换底层 provider。本网关 OpenAI 兼容入口可以作为 OpenCode 的一个自定义 provider。

前置要求

• 已经在网关后台拿到 API Token（参考 快速开始）

1. 安装 OpenCode

任选一种：

# 一行安装脚本（macOS / Linux）
curl -fsSL https://opencode.ai/install | bash

# npm
npm install -g opencode-ai

# Homebrew
brew install sst/tap/opencode

# Arch
yay -S opencode-bin

验证：

opencode --version

2. 注册自定义 provider

编辑 ~/.config/opencode/opencode.json（不存在就新建），加一段 provider 配置：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "zc-api": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ZC API Gateway",
      "options": {
        "baseURL": "https://api.geoq.help/v1"
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o"
        },
        "claude-sonnet-4-5": {
          "name": "Claude Sonnet 4.5"
        },
        "gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro"
        },
        "deepseek-chat": {
          "name": "DeepSeek Chat"
        }
      }
    }
  }
}

字段说明：

字段	含义
npm	用哪个 provider 适配包，OpenAI 兼容统一用 @ai-sdk/openai-compatible
options.baseURL	网关 OpenAI 兼容入口，末尾要带 /v1
models	在 OpenCode 模型列表里展示哪几个，key 是真实 model id

3. 设置 API Key

OpenCode 用 provider id 大写 + _API_KEY 的环境变量约定：

export ZC_API_API_KEY="sk-你的Token"

或用 OpenCode 内置的密钥管理：

opencode auth login
# 按提示选 zc-api，粘贴 Token

写进 ~/.zshrc / ~/.bashrc 让它持久化。

4. 启动

opencode

进入界面后按 Tab 或输入 /models 切换模型，选刚才在 models 里登记的任一项。

5. 验证

> 解释下当前项目的入口文件

正常返回响应 + 后台 日志 页面有调用记录，就接通了。

6. 常见问题

模型列表里看不到 zc-api

• opencode.json 路径不对：macOS / Linux 是 ~/.config/opencode/opencode.json，Windows 是 %APPDATA%\opencode\opencode.json
• JSON 语法错了：用 cat ~/.config/opencode/opencode.json | jq . 验证

报错：401 Unauthorized 环境变量名错了。OpenCode 是按 provider id 推的，provider id 是 zc-api，对应变量 ZC_API_API_KEY（横杠转下划线，全大写，加 _API_KEY）。

想加更多模型 直接在 models 对象里加 key，model id 必须是网关后台 模型 页面真实存在的名字。

多 provider 共存opencode.json 的 provider 是个对象，可以同时挂 zc-api、anthropic、openai，互不影响。在模型选择器里用 provider/model 区分。

进阶

• 走代理：HTTPS_PROXY=http://127.0.0.1:7890 opencode
• 项目级覆盖：在项目根目录放 opencode.json，OpenCode 会优先用它
• 团队共享配置：把 opencode.json（不含密钥）提交进仓库，密钥仍走环境变量