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

2. After installation or uninstallation, run:

dsh web

3. 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.

Related Links¶

• GitHub: https://github.com/jiujiezongheti/zen-useragent
• Directory page reference: https://www.skillhub.cn/plugins/jiujiezongheti/zen-useragent (this URL comes from a lead and has not been confirmed in the fetched content)