最近在折腾 AI 编程和自动化流程的时候，发现一个特别有意思的玩法：把某个开源编码终端自带的免费模型额度，通过本地网关转给其他 AI agent 工具用。听起来有点绕，但其实落地后非常香——相当于一份免费资源，同时喂饱好几个干活的应用。这篇文章就把这套免费模型接入与复用的思路、配置、坑点完整写出来，给正在研究低成本 AI 落地方案的开发者做个参考。
核心关键词：opencode 免费模型、模型路由、agent 接入、API 复用、本地网关配置。
这个玩法适合谁？如果你手头有多个 agent 工具，比如自动写代码的助手、跑测试的机器人、日常问答的小助手，都在花钱买各种模型 API，那这套方案能帮你把其中一部分流量切到免费额度上，实测下来每个月能省下不少成本。当然，前提是你愿意花一点时间做配置，而且对本地网络和 API 转发有基础概念。文章里所有步骤我都按复现标准写，跟着做就行。
1. 玩法拆解：为什么免费模型能“给别的 agent 用”
很多开源编码终端产品，本身会捆绑一些免费模型服务，这个“捆绑”不是简单的网页聊天，而是通过后端 API 把模型能力开放给终端调用。关键点在于：这套 API 的调用链路、鉴权方式、模型路由逻辑，实际上是独立于终端 UI 的。也就是说，只要我们能拿到调用细节，完全可以把这份额度“分享”给其他程序。
1.1 底层链路：终端、网关、模型服务三者的关系
从架构上看，整个调用链路由三层组成：终端界面负责交互，本地网关负责转发和鉴权，模型服务端负责真正执行推理。opencode 这类工具在安装后，会在本地起一个服务，所有对话请求先打到这个本地服务，再由它带着你的凭据去访问远端模型接口。
这里有个容易被忽略的设计：本地网关的地址和端口是固定且可配置的，模型名称也支持自定义映射。这意味着我们可以把本地网关当成一个“中转站”，让外部程序也往这个中转站发请求。只要中转站能识别请求格式，并按规则把模型名替换成免费通道对应的名字，再把结果返回给调用方，就实现了复用。
1.2 “白嫖”的技术本质：额度共享与请求转发
所谓白嫖免费模型给其他 agent 使用，本质上做两件事：第一，复用已有的免费模型账号额度；第二，把其他 agent 的请求格式转成终端网关能识别的格式。很多 agent 工具支持 OpenAI 兼容的对话补全接口，而终端网关往往也提供同类接口，这就是天然的对接点。
举个例子，某个 agent 工具默认请求地址是http://localhost:8000/v1/chat/completions，模型名填的是gpt-4o-mini；而免费通道只支持一个叫free-model的模型名。我们可以在网关层做一层模型名改写，把gpt-4o-mini改写为free-model，这样 agent 无需任何改动就能用上免费额度。
需要特别说明：这里并不是破解或绕过任何限制，而是在遵守服务条款的前提下，复用本机已拥有的模型调用资格。具体某款产品的免费规则以官方文档为准，使用前请仔细阅读条款。
1.3 适用场景与不适合的场景
这套思路最适合的场景是个人开发环境、本地测试环境、小团队内部工具集成。比如你有三个 agent 都在跑，高峰期同时调用付费 API，免费额度往往被闲置，通过路由把一部分请求切过去，整体开销立刻降下来。
不适合的场景包括：生产环境高并发调用、对响应速度有硬性要求的业务、需要专用模型能力（比如长上下文超强推理）的严肃任务。免费模型通常有速度限制，排队严重时可能长达几十秒，用于测试、批处理、低优先级任务更合适。
2. 准备工作：环境、账号与工具选型
在动手之前，先把环境和账号整理好。整个过程不复杂，但走错一步排查起来挺费劲。
2.1 安装 opencode 并确认免费模型可用
第一步是安装 opencode 软件本体。安装过程不细说，各系统都有对应安装方式，装完后正常启动，在设置界面找到模型管理部分，确认免费模型的开关是打开的。这里有一个关键动作：必须先在终端里发起一次真实对话，确认免费模型能正常返回内容。这一步能排掉账号初始化、余额确认、网络连通性等一系列潜在问题。
实测中遇到过一种情况：免费模型列表能看到，但一发送就报错“insufficient quota”。原因一般是账号没有完成某种验证（手机号或邮箱验证）。所以务必先人工验证一轮，再进入后面的配置。
2.2 获取调用凭据与基础参数
免费模型虽然不用付费，但调用时依然需要带着一个 token 或 API key。这个凭据一般在终端设置的“账户”页面可以找到。如果界面上没有直接展示，可以查看本地配置文件，里面通常会以明文或加密形式存储账号信息。
拿到凭据后，把以下几个参数记下来备用：
- 模型名称（免费通道对应的确切名称，比如
free-model-v1） - 本地网关地址（通常是
127.0.0.1加一个端口） - API 路径（一般是
/v1/chat/completions） - 鉴权头格式（
Authorization: Bearer <token>）
2.3 确认其他 agent 支持的标准接口
这个环节容易被忽略。不是所有 agent 工具都能自定义 API 地址和模型名，有些是硬编码的。在动手之前，先看几样东西：
- 是否支持自定义接口地址（base_url / api_base）
- 是否支持自定义请求头（header）
- 是否支持修改模型名（model_name）
- 是否支持代理设置（proxy）
这三项里至少前两项要支持，否则后面没法玩。绝大多数开源 agent 框架（比如某知名的终端助手、某自动化测试框架）都支持环境变量覆盖默认接口地址，问题不大。
提示：如果某个 agent 只支持 HTTPS 地址，不支持 HTTP 本地地址，那需要额外加一层 TLS 边缘代理。多数工具没有这么严格，但遇到时要有 awareness。
2.4 工具选型：用现成网关还是自己写路由
如果要转发的 agent 只有一个，而且它支持自定义 base_url，那最简单的方式是把 agent 的 base_url 直接指向 opencode 的本地网关，模型名改成免费模型名，完事。但如果我们想同时给多个 agent 用，或者想对请求做更精细的控制（比如多账号轮询、接口格式转换、日志记录），我建议额外加一个轻量网关。
轻量网关的选择有三个方向：
- 直接用支持自定义转发的 API 网关（如某知名开源 API 网关，但这类一般偏重）
- 用脚本写一个几十行的转发服务，基于标准库即可
- 用现成的模型路由代理工具，但要注意它是否支持自定义上游
综合来看，我最推荐自己写一个转发服务，理由很简单：这次的需求极其单一，就是把 A 接口转成 B 接口，改改模型名，加一下鉴权头。引入重型依赖反而增加维护成本。
3. 核心配置：模型名映射、鉴权与路由规则
这一节是整个过程的重点，也最容易出错。配置如果不正确，轻则模型名报错，重则凭据泄露。分三块讲。
3.1 配置 opencode 本地网关的监听参数
默认情况下，opencode 的本地网关监听在回环地址，端口通常是某个高位端口。为了让其他 agent 能访问，我们需要确认它监听的可达范围。如果所有 agent 都跑在同一台机器上，用127.0.0.1就行；如果 agent 跑在容器里，就要让网关监听0.0.0.0，并注意端口映射。
以某版本为例，配置文件里有一段网络监听设置：
{ "host": "127.0.0.1", "port": 8765 }改成外部可访问时，要注意开放防火墙端口，同时考虑安全问题。因为网关带着你的完整访问凭据，暴露在非回环地址上后，局域网内任何设备都能用它消耗你的额度。如果是暂时测试，建议保留127.0.0.1，配合容器network_mode: host或端口转发处理。
3.2 编写模型名映射规则
免费模型通道往往只认一个或几个特定模型名。比如你开通的是free-flash，但 agent 工具请求时用的是gpt-4o，这就会导致 404 或者 400 报错。
模型名映射的核心思路：在网关层把入站请求里的模型名字段取出来，查配置文件里的映射表，如果命中就直接替换，没命中则原样透传。映射表建议用 JSON 存，方便扩展：
{ "gpt-4o": "free-flash", "gpt-4o-mini": "free-flash", "claude-3.5-sonnet": "free-flash" }这里有一个常见误区：不是所有 agent 工具发过来的模型名都是标准名，有的会在模型名后面带上版本后缀，有的带路径前缀。处理办法是“先截取最后一段，去掉所有/与:，再做精确匹配”。如果匹配不到，不要 fallback 到免费模型，避免一次异常的模型调用触发额度超限。
3.3 鉴权转发：怎么安全地把凭据带给上游
opencode 本地网关收到请求后，通常自带鉴权校验，只会检查请求来源的 token 是否合法。但我们转发的场景里，agent 工具可能不会主动带 token，或者带的 token 是它自己配置的假 token。
因此转发服务要做两件事：
- 对外校验：验证调用方传来的 token 是否匹配你自己设定的一个“共享密钥”
- 对内注入：与共享密钥校验通过后，把请求头发送出去前，替换成 opencode 网关认识的真实凭据
具体实现片段如下（Python 伪代码）：
import json from http.server import BaseHTTPRequestHandler UPSTREAM_URL = "http://127.0.0.1:8765/v1/chat/completions" SHARED_TOKEN = "my-shared-secret" REAL_TOKEN = "the-real-token-from-config" class Proxy(BaseHTTPRequestHandler): def do_POST(self): if self.headers.get("Authorization") != f"Bearer {SHARED_TOKEN}": self.send_error(401) return body = json.loads(self.rfile.read(...)) body["model"] = map_model(body.get("model")) # 重新构造请求，带上REAL_TOKEN，发到UPSTREAM_URL这段逻辑里最重要的就是“替换头部 token”这一步。千万不要把真实 token 直接配到 agent 里，万一 agent 配置同步到团队其他人手里，等于把额度拱手送人。
3.4 多账号轮询与限流策略（进阶）
免费模型的每日调用额度通常不是无限量。如果你身边有多个账号，可以在网关层做账号池管理。思路是配置多组上游地址和凭据，每次请求时按顺序或按权重取一个上游。
限流策略同样建议做在网关层，而不是依赖单个 agent 的 self-limit。比较简单的做法是用令牌桶，但考虑到转发服务本身已很轻量，不必引入复杂算法，直接基于请求时间戳做滑动窗口计数即可。举个例子，如果每秒最多 3 个请求，每 5 分钟最多 200 个请求，就维护两个计数器，超了直接返回 429。这样能很好地避免触发上游账号的限流封禁。
4. 实操过程：一个最小可运行的转发服务
讲了这么多概念，现在完整跑通一个最小实现。我以 Python 标准库 + requests 为示例，全程无需安装第三方 web 框架，方便快速部署在任何内网机器上。
4.1 最小服务代码框架
首先准备一份proxy_server.py：
import json import requests from http.server import HTTPServer, BaseHTTPRequestHandler UPSTREAM_BASE = "http://127.0.0.1:8765/v1/chat/completions" SHARED_TOKEN = "shared-secret-change-me" REAL_TOKEN = "real-token-from-config" MODEL_MAP = { "gpt-4o": "free-flash", "gpt-4o-mini": "free-flash", "claude-3.5-sonnet": "free-flash", } class Handler(BaseHTTPRequestHandler): def do_POST(self): if self.path != "/v1/chat/completions": self.send_error(404) return auth = self.headers.get("Authorization", "") if auth != f"Bearer {SHARED_TOKEN}": self.send_error(401) return length = int(self.headers.get("Content-Length", 0)) payload = json.loads(self.rfile.read(length)) model = payload.get("model", "") mapped = MODEL_MAP.get(model) if mapped is None: self.send_error(400, "model not allowed") return payload["model"] = mapped headers = { "Authorization": f"Bearer {REAL_TOKEN}", "Content-Type": "application/json" } resp = requests.post(UPSTREAM_BASE, headers=headers, json=payload, timeout=120) self.send_response(resp.status_code) self.send_header("Content-Type", "application/json") self.end_headers() self.wfile.write(resp.content)这段代码的核心价值在于：只接受带有共享密钥的请求，白名单模型映射，其他一律拒绝。逻辑清晰，出了问题好排查。
4.2 启动并验证转发功能
启动服务：
python3 proxy_server.py服务默认监听 8000 端口。留意外面来的 agent 请求会打在这个端口上。如果你不想直接用 8000，可以给 HTTPServer 传入自定义端口。
验证步骤分两层。第一层，用 curl 直接测转发服务：
curl -X POST http://127.0.0.1:8000/v1/chat/completions \ -H "Authorization: Bearer shared-secret-change-me" \ -H "Content-Type: application/json" \ -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]}'如果返回 200 且出现content字段，说明链路已经通了。第二层，启动一个 agent 工具，把 base_url 改成http://127.0.0.1:8000/v1，模型名填gpt-4o，密钥填共享密钥，触发一次实际任务。能正常输出，整个方案就成立。
注意：curl 测试时一定要留意返回头里的
Content-Type是否被正确透传。有的 agent 对返回格式的content-type极其敏感，如果上游返回text/plain或application/octet-stream，智能体可能解析失败，表现为“返回了但没内容”。所以网关透传时尽可能保留上游的 Content-Type。
4.3 日志与观测：怎么知道请求是否走对通道
转发服务跑了之后，最怕的是“看起来通了，但用的还是付费通道”。所以必须在日志里记录每次请求的目标模型名。我建议加一行日志：
print(f"[{time.time():.3f}] model={model} -> {mapped} from={self.client_address[0]}")实测中遇到过一种隐蔽情况：某个 agent 框架在初始化时，会额外发一个“探测请求”来检查模型类型，它会先把请求发到/v1/models而不是/v1/chat/completions。如果你的网关只实现了对话补全接口，探测请求会返回 404，框架就会认为模型不可用，直接放弃切换 base_url。解决方案是额外实现一个GET /v1/models的返回：
def do_GET(self): if self.path == "/v1/models": self.send_response(200) self.send_header("Content-Type", "application/json") self.end_headers() self.wfile.write(json.dumps({"data": [{"id": "gpt-4o"}, {"id": "gpt-4o-mini"}]}).encode()) else: self.send_error(404)这个小细节能避免很多 agent 的兼容性问题。毕竟它们大多不是为第三方中转站设计的，接口规范越多越友好。
4.4 部署位置：本机、容器还是内网服务器
从实用性角度，有三种部署位置可选：
- 本机部署：最省事，适合和 agent 在同一台机器。缺点是本机待机时，其他设备无法使用
- Docker 容器部署：适合开发环境，需要把端口映射到宿主机。注意容器内访问宿主机网关的地址要用
host.docker.internal（Mac/Windows）或172.17.0.1（Linux） - 内网小服务器部署：适合团队共享。这时必须考虑鉴权和限制来源 IP
无论哪种部署，核心原则是：要对外可达但不对外公开。你不想让整个局域网或公网的人都能拿着你的密钥消耗额度。如果放在服务器上，建议在防火墙层面只允许信任网段来源访问端口。
5. 常见问题与排查：避坑记录
整个流程踩下来，有几个问题几乎是每个人都会遇到的，单独列出来细说。
5.1 免费模型报错“model not found”怎么办
这八成是模型名映射没配置对。先不要急着改网关代码，直接用 curl 打给 opencode 本地网关，看看它接受什么模型名：
curl -X POST http://127.0.0.1:8765/v1/chat/completions \ -H "Authorization: Bearer <real-token>" \ -H "Content-Type: application/json" \ -d '{"model": "free-flash", ...}'能通，说明网关层正常，问题在映射表。不能通，说明免费通道的模型名不叫这个。去 opencode 的模型列表页核对准确名称。我遇到过一次模型名大小写不一样导致的 404，用 UI 里显示的名字核对后，问题瞬间解决。
5.2 agent 报错“Invalid base_url”
有些 agent 工具内置了对 base_url 的校验，要求必须是标准 URL，且不能是纯 IP 加端口这种形式。解决办法是在 base_url 前加一个标准路径：
http://127.0.0.1:8000/v1如果还不行，检查 agent 是否强制要求 HTTPS。本地 HTTP 无法满足时，可以内网部署一个简单的反向代理，把 HTTPS 443 端口映射到本地服务，但这需要证书，实践成本稍高。多数工具不会走到这一步，遇到再说。
5.3 请求卡死或长时间无响应
这个问题的根源通常是免费模型的排队机制。免费通道在高峰期的排队时间可能长达几十秒，而多数 agent 自带的超时时间只有 10 秒。于是表现为请求发出去后，agent 端先超时了，但网关其实还在等上游返回。
解决方向有几个：
- 调大 agent 端的请求超时时间，建议至少 60 秒
- 在网关层做异步转发，先把请求接住，立即返回一个“排队中”的占位响应，等上游算完再推送。但很多 agent 不支持这种异步模式，所以实用性不强
- 提前把一些简单任务改成离线批处理，避开高峰期访问
5.4 长时间运行后突然 401
这通常不是网关坏了，而是上游免费通道的 token 过期了。免费通道的 token 有时效限制，可能几小时或几天就换一次。如果你发现白天还能用，晚上突然全 401，多半是 token 刷新了。
解决办法有两个：
- 每天人工检查一次本地网关的连通性，发现 401 就去配置里拉新的 token
- 写一个定时任务，定期检测本地网关的健康状态，如果连续 N 次失败，发个通知提醒自己
自动化脚本不复杂：
*/10 * * * * curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8765/v1/models | grep -q 200 || echo "gateway down"收到提示后再手动去换 token，成本不高，胜在及时。
5.5 并发过多导致免费额度被迅速用完
免费模型通常有每小时或每请求的硬性限制。如果同时跑 10 个 agent，高峰期 60 个请求一拥而入，很可能几分钟内触发限流。网关层加上简单的并发限制能有效缓解。
最简单的实现是“同时最多处理 4 个请求”，多余请求直接返回 429：
import threading semaphore = threading.Semaphore(4) def do_POST(self): if not semaphore.acquire(blocking=False): self.send_error(429, "Too Many Concurrent Requests") return try: ... finally: semaphore.release()这样既不会把上游打死，也能让其他 agent 的请求快速失败而不是等半天。失败后的重试策略由 agent 自己决定，一般情况下没问题。
6. 安全与合规：哪些细节必须守住
这部分的优先级比功能实现更高。因为转发服务一旦部署，就相当于把账号凭据管理权从终端工具转移到了你写的网关。出任何安全事故，代价都很大。
6.1 密钥隔离：共享密钥与真实密钥分离
前文提过，agent 配置里只能放共享密钥，真实 token 放在网关环境变量或本地配置文件中。我见过一个团队直接把真实 token 写在 agent 的工具配置里，结果配置随代码仓库同步到了公开仓库，几小时内额度就被刷爆。这是个很痛的教训。
建议把真实 token 放到单独的环境变量读取：
import os REAL_TOKEN = os.getenv("OPENCODE_REAL_TOKEN")这样即使代码被盗取，token 也不会跟着泄露。
6.2 限制来源 IP 与调用频率
如果网关部署在服务器上，除了共享密钥，再加一层来源 IP 白名单会更安全。很多开源 API 网关自带 IP 过滤功能，我用的自写工具比较原始，直接塞一个 CIDR 判断。如果你不想自己实现，可以让防火墙层面设置来源 IP 规则，再配合共享密钥双保险。
频率限制这一层，除了防止上游限额被打爆，还能缓解“恶意调用”问题。即使共享密钥被别人拿到，限流也会把损失控制在较低水平。比如设置每分钟 60 次，即便被刷，一个小时的消耗也就在 3600 次左右，还在可控范围内。
6.3 使用条款边界
最后再说一下合规。免费模型的服务条款通常规定只能通过官方终端或其认可的渠道调用。通过自建网关转发给其他 agent，在某种程度上属于“灰区”。不同产品条款差异很大，有的明确禁止这样做，有的只是没说而已。
我的建议是：个人学习、本地实验、小范围团队测试用起来没压力；如果要进入生产环境或商业化项目，务必先阅读该免费模型服务的条款，确认允许接入第三方工具再放大使用。实际上很多厂商反而希望开发者用 API 接入，所以只要不滥用、不绕过计费，通常不会为难正常测试和开发。
7. 进阶玩法：从转发到统一模型路由
如果在上面这些都跑通了，可以继续扩展一层：把网关从单一免费模型转发器升级成通用的模型路由中心。这时候你能做的就远不止“白嫖”一个模型了。
7.1 多模型统一入口与降级策略
假设团队开发环境里有多个模型可用：免费模型、付费大模型、本地部署的开源模型。每个 agent 可能需要在不同任务里使用不同模型。统一路由中心的价值在于：同一个接口地址，根据不同任务标签自动选择最合适的模型。
比如在请求体里加一个自定义字段"preference": "fast"，网关解析后路由到速度快的免费模型；"preference": "strong"时路由到付费高能力模型；如果付费模型报错，自动降级回免费模型，保证任务不会中断。这个策略在真实开发中非常实用。
7.2 缓存层：避免重复请求烧掉额度
如果你有一批重复度很高的测试任务，可以给网关加上一层简单缓存。相同请求内容在短时间内直接返回历史结果，不再打到上游。这个对“单元测试生成”“重复格式转换”类任务效果尤其明显。
缓存实现不复杂，用字典加过期时间就行：
cache = {} CACHE_TTL = 600 def get_cached(key): entry = cache.get(key) if entry and time.time() - entry["ts"] < CACHE_TTL: return entry["data"] return None上线缓存后，你会发现免费额度的消耗速度进一步下降。不过有一个坑：如果上游模型更新迭代了，缓存结果可能过时，建议只对结果较稳定的任务开启缓存。
7.3 汇总日志与分析利用情况
统一路由中心的另一个好处是能收集全链路使用日志。日志里记录谁、在什么时候、调了什么模型、消耗了多少 token。攒上一周，用 pandas 或 CSV 简单分析一下，哪些 agent 在真正干活、哪些在空转、哪些模型调用占了 80% 的消耗，一目了然。
这个数据对后续成本优化特别有价值。比如你发现某个 agent 每天在同一时段疯狂调用免费模型，因为队列阻塞导致任务失败率升高，那就知道应该给它补充一个付费备用通道，或者调整任务执行时段。
8. 个人体会与最后的实用建议
折腾完这套方案后，我的整体感受是：技术上并不复杂，真正的难点是“摸清各方工具的接口规范差异”。opencode 这类工具提供了很灵活的接口，让复用变得可行，但不同 agent 往往有不同的“预期”，有的期望你返回特定格式，有的对鉴权头很挑剔，有的会额外探测接口。把这些“预期”一一满足，才能让整套链路稳定跑起来。
最后分享一个实用小建议：如果你只想快速上手，不想写代码，可以先尝试最朴素的方案——把某个 agent 的 base_url 直接指向 opencode 本地网关，模型名改成免费模型名。这个方案虽然不灵活，但五分钟就能验证可行性。等确认能跑通，再决定要不要升级成带映射和限流的转发服务。大部分人的需求其实到第二步就够了，别一上来就搞复杂架构。
