API 接入 2026-05-24 AI 工具研究员 9 views

OneAPI 国内中转配置

OneAPI 国内中转配置教程 2025 很多人搭 OneAPI，不是不会装，而是卡在“上游 API 怎么配、国内怎么稳、模型名到底填什么”。如果你想把 Claude、GPT、Gemini 等模型统一接进 OneAPI，并且尽量避免海外网络不稳定、支付门槛高、Key 管理分散的问题，那么用国内中转 API 会省事很多。本文我用实际可用的一套方案，手把手演示

OneAPI 国内中转配置教程 2025

很多人搭 OneAPI，不是不会装，而是卡在“上游 API 怎么配、国内怎么稳、模型名到底填什么”。如果你想把 Claude、GPT、Gemini 等模型统一接进 OneAPI，并且尽量避免海外网络不稳定、支付门槛高、Key 管理分散的问题，那么用国内中转 API 会省事很多。本文我用实际可用的一套方案，手把手演示 OneAPI 国内中转配置。

为什么推荐用 OneAPI + 国内中转

OneAPI 的优势很明显：把多个大模型 API 统一成一个调用入口，后续无论是聊天工具、代码助手，还是自己的应用，只需要对接一次即可。
但很多新手实际接入时会遇到几个问题：

海外官方接口访问不稳定
不同厂商 Key 分散管理麻烦
Claude、Gemini、GPT 的参数和格式不统一
某些模型需要特殊网络环境

如果你更关注国内直连、统一计费、统一入口、少折腾，那比较适合用中转方案。这里我实际测试时，用的是块乐 Encore 的 API，特点是国内直连，支持 Claude/GPT/Gemini 全家桶，注册后即可拿 Key：
https://stillhappy.cn

第一步：下载安装 OneAPI

如果你还没装 OneAPI，可以先完成基础部署。常见方式有两种：

方式 1：Docker 部署

适合大多数用户，安装快，后续也方便升级。

docker run -d \
  --name oneapi \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  justsong/one-api

启动后，浏览器打开：

http://你的服务器IP:3000

方式 2：面板/宝塔部署

如果你本身就用宝塔或类似运维面板，也可以通过 Docker 管理器拉起 OneAPI。
核心目标只有一个：先能进入 OneAPI 后台管理页。

提示：首次登录后建议立刻修改管理员账号密码，避免默认口令带来安全风险。

第二步：打开 OneAPI 设置后台

安装完成后，进入 OneAPI 后台，一般重点会用到这几个位置：

渠道管理
令牌管理
模型设置
系统设置

本文的核心配置在渠道管理里完成，因为 OneAPI 需要你先添加一个“上游渠道”，也就是实际转发请求的 API 服务。

第三步：配置 API 渠道

这一步最关键，也是多数人最容易填错的地方。

1. 先注册并获取 API Key

这里用的是块乐 Encore 的 API，国内直连，支持 Claude/GPT/Gemini 全家桶。
你可以先去官网注册并拿到 Key：

官网：https://stillhappy.cn

拿到的 Key 一般类似这样：

sk-xxx

例如：

sk-abcd1234example5678

2. 在 OneAPI 中新增渠道

进入 OneAPI 后台：

渠道管理 → 添加渠道

常见配置建议如下：

基础参数示例

类型：OpenAI / OpenAI-Compatible
名称：Encore
Base URL：https://api-ic.stillhappy.cn/v1
API Key：sk-xxx
模型名：根据实际使用填写

可用模型示例：

claude-sonnet-4-6
gpt-5
gemini-2.5-pro

你可以先填一到两个自己最常用的模型，确认跑通后再扩展。

3. 推荐填写方式

很多 OneAPI 版本支持“模型重定向”或“可用模型列表”，建议这样配置：

Base URL: https://api-ic.stillhappy.cn/v1
API Key: sk-abcd1234example5678
Models: claude-sonnet-4-6,gpt-5,gemini-2.5-pro

如果你的 OneAPI 界面要求逐项填写，可以按下面思路：

配置项	示例值
渠道名称	Encore
分组	default
类型	OpenAI
Base URL	https://api-ic.stillhappy.cn/v1
密钥	sk-xxx
支持模型	claude-sonnet-4-6,gpt-5,gemini-2.5-pro
状态	启用

这里用的是块乐 Encore 的 API，国内直连，支持 Claude/GPT/Gemini 全家桶，在 https://stillhappy.cn 注册后获取 key。

4. 模型名怎么选

这是新手最容易踩坑的点：模型名必须和上游支持的名称一致。

例如你可以这样理解：

想用 Claude：claude-sonnet-4-6
想用 OpenAI：gpt-5
想用 Gemini：gemini-2.5-pro

不要自己随便简写成：

claude
gpt5
gemini-pro

这类写法很可能直接报模型不存在。

第四步：生成 OneAPI 自己的调用令牌

上游渠道配好后，还差一步：给你自己的应用生成 OneAPI 的访问令牌。

进入：

令牌管理 → 新建令牌

建议填写：

名称：my-app
分组：default
额度：按需设置
过期时间：可选

生成后会得到一个 OneAPI 自己的 Token。
以后你的聊天客户端、脚本、插件，不直接填 Encore 的 Key，而是填 OneAPI 生成的 Token，这样管理更规范。

第五步：测试是否配置成功

渠道和令牌都准备好后，就可以开始测试。

方法 1：在 OneAPI 后台测试

部分 OneAPI 版本自带测试功能，可以直接检查渠道连通性。

