Zen 免费模型中继 kuraneko1/dsh-opencode-zen

dsh-opencode-zen

English ・ MIT ・ 审计备忘

DSH 插件，专供 OpenCode Zen 的免费模型。裸 dsh 和 RDSH 都能跑。

架构

前置条件

| 前置条件 | 原因 |
| opencode 命令 | 必需。Zen 的免费额度只接受「来自 OpenCode 本体」的请求。中继会自动把它作为上游客户端启动。放在 PATH 里，或用 OPENCODE_BIN=/path/to/opencode 指定 |
| Linux / Node 22.19 以上 | 中继需要（systemd 可选） |
| pnpm | 插件管理器要用。install.sh 会先通过 corepack 尝试自动启用，不行就提示你执行 npm i -g pnpm |

不想装 OpenCode 的话，这个插件就用不了。请改用 DSH 标准服务商（deepseek-official、opencode-go 等）。

环境里没有配置档时，install.sh 会交给 dsh plugin 创建配置档（不用手动准备）。
没有 systemd 的环境（容器等）里，中继会在后台启动。

端口

| 端口 | 用途 | 修改方式 |
| 8099 | 应用唯一访问的入口（本地中继）。必须带 token | PROXY_PORT |
| 4096 | 中继在内部启动的专用 OpenCode。无需直接使用 | OC_PORT |
| — | 密钥与状态的存放位置（0600） | FREEMODELS_RUNTIME_DIR |

默认是 8099 和 4096，状态放在 ~/.local/state/dsh-opencode-zen。改端口时，记得给 dsh-opencode-zen-setup 也传 --base-url http://127.0.0.1:<PROXY_PORT>/v1。

安装

curl -fsSL https://raw.githubusercontent.com/kuraneko1/dsh-opencode-zen/main/install.sh | bash

| 想改什么 | 怎么做 |
| 换配置档 | PROFILE=tui bash install.sh |
| 不注册为服务 | SERVICE=0 bash install.sh |
| 指定 OpenCode 位置 | OPENCODE_BIN=/opt/opencode/opencode bash install.sh |
| 停掉中继 | systemctl --user disable --now dsh-opencode-zen.service |

手动安装：

dsh plugin --profile web add https://github.com/kuraneko1/dsh-opencode-zen/releases/download/v0.2.21/dsh-opencode-zen-0.2.21.tgz
"${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/.bin/dsh-opencode-zen-setup" --install --profile web --service

装完后，在模型选择里选 OpenCode Zen（免费）。默认模型不会变。

免费额度只需登录一次

opencode auth login --provider opencode # 在浏览器里登录（只需 1 次）
systemctl --user restart dsh-opencode-zen.service # 登录后重启中继

报 403 OpenCode's free tier can only be used from within OpenCode，说明 OpenCode 里没存凭据（官方 issue #52917 结论相同，给出的修复步骤就是登录）。
没登录的话，真正的 OpenCode 也会报同样的 403。

注意：issue 里写的 opencode auth login opencode 在 1.19 系里不能用（它把位置参数当成 URL，会报 fetch() URL is invalid）。请加上 --provider。

中继只把已保存凭据里 opencode（Zen/Console）这一条 交给专用客户端。其他服务商的凭据一概不复制。没登录时以匿名身份启动，并给出警告。

补充：以前匿名（无凭据）也能用免费额度，后来提供方收紧了匿名通道。opencode 服务商的凭据不是 OAuth，而是 API key（OPENCODE_API_KEY），官方步骤是在 opencode.ai/auth 登录后获取 key（登录时可能要求填账单信息。免费模型 cost 为 0）。

出现 403 FreeTierError 时

先做诊断（经中继实际请求一次）：

node zen-doctor.mjs

实测结论（2026-10-17）：同一账号、同一版本，线路出口是 IPv6 就通过，是 IPv4 就被拒。 本机 IPv4 219.8.20.246 被拒，z170-desktop 的 IPv6 2402:6b00:… 成功（没有伪装客户端）。

- 判定为 IPv4 时 → 开启线路的 IPv6，或改用出口已被接受的主机上的中继： ssh -N -L 8099:127.0.0.1:8099 ryu@<そのホスト> # 相手の中継をローカル8099へ

DSH 侧的凭据要跟对端主机的 proxy.key 保持一致（dsh-opencode-zen-setup --install --key-file <那个文件>）。
- 有时也需要凭据（opencode auth login --provider opencode）。有些线路匿名就能通过，所以没设置凭据也不一定马上失败。
- 如果仍然返回 403，那就是提供方的判断了。这个插件不会绕过它。

出现「原生 CLI 能通，走中继却 403」的时候

提供方的网关看的是线路的出口（2026-10-17 实测：同一账号、同一版本，IPv6 出口被接受，IPv4 出口被拒绝）。
实际上这台主机有线连接是 ipv6.method=disabled，没有 IPv6，走的是 IPv4 出口，所以被拒绝了。步骤如下：

1. 检查线路 ip -6 route show default # 没有默认 IPv6 路由就说明没走 IPv6
curl -6 https://api64.ipify.org # 返回 200 就说明走的是 IPv6

2. 没有就启用（例如 NetworkManager） nmcli connection modify "<连接名>" ipv6.method auto nmcli device reapply <NIC>

3. 后启用 IPv6 之后，要重启中继
systemctl --user restart dsh-opencode-zen.service

专用 OpenCode 在启动时决定路由，所以即使后来有了 IPv6，它自己也不会切换（这就是「原生 CLI 能通，只有中继 403」的真相）。
0.2.21 起，如果拒绝持续发生、又检测到 IPv6 新变得可用，会自动重启专用 OpenCode。
4. 状态可以用 GET /health 查看：egress.ipv6（这台机器是否有全局 IPv6）和 refusals.count（被上游以 403 拒绝的累计次数）。

不带工具的请求也能通过

上游网关会拒绝不带工具的请求（实测：不带工具返回 403，同样内容带 1 个工具返回 200）。
DSH 正常的智能体调用一定带工具，所以不成问题；但为了应对摘要、标题生成这类内部调用，不带工具时会只附带一个最小的工具定义发出去，返回的工具调用不交回调用方，直接丢弃 （因为调用方并没有要求工具）。

需要了解的事

- 长会话：deepseek-v4.1-flash-free 和 glm-5.3-flash-free 按实测 1M（999,312 / 1,047,653 token）声明。其他模型保持公开值
- 不带工具的单次请求会被提供方返回 403 FreeTierError。DSH 会发送真实的工具，所以正常使用能通过
- 空的配置档下，可能会要求你批准 DSH 自身依赖的构建（pnpm approve-builds）。这个插件没有构建脚本
- 仅限带认证的 loopback。Zen 的凭据（用 opencode auth login --provider opencode 保存的 API key）有些线路需要、有些线路不需要（实测有匿名就能通过的例子）。中继只要存在保存的凭据，就只采用 opencode 这一条（免费模型本身 cost 为 0）
- 不保证免费额度持续、全模型、未来版本

详细限制见 AUDIT.md，变更记录见 CHANGELOG.md。