opencode 免费通道 TLS 指纹门禁 — 补丁与实测记录
这是一个补丁 + 技术记录,不是可直接安装的插件包。 它记录 2026-11-13 在
dsh-our-free-model 上定位到的一个门禁问题、实测证据、以及一份可选的绕过实现。
⚠️ 使用前必读:本补丁绕过了上游新增的客户端校验
请你先完整读完这一节再决定要不要用。
1. 这个补丁在做什么
opencode.ai 的匿名免费通道在 2026-11 期间加了一道客户端身份校验:它按 TLS 握手的
指纹(JA3)区分「是不是它自己的客户端」,不认识的连接一律返回
FreeUsageLimitError(HTTP 429),与请求内容无关。
本补丁的做法是:当免费通道返回这个错误时,改为调用官方开源的 opencode 命令行程序
(opencode run --format json)去完成这一次请求,再把结果转回原有的流式格式。
换句话说:它让第三方程序借用了官方客户端那条会被放行的连接,从而使用上游原本可能 并不打算开放给第三方的免费额度。
2. 这可能违反上游的服务条款
- opencode.ai 的服务条款与用量政策由你自行查阅并遵守。本补丁的作者不是这些条款的 当事方,也不代表上游做任何解释。
- 上游维护的
dsh-our-free-model在 README 中已明确写明:「上游条款由你遵守。使用各 渠道即表示你同意对应上游的服务条款与用量政策;因违反上游政策导致的限流、封禁或其它 后果由使用者自行承担。」 - 免费额度是上游单方面提供、可随时收紧或关闭的。绕过一道刚加上的校验,很可能正是 上游试图阻止的行为。
- 若上游因此收紧策略、封禁账号或采取其它措施,后果由使用者自行承担。
3. 本补丁不承诺任何东西
- 不承诺能用、不承诺能一直用、不承诺不被封、不承诺上游不会改变策略。
- 不承诺正确性:桥接路径有真实的能力降级(见下节)。
- 作者不对任何直接或间接损失负责。
4. 能力降级(务必知道)
走桥接路径时,模型决定要用的工具(shell、读写文件等)是由那个官方 agent 自己执行的, 不是交回你的程序、按你的权限审批链执行的。因此:
- 你拿到的是「已经执行完的结果文本」,不是一次待你批准的工具调用;
- 那些命令没有经过你自己的审批、沙箱或审计;
- 你的对话内容会经过官方 client 的完整 agent 流程(它会注入自己的系统提示与工具集)。
本仓库的桥把这份授权收窄到只读:read / list / glob / grep / external_directory 放行,
bash / edit / write 一律拒绝 —— 官方 agent 可以读、不能改、不能起 shell。
这是一份独立的临时配置(经 OPENCODE_CONFIG 传给子进程),
不会改动你自己 ~/.config/opencode 的任何设置。
这个收窄不是可选的礼貌,缺了它整条路就是死的。 早期版本没给权限配置, 官方 CLI 在非交互模式会把「需要授权」自动拒绝,然后那一轮直接结束、不产出任何正文。 表面现象是桥报
produced no text、上层最终回显上游那句 429 —— 看起来像「补丁失效了」, 实际是官方 agent 想去读文件、被它自己的权限系统挡住了。任何 agent 类回合(带 tools 的) 都会稳定踩到,而这类回合恰恰是最常见的形态。详见下方「实测记录」最后一节。
如果这不可接受,请不要启用这一路径(本文档附带的代码是可选回退,正常直连优先)。
5. 不要用它做这些事
- 不要用它做高频/并发批量调用、压测或爬取——这既伤上游也最容易导致封禁。
- 不要用它传输密码、密钥、个人身份信息、商业机密或任何你不愿第三方处理的内容。
- 不要把它包装成「免费无限额度」对外宣传或转售。
- 不要用它访问你不被授权访问的资源。
这个仓库里有什么
src/official-bridge.js 新增模块:把官方 CLI 当作回退传输层
patches/http.js.diff 对上游 2.8.0 的 src/http.js 的补丁(43 行新增)
tests/official-bridge.test.mjs 离线回归(9 项,不依赖网络)
仓库里不包含上游代码。official-bridge.js 是独立新文件;http.js 以补丁形式给出,
你需要自备上游的 dsh-our-free-model 2.8.0 才能应用。
门禁是怎么被定位的(实测记录)
同一出口、同一时刻的对照
| 客户端 | TLS JA3 | 密码套件 | 扩展 | 结果 |
|---|---|---|---|---|
官方 opencode 二进制(Bun 1.3.14) |
4b74b406489f0541b7dd8c6638e9bb88 |
17 | 14 | 200 正常出字 |
node fetch(undici) |
d0642faa769160a231dbd70e346d3790 |
52 | 12 | 429 |
bun -e 'fetch(...)' |
fef5c9001831a7739f735d0b118547ce |
17 | 13 | 429 |
官方指纹两次独立测量完全一致;bun 裸跑与官方套件数相同、只差一个扩展就被拒,
说明校验很紧。
排除掉的其它可能(都是实测,不是推测)
| 假设 | 反证 |
|---|---|
| 配额用尽 | 同一秒官方成功、第三方 429;跨过 Retry-After 反解的 UTC 零点后仍 429 |
| 出口 IP 被封 | 换 4 国 5 个 IP、绕过 TUN 走家宽,全部 429;官方走同一个代理仍成功 |
| 请求头/体/路径不对 | 用 MITM 抓到官方真实字节(含 38KB 系统提示 + 13 工具 + max_tokens:32000)逐字节重放仍 429;两条路径都试过 |
| 插件版本旧 | 已升到 2.8.0(上游 v2.8.3 的发版说明与免费通道无关) |
结论:闸门在 socket 层,不在应用层。任何改 header / 改 body / 换 IP 的尝试都不可能通过。
如何应用(仅限你确实决定要用的场合)
- 自备上游插件
dsh-our-free-model@2.8.0并解包。 - 复制
src/official-bridge.js到package/src/。 cd package/src && patch -p1 < <本仓库>/patches/http.js.diff(补丁已实测:在 2.8.0 原版上应用后与验证过的成品逐字节一致)。- 确保机器上装有官方
opencode可执行文件;否则用OUR_FREE_MODEL_OFFICIAL_BIN=/path/to/opencode指定。 - 运行
node tests/official-bridge.test.mjs,应显示10 checks passed。
改动行为:正常直连优先,只有收到 FreeUsageLimitError 且本机有官方二进制时才走桥接;
桥接失败会回落到原始错误,不掩盖上游的回应。
实测结果(供参考,不构成承诺)
transport: official-bridge
单轮 8.5s 出字 ✅
多轮上下文保留(7391 → 7391) ✅
带 13 工具的 DSH 真实回合 7.0s ✅(工具由官方 agent 执行)
连续 3 次 5.1~10.3s,usage 帧正常 ✅
离线回归 10/10 ✅
补记:第一版「看起来修好了」,其实只测了最不容易踩坑的那一类回合
第一版上线后,用户重启,仍然报同一句 Free usage limit reached。不是 TLS 反复,也不是没生效:
| 检查 | 读数 | 说明 |
|---|---|---|
| 包安装时刻 vs 进程启动 | 19:57 → 20:01 | 进程在装机之后,排除「磁盘修好、内存没换」 |
| 单独调桥 | 6.0s 出字 | 排除 TLS 与二进制路径 |
| 宿主 stderr | official bridge could not carry the turn (the official client produced no text) |
桥跑了,但零正文 |
手工跑同一条命令,事件流是这样结束的:
step_start
→ permission requested: external_directory (/etc/*); auto-rejecting
→ tool_use(read, state.error="The user rejected permission ...")
→ step_finish(reason=tool-calls) ← 进程到此结束,一个 text 都没有
根因:非交互模式下,官方 CLI 会把「需要授权」自动拒绝,然后这一轮直接结束。 而 agent 类回合(带 tools、提示词里提到文件路径)几乎必然触发它 —— 第一版只验证了 「纯文本回合」,于是拿到了一整片假绿。
修法:给子进程一份只读权限配置(见上文「能力降级」)。
external_directory 必须放行 —— 官方把 cwd 之外的任何路径都判为「外部」并询问,
而询问在非交互下就是拒绝,这是同一故障的第二个入口。
修后同一场景实测:200 / x-our-free-model-transport: official-bridge / 178 字符正文,
且事件流里能看到 tool_use(read, completed) —— 官方 agent 确实读到了文件再作答。
回归用例也补了一条:用一个假二进制把 OPENCODE_CONFIG 抄出来,逐项断言
read=allow、external_directory=allow、bash|edit|write=deny —— 以后谁"顺手收紧权限",这条会先红。
更正当的替代路线
如果你只是想让自己能用,把这个问题报给上游往往比私下绕过更划算: 上游维护者在 issue 里明确说过「上游收紧、插件侧无法用代码修复」, 但他们不知道这次是 TLS 指纹门禁。把上面的 JA3 对照给他们,让他们决定是否跟进, 风险就留在项目方那边而不是你身上。
许可
src/official-bridge.js 与 tests/ 以 MIT 发布。
上游 dsh-our-free-model 本身亦为 MIT(Copyright (c) 2026 Ebony-Vinyl);
本仓库不包含其代码,仅以补丁形式引用其修改点。使用上游代码请遵守其许可与条款。
opencode / OpenCode 是各自权利人的商标或产品名,本项目与其无隶属、认可或赞助关系。
No comments yet. Be the first to write one.