第三方应用接入指南

HiLinkup 可以接入 OpenAI、Anthropic/Claude 与 Gemini 风格客户端。先确认应用的协议和字段类型，再填写地址；“兼容 OpenAI”并不代表所有客户端都会调用同一个端点。

通用连接参数

配置项	应填写的值	常见字段名称
服务类型	按应用实际支持选择 OpenAI、Anthropic/Claude 或 Gemini	Provider、API 类型
API Key	在 HiLinkup 控制台创建的密钥	API Key、Token
地址	Base URL 或完整 Endpoint，不能混用	API Host、Endpoint、Base URL
Model	`/v1/models` 返回的完整 ID	Model、Model ID、Deployment

先看字段名称。Base URL 通常由客户端继续拼接路径；Endpoint 通常要求完整地址。配置后应检查最终请求 URL，避免遗漏或重复 /v1。

按协议填写配置

不同应用的“兼容 OpenAI”并不总是同一种协议。配置前先看应用要求的是 OpenAI、Claude 还是 Gemini。

协议	适用场景	Base URL / Endpoint	鉴权方式	示例文档
OpenAI Responses	Codex、支持 Responses 的 Agent 和明确要求该协议的客户端	Base：`https://api.hilinkup.com/v1`；完整：`.../v1/responses`	`Authorization: Bearer $HILINKUP_API_KEY`	Responses
OpenAI Chat Completions	WorkBuddy、传统聊天客户端、`ChatOpenAI` 与只支持聊天协议的插件	Base：`https://api.hilinkup.com/v1`；完整：`.../v1/chat/completions`	`Authorization: Bearer $HILINKUP_API_KEY`	Chat Completions
Claude Messages	Claude Code、Anthropic SDK、Claude 风格客户端	Base：`https://api.hilinkup.com`；完整：`.../v1/messages`	`x-api-key` + `anthropic-version: 2023-06-01`	Claude Messages
Gemini generateContent	Gemini SDK、Google AI 风格客户端	Base：`https://api.hilinkup.com`；完整：`.../v1beta/models/{model}:generateContent`	`x-goog-api-key: $HILINKUP_API_KEY`	Gemini generateContent

协议名称不等于模型来源。Responses、Chat Completions、Claude Messages 与 Gemini generateContent 都可以调用 HiLinkup 平台中支持该协议的中国模型。模型是否出现在 /v1/models 中，也不自动证明它支持每一种协议。

/v1/models 的 owned_by 表示供应商，id 使用 供应商/模型 格式。实际调用建议填写完整 ID，例如 aliyun/kimi-k3；只填写 kimi-k3 时由平台当前的默认供应商设置选择路由。

常见应用的协议

应用或配置方式	协议	地址填写方式
Codex CLI、Codex 客户端	OpenAI Responses	Base URL `https://api.hilinkup.com/v1`
WorkBuddy 自定义 Endpoint	OpenAI Chat Completions	完整 Endpoint `https://api.hilinkup.com/v1/chat/completions`
Claude Code、CC Switch 的 Claude Code 模式	Claude Messages	确保最终请求为 `https://api.hilinkup.com/v1/messages`
Cherry Studio、Chatbox、LobeChat、Open WebUI、NextChat、LibreChat、AnythingLLM	OpenAI Chat Completions	通常填写 Base URL `https://api.hilinkup.com/v1`
LangChain `ChatOpenAI`、LlamaIndex `OpenAILike`、Dify 当前 OpenAI-compatible 配置	OpenAI Chat Completions	通常填写 Base URL `https://api.hilinkup.com/v1`
原生 Gemini 客户端	Gemini generateContent	确保最终请求包含 `/v1beta/models/{model}:generateContent`

Cursor、Cline、Roo Code、Continue、OpenCode、OpenClaw 等工具更新较快。若界面提供单独的 Responses、Chat Completions 或 Anthropic 选项，以当前版本的协议名称为准；不要只根据“OpenAI-compatible”字样猜测。

