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 — перший інструмент, що постачає його з квитанціями.