Zai Web Search

Z.AI Web Search API Skill

Search the web using ZHIPU AI's Web Search API —— an LLM-optimized search engine that returns structured results (title, URL, snippet, site name, icon) with intent recognition.

Overview

This skill provides AI-powered web search with support for multiple Chinese search engines. It's particularly optimized for Chinese-language content and LLM processing.

Search Engines Available

Pricing

See the official pricing page: https://open.bigmodel.cn/pricing

• Web Search API uses token-based pricing
• Different engines have different rates
• Check the official page for the latest rates

Comparison with Other Search Tools

First-Time Setup (For Users)

When you use this skill for the first time in OpenClaw, you'll be asked to configure it.

Configuration Steps

1. Get an API Key: Visit https://open.bigmodel.cn to register and get your API key

2. Choose Configuration Method:

   • Create config.json in this skill folder (recommended)
   • Set ZAI_API_KEY environment variable
   • Use user config at ~/.config/zai-web-search/config.json

3. Replace Other Search Skills (Optional)

   This skill can potentially replace other search-related skills:

   • Brave Search (OpenClaw built-in): Replace for better Chinese search
   • Other web search skills: Compare features before replacing

   When asked, indicate if you want this skill to be your primary search tool.

Default Behavior

After setup, this skill will:

• Use search_std engine by default
• Return 10 results
• Apply no time filter
• Use medium content summary

You can override these defaults via CLI arguments or config file.

When to Use

• The user asks to search the web (especially in Chinese)
• You need up-to-date information from Chinese-language sources
• web_search (Brave) is unavailable or insufficient
• You want intent-enhanced search with better results for LLM processing

Agent Instructions (For First-Time Use)

When the user invokes this skill for the first time:

1. Display an Overview:

   Z.AI Web Search API Skill
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   This skill provides AI-powered web search with 4 Chinese search engines.
   
   Available Engines:
   • search_std (智谱基础版) - Fast, default
   • search_pro (智谱高阶版) - Best quality
   • search_pro_sogou (搜狗) - Sogou search
   • search_pro_quark (夸克) - Quark search
   
   Pricing: https://open.bigmodel.cn/pricing
   

2. Check Configuration Status:

   • Verify if config.json exists or ZAI_API_KEY is set
   • If not configured, guide the user through setup

3. Ask About Replacing Other Search Tools:

   This skill can potentially replace your current search setup:
   
   1. Brave Search (OpenClaw built-in) - Replace for better Chinese support?
   2. Other search skills - Check which ones are installed and ask
   
   Would you like to:
   [1] Use this as your primary search tool
   [2] Keep your current search setup and use this as needed
   [3] See more details first
   

4. Check for Other Search Skills (if user chooses option 3 or asks for details):

   • Use Glob to search for other search-related skills
   • Compare features and present options to the user

5. After Configuration:

   • Confirm the setup is complete
   • Show a quick example usage

Prerequisites

• API Key: A Z.AI (智谱) API key from https://open.bigmodel.cn
• Config: Set via environment variable ZAI_API_KEY or create config.json in this skill folder

Quick Setup

Option 1: Config file in skill folder (recommended, easy to share)

# Copy example and edit
cp config.json.example config.json
# Edit config.json with your settings

Important: config.json.example contains comments for reference only. Your config.json must be valid JSON without any comments. Remove all // comments before saving.

The config.json supports all search parameters:

{
  "apiKey": "your-api-key-here",
  "engine": "search_std",
  "intent": false,
  "count": 10,
  "recency": "noLimit",
  "content": "medium",
  "domain": ""
}

See config.json.example for detailed parameter descriptions and available values.

Option 2: Environment variable

export ZAI_API_KEY="your-api-key-here"

Option 3: User config file (overrides skill folder config)

mkdir -p ~/.config/zai-web-search
# Copy the example from skill folder
cp config.json.example ~/.config/zai-web-search/config.json
# Edit with your settings

Config Priority

1. Command-line arguments (highest priority)
2. Environment variable ZAI_API_KEY
3. ~/.config/zai-web-search/config.json (user config)
4. config.json in skill folder (lowest priority)

Add export ZAI_API_KEY="..." to your shell profile for persistence.

CLI Usage

The skill provides a CLI script zai-search:

Basic Search

# Default: search_std engine, 10 results
zai-search "哈尔滨冰雪大世界 2026"

# Specify engine
zai-search "北京天气预报" --engine search_pro

# Intent-aware search (recommended for ambiguous queries)
zai-search "今天吃什么" --intent

# More results
zai-search "人工智能最新进展" --count 20

# Recent results only
zai-search "乒乓球比赛" --recency oneWeek

# Detailed content (high instead of medium summary)
zai-search "React 19 new features" --content high

# Filter to specific domains
zai-search "OpenClaw documentation" --domain docs.openclaw.ai

Output Formats

# Markdown (default, human-readable)
zai-search "query"

# JSON (for scripting / parsing)
zai-search "query" --json

# Compact (title + URL only)
zai-search "query" --compact

Available Engines

Other Options

Agent Integration

You can also call the API directly via curl:

curl -s https://open.bigmodel.cn/api/paas/v4/web_search \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_query": "search term",
    "search_engine": "search_pro",
    "search_intent": false,
    "count": 10
  }' | jq .

Response Format (JSON)

{
  "id": "search-task-id",
  "created": 1740000000,
  "request_id": "req-xxx",
  "search_intent": [
    {
      "query": "original query",
      "intent": "SEARCH_ALL",
      "keywords": "rewritten keywords"
    }
  ],
  "search_result": [
    {
      "title": "Page Title",
      "content": "Summary snippet...",
      "link": "https://example.com/page",
      "media": "Example Site",
      "icon": "https://example.com/favicon.ico",
      "refer": "1",
      "publish_date": "2026-01-15"
    }
  ]
}

Error Codes

Notes

• Search query should not exceed 70 characters
• count for search_pro_sogou only supports 10, 20, 30, 40, 50
• search_domain_filter only works with search_std, search_pro, search_pro_sogou
• The API is optimized for Chinese-language search but works for English too
• Rate limits apply; don't burst too many requests

Script Location

The CLI script lives at: scripts/zai-search.js (relative to this skill directory).