OpenCode

• 官方主页：opencode.ai
• 安装文档：opencode.ai/docs
• 网关配置：opencode.ai/docs/providers · opencode.ai/docs/config
• 协议类型：OpenAI Chat Completions（通过 @ai-sdk/openai-compatible，端点 /v1/chat/completions）

安装

官方推荐使用安装脚本，也提供包管理器方式。其余写法以官方安装文档为准。

安装脚本（推荐，macOS / Linux / WSL）

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

Node.js 包管理器（任选其一）

npm install -g opencode-ai
pnpm install -g opencode-ai
bun install -g opencode-ai
yarn global add opencode-ai

Homebrew（macOS / Linux）

brew install anomalyco/tap/opencode

Windows

官方推荐在 WSL 中按 macOS / Linux 方式安装；也可用包管理器：

choco install opencode
scoop install opencode
npm install -g opencode-ai

安装完成后用 opencode --version 确认版本。

对接 TokenBay

OpenCode 默认走 OpenCode Zen 等内置提供方。要改走 TokenBay，需在配置文件 opencode.json 中注册一个自定义 provider：

• npm 用 @ai-sdk/openai-compatible，表示走标准 Chat Completions 协议；
• options.baseURL 指向 TokenBay 网关；
• 凭证可写在 options.apiKey（支持 {env:变量名} 引用环境变量），或通过 /connect 命令存入 OpenCode 的凭证库；
• models 列出可用模型，其键名必须与 TokenBay 的模型 ID 完全一致，否则模型选择器里不会出现。

Base URL 注意：@ai-sdk/openai-compatible 会在 baseURL 后追加 /chat/completions。因此 baseURL 必须写成 https://api.tokenbay.com/v1（带 /v1），而不是裸的 https://api.tokenbay.com，否则会 404。

1. 获取 API Key

登录 TokenBay 控制台 → API 密钥 → 创建密钥。复制以 sk- 开头的完整字符串。明文仅显示一次，离开页面后无法再查看。

2. 配置环境变量

推荐用环境变量保存凭证，再在配置文件里用 {env:TOKENBAY_API_KEY} 引用，避免把密钥明文写进配置：

macOS / Linux（zsh 或 bash）

把下面这行追加到 ~/.zshrc 或 ~/.bashrc，然后执行 source ~/.zshrc 让其生效：

export TOKENBAY_API_KEY="sk-XXXXXXX"

Windows（PowerShell，写入用户级环境）

[Environment]::SetEnvironmentVariable('TOKENBAY_API_KEY','sk-XXXXXXX','User')

Windows（CMD）

setx TOKENBAY_API_KEY "sk-XXXXXXX"

PowerShell 与 CMD 的写法都是永久化用户环境变量，需要新开一个终端窗口才会读到。

3. 写入 OpenCode 配置文件

OpenCode 的配置文件有两个常用位置，后者优先级更高：

项目级 opencode.json 可随项目提交到 Git，与全局配置使用同一套 schema。建议把通用的 provider 配置放在全局，仅在个别项目用项目级文件覆盖。

文件不存在则新建，写入以下内容（以全局配置为例）：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenbay": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TokenBay",
      "options": {
        "baseURL": "https://api.tokenbay.com/v1",
        "apiKey": "{env:TOKENBAY_API_KEY}"
      },
      "models": {
        "claude-sonnet-4.6": { "name": "Claude Sonnet 4.6" },
        "claude-opus-4.8": { "name": "Claude Opus 4.8" },
        "claude-haiku-4.5": { "name": "Claude Haiku 4.5" },
        "gpt-5.3-codex": { "name": "GPT-5.3 Codex" }
      }
    }
  },
  "model": "tokenbay/claude-sonnet-4.6"
}

字段说明：

备选：用 /connect 存凭证。如果不想用环境变量，可在 OpenCode 的 TUI 里运行 /connect，下拉选择 Other，输入 provider ID tokenbay，再粘贴 API Key。凭证会存入 ~/.local/share/opencode/auth.json，此时可省略上面的 options.apiKey，但 provider.tokenbay 的 baseURL 与 models 仍需在配置文件中定义。

4. 推荐模型

模型 ID 直接透传上游，无前缀。在 OpenCode 中选择模型时需带上 provider 前缀，即 tokenbay/claude-sonnet-4.6。

模型名格式：TokenBay 的模型名称中版本号仅接受小数点形式（如 claude-sonnet-4.6），不要写成连字符形式（claude-sonnet-4-6）。

上表为示例，准确的 Model ID、模态与端点以 控制台 Models 页面（或 模型清单）为准；接入前请核对并确认所属分组已授权该模型。

5. 进阶配置

复杂推理或长上下文任务耗时较长，默认超时可能导致请求中断。OpenCode 在 provider 的 options 里提供 timeout、chunkTimeout 等超时项；也可声明每个模型的上下文/输出上限（limit），让 OpenCode 正确显示剩余上下文，并用 headers 透传自定义请求头：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenbay": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TokenBay",
      "options": {
        "baseURL": "https://api.tokenbay.com/v1",
        "apiKey": "{env:TOKENBAY_API_KEY}",
        "timeout": 600000,
        "chunkTimeout": 30000
      },
      "models": {
        "claude-sonnet-4.6": {
          "name": "Claude Sonnet 4.6",
          "limit": { "context": 200000, "output": 64000 }
        }
      }
    }
  },
  "model": "tokenbay/claude-sonnet-4.6"
}

limit 中的数值为示例，请以 控制台 Models 页面 标注的各模型上下文/输出上限为准。