接入前准备

为应用创建独立 API Key

打开 API Key 管理，按应用创建密钥。不要在多个不相关客户端之间共用一个生产密钥。

确认模型 ID

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

从 data[].id 复制完整的 供应商/模型 ID，例如 aliyun/kimi-k3。

先验证基础 API

在配置第三方应用前，先完成快速开始。这样可以区分“账户/API 问题”和“客户端配置问题”。

选择你的应用

开发工具

Claude Code

在终端编程工作流中配置模型服务。

CC Switch

通过可视化供应商管理器切换 Claude Code 到 HiLinkup。

Codex CLI

通过 config.toml 的自定义 model provider 接入 HiLinkup。

Codex 客户端

使用 CC Switch 图形化配置供应商和客户端模型菜单。

WorkBuddy

通过 Chat Completions Endpoint 添加 HiLinkup 自定义模型。

Cursor

配置自定义 OpenAI Base URL 和模型。

Cline

在 VS Code 中配置 OpenAI-compatible Provider。

Roo Code

配置 Roo Code 的自定义 OpenAI Provider。

Continue

在 VS Code 或 JetBrains 中配置模型。

OpenCode

在终端 Agent 中使用 HiLinkup。

OpenClaw

配置 Agent Provider 并验证完整工具链。

聊天客户端与知识库

Cherry Studio

添加 Provider、同步模型并验证多模态能力。

Chatbox

配置桌面端 OpenAI-compatible 服务。

LobeChat

配置本地或部署版 LobeChat。

Open WebUI

在管理员设置中添加 OpenAI API 连接。

NextChat

配置 ChatGPT-Next-Web / NextChat。

LibreChat

通过自定义端点配置模型列表。

AnythingLLM

将 HiLinkup 用作聊天与知识库模型。

应用框架

Dify

在工作流和应用中配置模型供应商。

LangChain

使用 langchain-openai 接入。

Vercel AI SDK

在 TypeScript 应用中创建 OpenAI-compatible Provider。

LlamaIndex

在 RAG 与 Agent 应用中配置模型。

通用配置流程

先选择协议

新项目优先选择 Responses。传统聊天客户端选择 OpenAI-compatible / Chat Completions；Claude Code 选择 Anthropic/Claude；原生 Gemini 客户端选择 Gemini。

确认字段是 Base URL 还是 Endpoint

按上方协议表填写地址，并使用为该应用创建的独立密钥。保存后检查最终请求路径和鉴权头。

添加模型

优先使用应用的“获取模型”或“同步模型”功能。无法同步时，手动添加 /v1/models 返回的完整模型 ID。

保存并测试连接

如果应用提供连接测试，先执行测试。测试失败时保留完整状态码和错误正文。

新建普通对话

先发送短文本，不要立即启用图片、工具、知识库、联网搜索或超长上下文。

逐项启用高级能力

普通对话成功后，分别测试流式输出、图片输入、工具调用、结构化输出和长上下文。只启用模型真正支持的能力。

第三方客户端验收清单

检查项	通过标准
连接	测试请求返回 HTTP `200`
模型	使用 `/v1/models` 中存在的完整 ID
文本对话	能返回非空回答
流式输出	内容逐段显示并正常结束
用量	控制台可看到对应请求或用量变化
图片	支持视觉的模型能读取上传图片
工具调用	支持工具的模型能返回有效参数
安全	API Key 未出现在日志、截图和前端代码中

开发第三方集成时的实现要求

如果你在开发客户端或 Provider 插件，而不是只填写现有应用的设置，请遵循以下约定。

客户端初始化

import OpenAI from "openai";

export const hilinkup = new OpenAI({
  apiKey: process.env.HILINKUP_API_KEY,
  baseURL: process.env.HILINKUP_BASE_URL ?? "https://api.hilinkup.com/v1",
  timeout: 60_000,
  maxRetries: 2,
});

import os
from openai import OpenAI

