English | 中文

RAGFlow Kit

RAGFlow Knowledge Base Retrieval Plugin for OpenClaw

Overview

RAGFlow Kit is an OpenClaw plugin that enables agents to search, upload, and delete documents in RAGFlow knowledge bases through natural language queries. It supports per-agent and per-team access control with fine-grained permissions.

Features

• Knowledge Base Search — Query RAGFlow knowledge bases using natural language
• Document Upload — Upload text files to knowledge bases with auto-parsing
• Document Delete — Delete documents from knowledge bases
• Access Control — Configure which agents can search / upload / delete on which knowledge bases
• Team Support — Manage knowledge base permissions by teams
• Similarity Filtering — Filter search results by minimum similarity threshold
• Hot Reload — Configuration changes take effect without restarting OpenClaw

Tools

Installation

As npm package

npm install ragflow-kit

As OpenClaw plugin (from source)

# Clone the repo
git clone https://github.com/YOUR_USERNAME/ragflow-kit.git
cd ragflow-kit

# Install dependencies
npm install

# Build
npm run build

# Copy to OpenClaw plugins directory
cp -r dist ~/.openclaw/plugins/ragflow-kit

Configuration

Edit your OpenClaw configuration file (openclaw.json):

{
  "plugins": {
    "entries": {
      "ragflow-kit": {
        "enabled": true,
        "config": {
          "ragflow": {
            "api_url": "https://your-ragflow-server.com",
            "api_key": "your-api-key-here"
          },
          "retrieval": {
            "chunk_size": 6,
            "min_similarity": 0.6
          },
          "access": {
            "agents": {
              "main": {
                "search_kbs": ["kb_name_1"],
                "upload_kbs": ["kb_name_1"],
                "delete_kbs": ["kb_name_1"]
              }
            },
            "teams": {
              "team_alpha": {
                "search_agents": ["agent_id_1", "agent_id_2"],
                "search_kbs": ["shared_kb"],
                "upload_agents": ["agent_id_1"],
                "upload_kbs": ["shared_kb"],
                "delete_agents": [],
                "delete_kbs": []
              }
            }
          }
        }
      }
    }
  }
}

Configuration Reference

ragflow — RAGFlow connection

retrieval — Search behavior

access — Permission control

AgentAccess structure:

{
  search_kbs: string[];   // KB names/IDs this agent can search
  upload_kbs: string[];    // KB names/IDs this agent can upload to
  delete_kbs: string[];   // KB names/IDs this agent can delete from
}

TeamAccess structure:

{
  search_agents: string[];  // Agent IDs in this team (for search)
  search_kbs: string[];     // KB names/IDs this team can search
  upload_agents: string[]; // Agent IDs in this team (for upload)
  upload_kbs: string[];    // KB names/IDs this team can upload
  delete_agents: string[];// Agent IDs in this team (for delete)
  delete_kbs: string[];    // KB names/IDs this team can delete
}

Usage

rag_search

Search for relevant documents in configured knowledge bases.

Parameters:

Example:

{
  "tool": "rag_search",
  "params": {
    "query": "What is the company policy on remote work?"
  }
}

Response format:

{
  "content": [{
    "type": "text",
    "text": "{...JSON with chunks...}\n\n[Provenance Requirements]\nYou must cite sources using [X] format..."
  }]
}

rag_upload

Upload a text file to a knowledge base. Triggers parsing automatically.

Parameters:

Example:

{
  "tool": "rag_upload",
  "params": {
    "kb_name": "company-policies",
    "file_name": "remote-work.txt",
    "file_content": "Remote work policy content here..."
  }
}

Without parameters — lists all available knowledge bases for the agent.

rag_delete

Delete a document from a knowledge base.

Parameters:

Example:

{
  "tool": "rag_delete",
  "params": {
    "kb_name": "company-policies",
    "document_id": "doc-xxx-123"
  }
}

File Structure

ragflow-kit/
├── src/
│   ├── index.ts           # Plugin entry, registers three tools
│   ├── modules/
│   │   ├── auth.ts        # RAGFlowClient HTTP client
│   │   ├── query.ts       # Search logic, permissions, KB resolver
│   │   ├── upload.ts      # Upload & delete file operations
│   │   └── config.ts      # Config loading & hot reload
│   ├── config/
│   │   └── schema.ts      # Default values & validation
│   ├── types/
│   │   └── index.ts       # TypeScript type definitions
│   └── utils/
│       └── index.ts       # normalizeUrl, buildResultText, etc.
├── dist/                  # Compiled JavaScript (published to npm)
├── openclaw.plugin.json   # Plugin manifest
├── package.json
├── tsconfig.json
└── README.md

Architecture Notes

KB Name → ID Resolution

Knowledge base names are resolved to IDs lazily on first use and cached (max 100 entries). The cache is cleared when api_url, api_key, or access credentials change.

Hot Reload

Config is reloaded on every tool call (not at startup). If the config file is modified, changes take effect on the next tool call without restarting OpenClaw.

Permission Merging

Agent-level and team-level permissions are merged. A KB is accessible if any permission source grants access (union, not intersection).

License

MIT License