Introduction

OpenCode Zen’s free tier is only available to official clients; the server determines the request source through specific HTTP Headers. The dsh-llm-pi-ai adapter built into DeepSeek Harness (DSH) theoretically supports injecting these headers, but because its requestHeaders() method overrides the user-defined User-Agent, the opencode detection always fails and the headers are never injected.

The dsh-zen-spoof plugin registers directly as the opencode provider, completely bypassing pi-ai, and controls all request headers itself. It does not depend on any patch or specific version, and works with any DSH version.

Installation and Configuration

Install the plugin by running the following command:

dsh plugin --profile web add dsh-zen-spoof

After installation, because the plugin registers the opencode route, it conflicts with the same-named route in pi-ai. You must manually edit the configuration file to avoid a DUPLICATE_ADAPTER error.

  1. Locate the settings.yaml file:
    • Windows: <dsh install dir>\.dsh\settings.yaml
    • macOS / Linux: ~/.dsh/settings.yaml
  2. Comment out the opencode provider configuration under llm-pi-ai:
    llm-pi-ai:
      providers:
        # opencode: 已由 dsh-zen-spoof 插件接管
        opencode-go:
          # ... 其他 provider 配置保持不变 ...

Features

  • Fully self-contained: does not rely on pi-ai patches or specific versions, and does not rely on patches provided by the dsh installer.
  • Automatic model discovery: retrieves the latest free model list from the Zen API at startup; falls back to the built-in list on failure.
  • Thinking mode: automatically passes through the reasoning_effort parameter and parses the reasoning_content field, displaying the thinking process in the DSH UI.
  • Automatic fallback: on 429 or 5xx errors, rotates models within the candidate pool, supporting exponential backoff and the Retry-After response header.
  • Hot credential updates: resolves the API Key per request; Keys can be changed without restarting.
  • Error code alignment: error handling is compatible with DSH’s built-in retry mechanism.
  • Multi-block output: correctly handles the assembly order of reasoning -> text -> tool-call in streaming responses.

Usage

Start the DeepSeek Harness Web UI:

dsh web

In the session settings, select provider: opencode, and choose any of the following free models:

Model ID Description
mimo-v2.5-free MiMo V2.5 (default)
deepseek-v4-flash-free DeepSeek V4 Flash
ling-3.0-flash-free Ling 3.0 Flash
nemotron-3-ultra-free Nemotron 3 Ultra

The plugin retrieves the model list automatically at startup; the table above is for reference only.

The API Key by default reuses the value of OPENCODE_API_KEY in the DSH credential store.

Configuration Options

Field Default Description
apiKey Empty If empty, automatically reads the DSH credential store
apiKeyRef OPENCODE_API_KEY Credential reference name
baseURL https://opencode.ai/zen/v1 Gateway address
providers ["opencode"] Registered route name
spoofClient cli Value for x-opencode-client
project dsh Value for x-opencode-project
userAgent opencode/1.18.30 User-Agent, must include a version number
enableAutoFallback true Automatically switch models when rate-limited
maxFallbackAttempts 5 Maximum number of switches per attempt
initialBackoffMs 1000 Backoff starting point (milliseconds)
maxBackoffMs 30000 Backoff upper limit (milliseconds)
timeoutMs 120000 Idle timeout (milliseconds); 0 means no limit

When overriding the configuration via Cordis, all keys must be restated.

Notes

  • Spoofing risk: client header spoofing is a grey-area technique; the official provider may tighten policies or flag unofficial traffic. It is recommended to use a low-risk/test API key.
  • Manual configuration: after installation, you must manually comment out the opencode provider in settings.yaml; otherwise an error will occur.
  • Credential lookup: you can find the location of settings.yaml on the “Settings” page in the DSH web UI or by running the dsh config command.