Preface

When using the OpenCode ZEN free model in DSH, you may encounter an issue where request headers are not taking effect: even though headers are configured in the provider settings, the actual API requests may still be identified as deepseek-harness, resulting in a 429 FreeUsageLimitError.

dsh-plugin-zen-useragent addresses this problem: it ensures that request headers configured in the provider (such as User-Agent) actually reach the pi-ai API requests, causing the requests to be identified as an opencode client rather than deepseek-harness.

What It Is

This is a DSH plugin maintained by jiujiezongheti. The repository identifier is jiujiezongheti/zen-useragent, the package name is dsh-plugin-zen-useragent, and it is licensed under MIT.

The core problem it solves: the OpenCode ZEN free model in DSH returns 429 FreeUsageLimitError due to an unexpected client identifier.

Core Features

  • Ensures request headers configured in the provider (such as User-Agent) reach the pi-ai API requests.
  • Fixes the 429 FreeUsageLimitError for the OpenCode ZEN free model.
  • Patches requestHeaders so configured headers override attribution.
  • Automatically re-patches after DSH upgrades.
  • The patch is idempotent and executes automatically on every startup.

Installation and Activation

  1. Install the plugin to the web profile. Install from GitHub source:
dsh plugin --profile web add github:jiujiezongheti/zen-useragent

Or install from npm:

dsh plugin --profile web add dsh-plugin-zen-useragent
  1. After installation or uninstallation, run:
dsh web
  1. When the terminal shows output like the following at startup, it means the patch is active:
[dsh-plugin-zen-useragent] patched: ...

Typical Usage

Configure request headers in the opencodezen provider in settings.yaml, for example:

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

After saving, run:

dsh web

After restarting, switch to the opencode free model and send a message. If the 429 error no longer appears, the plugin is working.

Applicable Scenarios and Notes

  • Suitable for scenarios where you configure the opencodezen provider in DSH and want to preserve custom headers such as User-Agent in API requests.
  • The patch only affects providers that explicitly configure headers with the same name; providers without configured headers behave exactly as native.
  • If the function structure changes after a DSH upgrade, the plugin will print:
SKIPPED: unrecognized requestHeaders shape

In this case, it will avoid breaking the new code, and you need to upgrade this plugin.

  • If the target is read-only or the write fails, the plugin will print:
READONLY: ...

or:

WRITE FAILED: ...

It will skip and not interrupt DSH startup, and requests will fall back to native behavior.

  • The plugin runs with the current dsh process permissions. You should review the source code and license before installation; this plugin is licensed under MIT.

Uninstallation

Run:

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

After uninstalling, restart DSH:

dsh web

The patched files will be preserved. For a complete restore, you can delete the patch marker lines or reinstall DSH.