Claw Wiki

核心用途

claw-wiki 是一个面向 OpenClaw 产品的本地文档知识库技能。其核心功能是提供离线的、可验证的产品文档查询能力，覆盖部署配置、CLI 命令、网关行为、通道机制、工具使用及故障排查等场景。同时支持在显式请求时刷新本地快照，与上游文档保持同步。

显著优点

权威性与可验证性

• 所有回答严格基于本地 openclaw_docs/ 快照，而非模型记忆，确保信息可追溯、可验证
• 响应中明确标注引用的文件路径，便于用户快速核查原文
• 支持版本溯源：通过 state/source-lock.json 提供当前快照的 commit、ref 及同步时间

高效的检索策略

• 采用分层路由机制：routing-cheatsheet.md 处理宽泛意图 → query-examples.md 优化弱关键词 → rg 精准搜索
• 优先文件名匹配，再扩展至内容，避免全树遍历的性能损耗
• 对超大文件支持段落级跳转，兼顾速度与上下文完整性

可控的更新机制

• 支持显式刷新：sync_docs.py → validate_docs.py → build_knowledge.py → diff_docs.py 的确定性流水线
• 更新范围清晰：仅读取上游（local checkout 或 git fetch/clone），禁止写操作（无 push、无 PR、无上传）

潜在局限

内容时效性约束

• 本地快照非实时同步，用户需主动请求更新才能获取最新文档
• 对于"最新"特性询问，必须显式声明快照版本，避免误导

语言覆盖局限

• 仅保证英文文档集的可用性；docs.json 中的本地化导航条目可能存在但未经完整验证

查询依赖用户意图清晰度

• 若用户意图模糊且关键词薄弱，需依赖 routing-cheatsheet.md 和 query-examples.md 的启发式路由，存在一定理解偏差风险

适合人群

• OpenClaw 运维/开发工程师：需要快速查询部署配置、CLI 用法、网关行为
• 技术支持人员：处理故障排查、诊断指南、安全策略相关咨询
• 产品集成者：了解通道、提供商、插件、节点等集成机制
• 文档维护者：需要定期同步上游文档变更的自动化场景

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 信息过时 | 本地快照可能滞后于上游 | 响应中强制声明快照版本；用户要求"最新"时触发更新流程 |

| 幻觉生成 | 模型可能编造不存在的参数或命令 | 严格禁止发明未在文档中出现的 flags、defaults、config keys |

| 权限越界 | 误执行写操作至上游仓库 | 明确禁止 `git push`、PR 创建、上传 skill 文件夹 |

| 搜索遗漏 | 宽泛查询导致关键文档未命中 | 采用"文件名→内容→扩大范围"的渐进式搜索策略 |

| 本地化误导 | 非英文文档内容准确性未验证 | 优先使用英文文档集，非英文内容需显式声明验证状态 |

核心用法

Claw Wiki 是一款面向 OpenClaw 产品的本地化文档查询技能。其核心工作流程分为两大模式：

文档查询模式：当用户询问 OpenClaw 的功能用法、部署配置、CLI 命令或故障排查时，Skill 从本地 openclaw_docs/ 目录的快照中检索信息，通过 rg 文本搜索快速定位相关文件，读取 1-3 个最匹配的文档后合成答案，并标注引用的文件路径供用户核验。

快照维护模式：当用户明确要求"更新文档""检查是否过时"或"同步最新版本"时，Skill 读取 state/source-lock.json 确认当前快照版本，随后执行脚本化流程：sync_docs.py 从上游仓库拉取最新文档、validate_docs.py 验证文档结构、build_knowledge.py 重建索引、diff_docs.py 生成变更摘要，最终向用户报告同步结果。

路由策略上，Skill 内置智能目录映射（如安装问题导向 install/、CLI 问题导向 cli/、安全问题导向 security/），并辅以 references/routing-cheatsheet.md 和 query-examples.md 优化查询效率。

显著优点

1. 离线可用性：本地快照设计确保无需实时网络连接即可响应绝大多数产品问题，查询延迟极低。
2. 信息权威性：所有内容源自 OpenClaw 官方仓库（github.com/openclaw/openclaw），避免记忆幻觉和过时信息，每个答案均可溯源到具体文件路径。
3. 零依赖安全架构：仅使用 Python 标准库，无第三方依赖包，彻底规避供应链攻击风险。
4. 只读安全模型：网络操作仅限于 git clone/fetch 单向拉取，无数据上传、无远程写入、无敏感信息外泄。
5. 确定性更新流程：文档同步通过脚本化工作流完成，版本锁定在 source-lock.json 中，可验证、可回滚。

潜在缺点与局限性

1. 时效性滞后：本地快照非实时同步，若用户未主动触发更新，可能基于过时版本作答；Skill 明确标注快照日期，但用户可能忽略 freshness 提示。
2. 英语内容优先：兼容性目标仅为英文文档，其他语言版本的导航条目虽可能存在，但验证不保证其可用性，非英语用户可能体验受限。
3. 搜索精度依赖：rg 文本搜索对查询词质量敏感，模糊或宽泛的问题可能需多次迭代才能定位准确文档。
4. 维护成本：Skill 作者需持续跟踪上游 OpenClaw 文档的架构变更（如目录重组、文件重命名），否则路由映射可能失效。

适合的目标群体

• OpenClaw 运维工程师：需要快速查询部署配置、网关行为、故障排查指南。
• 平台集成开发者：查阅 CLI 命令、Provider/Channel 集成文档、API 行为定义。
• 企业内训师与技术支持：基于官方文档构建内部知识库，确保回答口径一致。
• 离线环境用户：处于网络受限或隔离环境中的 OpenClaw 使用者。

常规使用风险

1. subprocess 调用风险：sync_docs.py 使用 subprocess.run 执行 git 命令，虽参数由内部构造且仅为只读操作，但属潜在攻击面；当前实现已做输入隔离，风险可控。
2. 文件系统写操作：同步流程涉及 shutil.rmtree/copytree 等目录操作，虽限制在 Skill 目录内，但异常中断可能导致快照损坏，建议依赖 validate_docs.py 进行完整性校验。
3. 上游仓库可用性：文档同步依赖 GitHub 网络可达性，企业内网部署时需配置代理或镜像。
4. 无内容签名验证：当前版本未对拉取的文档进行哈希签名验证，极端场景下存在上游仓库被篡改后污染本地快照的理论风险（依赖 Git 本身的完整性校验）。