集成指南 | TokenHub 文档

将 TokenHub 接入 Claude Code、Codex、Cursor、Cline、Kilo Code 等常用 Agent 工具。

TokenHub 同时提供 OpenAI 兼容、Anthropic Claude Messages 兼容和 Gemini 兼容接口。大多数 Agent、IDE 插件、桌面客户端只要能自定义 Base URL、API Key 和 Model ID，就可以接入 TokenHub。

这篇教程先帮你选择工具，再说明不同协议该填什么地址。对于 Claude Code、Codex、OpenCode 这类第三方 Agent，推荐优先写入工具自己的用户级配置文件；临时 export 环境变量只用于快速验证和排错。

开始前准备

在配置任何工具之前，先准备好三样东西：

TokenHub 工作台创建的 API Key。
TokenHub 模型列表中的 Model ID，例如你准备用于聊天、代码、推理或快速补全的模型。
工具支持的协议类型，常见选项是 OpenAI Compatible、Anthropic Claude Messages 或 Gemini Compatible。

建议先把密钥保存到本地安全位置。教程中的 TOKENHUB_API_KEY、sk-... 都是占位示例，实际填写时换成 TokenHub 工作台生成的 Key。不要把 Key 写进项目仓库、截图、共享配置文件或公开 Issue。

使用工具

按开发者 Agent、IDE 插件、桌面客户端分组选择工具。每张卡片都会进入对应的接入教程。

Terminal agents

开发者 Agent

适合仓库级阅读、代码修改、命令行任务和自动化开发流。

Claude CodeAnthropic 官方 AI 编程 CLI CodexOpenAI 官方 AI 编程智能体 OpenCode开源 AI 编程编辑器，本地优先 Aider终端里的结对编程 Agent Qwen Code通义千问 AI 编程 CLI

In-editor tools

IDE 插件

在编辑器内完成问答、补全、重构和差异审阅。

CursorAI 原生代码编辑器 ClineVS Code 插件，自主编码 Roo CodeVS Code 插件，多模式协作 Kilo Code开源 VS Code 编程智能体

Desktop clients

桌面客户端

用于日常对话、模型调试、提示词验证和多模型切换。

Cherry Studio多 AI 模型聚合客户端

如果你正在配置仓库级任务，优先看 Claude Code、Codex、OpenCode、Aider 这类开发者 Agent；如果你希望在编辑器里问答、修改当前文件或做补全，优先看 Cursor、Cline、Kilo Code、Roo Code、Qwen Code；如果只是先验证模型输出、提示词和 Key 是否可用，Cherry Studio 这类桌面客户端更轻。

配置文件优先

第三方 Agent 往往会在后台启动自己的进程。只在某个终端里 export 环境变量，容易出现“终端可用、IDE 不可用”或“新窗口失效”的问题。更稳妥的做法是把 TokenHub 配置写入工具自己的配置文件。

常见位置如下：

工具	推荐配置位置	说明
Claude Code	`~/.claude/settings.json`，可选 `~/.claude.json`	在 `model` 和 `env` 中写入 Anthropic 兼容变量；onboarding 或 VS Code 插件配置只作为补充。
Codex	`~/.codex/config.toml`	添加 TokenHub provider，并用 `env_key` 读取 Key。
Aider	`~/.aider.conf.yml` 或项目内 `.aider.conf.yml`	固化模型和 `openai-api-base`，Key 仍放在本机环境或密钥管理中。
OpenCode	`~/.config/opencode/opencode.json` 或项目内 `opencode.json`	配置 `@ai-sdk/openai-compatible` 自定义 provider、`options.baseURL`、模型和 `/connect`。
Qwen Code	`~/.qwen/settings.json` 或项目内 `.qwen/settings.json`	写入 `modelProviders.openai`、`security.auth.selectedType = "openai"`、`envKey` 和 `model.name`。
IDE 插件	VS Code / JetBrains 的用户设置或插件设置页	写入 provider、Base URL、API Key、Model ID 和权限策略。
桌面客户端	客户端服务商配置页	新增 OpenAI Compatible 或 Custom Provider，并手动添加模型。

只有在排查网络、Key、模型名时，才建议临时使用环境变量。验证通过后，把同样的值固化到配置文件里。

选择接入协议

先看工具支持哪种 Provider，再决定 Base URL。不要把不同协议的地址混用，否则最常见的结果就是 404、请求格式错误或模型列表为空。

