LLM-Server/docs/research/dashscope-websearch-selfhost-options.md

# Research: self-hosted alternatives to DashScope for Qwen Code's built-in `web_search` tool

**Question:** Qwen Code CLI's built-in `web_search` tool requires `tools.webSearch.model`
to resolve to a "DashScope-compatible `modelProviders` entry." Is there any real,
non-Alibaba-Cloud way to satisfy that requirement with something self-hosted —
or is the already-working OmniRoute MCP + SearXNG path (`docs/research/omniroute-qwen-websearch.md`)
the end of the road?

**Answer, short version:** No. The client-side code that decides whether a
`baseUrl` is "DashScope-compatible" checks the **literal hostname** against a
hardcoded allowlist of Alibaba-owned domains, before any request is sent — it
is not a protocol-compatibility check that a look-alike server could pass. A
self-hosted server cannot satisfy it, full stop, unless you fork qwen-code and
delete that check. Once you've done that, the actual wire protocol
(OpenAI SDK `responses.create()`, SSE, specific item types) is buildable
(a few hundred lines), but nothing you can install off the shelf implements it
today. The already-working OmniRoute MCP + SearXNG path costs nothing further
and does not have this problem. **Recommendation: don't build this — see
§6.**

## 1. What "DashScope Responses API" is, precisely

Alibaba Cloud Model Studio (Bailian/DashScope) added an **OpenAI-compatible
Responses API**, layered on top of its existing Chat Completions
compatible-mode surface:

