@loxai/ragflow-research

OpenClaw plugin: exposes loxai_ragflow_research (native tool, no exec) against RAGFlow POST /api/v1/retrieval.

Breaking change (0.2.0): the tool id was ragflow_research in 0.1.x; update TOOLS.md, any tools.allow / tools.alsoAllow entries that listed the old name, and saved prompts after upgrading.

0.2.1: ships openclaw-ragflow-research-setup (manual / scripted merge).

0.2.2: npm postinstall runs that logic with --best-effort so a normal openclaw plugins install → npm install pass merges loxai-ragflow-research into tools.alsoAllow when lifecycle scripts run. Set OPENCLAW_RAGFLOW_SKIP_SETUP=1 to disable. If OpenClaw installs with --ignore-scripts, run npx … openclaw-ragflow-research-setup once.

0.2.3: AGENT_INSTALL.md is now a step-by-step OpenClaw install guide (Chinese); minor doc corrections for release.

0.2.4: bin ships openclaw-ragflow-research-setup.js (not .mjs) so npm publish keeps the bin entry — npm strips .mjs bin targets as invalid on publish for some CLI versions.

0.2.5: publishConfig (access: public, explicit registry.npmjs.org); expanded publish troubleshooting — E404 is almost always missing @loxai publish permission, not a broken tarball.

You may rename the npm scope/package later without necessarily changing the agent tool id loxai_ragflow_research.

Plugin id vs tool id (why names differ)

This is intentional OpenClaw layering, not sloppy naming:

| | loxai-ragflow-research | loxai_ragflow_research | | --- | --- | --- | | What it is | Plugin id — stable identity of this extension (openclaw.plugin.json → "id") | Tool id — the callable surface registered for agents | | Where you see it | Plugin list / CLI, plugins.allow, plugins.entries.<…>, often tools.alsoAllow | Chat transcripts, model tool calls, TOOLS.md routing, contracts.tools | | npm package | Related but separate: @loxai/ragflow-research is only the install artifact | Does not need to match the tool id |

So: loxai-ragflow-research = which plugin; loxai_ragflow_research = which tool the model invokes (not “a script filename”, though implementation lives in the plugin bundle). One plugin can expose multiple tools in theory; this one exposes a single tool.

Requirements

• OpenClaw Gateway with compatible plugin API (see package.json → openclaw.compat).
• Node ≥ 18.18.
• RAGFlow instance with API key and at least one dataset UUID.

Install

简明中文安装步骤：AGENT_INSTALL.md。

openclaw plugins install @loxai/ragflow-research

Local path (from this repo):

openclaw plugins install /absolute/path/to/DeepFlow/infra/ragflow-search-skill/packages/ragflow-research

Then openclaw gateway restart (or follow your host’s reload docs).

Automatic tools.alsoAllow (≥ 0.2.2, published npm)

openclaw plugins install does not call OpenClaw hooks for tool policy — but it does run npm install for the package. From 0.2.2 this package defines postinstall, which merges loxai-ragflow-research into tools.alsoAllow (same merge rules as the CLI helper). You must install a build that includes postinstall (publish 0.2.2 and upgrade).

Caveats:

• If npm runs with ignore-scripts, nothing runs — use npx --yes @loxai/ragflow-research openclaw-ragflow-research-setup once.
• openclaw.json must be strict JSON for the script to parse it (JSON5/comments → merge skipped with a warning in postinstall).
• Optional opt-out: OPENCLAW_RAGFLOW_SKIP_SETUP=1 during install.

Easiest: merge tools.alsoAllow (manual helper, ≥ 0.2.1)

OpenClaw core does not patch tools.* when you install npm plugins (upstream discussion). This package adds npm postinstall (≥ 0.2.2) plus the openclaw-ragflow-research-setup CLI when scripts are skipped or merge fails:

# Fallback when postinstall did not run (see caveats above):
npx --yes @loxai/ragflow-research openclaw-ragflow-research-setup
openclaw gateway restart

Manual: tools.alsoAllow / profile (coding)

If you skip the helper, with default tools.profile: "coding" you still need one of:

1. tools.alsoAllow includes loxai-ragflow-research (append if the array already exists).

2. tools.profile: "full".

3. openclaw config patch when alsoAllow is absent (arrays replace on patch — see CLI — config patch).

If plugins.allow is non-empty, it must still include loxai-ragflow-research so the plugin can load (install often adds this for you).