工具类型	优先选择	什么时候使用
OpenAI Compatible / Custom OpenAI	`https://us-api.tokenhub.com/v1`	绝大多数 IDE 插件、桌面客户端、CLI Agent 都支持；适合 Chat Completions 和 Responses。
Anthropic / Claude Compatible	`https://us-api.tokenhub.com`	Claude Code 或明确要求 Anthropic Messages 协议的工具。
Gemini Compatible	`https://us-api.tokenhub.com`	明确支持 Gemini 原生接口、需要 `/v1beta/models` 模型列表的工具。

如果工具把 Host 和 Path 分开填写，Host 填 https://us-api.tokenhub.com，OpenAI 兼容路径填 /v1。如果工具只接受一个完整 Base URL，OpenAI 兼容模式直接填写 https://us-api.tokenhub.com/v1。

通用配置表

工具要求	在 TokenHub 中填写
OpenAI 兼容 Base URL	`https://us-api.tokenhub.com/v1`
OpenAI Chat Completions 测试地址	`https://us-api.tokenhub.com/v1/chat/completions`
OpenAI Responses 测试地址	`https://us-api.tokenhub.com/v1/responses`
Anthropic Base URL	`https://us-api.tokenhub.com`
Anthropic Messages 测试地址	`https://us-api.tokenhub.com/v1/messages`
Gemini Base URL	`https://us-api.tokenhub.com`
Gemini 模型列表地址	`https://us-api.tokenhub.com/v1beta/models`
API Key	TokenHub 工作台创建的密钥，建议在本地命名为 `TOKENHUB_API_KEY`
Model ID	使用 TokenHub 模型列表中的模型名称

其它工具配置方法

没有出现在上方卡片里的工具，也可以按这个流程接入：

打开工具的 Models、Providers、API Keys、LLM Provider 或自定义模型设置页。
找到 OpenAI Compatible、Anthropic Compatible、Gemini Compatible 或 Custom Provider。
先按工具支持的协议选择 Base URL，不要同时混用多个协议。
填入 API Key 和 Model ID；如果工具要求模型别名，可以命名为 TokenHub / 模型名，避免和其它服务商混淆。
保存配置后，先执行一次只读提示；确认成功后，再开启文件写入、终端命令、自动补全或 Agent 自动化任务。

如果工具要求分别配置 Chat Model、Edit Model、Apply Model、Fast Model 和 Embedding Model，第一次接入只配置最核心的 Chat Model。这样排错路径最短；连通后再逐步补齐其它模型。

验证方式

配置完成后，不要直接把工具交给真实项目。建议按下面顺序验证：

检查配置文件或 UI 设置，确认 Base URL、API Key、Model ID 没有空格、换行或旧值。
发送只读提示，例如“用一句话介绍当前项目，不要修改文件”。
在 TokenHub 请求日志中确认请求发往 https://us-api.tokenhub.com，模型名称与 TokenHub 模型列表一致。
再测试目标能力：代码 Agent 测试读文件和小改动；IDE 插件测试当前文件解释；桌面客户端测试长文本和流式输出。
确认无误后，再允许工具执行命令、批量改文件或开启自动化模式。

可直接复制这条验证提示：

请阅读当前项目的 README，并用三句话总结项目用途。不要修改任何文件。

常见问题

现象	处理方式
401 或认证失败	检查 API Key 是否来自 TokenHub 工作台，确认工具读取的是最新 `TOKENHUB_API_KEY`。
404 或模型不存在	使用 TokenHub 模型列表中真实存在的 Model ID，并确认协议和模型能力匹配。
OpenAI 工具请求失败	Base URL 通常必须是 `https://us-api.tokenhub.com/v1`，不要只填根域名。
Claude 工具请求格式错误	Anthropic 兼容工具通常填 `https://us-api.tokenhub.com`，不要额外拼 `/v1/messages`。
Gemini 模型列表为空	检查模型列表地址是否为 `https://us-api.tokenhub.com/v1beta/models`，必要时手动填 Model ID。
流式输出中断	先关闭流式输出验证一次非流式请求，再检查网络代理、超时和模型上下文长度。
工具用了其它服务商	检查 Chat、Edit、Apply、Fast、Autocomplete 等所有模型槽位是否都改成 TokenHub。
IDE 里读不到配置	优先写工具的用户级配置文件；如果只用了临时环境变量，请从同一终端启动 IDE。