OpenWiki 使用教程：让 Codex、Claude Code 与 Hermes 共享一个 LLM Wiki

本文更新于 2026-08-11，实测版本为 OpenWiki 0.3.2。项目仍处于快速迭代期，后续命令和界面可能变化，请以官方仓库为准。

很多人把“AI 知识库”理解成：上传一批文件，提问时让模型临时找几段相关内容。这是典型的 RAG 思路。Karpathy 提出的 LLM Wiki 不太一样：它让 AI 把原始资料持续编译成一套可读、可链接、可修订的 Markdown Wiki。新资料到来时，不只是增加一个向量索引，而是更新主题页、人物页、对比页、索引和变更记录。[4]

LangChain 的 OpenWiki，则把这个想法做成了可以安装运行的开源 CLI：它既能为代码仓库生成持续更新的工程文档，也能把 Notion、Gmail、Slack、X、网页搜索、Hacker News 和本地 Git 仓库等来源整理成个人知识库。[2]

本文基于官方仓库、npm 包、CLI 实测和公开规范，给出一套从安装、生成、接入 Notion、跨 Agent 使用，到自动更新和排错的完整教程。

一、先说结论：OpenWiki 解决的到底是什么问题

LLM Wiki 的重点不是“搜索更快”，而是让知识产生复利：

• 原始资料保留为证据；
• AI 将资料整理成结构化 Markdown；
• 不同页面之间建立链接；
• 新资料会更新旧结论，而不是不断堆积重复摘要；
• Codex、Claude Code、Hermes 等 Agent 可以读取同一套 Wiki；
• Wiki 可以进入 Git，获得版本历史、差异对比和回滚能力。

Karpathy 将其概括为三层：不可变的 Raw Sources、由 AI 维护的 Wiki，以及约束目录结构和维护流程的 Schema。他还建议用 index.md 做内容目录、用 log.md 记录每次摄取、查询和维护操作。[4]

OpenWiki 在此基础上提供了可执行实现。当前官方明确区分两种模式：[2]

• Code 模式：读取当前代码仓库，把文档写入仓库的 openwiki/ 目录；
• Personal 模式：读取配置好的个人数据源，把知识写入 ~/.openwiki/wiki。

如果你是程序员，建议先试 Code 模式；如果你希望把 Notion、邮件、文章和 AI 对话沉淀成“第二大脑”，再配置 Personal 模式。

二、为什么值得为 Agent 单独建立长期知识层

为了确认 OpenWiki 不是停留在概念层的“知识库包装”，本文做了四项独立验证：检查 npm 发布信息与运行要求、阅读官方仓库和生成文档、实际运行 CLI 帮助，以及启动本地可视化服务。实测结果表明，它已经覆盖初始化、增量更新、连接器摄取、跨 Agent 指引和知识图谱浏览等完整环节。

从实际工作流看，OpenWiki 最值得关注的不是某一个界面，而是以下四个机制：

1. 把知识从单次对话中剥离出来。 Codex、Claude Code、Hermes 或其他 Agent 只要能读取文件，就能复用同一批 Markdown，不再把重要背景锁在某个模型的聊天记录里。
2. 把一次性摘要改成增量维护。 新资料到来后，系统会尝试修订已有主题和关联关系，而不是无限堆积互不相干的摘要。
3. 让知识保持可审阅。 最终产物是普通 Markdown，可以人工检查、修改、提交 Git、对比差异和回滚。
4. 同时服务代码与个人资料。 Code 模式面向项目文档，Personal 模式面向 Notion、邮件、网页和本地仓库，两者都可以成为 Agent 的长期上下文。[2]

截至本文写作时，npm 上的 OpenWiki 最新版是 0.3.2，采用 MIT 许可证，并要求 Node.js 22 或更高版本。[2][3] 这说明它仍是快速迭代中的早期工具，生产使用时应固定版本，并在升级前检查 Changelog。

还需要注意 OKF 版本差异：OpenWiki README 当前写明输出 Open Knowledge Format v0.1，而 Google 官方 OKF 规范仓库目前已经更新到 v0.2。使用者不必手工修改生成文件，但在与其他 OKF 工具互操作时，应先确认双方支持的版本。[2][5]

三、安装前准备

1. 检查 Node.js

