qwen-code/docs/developers/tools/web-search.md

Web Search

Qwen Code provides web search two ways:

1. Built-in web_search tool — backed by the DashScope Responses API server-side search or, for Qwen Subscription sessions, the Qwen MCP search service. Enabled after Plus/Pro subscription sign-in and on by default at startup for supported ModelStudio and OpenAI-compatible DashScope configurations; no extra provider or MCP setup.
2. MCP (Model Context Protocol) integrations — connect any external search service (Tavily, GLM, and others). Use this when your provider cannot back the built-in tool.

Built-in web_search

For DashScope, the built-in tool issues a self-contained search request to a small auxiliary model with server-side web_search (and web_extractor) tools, and returns the narrated findings plus source URLs. With Qwen Account with Subscription, it uses the Qwen MCP search service and your current login credentials. No separate search API key, auxiliary model, or mcpServers configuration is needed. webExtractor applies only to DashScope search.

When it turns on by itself

If you configured nothing under tools.webSearch, the tool registers whenever the model you are running can back the search request with the same credentials:

How you signed in	Built-in search
Qwen Account with Subscription — Plus or Pro	on
Alibaba ModelStudio → Standard API Key	on
Alibaba ModelStudio → Token Plan	on
Alibaba ModelStudio → Coding Plan	off — its endpoint is not verified for this API
QwenCloud → Standard API Key	on
QwenCloud → Token Plan	on
An OpenAI-compatible modelProviders or Custom Provider entry on a recognized DashScope Responses host, with a direct key	on
Third-party providers (OpenRouter, DeepSeek, ModelScope, …), custom endpoints on other hosts, local models	off

DashScope searches bill the same key as your main model; subscription searches reuse your Qwen login credentials. Permission handling follows the active approval mode and rules; in default approval mode the first search asks for confirmation. When your provider cannot back the tool, it simply does not appear at startup — no startup warning.

To turn it off:

{ "tools": { "webSearch": { "enabled": false } } }

or ENABLE_WEB_SEARCH=false. Bare mode and safe mode always disable it.

Configuring it explicitly

This section configures DashScope search. Subscription search reuses your membership credentials and needs no additional setup. Explicit search settings still take precedence over automatic subscription search.

Point the tool at a ModelStudio Standard/Token Plan or another verified DashScope Responses entry. This is useful when your main model runs on another provider and you also hold a separate supported DashScope key. Coding Plan hosts are excluded from automatic activation because the Responses search tools are not verified there. You can opt in explicitly with tools.webSearch.model; if the endpoint does not serve them, the first search fails loudly. Use an MCP search provider if you do not want to rely on that unverified path.

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3.8-flash",
        "envKey": "DASHSCOPE_API_KEY",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
      }
    ]
  },
  "tools": {
    "webSearch": {
      "enabled": true,
      "model": "qwen3.8-flash"
    }
  }
}

Setting	Env override	Meaning
tools.webSearch.enabled	ENABLE_WEB_SEARCH	Set false to turn the tool off. Implicit startup activation requires leaving enabled, model, and the env-only backend unset. Setting true permits automatic derivation only when the env-only backend is also unset; otherwise a model is required.
tools.webSearch.model	WEB_SEARCH_MODEL	Search model selector for the explicit path (modelId or authType:modelId). With WEB_SEARCH_BASE_URL it is the plain model id for that endpoint; otherwise it must match a declared DashScope-compatible modelProviders entry. The automatic path uses qwen3.8-flash.
tools.webSearch.webExtractor	WEB_SEARCH_EXTRACTOR	Let the search agent open result pages for better-grounded answers (default true; billed separately by DashScope).
tools.webSearch.timeoutMs	WEB_SEARCH_TIMEOUT_MS	Total time budget for one search, in milliseconds (default 120000, max 600000; other values fall back to the default). A search that runs out of time returns what arrived as a partial result once at least one search call has completed; if the budget expires before the first search call finishes, the tool reports a timeout error instead, because narration with no executed search is not auditable evidence. A per-tool execution cap (QWEN_CODE_TOOL_EXECUTION_TIMEOUT_MS) below this budget fires first and discards the partial result; keep it above timeoutMs.
tools.webSearch.allowedHosts	WEB_SEARCH_ALLOWED_HOSTS	Extra host suffixes trusted for a search backend you configured explicitly — an exact host, or any subdomain of a listed suffix (comma-separated in the env var). Empty by default, so behaviour is unchanged unless set. Only the WEB_SEARCH_BASE_URL backend and the modelProviders path consult it; automatic derivation never does, so a custom host is used only where your own configuration names it. The configured host receives the API key. Entries are trimmed and lower-cased, and entries without a dot are ignored.
tools.webSearch.maxPerSession	WEB_SEARCH_MAX_PER_SESSION	Maximum web_search calls in one session (default 200, max 10000; other values fall back to the default). The count is shared with subagents and resets when the session changes (/clear, /resume, branching). Once it is reached, further searches are skipped and the model is told to continue with what it has gathered.

