> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# OpenWiki 快速指南
- URL: https://www.hubwiz.com/blog/a-quick-guide-to-openwiki/
- Published: 2026-09-02T08:03:38.000Z
- Updated: 2026-09-02T08:03:38.000Z
- Description: 这篇文章做两项工作。首先是解释：OpenWiki实际上是什么，它的自纠正机制如何工作。其次是路测。
- Author: admin
- Tags: AGENT, OPENWIKI, #Import 2026-10-14 14:41

我在一个完全开源的栈上运行了LangChain的wiki代理：本地模型、四次失败、一个Ralph循环，以及一个完成的wiki。

五次尝试完全本地生成wiki。橙色失败，蓝色完成。图表来自作者的运行日志。

文档失败是因为它是一次性写入的。记忆有效是因为它经常覆盖。我们所谓的大部分文档都是穿着第二件衣服的第一件，这就是它腐烂的原因。

OpenWiki是迄今为止修复这个问题最有趣的尝试，这篇文章做两项工作。首先是解释：OpenWiki实际上是什么，它的自纠正机制如何工作。其次是路测：我在一个完全开源的栈上端到端运行了它，包括本地模型，我将告诉你这到底需要什么。剧透：四次不同的失败，一次荒谬的救援，以及一个真正让我惊讶的结果。

## 1、OpenWiki是什么？