OpenWiki 要求 Node.js 22 或更高版本：[3]

node --version
npm --version

如果 Node 版本低于 22，建议通过 NodeSource、nvm 或系统包管理器升级。升级后重新打开终端，再次检查版本。

2. 安装 OpenWiki

npm install -g openwiki

检查是否安装成功：

openwiki --help

本文在 Node.js v22.23.2 下实际运行了 openwiki@0.3.2 --help，命令正常返回 Code、Personal、Auth、Ingest、Cron 和 Visualize 等指令。

如果你暂时不想全局安装，也可以先用 npx 测试：

npx -y openwiki@0.3.2 --help

四、最简单的用法：给代码仓库生成 Wiki

进入一个 Git 项目：

cd /path/to/your-project
openwiki code --init

也可以省略 code，因为默认就是代码模式：

openwiki --init

第一次运行会让你选择模型提供商、模型和认证方式。配置完成后，OpenWiki 会分析仓库，并把文档写入：

your-project/
├── openwiki/
│   ├── index.md
│   ├── INSTRUCTIONS.md
│   └── ...
├── AGENTS.md
└── CLAUDE.md

OpenWiki 会在根目录的 AGENTS.md 和 CLAUDE.md 中维护自己的标记区块，用来提醒 Codex、Claude Code 等编程 Agent 优先读取 Wiki；它只改写自己的区块，保留你在文件里的其他项目指令。[2]

生成中文 Wiki

openwiki code --init --language zh-CN

语言参数会影响生成文档，代码、文件名和标识符仍保持原样。[2]

自定义文档重点

编辑：

openwiki/INSTRUCTIONS.md

可以写入类似要求：

重点记录：
- 项目架构和关键数据流
- 部署、回滚与故障排查
- 数据库表和 API 路由
- 容易踩坑的环境变量
- 重要设计决策及其原因

不要记录：
- node_modules
- 构建产物
- 临时日志

这个文件由你控制，正常更新时 OpenWiki 不会覆盖它。[2]

排除隐私文件和无关目录

在项目根目录创建 .openwikiignore：

.env
.env.*
secrets/
node_modules/
dist/
build/
*.log

它采用类似 .gitignore 的规则。被忽略的路径不会被 OpenWiki 主动读取和扫描，但其他可见文件仍可能间接提到这些模块，所以它不能替代真正的密钥隔离。[2]

五、更新已有 Wiki

代码变化后运行：

openwiki code --update --print

--print 表示执行一次、输出结果后退出，适合脚本和 CI。OpenWiki 会比较已有文档与新代码，在有变化时更新 Wiki；没有变化时尽量保持 no-op，避免定时任务制造无意义提交。[2]

也可以直接给出更新重点：

openwiki code --update --print \
  "优先更新认证流程、数据库迁移和部署文档"

六、个人模式：把 Notion 等资料变成第二大脑

初始化个人知识库：

openwiki personal --init

默认输出目录是：

~/.openwiki/wiki

连接器抓取的原始数据和清单通常保存在：

~/.openwiki/connectors/<connector>/raw/

模型凭据和 OAuth Token 保存在本机：

~/.openwiki/.env

这些文件不要提交到 Git，也不要发送给别人。[2]

使用 ChatGPT 登录，而不是单独填写 OpenAI API Key

官方提供了 openai-chatgpt Provider，可通过浏览器登录 ChatGPT，并使用当前订阅中包含的 Codex 用量：[2]

OPENWIKI_PROVIDER=openai-chatgpt openwiki personal --init

命令会打开 auth.openai.com。如果在远程服务器上运行，它也会打印登录地址。登录完成后，OpenWiki 会保存访问令牌和刷新令牌。刷新令牌应当视同密码保护。

如果你更愿意用 API Key，也可以在首次向导里选择 OpenAI、Anthropic、Gemini、OpenRouter、Bedrock、GitHub Copilot 或 OpenAI-compatible Provider。OpenAI-compatible 模式可连接 Ollama、LM Studio 和自建网关。[2]

七、接入 Notion

先运行 OAuth：

openwiki auth notion

它会打开 Notion 授权页面。授权时应只选择确实需要进入 Wiki 的页面或工作区，不建议一开始就开放全部公司资料。

