Adding a new search provider

[lusty cloak]

I see there's a fixed set of AI search providers as I am installing OpenClaw. Brave, Exa, Firecrawl, etc. If I had another search provider in mind, how would I get it listed as a possible provider for OpenClaw?

[ruby meadow]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[pseudo siren]

Short version: it needs to be a web search provider plugin, not just a config entry.

I checked current source/docs: openclaw configure --section web builds that list from plugins that register a web-search provider. To appear there, the plugin should:

1. Implement/register:

api.registerWebSearchProvider({
  id: "my-search",
  label: "My Search",
  hint: "What makes it useful",
  onboardingScopes: ["text-inference"], // this makes it show in setup/configure web
  envVars: ["MY_SEARCH_API_KEY"],
  credentialPath: "plugins.entries.my-search.config.webSearch.apiKey",
  createTool: () => ({
    description: "Search using My Search",
    parameters: { type: "object", properties: { query: { type: "string" } } },

    execute: async (args) => ({ content: [] }),
  }),
});

2. Declare ownership in openclaw.plugin.json:

{
  "id": "my-search",
  "contracts": {
    "webSearchProviders": ["my-search"]
  }
}

3. Install/publish that plugin, or contribute it as a bundled extension if you want it in the default OpenClaw provider list for everyone.

Docs:

• Web search providers: https://docs.openclaw.ai/tools/web
• Provider plugin SDK: https://docs.openclaw.ai/plugins/sdk-provider-plugins#step-5-add-extra-capabilities
• Plugin manifest contracts: https://docs.openclaw.ai/plugins/manifest#contracts-reference

If you want this added upstream as a bundled provider, best path is to file a GitHub issue with the provider name/API docs and desired behavior: https://github.com/openclaw/openclaw/issues

[lusty cloak]

Cool - am I right in assuming that even if it's not added to the repo, OpenClaw users can still customize + add a new search endpoint (or any tool call they want) to their OpenClaw agent?

[pseudo siren]

Yes — that assumption is right.

You don’t need it added to the OpenClaw repo unless you want it bundled for everyone. A user can add their own capability locally by making/installing a plugin that either:

• registers a web search provider via registerWebSearchProvider(...) so it can back web_search
• registers a totally custom tool via registerTool(...)
• or uses an MCP-style integration if the tool already exists externally

The one caveat: it’s not usually “just add a URL in config.” OpenClaw needs something that adapts that endpoint into a tool/provider shape: schema, credentials, request logic, output format, etc.

Useful docs:

• https://docs.openclaw.ai/tools/web
• https://docs.openclaw.ai/plugins/building-plugins
• https://docs.openclaw.ai/plugins/sdk-provider-plugins

[lusty cloak]

What is the approval process like if I wanted to add a new search provider to the options in the OpenClaw repo?

[pseudo siren]

For getting it bundled into the OpenClaw repo, treat it like a normal upstream feature PR, with a little extra caution because new providers create long-term maintenance surface.

I’d do it like this:

1. Open a GitHub issue first describing the provider and why it should be bundled rather than just shipped as a third-party plugin. New features are often better as plugins unless there’s a strong reason to include them by default.
2. Include useful details:
   • provider API docs
   • auth/env var shape
   • expected result format
   • pricing/rate limits if relevant
   • whether it supports plain search, content extraction, citations, filters, etc.
3. If it seems accepted directionally, send a focused PR adding:
   • extensions/<provider>/...
   • openclaw.plugin.json with contracts.webSearchProviders
   • api.registerWebSearchProvider(...)
   • docs under the web/search tooling docs
   • tests for provider registration/config/runtime behavior