openclaw-doc-finder#

OpenClaw 官方文档检索技能。识别用户意图，路由到正确文档，给出精确 URL + 关键命令片段。

检索流程（Pipeline）#

text

用户问题 → 意图识别 → 诊断决策树（可选）→ 文档路由 → 本地片段 → 缓存命中 → 远程拉取 → 回答 → 记录速查

严格顺序，不得跳步：

1. 意图识别：解析用户问题，判断属于哪个场景类别
2. 诊断决策树（可选）：如问题模糊（"任务卡住"、"没有反应"），先用 references/diagnostic-tree.md 引导用户细化
3. 文档路由：查 references/doc-index.md 定位目标文档列表
4. 本地片段优先：检查 references/ 已有片段
5. 缓存命中：检查 references/fetched/<doc-name>.md 是否已有缓存且未过期（7 天内）
6. 远程拉取：本地/缓存均无 → 按"远程拉取规则"拉取，成功后自动缓存
7. 版本检查：回答结尾检查 VERSION
8. 记录速查：将问题与结论追加到 references/doc-lookups.md

---

意图识别规则#

见 references/doc-index.md 的「意图→文档路由表」。优先精确匹配场景关键词。

常见场景映射：

场景目标文档首次安装 / 开始上手start/getting-started.md / start/quickstart.mdgateway 配置 / 配置文件gateway/configuration.mdgateway 配置项详解gateway/configuration-reference.md通道接入（Discord/Telegram/飞书等）channels/index.md + 对应通道文档技能安装 / clawhub / skillhubtools/clawhub 或 start/hubs.md故障排除 / 报错gateway/troubleshooting.md / channels/troubleshooting.md凭证 / secrets / API keygateway/secrets.md模型配置 / 供应商providers/ 目录 + gateway/configuration.mdCLI 命令用法cli/ 目录openclaw doctorgateway/doctor.md安全策略 / 权限gateway/security/ + gateway/sandboxing.md远程访问 / VPS 部署gateway/remote.md + vps.md心跳 / 自动化任务gateway/heartbeat.md + cron-jobs节点配对 / 移动端nodes/ 目录任务阻塞 / 队列 / 并发concepts/queue.md + references/diagnostic-tree.md

---

本地片段优先级#

• references/doc-index.md — 始终可用，路由总表
• references/diagnostic-tree.md — 新增"症状→排查路径"决策树
• references/config-guide.md — gateway 配置高频片段
• references/troubleshoot.md — 常见报错速查
• references/doc-lookups.md — 已查阅问题速查（查阅前优先检查）
• references/fetched/<doc-name>.md — 新增 已缓存的远程文档（7 天有效期）

---

远程拉取规则#

拉取顺序（降级策略）#

当本地和缓存均无目标内容时，按以下顺序尝试：

text

1. web_fetch
   ↓ 失败（Blocked / 网络错误）
2. firecrawl_scrape
   ↓ 失败（Blocked / 超时）
3. exec → curl（最终兜底）
   ↓ 失败
4. 提供手动查询链接

curl 降级命令模板#

bash

# 文档 URL 格式：https://docs.openclaw.ai/<path>
# 用 curl 拉取并提取正文（去除 HTML 标签）
curl -sL "<完整URL>" | python3 -c "
import sys, re
html = sys.stdin.read()
html = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.DOTALL)
html = re.sub(r'<style[^>]*>.*?</style>', '', html, flags=re.DOTALL)
text = re.sub(r'<[^>]+>', ' ', html)
text = re.sub(r'&nbsp;', ' ', text)
text = re.sub(r'\s+', ' ', text).strip()
# 提取核心内容（从第一个段落开始）
idx = text.find('。') if '。' in text else text.find('. ')
if idx > 0: print(text[idx:idx+3000])
"

自动缓存规则#

• 缓存目录： references/fetched/
• 命名规范： <doc-name>.<timestamp>.md>（如 queue.20260405.md）
• 有效期：7 天（自动清理过期缓存）
• 写入时机：远程拉取成功后立即写入

无法拉取时的兜底#

如三种方式均失败，回答格式：

⚠️ 无法自动拉取文档（网络限制）。请手动查看：

• 文档地址： https://docs.openclaw.ai/
• 文档站搜索： https://docs.openclaw.ai/search?q= <关键词>

---

版本管理#

• 版本文件： VERSION（语义化版本，格式 v1.0.0）
• 每次更新 references/ 内容，必须同步更新 VERSION
• 大版本更新（文档 breaking changes）：主版本号 +1，并记录 CHANGELOG

版本同步策略（优化）#

不要 在每次回答前都运行 sync-version.py（开销太大）。

正确做法：

• 技能初始化时检查一次（后台静默执行）
• 用户手动触发： /openclaw_doc_finder_check
• OpenClaw 大版本升级后主动提醒

bash

# 手动触发版本同步（干跑）
python3 scripts/sync-version.py --dry-run

# 执行同步
python3 scripts/sync-version.py

---

输出格式规范#

回答 必须 包含：

1. 文档标题 + 完整 URL（ https://docs.openclaw.ai/<path>）
2. 关键命令（从文档中提取的 CLI 命令，用 ```bash 包裹）
3. 配置片段（关键配置项示例）
4. 版本提示（如已拉取最新内容，提醒技能版本）

当无法拉取时：

text

⚠️ 无法自动拉取文档。请手动查看：
- https://docs.openclaw.ai/<path>

当问题模糊时（先用决策树引导）：

text

在给出具体文档之前，我需要先确认一下：
[引用 diagnostic-tree.md 中的关键问题]

禁止：

• 不带 URL 的泛泛回答
• 混用多个不相关的文档链接

---

速查记录规则#

每次使用本技能查询文档后， 必须 将问题与结论追加到 references/doc-lookups.md：

• 已有相同问题记录 → 更新对应条目而非重复追加
• 新问题 → 在对应分类下按格式追加
• 记录内容：问题、官方结论、相关文档路径、查阅时间
• 这样下次遇到同类问题时可 直接复用，无需重复查阅

---

CHANGELOG#

v1.2.0#

• 新增：远程拉取降级策略（web_fetch → firecrawl → curl）
• 新增：自动缓存机制（references/fetched/，7 天有效期）
• 新增：诊断决策树（references/diagnostic-tree.md）
• 优化：版本同步改为手动触发，不再每次回答前执行
• 新增：无法拉取时的兜底说明

v1.1.0#

• 优化触发条件：增加主条件+排除场景结构
• 提升激活准确性，防止误触发其他专业技能场景