本地网关统一管理多AI编程Agent的API Key与用量

说实话，我一开始也没把这事放在心上。装了三四个AI编程Agent之后，突然发现自己手里攒了一堆API Key：DeepSeek一个、豆包一个、通义一个，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 开源网关方案横向对比

我花了一晚上调研了几款主流的开源网关，下面这个表是我当时的对比结果：

这里解释一下为什么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 多渠道路由与模型映射

多渠道路由是网关的核心价值之一。我可以在后台维护若干条渠道，每条渠道对应一个模型服务商，并配置它提供的模型列表。实际请求进来时，网关会根据请求中的模型名自动选择合适的渠道转发。

举个例子，我配了这么几条渠道：

然后在模型映射里做调整，比如把所有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: - TZ=Asia/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/v1，API 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和用量折腾得头疼，我建议你也找个周末试着搭一套。按我上面写的步骤走，大部分坑你都能绕过去。等用顺手了，你大概率也会和我一样，感叹一句“早该这么干了”。