最近一直在折腾 NewAPI 这个开源网关把 OpenAI、Claude、Gemini 这些主流大模型的 Key 全部收拢到一个入口里。以前每次换模型都要登录不同平台、重新复制地址和密钥调用端还得各自改 base_url时间一长自己都分不清哪笔消费是哪个项目产生的。NewAPI 解决的就是这个痛点一个面板管所有渠道一个令牌走所有模型OpenAI 的 SDK 或者 Claude Code 这类工具只要改两行配置就能切模型对个人折腾和团队共享都挺实用。下面这套部署和接入流程我基本是踩着坑走下来的整理成一篇可以直接照抄的实操记录10 分钟把服务跑起来没什么问题。1. 项目整体设计与核心思路1.1 为什么要做一个多模型统一入口很多人一开始觉得我有 OpenAI 的 Key 就直连 OpenAI有 Gemini 的 Key 就直连 Gemini为什么要多此一举加一个网关这个想法在只用一个模型、一个人用的时候没问题但只要需求稍微复杂一点痛点就全出来了。举个例子我给自己的博客写了几个自动化脚本有的需要调用 GPT 做摘要有的用 Claude 进行长文本分析还有个小工具走 Gemini 的多模态识别。如果不加网关每个脚本里都要配置各自的 base_url 和 api_key切换模型就要改代码。更麻烦的是把脚本共享给朋友用的时候总不能把我的 Key 直接发出去别人也没办法自己配置一堆环境变量。NewAPI 的思路类似一个路由器上游连接各种模型服务下游只暴露出一个兼容 OpenAI 格式的接口。所有调用方只需要知道网关的地址和一枚令牌真正背后调用的是哪家模型、用的哪个 Key、花了多少钱全部由网关统一处理。这样配置分散、费用统计难、密钥管理乱的问题就一次性解决掉了。1.2 核心功能模块NewAPI 脱胎于 One API功能上延续了渠道、令牌、日志这套经典设计我整理了一下日常用得最多的几个模块模块作用使用场景渠道Channel配置上游模型服务包括平台类型、密钥、Base URL、模型列表添加 OpenAI、Claude、Gemini 等渠道令牌Token生成虚拟 API Key可设置额度、过期时间、模型范围分发给不同项目或团队成员模型映射把渠道真实模型名映射成自定义别名统一对外模型名方便切换底层渠道日志记录每次请求的模型、令牌、Token 消耗、状态码排查问题、统计用量用户/分组区分不同用户与模型分组多人共用、权限隔离这些模块不是花架子实际用起来能省很多事。比如模型映射我把某个渠道里真实的模型名gpt-4o-2024-11-20映射成gpt-4o客户端配置永远写gpt-4o。以后换模型版本只需要改渠道里的映射关系客户端完全不用动。1.3 部署形态与数据库怎么选NewAPI 的部署我推荐直接用 Docker镜像打包了运行环境不用在宿主机上装各种依赖升级也方便。数据库默认使用 SQLite数据落在挂载出来的目录里不需要额外部署 MySQL 或 PostgreSQL。有些人会担心用 SQLite 会不会资源占用很高实际上这个顾虑是多余的。NewAPI 作为 API 网关本身不存放大量业务数据请求日志量没有大到需要专门数据库支撑的程度。个人用甚至一台 1 核 1G 的小主机都能跑得很稳内存占用大概几百 MB 起步具体取决于并发请求量。备份也简单把挂载的 data 目录整体复制一份就行这种轻量部署方式我觉得才是合理的。如果团队成员很多、请求量大再考虑引入 MySQL 和 Redisdocker-compose.yml里增加对应服务并在环境变量里配置连接串即可但这是后话新手阶段不需要碰。2. 10 分钟部署从空服务器到面板跑起来2.1 部署前需要准备什么部署 NewAPI 的前提条件其实不多一台可以访问外网的服务器推荐 Linux 系统Debian/Ubuntu 或 CentOS 都行服务器上安装 Docker 和 Docker Compose一个域名可选但推荐后面绑定 HTTPS 用需要接入的各模型平台 API Key我这里以 Docker Compose 为例因为它通过一个配置文件就可以管理容器参数后续想要加环境变量、加数据库服务直接编辑文件再重启就行。先确认 Docker 环境已经装好终端执行docker -v和docker compose version能输出版本号就继续往下走。2.2 核心部署步骤Docker Compose 一条命令跑起来进入一个自己习惯放配置的目录比如/opt/new-api然后新建docker-compose.ymlservices: new-api: image: calciumion/new-api:latest container_name: new-api restart: always ports: - 3000:3000 volumes: - ./data:/data environment: TZ: Asia/Shanghai我解释一下几个关键配置。镜像用的是calciumion/new-api这是 NewAPI 官方构建的镜像持续更新端口把宿主机 3000 映射到容器 3000如果你服务器上 3000 被占用改成类似8888:3000宿主机端口映射也行数据目录挂载到当前目录下的data文件夹后续容器无论怎么重建数据都在时区设置为Asia/Shanghai日志时间看起来更直观。写好文件后在/opt/new-api目录下执行docker compose up -d第一次启动会自动拉取镜像网速正常的话一两分钟就能完成。启动后运行docker compose ps查看状态只要STATUS列是Up就说明容器起来了。2.3 初始化面板账号密码与基础设置容器启动后打开浏览器访问http://你的服务器IP:3000。第一次进入会看到登录页NewAPI 默认账号是root默认密码是123456。这里有个非常容易踩的坑新版镜像为了安全首次登录强制要求修改默认密码。如果你用默认密码直接调 API是会被拒绝的。所以登录进去后第一件事就是修改密码别跳过去。密码修改完进入后台的“系统设置”需要检查几个地方服务地址如果后续要绑定域名把这个地址改成最终的访问地址比如https://api.example.com这样分享链接和回调地址才会正确用户注册如果只是自己用建议关闭开放注册避免被别人注册后蹭你的额度日志保留天数按需设置日志会占用一定磁盘空间个人使用设置保留 30 天足够基础设置做完Deployment 这一步就算完成了剩下的工作都在面板里操作。2.4 绑定域名与 HTTPS可选但推荐直接用 IP 加端口调用在调试阶段没问题但我还是建议绑定域名并开启 HTTPS。一是很多客户端的配置项对 base_url 有格式要求HTTPS 地址兼容性更好二是令牌在公网传输走 HTTPS 能避免被截获的风险三是后续如果要接入 Claude Code、Gemini CLI 这类工具它们对非 HTTPS 地址的兼容性不太好。域名绑定本质就是 Nginx 反向代理加证书签发。Nginx 配置示例server { listen 80; server_name api.example.com; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }把api.example.com替换成自己的域名然后把域名解析到服务器 IP。证书签发直接用 certbot 的自动化命令我的习惯是先跑通 HTTP 再上 HTTPS因为前端挂了某个静态资源加载不出来排查起来会怀疑是不是 Nginx 配置出错了先确认服务本身正常再叠加证书层问题定位会简单很多。3. 接入 OpenAI、Claude、Gemini 的完整操作3.1 OpenAI 渠道配置进入后台后打开“渠道”页面点击“新建渠道”。类型选择OpenAI渠道名称随便起一个自己能识别的名字比如“OpenAI 官方”。OpenAI 的 Base URL 默认是https://api.openai.com/v1NewAPI 一般会自动填充没有的话手动填上。密钥填你在 OpenAI 开发者平台创建的 API Key格式是sk-开头的一串字符。模型列表建议把你实际会用到的模型名都填进去用英文逗号分隔例如gpt-4o,gpt-4o-mini,gpt-4.1,gpt-4.1-mini,o3这里我特别想提醒一句模型列表的填写直接决定后续能不能调用成功。如果你只在渠道里填了一个gpt-4o而客户端请求的是gpt-4o-mini网关会直接返回“模型不存在”。宁可多填几个模型也不要只填一个。填完后点击“测试”如果返回提示成功说明渠道已经连通。测试失败的话基本就是以下几种情况密钥无效、服务器无法访问 OpenAI 接口、模型名填写有误。这类问题的定位方法我放到后面的常见问题部分细说。3.2 Claude 渠道配置与 Claude Code 准备Anthropic Claude 的接入方式和 OpenAI 非常相似渠道类型选择Anthropic ClaudeBase URL 填https://api.anthropic.com密钥填sk-ant-开头的 Anthropic API Key。模型列表需要特别说明一下Claude 的模型名变动比较频繁进入 Anthropic 控制台能看到当前账号有权访问的模型列表。以较常见的为例claude-sonnet-4-20250514,claude-opus-4-20250514,claude-haiku-4-20250514模型名必须与实际模型 ID 完全一致填错一个字符都会导致调用失败。我在调试时就遇到过把claude-sonnet-4-20250514写成claude-sonnet-4的情况结果渠道测试通过但实际调用报 “model not found”后来才发现是模型 ID 不完整。如果你准备用 Claude Code 这个官方命令行工具还需要清楚 NewAPI 额外提供了一条/anthropic的兼容路径。Claude Code 调用 Anthropic 原生 API要让新 API 网关接管请求需要设置两个环境变量export ANTHROPIC_BASE_URLhttp://你的服务器地址:3000/anthropic export ANTHROPIC_AUTH_TOKEN这里填 NewAPI 生成的令牌这里有一个容易混淆的地方ANTHROPIC_AUTH_TOKEN填的并不是 Anthropic 官方 Key而是你在 NewAPI 令牌页面创建出来的虚拟令牌。这样才能做到把 Claude Code 的请求先送进 NewAPI再由网关转发到 Claude 渠道。3.3 Gemini 渠道配置Google Gemini 的接入同样不复杂。先去 Google AI Studio 获取 API Key格式是AIza开头的一串字符。NewAPI 新建渠道时类型选择Google GeminiBase URL 默认是https://generativelanguage.googleapis.com/v1beta不需要改动。Gemini 模型列表比较典型的是gemini-2.0-flash,gemini-2.0-flash-lite,gemini-2.5-flash-preview-05-20,gemini-2.5-pro-preview-05-20同样建议填写完整模型名。Gemini 渠道测试失败的时候除了密钥问题还有一个常见原因是账号所在地网络环境不在 Google 支持范围内。这个问题属于账号侧和网络侧NewAPI 本身解决不了需要确保服务器和调用环境都满足 Google 服务的使用条件并且遵守官方服务条款。另外 Gemini 模型免费额度相对宽松个人跑一些小工具、做图片识别、build 一些自动化 demo 非常合适。3.4 自定义/第三方 OpenAI 兼容渠道除了这几家官方渠道很多第三方模型服务商都会提供 OpenAI 兼容的接口比如各种云厂商托管的模型 API。这类服务在 NewAPI 里处理方式很统一类型选择OpenAIBase URL 改成第三方指定的网关地址密钥填第三方提供的 Key模型列表填第三方平台的模型 ID。有些第三方的 OpenAI 兼容接口路径还带了版本号前缀例如/api/v3。这种路径一定要完整填进去因为 NewAPI 在转发请求时会直接拼接你填写的 Base URL 和实际的路径漏掉前缀就会 404。我当时接入一个国产模型平台的模型时就踩了这个坑。平台文档写的接口地址是https://ark.cn-beijing.volces.com/api/v3但是在 OpenAI 标准 SDK 里调用时会自动把chat/completions追加在 base_url 后面。配置渠道使用这类平台时模型名、API 地址、密钥必须从该平台控制台拿原始信息而不能直接照搬 OpenAI 的模型名。渠道类型按实际协议选择 OpenAI 兼容类型即可。3.5 渠道连通性测试渠道配置页里有一个“测试”按钮点击后 NewAPI 会用该渠道配置发起一次最小化的模型请求。测试通过基本能证明密钥有效、网络可达、模型名可用。但我要提醒一下渠道测试通过不等于万事大吉。它测试时用的是渠道里填写的第一个模型而实际请求可能是任意模型。所以我习惯把测试当作第一道校验真正最终确认还是回到“令牌”页面创建一个临时令牌然后用客户端实际调用一次在日志里能看到完整请求和响应这样更稳妥。4. 令牌管理与统一调用姿势4.1 创建令牌并设置额度渠道是上游连接令牌是下游分发。进入“令牌”页面点击“添加令牌”你可以设置令牌名称、过期时间、额度上限和允许访问的模型范围。额度上限建议一定要设置。就算你是自己用也应该设一个合理上限避免某个客户端出 bug 陷入死循环把模型额度全部刷完。令牌创建成功后会生成一个以sk-开头的令牌字符串这个字符串只在创建时完整显示一次务必复制保存好。如果你要把令牌分给不同项目组或团队成员可以创建多个令牌额度互相独立。某个月某个人用超了直接看日志就能定位到对应令牌比在一堆官方账单里翻找方便太多。4.2 用 OpenAI SDK 和 curl 验证调用NewAPI 对外暴露的是 OpenAI 兼容接口所以任何支持自定义 base_url 的 OpenAI SDK 都可以直接用。以 Python 为例from openai import OpenAI client OpenAI( base_urlhttp://你的服务器地址:3000/v1, api_key这里填你创建的NewAPI令牌, ) resp client.chat.completions.create( modelgpt-4o, messages[ {role: user, content: 你好请介绍一下自己} ] ) print(resp.choices[0].message.content)注意base_url需要带上/v1后缀。这是 OpenAI SDK 的约定SDK 会在 base_url 后面拼接/chat/completions。如果你填的是http://你的服务器地址:3000有些 SDK 版本会自动补/v1有些不会保险起见直接写上/v1。用 curl 验证更快不用写代码curl http://你的服务器地址:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 这里填NewAPI令牌 \ -d { model: gpt-4o, messages: [{role: user, content: 你好}] }能正常返回内容说明整个链路已经跑通。4.3 Claude Code、Gemini CLI 与 VS Code 插件接入Claude Code 的接入方式在 3.2 已经提到了核心就是ANTHROPIC_BASE_URL指向 NewAPI 的/anthropic路径ANTHROPIC_AUTH_TOKEN填 NewAPI 令牌。实际跑的时候还有一个细节如果 NewAPI 那边渠道模型名与你本地 Claude Code 配置的模型名不一致启动时就会报错。解决办法是在渠道配置里把模型列表补全或者在令牌上把模型限制放开。Gemini CLI 的接入思路类似官方 CLI 支持通过环境变量指定 API 地址和 Key。这类工具的文档一般会注明baseUrl和apiKey的配置项如果遇到“白屏”或“无法登录”的情况优先检查环境变量是否生效以及在当前网络环境下能否访问 Google 服务。VS Code 里这类 CLI 插件有不少基本都是读取对应环境变量后启动子进程。我建议先在终端里手动运行命令验证没问题再去折腾编辑器集成因为插件会吞掉很多错误信息直接排查很让人头大。4.4 模型命名统一与映射技巧模型映射是 NewAPI 一个非常实用的功能但很多人会忽略。它的本质是“渠道真实模型名”和“对外暴露模型名”之间的翻译层。举个例子OpenAI 官方渠道里的模型名是gpt-4o-2024-11-20但你的应用客户端里一直写的是gpt-4o。如果直接调用网关找不到这个模型名会报“模型不存在”。这时候在渠道配置的“模型映射”里写gpt-4o - gpt-4o-2024-11-20客户端继续用gpt-4o请求网关会自动转换成真实模型名转发给 OpenAI。以后官方推出新版本你只需要把映射的目标改成新模型 ID客户端一行代码都不用动。这种命名解耦能力在多模型切换场景下特别好用。5. 常见问题与排查技巧实录5.1 部署启动类问题速查这部分问题我觉得有必要单独列出来因为部署阶段出问题最让人烦躁而且很多是环境问题不是代码问题。现象可能原因解决办法容器启动后马上退出数据目录权限不足检查./data目录权限执行chmod -R 755 data后重启容器访问 IP:3000 无法打开防火墙或安全组未放行端口在云控制台和系统防火墙里放行 3000 端口默认密码 root/123456 登录失败新版本首次登录强制改密查看容器日志是否有初始化提示或进入数据库重置密码页面打开但白屏浏览器缓存或反代配置异常清理缓存检查 Nginx 是否正确转发 WebSocket 连接端口放行这个问题很隐蔽我有一次在本地测试一切正常部署到云服务器后怎么都打不开最后发现是安全组只开放了 80 和 4433000 端口被默认拦截。如果你用的是云厂商服务器控制台上的入方向规则必须显式允许对应端口。5.2 渠道测试失败与模型路由问题渠道测试失败先看三个维度密钥、网络、模型名。密钥错了会提示401或403网络不可达会提示超时模型名错了会提示model not found。模型路由问题在调用阶段更隐蔽。比如你添加了多个 OpenAI 渠道每一个渠道可能服务不同模型。客户端请求某个模型时NewAPI 会去所有渠道里寻找包含该模型的渠道。如果没有任何渠道包含该模型即使某个渠道本身可用也会返回“模型不存在”。排查这类问题去日志页面看请求记录确认请求的模型名和命中的渠道非常直观。5.3 图片输入提示模型不支持这个问题在 DSH 这类客户端里很常见现象是纯文本请求正常一旦上传图片客户端直接提示“模型不支持图片输入”或“图片输入显示模型不支持”。遇到这种提示我的排查顺序是这样的先确认客户端选中的模型是否是支持视觉的多模态模型比如gpt-4o、gemini-2.0-flash、claude-sonnet-4都支持图片输入但一些纯文本模型比如gpt-4o-mini的部分限制场景或旧模型可能不支持再确认 NewAPI 渠道列表里填写的模型名是否准确如果渠道真实模型名和客户端请求名通过映射关联映射目标必须是对应支持视觉的模型最后检查客户端发送图片的格式多数 OpenAI 兼容客户端使用image_url格式传 base64 图片如果某个客户端用了非标准格式网关可能不会将其识别为图片请求我的经验是绝大多数情况都卡在第二步因为模型映射把本来支持视觉的模型映射到了错误的真实模型上。调整映射关系后问题一般就消失了。5.4 Claude Code 工具的经典报错Claude Code 在 Windows 上经常出现“无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”的报错。这通常是安装完成后没有配置环境变量路径。解决方式很简单通过 npm 全局安装后找到 npm 全局 bin 目录Windows 下一般是%APPDATA%\npm把这个目录加入 PATH然后重新打开终端。另一个 Windows 专属问题是在 Claude Code 启动时提示 Workspace requires the Virtual Machine Platform on Windows。这个不是 NewAPI 的问题而是 Windows 功能没启用。去“控制面板”的“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”重启系统后就能解决。还有朋友遇到过ANTHROPIC_BASE_URL配置了但还是连到官方地址的情况。排查思路是先检查环境变量是否真的提交给了终端进程Windows 下尤其要使用set ANTHROPIC_BASE_URL...或setx命令而不要直接复制 Linux 的export语法。5.5 OpenAI 与 Gemini 账号相关事项账号注册和 API Key 获取属于平台侧问题不属于 NewAPI 范畴但使用者经常会混在一起。OpenAI 注册需要在官方支持的区域网络环境下完成注册后到开发者平台创建 Key密钥只显示一次丢失只能重新建。账户因为风控被停用的情况偶有发生如果确定账号里有余额可以整理订单号、支付记录和账户邮箱通过官网支持渠道提交申诉退款结果以官方反馈为准。Gemini 侧类似有些用户开 Gemini CLI 时报your current account is not eligible for Gemini Code Assist for individuals。这是 Code Assist 服务的账户资格限制不是 API Key 问题。如果要用 Gemini 模型建议直接在 AI Studio 创建普通 API Key配置到 NewAPI 渠道里调用比纠结 Code Assist 资格省事得多。Gemini 的地区限制也一样需要在支持区域内访问 Google 服务配置时注意网络环境须满足官方条款要求。5.6 部署数据库资源焦虑很多人看到 NewAPI 支持连接 MySQL、PostgreSQL、Redis就担心默认部署方式会不会占很多资源。实际上默认 SQLite 模式就是读写一个本地文件内存占用不高CPU 也只在处理请求时有波动。个人或者小团队使用根本不需要额外搭建数据库容器。如果你确实需要用 MySQLdocker-compose 里加一个 mysql 服务然后在 NewAPI 的环境变量里设置SQL_DSN指向对应的连接串重启容器即可。我自己的服务器是 2 核 2G 的配置同时跑 NewAPI、Nginx 和一两个小应用内存都还有富余。资源焦虑在新 API 的部署上属实没必要。最后聊两句我自己的使用习惯。我踩坑最多的地方就是模型名映射后来干脆在渠道里把所有能用的模型名全列出来客户端只暴露两三个稳定的逻辑名维护成本一下子降下来。令牌方面我给每个项目单独建一个令牌设置固定额度月底看日志就知道哪个项目消耗了大头这在多个场景共用一套模型时特别能救命。如果你刚上手建议先只接一个 OpenAI 渠道跑通一条完整的调用链路再逐步把 Claude 和 Gemini 加进来。一次性把所有渠道都配上出了问题反而不知道从哪里排查。