Configure (recommended: ~/.openclaw/.env)

The Gateway loads ~/.openclaw/.env into process.env. Use the same variable names as the exec Skill / ragflow_retrieve.py:

| Variable | Required | Purpose | |----------|----------|---------| | RAGFLOW_BASE_URL | yes | HTTP root, no trailing / | | RAGFLOW_API_KEY | yes | Bearer token | | RAGFLOW_DATASET_IDS | yes* | Comma-separated dataset UUIDs | | RAGFLOW_DATASET_ID | yes* | Single dataset UUID (if RAGFLOW_DATASET_IDS unset) | | RAGFLOW_RETRIEVAL_PATH | no | Default /api/v1/retrieval |

*Or pass datasetIds on each tool call; or set optional plugins.entries.loxai-ragflow-research.config.datasetIds as a fallback.

Example ~/.openclaw/.env:

RAGFLOW_BASE_URL=http://127.0.0.1:9380
RAGFLOW_API_KEY=your-key
RAGFLOW_DATASET_IDS=uuid-one,uuid-two
# optional:
# RAGFLOW_RETRIEVAL_PATH=/api/v1/retrieval

After editing env, openclaw gateway restart.

Optional overrides in openclaw.json

If a key is set in env, it wins. Plugin config can fill gaps only (e.g. base URL / key without touching .env), or supply similarityThreshold, pageSize, timeoutSeconds, insecureTls:

{
  plugins: {
    entries: {
      "loxai-ragflow-research": {
        enabled: true,
        config: {
          similarityThreshold: 0.2,
          pageSize: 30,
          timeoutSeconds: 120,
          insecureTls: false,
        },
      },
    },
  },
}

Install succeeds with an empty config; secrets normally stay out of JSON.

Tool

• loxai_ragflow_research — parameters: question (required); optional datasetIds, similarityThreshold, vectorSimilarityWeight, page, pageSize, topK, keyword, highlight.

Troubleshooting: loxai_ragflow_research missing from the agent tool list

/reset only clears conversation; it does not reload Gateway config or change tool policy.

1. Default tools.profile: "coding" (most common)

Local onboarding often sets tools.profile to coding. That profile allows fixed built-in groups (group:fs, group:runtime, group:web, group:sessions, group:memory, …). Third-party plugin tools are not part of those groups, so loxai_ragflow_research never enters the agent allowlist even though the plugin package is installed and onStartup is true.

Official reference: group:openclaw is “all built-in tools” and excludes provider / npm plugins; see Config — tools.

Confirm: temporarily set:

{
  tools: {
    profile: "full",
  },
}

Run openclaw gateway restart, open a new session, check tools again. If loxai_ragflow_research appears, the blocker was coding (or another restrictive profile).

Operational fixes (pick one; restart Gateway after edits):

• Prefer full only if you accept all tools: "tools": { "profile": "full" }.
• Stay on coding and add plugin tools without replacing the profile — use tools.alsoAllow with the plugin id (confirmed pattern in recent Gateways):

{
  tools: {
    profile: "coding",
    alsoAllow: ["loxai-ragflow-research"],
  },
}

alsoAllow is additive: you keep the usual coding groups and extend them. Some setups also accept the tool id in alsoAllow (e.g. "loxai_ragflow_research"); if one form works and the other does not, prefer the plugin id above.

• Narrow tools.allow alone can behave like a restrictive allowlist (easy to accidentally drop built-ins). Prefer alsoAllow + profile unless you fully understand your merge semantics; see Config — tools.

If policy still blocks tools, fall back to profile: "full" until you align with docs for your exact Gateway version.

Also check tools.byProvider: per-provider allow can narrow tools further.

2. plugins.allow vs tools.allow / tools.profile

These layers are independent:

• plugins.* — which plugins may load. When plugins.allow is already a non-empty list, openclaw plugins install appends the installed plugin id (here loxai-ragflow-research) so the plugin can load at all. That is why you may already see it in openclaw.json without editing by hand. See Plugins — install.
• tools.* — which tool ids / groups reach the agent after plugins register. tools.profile (e.g. coding) and optional tools.allow, tools.alsoAllow, tools.deny are not auto-written by plugin install today. For coding, tools.alsoAllow with the plugin id is often the right additive knob. The manifest field contracts.tools declares tool names for discovery / diagnostics; it does not mutate tools.allow / alsoAllow.

