这两年我把日常开发里能接触到的 AI 编程工具基本都换了一圈Cline、Continue、Codex、Trae 都实际跑过项目最后发现真正让效率提升一个档次的不是某个模型有多聪明而是把各个模型的 API Key 收拢到一个入口。今天这篇就聊聊我自己的做法怎么用一个 API Key、一个 base URL把所有主流大模型统一接到你的 AI 编程工具里。先解释一下这个思路能解决什么问题。正常情况下一名开发者手头至少有两三个模型的账号OpenAI 的 GPT 系列做通用对话和复杂推理DeepSeek 的便宜且代码能力强通义千问或 GLM 在某些场景下要顶上去。如果你用的是 Cline 这类开源编程助手每换一个模型就要重新配置一次 Provider、重新填 key遇到某个 key 余额不足还得全局找一遍哪里有硬编码。等到你想在团队里把工具铺开更麻烦钥匙一地、权限乱糟糟、花谁的额度都说不清。统一网关解决的就是这种事——把所有的上游模型渠道接到一个服务里你只给每个工具发一把钥匙这把钥匙能解锁全部模型还能按成员分额度、按模型做路由、按调用记日志。整篇文章会按我自己的实践路径来写先做方案选型再讲怎么自建一个统一网关接着把编程工具接进去最后把那些我在实际使用中遇到的高频报错和坑位一次性说清楚。我尽量把配置过程写成可以直接抄作业的状态你拿自己的 API Key 照着来就行。1. 为什么需要“一个 Key 管所有模型”1.1 AI 编程工具的多模型需求是常态我最早用 AI 编程工具的时候只接了一个模型觉得够了。后来真正写业务代码才发现不同模型有各自的脾气有的擅长从零生成工程骨架有的适合做代码 review 找漏洞有的上下文窗口大适合整仓库分析还有的本地小模型速度快适合做补全和重命名。拿我常用的几个场景举例让模型写一个完整模块我会用推理能力更强的模型宁可多等几秒。让模型帮我改一个不熟悉的开源库我会找上下文窗口大的模型把整个相关目录塞进去。日常改 lint 报错、补注释、生成测试用例用便宜又快的模型最划算没必要每次都上最贵的。你要是只用一家模型也能凑合但心里会一直觉得“换个模型没准能更好”。很多 AI 编程工具支持自定义 Provider就是给这种需求准备的。可问题是每加一个模型你就要多保存一对 base URL 和 API Key每次工具升级或者换设备都要重新填一遍。1.2 钥匙太多才是最大的麻烦API Key 管理这件事看起来是小问题实际踩过才知道难受。我见过不少同事直接把 key 写到源码里然后提交到仓库第二天就收到平台发的“疑似 key 泄露”警告邮件。也见过有人把 key 放在前端环境变量里结果所有调用记录都能在网上被抓到。钥匙一旦泄露损失的不只是余额还有可能被人拿来跑一些不该跑的任务最后账号被限制。还有一个很现实的场景团队协作。你在公司里给三个人每人发一套各家模型的 key过一个月有人离职你要保证他把所有 key 都交回来、所有地方都删干净几乎不可能做到。但如果你只有一个统一网关离职成员的 key 你随时可以一键禁用他手里那把钥匙立刻报废上游密钥永远不用暴露给个人。这就是我强烈建议个人和团队都做一层统一接入的原因。1.3 “统一网关”具体是什么说穿了特别简单你部署一个服务把各家大模型的 API 都接进去然后这个服务对外提供一个 OpenAI 兼容的接口。你所有 AI 编程工具都连这一个地址、用同一个 key至于这个 key 背后到底调的是 DeepSeek 还是通义还是 GPT由网关里的路由规则决定。这套东西本质和支付网关很像商家不需要分别对接每家银行只需要接一个支付网关用户拿什么卡都能付款。模型网关也是同理你不需要关心上游到底是谁只需要知道我的 key 能调用哪些模型、花多少钱就行。OpenAI 兼容接口的意思就是现有已经支持 OpenAI SDK 的编程工具改了 base URL 和 key 以后基本不用改代码就可以直接用。大多数 AI 编程工具都支持这个模式这也是后面所有操作能成立的基础。2. 统一接入的主流方案怎么选2.1 三种路线对比现在想做到“一个 key 用所有模型”路线大致有三类自建一个开源网关典型代表是 new-api、one-api 这套项目。用一个轻量级代理层比如 LiteLLM Proxy把配置写在 YAML 里。直接买一个第三方托管服务把 key 交给平台比如 OpenRouter。三条路线我都用过各自定位完全不同。我用一张表把关键差异列出来对比维度new-api / one-api 自建LiteLLM ProxyOpenRouter 托管部署成本中需要 Docker 环境低单容器或 Python 进程无注册即用功能丰富度高带令牌管理、额度、日志、统计中偏向开发配置和路由够用模型全但管理功能一般渠道管理网页可视化适合团队配置文件适合开发者习惯平台方统一管理你不能自定义渠道自定义模型支持能接任意 OpenAI 兼容地址支持可写自定义 provider只能选平台已上架的模型多用户和权限好支持令牌额度隔离一般需要自己包一层平台提供账户体系但粒度有限日志与审计强自带调用日志中可接入外部日志提供基础用量统计单看功能new-api 这类自建项目对个人和团队开发者是最平衡的。LiteLLM 更适合做基础设施的开发者他们希望通过代码管理一切。OpenRouter 适合不想折腾的人但它的自定义上游能力很弱你想接入一个自己的本地模型或者公司内网的模型基本就抓瞎了。2.2 我为什么最终选了 new-api我的场景是个人机和团队小规模协作都要用。个人这边我想把 OpenAI、DeepSeek、通义千问、本地 Ollama 全部接进去哪个顺手用哪个。团队这边我需要给每个成员单独发 key限制每月的调用额度出问题的时候能查到是谁在什么时候调了什么模型。new-api 的“渠道 - 令牌 - 日志”这套设计逻辑正好都能覆盖。对比 one-apinew-api 是社区里维护更活跃的分支修复了很多老版本的问题增加了不少新模型提供商的支持界面也更好用。我部署完以后几分钟就能把一个新渠道加进去不用改代码。所以下面的实操部分我会以 new-api 为主。如果你更喜欢 LiteLLM 或者已经有了其他网关核心思路也是相通的只是配置入口不一样。2.3 选择之前先想清楚这三点见过不少朋友一上来就折腾自建网关结果用了两天就放弃了。我建议在动手之前先问自己三个问题是只给自己用还是要给团队用个人用 LiteLLM 就够团队用需要额度隔离和审计还是 new-api 这类更合适。是只接云端模型还是也要接本地模型自建网关更容易把 Ollama 这种本地服务也包进去。你愿意维护一个服务吗自建网关虽然不难但要升级、备份、看日志。如果完全不想操心托管服务更适合你。想明白这三点再动手就不会做了半个月才发现方向不对。3. 用 new-api 自建统一网关的完整实操3.1 部署前的准备new-api 部署并不复杂前提是你有一台能长期运行的服务器或者一台不会经常关机的电脑。我一开始就是拿家里一台旧笔记本跑的CentOS 系统装了个 Docker内存 4GB完全够用。如果你有云服务器配置更不是问题。需要准备的环境就三件事Docker 和 Docker Compose这个是必备的。网上的安装教程很多这里不展开。一个空闲端口默认是 3000如果被占用了要提前改。一个用来持久化数据的目录建议单独建个文件夹比如/opt/new-api后面所有数据都放在里面。我不建议直接在宿主机上装二进制跑除非你很清楚依赖项怎么处理。Docker 的好处是升级方便容器替换一下就行数据目录单独挂出来坏了也能快速恢复。3.2 启动服务与初始化我用的 docker-compose 配置大致是这个样子version: 3.4 services: new-api: image: calciumion/new-api:latest container_name: new-api restart: always ports: - 3000:3000 volumes: - ./data:/data environment: - TZAsia/Shanghai把上面内容保存成docker-compose.yml后在/opt/new-api目录下执行docker-compose up -d第一次启动会自动初始化数据库默认用的是容器里的 SQLite对个人和几十人的小团队足够用了。接着打开浏览器访问http://你的服务器IP:3000第一次进入会让你注册一个管理员账号。这个账号就是整个网关的管理员所有渠道、令牌、额度的配置都在它下面。注册完成后先把页面右上角的“设置”整体过一遍重点看模型相关选项比如是否启用模型重定向、是否允许用户自行创建令牌。我习惯在刚开始部署时就顺手把“令牌自动续费”和“默认额度”这些选项调好免得后面给同事开账号时手忙脚乱。3.3 添加渠道把各家大模型接进来这是整个配置过程里最关键的一步。登录管理员后台找到“渠道”菜单点“添加渠道”。渠道的意思就是你去连接某一家的模型接口所以要填的信息基本包括渠道类型、接口地址、API Key、模型列表。以常用的几个渠道为例OpenAI 渠道类型选择 OpenAI代理地址填https://api.openai.com/v1密钥填你 OpenAI 账号下的 API Key模型列表填gpt-4o、gpt-4o-mini这些你实际开通的模型名。DeepSeek 渠道类型选择 DeepSeek地址填https://api.deepseek.com/v1密钥填 DeepSeek 开放平台的 key模型填deepseek-chat、deepseek-reasoner。通义千问渠道类型选择通义千问DashScope地址填阿里云 DashScope 的 OpenAI 兼容地址https://dashscope.aliyuncs.com/compatible-mode/v1密钥填 DashScope 的 key模型填qwen-plus、qwen-max等实际开通的模型。Ollama 本地模型渠道类型选择 Ollama地址填http://宿主机IP:11434/v1不用填密钥模型填你本地已下载的模型名比如qwen2.5-coder:7b。渠道添加完以后我习惯做一步验证在渠道列表里点“测试”。如果返回可用模型或一个正常的响应说明渠道配置没问题。这里有一点要提醒你new-api 的渠道是支持分组的你可以在添加渠道时给不同渠道打上不同的组名。默认组是default如果你的客户端请求里没有指定分组就会落到默认组。建议一开始就约定好分组规则后面路由控制会省很多事。3.4 创建令牌你的唯一 API Key渠道配好了接着就要创建令牌。在后台“令牌”菜单里点“添加令牌”设置令牌名称、过期时间、模型范围、额度额度。这里我推荐的做法是不要直接用管理员账号的令牌去接编程工具而是给每个工具或每个人单独开一个令牌。模型范围可以勾选允许调用的模型额度按实际需求填。比如我给自己专门用来跑 Cline 的令牌就只勾选代码相关的模型每天额度设一个上限防止某天某个模型死循环疯狂调用把余额烧光。创建完令牌后你会拿到一串sk-开头的字符串这就是你以后唯一需要保管的 API Key。它对应一个固定的 base URLhttp://你的服务器IP:3000/v1。把这两个信息保存到一个安全的地方比如密码管理器里接下来所有配置都用它。顺手用 curl 测一下网关是否正常这一步非常值得做能帮你把“网关没部署好”和“编程工具配置不对”这两个问题先隔离出来curl http://你的服务器IP:3000/v1/models \ -H Authorization: Bearer sk-你的令牌如果返回一个包含模型列表的 JSON就说明网关对外已经能正常工作了。这时候再有问题就是工具端的配置问题。4. 把 AI 编程工具接到统一网关4.1 OpenAI 兼容就是一个“万能接口”现在主流的 AI 编程工具基本都支持 OpenAI 兼容的自定义接口。说白了你只要在工具设置里找到“自定义 Provider”或“OpenAI Compatible”这一栏把 new-api 的地址和令牌填进去再选择模型名工具就能正常调用。这背后依赖的就是统一网关对外暴露的/v1/chat/completions接口。你可能会问为什么偏偏是 OpenAI 兼容格式流行到这种程度因为这个协议足够简单且成熟各家模型厂商为了低门槛接入生态都主动适配了这个格式。DeepSeek 官方直接给了 OpenAI 兼容地址阿里云 DashScope 也专门做了一个兼容模式。这就像全世界都统一用 USB-C 接口你的充电头只要支持 PD 协议什么设备都能充。new-api 把你的 key 转换成各家需要的格式工具端永远只认一种格式这就把兼容性问题一次性解决了。4.2 以 Codex CLI 为例的配置OpenAI 官方出的 Codex 工具很多人在用它本身支持自定义模型提供商。配置方式是在项目或用户目录下写一个配置文件然后在环境变量里指定 key。我大致会这样做。先设置环境变量export OPENAI_API_KEYsk-你的网关令牌 export OPENAI_BASE_URLhttp://你的服务器IP:3000/v1然后启动codex在配置中选择这个自定义 base URL。不同版本配置项略有差异以你当前版本为准。关键点是OPENAI_API_KEY一定填网关生成的令牌不是原始平台 keyOPENAI_BASE_URL一定带/v1路径。很多人在这一步漏掉/v1导致请求直接 404还以为是工具坏了。配置好以后Codex 内部所有请求都会走网关。你在 Codex 里选的模型名比如deepseek-chat网关会自己路由到 DeepSeek 渠道上游。你不需要知道上游真实地址在哪也不需要再单独配置 DeepSeek 的 key。4.3 Cline 和 Continue 的接入方式再拿两个常见的 VSCode 插件说明。Cline 的配置路径比较直观打开扩展设置在 API Provider 里选择 OpenAI Compatible然后填 base URL 和 API key最后在 model 里填你要用的模型。注意 model 必须填网关令牌允许范围内的模型名如果填了没开通的模型后续调用会报“model not allow”之类的错误。Continue 则通过config.yaml配置模型列表我自己日常用的配置文件大致长这样models: - name: DeepSeek Chat provider: openai model: deepseek-chat apiBase: http://localhost:3000/v1 apiKey: sk-你的网关令牌 roles: - chat - autocomplete - editContinue 和 Cline 的不同点在于它能同时配多个模型并按角色区分用途。我一般把补全模型和聊天模型指向不同网关渠道这样聊天时用能力强的大模型写代码补全时用延迟低的模型。顺带说一下如果你用的是 Trae 这类出厂自带模型绑定的工具那可能需要看它是否支持自定义 OpenAI 兼容提供商。支持的话原理和上面一模一样不支持的话你就只能继续用工具内置的模型这类工具就不太适合走统一网关的方案。4.4 自己写代码时怎么处理流式输出如果你不只是用现成插件而是想在自己写的脚本或工具里调用网关那绕不开流式输出。大模型的回答是一次一个字蹦出来的以 SSE 协议推给你。网关会原样把上游的流式响应转发过来你的客户端代码负责解析。以 Python 的 openai 官方 SDK 为例from openai import OpenAI client OpenAI( base_urlhttp://你的服务器IP:3000/v1, api_keysk-你的网关令牌 ) response client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 写一个快速排序}], streamTrue ) for chunk in response: delta chunk.choices[0].delta.content if delta: print(delta, end)这里streamTrue表示开启流式。注意两点一是choices[0].delta在首尾阶段可能为空要做空值判断二是有一个finish_reason字段流结束后会变成stop如果你要做完整的结束处理需要判断它。在 Web 前端里主流做法是用 fetch 配合 ReadableStream或者直接用 EventSource。因为 OpenAI 兼容接口走的是 POST 请求EventSource 没法发 POST所以前端要么用 fetch 手动解析要么用 HTTP 客户端库。取消请求也很重要前端用户点“停止生成”时你要调用 AbortController 去中断连接否则网关和上游还会继续跑白白消耗额度。我自己的经验是先在后端持有一个可取消的请求对象前端断连时立刻触发取消。这样能最大化避免“用户已经不想看了模型还在继续生成”这种浪费。5. 实战中的高频报错与排查手册5.1 401 鉴权错误到底怎么查我开始用统一网关的那阵子最常遇见的就是 401。错误文案五花八门但根源基本就三种key 不对、token 没生效、header 没带对。先看一个经典报错code:api_key_required,message:api key is required in authorization header。这个翻译过来就是请求头里没有带 Authorization 字段。你用的是不是只填了 base URL、忘记填 key或者填 key 的位置不对这类纯客户端问题最好排查。还有一类报错长这样unexpected status 401 unauthorized: authentication fails, your api key: ****。前面能看出来某个工具确实把请求发出去了但网关验签没通过。常见原因是令牌过期、令牌被封禁或者不小心把令牌复制少了字符。遇到这种情况我一般先回到 new-api 后台找到对应的令牌点“重置”拿重新生成的令牌再试一次。如果错误直接来自某个特定模型渠道比如提示incorrect api key provided那问题往往不在网关令牌而在上游渠道的密钥。你应该去渠道配置里检查上游 key 是不是失效了。这里要区分一个概念网关令牌是给工具用的渠道密钥是给上游平台用的两边各自独立。有些同学把原始平台 key 填到工具里自然会报错因为网关不认别人的钥匙。5.2 模型列表为空或路由失败另一个常见的坑是模型列表为空。你用 curl 请求/v1/models返回正确但在 Cline 的模型下拉列表里看不到任何模型或者选了模型以后调用报 “model not found”。这种一般跟令牌的模型范围有关。如果你创建令牌时把模型范围限制成了某个特定模型 ID而你的工具刚好不在这个范围内就会被拒绝。再讲一个非常有代表性的报错llm-deepseek: no api key for provider route deepseek-official。我当初看到这个报错也是一头雾水后来明白了这是网关在路由时找不到能处理这个请求的渠道。要么你这个模型对应的渠道没有填上游 key要么渠道被停用了要么模型名对不上。这个报错好在把 provider route 给出来了直接去后台检查 DeepSeek 渠道的状态就能定位。路由失败还有一个容易被忽略的原因模型名不匹配。你在客户端填的模型名必须和网关渠道里配置的模型名一致。有时候官方模型名更新了比如deepseek-chat变成deepseek-v3但渠道里没更新就会路由失败。在 new-api 后台有一个“模型重定向”的功能可以把一个名字映射到另一个名字非常适合这类场景。5.3 超时、限流与稳定性AI 编程工具调用大模型跟普通接口最大的区别就是响应时间特别长。一个复杂的代码生成任务可能要好几分钟。这段时间内只要网络抖动一次前端就可能报了超时错误。我的处理策略是分层处理。网关这一层我会调高模型渠道的超时时间。客户端这一层比如 Cline 里我会让它自动重试一次超时请求不过重试要小心因为如果是推送到一半断的前端可能会拿到重复内容导致代码文件里出现半截内容叠加的情况。限流也是绕不开的。各家模型平台的限流策略不一样有的按每分钟请求数有的按每分钟 token 数。网关的好处是统一管理你可以把多个渠道配置成同一模型网关会自动做负载均衡。比如你有两个 OpenAI 账号或者 DeepSeek 有两个 key可以加到同一个渠道下new-api 会轮流用它们有效降低单 key 被限流概率。我建议在客户端也做一层退避重试逻辑。遇到 429 或者 503 时先等几秒再重试不要疯狂请求。网关后台有每分钟请求限制配置适当设一个值避免程序 bug 导致雪崩。5.4 本地模型混跑的特别提醒本地用 Ollama 跑模型是成本最低的试验方式但接入网关时有一些特有的坑。最常见的是容器网络问题new-api 跑在 Docker 容器里Ollama 跑在宿主机上如果填http://localhost:11434/v1请求会进到容器自己的回环地址根本找不到 Ollama。这种情况要填宿主机在 Docker 网络里的地址或者用host.docker.internal这个特殊域名。我用 mac 时这个域名直接可用Linux 上有时要在启动容器时加add-host参数把域名指向宿主机 IP。另外本地模型的并发能力一般很弱。7B 模型在小显存卡上单条请求就能把资源吃满。如果你通过网关把同一个本地模型同时暴露给 Cline 和 Continue两边同时请求等待时间会非常感人。我的做法是给本地模型渠道设一个较低的并发限制或者把它放到一个独立分组只给特定客户端用。还有 GPU 显存的问题。模型一旦超过显存容量Ollama 会把参数往内存里卸速度会断崖式下降。如果你发现本地模型经常莫名奇慢先看看是不是模型参数量超出了显存。或者直接用 Q4 量化版模型换一个更大的模型不一定会更好用反而可能在本地跑不动。6. 几个让我少走弯路的建议6.1 Key 安全这是底线问题统一网关虽然降低了 key 暴露的风险但网关令牌本身依然是要保护的资产。我见过有人把网关令牌直接写在 VSCode 的 settings.json 里然后整个配置同步到 GitHub Gist 上等于把密码贴在公告栏。正确做法是用环境变量或者系统密钥链管理工具保存VSCode 的设置里尽量用${env:变量名}这种引用方式。网关管理后台本身也要设强密码有条件的话开启两步验证。因为拿到了管理员账号就等于拿到了所有上游渠道的密钥。这一点在团队场景尤为重要建议管理员账号和普通成员账号严格分离普通成员只能创建自己的令牌、查看自己的调用记录不能看渠道密钥。6.2 成本控制要有预判统一网关把多模型集中管理以后成本控制反而变得更重要了。因为调用入口太方便你可能会不自觉地切换各种模型月底账单出来才吓一跳。我的习惯是给每个令牌设一个每日额度同时定期看日志里哪个模型调用量异常。new-api 自带折线图和用量统计每周扫一眼就够。如果某个模型用量特别大可以考虑启用缓存功能。网关会把相同的请求结果缓存一段时间常见于代码补全这类重复请求较多的场景能省下不少 token 费用。不过要注意缓存只适合无需实时更新的内容如果你让模型读文件做分析内容一变还命中旧缓存就麻烦了。6.3 尽量保留上游渠道的独立性统一网关虽然好用但不要把所有鸡蛋都放一个篮子里。我的做法是源代码和脚本里永远只写网关令牌但自己手头保存一份各平台原始 key 的备份。万一哪天网关服务挂了或者要迁移可以临时直接连原始渠道继续干活不会卡死在网关这个环节。同时网关服务本身也要做备份。new-api 的数据都存在挂载目录里定期把/data目录拷贝一份就行。很多容器部署的朋友会直接跑docker-compose up -d以后就不管了直到某天服务器磁盘坏了才后悔。花两分钟配一个 cron 定时备份成本极低收益极大。这也是我个人这段时间最大的一个体会工具链越自动化越要在关键节点留好后路。统一 API Key 让人爽但爽的前提是你知道自己每一层依赖是什么出了问题能在五分钟内定位。把这套流程跑顺以后再回过头看那些五花八门的配置文档你会发现你只需要记住一个地址、一把钥匙剩下的事情交给网关。这套结构后期还可以继续扩展比如接进来更多新模型、给不同项目分配不同模型组、把微调后的模型也统一挂进去都是同一个套路。
