mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-16 18:16:08 +00:00
147 lines
5.3 KiB
Markdown
147 lines
5.3 KiB
Markdown
# WebSearch Configuration Guide
|
|
|
|
Last Updated: 2026-03-23
|
|
|
|
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
|
|
- Export the matching API key first for Exa, Tavily, or Brave
|
|
- Review whether any legacy fallback CLIs are still enabled in config
|
|
|
|
### Via Config File
|
|
|
|
Edit `~/.ccs/config.yaml`:
|
|
|
|
```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
|
|
|
|
Export the matching API key in the environment that launches CCS, then refresh status:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
### 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 stay in environment variables, not in dashboard state
|
|
- Never commit API keys to version control
|
|
- Use shell profile or `.env` tooling with proper permissions
|