Claw Wiki

核心功能

claw-wiki 是一款面向 OpenClaw 产品的本地化文档检索与维护技能。其核心能力包括：

1. 离线文档查询：基于本地 openclaw_docs/ 目录的 Markdown 源文档，通过结构化索引（docs-manifest.json、topic-index.json）实现快速全文检索，覆盖安装部署、平台适配、运行时模型、CLI 命令、通道配置、安全策略等完整产品知识体系。

2. 智能路由导航：内置 routing-cheatsheet.md 和 query-examples.md，针对模糊意图自动映射到最佳文档路径（如安装问题→start//install/，故障排查→help//diagnostics/）。

3. 文档版本管理：通过 source-lock.json 锁定上游来源、分支、提交哈希及同步时间戳，明确告知用户本地快照的新鲜度；支持通过脚本化工作流（sync_docs.py → validate_docs.py → build_knowledge.py → diff_docs.py）按需拉取上游更新并生成变更摘要 latest-diff.md。

显著优势

• 确定性可重复：本地快照避免了远程文档的实时变动，确保答案的一致性与可追溯性，特别适合 CI/CD 环境或合规场景。
• 低延迟响应：基于本地 rg 全文搜索与预建索引，无需网络往返即可秒级定位文档片段。
• 权限边界清晰：严格只读上游（禁止 git push、PR 创建、技能内容回传），降低供应链安全风险。
• 多语言支持基础：保留本地化导航入口扩展能力（虽验证仅保证英文文档集可用）。

潜在局限

• 新鲜度依赖手动刷新：文档非实时同步，用户需主动触发更新流程才能获取上游最新变更；若长期未刷新，可能遗漏关键 Bugfix 或 API 变更说明。
• 英语为唯一验证语言：虽存在多语言导航元数据，但核心内容仅保证英文可用，非英语用户可能体验受限。
• 索引构建依赖脚本：首次使用或文档结构大幅变更后需执行 build_knowledge.py 重建索引，存在短暂不可用窗口。
• 模糊查询精度受限：极度口语化或跨领域混合问题可能需多次迭代搜索才能定位，路由表覆盖范围决定上限。

适用人群

• OpenClaw 平台运维工程师与 SRE，需离线或内网环境查阅配置手册
• 开发团队技术负责人，需要锁定特定版本文档进行合规审计
• 集成开发者，频繁查询 CLI 参数、通道行为、网关安全策略等实现细节
• 技术写作者或培训师，需要稳定版本文档作为课程或手册基础

常规风险提示

• 版本漂移风险：回答中需主动声明快照提交哈希及日期，避免用户误将过期文档当作当前权威来源。
• 权限误配置风险：scripts/ 目录包含 git fetch/clone 能力，若运行环境具备写权限，需确保遵循「只读上游」原则，防止意外推送。
• 索引失效风险：手动修改 openclaw_docs/ 未触发重建脚本时，可能导致搜索结果与文件内容不一致。
• 上游变更冲突：更新流程中若上游文档结构重构（如文件重命名、目录迁移），diff_docs.py 生成的摘要可能需人工介入理解。

核心用法

Claw Wiki 是一个专为 OpenClaw 开源项目设计的文档查询与管理 Skill。用户可通过自然语言提问获取产品使用、部署配置、CLI 命令、网关行为等技术文档答案。Skill 的核心工作流分为两类场景：常规查询时，系统从本地 openclaw_docs/ 目录快照中检索内容，通过 rg 文本搜索定位相关文件，读取 1-3 个最相关文档后综合回答，并标注引用路径；当用户需要更新文档或验证时效性时，执行完整的同步流程：读取 state/source-lock.json 确认当前版本，运行 scripts/sync_docs.py 等脚本从上游拉取最新文档，重建索引与差异报告。

显著优点

该 Skill 的设计理念以可重复性与准确性为核心。相比依赖大模型记忆或实时联网检索，本地快照模式确保答案完全基于官方文档原文，杜绝幻觉与版本错乱。其结构化路由系统（routing-cheatsheet.md、query-examples.md）显著提升复杂问题的定位效率；纯 Python 标准库实现零第三方依赖，部署轻量且供应链攻击面为零；完整的版本溯源机制（source-lock.json 记录 commit、ref、同步时间）满足企业合规审计需求。

潜在局限

首要限制是文档时效性边界：本地快照可能滞后于上游更新，需用户主动触发同步或接受版本标注。其次，语言覆盖偏向英文：虽然 docs.json 可能存在本地化导航，但验证仅保证英文文档集可用，多语言用户可能体验降级。此外，Skill 功能高度绑定 OpenClaw 单一项目生态，跨项目或通用技术问题超出能力边界；大型文档文件的片段读取策略虽优化性能，但可能遗漏跨章节关联信息。

适合人群

该 Skill 精准服务于三类用户：OpenClaw 系统管理员与运维工程师，需快速查询网关配置、故障排查与 CLI 操作；开发者与集成工程师，关注 Channels、Providers、Tools 等扩展机制的实现细节；以及技术文档撰写者与培训师，需要可验证、可引用的官方文档来源。对离线环境或合规敏感型组织（金融、政务）尤为适用。

常规风险

性能方面：首次同步或大规模文档更新时，全量 git clone 与索引重建可能消耗显著时间与磁盘 I/O；rg 搜索在大目录下的响应延迟需纳入用户体验考量。依赖项风险：尽管 Skill 本身零依赖，但其功能完整性依赖本地 Git 环境与 Python 解释器版本兼容性。数据一致性：sync_docs.py 的备份机制（openclaw_docs.previous/）可防止意外丢失，但用户本地修改若未提交可能被覆盖，需明确工作流预期。网络可用性：离线场景下无法执行更新操作，需提前规划快照维护周期。