前言¶

在 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 來自提供線索，未在已抓取正文中確認）