docs: add web search and web fetch design proposal

[alexeykazakov]

• Design for operator-managed web search via spec.webSearch (Brave, Tavily, DuckDuckGo, Gemini) and web fetch via spec.webFetch
• Search API keys use proxy credential injection — secrets never reach gateway
• Three provider categories: standalone API, key-free, LLM-as-search
• Companion questions doc with all design decisions and rationale

Summary by CodeRabbit

• Documentation
  • Finalized "Web Search and Web Fetch Support" design proposal: architecture, security model, reconciliation flow, provider categories, validation rules, proxy behavior, config injection, and implementation roadmap with examples.
  • Recorded final design decisions and Q&A for integrating web search: supported providers, credential delivery, validation rules, provider-specific proxy handling, single-provider config, WebFetch toggle, and related operational behaviors.

[coderabbitai]

Walkthrough

Adds two final design documents specifying operator-managed web search and web fetch support in the Claw CRD (status: Final, 2026-05-12), covering schema, validation, proxy configuration, provider categories (Brave, Tavily, DuckDuckGo, Gemini), reconciliation flow, and example specs.

Changes

Web Search & Web Fetch Design Proposal

Layer / File(s)	Summary
Proposal + architecture docs/proposals/web-search-design.md	New design doc (Final, 2026-05-12) describing how OpenClaw consumes openclaw.json for tools.web.search/plugins.entries.<provider>.config.webSearch and tools.web.fetch, provider categories, proxy route/domain behavior, and the end-to-end reconciliation flow including the WebSearchConfigured condition.
CRD schema, validation, and reconciler rules docs/proposals/web-search-design.md	Specifies ClawSpec additions: webSearch and webFetch, WebSearchSpec/WebFetchSpec shapes, CEL validation expressions and reconciler validation rules (including provider-specific checks and proxy requirements).
Proxy integration and secrets model docs/proposals/web-search-design.md	Defines proxy configuration changes: configureProxyForWebSearch, route generation, proxy secret mounting, secret resourceVersion stamping, and proxy credential injection with proxy domain allowlisting and placeholder API-key usage.
ConfigMap/operator.json injection & provider selection docs/proposals/web-search-design.md	Describes operator.json injection for tools.web.search and tools.web.fetch, provider-specific placeholder API keys, optional config merging behavior, and how the gateway sees provider selection.
Examples and implementation plan docs/proposals/web-search-design.md	Provides YAML examples for Brave, DuckDuckGo, Gemini, Tavily, and web-fetch-only; lists files and tests to be added/updated and reconciliation wiring steps.
Design Q&A docs/proposals/web-search-questions.md	Finalized answers to nine design questions covering API-key delivery (proxy injection), supported providers, provider category behaviors, single-provider struct choice, WebSearchConfigured semantics, Gemini Google-credential validation, and web.fetch handling.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

• docs: add config merge design proposal #89: related operator ConfigMap/operator.json injection and optional config merging behavior referenced by the web-search design.

Suggested labels

documentation, proposal

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding design proposal documents for web search and web fetch functionality.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/proposals/web-search-design.md`:
- Around line 88-89: Add explicit SSRF guardrails for webFetch and type:none
allowlist expansion: validate spec.credentials entries and any code paths that
set tools.web.fetch.enabled (when spec.webFetch.enabled is true) to reject or
strip domains that resolve to localhost/127.0.0.0/8, loopback/link-local ranges,
RFC1918 private ranges, metadata endpoints (e.g., 169.254.169.254 and cloud
provider metadata hostnames), IP-literal hosts (raw IPs in host portion), and
non-HTTP(S) schemes before updating the proxy allowlist; enforce the same
denylist in the proxy's runtime resolver/fetch layer so even allowed domains
cannot be used to reach these targets, and surface clear validation errors when
a spec.credentials entry with type:none is rejected.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: 3decb940-6a7f-41e1-9e8f-8a5d34feebc6

📥 Commits

Reviewing files that changed from the base of the PR and between be5d8c8 and f5fbf16.

📒 Files selected for processing (1)

• docs/proposals/web-search-design.md

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: E2E Tests
• GitHub Check: Unit Tests

🧰 Additional context used

📓 Path-based instructions (1)

**

⚙️ CodeRabbit configuration file

-Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity.

Files:

• docs/proposals/web-search-design.md

🪛 LanguageTool

docs/proposals/web-search-design.md

[grammar] ~88-~88: Ensure spelling is correct
Context: ... the proxy (LLM providers, search APIs, builtin passthroughs). Users can open additiona...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

---

[uncategorized] ~252-~252: “Google” is a proper noun and needs to be capitalized.
Context: ...which the operator already sets for the google LLM provider. If the user provides `spe...

(A_GOOGLE)

---

[uncategorized] ~252-~252: “Google” is a proper noun and needs to be capitalized.
Context: ...es.google.config.webSearch` (OpenClaw's google extension id) for provider-specific tun...

(A_GOOGLE)

🪛 markdownlint-cli2 (0.22.1)

docs/proposals/web-search-design.md

[warning] 92-92: Fenced code blocks should have a language specified

(MD040, fenced-code-language)