Kagi Search Plugin for OpenClaw

Web search via Kagi Search API for OpenClaw.

Features

• Structured results — Returns titles, URLs, snippets, and publication dates
• Balance monitoring — Warns when balance is low, blocks searches when critically low
• Account personalization — Results inherit your Kagi account's blocked/promoted sites
• Related searches — Optionally include Kagi's related search suggestions

Requirements

• OpenClaw >= 2026.1.0
• Kagi Search API access (request at [email protected])

Installation

Option 1: Clone to extensions directory

git clone https://github.com/nullvariable/openclaw-kagi-search.git ~/.openclaw/extensions/kagi-search

Option 2: Via OpenClaw plugins (coming soon)

openclaw plugins install @nullvariable/openclaw-kagi-search

Configuration

Add to your OpenClaw config (~/.openclaw/openclaw.json or ~/.config/openclaw/config.json5):

{
  plugins: {
    entries: {
      "kagi-search": {
        enabled: true,
        config: {
          // Required: Get your API key from https://kagi.com/settings/api
          apiKey: "your-kagi-api-key",
          
          // Optional settings
          maxResults: 10,           // Default results per search (1-50)
          timeoutMs: 30000,         // Request timeout in ms
          
          // Balance monitoring thresholds
          balance: {
            warnThreshold: 1.00,    // Log warning when balance < $1.00
            blockThreshold: 0.25,   // Block searches when balance < $0.25
          },
          
          // Include related search suggestions in results
          includeRelatedSearches: false,
        },
      },
    },
  },
}

Environment Variable

Alternatively, set the API key via environment variable:

export KAGI_API_KEY="your-kagi-api-key"

Usage

The plugin registers a kagi_search tool that agents can use:

Search using kagi_search for "OpenClaw documentation"

Tool Parameters

| Parameter | Type | Required | Description | |-----------|---------|----------|------------------------------------------| | query | string | Yes | Search query | | limit | integer | No | Max results (1-50, default from config) |

Response Format

{
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "snippet": "Result snippet text...",
      "published": "2024-09-30T00:00:00Z"
    }
  ],
  "relatedSearches": ["related term 1", "related term 2"],
  "meta": {
    "balance": 9.975,
    "queryTimeMs": 213,
    "resultCount": 5
  }
}

Balance Monitoring

The plugin tracks your Kagi API balance and provides two thresholds:

| Threshold | Default | Behavior | |-----------|---------|----------| | warnThreshold | $1.00 | Logs a warning when balance drops below | | blockThreshold | $0.25 | Blocks all searches until balance is replenished |

Balance is updated after each search from the API response metadata.

Account Personalization

Kagi Search API results inherit your account settings:

• Blocked sites — Sites you've blocked won't appear in results
• Promoted sites — Sites you've promoted will be prioritized
• Snippet length — Configurable under Kagi Settings → Search

This is intentional — your agent's searches reflect your preferences. See Kagi Personalization for more details.

Pricing

Kagi Search API costs $0.025 per query ($25 per 1,000 searches).

• Check your balance: https://kagi.com/settings/api
• API documentation: https://help.kagi.com/kagi/api/search.html

Comparison with Other Search Providers

| Feature | Brave | Perplexity | Kagi | |----------------------|-------------|-------------|--------------| | Result type | Structured | AI-synth | Structured | | Free tier | Yes | No | No | | Pricing | Pay-per-use | Pay-per-use | $0.025/query | | Personalization | No | No | Yes | | Related searches | No | No | Yes |

Documentation

• Kagi Search API Documentation
• Kagi API Authentication
• Kagi API Settings
• OpenClaw Plugin Documentation

License

MIT © Doug Cone