OpenWiki на практике: Grounded Claims и полностью локальный запуск на Ollama

Документация гниёт, потому что её пишут один раз. Память остаётся полезной, потому что её постоянно перезаписывают. Большая часть того, что выдаёт себя за документацию, на деле относится к первому виду, лишь притворяясь вторым, — потому она и устаревает.

OpenWiki — инструмент от LangChain — интересная попытка это изменить. Ниже объясняется, что он делает и как устроен его механизм самоисправления, а затем идёт практический тест на полностью открытом стеке с локальными моделями. Этот запуск дал четыре разных сбоя, почти комичное спасение и результат лучше ожидаемого.

Что такое OpenWiki

LangChain — команда, стоящая за большой частью открытой инфраструктуры для ИИ-приложений, — выпустила OpenWiki как бесплатную утилиту командной строки под лицензией MIT. Её направляют на репозиторий, где агент изучает код и пишет связанные между собой markdown-страницы в папку openwiki/. По мере поступления коммитов страницы обновляются.

Основная аудитория здесь не люди: вики пишется для агентов. Инструмент вставляет ссылку в AGENTS.md и CLAUDE.md — файлы, которые Claude Code, Codex, Cursor и похожие ассистенты загружают при старте. Любой агент, открывший репозиторий, сразу находит готовую карту и пропускает привычное повторное изучение архитектуры. Пробежаться по сводке стоит намного меньше токенов и минут, чем снова прочёсывать исходники.

Обновления берутся из системы контроля версий. Инструмент смотрит, какие коммиты появились с прошлого запуска, читает диффы и переписывает только затронутые части. Если подключить его к CI-задаче по расписанию, вики обновляется сама каждый день и открывает pull request, как это сделал бы коллега-человек.

Grounded Claims: факты с приложенными доказательствами

Документацию генерирует множество инструментов. OpenWiki выделяется механизмом под названием Grounded Claims («обоснованные утверждения»), и он заслуживает внимательного разбора.

Каждое важное утверждение живёт в двух местах. Это проза на странице вики, а ещё структурированная запись в сопутствующем файле, которая указывает на точные строки кода, подтверждающие утверждение, вместе с хешем этих строк в том виде, в каком они были на тот момент.

Вот пример из тестового запуска. На странице сказано, что события «persisted to the run_events table before any listeners are invoked» (сохраняются в таблицу run_events до вызова каких-либо слушателей). Сопутствующая запись привязывает это предложение к строкам 9–26 одного файла. Измените эти строки — и сохранённый хеш перестанет совпадать, так что утверждение устареет. Устаревание заставляет перегенерировать страницу при следующем запуске, даже если планировщик обновлений счёл её нормальной.

В этом и разница между документацией и памятью. Документация ждёт, пока кто-нибудь заметит, что она неверна. Утверждение само знает, когда оно неверно, и само назначает себе ремонт. Документация не просто описывает код — её можно опровергнуть, сверив с ним.

Откуда взялась идея

OpenWiki появился не на пустом месте. В апреле 2026 года Андрей Карпатый, один из основателей OpenAI, опубликовал короткий gist с описанием «LLM Wiki» из трёх слоёв: неизменяемые исходники, markdown-вики, которую LLM поддерживает на их основе, и схема, описывающая организацию вики. Аргумент был направлен против retrieval-augmented generation — стандартной практики искать по документам в момент вопроса. Один раз скомпилируйте знания в долговечные страницы, говорил он, и они накапливаются. Каждый раз доставайте фрагменты — и они испаряются.

За несколько дней gist набрал больше 5000 звёзд, и LangChain называет его прямым источником вдохновения. С этой точки зрения OpenWiki — это набросок, превращённый в продукт, плюс Grounded Claims сверху. Результат пишется в Open Knowledge Format от Google версии 0.2 (спецификация OKF лежит в репозитории knowledge-catalog от Google), который должен позволить любому агенту потреблять упакованные знания. Markdown-вики как память агентов тихо становится общим паттерном, и OpenWiki — его самая полная на сегодня форма: за два месяца он собрал 15 000 звёзд на GitHub, выпуская новые релизы каждые несколько дней. Его собственный репозиторий документирован им же.

Практический тест: полностью open source

