OpenWiki v0.5.2 中文教程：代码 Wiki、Claims 与 Agent 集成

OpenWiki 用 Agent 阅读代码库并维护一套归你所有的 Markdown Wiki。它不只记录页面更新时间，还把关键事实写成 Grounded Claims，关联到具体源码证据；证据变化时，更新流程会重新核对相关页面。当前正式版 v0.5.2发布于 2026 年 9 月 15 日，要求 Node.js 22.22.0 以上。

路径一：接入 Codex 等编码 Agent

node --version
npm install -g openwiki@0.5.2
openwiki integrations install codex
openwiki integrations list

安装后重启 Codex，在目标仓库要求“初始化这个仓库的 OpenWiki，并在写入前说明将读取和创建的路径”。集成默认是用户级；需要只作用于当前项目时加 --project /path/to/repo。它还能接 Claude、OpenCode、Cursor、IBM Bob 和 Kiro。外部编码 Agent 集成目前使用仓库源码和测试，不会把 personal connectors 的资料带进代码 Claims。预期结果是仓库出现 openwiki/、索引和页面，以及对应 .claims/ 证据文件；用 Git diff 检查，不要自动提交。

路径二：独立 CLI 初始化和更新

npm install -g openwiki@0.5.2
cd /path/to/repo
openwiki --init
openwiki --update

独立路径会引导配置模型 provider。中断时，openwiki/.run.json 保存运行状态；完整收尾验证通过后才会删除。更新前 OpenWiki 会检查 Claims 中的证据版本，即使规划器漏掉页面，失效的 Claim 也会触发复核。生成目录应进入版本控制，便于审阅页面、claims 和 manifest 的共同变化。openwiki/INSTRUCTIONS.md 用于用户说明，重新初始化时要确认其保留行为，避免把手工要求写进会重建的生成页。

配置、权限、个人数据和可视化

个人模式的凭证、连接器数据、聊天历史和技能默认写在 ~/.openwiki；容器或隔离环境可在启动前设置 OPENWIKI_CONFIG_DIR=/data/openwiki。连接器可能摄取 Notion、Gmail、Slack 等资料，授权范围与保留策略要逐个核对。可视化服务默认只应留在本机 127.0.0.1:4321；图谱会加载 CDN 资源，严格离线环境要先测试或使用导出结果。搜索和读取工具是本地只读、无需模型的路径，生成与更新才会调用 provider。

验证、排错和升级

初始化后至少检查：index 能打开；一个架构事实能从 Claim 回到源码；修改被引用代码后 update 会重审相关页面；失败运行保留 .run.json 而不是假装成功。Mermaid 默认只有轻量检查，需要与 GitHub 渲染严格一致时，官方建议安装 mermaid 和 jsdom。provider 报错先查认证、模型名与网络；OpenRouter 402 可能来自输出 token 上限的额度预检；Bedrock 流式停顿可按官方环境变量设置有限超时。升级前提交整个 openwiki 目录，固定安装新版本，重跑 update 并比较 Claims。v0.5.2 增加 IBM Bob/Kiro 集成及多项 provider、安全和稳定性修复。

遥测和自动更新边界

官方说明单次 run 遥测记录命令、成功/失败/no-op、粗粒度错误类别，以及设置时的 brain mode、provider 和 connector 名称；不收集文件内容、仓库数据或名称、凭证、提示词、输出、路径、URL 和模型 ID。可用 --telemetry-file=PATH 预览一次运行会发送什么。GitHub Actions 自动更新要固定 action 和 OpenWiki 版本，只允许提交生成文档路径，并保留 PR 审查；默认 GITHUB_TOKEN 创建的 PR 通常不会触发多数 pull_request 检查，官方因此要求专用 token 或组织批准的 GitHub App。

与 DeepWiki Open 的实际区别

DeepWiki Open 是可自托管的 GitHub/GitLab/Bitbucket Wiki 生成和问答应用，更偏 Web 服务与在线浏览。OpenWiki 是本地 CLI 和编码 Agent 工作流，Wiki 直接存进仓库，并用 Claims 维护事实到源码的版本化联系。需要一个团队可访问的自托管 Web 界面时，DeepWiki Open 的产品形态更合适；希望文档随代码评审、可由 Agent 本地更新并追踪证据时，OpenWiki 更贴合。

常见问题