说实话我一开始也没把这事放在心上。装了三四个AI编程Agent之后突然发现自己手里攒了一堆API KeyDeepSeek一个、豆包一个、通义一个GitHub Copilot算一个还有各平台送的体验额度。更要命的是这些Key散布在Cline、Roo Code、Continue、Trae这些工具的配置页里时间一长连哪个Key是给哪个Agent用的都快忘了。直到某天月底一算账发现十几个Key的消费记录像天书一样我才决定认真搭一套本地网关把所有模型通道、密钥和用量收拢到一起。这篇东西就是我整个整理过程的完整复盘包括为什么要做网关、怎么选型、怎么部署、怎么把手里这些Agent全部接进去以及我踩过的各种坑。如果你也装了好几个AI编程插件或者你带的小团队里每个人都在各自配Key这篇文章应该能帮你省下不少事。1. 为什么Key管理会变成一团乱麻1.1 装了一堆AI编程Agent之后先说下我的实际场景。我日常写代码的主力是VS Code插件栏里躺着Cline、Roo Code、Continue偶尔还用Trae处理一些简单任务。这三个工具本身设计思路不同Cline擅长自主规划任务Roo Code偏测试驱动和自定义模式Continue更像内联对话助手。但它们的共同点是——都要在设置里填一个模型服务地址和API Key。如果我只用一个模型服务商那倒简单。但问题恰恰在于不同模型在不同场景下各有优势复杂重构我习惯用DeepSeek最新版简单补全用Flash类模型响应更快代码审查这类任务用豆包的长上下文更划算。于是我的配置面板里出现了三四组Key每个Agent还可能有自己的偏好模型。这时候只要其中一个服务商调整了计费策略或者某个Key触发了限流我就得挨个Agent去检查到底是谁在调用、用了多少量。这种状态持续了两个月我终于不想忍了。其实这件事的本质是AI编程Agent的数量在增长但Key管理和用量统计的方式还停留在石器时代。一个工程团队如果有三五个开发每人手里两三个Key那可真就是一笔糊涂账了。1.2 分散管理的几个真实痛点我把这段时间感受到的痛苦归纳成了几点你会发现它们之间还会互相放大密钥泄露风险成倍增加Key散落在多个Agent的配置文件中有的插件还会把配置同步到云端甚至存在配置文件被误提交到Git仓库的风险。一旦泄露别人就能拿你的Key去调用模型账单直接算你头上。费用归因完全靠猜月底收到服务商账单只知道总金额不知道是哪个项目、哪个Agent、哪个成员花掉的。如果是个人使用还好团队协作时大家互相“借”Key月底分摊费用基本靠拍脑袋。限流与故障互相干扰多个Agent共用同一个Key时某个Agent跑批量任务很容易把额度打满其他Agent跟着全部超时。你甚至不知道是哪条请求触发的限流。切换模型成本太高今天想统一换成某家新出的模型得去每个Agent的配置里改一遍改完之后还容易漏掉一两个导致部分Agent还在用旧模型。这四点叠加起来体验就非常折磨了。这时候我才意识到我需要的不是一个“更好的Key”而是一层能统一收口这些东西的中间层。1.3 为什么我最终选了本地网关这条路先解释一下“本地网关”是什么。简单说就是在我自己的机器上跑一个轻量服务它把各种模型的API统一封装成一个OpenAI兼容格式的入口。我的所有编程Agent只认这个入口而网关自己再去管理和调度后端的多个模型服务商。为什么是本地而不是直接买个商业SaaS服务我当时权衡了三个因素数据敏感度代码补全和上下文会包含我的业务代码片段如果经过第三方转发服务等于把代码提交记录交给了别人。本地网关意味着所有请求都在自己的机器上转发代码内容只在本地和后端模型服务商之间传输中间不经过任何额外环节。完全可控性本地网关想怎么配就怎么配模型怎么映射、令牌额度怎么分、日志保留多久全部由我决定。SaaS方案往往有功能限制比如免费版只能接固定几个模型商。成本为零主流开源网关项目都是免费的我只需要一台能长期开机的电脑或者家里的小服务器就够了。当然本地网关也有代价——需要自己维护、更新、排障。但对一个搞技术的人来说这个成本完全可接受而且一次搭好长期受益。2. 网关方案的整体设计与选型分析2.1 网关要解决的核心问题在动手搭之前我先把自己的需求列成了清单。这样选型的时候就有据可依不会看着眼花缭乱的开源项目走不动路。统一入口所有Agent的Base URL只需要填一个地址比如http://localhost:3000/v1格式必须是OpenAI兼容的这样任何支持自定义接口的工具都能直接接。多渠道接入后端要能同时接DeepSeek、豆包、通义、Kimi、智谱这些国内服务商也最好能接Ollama这类本地模型这样我可以混合调度。可视化令牌管理能创建多个独立的访问令牌每个令牌可以单独限制额度、设置有效期随时一键禁用。用量统计与计费归因每次请求要记录token消费量最好能按令牌、按模型、按渠道维度统计方便月底算账。模型映射因为我可能在不同Agent里填不同的模型名网关要能把请求里的模型名映射到我实际要用的模型上。需求列完之后基本能看出来我需要的是一个带管理后台的开源API网关而不是一个裸的转发脚本。裸脚本虽然灵活但日志、统计、令牌管理这些全都要自己写时间成本太高了。2.2 开源网关方案横向对比我花了一晚上调研了几款主流的开源网关下面这个表是我当时的对比结果方案技术栈江湖地位优势劣势one-apiGo React元老级稳定、文档多、社区人广项目更新变慢部分新模型渠道缺失new-apiGo Reactone-api的活跃分支渠道更新快、功能更全、有模型重定向项目较新升级需要关注变更LiteLLM ProxyPython海外社区主力支持的Provider极多、配置灵活无成熟的可视化管理后台Virtual Key功能偏简自研转发脚本任意语言——完全个性化日志、统计、鉴权全要自己造维护成本高这里解释一下为什么new-api是one-api的活跃分支这个背景one-api是很早的开源网关项目后来社区里有人觉得它更新节奏不够快很多新的模型服务商接入不及时于是就有了new-api这个fork在原有基础上增加了不少新渠道和功能。实际用下来new-api的渠道配置项更丰富比如支持模型重定向把请求里的A模型名映射到B渠道的C模型名、更细粒度的分组和令牌配置。LiteLLM Proxy其实也是一个好方案尤其是你在海外云服务上用得多、Provider种类又特别杂的场景。但它的管理界面太简陋了配额、令牌、日志都得靠命令行或者操作数据库对“想快速搞定”的人来说不够友好。所以我最终把重心放在了new-api上。2.3 我为什么最终选了它最终我选的是new-api理由是它在“开箱即用”这件事上做得最好。它有完整的管理后台我可以在浏览器里完成渠道配置、令牌创建、日志查询不需要碰命令行。同时它支持Docker部署一条命令就能拉起来后续升级也方便。另外还有一个很现实的因素它的模型重定向功能很成熟。举个例子我有个Agent配置里写死了模型名gpt-4o-mini但我并不想真的去用OpenAI我想把这类轻量任务全部导给DeepSeek的deepseek-chat。在new-api里我只需要在渠道配置里把模型重定向设好请求就会自动转发过去。这样我就能在不改动Agent配置的前提下灵活调整后端模型策略。当然如果你已经有Python环境、又喜欢配置驱动的方案LiteLLM也完全可以。我的建议是先想清楚自己最依赖的是“可视化后台”还是“配置灵活性”再决定选哪个方向。3. 核心功能实现路由、密钥托管与用量统计3.1 统一入口与密钥托管机制网关搭起来之后所有Agent都指向同一个地址http://localhost:3000/v1。这个入口实际上是一个OpenAI兼容的RESTful API包括/v1/chat/completions这些端点。Agent发来的请求格式和我直接调用GPT接口时一模一样所以它们不需要做任何特殊适配。密钥托管这块我理解的核心是“上游Key和下游令牌分离”。上游Key指的是各模型服务商给我的真实Key保存在网关后台的渠道配置里Agent接触不到。下游令牌是网关自己生成的sk-xxx样式的字符串我把它填到Agent的配置里。这样做的好处是即使某个Agent的配置文件泄露了泄露的也只是网关令牌而网关令牌可以随时停用、随时更换不影响到上游真实Key的安全。在配置上游渠道时要注意很多服务商的Key是明文显示在渠道列表里的。new-api这块做得还可以渠道编辑后一般不会完整回显Key只显示掩码。但如果你部署在我这样的家庭服务器上最好再给后台加一层访问控制比如用反向代理加个Basic Auth别让后台裸奔在局域网里。3.2 多渠道路由与模型映射多渠道路由是网关的核心价值之一。我可以在后台维护若干条渠道每条渠道对应一个模型服务商并配置它提供的模型列表。实际请求进来时网关会根据请求中的模型名自动选择合适的渠道转发。举个例子我配了这么几条渠道渠道名称模型服务商可用模型deepseek-officialDeepSeekdeepseek-chat, deepseek-reasonerdoubao-official豆包doubao-pro-32k, doubao-lite-32ktongyi-official通义qwen-plus, qwen-turbo然后在模型映射里做调整比如把所有Agent请求里的gpt-4o-mini映射到deepseek-chat这样就能让原本为OpenAI模型设计的Agent无缝改用DeepSeek。这种设计最大的好处是灵活。今天觉得某家模型不好用只需要在后台把映射关系改一下所有Agent立刻生效完全不用去逐个改配置。如果某条渠道频繁限流我也可以在渠道配置里调低它的优先级或者为同一个模型配两条备用渠道网关会自动做负载均衡。3.3 Token用量统计与费用归因用量统计这块new-api的日志功能做得比较细。每一次请求都会记录下模型名、输入token数、输出token数、总token数、估算费用、耗时、渠道、令牌以及请求的状态码。在后台的日志页面可以按时间范围、模型、渠道、令牌等维度检索。这里有一个关键点费用统计的准确性取决于你在渠道里配置的“模型价格”是否正确。不同服务商的计费单位不太一样有的按千token计价有的按百万token计价还有的区分输入和输出价格。如果把价格配错了后台估算出的费用就会和真实账单对不上。我自己就犯过这个错——当时把DeepSeek的输入输出价格填反了月底后台显示的费用比真实账单高出一大截排查了半天才发现是价格配错了。对个人或小团队来说即使费用估算不是100%精确也没关系token量的相对比较才是核心。我主要用它来回答三个问题哪类任务最费token、哪个Agent调用最频繁、哪个渠道的性价比最高。这些问题搞清楚之后优化模型选型和缓存策略就都有数据支撑了。4. 完整部署与接入实操4.1 部署前的准备清单动手部署之前先准备好下面这些一台能长期运行的电脑或服务器我用的是家里一台旧i3小主机2核4G内存跑new-api绰绰有余。Docker和Docker Compose这是最省事的部署方式。一个用来存放网关数据SQLite或MySQL的目录我建议单独建一个/opt/new-api之类的目录后续备份直接打包这个目录就行。各模型服务商的API Key提前准备好配置渠道的时候要用。规划好端口。默认是3000端口如果本机没被占用就直接用如果要用HTTPS或者统一端口再考虑挂反向代理。注意端口绑定上如果你是单机自己用强烈建议把服务只绑定在127.0.0.1:3000不要直接用0.0.0.0暴露到局域网。我当时图省事直接暴露了后来发现局域网里其他设备也能访问到后台虽然没出事但心里总是别扭最后还是收回了本机。4.2 Docker Compose一键部署网关我用的配置文件如下你可以直接参考version: 3.8 services: new-api: image: calciumion/new-api:latest container_name: new-api restart: always ports: - 127.0.0.1:3000:3000 environment: - TZAsia/Shanghai - SESSION_SECRET请改成一段很长的随机字符串 volumes: - ./data:/data这里有几个点想解释一下。SESSION_SECRET是用来加密登录会话的如果留空或者用默认值登录态很容易出问题。./data:/data是数据持久化目录SQLite数据库文件会放在这里升级容器时数据不会丢。TZ设置成Asia/Shanghai是为了让日志和统计的时间显示正常不然后台看到的记录时间会慢八个小时。在配置目录下运行docker compose up -d等镜像拉完、容器跑起来浏览器访问http://127.0.0.1:3000就能看到登录界面了。首次部署默认会有一个root账号密码好像是123456登录后第一件事就是改掉默认密码这个千万别忘。如果你家里本身有NAS或者软路由也可以直接在上面跑。原理一样只要能跑Docker就行。4.3 配置渠道与创建访问令牌登录后台之后核心操作就是两块配置渠道和创建令牌。先配置渠道。进入“渠道”页面点击新建选择渠道类型。比如我选DeepSeek就填入DeepSeek提供的API Key和各种地址参数。渠道类型不同表单字段会略有差异但基本思路都是“给这个渠道一个名字填入Key勾选该渠道支持的模型”。如果你用的是国内的几家服务商渠道类型里一般都有对应的预设直接选就行。这里有个比较容易踩坑的点渠道类型和“Base URL”的关系。new-api的渠道类型里自带了很多服务商的默认地址一般情况下不用自己填。但如果你用的服务商提供了专用接入地址比如某些平台的兼容模式用的是一个自定义域名那就需要手动把地址填进去。填错地址的话渠道测试会直接报连接错误。配置好渠道之后再进“令牌”页面创建一个新令牌。令牌分为两种一种是给Agent用的“普通API令牌”填进Cline、Roo Code这些插件里另一种是管理用的令牌一般我们不需要。创建令牌时可以设置额度限制比如我给Cline的令牌设了一个月1美元按网关价格估算给Roo Code的令牌设了2美元这样即使某个Agent跑飞了也不会把整个预算烧光。4.4 在AI编程Agent中接入网关这一步其实是最简单的因为网关提供的是OpenAI兼容接口绝大多数编程Agent都支持自定义Base URL。以Cline为例在设置里选择API Provider为“OpenAI Compatible”然后把Base URL填成http://127.0.0.1:3000/v1API Key填成刚才在后台创建的令牌模型填成网关里有的模型名比如deepseek-chat保存即可。Roo Code的配置类似它本身就是Cline的一个增强分支API设置基本一致。Continue的话需要改它的config.json在里面增加一个OpenAI兼容的provider配置。这里有个容易踩坑的细节Base URL一定要带/v1。很多Agent的输入框只需要填到根路径比如http://127.0.0.1:3000但new-api的路由是在/v1路径下的。如果你只填了根路径请求会404。我第一次就栽在这个地方排查了半小时才反应过来。接入完成后先在Agent里发一条简单消息测一下能正常返回就说明链路通了。这时候去网关后台的“日志”页面能看到一条刚产生的请求记录token数量、耗时都清清楚楚。4.5 端到端验证与用量核对接线完成之后别急着收工我习惯做一轮端到端验证确保每个环节都符合预期。第一步验证模型路由是否正确。我故意在一个Agent里配置了模型映射请求gpt-4o-mini然后在网关后台日志里看最终转发的渠道是不是DeepSeek。如果发现走的不是预期渠道就回去检查模型映射和渠道配置。第二步验证令牌限制是否生效。我创建过一个额度极小的令牌比如$0.01然后拿它去请求一个大模型任务很快就能看到请求失败提示余额不足。这说明配额控制在工作。如果你想更稳一点给某个令牌设置一个能跑几十次请求的额度在实际运行中观察它扣费是否正常。第三步验证统计数据可回溯。等业务跑了几天之后我去日志页面按令牌维度筛一遍确认每天的token消费量有记录、费用估算正常。如果发现某天日志断档大概率是网关重启过或者有人改了时间这种问题早点发现比月底才发现要好。5. 常见问题与排查技巧5.1 Key/渠道无法使用报401或403这是最高频的问题。401多半是密钥或令牌的问题403一般是权限或限额问题。排查顺序我建议这样先在后台“渠道”页面点那个渠道的“测试”按钮看渠道本身是否正常。如果渠道测试失败大概率是上游Key过期、余额不足或者上游服务商的接口地址有变。如果渠道测试成功但Agent请求依然401再看Agent里填的令牌是否正确、是否过期、额度是否超额。另外一个容易被忽略的点有些模型服务商有单独的“模型服务”开关不是单纯一个API Key就能调所有模型。比如某些平台需要单独开通某个模型的权限如果你的渠道Key没有该模型权限即使Key有效请求也会以某种方式失败。这时候要去服务商控制台确认权限。5.2 模型名报错、请求直接404或提示模型不存在这个问题通常出在“Agent请求的模型名”和“渠道里配置的模型名”不一致。举例来说Agent里填了gpt-4o-mini但DeepSeek渠道里并没有这个模型于是网关找不到匹配的渠道直接报模型不存在。解法是去渠道配置里打开“模型重定向”功能或者把Agent里的模型名改成网关渠道里真实存在的模型名。我个人更推荐用模型重定向因为这样Agent配置不用改以后想换模型直接后台改映射就行。还有个小坑是大小写问题。某些模型的别名在Agent侧可能被自动转成了小写比如DeepSeek-Chat被转成deepseek-chat导致匹配不到。遇到这种情况在渠道里配置模型名时尽量用Agent实际请求的那个大小写。5.3 用量统计数字不准或日志消失如果你发现统计和预期差距很大先检查两个地方一是渠道配置里的模型单价是不是填错了尤其要注意是按“千token”还是按“百万token”计价二是时区设置。如果容器时区不是Asia/Shanghai日志记录的时间会偏移按天汇总时数据会“串天”。至于日志消失多半是容器重启后数据没有持久化。检查宿主机上./data目录下有没有生成SQLite文件如果文件不存在说明你的volume路径没挂对数据存在了容器内部容器一删就全没了。这个教训我经历过一次之后我每周都会把./data目录打包备份一次。5.4 密钥轮换与团队隔离的建议最后分享一个安全实践层面的建议。无论个人还是团队都不要把同一个令牌到处填。我的做法是给每个Agent、每个项目各建一个令牌并设置各自的额度上限。这样可以做到某个项目跑飞了只影响它自己的令牌我直接在后台禁用它不影响其他Agent正常工作。月底看统计时能精确到“Cline负责的重构任务消耗了多少钱”这种粒度。如果团队里有人离职或者设备丢失只需禁用对应的令牌不需要动上游真实Key。对于上游Key本身我也建立了定期轮换的习惯大概每三到四个月会去各服务商控制台重置一次Key然后更新到网关渠道配置里。这个过程只需要花十来分钟但能把密钥泄露的风险窗口压到最小。毕竟对开发环境来说Key泄露一次可能比丢一台电脑还麻烦。另外如果你把网关部署在需要多人访问的环境里建议在网关前面再套一层轻量反向代理加上Basic Auth或者更严格的身份认证。网关后台本身不推荐直接暴露能锁到内网就锁到内网。搭这套网关的过程前前后后花了我一个周末加几个晚上的时间但用到现在我觉得这笔投入非常值。最直接的改变是我再也不用去挨个Agent翻配置页所有Key都在一个后台里管着哪位Agent调用最多、哪个模型最费钱打开面板一目了然。如果你也在几个编程Agent之间反复横跳、被Key和用量折腾得头疼我建议你也找个周末试着搭一套。按我上面写的步骤走大部分坑你都能绕过去。等用顺手了你大概率也会和我一样感叹一句“早该这么干了”。