Complete Tutorial: Connecting OpenClaw to Google/Brave/Perplexity/Grok/Kimi Search Engines

Difficulty: Intermediate | Duration: 15 Minutes | Takeaway: Master configuration methods for the 5 major search providers in OpenClaw

Target Audience

• Developers who have installed OpenClaw and want to enable search functionality
• Engineers with 1-5 years of experience interested in AI Agent tool configuration
• Users who want to give OpenClaw real-time web search capabilities

Core Dependencies

• Node.js 18+
• OpenClaw (latest version)
• API Key for at least one search provider

Project Structure

openclaw/
├── config.yaml              # Main configuration file
├── .env                     # Environment variables (optional)
└── src/
    └── agents/tools/
        └── web-search.ts    # Search implementation

1. Why Configure a Search Provider

One of the core capabilities of OpenClaw is enabling AI Agents to search the web in real-time. When your agent needs to look up data, stay updated on the latest info, or verify facts, the search tool serves as its "eyes."

OpenClaw supports 5 major search providers; you can choose based on your needs:

2. Configuration Method 1: Environment Variables

The simplest way is through environment variables. OpenClaw will automatically read these variables upon startup to enable the corresponding search provider.

2.1 Provider-specific Environment Variables

# Perplexity
export PERPLEXITY_API_KEY="pplx-xxxxxxxxxxxx"

# Brave Search
export BRAVE_API_KEY="BSAxxxxxxxxxxxx"

# Gemini (Google)
export GEMINI_API_KEY="AIzaSyxxxxxxxxxxxx"

# Grok (xAI)
export XAI_API_KEY="xai-xxxxxxxxxxxx"

# Kimi (Moonshot) - Both supported
export KIMI_API_KEY="sk-xxxxxxxxxxxx"
# OR
export MOONSHOT_API_KEY="sk-xxxxxxxxxxxx"

2.2 Full Example

Create a .env file:

# OpenClaw Config
OPENCLAW_SECRET_INPUT_MODE=ref

# Search provider (choose one)
PERPLEXITY_API_KEY=pplx_xxxxxxxxxxxxxxxx

# Other optional configs
LOG_LEVEL=info

Then start OpenClaw:

openclaw start

3. Configuration Method 2: config.yaml

For more granular control, you can configure settings directly in config.yaml.

3.1 Basic Configuration Structure

tools:
  web:
    search:
      enabled: true
      provider: perplexity  # Choose provider
      maxResults: 5         # Number of results 1-10
      timeoutSeconds: 30    # Request timeout
      cacheTtlMinutes: 15   # Cache duration

3.2 Individual Provider Configurations

tools:
  web:
    search:
      enabled: true
      provider: perplexity
      maxResults: 5

      # Perplexity Config
      perplexity:
        apiKey: pplx_xxxxxxxxxxxx

      # Brave Config (used when provider is brave)
      apiKey: BSAxxxxxxxxxxxx

      # Grok Config (used when provider is grok)
      grok:
        apiKey: xai-xxxxxxxxxxxx
        model: grok-4-1-fast
        inlineCitations: false

      # Gemini Config (used when provider is gemini)
      gemini:
        apiKey: AIzaSyxxxxxxxxxxxx
        model: gemini-2.5-flash

      # Kimi Config (used when provider is kimi)
      kimi:
        apiKey: sk-xxxxxxxxxxxx
        baseUrl: https://api.moonshot.ai/v1
        model: moonshot-v1-128k

4. Hands-on Configuration Examples

Next, we will configure the most popular provider, Perplexity, using two methods.

4.1 Perplexity: Precise Filtered Search

Step 1: Get an API Key

Visit Perplexity API Settings to register an account and generate an API Key. Note that Perplexity API requires separate billing from personal subscription accounts.

Step 2: Set Environment Variables

# Linux/macOS
export PERPLEXITY_API_KEY="pplx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Windows (PowerShell)
$env:PERPLEXITY_API_KEY="pplx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Step 3: Start OpenClaw

openclaw start

OpenClaw will automatically detect PERPLEXITY_API_KEY and enable Perplexity search.

Model Selection Guide:

Perplexity has two main models:

• sonar — Lightweight and fast, 127K context, ideal for high-frequency simple queries ($1/M tokens)
• sonar-pro — High reasoning capability, 200K context, ideal for complex research tasks ($6/M tokens)