So you cannot, via **openclaw.plugin.json alone, force OpenClaw (current docs) to add loxai_ragflow_research to tools.allow or relax tools.profile on install — that remains operator configuration unless upstream adds an explicit feature.

If plugins.allow is non-empty, it must still include loxai-ragflow-research or the plugin cannot expose tools (even if tools.allow lists them). See also Configuration reference — plugins.

3. Plugin failed at runtime registration

openclaw plugins doctor
openclaw plugins inspect loxai-ragflow-research --runtime
OPENCLAW_PLUGIN_LOAD_DEBUG=1 openclaw gateway run   # or your gateway launch path

Routing: model still prefers web_search

OpenClaw does not choose tools for the model. Even with a strong tool description, many models still default to web_search for factual questions. Treat workspace policy + optional tools.deny as the reliable layer.

A. TOOLS.md in the agent workspace (recommended)

Create or edit ~/.openclaw/workspace/TOOLS.md (paths follow Config — agents) with something like:

## Tool routing (binding)

- For **any** question that might be answered from **our RAGFlow knowledge base** (internal docs, policies, runbooks, product specs we indexed): **always call `loxai_ragflow_research` first** with the user's full question.
- Call **`web_search`** only after `loxai_ragflow_research` returns **no useful chunks**, or the user **explicitly** asks for public internet / live / breaking news / external sites.
- Do **not** skip `loxai_ragflow_research` because the topic "sounds general" — internal KB may still contain the answer.

Restart Gateway or start a new session so bootstrap context picks this up.

B. Deny web_search (forces KB-first behaviour)

If this agent must never hit the public web:

{
  tools: {
    deny: ["web_search"],
  },
}

See Config — tools. To block all web tools: deny group:web (also removes web_fetch, etc.) — only if acceptable.

C. Restrictive tool policy (tools.profile / tools.alsoAllow / tools.allow)

Even when tools.allow is unset, the default tools.profile: "coding" still restricts agents to built-in groups only — plugin tools such as loxai_ragflow_research are not included. Use tools.alsoAllow with loxai-ragflow-research (plugin id) under coding, or see Troubleshooting above.

If you use a non-empty restrictive tools.allow, ensure it includes loxai_ragflow_research (and any other tools you need). Prefer alsoAllow when you only want to extend the profile without replacing it.

D. Plugin versions

≥ 0.2.2 adds npm postinstall to merge loxai-ragflow-research into tools.alsoAllow during npm install (unless scripts skipped / non-JSON config). ≥ 0.2.0 exposes the tool as loxai_ragflow_research (rename from ragflow_research). ≥ 0.1.4 added displaySummary and tighter routing copy; upgrade does not replace (A)–(C).

E. Verify registration

openclaw plugins inspect loxai-ragflow-research --runtime

Look for loxai_ragflow_research in registered tools.

Build / publish

cd packages/ragflow-research
npm install
npm run build
npm publish --access public
# If your npm account has 2FA "auth-and-writes", also pass one-time password:
# npm publish --access public --otp 123456

Publish troubleshooting:

• npm publish removes bin / warns about .mjs: CLI entry must be bin/openclaw-ragflow-research-setup.js. Run npm pkg fix so bin paths normalize (no leading ./). npm pack --dry-run should list that file with no “removed bin” warnings.
• E404 on PUT ... /@loxai/ragflow-research: this is not “package missing from npm” in most cases — npm returns 404 when your logged-in user is not allowed to publish under @loxai. Fix on npmjs.com / account, not in this repo:
  1. npm config get registry → must be https://registry.npmjs.org/ (not a company mirror without publish rights).
  2. npm whoami → must be the npm user that owns / was invited to @loxai.
  3. npm owner ls @loxai/ragflow-research → your user must appear; otherwise ask an @loxai org Owner to invite you as Developer (or transfer maintenance).
  4. Granular access tokens: tokens marked read-only cannot publish — create a token with publish permission for that scope / package.
  5. 2FA: enable auth-and-writes → every npm publish needs --otp once per publish.

本地自检 tarball：npm pack --dry-run、npm publish --dry-run --access public（均应成功且无 bin 警告）。

Legacy exec Skill

The sibling SKILL.md + scripts/ragflow_retrieve.py under infra/ragflow-search-skill remains an exec-based fallback.