OpenCode

第 1 版 · 更新于 2026-11-12 · 阅读约 3 分钟

为 OpenCode CLI 配置 Runtoken 的 Chat Completions 接入。

准备工作#

开始前，请准备：

已安装的 OpenCode V2 CLI 和一个小型测试项目，安装与使用方式见官方 CLI 指南。
Runtoken 平台 API Key。
支持工具调用的 Chat Completions 模型 ID。

本文采用 V2 配置格式。已有 V1 配置时，请先按官方迁移指南处理，再合并本文示例。

连接配置#

在测试项目中创建 opencode.json。文件已存在时，合并 Provider 并保留其他设置。下面使用 OpenCode 的自定义 Provider 格式。

opencode.json · OpenCode V2json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "runtoken/YOUR_MODEL_ID",
  "providers": {
    "runtoken": {
      "name": "Runtoken",
      "env": ["RUNTOKEN_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.runtoken.net/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "Runtoken coding model",
          "capabilities": {
            "tools": true
          }
        }
      }
    }
  }
}

将两处 YOUR_MODEL_ID 替换为 Runtoken 模型目录中的同一个 ID。runtoken/ 前缀用于选择本地 Provider，不属于平台模型 ID。

配置字段	用途
`providers.runtoken`	定义 `runtoken/` 前缀所选择的 Provider。
`env`	指定提供凭据的环境变量名。
`package`	选择本例使用的 OpenAI 兼容运行时。
`settings.baseURL`	设置 API 前缀，不附加 `/chat/completions`。
`models`	注册可供选择的模型 ID。
`capabilities.tools`	向客户端声明工具调用能力，仅用于确实支持工具的模型。

声明能力不会改变模型本身的支持范围。上下文上限、推理选项和媒体能力应与所选模型一致，不直接复制其他 Provider 的数值。

设置凭据并启动#

在测试项目中打开终端，设置 Key 后启动独立会话。独立服务使用这个终端的环境；已运行的共享后台服务可能使用不同的环境变量。服务模式见官方 CLI 说明。

bash

export RUNTOKEN_API_KEY="YOUR_PLATFORM_KEY"
opencode --standalone

$env:RUNTOKEN_API_KEY = "YOUR_PLATFORM_KEY"
opencode --standalone

将 YOUR_PLATFORM_KEY 替换为平台 Key。真实 Key 不写入项目配置、提示词或截图；包含 Key 的命令可能留在终端历史中。

打开 /models，选择 Runtoken 下的模型。已有会话可能保留先前选择的模型，因此还需要检查当前会话，不能只看配置文件里的默认值。选模规则见官方模型说明。

检查连接与文件任务#

先发送简短请求，再按时间、Key 和模型查找 Runtoken 中的对应请求记录。随后在测试项目中尝试一个小型文件任务。

检查文件创建text

创建 greeting.py，其中包含 greet(name) 函数。
它返回 "Hello, " 与 name 拼接后的字符串，名字为空时返回 "Hello, friend"。
不安装依赖，也不访问网络。

审阅拟执行的文件操作，在合适时批准修改。检查实际文件，再要求 OpenCode 重新读取它，将空名字的问候语改为 Hello, guest。

确认第二轮读取了已有文件，并修改了预期的那一行。仅在回复中展示代码，不能说明文件已经写入，或工具结果已经正常回传。

能力与限制#

本配置使用 Chat Completions。仅修改模型 ID，不会使 Runtoken 将请求转换为 Messages、Responses 或 Gemini 协议。

任务	需要满足的条件
文本回复	所选模型接受请求并返回可用响应。
文件修改	工具调用、工具结果回传及工作区权限正常。
终端命令	客户端允许操作，本地环境能够执行。
长会话	上下文处理与请求选项符合模型的支持范围。

模型请求发送到配置的网关；文件与命令工具在 OpenCode 的执行环境中运行。保留正常的工具权限，更换 Provider 不会授予本地文件或命令访问权限。

排查问题#

修改高级选项前，先查看错误响应并核对当前模型。

现象	检查方向
配置文件被拒绝	统一使用 V2 字段，并按声明的 schema 校验。
找不到 Runtoken 模型	检查 `providers` 条目、`models` 中的模型 ID 及凭据变量。
`401`	确认 Key 有效，且执行模型请求的进程能够读取该变量。
`404` 或模型被拒绝	基础地址、准确模型 ID 和 Chat Completions 支持情况。
能回复，不能修改文件	工具能力、工具结果回传及工作区权限。
实际使用了其他模型	当前会话的 `/models` 选择，以及 Agent 单独指定的模型。
`429`	Runtoken 错误响应中的具体限额与重置说明。

恢复配置与后续阅读#

结束测试后退出会话，清除本次终端中的临时凭据变量。

bash

unset RUNTOKEN_API_KEY

Remove-Item Env:RUNTOKEN_API_KEY -ErrorAction SilentlyContinue

恢复原先的默认模型，仅移除本次测试新增的 Provider 条目，保留项目中的其他配置。

请求格式见 OpenAI Chat。配置文件的位置与校验方式见 OpenCode 配置说明及其配置 schema。

这篇文档有帮助吗？