OpenCode 接入
在 opencode.json 里注册一个指向 JuCode 的自定义 provider。
OpenCode 的 provider 配置分成两半,这是接入时最容易卡住的地方:
- 凭证由
/connect命令录入,存在~/.local/share/opencode/auth.json - 地址和模型列表写在
opencode.json里
两边靠 provider id 对上。/connect 时填的 id 和配置文件里的 key 不一致,表现就是
模型压根不出现在 /models 列表里,或者出现了但一调就 401。
另一件要提前知道的事:OpenCode 的模型元数据来自 models.dev, JuCode 的模型名不在上面,所以上下文窗口和最大输出得你自己在配置里写。
安装
curl -fsSL https://opencode.ai/install | bash也可以用 npm:npm install -g opencode-ai。
配置
录入凭证
启动 opencode,运行 /connect,在 provider 列表里拉到最下面选 Other,然后:
- 输入 provider id,填
jucode - 粘贴你的 API Key(
sk-juc-开头)
记住这个 id
下一步配置文件里的 key 必须是同一个字符串。
不想走这一步的话,可以跳过 /connect,直接在配置里写 options.apiKey,见第三步。
写配置文件
放在 ~/.config/opencode/opencode.json,对所有项目生效。
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"jucode": {
"npm": "@ai-sdk/openai-compatible",
"name": "JuCode",
"options": {
"baseURL": "https://api.jucode.cn/v1"
},
"models": {
"gpt-5.4": {
"name": "GPT-5.4",
"limit": { "context": 1050000, "output": 128000 }
},
"gpt-5.4-mini": {
"name": "GPT-5.4 mini"
}
}
}
},
"model": "jucode/gpt-5.4",
"small_model": "jucode/gpt-5.4-mini"
}几个要点:
npm选@ai-sdk/openai-compatible,它走/v1/chat/completions。官方文档里另一个 选项@ai-sdk/openai走/v1/responses——JuCode 也提供那个端点,但它恒为流式, 没必要为此多绕一层。baseURL带/v1。- 顶层
model的格式是provider/model,前半段就是 provider id。 small_model是标题生成之类轻量任务用的模型,不写的话 OpenCode 会自己挑一个更便宜 的,挑不到就退回主模型。limit.context和limit.output填/v1/models返回的context_window和max_output_tokens。不填 OpenCode 就无法判断还剩多少上下文,因为它拿不到 models.dev 上的数据。
直接在配置里给 Key(可选)
跳过 /connect 的话,把 Key 写进 options:
"options": {
"baseURL": "https://api.jucode.cn/v1",
"apiKey": "{env:JUCODE_API_KEY}"
}{env:...} 找不到变量时会被替换成空字符串
不会报错,不会警告。所以变量名拼错的表现是 401,而不是一句明确的变量未设置。配好之后先
echo $JUCODE_API_KEY 确认一下。
验证
确认模型出现在选择器里
启动 opencode,运行 /models。JuCode 分组和你在 models 里列出的模型应该都在。
不在就说明配置没被读到,或者 provider id 对不上。
发一个请求
opencode run "用一句话解释什么是幂等性"用 Anthropic 端点
想让 OpenCode 调 JuCode 上的 claude-* 模型,覆盖内置 anthropic provider 的地址
即可:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"baseURL": "https://api.jucode.cn/anthropic/v1",
"apiKey": "{env:JUCODE_API_KEY}"
}
}
},
"model": "anthropic/claude-sonnet-5"
}这里的 baseURL 要带 /v1
和 Anthropic 官方 SDK 的写法不同。官方 SDK 填到 https://api.jucode.cn/anthropic
为止,由 SDK 自己拼 /v1/messages;OpenCode 底层用的是 AI SDK,它的 baseURL 默认值
就是 https://api.anthropic.com/v1,所以要写成 https://api.jucode.cn/anthropic/v1。
内置 anthropic provider 的模型列表来自 models.dev,里面的名字和 JuCode 上实际可用的
不一定对得上。对不上就自己在 provider.anthropic.models 里补一条,写法和上面自定义
provider 一样。
排查
按可能性排序:
-
provider id 不一致。
/connect时填的 id 和opencode.json里的 key 必须 完全相同。跑opencode auth list对一下。 -
{env:...}里的变量名拼错了。 它会被静默替换成空字符串,表现就是 401。 -
Key 本身有问题。 绕开 OpenCode 直接验:
curl https://api.jucode.cn/v1/models \ -H "Authorization: Bearer $JUCODE_API_KEY"完整的 401 分支见认证。
/models 只列出你在配置的 models 里声明过的模型——自定义 provider 不会自动发现。
所以要加模型就得手写一条。
先确认配置文件本身被读到了:全局配置必须在 ~/.config/opencode/opencode.json,项目
配置必须在项目根目录的 opencode.json。JSON 语法错误也会让整个文件被跳过。
模型名声明了,但这把 Key 调不了。列一下能调的:
curl https://api.jucode.cn/v1/models \
-H "Authorization: Bearer $JUCODE_API_KEY"不同 Key 看到的列表可能不同,Key 上可以配模型组白名单。详见 模型与能力。
说明当前会话用的是别的 provider。OpenCode 会记住上次选过的模型,顶层 model 只是
默认值。跑 /models 看当前选中的是哪一个,重新选一次 JuCode 下的模型。
另一个可能是配置被覆盖了。OpenCode 的配置来源按顺序合并,后面的覆盖前面的:远程配置
→ 全局配置 → OPENCODE_CONFIG 指定的文件 → 项目配置 → OPENCODE_CONFIG_CONTENT
→ 托管配置。项目里的 opencode.json 会盖掉你的全局设置。
确认 JuCode 这边的额度:
curl https://api.jucode.cn/v1/open/balance \
-H "Authorization: Bearer $JUCODE_API_KEY"详见开放 API。
limit.context 和 limit.output 没填,或者填的值和实际不符。这两个值 OpenCode 只用
来估算剩余上下文,不影响请求本身,所以填错了不会报错,只是压缩时机不准。
正确的值在 /v1/models 的 context_window 和 max_output_tokens 字段里。