Если следовать официальной документации, облачная модель OpenAI или Anthropic может сгенерировать вики примерно за три минуты и около десяти центов — по отзывам сообщества. Тест посложнее — сможет ли всё работать на открытом стеке с локальной моделью, чтобы весь код оставался на машине.

Конфигурация

Четыре бесплатных открытых компонента:

• OpenWiki v0.4.0, установленный глобально через npm install.
• Ollama для локального запуска моделей. Встроенного провайдера Ollama нет, но OpenWiki умеет работать с любым OpenAI-совместимым эндпоинтом, а Ollama его предоставляет.
• Две модели с открытыми весами: сначала gpt-oss:20b от OpenAI (загрузка 13 ГБ), затем qwen3.5 4B от Alibaba (3,4 ГБ).
• Железо: ноутбук с 24 ГБ объединённой памяти, средний класс и совсем не рабочая станция.

Целью стал личный прототип Hangar — сервер оркестрации агентов с веб-интерфейсом. В нём 58 файлов на TypeScript, распределённых между сервером, веб-клиентом и примерами. Это настоящий код скромного размера, ничего экзотического.

Настройка провайдера — пара строк в ~/.openwiki/.env:

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, результаты сборки, lock-файлы и изображения. Он работает как жёсткая граница того, что будет прочитано, и с локальной моделью это вдвойне важно, ведь всё, что читает агент, должно протиснуться через окно поменьше.

Затем был запущен openwiki code --init --print, и он упал. Четыре раза, четырьмя разными способами. За каждым сбоем стоял урок, о котором текст ошибки так и не сказал, ведь этот текст от раза к разу почти не менялся.

Сбой 1: окно, о котором никто не сказал

Через две минуты первый запуск завершился одной строкой:

Repository planning worker exited without submit_plan.

Ни трассировки, ни причины. Причина лежала далеко за пределами OpenWiki. Ollama запускает каждую модель с контекстным окном на 4096 токенов — это рабочая память, которую модель видит за раз. Промпт сканирования репозитория во много раз больше. Ollama не выдаёт ошибку при переполнении. Она молча обрезает начало, так что модель так и не прочитала ту часть, где объяснялось, что существует инструмент submit_plan. ollama ps это подтвердил, показав модель с CONTEXT 4096.

Исправление — одна переменная окружения при запуске Ollama. Тому, кто захочет повторить эксперимент дома, эта строка нужнее любой другой:

OLLAMA_CONTEXT_LENGTH=32768 ollama serve

Сбой 2: то же сообщение, другая причина

С увеличенным окном планировщик снова упал — та же строка через те же две минуты. Вот где отладка локальных ИИ-стеков становится по-настоящему трудной: один текст ошибки, несколько первопричин и никакой телеметрии, чтобы их различить.

Следующим шагом стала проверка слоя ниже. Собранный вручную запрос к эндпоинту Ollama со схемой инструмента submit_plan показал бы, способна ли модель вообще сделать структурированный вызов инструмента:

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

Он вернул идеально оформленный вызов инструмента, причём у обеих моделей. По отдельности вся «сантехника» работала, значит, проблема была в транспорте между OpenWiki и Ollama. По умолчанию OpenWiki отправляет запросы без стриминга, а этому пайплайну нужен был стриминг. Ещё одна строка в файле .env:

OPENWIKI_OPENAI_COMPATIBLE_STREAMING=true

При следующем запуске планировщик прошёл.

Сбой 3: сильная модель, которая так и не сдала работу

Тут стало интересно. Когда планирование заработало, модель на 20B взялась за реальную работу. Вызовы растянулись с секунд до минуты с лишним, и через восемь минут на диске появилась настоящая страница вики: точное описание шины событий Hangar. Пути к файлам верные, поведение описано правильно (сначала сохранить, потом разослать), есть полноценная таблица полей. Это не шаблонная болванка. Модель поняла код.

А потом запуск всё равно упал:

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

Модель закончила трудную часть — написание, — а затем пропустила формальный вызов инструмента, которым страница сдаётся. Пайплайн выбросил страницу, которая уже лежала на диске. Проблема была не в способностях. Проблема была в том, чтобы довести дело до конца в хвосте длинного контекста.

Сбой 4: маленькая модель тоже споткнулась

Следующей была qwen3.5 4B — модель с одним из самых проверенных шаблонов вызова инструментов в Ollama, теперь с окном на 65 536 токенов. Она продвинулась дальше и завершила страницу шины событий вместе с её файлом утверждений, то есть весь пайплайн впервые отработал от начала до конца. А затем, на 51-й минуте и посреди второй страницы, упала со знакомым сообщением про submit_page.

