ccs/docs/websearch.md

WebSearch Configuration Guide

Last Updated: 2026-03-27

CCS provides automatic web search for third-party profiles that cannot access Anthropic's native WebSearch API.

How WebSearch Works

Native Claude Accounts

Native Claude subscription accounts still use Anthropic's server-side WebSearch directly.

Third-Party Profiles

Third-party profiles cannot execute Anthropic's server-side WebSearch because the tool never reaches their backend. CCS now solves that by intercepting WebSearch and running real local search providers directly.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                   Claude Code CLI                           │
│                                                              │
│  WebSearch Tool Request                                      │
│       │                                                      │
│       ├── Native Claude Account? → Anthropic WebSearch API  │
│       │                                                      │
│       └── Third-party Profile? → PreToolUse Hook            │
│                                   │                          │
│                                   ├── 1. Exa Search API      │
│                                   ├── 2. Tavily Search API   │
│                                   ├── 3. Brave Search API    │
│                                   ├── 4. DuckDuckGo HTML     │
│                                   └── 5. Legacy CLI fallback │
│                                      (Gemini/OpenCode/Grok)  │
└──────────────────────────────────────────────────────────────┘

Why This Changed

The previous design asked another model CLI to perform web search and summarize the answer. That was brittle:

• CLI syntax changed upstream
• auth state varied per tool
• prompt/tool behavior drifted across releases

The new flow matches the goclaw model more closely: web search is treated as a first-class deterministic capability, not an LLM-to-LLM workaround.

Providers

Provider	Type	Setup	Default	Notes
Exa	HTTP API	EXA_API_KEY	No	High-quality API search with extracted content
Tavily	HTTP API	TAVILY_API_KEY	No	Agent-oriented search API
DuckDuckGo	HTML fetch	None	Yes	Built-in zero-setup fallback
Brave Search	HTTP API	BRAVE_API_KEY	No	Cleaner snippets and metadata
Gemini CLI	Legacy CLI	npm i -g @google/gemini-cli	No	Optional compatibility fallback
OpenCode	Legacy CLI	curl -fsSL https://opencode.ai/install | bash	No	Optional compatibility fallback
Grok CLI	Legacy CLI	npm i -g @vibe-kit/grok-cli + GROK_API_KEY	No	Optional compatibility fallback

Configuration

Via Dashboard

Open ccs config → Settings → WebSearch.

• Enable Exa, Tavily, Brave, or DuckDuckGo in the backend chain
• Set or rotate Exa, Tavily, and Brave API keys directly inside each provider card
• Saved keys are persisted in global_env and injected at runtime, so readiness updates from the same screen
• Review whether any legacy fallback CLIs are still enabled in config

Via Config File

Edit ~/.ccs/config.yaml:

websearch:
  enabled: true
  providers:
    exa:
      enabled: false
      max_results: 5
    tavily:
      enabled: false
      max_results: 5
    duckduckgo:
      enabled: true
      max_results: 5
    brave:
      enabled: false
      max_results: 5
    gemini:
      enabled: false
      model: gemini-2.5-flash
      timeout: 55
    opencode:
      enabled: false
      model: opencode/grok-code
      timeout: 90
    grok:
      enabled: false
      timeout: 55

Environment Variables

Variable	Description
EXA_API_KEY	Enables Exa when providers.exa.enabled: true
TAVILY_API_KEY	Enables Tavily when providers.tavily.enabled: true
BRAVE_API_KEY	Enables Brave Search when providers.brave.enabled: true
GROK_API_KEY	Required only for legacy Grok CLI fallback
CCS_WEBSEARCH_SKIP	Skip hook entirely
CCS_DEBUG	Verbose hook logging

Troubleshooting

WebSearch says "Ready (DuckDuckGo)"

That is expected. DuckDuckGo is the default zero-setup backend.

Exa, Tavily, or Brave is enabled but not ready

Set the matching API key in the WebSearch dashboard card, or export it in the environment that launches CCS, then refresh status:

export EXA_API_KEY="your-api-key"
# or: export TAVILY_API_KEY="your-api-key"
# or: export BRAVE_API_KEY="your-api-key"
ccs config

If the dashboard says the key is stored but still not ready, check whether Settings -> Global Env is disabled. WebSearch reuses that injection path for dashboard-managed keys.

I still want Gemini/OpenCode/Grok fallback

Those providers remain supported, but they are no longer the primary path. Enable them explicitly in config.yaml if you want them as last-resort fallback.

WebSearch returns no results

1. Check websearch.enabled: true
2. Keep DuckDuckGo enabled unless you have a strong reason to disable it
3. If using Exa, Tavily, or Brave, verify the matching API key
4. Run with CCS_DEBUG=1 for hook logs

Security Considerations

• API keys entered from the dashboard are stored in ~/.ccs/config.yaml under global_env and injected as environment variables at runtime
• Shell-exported keys still work and are detected as external environment input
• Never commit API keys to version control
• Use the dashboard only on trusted machines, and protect ~/.ccs/config.yaml with normal user-level filesystem permissions