Introduction

DeepSeek Harness (DSH) adopts a plugin-based architecture. When integrating with third-party OpenAI-compatible gateways, developers often encounter issues such as tool call IDs being overwritten in streaming output and unable to automatically recover from specific 400 errors. dsh-llm-gateway-compat is a community-maintained adapter plugin designed to fix these compatibility issues and provide more stable gateway connectivity.

Plugin Scope

This is a non-official community plugin maintained by user snowshadow. It primarily addresses three core pain points when DSH interacts with OpenAI-compatible gateways: the risk of overwriting streaming tool call IDs, handling specific 400 errors, and adapting Chat Completions routing.

Core Features

The plugin includes the following functional modules:

  1. Streaming Tool Call Repair
    The plugin wraps the llm/stream flow. If an empty id or name appears in a streaming response, those empty values will not override previously received non-empty values. If no ID has been received, the plugin automatically generates compat_call_<index>.

  2. Request Error Handling
    The plugin listens for the agent/request-error event. When a developer-role rejection or a 400 error related to max_completion_tokens is encountered, the plugin writes the matching fields into the official llm-pi-ai compatibility configuration and retries the step once. It does not retry generic 400 errors.

  3. Chat Completions Routing Adapter
    The plugin provides an optional routing adapter. By default, it uses system as the role and max_tokens as the output limit. It ensures empty tool call IDs are not overwritten and supports additional request fields and custom authentication headers.

Installation and Enablement

Installing this plugin requires DeepSeek Harness version 0.1.5-rc.1 or higher. Run the following command to install it:

dsh plugin --profile web add github:snowshadow/dsh-llm-gateway-compat

After installation, restart the dsh web service. Because the plugin includes build artifacts (located in the lib/ directory), no TypeScript build is required during installation.

Configuration Notes

All plugin configuration items must be manually edited in settings.yaml. There is no Web settings card available yet.

Global Switches

Add the llm-gateway-compat configuration section in settings.yaml to control the core behavior:

Setting Default Description
enabled true Master switch, controlling streaming wrapping and error recovery.
diagnose true Classifies gateway 400 errors and injects diagnostic information.
autoApplyCompat true Persists the identified error configuration into llm-pi-ai and retries.

Provider Routing Configuration

Define Chat Completions routing through the providers field. The following is an example of connecting to Alibaba Cloud DashScope:

llm-gateway-compat:
  providers:
    dashscope-compat:
      displayName: DashScope
      baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1
      apiKeyEnv: DASHSCOPE_API_KEY
      authHeader: bearer
      thinkingFormat: reasoning_content
      extraBody:
        user: harness
      models:
        - id: deepseek-v4-flash
          name: DeepSeek V4 Flash

Key parameter descriptions:
* baseURL: Gateway address; the plugin automatically appends /chat/completions.
* apiKeyEnv: Credential reference; it must be defined on the model page or in environment variables.
* authHeader: Authentication method; supports bearer or api-key.
* thinkingFormat: Reasoning format; options are reasoning_content (default), thinking, think-tags, or none.
* extraBody: Used to pass gateway-specific fields (such as user); the plugin automatically strips max_completion_tokens to avoid conflicts.

Limitations and Notes

When using this plugin, note the following limitations:

  • Unofficial software: This package is not an official DeepSeek product and does not carry official endorsement.
  • Version requirement: DeepSeek Harness >= 0.1.5-rc.1 must be used.
  • Recovery limitation: It cannot recover tool names that the gateway never sent.
  • Input limitation: The plugin rejects image inputs and returns an UNSUPPORTED_CONTENT error.
  • Tag application: think-tags applies only to replayed assistant history and does not apply to partial tags during streaming.
  • Configuration method: There is no Web settings card; all configuration must be manually edited in settings.yaml.
  • Replay limitation: autoApplyCompat takes effect only on the llm-pi-ai route and writes supportsDeveloperRole: false and maxTokensField: max_tokens.

Conclusion

dsh-llm-gateway-compat improves DSH compatibility with third-party OpenAI-compatible gateways by fixing streaming tool calls and error-handling mechanisms. Developers can configure routes and parameters according to their own needs, but should be mindful of its unofficial nature and specific configuration limitations.

View plugin directory
View source code