Advanced Filtering (config.yaml):

tools:
  web:
    search:
      enabled: true
      provider: perplexity
      maxResults: 5
      perplexity:
        apiKey:
          source: env
          provider: default
          id: PERPLEXITY_API_KEY
        # Search recency filter: hour / day / week / month
        searchRecencyFilter: week
        # Search specific domains only (e.g., limit to authoritative sources)
        searchDomainFilter:
          - "github.com"
          - "stackoverflow.com"

Rate Limits: Default is 50 requests/minute, using a leaky bucket algorithm. If you encounter 429 errors, it is recommended to implement exponential backoff retries.

4.2 Brave Search: Privacy-First Regional Search

Step 1: Register for Brave Search API

Visit Brave Search API Dashboard. It offers approximately 1000 free queries per month ($5 free credit), then $5/1000 requests thereafter.

export BRAVE_API_KEY="BSAxxxxxxxxxxxxxxxx"

Step 2: Set provider to brave

tools:
  web:
    search:
      provider: brave
      apiKey:
        source: env
        provider: default
        id: BRAVE_API_KEY
      brave:
        # Specify country/region (ISO 3166-1 alpha-2, e.g., US / GB / DE / JP / CN)
        country: US
        searchLang: en
        # Freshness: pd(day) / pw(week) / pm(month) / py(year)
        freshness: pw

Brave Goggles (Custom Ranking): Brave's unique Goggles feature allows you to customize search result rankings, such as prioritizing technical docs or blocking low-quality content farms.

Cost Control: Set usage limits in the Brave Dashboard to avoid unexpected budget overruns. Combine with caching (cacheTtlMinutes: 60) to reduce calls.

4.3 Gemini: Google AI Search Grounding

Step 1: Get a Gemini API Key

Visit Google AI Studio to create an API Key. The free tier is quite generous.

export GEMINI_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Step 2: Configuration

tools:
  web:
    search:
      provider: gemini
      gemini:
        apiKey:
          source: env
          provider: default
          id: GEMINI_API_KEY
        model: gemini-2.5-flash

How it works: Gemini uses Google Search Grounding to automatically decide if it needs to search the web. When needed, it executes a search and attaches groundingMetadata (sources and citations) to the response. Search is not triggered for every request.

Billing: Billed per prompt (not per search) for Gemini 2.5 and below. Daily limit is 1 million queries.

4.4 Grok: Web + X Platform Dual Search

Grok’s unique advantage is its ability to search both the web and the X (Twitter) platform simultaneously, making it ideal for tracking real-time social media trends.

export XAI_API_KEY="xai-xxxxxxxxxxxx"

tools:
  web:
    search:
      provider: grok
      grok:
        apiKey:
          source: env
          provider: default
          id: XAI_API_KEY
        # Recommended model: Optimized for agentic search
        model: grok-4-1-fast
        # Enable inline citations, response includes [[1]](url) annotations
        inlineCitations: true

Dual Search Combo: Grok supports enabling web_search (general web) and x_search (X platform) together, allowing filters for specific handles or date ranges:

grok:
  tools:
    - type: web_search
      # Understand image content during search
      enableImageUnderstanding: true
    - type: x_search
      # Only see X content from 2025 onwards
      fromDate: "2025-01-01"
      # Only track specific accounts
      allowedXHandles:
        - "elonmusk"
        - "xai"

Billing Reminder: web_search and x_search each cost $10/1000 tool calls, plus token costs. Monitor usage carefully during high-frequency tasks.

4.5 Kimi: Ultra-Long Context + Extremely Low Cost

Kimi is a large model by Moonshot AI. Its API pricing is highly competitive ($0.60/$2.50 per M tokens), and it features automatic context caching (saving 75% on input costs), making it suitable for summarizing large search results or processing long documents.

export KIMI_API_KEY="sk-xxxxxxxxxxxx"
# OR
export MOONSHOT_API_KEY="sk-xxxxxxxxxxxx"

tools:
  web:
    search:
      provider: kimi
      kimi:
        apiKey:
          source: env
          provider: default
          id: KIMI_API_KEY
        # Use international endpoint by default; switch to api.moonshot.cn for Mainland China
        baseUrl: https://api.moonshot.ai/v1
        # Recommended K2 series, supports native $web_search tool
        model: kimi-k2.5
        # Instant mode (non-thinking), ideal for quick searches
        temperature: 0.6

