Introduction

When running agents in DeepSeek Harness (DSH), model request failures are not uncommon: retries exhausted, authentication errors, quota exhaustion, 429 rate limiting, etc. The common practice is to manually modify the configuration or interrupt the current task to switch models, a cumbersome process that easily disrupts ongoing conversation steps.

Here we introduce the community plugin dsh-llm-fallbacks (maintainer omdsh-dev). It maintains a provider/model fallback chain for the current role at the DSH gateway side. When requests continuously fail, it switches to the next model along the chain, allowing the current step/turn to continue on the target model without task interruption due to model issues.

What is This

dsh-llm-fallbacks is a model inference plugin for DSH, with the npm package name dsh-llm-fallbacks, current version 0.3.5, MIT license, requiring Node.js ≥ 22. It is compatible with DSH 0.1.1-rc.2 and dsh-tui.

The core problem it solves is: defining model switching strategies after failure based on roles (including root requests and sub-agents), and supporting time-based rotation of the “active root chain”. Configurations are stored in the shared fallbacks: namespace, editable by both Web and terminal frontends.

Core Features

Fallback Chain Switching on Failure

When an agent’s LLM requests repeatedly fail (retries exhausted, auth, quota, rate limit, etc.), the plugin sequentially tries the next provider/model according to the chain configured for the current role. The current step continues execution on the target model.

Root Chain and Default Model

rootChain defines the all-day default chain: entries before the last are fallback models tried sequentially upon failure, with the last item being the Default model. The specification requires that the chain end must be one of the official V4 models: deepseek-official/deepseek-v4-flash or deepseek-official/deepseek-v4-pro (one of the two). The settings card and gateway validate the chain end upon saving; old configurations with non-compliant chain ends will trigger a warning on startup but can still work as a pure fallback chain, though they cannot be saved as-is.

Time Slots

Optional timeSlots rotate the active root chain based on wall-clock windows: each slot row includes its own chain. When the current time falls within a certain row’s window, the next root request uses that row’s chain instead of the all-day rootChain; when no time slot matches, the all-day chain is used. Time slot switching only affects the routing seed and does not consume cooldown; the fallback logic on failure remains unchanged.

Built-in four UTC+8 presets (windows are code constants, preset rows lock tz to Asia/Shanghai):

Preset Window
liang-peak Monday to Friday 09:00–12:00, 14:00–18:00
liang-valley Other UTC+8 times
glm-peak Monday to Friday 14:00–18:00
glm-valley Other times

glm-peak / glm-valley only appear in the card selector when zai-coding-cn is configured. Custom start/end (can cross midnight) and days are also supported.

Roles and Rules

roles can declare independent chains and rules for sub-agents: rules only match sub-agent requests, not root requests. Roles can set fallback: inherit-root, first traversing the role chain then the inherited root chain.

Dual Frontend Support

The same plugin package is installed for different targets via --profile:

  • Web: Settings → Plugins → Fallbacks card
  • dsh-tui: /fallbacks session diagnostics, /fallbacks config read-only echo, /settings fallbacks section editing (requires dsh-tui ≥ v0.8.5)

The shared configuration source is the fallbacks: section in $DSH_HOME/settings.yaml.

Installation and Enabling

Install under the corresponding profile (registry installation pulls the built dist/; no compilation needed on the target machine):

dsh plugin --profile web add dsh-llm-fallbacks      # Web: Settings → Fallbacks card
dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui terminal

Use @<version> to pin the version. For uninstallation, --dump-config validation, etc., see the repository docs/install.md.

Upgrade Note for Versions Before 0.2.2: Older versions write persistent fallbacks/switch session events, which may prevent newer DSH versions from opening sessions. You need to stop dsh first, then run the fix script in the cloned repository directory (--dry-run for preview, --apply --backup to apply). Since version 0.2.2, the plugin no longer writes such events.

The plugin is disabled by default: when fallbacks.enabled is false, the plugin is a no-op. It must be explicitly enabled and configured with a chain to take effect.

Typical Usage

Add a fallbacks: section to $DSH_HOME/settings.yaml. Below is the structural explanation of a minimal runnable example.

1. Enable the Plugin

fallbacks:
  enabled: true

2. Configure the All-Day Root Chain

  rootChain:
    - anthropic/claude-3-5-sonnet          # First try on failure
    - deepseek-official/deepseek-v4-flash  # Chain end Default (choose Flash or Pro)

3. (Optional) Time-Based Chain Switching

  timeSlots:
    - kind: preset
      preset: liang-peak
      chain:
        - anthropic/claude-3-5-sonnet
    - kind: custom
      name: evening
      start: '22:00'
      end: '02:00'
      days: [1, 5]
      chain:
        - openai/gpt-4o

4. (Optional) Define Roles for Sub-Agents

  roles:
    list:
      - id: reviewer
        persona: Code-review subagents
        chain:
          - openai/gpt-4o-mini
        fallback: inherit-root
    rules:
      - role: reviewer

Web users can graphically edit the same namespace in the settings card; terminal users can use /settings to edit simple fields or JSON text fields for complex structures.

Use Cases and Considerations

Who it’s for: Those who run multi-model, multi-provider agents on DSH long-term; those needing automatic primary model switching during peak and off-peak hours; those wanting sub-agents (e.g., reviewer) to use different fallback strategies from the main session.

Usage Notes:

  • The plugin runs with the current dsh process permissions. Before installation, please read the source code and MIT license to confirm the behavior meets expectations.
  • The community directory SkillHub is an independent site with no official affiliation with DeepSeek / High-Flyer; plugin lists and GitHub repository (approximately 16 stars) are for reference only.
  • The chain end Default model must comply with the official V4 specification; otherwise, it cannot be saved via Web/gateway.
  • /fallbacks and /fallbacks config are diagnostic read-only commands and cannot replace the settings card or YAML editing.

Conclusion

After the above steps, DSH can automatically switch to fallback models based on roles and time slots without interrupting tasks when model-layer failures occur. dsh-llm-fallbacks consolidates “what to do after retries are exhausted” into a configurable fallbacks: namespace, shared between Web and dsh-tui.