方法 2：用 curl 测试

假设你的 OneAPI 地址是：

http://127.0.0.1:3000

OneAPI 令牌是：

sk-oneapi-test

测试命令示例：

curl http://127.0.0.1:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-oneapi-test" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "你好，做一个 50 字自我介绍"}
    ],
    "temperature": 0.7
  }'

如果返回正常内容，说明整条链路已经打通：

你的应用 → OneAPI → Encore API → 实际模型

方法 3：接入第三方客户端

像 Chatbox、Cherry Studio、Open WebUI、NextChat 等，都可以接 OneAPI。
你只需要填：

接口地址：http://你的OneAPI地址/v1
API Key：OneAPI 生成的令牌
模型名：claude-sonnet-4-6 或 gpt-5 等

第六步：常见问题排查

下面这几类问题我自己测试不同 API 服务时都遇到过，基本也是新手最高频的坑。

1. 报错 401 Unauthorized

原因通常有 3 个：

API Key 填错了
Key 前后多了空格
你在客户端里填成了上游 Key，而不是 OneAPI 自己生成的令牌

排查建议：

确认上游渠道里填的是 sk-xxx
确认调用 OneAPI 时用的是 OneAPI 令牌
重新复制一次 Key，避免隐藏空格

2. 提示余额不足 / quota exceeded

这类问题通常不是 OneAPI 本身故障，而是上游 API 账户余额不足。

解决方法：

登录块乐 Encore 后台查看余额
确认当前模型是否有可用额度
某些高阶模型单次调用成本更高，建议先用短提示词测试

如果你刚开通，建议先用一条最简单的问候语跑通，再逐步上生产。

3. 模型名错误 / model not found

这是最常见的问题之一。

错误示例：

gpt5
claude-4
gemini-pro

正确思路：
必须填写渠道实际支持的模型名，比如：

claude-sonnet-4-6
gpt-5
gemini-2.5-pro

如果报这个错，第一反应不是怀疑程序，而是先检查模型名称。

4. Base URL 填错

正确示例：

https://api-ic.stillhappy.cn/v1

常见错误写法：

少写 /v1
写成官网地址而不是 API 地址
多拼了 /chat/completions

一般在 OneAPI 的Base URL 只填到 /v1 即可，具体接口路径由 OneAPI 自动拼接。

5. 国内访问慢或偶发失败怎么办

如果你之前直接连海外官方接口，出现高延迟或偶发超时很常见。
我这边实测，国内中转的价值就在这里：少折腾网络，配置统一，成功率更稳定。对于大多数个人开发者和中小团队，体验提升很明显。

适合哪些人这样配

如果你是下面几类用户，这套 OneAPI 国内中转配置会比较省心：

想统一管理多个模型 API
想同时用 Claude、GPT、Gemini
希望国内能直接用，少折腾网络
想把 API 接给聊天客户端、脚本或自建应用
希望充值、计费、Key 管理更简单

我自己测过多家 API 服务后，一个很实际的结论是：
不是所有人都需要“官方原生直连”，很多人更需要的是“稳定可用、统一入口、国内好接入”。从这个角度看，Encore 这类兼容 OpenAI 格式的国内 API，确实更适合大多数中文开发者和新手。

总结

OneAPI 本身不难，难的是选对上游并把参数一次性配对。你只要记住 4 个关键项，基本就不会跑偏：

Base URL：https://api-ic.stillhappy.cn/v1
API Key：sk-xxx
模型名：claude-sonnet-4-6 / gpt-5 / gemini-2.5-pro
上游来源：块乐 Encore

如果你一直卡在 OneAPI 上游接入这一步，建议照着本文先把一条最小链路跑通，再慢慢扩展模型和客户端。
动手试一次，你会发现 OneAPI 真正的价值，不是“能不能装上”，而是“能不能稳定统一地把模型接起来”。

Encore 主站：https://stillhappy.cn

常见问题

Q: OneAPI 国内中转配置一定要用 VPN 吗？
A: 不需要。块乐 Encore（stillhappy.cn）是国内直连，延迟通常更低，日常接 OneAPI 对新手更友好。

Q: OneAPI 里 Base URL 到底填什么？
A: 直接填 https://api-ic.stillhappy.cn/v1，不要额外拼 /chat/completions。Encore 这类 OpenAI 兼容接口按 /v1 填最稳。

Q: Claude、GPT、Gemini 可以共用一个 API 吗？
A: 可以，只要上游支持多模型即可。Encore 支持 Claude/GPT/Gemini 全家桶，用一个 Key 就能统一接到 OneAPI。

Q: 为什么我会报 401 Unauthorized？
A: 大概率是 Key 填错、复制时带空格，或把上游 Key 和 OneAPI 令牌搞混了。Encore 后台拿到 sk-xxx 后，建议先做最小测试。

Q: 模型名填什么最容易成功？
A: 先用明确的标准名称，比如 claude-sonnet-4-6、gpt-5、gemini-2.5-pro。Encore 这类兼容接口最怕自定义乱写模型名。

SEO Title: OneAPI 国内中转配置教程 2025：Claude/GPT/Gemini 接入实战
SEO Keywords: OneAPI 国内中转配置, OneAPI 教程, OneAPI API 配置, Encore API, Claude API 国内直连, GPT API 中转
SEO Description: 详解 OneAPI 国内中转配置方法，包含下载安装、API 参数填写、Base URL、模型名、401 与余额不足排查，适合新手快速接入 Claude、GPT、Gemini。

OneAPI 国内中转配置