前言¶

在 DSH 中使用 OpenCode ZEN 免费模型时，会遇到一类请求头未生效的问题：provider 配置里已经写了请求头，但实际 API 请求仍可能被识别为 deepseek-harness，于是返回 429 FreeUsageLimitError。

dsh-plugin-zen-useragent 针对这个问题：它让 provider 配置的请求头（如 User-Agent）真正到达 pi-ai 的 API 请求，把请求识别为 opencode 客户端而不是 deepseek-harness。

这是什么¶

这是一个由 jiujiezongheti 维护的 DSH 插件。仓库标识为 jiujiezongheti/zen-useragent，包名为 dsh-plugin-zen-useragent，许可证为 MIT。

它解决的核心问题是：OpenCode ZEN 免费模型在 DSH 中因客户端标识不符合预期而返回 429 FreeUsageLimitError。

核心功能¶

• 让 provider 配置的请求头（如 User-Agent）到达 pi-ai API 请求。
• 修复 OpenCode ZEN 免费模型 429 FreeUsageLimitError。
• 通过补丁 requestHeaders 让配置 headers 覆盖 attribution。
• DSH 升级后自动重新打补丁。
• 补丁幂等，每次启动自动执行。

安装与启用¶

1、将插件安装到 web profile。从 GitHub 源安装：

dsh plugin --profile web add github:jiujiezongheti/zen-useragent

或从 npm 安装：

dsh plugin --profile web add dsh-plugin-zen-useragent

2、安装或卸载后执行：

dsh web

3、启动终端出现下面这种输出时，表示补丁生效：

[dsh-plugin-zen-useragent] patched: ...

典型用法¶

在 settings.yaml 的 opencodezen provider 中配置请求头，例如：

opencodezen:
  headers:
    User-Agent: opencode/1.18.18
    Referer: https://opencode.ai

保存后执行：

dsh web

重启后切换到 opencode 免费模型发送一条消息，如不再出现 429，即可认为该插件生效。

适用场景与注意¶

• 适合在 DSH 中配置 opencodezen provider，并希望在 API 请求中保留自定义 User-Agent 等 headers 的场景。
• 补丁只影响 provider 显式配置了同名请求头的情况；未配置 headers 的 provider 行为与原生完全一致。
• 若 DSH 升级后函数结构变化，插件会打印：

SKIPPED: unrecognized requestHeaders shape

此时会保持不破坏新代码，需要升级本插件。

• 若目标只读或写入失败，插件会打印：

READONLY: ...

或：

WRITE FAILED: ...

并跳过，不中断 DSH 启动，请求回退为原生行为。

• 插件以当前 dsh 进程权限运行。安装前应检查源码与许可证；本插件许可证为 MIT。

卸载¶

执行：

dsh plugin --profile web remove dsh-plugin-zen-useragent

卸载后需要重启 DSH：

dsh web

被补丁的文件会保留。如需彻底还原，可删除补丁标记行，或重装 DSH。

相关链接¶

• GitHub：https://github.com/jiujiezongheti/zen-useragent
• 目录页线索：https://www.skillhub.cn/plugins/jiujiezongheti/zen-useragent（该 URL 来自提供线索，未在已抓取正文中确认）