dsh-gateway-provider
> 中文文档：[docs/README.zh.md](docs/README.zh.md)
Use all the models behind your LLM gateway — newapi, LiteLLM, Higress, or any OpenAI-compatible endpoint — directly in DeepSeek Harness.
Install the plugin, paste your API key, and every gateway model shows up in dsh's model picker with its real parameters (context window, output cap, reasoning support) fetched from models.dev. Requests go out over each model's own native protocol — OpenAI, Anthropic, or Gemini — so tool calls and streaming behave the way that model's maker intended.
Why this exists
dsh ships one adapter per official provider. If your models live behind a gateway, the manual alternative is a hand-maintained static model list with guessed context windows and output caps. This plugin mounts the gateway itself instead:
- Nothing to maintain by hand — the model list is read from the gateway
(GET /v1/models, with a management-API fallback for newapi); add a model on the gateway side and it appears in dsh, no re-deploy.
- Real numbers, not guesses — models.dev data fills context window,
output cap, reasoning levels, release date; config defaults only fill gaps.
- Every wire format, one plugin — each model routes over its own
protocol (OpenAI chat completions / OpenAI responses / Anthropic messages / Gemini), handled by the same pi-ai SDK the official dsh adapter uses.
- Multiple gateways at once — a default
newapiroute plus one
gateway:<id> route per extra gateway, each with its own cache and key.
- A settings page instead of YAML — Settings → Gateway Models: add
gateways from templates (NewAPI / LiteLLM / Higress / OpenAI-compatible / fully custom), test connections, sync models, hide or override any model, add custom models.
Requirements
- DeepSeek Harness (dsh) with a
webprofile (the settings page is a web-UI
extension; the provider itself works in any profile).
- A gateway API key (e.g. a newapi token).
Install
# 1. Install the plugin (dsh plugin add runs pnpm add under the hood)
dsh plugin --profile web add dsh-gateway-provider
# 2. Store your key — pick ONE of:
# a) the dsh credentials file (recommended; created with mode 0600, hot-reloaded)
echo "NEWAPI_API_KEY: sk-REPLACE_WITH_YOUR_KEY" >> ~/.dsh/.credentials.yaml
# b) or export it in the shell you launch dsh from:
# export NEWAPI_API_KEY=sk-REPLACE_WITH_YOUR_KEY
# 3. Restart and open the settings page
dsh --profile web
# → Settings → Gateway ModelsExpected result: the model picker gains a "NewAPI" route listing your gateway's chat models, newest first. Click Test on the gateway card — it should answer ✓ Connected — N models. Not using the public newapi cloud? Set Base URL on the card (or baseURL in config) to your own gateway address first.
Daily use
Everything lives in Settings → Gateway Models:
- Add more gateways — "Add Gateway", pick a template (LiteLLM, Higress,
OpenAI-compatible, or fully custom with per-protocol URLs), point it at the base URL, name its key env var, Test, Sync. Each gateway becomes its own route in the picker.
- Tame the model list — non-chat models (image / speech / embedding /
rerank …) are excluded by default regexes; hide or rename any model; add a custom model by hand if the gateway hides it; per-model protocol, context window, output cap, and reasoning levels are all editable.
- Keys live in dsh's credential store — the settings page shows a badge
(✓ Key set · NEWAPI_API_KEY / ⚠ No key set) and can write the key there for you.
Configuration reference
Optional — everything below has a working default. Config lives in the llm-newapi: section of ~/.dsh/settings.yaml (the settings page edits the same keys). The frequently used ones:
| Key | Default | Meaning |
|---|---|---|
baseURL | https://api.newapi.ai | Your gateway's base URL. Env fallbacks: NEWAPI_BASE_URL, NEWAPI_API_URL. |
apiKeyEnv | NEWAPI_API_KEY | Which env/credential variable holds the key. |
label | NewAPI | Route label shown in the picker. |
flavor | newapi | Template label only (newapi / litellm / higress / openai-compatible / custom). |
gateways | — | Array of extra gateways: { id, baseURL, apiKeyEnv, label, … }, each becoming a gateway:<id> route. |
models | — | Per-model overrides: { id, name, disabled, protocol, contextWindow, maxTokens, reasoningLevels }. |
useModelsDev / modelsUrl | true / models.dev | Parameter enrichment source (supports file: URLs for offline). |
excludePatterns | image/speech/… | Regex list of model ids to keep out of the picker. |
sortModelsByRelease | true | Newest models first. |
catalogMode | auto | v1 (/v1/models only) / management (newapi user API) / auto. |
endpointPriority | responses → anthropic → openai → gemini | Which protocol to prefer when a model supports several. |
openaiURL / responsesURL / anthropicURL | — | Fully-custom gateways only: per-protocol endpoint URLs; unset = that protocol off. |
maxTokens / defaultContextWindow | 32768 / 128000 | Fallbacks when models.dev has no data. |
streamIdleTimeoutMs | 600000 | Idle timeout while streaming. |
headers | — | Extra HTTP headers sent to the gateway. |
Troubleshooting
| Symptom | Cause → fix |
|---|---|
| Picker route exists but zero models | The plugin can't read your model list. Check the gateway base URL; try catalogMode: "management" for newapi gateways that restrict /v1/models. |
401 / auth errors on every request | Key missing or wrong: check the badge in Settings → Gateway Models, or NEWAPI_API_KEY in ~/.dsh/.credentials.yaml. |
| A model's context window looks wrong | models.dev had no match. Edit the model on the settings page (or a models: override). |
| Wrong format answers / tool calls flaky for one model | That model is routed over a protocol it handles poorly. Pin protocol on the model (openai, openai-response, anthropic, gemini). |
| Custom gateway with separate endpoints | Use flavor: "custom" and set openaiURL / responsesURL / anthropicURL explicitly. |
How it works (one minute version)
At startup the plugin registers one provider route per gateway, pulls the model list from the gateway, and fuzzy-matches each model id against models.dev to fill in real parameters. When you pick a model, dsh's request is translated to the pi-ai SDK's format and sent over that model's native protocol; the streamed reply is translated back into dsh chunks. Catalogs are cached (30 min by default) per gateway. No hand-written protocol code — the bridge is lifted from the official dsh-llm-pi-ai adapter.
Development
git clone https://github.com/Luck9Star/dsh-gateway-provider
cd dsh-gateway-provider
npm run link # symlink into your dsh profile (single instanceof safety)
npm run test:client # settings-UI render, both locales
npm run test:urls # URL/derivation units
npm run smoke # live gateway round-trip (needs a real key)Developing from a checkout: point the profile's package.json at "dsh-gateway-provider": "link:/abs/path" and re-run pnpm install in the profile. Do not also add an id: llm-newapi row to the profile's own cordis.patch.yml — the bundle patch already provides it (duplicate row = loader error).
References & credits
- pi-ai SDK — all
four wire protocols; the bridge reuses the official dsh-llm-pi-ai adapter's translation layer.
- models.dev — the parameter catalog (context
windows, output caps, reasoning, release dates).
LiteLLM, Higress — the gateways this plugin is tested against (any OpenAI-compatible endpoint works).
Security
Keys live in dsh's credential store or the launching environment — never in settings YAML. The repo runs gitleaks in CI and pre-commit to keep secrets out.
License
[MIT](LICENSE)