Endpoint Selection:

• Global (Recommended): https://api.moonshot.ai/v1
• Mainland China: https://api.moonshot.cn/v1

Model Versioning: The old moonshot-v1-128k series is now legacy. New projects should use the K2 series (kimi-k2.5, kimi-k2-turbo-preview), which supports the native $web_search tool at only $0.005 per call.

5. Verifying Configuration

After configuration, test whether the search functionality is working properly.

5.1 Test via CLI

openclaw configure --section web

This starts an interactive configuration wizard to check the current search status.

5.2 Test in Conversation

Start OpenClaw and ask the agent:

What's the latest version of Node.js?

If configured correctly, the agent will search the web and return the latest info.

5.3 View Logs

openclaw logs --tail 50

Search-related logs will show whether requests were successful.

6. Advanced Configuration

6.1 Timeout and Cache

tools:
  web:
    search:
      timeoutSeconds: 30    # Request timeout 30s
      cacheTtlMinutes: 15  # Cache results for 15m

6.2 Controlling Result Count

tools:
  web:
    search:
      maxResults: 10  # Max 10 results returned

6.3 Disabling Search

If you temporarily don't need search capabilities:

tools:
  web:
    search:
      enabled: false

7. Troubleshooting

Q1: Search returns "No API key configured"

Cause: API Key not configured or environment variables not set correctly.

Solution:

# Confirm environment variable is set
echo $PERPLEXITY_API_KEY

# If empty, set it again
export PERPLEXITY_API_KEY="your-key-here"

Q2: Request Timeout

Cause: Network issues or provider service congestion.

Solution: Increase timeout configuration:

tools:
  web:
    search:
      timeoutSeconds: 60

Q3: Search results are poor

Cause: Different providers have different result styles.

Solution: Try switching providers or increase maxResults for more data.

Q4: Caching Issues

Cause: Old cache preventing results from updating.

Solution: Set cacheTtlMinutes: 0 to disable cache or wait for it to expire.

Q5: Which provider should I choose?

Recommendations:

• Perplexity - Best overall experience, supports structured search; sonar is fast, sonar-pro is for deep research.
• Gemini - High free tier, Google ecosystem, predictable prompt-based billing.
• Brave - Privacy-centric, ~1000 free requests/month; Goggles ranking is a unique advantage.
• Grok - The only choice for real-time X platform content; web + social dual search.
• Kimi - Lowest pricing, 256K context, automatic caching saves significant costs.

Q6: API Key Security

Advice:

• Always use environment variables or secretInputMode: ref.
• Never write API Keys in plain text in config.yaml.
• Rotate API Keys regularly (every 3-6 months).
• Set usage caps in provider dashboards to prevent overspending.

Q7: Grok search error "search_parameters is not a valid field"

Cause: Using the deprecated Live Search API.

Solution: xAI's old search_parameters was deprecated in late 2025. Upgrade to the new Agent Tools API (web_search / x_search). Ensure OpenClaw is updated to the latest version.

Q8: Gemini sometimes doesn't trigger search

Cause: Gemini autonomously decides if it needs the web; it doesn't trigger Google Search Grounding every time.

Solution: This is normal behavior. If you want to force a search, include instructions like "Please search for the latest info." Check the groundingMetadata field in the response to confirm a search occurred.

8. Advanced Directions

• Multi-provider Failover: Automatically switch to a backup provider if the primary one is unavailable.
• Perplexity Domain Whitelisting: Use searchDomainFilter to limit searches to authoritative domains for improved accuracy.
• Brave Goggles Customization: Tailor search rankings for technical docs or academic papers.
• Grok Dual Search: Combine web_search + x_search for a fusion of web and real-time social content.
• Kimi Long Context Search: Use the 256K context to feed massive search results into the model for analysis at once.
• Firecrawl Integration: Pair with web crawling for deep research requiring full webpage reading.
• Cache Optimization: Set reasonable TTLs for high-frequency queries to drastically lower API costs.

---

Further Reading:

• OpenClaw Official Docs - Web Tools
• Perplexity API Documentation
• Brave Search API Documentation
• Gemini Grounding with Google Search
• xAI Grok Live Search Docs
• Moonshot AI Open Platform