OpenWiki是[LangChain](https://www.langchain.com/blog/introducing-openwiki-an-open-source-agent-for-repo-documentation?ref=hubwiz.com)的一个免费、MIT许可的命令行工具，LangChain是构建AI应用程序最常用的开源工具背后的公司。你将其指向一个仓库。代理读取代码，将链接的markdown wiki写入仓库内的`openwiki/`文件夹，并在代码更改时保持其最新。

这个wiki不是给你的，或者主要不是。它是给代理的。OpenWiki将指针块写入`AGENTS.md`和`CLAUDE.md`，这是Claude Code、Codex和Cursor等编码代理在启动时读取的约定文件。一个[编码代理](https://github.com/langchain-ai/openwiki?ref=hubwiz.com)到达你的仓库时会发现一张精心策划的地图，而不是每次都从头重新发现你的架构。阅读摘要也比重新阅读源代码便宜得多，无论是时间还是token。

更新来自版本控制。OpenWiki检查自上次运行以来哪些提交落地了，读取差异，并仅更新更改的内容。将其连接到计划的CI任务，wiki会每天自行刷新，像任何其他贡献者一样打开一个包含其编辑的拉取请求。

## 2、聪明的部分：带收据的主张

许多工具生成文档。使OpenWiki不同的机制称为Grounded Claims，值得慢慢解释。

wiki中的每个重要事实都存储两次。一次作为页面上的散文。一次作为侧车文件中的结构化主张，固定在证明它的精确代码行上。固定包括主张制定时那些行的内容哈希。

这是我运行中的一个真实例子。wiki断言事件"在调用任何监听器之前持久化到run\_events表"。侧车将该句子固定到特定源文件的第9到26行，并进行哈希。如果我编辑这些行，哈希就不再匹配。主张变得过时，过时的主张强制其页面在下次运行时重新生成，即使更新规划器认为该页面不需要工作。

这就是文档和记忆之间的区别。文档等待人类注意到它是错误的。主张知道自己错了，并安排自己的纠正。文档不仅仅是描述代码。它们可以针对代码证伪。

## 3、这个想法从何而来

OpenWiki并非凭空出现。Andrej Karpathy是OpenAI的创始成员，也是AI工程领域最受欢迎的声音之一。2026年4月，他发布了一个[简短的要点](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f?ref=hubwiz.com)，勾勒了他称之为LLM Wiki的内容。三层：不可变的原始源、从中编译的LLM维护的markdown wiki，以及描述wiki如何组织的模式。他的论点针对检索增强生成，这是在提问时搜索文档的标准技术。他认为，将知识一次性编译成持久页面，它会复合。每次都检索片段，它会蒸发。

这个要点在几天内获得了5000颗星，LangChain[直接将其归功于](https://www.langchain.com/blog/introducing-openwiki-an-open-source-agent-for-repo-documentation?ref=hubwiz.com)灵感。OpenWiki本质上就是那个草图，产品化的，在此基础上添加了Grounded Claims。输出甚至使用了Google的Open Knowledge Format，[OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md?ref=hubwiz.com)，这是一个开放标准，用于打包知识以便任何代理都可以使用。作为代理记忆的markdown wiki悄然成为了一种趋同模式。OpenWiki是目前最完整的表达：两个月内15,000个GitHub星，每隔几天发布一次。它甚至用自己的代码文档化了自己的仓库。

## 4、路测：完全开源还是失败

[官方文档](https://docs.langchain.com/oss/openwiki/overview?ref=hubwiz.com)会很乐意连接OpenAI或Anthropic，在大约三分钟内为大约十美分生成一个wiki，根据社区报告。我想回答更难的问题。我能用开放栈运行整个东西吗？用本地模型，这样没有一个字节离开我的机器？

### 4.1 技术栈

四件，全部免费，全部开源。

- **OpenWiki v0.4.0**，用`npm install -g openwiki`安装。
- [Ollama](https://ollama.com/?ref=hubwiz.com)，本地运行开放权重模型的标准工具。OpenWiki没有原生Ollama提供者，但它可以与任何OpenAI兼容端点通信，Ollama暴露了一个。
- **两个开放权重模型。**首先是gpt-oss:20b，OpenAI的开放权重模型，13GB下载。后来是qwen3.5 4B，阿里巴巴开放系列的3.4GB模型。
- **硬件：**一台具有24GB统一内存的Apple笔记本电脑。中端，不是工作站。

目标是我的一个名为Hangar的个人原型：一个带有Web UI的代理编排服务器，58个TypeScript文件分布在服务器、Web客户端和示例中。真实代码，适度规模，没什么奇特的。

整个提供者配置是`~/.openwiki/.env`中的五行：

```bash
OPENWIKI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_API_KEY=ollama
OPENAI_COMPATIBLE_BASE_URL=http://localhost:11434/v1
OPENWIKI_MODEL_ID=gpt-oss:20b
OPENWIKI_TELEMETRY_DISABLED=1

```

我还在仓库根目录给了它一个`.openwikiignore`，排除了`node_modules`、构建输出、锁文件和图像。该文件是一个硬读边界，对于本地模型来说它重要两倍：代理读取的所有内容都必须适合更小的窗口。

然后我运行了`openwiki code --init --print`，看着它失败。四次，四种不同的方式。每次失败都教会了我错误消息没有告诉我的东西，因为错误消息几乎每次都相同。

### 4.2 失败一：沉默的4096 token窗口

两分钟后，第一次运行以一行死亡：

```
Repository planning worker exited without submit_plan.

```

没有堆栈跟踪，没有原因。真正的罪魁祸首与OpenWiki无关。Ollama将每个模型默认为4096 token的上下文窗口，这是模型一次可以看到的工作内存。OpenWiki的仓库扫描提示比这个大小大好几倍。当提示溢出时，Ollama不会报错。它从顶部静默截断，所以模型从未看到告诉它存在`submit_plan`工具的指令。`ollama ps`确认了这一点：模型加载时`CONTEXT 4096`。

修复方法是Ollama服务器上的一个环境变量，这是本文对任何在家尝试的人最重要的单行代码：

```bash
OLLAMA_CONTEXT_LENGTH=32768 ollama serve

```

### 4.3 失败二：相同错误，不同原因

窗口提高后，规划器再次死亡。相同的行，相同的两分钟。这就是调试本地AI栈变得真正困难的地方：一条错误消息，多个根本原因，没有遥测来分离它们。

所以我直接测试了下一层。一个手动构建的请求到Ollama的端点，附加了`submit_plan`工具模式，看看模型是否能进行结构化工具调用：

```bash
curl http://localhost:11434/v1/chat/completions \
  -d '{"model":"gpt-oss:20b", "tools":[…submit_plan schema…], …}'

```

它返回了一个完美形成的工具调用。两个模型都是如此。管道在隔离状态下工作，这意味着故障存在于OpenWiki和Ollama之间的传输中。OpenWiki默认发出非流式请求，而这个管道需要流式传输。在`.env`中再加一行：

```bash
OPENWIKI_OPENAI_COMPATIBLE_STREAMING=true

```

规划器在下次运行时通过了。

### 4.4 失败三：有能力的模型无法完成

现在是有趣的一个。规划工作后，20B模型进入了真正的工作。它的调用从几秒钟延长到一分多钟，八分钟后，一个真正的wiki页面出现在磁盘上：对Hangar事件总线的准确描述。正确的文件路径。正确的功能，分发前的持久化。一个正确的字段参考表。这不是样板代码；模型理解了代码。

然后运行还是死了：

```
/openwiki/architecture/event_bus.md worker exited without submit_page.

```

模型完成了困难的生成工作，并跳过了提交完成页面的仪式性工具调用。管道丢弃了一个已经写好在磁盘上的页面。能力从来不是问题。在长上下文末尾关闭循环的纪律才是。

### 4.5 失败四：较小的模型撞上了同样的墙

我切换到qwen3.5 4B，其工具调用模板是Ollama中经过最多实战测试的之一，并将窗口提高到65,536 token。它走得更远。它完全完成了事件总线页面，这次包括其Grounded Claims侧车，这是整个管道端到端工作的第一个时刻。51分钟后，它在写第二个页面时死亡。相同的行：worker exited without `submit_page`。

模式现在不可否认。每个页面worker都在累积上下文：页面草稿、它读取的证据、工具历史。迟早，结束指令会从静默截断的窗口末端掉落。故障从来不是关于哪个模型。它是关于当内存耗尽时服务栈做什么：什么也不做，静静地。

## 5、救援是一个Ralph循环

这里变得有趣了。OpenWiki v0.4.0在持久运行文件`openwiki/.run.json`中检查点其进度，因此中断的生成会恢复而不是重新启动。这意味着"每几页崩溃"的修复方法简单得令人尴尬：再运行一次。在循环中。直到它干净退出。

这个模式有个名字。它是一个Ralph循环，故意愚蠢的while-true，向代理提供相同的指令直到工作完成，以辛普森一家中那个可爱迟钝的孩子命名。我之前写过运行它们的文章。我没指望一个会拯救别人的产品。整个harness只有八行shell：

```bash
for i in 1 2 3 4 5 6 7 8; do
  if openwiki code --init --print; then
    echo "COMPLETE after $i iterations"; break
  fi
done

```

我再次提高了Ollama的窗口，到98,304 token，为worker提供更多空间。然后我让循环运行。

![None](https://www.hubwiz.com/blog/content/images/2026/09/1-EB3q_Ked4lBmkw7tUMATOw.png)

*每次迭代后存入的页面。进度是单调的：检查点意味着崩溃永远不会丢失已完成的工作。图表来自作者。*

六次迭代，不到三小时。第一次存入了四个完成的页面。第二次又存入了四个。然后连续三次迭代在一个困难页面上停滞，没有存入任何内容，这正是人类看护者会放弃的地方。第六次迭代突破了，一旦越过障碍，它在一次通过中完成了剩余的十五个页面，因为索引和摘要页面生成很快。最终状态：一个23页的wiki，18个grounded claims，每个事实都固定在哈希证据上，退出代码零。

循环没有让模型更聪明。它让失败变得廉价。这就是全部技巧，它之所以有效是因为OpenWiki的检查点使进度持久。暴力加上保存文件胜过脆弱的才华。

![None](https://www.hubwiz.com/blog/content/images/2026/09/1-mIX0SfuP6UQyacSjP9p5Rw.png)

*完成的设置。仓库、代理、模型服务器、模型、输出和重试循环都在一个机器边界内。唯一跨越它的行是从未使用的那行。图表来自作者。*

## 6、诚实的记分卡

将两条路线并排比较。云路线：大约三分钟，大约十美分无消费上限，零专业知识要求，你的代码离开机器。本地路线：端到端大约四小时，没有花费，四层故障需要诊断加上重试harness需要构建，没有一个字节离开。

本地方法合理吗？对大多数人来说，大多数时候，不。40倍的时间成本加上诊断静默故障的技能，与十美分相比是糟糕的交易。对于代码不能离开大楼的人来说，它不仅是合理的，而且是唯一的选择，而且它明显有效。

我关心的发现不同，我认为它比时间安排更重要。**每个故障都是配置形状的，不是能力形状的。** 模型理解了代码。20B写了准确的架构页面。每次崩溃的都是管道：默认窗口静默截断、丢弃工具调用的传输、耗尽而没有警告的上下文。"本地模型不够好"是错误的教训。正确的教训是本地服务栈仍然静默失败，没有人发现它。这是一个工程问题，不是模型规模问题，工程问题会被修复。

## 7、你应该使用它吗？

如果你的代码无论如何都在云API上：是的，今天就试试。三分钟版本是真实的，wiki质量是真实的，主张机制不同于任何其他正在发布的。从我遇到的尖锐边缘中三个警告。开始之前提交，因为init会破坏性地替换现有的wiki。如果使用计费密钥请注意花费，因为没有成本上限，社区报告显示差异很大。将其视为早期、快速发展的0.x，因为它确实是。

如果你想要完全私有：它有效，截至本周，在上述修复和耐心下。首先提高Ollama的上下文窗口。

如果你已经将知识保存在markdown中，接受更广泛的观点。行业从每个方向不断趋同于相同的答案：纯文本文件，由代理维护，由证据纠正。wiki不是产品。纠正循环才是。OpenWiki只是第一个带收据发布的工具。

---

原文链接：[OpenWiki Turns Your Codebase Into Self-Correcting Memory](https://medium.com/@davidroliver/openwiki-turns-your-codebase-into-self-correcting-memory-c8461329419d?ref=hubwiz.com)

汇智网翻译整理，转载请标明出处