Env-only configuration (no settings.json)

For environments where you cannot write a settings file (locked-down containers, CI with env injection only), the tool can be configured entirely through environment variables — no modelProviders entry needed:

export ENABLE_WEB_SEARCH=true
export WEB_SEARCH_MODEL=qwen3.8-flash
export WEB_SEARCH_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export WEB_SEARCH_ALLOWED_HOSTS=llm-gw.example.com   # only for a gateway host
export DASHSCOPE_API_KEY=sk-...        # or set WEB_SEARCH_API_KEY instead

WEB_SEARCH_BASE_URL mirrors a modelProviders entry's baseUrl and must be a DashScope-compatible endpoint; when it is set, it takes precedence over modelProviders resolution and WEB_SEARCH_MODEL is used as the plain DashScope model id. The API key is read from WEB_SEARCH_API_KEY if set, otherwise from DASHSCOPE_API_KEY. If the endpoint is a gateway on your own domain, list that host in WEB_SEARCH_ALLOWED_HOSTS (or tools.webSearch.allowedHosts) — the built-in list is otherwise the only thing the check accepts. Misconfiguration still surfaces as a startup notice.

Notes:

• For explicit DashScope search, the selector must resolve to a DashScope-compatible modelProviders entry carrying a direct API key via envKey. Your main model can be any provider. The legacy free Qwen OAuth provider cannot back this path; Qwen Subscription search uses the separate MCP service described above.
• Search registration is re-evaluated after successful authentication changes. Signing in to Qwen Subscription enables search in the current session without restarting. Explicit disabling, bare/safe mode, and tool permission rules still apply.
• Automatic host detection intentionally accepts only known DashScope regional hosts, Model Studio and QwenCloud MaaS hosts (including their token-plan. subscription subdomains), and internal Alibaba hosts. Generic *.alicloudapi.com gateways, DASHSCOPE_PROXY_BASE_URL and any host you only added to allowedHosts are excluded from that automatic path, because it runs without your involvement and would otherwise hand your main provider's key to a host nobody declared. For a gateway you do declare, list it in tools.webSearch.allowedHosts and point WEB_SEARCH_BASE_URL (or a modelProviders entry) at it.
• If enabled explicitly but misconfigured, the tool stays off and a startup notice explains which condition failed. Automatic activation never emits a notice.
• DashScope searches bill your DashScope key (usage.x_tools counts). Auto approval mode (the default) lets the classifier approve searches without prompting; in default approval mode the tool asks, and approving with "always allow" persists a standard WebSearch permission rule, like other tools.
• There is no client-side model allowlist; a model the Responses endpoint does not serve fails loudly on first use.
• A search that exceeds its time budget returns what arrived as a partial result once at least one search call has completed; if the budget expires before the first search call finishes, the tool reports a timeout error instead, because narration with no executed search is not auditable evidence. When a search call did complete but the narrated answer never arrived, the result carries at most 6,000 characters of the page text the agent had read, labeled as raw page content.
• The per-session cap counts web_search tool calls, not the searches one call runs internally, and a call that fails still counts because the request was sent. A skipped call is not an error: it tells the model the budget is used and to ask you to raise tools.webSearch.maxPerSession if more searches are genuinely needed.

MCP alternatives

If your provider cannot back the built-in tool, web search is available by connecting an external MCP server — see the services below.

⚠️ Historical Breaking Change: original built-in web_search removed

Affected versions: V0.0.7+ through the last release with the original multi-provider built-in web search.

The original built-in web_search tool (Tavily/Google/GLM/DashScope multi-provider) and its configuration were removed. The built-in tool documented above is a different implementation with different configuration. If you were using any of the following, migrate either to the new built-in tool (DashScope) or to MCP:

