ERP Platform Docs

Решение

время чтения ~5 мин.

ADR-022 (решение, ревизия 2): OpenClaw — выбор технологии для AI-агента

Ревизия 2 — 2026-05-13 (поздний вечер)

Первый раз 13.05 утром приняли самопис на Node + ReAct loop (erp-openclaw-agent + erp-llm-gateway). После 6 часов отладки выяснилось, что Qwen 14B Q5 на тонком промпт-инжиниринге не справляется надёжно с tool calling: путал UUID, копировал placeholder’ы, параллелил tool calls с зависимостями. Заодно обнаружили, что существует open-source mainstream-проект OpenClaw (Питер Штайнбергер, 371k звёзд, MIT, https://openclaw.ai) — ровно тот use-case (агент + skills + ollama backend), что мы писали руками. Решили выкинуть самопис и переехать на готовый фреймворк.

Решение (финальное)

OpenClaw + наш custom MCP-server erp-openclaw-skills + Qwen 2.5 14B (Ollama):

┌─────────── VPS (erp-test.nirbi.ru) ───────────┐
│ admin-web → admin-bff → ws-shim (новый)        │
│                            ↓ WebSocket+token   │
└────────────────────────────┼───────────────────┘
                             │ (autossh -R 18789)
┌─────────────── Windows ────┼───────────────────┐
│        OpenClaw Gateway :18789                 │
│            ↓ ollama provider                    │
│        Ollama (в WSL2 Ubuntu-24.04)            │
│            └── qwen2.5:14b-instruct-q5_k_m      │
│                                                 │
│        MCP-servers (subprocess через stdio):    │
│        ├── @mcp/server-filesystem → obsidian_erp│
│        │   (read-only docs, daily git pull)     │
│        └── erp-openclaw-skills (custom)         │
│            └─ 6 tools → HTTPS к erp-test.nirbi.ru│
└─────────────────────────────────────────────────┘

Что строим:

  1. OpenClaw Gateway на Windows native (рядом с WSL2 + Ollama, runbook: Windows OpenClaw Setup)
  2. MCP obsidian-vault — @modelcontextprotocol/server-filesystem с путём к локально склонированному obsidian_erp (daily git pull). Агент имеет read-only доступ к документации: ADR, бизнес-спекам, контрактам сервисов
  3. MCP erp-skills — наш собственный (nearbyErp/erp-openclaw-skills, MIT, https://github.com/nearbyErp/erp-openclaw-skills), 6 tools:
    • find_stores(query) — Store Service /api/v1/admin/stores?search=
    • find_products(query, store_id) — Catalog /api/v1/admin/catalog/products
    • get_stoplist(store_id) — Catalog /api/v1/admin/catalog/stop-lists/stores/{id}
    • add_to_stoplist(product_id, store_id) — Catalog
    • get_sales_summary(store_id, from, to?) — Order Service list + агрегация
    • create_order — STUB на MVP, нужен новый admin endpoint в order-service (fast-follow)
  4. WebSocket-shim в admin-bff — переписан /api/v1/admin/agent/chat на JSON-RPC поверх WebSocket к OpenClaw (вместо OpenAI-compat REST). SSE-стрим к UI остаётся без изменений
  5. Auth — один service-token JWT (TTL 90 дней) с правами Администратора синтетического тенанта, прокинут в erp-skills через env. Для MVP. После демо — pass-through юзерского JWT

Что выкинуто (по сравнению с Ревизией 1)

Сервис/модульСудьба
erp-openclaw-agentУдаляется — OpenClaw сам держит агента + memory + ReAct loop
erp-llm-gatewayУдаляется — OpenClaw сам ходит в Ollama напрямую
Парсер <tool_call> блоковУдаляется — OpenClaw делает это лучше
Самописный системный промпт с правиламиУдаляется — в config OpenClaw, мы только пишем сам текст
Своя БД agent_db для conversationsУдаляется — OpenClaw держит sessions
Наш tool registryУдаляется — заменяется MCP-протоколом

Что сохранили из Ревизии 1

ЧтоИспользование
Windows WSL2 + Ollama + Qwen 14B (ADR-023)Backend OpenClaw
autossh reverse SSH tunnelИспользуем — пробрасываем 18789 рядом с 11434
socat-bridge на VPSНе нужен больше для tools (OpenClaw сам ходит наружу через HTTPS к erp-test.nirbi.ru) — можно удалить
Admin BFF SSE-proxyПереписан на WebSocket-client
Admin Web <AgentChatBubble />Без изменений — UI говорит с admin-bff тем же протоколом
User Service permissions agent.use + agent.configБез изменений

Что добавилось ценного

  • Доступ к Obsidian-vault — теперь агент знает архитектуру системы, может ответить «как устроено X», «где описано Y», «что в ADR-022» и т.п. Это расширяет use-case от «оператор для CRUD» до «техно-консультант + оператор»
  • Profession-tested промпт-инжиниринг OpenClaw (371k звёзд, mainstream) — не отлаживаем сами
  • Готовые MCP-серверы для других use-case на будущее (Slack, GitHub, и т.д.)
  • Memory между сессиями — встроена в OpenClaw

Почему не GPT-4o / Yandex GPT (платные API)

Бизнес-ограничение от 2026-05-12: не платим за per-token API. Решение в Ревизии 1 действует — используем локальную модель. Архитектура OpenClaw не блокирует переход на платный API (просто меняется конфиг provider), но на MVP остаёмся на Qwen 14B.

Последствия

Положительные

  • ✅ Не пишем 2 микросервиса (erp-openclaw-agent + erp-llm-gateway) — экономия ~500 строк кода и недели отладки
  • ✅ Промпт-инжиниринг tool calling — за OpenClaw, не наш (он уже отлажен)
  • ✅ Доступ к vault через MCP — бесплатный wow-эффект на демо («агент знает архитектуру системы»)
  • ✅ Стандартный протокол MCP — переиспользуем для других use-case ERP в будущем (заказы из Telegram, slack-бот для команды, etc)
  • ✅ Когда модель будет лучше (Qwen 3 / 32B / коммерческие API) — меняем 1 строку конфига

Отрицательные

  • ❌ Зависимость от mainstream open-source проекта (но MIT + 371k звёзд = риск минимален)
  • ❌ MCP-стандарт ещё юный (релиз 2024) — могут быть breaking changes. Митигация: pin версию @modelcontextprotocol/sdk в erp-openclaw-skills
  • ❌ Архитектура чуть сложнее (OpenClaw + 2 MCP-server + ws-shim) — но мы её не отлаживаем, только конфигурируем
  • ❌ create_order пока недоступен (нужен новый admin endpoint) — демо-сценарий 3 урезается до info-агента: «что в стоп-листе», «сколько продали», «найди товары X»

Риски

  • ⚠️ Windows-хост Алексея — single point of failure для всего AI-функционала. Митигация: на демо запасной ноут с предзагруженной моделью
  • ⚠️ Qwen 14B Q5 всё ещё может тупить даже с OpenClaw — но OpenClaw имеет встроенный механизм retry и более качественный promptmgmt. Митигация: бизнес-сценарии демо проиграть за 3 дня до показа
  • ⚠️ create_order не работает на MVP — снижает wow-эффект. Митигация: показать на демо чат с info-сценариями («сколько продали в Арбате за неделю», «что в стоп-листе») + кратко рассказать что create order в roadmap

Ссылки

Вид графа

Обратные ссылки