OpenCode

OpenCode 版本更新较快。只要当前版本支持自定义 OpenAI-compatible Provider，就可以使用 HiLinkup。

本页示例按 Chat Completions 配置并验证，最终请求为 POST /v1/chat/completions。若当前版本提供独立 Responses Provider，请改用该模式。

接入前准备

确认 HiLinkup API 可用

export HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY"

curl https://api.hilinkup.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HILINKUP_API_KEY" \
  -d '{
    "model": "aliyun/kimi-k3",
    "messages": [
      {
        "role": "user",
        "content": "Reply with: ok"
      }
    ],
    "max_tokens": 32
  }'

复制模型 ID

curl https://api.hilinkup.com/v1/models \
  -H "Authorization: Bearer $HILINKUP_API_KEY"

方法一：环境变量

export HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY"
export HILINKUP_BASE_URL="https://api.hilinkup.com/v1"
export HILINKUP_MODEL="aliyun/kimi-k3"

然后在 OpenCode 中选择 OpenAI-compatible / Custom OpenAI Provider，并映射：

OpenCode 字段	填写值
Provider	OpenAI-compatible / Custom OpenAI
API Key	`$HILINKUP_API_KEY`
Base URL	`https://api.hilinkup.com/v1`
Model	`aliyun/kimi-k3` 或 `/v1/models` 返回的模型 ID

方法二：用户级配置文件

如果 OpenCode 版本支持配置文件，建议把 Provider 配置放在用户级配置中，把 API Key 留在环境变量中。

{
  "providers": {
    "hilinkup": {
      "type": "openai-compatible",
      "name": "HiLinkup",
      "apiKey": "${HILINKUP_API_KEY}",
      "baseURL": "https://api.hilinkup.com/v1",
      "models": {
        "aliyun/kimi-k3": {
          "name": "aliyun/kimi-k3"
        }
      }
    }
  },
  "defaultProvider": "hilinkup",
  "defaultModel": "aliyun/kimi-k3"
}

OpenCode 不同版本的配置文件名和字段可能不同。如果你的版本使用 baseUrl、base_url 或 api_key，按当前版本 schema 调整字段，但值保持一致：Base URL 是 https://api.hilinkup.com/v1，Key 来自 HILINKUP_API_KEY。

方法三：项目级配置模板

团队可以提交不含密钥的项目模板，例如 .opencode.example.json：

{
  "provider": "openai-compatible",
  "apiKeyEnv": "HILINKUP_API_KEY",
  "baseURL": "https://api.hilinkup.com/v1",
  "model": "aliyun/kimi-k3",
  "temperature": 0.2,
  "maxTokens": 4096
}

使用时复制成个人本地配置：

cp .opencode.example.json .opencode.local.json
printf '%s\n' '.opencode.local.json' >> .gitignore

配置步骤

确认基础 API 可用

先完成快速开始，排除账户和网络问题。

新增自定义 Provider

在 OpenCode 配置中选择 OpenAI-compatible Provider，并映射 API Key、Base URL 和模型 ID。不要选择只能连接官方 OpenAI 地址的 Provider。

启动只读测试

在临时项目中要求 Agent 总结目录结构，不允许写文件或执行危险命令。

检查完整 Agent 路径

再测试工具调用、长提示和实际代码修改。基础 API 成功不代表完整 Agent 流程一定成功。

不要把 API Key 直接写入可提交的 OpenCode 项目配置。使用环境变量或用户级私有配置。

排查

连接测试失败

检查最终请求地址是否为 https://api.hilinkup.com/v1/chat/completions。如果出现 /v1/v1/chat/completions，说明客户端自动追加了 /v1，Base URL 应改成 https://api.hilinkup.com。

普通 cURL 成功，但 Agent 失败

Agent 请求通常会带工具定义和更长上下文。先关闭工具或使用只读任务；如果只读成功，再逐步启用编辑、命令执行和长上下文。

403 或模型不可用

检查模型 ID 是否来自 /v1/models，并确认当前 API Key 有权限调用该模型。

接入总览

开发工具

聊天客户端

应用框架

接入前准备

方法一：环境变量

方法二：用户级配置文件

方法三：项目级配置模板

配置步骤

排查

​接入前准备

​方法一：环境变量

​方法二：用户级配置文件

​方法三：项目级配置模板

​配置步骤

​排查

接入前准备

方法一：环境变量

方法二：用户级配置文件

方法三：项目级配置模板

配置步骤

排查