@qzhike/agent-search

OpenClaw 插件：为 Agent 提供 原生工具 qzhike_search（多后端检索 + RAGFlow/LightRAG 知识库）与 qzhike_search_fetch（按 resultId 取完整 sourceText）。安装后随包加载 Skill qzhike-agent-search，指导工具路由与编排。

工具

| 工具 | 用途 | |---|---| | qzhike_search | 知识库（RAGFlow）+ 公网搜索；返回瘦 results[]（finalSummary、refId、resultId、appendix） | | qzhike_search_fetch | resultId → 缓存中的完整 snippet 与元数据 |

配置路径：plugins.entries.qzhike-agent-search.config（OpenClaw 解析 ${ENV}；插件不读 process.env）。

安装

openclaw plugins install @qzhike/agent-search
openclaw gateway restart
openclaw plugins inspect qzhike-agent-search --runtime --json

tools.alsoAllow（自动）：openclaw plugins install 会触发包的 npm postinstall，将插件 id 与三个工具名合并进 ~/.openclaw/openclaw.json 的 tools.alsoAllow（与 @loxai/ragflow-research 同类）。若 npm 使用 --ignore-scripts，手动执行一次：

npx --yes @qzhike/agent-search openclaw-qzhike-agent-search-setup
openclaw gateway restart

跳过自动合并：OPENCLAW_QZHIKE_SKIP_SETUP=1。openclaw.json 须为严格 JSON（JSON5/注释会导致 merge 跳过并告警）。

本地路径（开发）：

openclaw plugins install --link /absolute/path/to/qzhike-agent-search

OpenClaw 配置

searchMode：fallback 与 concurrent

| 模式 | 行为 | |---|---| | fallback（默认） | 按 fallback 数组顺序线性尝试，首个有有效结果的 provider 胜出 | | concurrent | 按 concurrent 列表 全部 并行调用（去重），合并结果 |

可同时保留 fallback 与 concurrent 数组以便切换 searchMode（可选）；下方示例各只展示该模式所需字段。单次 qzhike_search 仍可用参数 searchMode / provider 覆盖 config。

fallback 模式（串行）

{
  plugins: {
    allow: ["qzhike-agent-search"],
    entries: {
      "qzhike-agent-search": {
        enabled: true,
        config: {
          searchMode: "fallback",
          fallback: ["ragflow", "searxng", "brave", "tavily"],
          providers: {
            ragflow: {
              auth: "deeproute",
              baseUrl: "${DEEPROUTE_API_DOMAIN}",
              apiKey: "${DEEPROUTE_API_KEY}",
            },
            brave: {
              auth: "deeproute",
              baseUrl: "${DEEPROUTE_API_DOMAIN}",
              apiKey: "${DEEPROUTE_API_KEY}",
            },
          },
        },
      },
    },
  },
  tools: {
    alsoAllow: [
      "qzhike-agent-search",
      "qzhike_search",
      "qzhike_search_fetch",
    ],
  },
}

concurrent 模式（并行）

与 fallback 共用 providers 与 .env；将 searchMode 改为 "concurrent"，并配置 concurrent 列表（所列 provider 全部并行）：

{
  plugins: {
    allow: ["qzhike-agent-search"],
    entries: {
      "qzhike-agent-search": {
        enabled: true,
        config: {
          searchMode: "concurrent",
          concurrent: ["ragflow", "kimi", "brave"],
          providers: {
            ragflow: {
              auth: "deeproute",
              baseUrl: "${DEEPROUTE_API_DOMAIN}",
              apiKey: "${DEEPROUTE_API_KEY}",
            },
            kimi: {
              baseUrl: "${DEEPROUTE_API_ENDPOINT}",
              apiKey: "${DEEPROUTE_API_KEY}",
              model: "kimi-k2.6",
            },
            brave: {
              auth: "deeproute",
              baseUrl: "${DEEPROUTE_API_DOMAIN}",
              apiKey: "${DEEPROUTE_API_KEY}",
            },
            tavily: {
              auth: "deeproute",
              baseUrl: "${DEEPROUTE_API_DOMAIN}",
              apiKey: "${DEEPROUTE_API_KEY}",
            },
          },
        },
      },
    },
  },
  tools: {
    alsoAllow: [
      "qzhike-agent-search",
      "qzhike_search",
      "qzhike_search_fetch",
    ],
  },
}