Removed	What to do
webSearch block in settings.json	Configure an MCP server in mcpServers instead (see below)
advanced.tavilyApiKey in settings.json	Use the Tavily MCP server
TAVILY_API_KEY environment variable	Use the Tavily MCP server
DASHSCOPE_API_KEY for web search	Use the built-in web_search tool
GLM_API_KEY for web search	Use the GLM WebSearch Prime MCP
--tavily-api-key / --glm-api-key / --dashscope-api-key CLI flags	Configure via mcpServers in settings.json

Migration Examples

Before (Tavily via built-in tool):

{
  "webSearch": {
    "provider": [{ "type": "tavily", "apiKey": "tvly-xxx" }],
    "default": "tavily"
  }
}

After (Tavily via MCP):

{
  "mcpServers": {
    "tavily": {
      "httpUrl": "https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-xxx"
    }
  }
}

---

Before (DashScope via built-in tool):

{
  "webSearch": {
    "provider": [{ "type": "dashscope", "apiKey": "sk-xxx" }],
    "default": "dashscope"
  }
}

After (Alibaba Cloud Bailian WebSearch via MCP):

{
  "mcpServers": {
    "WebSearch": {
      "httpUrl": "https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp",
      "headers": {
        "Authorization": "Bearer sk-xxx"
      }
    }
  }
}

---

Supported MCP Web Search Services

Alibaba Cloud Bailian WebSearch

The official web search MCP service provided by Alibaba Cloud Bailian platform, powered by DashScope. If you have a DashScope key, prefer the built-in web_search tool above — it uses a stronger search path than this MCP service.

• MCP Marketplace: https://bailian.console.aliyun.com/cn-beijing?tab=mcp#/mcp-market/detail/WebSearch
• Cost: Paid (billed via Alibaba Cloud DashScope)
• Get API Key: https://help.aliyun.com/zh/model-studio/get-api-key
• Best for: Chinese-language queries, access to Chinese web content, integration with the Alibaba Cloud ecosystem

Setup

Method 1: CLI command

qwen mcp add WebSearch \
  -t http \
  "https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp" \
  -H "Authorization: Bearer ${DASHSCOPE_API_KEY}"

Method 2: settings.json

{
  "mcpServers": {
    "WebSearch": {
      "httpUrl": "https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp",
      "headers": {
        "Authorization": "Bearer ${DASHSCOPE_API_KEY}"
      }
    }
  }
}

Replace ${DASHSCOPE_API_KEY} with your actual API key, or set it as an environment variable so Qwen Code picks it up automatically.

---

Tavily WebSearch

A production-ready MCP server providing real-time web search, extract, map, and crawl capabilities.

• Repository: https://github.com/tavily-ai/tavily-mcp
• Cost: Paid (free tier available)
• Get API Key: https://app.tavily.com/home
• Best for: General-purpose web search with high-quality AI-generated answers

Available Tools

• tavily_search — Real-time web search
• tavily_extract — Intelligent data extraction from web pages
• tavily_map — Create a structured map of a website
• tavily_crawl — Systematically explore websites

Setup

Method 1: CLI command (Remote MCP)

qwen mcp add tavily \
  -t http \
  "https://mcp.tavily.com/mcp/?tavilyApiKey=${TAVILY_API_KEY}"

Method 2: settings.json (Remote MCP)

{
  "mcpServers": {
    "tavily": {
      "httpUrl": "https://mcp.tavily.com/mcp/?tavilyApiKey=${TAVILY_API_KEY}"
    }
  }
}

Replace ${TAVILY_API_KEY} with your actual API key, or set it as an environment variable.

Method 3: settings.json (Local NPX)

{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here"
      }
    }
  }
}

---

GLM WebSearch Prime (ZhipuAI)

The official web search Remote MCP service provided by ZhipuAI (智谱AI), designed for GLM Coding Plan users. Provides real-time web search including news, stock prices, weather, and more.

• Documentation: https://docs.bigmodel.cn/cn/coding-plan/mcp/search-mcp-server
• Cost: Included in GLM Coding Plan subscription (Lite: 100 calls/month, Pro: 1,000/month, Max: 4,000/month)
• Get API Key: https://open.bigmodel.cn/apikey/platform
• Best for: Chinese-language queries, real-time information retrieval

Available Tools

• webSearchPrime — Web search returning page title, URL, summary, site name, and favicon

Setup

Method 1: CLI command

qwen mcp add web-search-prime \
  -t http \
  "https://open.bigmodel.cn/api/mcp/web_search_prime/mcp" \
  -H "Authorization: Bearer ${GLM_API_KEY}"

Method 2: settings.json

