OpenCode

安装 OpenCode，并通过自定义 provider 调用 TokenHub OpenAI 兼容接口。

OpenCode 当前推荐通过自定义 provider 接入 OpenAI 兼容服务。TokenHub 的 OpenAI 兼容 Base URL 是 https://us-api.tokenhub.com/v1，OpenCode 配置里要把它写到 options.baseURL，并使用 @ai-sdk/openai-compatible provider 包。

本教程使用的 TokenHub endpoint 是 https://us-api.tokenhub.com/v1/chat/completions。

适合场景

OpenCode 适合本地优先的代码阅读、编辑和自动化开发流。首次接入 TokenHub 时，先用只读任务验证模型、Key、Base URL 和 OpenCode provider 都生效，再授权它修改文件或运行命令。

安装 OpenCode

先参考 OpenCode 官方文档安装或升级。不同平台的安装入口可能变化，以官方文档当前版本为准。

确认命令可用：

opencode --version

如果命令不可用，重开终端或检查安装目录是否加入 PATH。

准备 TokenHub 凭证

在 TokenHub 工作台创建 API Key，并在本地终端中保存为环境变量：

export TOKENHUB_API_KEY="sk-..."

模型必须使用 TokenHub 模型列表中的真实 Model ID。下面示例使用 gpt-4.1，如果你的工作区没有这个模型，请替换成模型列表里可用的 ID。

可先用模型列表接口确认 Key 和网络：

curl "__API_BASE_URL__/v1/models" \
  -H "Authorization: Bearer $TOKENHUB_API_KEY"

写入 OpenCode 配置

OpenCode 可以读取用户级配置，也可以读取项目级 opencode.json。建议优先使用用户级配置，团队项目里只提交不含真实密钥的默认值。

配置位置	适合场景
`~/.config/opencode/opencode.json`	当前用户长期使用 TokenHub。
项目内 `opencode.json`	团队共享 provider 名称、Base URL 和默认模型等非密钥配置。
`/connect`	进入 OpenCode 后切换或确认当前会话使用的是 TokenHub provider。

示例配置：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenhub": {
      "name": "TokenHub",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "__API_BASE_URL__/v1",
        "apiKey": "{env:TOKENHUB_API_KEY}"
      },
      "models": {
        "gpt-4.1": {
          "name": "gpt-4.1"
        }
      }
    }
  },
  "model": "tokenhub/gpt-4.1"
}

这里的 tokenhub 是你在 provider 里定义的 provider 名称。启动或切换模型时也要使用同一个前缀：

opencode models tokenhub
opencode --model tokenhub/gpt-4.1

不要把 provider 前缀写成 openai/...。那会选择 OpenCode 的 openai provider，而不是上面配置的 TokenHub provider。

启动和切换 provider

进入项目后启动 OpenCode：

opencode --model tokenhub/gpt-4.1

在交互界面中可以执行：

/connect

确认当前会话选中的是 TokenHub provider，并且模型显示为 tokenhub/gpt-4.1 或你配置的其它 TokenHub 模型。

验证

先执行只读任务：

请只读分析当前项目，并列出一次安全的验证命令。不要修改文件。

看到 OpenCode 正常返回后，到 TokenHub 请求日志里确认请求的模型名、endpoint、token 用量和计费分组。确认无误后，再允许 OpenCode 编辑文件或运行命令。

常见问题

现象	处理方式
Provider 不出现	确认配置文件路径正确，`provider.tokenhub.npm` 是 `@ai-sdk/openai-compatible`，再运行 `opencode models tokenhub`。
401	确认启动 OpenCode 的终端能读取 `TOKENHUB_API_KEY`，并且 Key 来自 TokenHub 工作台。
404	确认 `options.baseURL` 是 `https://us-api.tokenhub.com/v1`，模型名同时存在于 TokenHub 模型列表和 `models` 配置中。
命令仍走 OpenAI provider	启动参数必须是 `tokenhub/<model>`；`openai/<model>` 会切到 OpenCode 的 OpenAI provider。
模型没有出现在列表中	在 `models` 中添加真实 TokenHub Model ID，然后重新启动 OpenCode。
工具要修改太多文件	先让 OpenCode 输出计划，再限定一次只改 1 到 2 个文件。