- Endpoint (per Alibaba's own docs): `POST {baseUrl}/responses`, where
  `baseUrl` is the region's compatible-mode base, e.g.
  `https://dashscope.aliyuncs.com/compatible-mode/v1` (China/Beijing) or the
  `-intl` / regional `*.maas.aliyuncs.com` variants.
  Source: https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-openai-responses
  and https://www.alibabacloud.com/help/en/model-studio/compatibility-with-openai-responses-api
- Request shape: standard Responses API (`model`, `input`, `stream`, `store`,
  `instructions`) plus a `tools` array that can include
  `{"type": "web_search"}`, `{"type": "web_extractor"}`, `{"type": "code_interpreter"}`
  as **hosted, server-side tools** — the inference backend runs the search
  itself and streams results back, the same hosted-tool pattern as OpenAI's
  own Responses API `web_search_preview`, not a client-side function-calling
  round trip.
  Source: https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-openai-responses
- Response shape: an `output` array of typed items — a `web_search_call` item
  carries `action: {type, query, sources: [{type: "url", url}]}`; narration
  comes back as `message` items with `content: [{type, text}]`.
  Source: same page.
- Separately, DashScope's plain Chat Completions endpoint (not Responses)
  has an older, unrelated `enable_search` boolean (passed via `extra_body`)
  for models like Qwen3.8/Qwen3.6-Plus — the docs explicitly note this older
  surface **does not return citations/sources**, which is exactly why
  qwen-code's built-in tool uses the *Responses* API instead.
  Source: https://docs.qwencloud.com/developer-guides/tool-calling/web-search

This is the same hosted-tool pattern as OpenAI's Responses API
`web_search_preview` (§4 confirms this directly from qwen-code's own client
code — it literally reuses the OpenAI Node SDK's `responses.create()` call
against a DashScope base URL).

## 2. What qwen-code's own client code actually sends (ground truth)

Fetched directly from `QwenLM/qwen-code`'s `main` branch,
`packages/core/src/tools/web-search.ts` (1087 lines) and
`packages/core/src/core/openaiContentGenerator/{constants,provider/dashscope}.ts`.
This supersedes anything inferred from the docs pages — it's the literal
implementation.

**The request** (`web-search.ts` lines 651–699):

```ts
const client = new OpenAI({
  apiKey,                    // from the resolved modelProviders entry's envKey
  baseURL: backend.baseUrl,  // the modelProviders entry's baseUrl / WEB_SEARCH_BASE_URL
  timeout: 60_000,
  defaultHeaders: { 'User-Agent': `QwenCode/${version} (...)`, ...customHeaders },
});

const tools = [{ type: 'web_search' }];
if (backend.webExtractor) tools.push({ type: 'web_extractor' });

const requestParams = {
  model: backend.modelId,
  input: `Perform a web search for the query: ${query}`,
  stream: true,
  store: false,
  instructions: SIDE_REQUEST_INSTRUCTIONS,   // a fixed system prompt, see source
  tools,
};

const stream = await client.responses.create(requestParams, { signal });
```

This is the **official OpenAI Node SDK**, so `client.responses.create()`
literally POSTs to `{baseURL}/responses` with that JSON body and reads back
an SSE stream — there is no DashScope-specific SDK involved at all. Anything
speaking real OpenAI Responses-API SSE syntax at that path, with these two
extra tool types, is protocol-compatible.

**What the client parses out of the SSE stream** (lines 359–509): event types
`response.output_item.added`, `response.output_item.done`,
`response.output_text.delta`, and terminal `response.completed` /
`.failed` / `.incomplete` / `.cancelled`, each carrying a `response` object
with `output: WsOutputItem[]` and `usage.x_tools.{web_search,web_extractor}.count`.
Output items it understands: `web_search_call` (`action.query`/`action.queries`,
`action.sources[].url`, `status`), `web_extractor_call` (`urls`, `goal`,
`output`, `status`), and `message` (`content[].text`). It also defensively
handles a DashScope-specific quirk: **request-level failures arrive as a bare
SSE `event:error` with `{code, message, request_id}` and no `type`/`error`
wrapper** — the OpenAI SDK doesn't recognize this shape, so qwen-code parses
it itself (comment: "probe-verified"). Any replacement backend needs to emit
exactly these item/event shapes, or qwen-code's parser silently ignores
unrecognized item types and ultimately reports
`WEB_SEARCH_NO_SEARCH_PERFORMED` (it treats zero `web_search_call` items as
"no search happened," with one retry, before failing outright — see lines
883–906).

**The hard gate — this is the actual finding.** Before any request is sent,
`evaluateWebSearchGate()` (lines 169–335) validates the resolved `baseUrl`
through `classifyDashScopeBaseUrl()` (lines 122–157):

```ts
function classifyDashScopeBaseUrl(baseUrl: string): DashScopeBaseUrlIssue | null {
  const url = new URL(baseUrl);
  if (url.protocol !== 'https:') return 'insecure';
  const hostname = url.hostname.toLowerCase();
  const suffixes = [
    ...DASHSCOPE_REGIONAL_HOSTS,   // dashscope.aliyuncs.com, dashscope-intl.aliyuncs.com, dashscope-us.aliyuncs.com
    'maas.aliyuncs.com',
    'alibaba-inc.com',
    'aliyun-inc.com',
  ];
  return suffixes.some(s => hostname === s || hostname.endsWith('.' + s)) ? null : 'unknown-host';
}
```

`DASHSCOPE_REGIONAL_HOSTS` is defined in
`packages/core/src/core/openaiContentGenerator/provider/dashscope.ts` as
exactly `['dashscope.aliyuncs.com', 'dashscope-intl.aliyuncs.com', 'dashscope-us.aliyuncs.com']`.

**This means "DashScope-compatible" is not a protocol claim you can satisfy
by implementing the right JSON shapes — it is a literal hostname allowlist
checked client-side, before the request is even built.** A self-hosted server
at `http://search.home`, `https://proxy-ai.home`, or any hostname you control
will be rejected with *"WebSearch ... is not a DashScope-compatible
endpoint"* regardless of what protocol it speaks, unless its hostname ends in
one of `dashscope.aliyuncs.com`, `dashscope-intl.aliyuncs.com`,
`dashscope-us.aliyuncs.com`, `*.maas.aliyuncs.com`, `*.alibaba-inc.com`, or
`*.aliyun-inc.com` — domains Alibaba owns, that you cannot obtain a valid TLS
certificate for. (There's also a separate, unrelated `DASHSCOPE_PROXY_BASE_URL`
env var used by the *main* content generator's provider-detection code
(`dashscope.ts` lines 244–262) for header/cache-control routing through a
corporate proxy — it is not consulted by `classifyDashScopeBaseUrl()` at all,
so it does not help here either.)

The only way around this specific check is to **fork qwen-code and delete or
relax `classifyDashScopeBaseUrl()`** — it's ~15 lines of open-source
TypeScript, so this is not hard *code-wise*, but it means running a patched
build of the CLI, not configuring the stock release.

## 3. Any self-hostable server implementing this surface today? — No

Checked the servers this task named:

- **vLLM**: has a real `/v1/responses` implementation
  (https://docs.vllm.ai/en/stable/api/vllm/entrypoints/openai/responses/), and
  for `gpt-oss` models specifically supports a **built-in `browser` tool**
  with a pluggable, MCP-compliant external tool server in place of the
  default Exa-backed reference implementation
  (https://vllm.ai/blog/2025-08-05-gpt-oss;
  https://github.com/vllm-project/recipes/blob/main/OpenAI/GPT-OSS.md). This
  is the closest existing building block found — but it's gpt-oss/harmony
  specific (not Qwen), and its tool/event shapes (`browser.search`,
  `browser.open` harmony-channel messages) are **not** the same as DashScope's
  `web_search_call`/`web_extractor_call` items qwen-code's parser expects, so
  it is not drop-in — it would need a translation shim in front, at which
  point you're building the shim anyway and don't need vLLM in the path.
- **SGLang**: Responses API support is unclear/inconsistent per its own
  issue tracker (https://github.com/sgl-project/sglang/issues/10038) — no
  usable built-in web-search tool found.
- **LiteLLM**: does expose `/v1/responses`, but has an **open bug**
  rejecting the `web_search` tool type outright — "LiteLLM raises a
  validation error... only `web_search_preview` is currently allowed"
  (https://github.com/BerriAI/litellm/issues/14011). Its actual SearXNG
  integration is the unrelated standalone `/v1/search` REST endpoint already
  documented in `docs/research/litellm-searxng-search.md` (§1–3 there) — a
  sibling API to chat/responses, not a Responses-API `tools:[{"type":"web_search"}]`
  handler. It doesn't have a DashScope-mode either
  (https://docs.litellm.ai/docs/providers/dashscope is a plain client wrapper
  that calls the real dashscope.aliyuncs.com; nothing in it hosts a
  DashScope-shaped server).
- **LocalAI / Ollama**: no Responses API or DashScope-compatible mode found
  in searches for either.
- **A generic "OpenAI Responses API" self-hosted shim that could be relabeled**:
  the closest match found, `teabranch/open-responses-server` (185 stars, 161
  commits, wraps Ollama/vLLM as a Responses API with MCP support), **does not
  implement `web_search` at all** — its own roadmap lists "Web search: crawl4ai"
  as a *future* item, not shipped (verified live against the repo,
  2026-09-05). No other candidate turned up in repeated GitHub searches for
  "dashscope emulator/mock/fake server" or "responses api web_search
  self-hosted."

**Conclusion for §3: nothing installable off the shelf implements the
DashScope Responses API's `web_search`/`web_extractor` hosted-tool surface.**
Building it means writing your own small SSE server (see §5 sizing).

## 4. Is DashScope's shape "OpenAI Responses API + web_search" reused wholesale?

Yes, confirmed directly from source, not inference: qwen-code's client uses
the **official `openai` npm package**'s `client.responses.create()` against a
DashScope `baseURL` (§2 above) — it is not a DashScope-specific SDK or
protocol. OpenAI's own Responses API supports a hosted `web_search_preview`
tool with a similar `output[].type === "web_search_call"` item shape
(OpenAI's public Responses API docs, referenced but not independently
re-fetched here since qwen-code's source is authoritative for what it
actually calls). DashScope's extension is the tool *name* (`web_search`
rather than `web_search_preview` — the exact naming mismatch LiteLLM's own
open bug in §3 stumbles on) plus the additional `web_extractor` tool and the
`x_tools` usage-accounting field. No existing "OpenAI Responses API shim"
project was found that already emulates `web_search_preview`/`web_search`
server-side against a pluggable backend (see §3) — the two hosted-tool
ecosystems (OpenAI's and DashScope's) both currently require literally
calling out to the vendor's own cloud; nobody has open-sourced a
self-hosted stand-in for either.

## 5. LiteLLM specifically, re-examined against this exact requirement

`docs/research/litellm-searxng-search.md` already established SearXNG is a
first-class LiteLLM `search_provider` behind the **standalone** `/v1/search`
REST endpoint (its own §1–2). That endpoint is irrelevant to qwen-code's
`tools.webSearch.model` gate: qwen-code doesn't call an arbitrary search REST
endpoint, it calls `POST {baseUrl}/responses` on an **OpenAI-SDK client**
with `tools:[{type:"web_search"}]`, and gates `baseUrl` on the Alibaba
hostname allowlist in §2. Even ignoring the hostname gate entirely (i.e.
assuming a patched qwen-code build), LiteLLM's `/v1/responses` route
currently **rejects** the `web_search` tool type per the open bug in §3 — so
today, LiteLLM cannot terminate this request even as an internal component of
a custom build. Nothing here changes the litellm-searxng-search.md
recommendation; it remains correct and unrelated to this question.

## 6. Effort assessment and recommendation

**Option A — patch qwen-code + hand-roll a DashScope-Responses-shaped SSE
server in front of SearXNG.** What it needs, concretely:
1. Fork qwen-code, delete/relax `classifyDashScopeBaseUrl()` (§2) — trivial,
   but means building and distributing a patched CLI, and re-patching on every
   upstream update that touches this file or its surrounding gate logic.
2. Write a small HTTP server exposing `POST /responses` that: accepts the
   exact request shape in §2, calls SearXNG (`http://search.home`, already
   reachable per `docs/research/litellm-searxng-search.md`'s `extra_hosts`
   finding) for results, and streams back SSE events in the precise sequence
   qwen-code's parser expects (`response.output_item.added` /
   `.done` with a `web_search_call` item carrying `action.sources[].url`,
   optionally a `message` item with narrated text, then
   `response.completed`). No narration/LLM step is strictly required — an
   empty or templated `message` still satisfies the parser as long as at
   least one non-`failed` `web_search_call` item exists (§2's "no-search"
   check only counts search-call items, not narration quality).
   Realistically a few hundred lines (Node/Python + SSE), a day or so of
   work plus debugging the exact event ordering, error-shape (`event:error`
   quirk), and `store`/`instructions` fields the client sends but doesn't
   strictly require echoing back.
3. Register this server's URL as a `modelProviders` entry — except the
   patched hostname check from step 1 is required for step 3 to pass at all,
   so steps 1 and 2 are both mandatory, not alternatives.
4. Maintain the fork indefinitely against upstream qwen-code releases.

**Option B — do nothing further.** `docs/research/omniroute-qwen-websearch.md`
already documents a **verified, working, fully self-hosted** path: OmniRoute's
own `omniroute_web_search` MCP tool, backed by this stack's SearXNG instance,
confirmed connected (`qwen mcp list` → Connected) and exercised end-to-end
(`POST /v1/search` returned real results). This uses qwen-code's *documented,
supported, unpatched* MCP-server extension point (`mcpServers` in
`settings.json`) — no fork, no upstream-drift risk, no protocol shape to
maintain.

**Recommendation: do not build Option A.** The built-in `web_search` tool's
"DashScope-compatible" requirement is, by design in qwen-code's own source, a
hostname allowlist for Alibaba's cloud — it is not a compatibility surface
meant to be reimplemented, and no one else has reimplemented it either (§3).
Satisfying it self-hosted requires forking and permanently maintaining a
patch to code whose only purpose is to *stop* you from doing that. The MCP
path in `omniroute-qwen-websearch.md` already delivers the same end-user
capability (web search, backed by this stack's own SearXNG, no external
API) through qwen-code's actual supported extension point, with zero ongoing
fork-maintenance burden. There is no functional gap Option A would close that
Option B doesn't already close today.

## Open questions / unknowns

- Whether `DASHSCOPE_REGIONAL_HOSTS` or the extra suffixes
  (`maas.aliyuncs.com`, `alibaba-inc.com`, `aliyun-inc.com`) ever change
  across qwen-code releases — checked only against the current `main` branch
  (fetched 2026-09-05); a future release could tighten or loosen this list.
- Whether OpenAI's own `web_search_preview` Responses-API tool has a
  publicly documented exact request/response JSON schema identical enough to
  DashScope's `web_search`/`web_extractor` pair that a single shim could serve
  both — not independently verified against OpenAI's own docs in this pass;
  qwen-code's source (§2) is authoritative for the DashScope side only.
- Whether `teabranch/open-responses-server`'s planned "Web search: crawl4ai"
  roadmap item, if shipped, would end up emitting DashScope-shaped
  `web_search_call` items or OpenAI-shaped `web_search_preview` ones — could
  become relevant later but is speculative (unshipped) as of this research.

## Sources

- https://qwenlm.github.io/qwen-code-docs/en/developers/tools/web-search/ and
  https://raw.githubusercontent.com/QwenLM/qwen-code/main/docs/developers/tools/web-search.md
  — current built-in-tool vs. MCP options, settings keys, migration note.
- `packages/core/src/tools/web-search.ts`,
  `packages/core/src/core/openaiContentGenerator/constants.ts`,
  `packages/core/src/core/openaiContentGenerator/provider/dashscope.ts` —
  fetched directly from `QwenLM/qwen-code`'s `main` branch via
  `raw.githubusercontent.com` on 2026-09-05; ground truth for the request
  shape, SSE parsing, and the hostname gate (§2).
- https://github.com/QwenLM/qwen-code/issues/3841 — prior (closed,
  "not planned") community proposal for DashScope `enable_search` passthrough;
  shows the feature that eventually shipped took a different path (Responses
  API, not Chat Completions `enable_search`).
- https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-openai-responses
  and https://www.alibabacloud.com/help/en/model-studio/compatibility-with-openai-responses-api
  — Alibaba's own Responses API docs: endpoint, `tools` shape, `output` item
  shape.
- https://docs.qwencloud.com/developer-guides/tool-calling/web-search —
  the older Chat-Completions `enable_search` mechanism and its
  no-citations limitation.
- https://docs.vllm.ai/en/stable/api/vllm/entrypoints/openai/responses/,
  https://vllm.ai/blog/2025-08-05-gpt-oss,
  https://github.com/vllm-project/recipes/blob/main/OpenAI/GPT-OSS.md — vLLM's
  Responses API and gpt-oss browser-tool/tool-server support.
- https://github.com/sgl-project/sglang/issues/10038 — SGLang Responses API
  support unclear.
- https://github.com/BerriAI/litellm/issues/14011 — LiteLLM's `/v1/responses`
  rejects the `web_search` tool type.
- https://docs.litellm.ai/docs/providers/dashscope — LiteLLM's DashScope
  provider is a plain client wrapper, no Responses API, no web_search.
- https://github.com/teabranch/open-responses-server — closest
  "self-hosted Responses API shim" found; web_search not implemented
  (roadmap item only), checked live 2026-09-05.
- `G:\_DEV\repos\LLM-Server\docs\research\omniroute-qwen-websearch.md` —
  the already-working, verified self-hosted alternative this doc is weighed
  against.
- `G:\_DEV\repos\LLM-Server\docs\research\litellm-searxng-search.md` —
  LiteLLM's actual (unrelated) SearXNG integration, re-confirmed as
  orthogonal to this question in §5.

## Tried it live (2026-09-05) — confirmed empirically, plus one new fact

The user asked to actually run the experiment rather than stop at the analysis above.

**What was done** (all local to the WSL install, reverted afterward — nothing in
this repo or the live OmniRoute instance was left changed):
- Patched the installed CLI file
  `~/.local/lib/qwen-code/lib/chunks/web-search-K2FMOGS5.js` with a one-line
  bypass in `classifyDashScopeBaseUrl()`: `if (baseUrl.includes("proxy-ai.home")) return null;`
- Added a `tools.webSearch` block to `~/.qwen/settings.json` pointing
  `model`/`baseUrl` at a new `qwen-experiment-websearch` `modelProviders` entry
  using OmniRoute's existing `http://proxy-ai.home/v1` and the already-working
  `OMNIROUTE_API_KEY`.
- Ran `qwen` with a prompt forcing use of the built-in `web_search` tool.

**Result — the client-side gate bypass worked**, confirming the research's
read of `classifyDashScopeBaseUrl()` was accurate: qwen accepted the OmniRoute
host as "DashScope-compatible" and attempted the tool call. It stopped at an
interactive approval prompt first (expected — headless auto-approve wasn't
attempted, since that flips on unrestricted auto-execution of every tool call
at process privilege, not just this one).

**New fact, not visible from static docs alone**: a direct `curl -X POST
http://proxy-ai.home/v1/responses` (with a valid key, matching the request
shape qwen would send) returned `{"error":{"message":"No active credentials
for provider: codex.","type":"authentication_error","code":"invalid_api_key"}}`
— **not** the generic "unknown route" error a nonexistent path returns (verified
earlier in this same research thread against `/v1/search`-adjacent bogus
paths). So `/v1/responses` **is a real, implemented OmniRoute route**, not
merely undocumented — the earlier inference that it didn't exist was wrong;
it exists but is hardcoded to proxy exclusively through a specific provider
connection OmniRoute's catalog calls `codex`.

**`codex` identified via `PROVIDER_REFERENCE.md`**: `id: codex`, alias `cx`,
name "OpenAI Codex", **auth type: OAuth** — a real, personal
ChatGPT/OpenAI-account connection, not a free/no-auth scraper provider like
several others already connected in this instance (`felo-web`,
`duckduckgo-web`, etc.). Checked `docs/reference/ENVIRONMENT.md` for any
setting to redirect `/v1/responses` to a different provider — **none
exists**; there is no `responsesProvider` or equivalent override.

**Why routing isn't configurable, architecturally**: OpenAI's Responses API
`web_search` is a *hosted* tool — the search executes inside the model
backend's own infrastructure as part of generating the response, not as a
client-visible round trip. Confirmed directly against llama.cpp's own
`tools/server` docs (`github.com/ggml-org/llama.cpp/tree/master/tools/server`):
it implements only `/v1/chat/completions` with client-side tool-calling
(the model emits a `tool_call`; the *client* must execute it), has no
`/v1/responses` endpoint, no hosted-tool execution, and its built-in
`--tools` are local-only (`read_file`, `grep_search`, `exec_shell_command`,
etc.) — none make outbound HTTP requests. So even with configurable routing,
pointing `/v1/responses` at the local Qwen model wouldn't work: the upstream
llama-server has nothing that could serve the hosted-tool half of the
contract. Building that would mean OmniRoute (or a custom shim) intercepting
the model's tool-call mid-generation and splicing in a real search — the
same shim work priced out as not-worth-it earlier in this document, now
confirmed to be the *only* way, not one option among several.

**Conclusion holds, sharpened**: the dead end isn't just qwen-code's
client-side hostname check anymore — even a fully self-hosted, hostname-gate-bypassed
setup terminates at OmniRoute's `codex`-only `/v1/responses` routing, which
itself terminates at needing a real OpenAI/ChatGPT OAuth account, which is
exactly the kind of external paid dependency this whole line of inquiry was
trying to avoid. `omniroute_web_search` via MCP (already working, already
free, already self-hosted) remains the only path that actually satisfies the
original goal.

**Revert**: both the CLI patch and the `settings.json` changes were reverted
after the test — `omniroute-search` MCP confirmed still `Connected` via
`qwen mcp list` afterward. No lasting changes from this experiment.