opencode 接入第三方中转站（xh.v1api.cc）配置教程

本教程介绍如何让 opencode 使用兼容 OpenAI 格式的第三方中转站 https://xh.v1api.cc。

一、前置准备

安装 opencode（任选其一）：

# npm
npm install -g opencode-ai

# 或 Homebrew (macOS)
brew install sst/tap/opencode

# 或官方脚本
curl -fsSL https://opencode.ai/install | bash

在中转站获取你的 API Key（形如 sk-xxxx）。

二、配置文件位置

opencode 使用 JSON 配置文件，常用两个位置：

位置	路径	说明
全局配置	`~/.config/opencode/opencode.json`	对所有项目生效，推荐放这里
项目配置	项目根目录下的 `opencode.json`	仅对当前项目生效，优先级高于全局配置

三、核心配置

创建或编辑 ~/.config/opencode/opencode.json，写入以下内容：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "xhv1api": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "XH V1API 中转站",
      "options": {
        "baseURL": "https://xh.v1api.cc/v1",
        "apiKey": "{env:XH_V1API_KEY}"
      },
      "models": {
        "gpt-4o": { "name": "GPT-4o" },
        "gpt-4o-mini": { "name": "GPT-4o Mini" },
        "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
        "deepseek-chat": { "name": "DeepSeek Chat" }
      }
    }
  },
  "model": "xhv1api/gpt-4o"
}

字段说明：

xhv1api：provider 的唯一 ID，可自定义，但后面 model 字段要保持一致。
npm：固定用 @ai-sdk/openai-compatible，表示走 OpenAI 兼容的 /v1/chat/completions 接口。
options.baseURL：中转站地址，注意结尾是 /v1，不要带 /chat/completions（opencode 会自动拼接）。
options.apiKey：{env:XH_V1API_KEY} 表示从环境变量读取密钥，避免明文写进配置文件。
models：模型列表。key 必须与中转站实际支持的模型 ID 完全一致，以上仅为常见示例，请根据中转站提供的模型列表增删。
model：默认模型，格式为 provider ID/模型 ID。
还可以配置 "small_model": "xhv1api/gpt-4o-mini"，用于标题生成等轻量任务，节省费用。

四、设置 API Key 环境变量

将密钥写入 shell 配置文件（zsh 为例）：

echo 'export XH_V1API_KEY="sk-你的密钥"' >> ~/.zshrc
source ~/.zshrc

注意：必须使用 export，否则 opencode 作为子进程读不到该变量，会导致 401 错误。

如果不想用环境变量，也可以直接把密钥明文写在 apiKey 字段里（不推荐提交到 git 仓库）。

五、验证配置

（可选）先用 curl 确认中转站和密钥可用：

curl https://xh.v1api.cc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XH_V1API_KEY" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "hi"}]}'

启动 opencode：
```
opencode
```
在 TUI 中输入 /models，应能看到 XH V1API 中转站 下配置的模型，选择一个模型发送消息测试即可。

六、常见问题排查

现象	常见原因及解决方法
401 / 403	密钥错误，或 `{env:XH_V1API_KEY}` 变量未 export；重新 `source ~/.zshrc` 后重启 opencode
404	`baseURL` 写错（如多写了 `/chat/completions`），应为 `https://xh.v1api.cc/v1`
模型列表为空	`models` 未声明，或 `model` 字段里的 provider ID 与配置的不一致
提示模型 ID 无效	`models` 的 key 与中转站接受的模型名不一致，以中转站文档为准
改了配置不生效	修改配置后需要重启 opencode
JSON 解析报错	配置文件语法错误，可用 `python3 -m json.tool ~/.config/opencode/opencode.json` 校验

七、补充说明

若中转站某些模型走的是 /v1/responses 接口（而非 /v1/chat/completions），需将 npm 改为 @ai-sdk/openai。
项目级 opencode.json 可用于给不同仓库固定不同的模型，配置格式相同。
更多配置项参见官方文档：https://opencode.ai/docs/providers/