查看 OpenWiki 从 Notion MCP 发现了哪些工具：

openwiki auth tools notion

开始摄取：

openwiki ingest notion

如果配置了多个来源，可以运行：

openwiki ingest all

摄取流程不是简单地把每个 Notion 页面复制成 Markdown，而是先保存来源数据，再让 Agent 抽取主题、人物、任务、决策和关联关系，最后合并到个人 Wiki 中。[2]

建议第一次只授权少量测试页面，检查以下内容后再扩大范围：

• 原始资料是否抓取完整；
• Wiki 是否把不同项目混在一起；
• 人名、时间和结论是否有来源依据；
• 私密页面是否被错误纳入；
• 增量更新是否重复生成同一主题。

八、让 Codex、Claude Code 和 Hermes 共享同一个知识库

Code 模式

Code 模式最省事。OpenWiki 会自动维护项目根目录的 AGENTS.md 与 CLAUDE.md 提示区块。Codex 读取 AGENTS.md，Claude Code 读取 CLAUDE.md，因此它们会知道 Wiki 的位置。[2]

Personal 模式

个人 Wiki 位于项目目录之外，需要在各 Agent 的项目指令中显式登记路径。例如在 AGENTS.md 增加：

## Shared LLM Wiki

Before answering questions that depend on prior research or personal context:
1. Read `~/.openwiki/wiki/index.md` first.
2. Search relevant Markdown pages under `~/.openwiki/wiki/`.
3. Prefer the compiled wiki for orientation, then inspect raw sources when provenance matters.
4. Do not overwrite the wiki manually unless the task explicitly asks for maintenance.

在 CLAUDE.md 中也可加入同样规则。Hermes Agent 则可以在相关任务中直接读取 ~/.openwiki/wiki/index.md，再按主题搜索 Markdown 文件。

这里的关键不是某个 Agent “接管”知识库，而是所有 Agent 都把同一个 Markdown 目录当作长期知识层。这样换模型、换终端甚至换编辑器时，知识仍然保留。

九、可视化浏览 Wiki

代码 Wiki：

openwiki visualize

个人 Wiki：

openwiki visualize ~/.openwiki/wiki

服务器或不希望自动打开浏览器时：

openwiki visualize ~/.openwiki/wiki \
  --port 4400 \
  --no-open

本文实际对官方仓库自带的 Wiki 运行了可视化命令，程序扫描到 14 个页面和 21 条链接，本地页面返回 HTTP 200。服务默认监听 127.0.0.1，不会自动暴露到公网；但页面中的图谱、Markdown 和 Mermaid 相关前端库会从公共 CDN 加载，因此浏览时仍需要网络。[2]

十、自动更新

GitHub Actions：适合 Code 模式

官方提供了定时工作流示例，核心流程是：完整检出 Git 历史、安装 Node.js 22 和 OpenWiki、执行 openwiki code --update --print，然后创建文档更新 PR。[6]

最容易忽略的是：

with:
  fetch-depth: 0

必须保留完整 Git 历史，否则 OpenWiki 可能找不到上次记录的提交，无法正确计算增量变化。[6]

模型 Key 应保存在 GitHub Actions Secrets 中，不要直接写进 YAML：

env:
  OPENWIKI_PROVIDER: openrouter
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
  OPENWIKI_MODEL_ID: your-model-id

GitHub Actions 的 Cron 使用 UTC。比如北京时间每天上午 10 点，对应 UTC 02:00：

on:
  schedule:
    - cron: "0 2 * * *"

Personal 模式

手工增量更新：

openwiki ingest all --print

只执行由调度器管理、当前到期的来源：

openwiki ingest all --scheduled --print

查看、暂停或恢复 OpenWiki 保存的连接器计划：

openwiki cron list
openwiki cron pause all
openwiki cron resume all

在 Linux 服务器上，也可以用系统 Cron、systemd timer 或 Hermes 定时任务调用 openwiki ingest all --scheduled --print。要确保定时进程能读取同一个用户的 ~/.openwiki/.env，并使用正确的 Node 与 OpenWiki 路径。

十一、日常使用工作流

推荐把 OpenWiki 当作“编译器”，而不是聊天机器人：

