dsh-web-search-gateway
Grounded web search for DeepSeek Harness, on the gateway you already pay for.
Why
The built-in web_search runs on DeepSeek's own endpoint and bills that
account — one search is a full model turn, because DeepSeek exposes no dedicated
search endpoint. If your chat runs somewhere cheaper, your search does not.
This plugin moves the search call onto an OpenRouter-compatible gateway, so
search is billed where your chat already is, at your gateway's price and with
the model you pick:
- Your model. The search model is configured separately from the chat model,
so a cheap chat model can stay exactly as it is.
- Your price. On
api.b.ai: chat on a discounted deepseek-v4.1-flash,
search on gpt-5.4-nano — the cheapest model there that actually searches.
- Your ceiling.
dsh-tool-web's searchMaxQueries (default 4) can turn one
tool call into four searches. Set it to 1 and the cost is one search.
Nothing about the model-facing tool changes: same tool, same arguments, same
citeable results. Only the engine behind it moves.
The cheap models usually cannot search. On api.b.ai the DeepSeek, GLM,
Qwen, MiniMax and MiMo models accept the request and silently never search —
so on that gateway the search model must differ from your chat model. The
plugin fails loudly instead of returning the model's memory as results. See
Verified gateways.
The Web search settings card, with a passing connection test
Install
dsh plugin add dsh-web-search-gateway --profile web
dsh credential set OPENROUTER_API_KEY # or export it before launching dsh
The package ships a bundle patch, so the first line composes everything: it
points the web seam at this provider and inserts the provider row. The key is
resolved per search (credentials service, then the process environment), so
rotating it never needs a restart — but the patch and a linked host entry are
read at boot, so restart dsh web once after installing.
GitHub or local checkout instead of npm
dsh plugin add github:vitas/dsh-web-search-gateway --profile web
git clone https://github.com/vitas/dsh-web-search-gateway.git
cd dsh-web-search-gateway && npm install && npm run build
dsh plugin add link:$PWD --profile web
Quick start
- Install, then restart
dsh web.
- Settings → Plugins → Web search (OpenRouter).
- Set Endpoint, Search model, paste the API key.
- Test search — you get a source count, the latency, and the first hits.
Verified gateways
Web search is a server tool: the gateway must implement it for the model you
name, and it is not part of the OpenAI-compatible standard — only the message
shape is. "OpenAI-compatible" therefore says nothing about whether search works,
which is why every claim here is measured rather than assumed.
Why not just point the built-in provider at my gateway?
The built-in dsh-web-search-deepseek provider is Anthropic-compatible and does
expose baseURL and model, so re-pointing it is the obvious first idea. On
api.b.ai it doesn't work: the request is accepted and the search never runs —
deepseek-v4.1-flash answers from memory (0 results, 44 input tokens for the
whole turn), and gpt-5.4-nano gets the tool back as a client-side call. Only
/v1/responses with the native OpenAI tool searches there, and only for the
OpenAI family. Measurements: docs/gateways.md.
api.b.ai (protocol openai)
Works on /v1/responses with tools: [{ type: 'web_search' }]; hits arrive as
url_citation annotations. Cheapest first:
| Model | Citations | Notes |
|---|
gpt-5.4-nano | 2 | cheapest verified; ~8.5k input tokens per query |
gpt-5.4-mini | 4 | |
gpt-5.5-instant | 8 | |
gpt-5-mini | 4 | large input token count |
gpt-6-astra, gpt-6-sol, gpt-5.6-sol, gpt-5.5 | 1–4 | |
Not supported — glm-*, deepseek-*, qwen*, minimax-*, mimo-*, and
gpt-5-nano all return HTTP 200 with no search at all (they don't implement
OpenAI's server-side tool, and an unknown entry in tools is dropped rather than
rejected); Gemini and Anthropic are refused at the route with not supported on /v1/responses; :online, plugins: [{ id: 'web' }] and openrouter:web_search
are OpenRouter's conventions and don't exist here.
Input tokens tell a real search from a silent no-op. A search that ran injects
its results into the context, so the same prompt suddenly costs thousands of
tokens: 4313 for gpt-5.4-nano, against 18 for gpt-5-nano and 24–105
for the non-OpenAI families. That is why the provider checks searched rather
than trusting a 200. Per-model failures and cost levers:
docs/gateways.md.
openrouter.ai (protocol openrouter)
baseURL: https://openrouter.ai/api/v1 plus a model carrying the web-search
badge. engine, searchContextSize, maxUses, maxTotalResults and the domain
filters pass through as server-tool parameters. On a gateway that isn't
OpenRouter this protocol is rejected — that's the gateway talking, not the plugin.
For OpenAI proper (https://api.openai.com/v1) the default protocol works as-is;
sources arrive as web_search_call.action.sources[] and take the same code path.
Protocols
protocol | Wire shape | Use for |
|---|
openai (default) | tools: [{ type: 'web_search' }] | OpenAI, Azure, and aggregators that proxy the native tool (api.b.ai) |
openrouter | tools: [{ type: 'openrouter:web_search', parameters }] | openrouter.ai, and gateways that adopted the server tool |
plugin (deprecated) | plugins: [{ id: 'web', … }] | older gateways that never adopted the server tool |
The provider also reads web_search_call.action.sources[],
openrouter:web_search.action.sources[] and url_citation annotations —
including snippets sliced out of the cited span when the gateway sends no
excerpt.
Settings
Every field is editable from the card and can be seeded from the composition
entry. Where the card lives depends on your harness version: DSH 0.1.7 puts it
on the row's own page under Plugins (the sidebar entry), DSH 0.1.5 under
Settings → web-search-openrouter. Edits land in the profile's patch, or in
settings.yaml on 0.1.5. A value that overrides the composition entry is marked
overridden and can be reset from the card.
| Field | Default | Meaning |
|---|
protocol | openai | Enablement surface (above) |
baseURL | https://openrouter.ai/api/v1 | Gateway base; /responses is appended |
model | openai/gpt-5.2 | Model that exposes web search on that gateway |
apiKeyEnv | OPENROUTER_API_KEY | Credential reference, resolved per search |
apiKey | — | Literal key; wins over apiKeyEnv (keep it out of shared profiles) |
maxResults | 5 | Requested results, 1–25; lower is cheaper |
maxOutputTokens | 1024 | max_output_tokens for one search turn |
includeAnswer | false | Return the search model's prose as content too |
allowedDomains, excludedDomains | — | Restrict results to, or drop results from, these hostnames |
engine, searchContextSize, maxUses, maxTotalResults | — | openrouter protocol only; passed through as server-tool parameters |
referer, title | — | HTTP-Referer / X-Title attribution headers |
Cost
Billed as tokens on the search model, not per query. Levers, cheapest first:
pick the cheapest model that searches (and only that one — the chat model is
separate), set searchMaxQueries: 1, keep maxResults low, leave
includeAnswer off. Measured numbers: docs/gateways.md.
Troubleshooting
| Symptom | Cause |
|---|
WEB_PROVIDER_CREDENTIAL_MISSING | No key under apiKeyEnv; set it in the card or export it before launching dsh. |
| "the gateway ran no server-side search for model …" | That model doesn't expose web search on that gateway. Pick one from the table above. |
| "Invalid value: 'openrouter:web_search'" | The gateway doesn't implement OpenRouter's server tool; switch protocol to openai. |
| "node only allows access to inference API paths" | A gateway-side proxy restriction; check baseURL (a stray trailing slash used to produce //responses). |
HTTP 404 on /responses | Chat-completions-only gateway; this provider needs a Responses endpoint. |
Development
npm install # esbuild + typescript
npm run check # host syntax check + client typecheck
npm test # 35 tests, no network, no credentials (1 skipped: the live one)
npm run check-locales
npm run build # rebuild the committed lib/client.js (also runs on npm pack)
# Live smoke test — opt-in, never in CI.
DSH_WEB_SEARCH_LIVE=1 OPENROUTER_API_KEY=sk-... \
DSH_WEB_SEARCH_BASE_URL=https://api.b.ai/v1 DSH_WEB_SEARCH_MODEL=gpt-5.4-nano \
node --test test/live.test.mjs
Architecture, seam contracts and the release process: docs/. Three
protocols; one browser card (English / 中文 / Русский); no @deepseek-ai/* runtime
imports; no install-time script — the bundle is committed and CI fails if it
drifted.
Privacy
No stored data, no background work. Per search, one HTTPS request to baseURL
with your query, the model name and the configured parameters; the gateway's own
terms govern the rest. The key is read from the DSH credential store at call time
and is never written to settings, logs or the browser.
License
Apache-2.0.