合并进现有 openclaw.json 时勿整文件覆盖（保留 models 等大模型配置）。若已有 tools.profile（如 coding），保留 profile，用 tools.alsoAllow 追加插件与工具名（安装时通常已自动合并）。勿用窄 tools.allow 覆盖 profile；勿配置 tools.deny: ["web_search"] — 检索优先 qzhike_search 由 workspace/TOOLS.md 约束。

大模型块（与插件无关但共用 env）：models.providers.deeproute.baseUrl 与 agents.defaults.memorySearch.remote.baseUrl 建议同为 "${DEEPROUTE_API_ENDPOINT}"（勿把 /api/v1 写进 DEEPROUTE_API_DOMAIN）。

在 ~/.openclaw/.env 中设置占位符（推荐拆成 domain / endpoint）：

DEEPROUTE_API_DOMAIN=http://<console-host>:20316
DEEPROUTE_API_ENDPOINT=http://<console-host>:20316/api/v1
DEEPROUTE_API_KEY=sk-...

baseUrl 约定（插值后由插件使用）：

| Provider | openclaw.json 中 baseUrl | |---|---| | auth: "deeproute"（ragflow、brave、…） | "${DEEPROUTE_API_DOMAIN}" → Console /api/mirror/{provider}/… | | kimi（无 auth，不走 mirror） | "${DEEPROUTE_API_ENDPOINT}" → /api/v1/chat/completions |

更完整的 DeepRoute 全 provider 模板见开源仓库 examples/openclaw.config.json5（npm 包内不含该文件）。

DeepRoute 扩展服务（凭据托管）

插件 auth: "deeproute" 时，只需 Console origin + user sk；厂商 Key、RAGFlow dataset_ids、SearXNG Base URL 等在 Console 扩展服务入库。

| 插件 provider | Console 扩展服务键 | |---|---| | ragflow | ragflow_base_url、ragflow、ragflow_dataset_ids | | searxng | searxng | | brave / tavily / serper / metaso / zai / exa / jina / minimax | 同名键 | | kimi | 不走 mirror；baseUrl: ${DEEPROUTE_API_ENDPOINT} + 同一 user sk |

Bundled Skill

本包含 skills/qzhike-agent-search/SKILL.md，在 openclaw.plugin.json 中声明；启用插件并 restart Gateway 后自动加载，一般无需再 symlink 到 ~/.openclaw/skills/。

Skill 约定：

• 检索类问题优先 qzhike_search（组织内文档 → 将 ragflow 放在 fallback 前列）
• 需命中条目全文 → qzhike_search_fetch({ resultId })
• 检索类问题第一条工具必须是 qzhike_search，勿先调内置 web_search（软约束，见 Skill / workspace/TOOLS.md）

可在 ~/.openclaw/workspace/TOOLS.md 中强化路由（复制仓库 examples/workspace-TOOLS.md）。

工具 API（摘要）

qzhike_search

| 参数 | 说明 | |---|---| | query | 必填，检索词 | | searchMode | 可选，fallback / concurrent | | provider | 可选，强制单一 backend |

响应要点：工具返回文本 + details。results[] 含 refId、citation、finalSummary（无 title/url）；顶层 appendixPaste / appendix.fullSection 为已编号 Markdown 链接附录（优先从 ## APPENDIX 文本块逐字粘贴）。条数由 config perProviderFetchCount / maxMergedResults 控制。

RAGFlow / LightRAG 命中：分块 URI（ragflow://… / lightrag://…）在 appendix.items[].line 的链接目标中；附录原样保留。需 chunk 全文 → qzhike_search_fetch({ resultId })。

排错

| 现象 | 检查 | |---|---| | 工具未出现 | plugins.allow 含 qzhike-agent-search；运行 openclaw-qzhike-agent-search-setup 或检查 tools.alsoAllow 含插件 id + 两个工具名 | | alsoAllow 未合并 | openclaw.json 是否为严格 JSON；npm 是否 --ignore-scripts；手动运行 setup CLI | | provider 被跳过 | plugins.entries.qzhike-agent-search.config.providers.* 是否配齐 | | RAGFlow 无结果 | Console 扩展服务 ragflow_*；deeproute 下勿在插件 config 写 dataset_ids | | 改配置不生效 | openclaw gateway restart 并新开会话 |

要求

• Node >= 22
• OpenClaw >= 2026.5.12（definePluginEntry + api.registerTool）

License

MIT