hilinkup = OpenAI(
    api_key=os.environ["HILINKUP_API_KEY"],
    base_url=os.getenv(
        "HILINKUP_BASE_URL",
        "https://api.hilinkup.com/v1",
    ),
    timeout=60.0,
    max_retries=2,
)

常用协议 cURL 模板

OpenAI Responses
OpenAI Chat
Claude
Gemini

curl https://api.hilinkup.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HILINKUP_API_KEY" \
  -d '{
    "model": "aliyun/kimi-k3",
    "input": "Tell me a three sentence bedtime story about a unicorn."
  }'

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": "developer",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

curl https://api.hilinkup.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $HILINKUP_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "aliyun/kimi-k3",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

curl "https://api.hilinkup.com/v1beta/models/aliyun/kimi-k3:generateContent" \
  -H "x-goog-api-key: $HILINKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Find the race condition in this multi-threaded C++ snippet: [code here]"
          }
        ]
      }
    ]
  }'

必须处理的兼容性细节

允许用户修改 Base URL，不要把域名写死在界面逻辑中。
启动或刷新时从 /v1/models 获取模型列表，并允许手动输入完整模型 ID。
当 tools 为空时，不要发送依赖工具的 tool_choice。
只向明确支持的模型发送图片、音频、工具和高级推理参数。
保留 HTTP 状态码、错误正文和请求标识，方便排查。
对 429、超时和部分 5xx 使用指数退避与有限重试。
不要自动重试 400、401、403 等确定性错误。
API Key 只保存在服务端、操作系统安全存储或受保护的本地配置中。

健康检查

export async function checkHilinkup() {
  const startedAt = Date.now();
  const models = await hilinkup.models.list();

  return {
    ok: models.data.length > 0,
    modelCount: models.data.length,
    latencyMs: Date.now() - startedAt,
  };
}

不要只检查域名是否能打开。有效健康检查至少应验证鉴权和模型列表。

常见配置错误

连接测试失败，但 cURL 正常

检查客户端最终请求的协议、路径和鉴权头。Responses 应到 /v1/responses，Chat Completions 应到 /v1/chat/completions，Claude 应到 /v1/messages，Gemini 应到 /v1beta/models/{model}:generateContent。

客户端没有显示模型

手动添加 /v1/models 返回的完整模型 ID。确认没有多余空格、显示名称或供应商前缀。

普通对话成功，图片或工具失败

这通常是能力不匹配，不是鉴权问题。换用支持对应能力的模型，并在客户端中启用正确的模型能力标记。

返回 401 或 403

检查密钥、账户状态和模型权限。不要通过反复修改 Base URL 来掩盖鉴权问题。

返回 429

降低并发，检查余额和额度，使用带抖动的指数退避。不要让多个插件同时无限重试。

查看完整错误排查

按 HTTP 状态码、请求阶段和客户端行为定位问题。

​通用连接参数

​按协议填写配置

​常见应用的协议

​接入前准备

​选择你的应用

​开发工具

Claude Code

CC Switch

Codex CLI

Codex 客户端

WorkBuddy

Cursor

Cline

Roo Code

Continue

OpenCode

OpenClaw

​聊天客户端与知识库

Cherry Studio

Chatbox

LobeChat

Open WebUI

NextChat

LibreChat

AnythingLLM

​应用框架

Dify

LangChain

Vercel AI SDK

LlamaIndex

​通用配置流程

​第三方客户端验收清单

​开发第三方集成时的实现要求

​客户端初始化

​常用协议 cURL 模板

​必须处理的兼容性细节

​推荐环境变量

​健康检查

​常见配置错误

查看完整错误排查

通用连接参数

按协议填写配置

常见应用的协议

接入前准备

选择你的应用

开发工具

聊天客户端与知识库

应用框架

通用配置流程

第三方客户端验收清单

开发第三方集成时的实现要求

客户端初始化

常用协议 cURL 模板

必须处理的兼容性细节

推荐环境变量

健康检查

常见配置错误