{
  "mcpServers": {
    "web-search-prime": {
      "httpUrl": "https://open.bigmodel.cn/api/mcp/web_search_prime/mcp",
      "headers": {
        "Authorization": "Bearer ${GLM_API_KEY}"
      }
    }
  }
}

Replace ${GLM_API_KEY} with your actual ZhipuAI API key, or set it as an environment variable.

---

Firecrawl

The official hosted MCP server from Firecrawl, providing web search, page scraping, website crawling and mapping, browser interaction, and file parsing. Search results can include each page's content as Markdown, so the model can read its sources without a separate fetch step. The hosted server works without an API key for search, scrape, and parse. Search queries, the URLs you ask it to read, and any files you parse are sent to Firecrawl.

• Documentation: https://docs.firecrawl.dev/mcp-server
• Cost: No API key needed for search, scrape, and parse (daily limit per IP); paid plans for higher limits
• Get API Key: https://www.firecrawl.dev/app/api-keys
• Best for: Web search where the model also needs to read the pages it finds, and trying MCP web search without an API key

Available Tools

• firecrawl_search — Web search, optionally returning each result's page content as Markdown
• firecrawl_scrape — Get a single page as clean Markdown
• firecrawl_parse — Convert a local file (PDF, Word, spreadsheet, and more) to Markdown

With an API key, the server also offers tools to map and crawl websites, interact with pages (click, type, navigate), and search developer sources like GitHub issues and docs.

Setup

Method 1: CLI command (Remote MCP)

qwen mcp add firecrawl \
  -t http \
  "https://mcp.firecrawl.dev/v2/mcp" \
  -H "Authorization: Bearer ${FIRECRAWL_API_KEY}"

To try it without a key, leave out the -H line. You get firecrawl_search, firecrawl_scrape, and firecrawl_parse within a daily per-IP limit.

Method 2: settings.json (Remote MCP)

{
  "mcpServers": {
    "firecrawl": {
      "httpUrl": "https://mcp.firecrawl.dev/v2/mcp",
      "headers": {
        "Authorization": "Bearer ${FIRECRAWL_API_KEY}"
      }
    }
  }
}

Replace ${FIRECRAWL_API_KEY} with your actual API key, or set it as an environment variable. If the key is empty, the server still connects but only offers the three keyless tools.

Method 3: settings.json (Local NPX)

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp@latest"],
      "env": {
        "FIRECRAWL_API_KEY": "your-api-key-here"
      }
    }
  }
}

---

SerpApi

The official hosted MCP server by SerpApi, providing real-time structured search results from Google, Baidu, Bing and other search engines through a single tool. Search queries and their parameters are sent to SerpApi.

• Documentation: https://serpapi.com/integrations/mcp
• Cost: Paid (free plan available)
• Get API Key: https://serpapi.com/manage-api-key
• Best for: Structured results from a broad choice of search engines

Available Tools

• search — Web search, optionally returning results as Markdown

Setup

Method 1: CLI command

qwen mcp add serpapi \
  -t http \
  "https://mcp.serpapi.com/mcp" \
  -H "Authorization: Bearer ${SERPAPI_API_KEY}"

Method 2: settings.json

{
  "mcpServers": {
    "serpapi": {
      "httpUrl": "https://mcp.serpapi.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SERPAPI_API_KEY}"
      }
    }
  }
}

Replace ${SERPAPI_API_KEY} with your actual API key, or set it as an environment variable. The key is only needed for searches. Without a valid API key, the server still connects and lists its tools, but search returns an error.

---

looot

A hosted MCP server from looot with web search, Google SERP results, news search and web page reading. Search queries and the URLs you ask it to read are sent to looot.

• Documentation: https://docs.looot.ai
• Cost: Paid (prepaid balance, no free tier)
• Get API Key: https://looot.ai
• Best for: Web search, Google SERP and news results, and reading a page as text

Available Tools

• web_search — Web search
• google_search_results — Google SERP results
• news_search — News search
• read_web_page — Read a single page as text

The server also exposes company and email lookups.

Setup

Method 1: CLI command (Remote MCP)

qwen mcp add looot \
  -t http \
  "https://api.looot.ai/mcp" \
  -H "Authorization: Bearer ${LOOOT_API_KEY}"

Method 2: settings.json (Remote MCP)

{
  "mcpServers": {
    "looot": {
      "httpUrl": "https://api.looot.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${LOOOT_API_KEY}"
      }
    }
  }
}

Replace ${LOOOT_API_KEY} with your actual API key, or set it as an environment variable.

---