Теперь причина была очевидна. Воркер страницы по ходу работы накапливает контекст: черновик, прочитанные доказательства и историю вызовов инструментов. В какой-то момент завершающая инструкция выпадает из окна, которое обрезается молча. Какая модель используется, значения не имело. Решающим было то, что делает слой сервинга, когда память заканчивается, а ответ — ничего, без всякого предупреждения.

Спасение: Ralph loop

Решение оказалось дурацким. Версия 0.4.0 сохраняет прогресс в надёжный файл запуска openwiki/.run.json, так что прерванная генерация продолжается с места остановки. Значит, инструмент, который падает каждые несколько страниц, можно починить, просто запуская его снова и снова, пока очередной запуск не завершится чисто.

Такой подход называют Ralph loop — в честь милого бестолкового мальчика из «Симпсонов»: намеренно тупой while-true, повторяющий одну и ту же команду, пока работа не будет сделана. Никто не ожидал, что он спасёт чужой продукт. Вся обвязка — несколько строк shell:

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 токенов, для запаса, и цикл запустили.

Шесть проходов и чуть меньше трёх часов спустя всё было готово. Первый проход сохранил четыре готовые страницы, второй — ещё четыре. Проходы с третьего по пятый застряли на одной трудной странице и ничего не сохранили — в этот момент наблюдающий человек, скорее всего, сдался бы. Шестой прошёл, и оставшиеся пятнадцать страниц пошли одним махом, ведь индексные и сводные страницы пишутся быстро. Итог — вики на 23 страницы с 18 обоснованными утверждениями, каждый факт привязан к захешированным доказательствам, и код выхода ноль.

Модель лучше не стала. Просто сбои перестали быть дорогими, и это работает лишь потому, что чекпоинт сохраняет готовую работу. Упорство вместе с файлом сохранения обыгрывает хрупкую изобретательность. В итоговой конфигурации репозиторий, агент, сервер моделей, модель, результаты и цикл повторов — всё находится на одной машине, а единственная линия, пересекающая границу, — та, которая никогда не используется.

Честное сравнение

Сравним два пути. Облачный занимает около трёх минут и примерно десять центов без лимита расходов, не требует особых навыков и отправляет код за пределы машины. Локальный занимает около четырёх часов от начала до конца и ничего не стоит, но требует диагностировать четыре слоя сбоев и построить обвязку с повторами, и ни один байт не покидает компьютер.

В большинстве случаев для большинства людей локальный путь того не стоит. Платить сорокакратным временем плюс экспертизой для поиска тихих сбоев ради экономии десяти центов — плохая сделка. Но когда коду нельзя покидать здание, это единственный выбор, и он явно работает.

Важнее другой вывод. Каждый сбой определялся конфигурацией, а не возможностями. Модели понимали код, и модель на 20B писала точные страницы об архитектуре. Каждый раз ломалась «сантехника»: окна по умолчанию, которые молча обрезают, транспорт, теряющий вызовы инструментов, и контекст, заканчивающийся без предупреждения. «Локальные модели недостаточно хороши» — неверный урок. Верный: локальные стеки сервинга всё ещё падают молча, и никто это не показывает. Это инженерная проблема, а не проблема масштаба модели, а инженерные проблемы решаются.

Стоит ли пробовать?

Если код и так ходит через облачные API, пробуйте прямо сейчас. Быстрый вариант работает, страницы хорошие, а ничего похожего на механизм утверждений на рынке больше нет. Несколько предупреждений об острых углах: сначала сделайте коммит, потому что init стирает существующую вики; следите за расходами через ключ с учётом, так как ничто не ограничивает траты, а отзывы сильно расходятся; и помните, что это ранний проект 0.x, который быстро меняется.

Для полностью приватного использования он на момент написания работает с исправлениями выше и некоторым терпением. Прежде всего увеличьте контекстное окно Ollama.

А для тех, кто уже хранит знания в markdown, общий вывод такой: отрасль со всех сторон сходится к одному ответу — простые текстовые файлы, которые поддерживают агенты и исправляют доказательства. Продукт — не вики. Продукт — цикл исправления, и OpenWiki — первый инструмент, который поставляет его с квитанциями.