TLDR: OpenClaw's built-in web_search tool uses whichever provider you configure, and auto-detection never picks a key-free one. You.com plugs in as MCP tools instead. Install the official plugin with openclaw plugins install clawhub:you, give its you server OAuth or a YDC_API_KEY bearer header, or add https://api.you.com/mcp?profile=free for keyless search at 100 queries a day. Then run openclaw mcp doctor you --probe to prove the tools load.
This guide covers the configuration question: what OpenClaw searches with, and how to wire You.com in through the Model Context Protocol. It was checked against OpenClaw's documentation in September 2026, when the current release was OpenClaw 2026.9.6. For a finished bot, the Discord build guide uses You.com's shell-based skill, and the skill launch post explains why that skill was built CLI-first. The MCP route differs in one practical way: tools arrive through OpenClaw's MCP client under normal tool policy, so the agent needs no shell access to search.
What Search Engine Does OpenClaw Use by Default?
None, until you choose. OpenClaw's web_search tool sends queries to the provider named in tools.web.search.provider. If that field is unset, OpenClaw auto-detects: it walks a fixed precedence list and uses the first API-backed provider whose credential it finds. The documented order is Brave, MiniMax Search, Gemini, Grok, Kimi, Perplexity, Firecrawl, Exa, Tavily, and paid Parallel, followed by a configured SearXNG endpoint (OpenClaw web search docs).
Three details in that logic decide what a fresh install can do:
- Key-free providers never win auto-detection. Parallel Search (Free), DuckDuckGo, Ollama Web Search, and Codex Hosted Search run only when you select them explicitly. OpenClaw does not route managed searches to a key-free provider just because no API key is configured, so without a key, managed search has no provider to use.
- Some models bring their own search. While the provider is unset, direct OpenAI Responses models use OpenAI's hosted web search, and the Codex app-server runtime uses Codex's hosted search. Settings → Search in the Control UI shows the effective route for each agent and model: native, a managed provider, disabled, or unavailable.
- Provider IDs must come from a search plugin. OpenClaw validates
tools.web.search.provideragainst the IDs that bundled and installed plugins declare, and a typo fails validation. The You.com plugin declares no search provider, so You.com never appears as aweb_searchbackend. Its tools sit next toweb_searchas separate MCP tools that the agent calls directly.
So adding You.com does not replace web_search; it adds You.com's search and page-extraction tools alongside it. If the protocol is new to you, read what the Model Context Protocol is first.
Which You.com Integration Fits Your OpenClaw Setup?
There are three ways to give an OpenClaw agent You.com search, and they differ in what gets installed and how the agent reaches the API:
| Path | What it installs | How the agent calls You.com | Auth |
|---|---|---|---|
Official plugin (clawhub:you) | Five skills, three MCP server definitions, YDC_API_KEY setup metadata | MCP tools | You add OAuth or an API key to the server entry |
Direct entry in mcp.servers | One server definition you control | MCP tools | Free profile, OAuth 2.1, or bearer API key |
youdotcom-cli skill | One skill that runs curl and jq against the REST API | Shell commands through the exec tool | API key |
The first two combine well, and this guide covers both: the plugin's skills teach the agent when to search, read a page, or run research, and your own server entry decides which tools exist and how they authenticate. The third path, the youdotcom-cli skill on ClawHub, is the one the Discord guide uses. It suits bash-first agents, but it needs exec permission, and results come back as command output rather than as MCP tool results.
How Do You Install the You.com Plugin From ClawHub?
Run these on the machine that hosts your OpenClaw Gateway. The last command confirms the plugin's skills loaded:
openclaw plugins install clawhub:you
# or pin the release you tested
openclaw plugins install clawhub:you@1.6.1
# or install the same package from npm
openclaw plugins install npm:@youdotcom-oss/openclaw
openclaw skills listAs of September 2026, the ClawHub listing marks you as official, at version 1.6.1, source-linked to the youdotcom-oss/agent-skills repository, and compatible with OpenClaw 2026.7.1-3 or later. You.com documents the same two install commands on its Agent Skills page. The package manifest declares:
- Five skills:
you-web,you-research,you-finance,you-discover, andyou-free. They load while the plugin is enabled, at the lowest skill precedence, so a same-named workspace skill overrides them. - Three MCP servers:
youathttps://api.you.com/mcp,you-researchat/mcp/research, andyou-financeat/mcp/finance, all over Streamable HTTP. - Setup metadata naming
YDC_API_KEY, plus a runtime-free entry point.
Here is the part that trips up first installs: none of those server entries carries credentials. OpenClaw describes setup.providers[].envVars as env vars that setup and status surfaces can check, not as something that writes an Authorization header. Without credentials, the default You.com endpoint answers 401 and points to its OAuth metadata (checked September 28, 2026). The skills cannot fill the gap either. OpenClaw's skills docs say an eligible skill does not grant tool access, and You.com's docs say a skill does not replace connecting an MCP server.
So finish the install by defining you yourself. OpenClaw treats user configuration as authoritative: an entry named you under mcp.servers replaces the plugin's default (manifest reference), and it lives where openclaw mcp status, doctor, and login operate. The next section gives three ways to write it. Pin the plugin in production: OpenClaw's install docs say to treat plugin installs like running code, and an unversioned clawhub:you follows new releases on openclaw plugins update.
How Do You Connect the You.com MCP Server Directly?
Each option below writes one entry under mcp.servers in OpenClaw's JSON5 config, ~/.openclaw/openclaw.json by default (config basics). Always pass --transport streamable-http. When the transport is omitted, OpenClaw falls back to SSE (transports reference), while the You.com endpoint accepts only POST requests and returns 405 for other methods (You.com MCP server docs).
Try it keyless with the free profile
openclaw mcp add you-free \
--url 'https://api.you.com/mcp?profile=free' \
--transport streamable-http
openclaw mcp doctor you-free --probeThe free profile needs no account. As of September 2026 it exposes you-search and you-discover, capped at 100 queries per day, and leaves out contents, research, finance, and balance. A keyless tools/list call on September 28, 2026 returned exactly those two tools. The name you-free is deliberate: the plugin's you-free skill uses that name for the free-profile server in its metadata, and when you-search is missing the skill tells the agent to ask you before changing MCP configuration. You.com's own guidance is to use an API key for everything beyond evaluation.
Sign in with OAuth 2.1
openclaw mcp add you \
--url https://api.you.com/mcp \
--transport streamable-http \
--auth oauth \
--include 'you-search,you-contents'
openclaw mcp login you
openclaw mcp doctor you --probeThe You.com remote server supports OAuth 2.1, so no key touches your config. openclaw mcp login prints an authorization URL, listens for the loopback redirect, and saves the tokens in OpenClaw's state database. On a headless Gateway, open the URL on another machine and pass the returned code back with the printed --code command. Two behaviors matter here. Static Authorization headers are ignored while auth: "oauth" is set, so pick one method per entry. And until login saves credentials, OpenClaw leaves that server out of the agent runtime instead of failing the turn, so a skipped login looks like an agent that simply never searches.
Use an API key from the environment
Create a key on the You.com API Keys page. It is shown only once, and new accounts start with $100 in complimentary credits as of September 2026 (authentication docs). Add YDC_API_KEY=your-key to ~/.openclaw/.env, which OpenClaw reads as a global fallback, then save the server with a reference instead of the literal key:
openclaw mcp set you '{"url":"https://api.you.com/mcp?tools=you-search,you-contents","transport":"streamable-http","headers":{"Authorization":"Bearer ${YDC_API_KEY}"}}'
openclaw mcp doctor you --probeThe single quotes stop your shell from expanding the variable, so the config stores ${YDC_API_KEY} and OpenClaw substitutes it when it loads config. A missing variable stays visibly unresolved and logs a warning (environment variables). This follows OpenClaw's rule to keep credentials out of config literals, and openclaw mcp doctor warns when a sensitive-looking header holds a literal value.
If you manage config as a file, the OAuth entry from above looks like this. OpenClaw's config is JSON5, and this strict JSON parses as either:
{
"mcp": {
"servers": {
"you": {
"url": "https://api.you.com/mcp",
"transport": "streamable-http",
"auth": "oauth",
"toolFilter": {
"include": ["you-search", "you-contents"]
}
}
}
}
}Which You.com Tools Should Your Agent See?
The tool list depends on the URL you connect to. You.com computes enabled tools on every request as the intersection of the profile ceiling and the allowlist:
| URL | Tools the agent sees | Auth |
|---|---|---|
https://api.you.com/mcp | you-search, you-contents, you-balance, you-discover | OAuth or API key |
https://api.you.com/mcp?profile=free | you-search, you-discover | None, 100 queries per day |
https://api.you.com/mcp?tools=you-search,you-contents | Exactly the named tools | OAuth or API key |
https://api.you.com/mcp/research | you-research only | OAuth or API key |
https://api.you.com/mcp/finance | you-finance only | OAuth or API key |
There is no you-answer tool on this server, although some older setup guides list one. Research and finance stay off the default list until you use their dedicated paths or name them in ?tools=.
You can scope in two places. On the server side, ?tools= or an X-Allowed-Tools header sets the allowlist; unknown names are dropped, and an empty intersection returns zero tools with no error. On the OpenClaw side, toolFilter.include and toolFilter.exclude filter the discovered tools, with simple * globs, before they become OpenClaw tools. Use one layer per entry so a reviewer can read the effective list at a glance.
For most assistants, you-search plus you-contents is a sensible default. You.com's docs call this pair the research base: the agent runs its own search, read, and synthesize loop, and the slower, higher-cost you-research tool stays out of reach. If you keep the plugin's you-research or you-finance entries, give them credentials the same way, or set enabled: false to drop them. For research, consider raising requestTimeoutMs, since OpenClaw's default per-server request timeout is 60 seconds (MCP config reference).
How Do You Verify the Agent Is Actually Calling You.com?
OpenClaw's own docs draw the line between configured and working: "Configured means credential or setup information is present. It does not prove that the provider accepts the credential or is reachable." A saved MCP definition works the same way. Check in this order:
openclaw mcp status --verbosereads config without connecting. It shows the resolved transport, auth mode, and filters, and flags stored OAuth tokens that need more authorization.openclaw mcp doctor you --proberuns static checks, including disabled servers, literal secrets, and incomplete OAuth, then opens a live connection and lists the tools the server advertises. Ifyou-searchis missing, look at your filter or profile.- In a Control UI chat, open + → Connectors → Tool access to inspect the tools available to that session. A passing probe proves the server works; it does not prove the session's tool policy lets the agent use it.
- Ask a question only a live search can answer, such as the latest OpenClaw release, and confirm the reply cites result URLs instead of answering from memory.
If a change does not seem to land, check which process owns the connection. With the Gateway's default hybrid hot reload, changed or removed servers retire immediately and the next turn uses the new definition. openclaw mcp reload refreshes only the current CLI process, so a Gateway running elsewhere needs its own reload, config publish, or restart (Connect MCP servers).
What Goes Wrong on First Install?
Several of these failures are silent: the server loads, the agent answers, and nothing tells you You.com was never called. These are the documented causes, drawn from OpenClaw's MCP registry and tool policy references and the You.com docs:
| Symptom | Cause | Fix |
|---|---|---|
web_search is on but has no provider | No API-backed key was found, and key-free providers are never auto-selected | Pick a provider in Settings → Search or with openclaw configure --section web, or let the agent use the You.com tools |
| The probe passes, but the agent never sees You.com tools | tools.profile is minimal, which hides MCP tools, or tools.deny includes bundle-mcp | Use the coding, messaging, or full profile, or add bundle-mcp to tools.alsoAllow |
| Tools disappear only in sandboxed sessions | With sandbox mode all or non-main, tools.sandbox.tools is a second gate | Add bundle-mcp or a server glob such as you__*; openclaw doctor checks this for entries in mcp.servers |
| The agent never searches after an OAuth setup | Login never completed, so OpenClaw omitted the server | Run openclaw mcp login you; status --verbose reports authorization-required until you do |
| The probe cannot connect | transport was omitted, so OpenClaw used SSE against a POST-only endpoint | Set transport to streamable-http |
| The probe connects but lists zero tools | The profile and allowlist do not intersect, such as ?profile=free with you-research | Drop the profile or fix the allowlist |
you-search works, but you-contents fails | API keys are scoped per product, and a key without Contents access gets a 403 reading "Missing required scopes" | Create a key with Contents access |
| Two search tools in a Claude Code, Codex CLI, or Gemini CLI session | With no managed provider selected, those adapters keep native search, and your You.com server is an additional tool | Select a managed provider to turn native search off, or keep both deliberately |
How Do You Keep a Searching Assistant Safe?
Search results are untrusted input, and an OpenClaw assistant often holds tools that act: messages, files, a browser. OpenClaw marks managed web_search results with an untrusted external-content wrapper, and the you-free skill tells the agent to treat results as evidence, not instructions. Neither makes injection impossible, so read our guide to prompt injection in AI agents before you give a searching assistant side-effect tools, and keep approvals and tool policy tight on those tools.
Two settings matter once the assistant serves a shared channel:
- Whose account pays. OAuth credentials are shared and operator-managed by default, so every sender on a shared Gateway searches on the operator's You.com account. Setting
oauth.identitytoper-requestergives each sender a separate sign-in. It requiresgateway.publicOrigin, and sign-in links are single-use bearer links, so use it only in channels where senders trust each other. - Where the key lives. Keep
YDC_API_KEYin the environment or OpenClaw's secret store, never in a committed config file. If a key leaks, revoke it on the API Keys page; revoked keys stop working immediately.
The same pattern works in other clients. The Cursor setup and the Claude Code setup connect the same server, and a written evaluation plan helps before you pick any provider: see what to test first in a web search API for agents.
LI Test
LI Test
Share Article: