Dify Knowledge Base Search Skill

🔍 Search your Dify Knowledge Base to get accurate, contextual answers

This skill enables AI agents to query Dify datasets for RAG (Retrieval-Augmented Generation) context retrieval. Perfect for knowledge base Q&A, documentation search, and contextual AI responses.

✨ Features

• List Knowledge Bases - Discover all available Dify datasets
• Smart Search - Query datasets with hybrid, semantic, or keyword search
• Auto-Discovery - Automatically find available datasets if ID not provided
• Configurable Results - Adjust top-k, search method, and reranking
• Error Handling - Graceful error messages for debugging
• Zero Hardcoding - All configuration via environment variables

🚀 Quick Start

1. Configure Environment Variables

Set up in openclaw.json:

{
  "env": {
    "vars": {
      "DIFY_API_KEY": "${DIFY_API_KEY}",
      "DIFY_BASE_URL": "https://dify.example.com/v1"
    }
  }
}

Environment Variables:

Variable	Required	Default	Description
DIFY_API_KEY	✅ Yes	-	Your Dify API Key (from Settings → API)
DIFY_BASE_URL	❌ No	http://localhost/v1	Your Dify instance base URL

2. Install Dependencies

pip3 install requests

🛠️ Tools

dify_list

Lists all available knowledge bases (datasets) in your Dify instance.

Invocation: dify_list tool

Example Response:

{
  "status": "success",
  "count": 2,
  "datasets": [
    {
      "id": "dataset-abc123",
      "name": "Product Documentation",
      "doc_count": 42,
      "description": "All product guides and tutorials"
    },
    {
      "id": "dataset-xyz789",
      "name": "API Reference",
      "doc_count": 156,
      "description": "REST API documentation"
    }
  ]
}

Usage:

{}

dify_search

Searches a Dify Dataset for relevant context chunks.

Invocation: dify_search tool (mapped to python3 scripts/search.py)

Parameters:

Parameter	Type	Required	Default	Description
query	string	✅ Yes	-	Search query or question
dataset_id	string	❌ No	Auto-discover	Specific dataset ID to search
top_k	integer	❌ No	3	Number of results to return
search_method	string	❌ No	hybrid_search	Search strategy
reranking_enable	boolean	❌ No	false	Enable reranking for better results

Search Methods:

• hybrid_search - Combine semantic + keyword search (recommended)
• semantic_search - Meaning-based similarity search
• keyword_search - Exact keyword matching

Example Usage:

{
  "query": "How do I configure OpenClaw?",
  "top_k": 5
}

{
  "query": "API authentication methods",
  "dataset_id": "dataset-xyz789",
  "search_method": "semantic_search",
  "reranking_enable": true
}

Example Response:

{
  "status": "success",
  "query": "How do I configure OpenClaw?",
  "dataset_id": "dataset-abc123",
  "count": 3,
  "results": [
    {
      "content": "To configure OpenClaw, edit the openclaw.json file...",
      "score": 0.8923,
      "title": "Installation Guide",
      "document_id": "doc-001"
    },
    {
      "content": "OpenClaw supports environment variables via...",
      "score": 0.8451,
      "title": "Configuration Options",
      "document_id": "doc-002"
    }
  ]
}

📋 Complete Workflow Example

[
  {
    "tool": "dify_list",
    "parameters": {}
  },
  {
    "tool": "dify_search",
    "parameters": {
      "query": "What are the system requirements?",
      "top_k": 5,
      "search_method": "hybrid_search"
    }
  }
]

🔧 Troubleshooting

Common Errors

Error	Solution
Missing DIFY_API_KEY	Set DIFY_API_KEY in environment variables
Connection refused	Check DIFY_BASE_URL is correct and accessible
No datasets found	Verify dataset exists in your Dify workspace
API request failed	Check network connectivity and API key permissions

Debug Mode

Run manually to see detailed errors:

DIFY_API_KEY=your-key python3 scripts/search.py <<< '{"query":"test"}'

📚 Integration Tips

RAG Pipeline Integration

# Example: Use search results in AI response
results = dify_search(query, top_k=5)
context = "\n".join([r["content"] for r in results["results"]])
final_prompt = f"Answer based on context:\n\n{context}\n\nQuestion: {query}"

Multiple Datasets

For searching across multiple datasets, loop through them:

{
  "query": "Find information about authentication",
  "dataset_id": "dataset-api-docs"
}

Then query another dataset separately.

🔒 Security

• Never commit API keys - Use environment variables or .env files
• Rotate keys regularly - Generate new keys in Dify Settings
• Restrict access - Limit API key permissions where possible

📖 Implementation Details

This skill uses the Dify Dataset API:

• List Datasets: GET /v1/datasets
• Search: POST /v1/datasets/{id}/retrieve

For API documentation, see: https://docs.dify.ai/reference/api-reference

📝 Changelog

v1.1.0 (2026-02-08):

• ✅ Added search method selection (hybrid/semantic/keyword)
• ✅ Added reranking support
• ✅ Auto-discovery of datasets
• ✅ Improved error handling
• ✅ Removed hardcoded URLs (fully configurable)
• ✅ Added detailed logging

v1.0.0 (2026-02-06):

• Initial release
• Basic list and search functionality