1. 收集：把高质量资料加入 Notion、本地仓库或其他连接器；
2. 摄取：运行 openwiki ingest ...；
3. 审阅：检查新增页面、关键事实和来源；
4. 提问：让 Agent 先读 index.md，再读取相关主题页；
5. 回写：把值得长期保留的对比、结论和决策写回 Wiki；
6. 维护：定期检查重复页面、失效链接、矛盾结论和过期资料；
7. 版本化：对重要 Wiki 使用 Git，审阅每次差异。

这和 Karpathy 的 Ingest、Query、Lint 三类操作基本一致：摄取资料、基于 Wiki 查询、定期检查知识库健康度。[4]

十二、隐私、安全与常见坑

1. Markdown 在本地，不等于数据完全不出本地

Wiki 文件和连接器缓存可以保存在本机，但如果使用云端模型，模型处理所需内容仍会发送给相应 Provider。高度敏感资料应使用本地兼容模型，或先做好脱敏和权限隔离。

2. 不要提交 ~/.openwiki/.env

它可能包含 API Key、OAuth 访问令牌与刷新令牌。备份时应加密，泄露后要立即撤销和重新授权。[2]

3. 第一次不要摄取全部资料

先用一个小型代码仓库或少量 Notion 页面验证目录结构和输出质量。范围过大时，成本、耗时、重复主题和错误合并都会更难控制。

4. Wiki 不是原始证据

AI 生成的主题页可能概括错误。重要决策必须能够追溯到原始材料。OKF 的目标之一正是让 Markdown 知识具备来源、可信度、新鲜度和生命周期等可追踪信息。[5]

5. 可视化页面默认不是远程管理后台

openwiki visualize 默认绑定本机回环地址。远程使用时优先通过 SSH 端口转发访问，不要为了方便直接暴露到公网。

6. 关闭匿名遥测

OpenWiki 默认收集匿名聚合使用事件；官方说明不会收集文件内容、凭据、提示词和模型输出。若仍希望关闭，可设置：[2]

export OPENWIKI_TELEMETRY_DISABLED=1
# 或
export DO_NOT_TRACK=1

十三、适不适合你

OpenWiki 比较适合：

• 有多个 AI 编程 Agent，希望它们共享项目知识；
• 代码仓库缺少持续更新的架构和运维文档；
• 长期研究一个主题，希望知识不断累积；
• Notion、邮件、网页和项目笔记分散在多个平台；
• 喜欢 Markdown、Git、Obsidian 这类可控工具。

暂时不适合：

• 只想临时上传几份 PDF 问一次问题；
• 不愿意审阅 AI 生成知识；
• 数据极敏感，却只能使用外部云模型；
• 资料数量很少，普通文件夹与全文搜索已经够用。

十四、最短上手清单

如果只想今天就试起来，执行：

# 1. 确保 Node.js >= 22
node --version

# 2. 安装
npm install -g openwiki

# 3. 在一个小型代码仓库里初始化中文 Wiki
cd /path/to/test-project
openwiki code --init --language zh-CN

# 4. 浏览图谱
openwiki visualize

# 5. 代码变化后增量更新
openwiki code --update --print

确认 Code 模式符合预期后，再尝试个人模式：

openwiki personal --init
openwiki auth notion
openwiki ingest notion
openwiki visualize ~/.openwiki/wiki

一句话总结：RAG 更像每次提问都去仓库临时找材料；LLM Wiki 更像让 AI 先把材料编成一本会持续修订的书。OpenWiki 的价值，是让这本书成为 Codex、Claude Code、Hermes 和人类都能读取的普通 Markdown。

延伸参考

如果希望直观看一遍 OpenWiki 的个人模式、Notion 授权、增量更新和跨 Agent 调用流程，可以观看这段操作演示。[1]

Sources

[1] https://www.bilibili.com/video/BV1EaN86hEhV — OpenWiki 操作演示（延伸参考） [2] https://github.com/langchain-ai/openwiki — LangChain OpenWiki 官方仓库 [3] https://www.npmjs.com/package/openwiki — openwiki npm 包 [4] https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f — Karpathy: LLM Wiki [5] https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md — Open Knowledge Format Specification [6] https://github.com/langchain-ai/openwiki/blob/main/examples/openwiki-update.yml — OpenWiki GitHub Actions 示例