AI overlay над OpenClaw: Telegram-бот, 18 role-based skills, FastAPI gateway, RAG, LangGraph intent routing и multi-LLM provider orchestration.
Kent — это инженерный показ agentic workflow design: как собрать управляемую систему из ролей, инструментов, контекста, проверок, интеграций и эксплуатационных ограничений.
Проект не заявляет себя как автономный сотрудник без границ. Kent показывает более практичный подход: role-based skills в OpenClaw, явный intent-routing workflow в LangGraph, RAG-контекст через PostgreSQL + pgvector, provider factory для нескольких LLM и контур regression evals.
Снаружи Kent выглядит как Telegram-бот с личностью, памятью, файлами, голосом, интеграциями и готовым деплоем на VPS. Внутри это overlay над платформой OpenClaw, где OpenClaw запускается в отдельном Docker-контейнере и оркестрирует 18 кастомных skills из workspace/skills/.
Каждый skill — это роль с собственным назначением, инструментами и контекстом. Такой дизайн ближе к production agentic workflow architecture, чем к одному большому prompt-у: поведение разбито на управляемые роли, маршруты, проверки и точки интеграции.
FastAPI gateway в api/main.py открывает 26 REST endpoints и 1 WebSocket. Через него доступны системные проверки, каталог skills и интеграций, proxy к агентам и чату, memory API, LangChain/RAG endpoints, LangGraph workflow и multi-LLM endpoints.
LangGraph используется как реальный StateGraph с conditional routing: classify_intent маршрутизирует запрос в handle_greeting, handle_question или handle_command. Ветка handle_question обогащает запрос RAG-контекстом. Это intent-routing workflow, доступный через POST /langgraph/workflow.
LangChain используется для LCEL chains, RAG и PGVector поверх PostgreSQL + pgvector. Embeddings работают через OpenAI text-embedding-3-small или mock-режим. Отдельно существует memory-система /memory/*.
Multi-LLM слой в api/russian_llm.py реализован как provider factory: абстрактный LLMProvider, 5 реализаций, реестр PROVIDER_CLASSES и ChatResponse с tracking-ом провайдера. В режиме KENT_RUSSIA_COMPLIANCE_MODE=true OpenAI и Anthropic блокируются на уровне provider factory.
Цель проекта — показать, как AI/LLM application engineering выглядит за пределами демо: FastAPI, Python, Docker, RAG, provider routing, compliance constraints, evals, observability, cost control и поставляемый deployment.
| Аудитория | Что смотреть |
|---|---|
| Работодателям | пример AI / LLM Application Engineering: FastAPI, RAG, LangGraph StateGraph, provider orchestration, evals, reliability, compliance |
| Разработчикам | overlay над OpenClaw с 18 role-based skills, Docker Compose, OpenAPI, WebSocket, тестами и CI |
| Предпринимателям | как упаковать AI-ассистента в B2B-продукт: Product Blueprint и Tech Plan |
| Клиентам | bash install.sh → персональный Telegram-бот на VPS с интеграциями и настройками |
bash <(curl -fsSL https://raw.githubusercontent.com/Refusned/Kent-Overlay/main/install.sh)Ручной деплой:
./prerequisites.sh
./configure.sh
./deploy.shПосле запуска:
FastAPI: http://localhost:8000
Swagger: http://localhost:8000/docs
Health: http://localhost:8000/health
Bot: https://t.me/ask_kent_bot
| Core | Telegram-чат с личностью и памятью, онбординг, голосовые, файлы, генерация картинок, веб-поиск, TTS |
| Role-based skills | 18 OpenClaw skills в workspace/skills/: каждая роль описывает поведение, инструменты и контекст |
| Agentic workflow | LangGraph StateGraph: classify_intent → conditional edges → handle_greeting / handle_question / handle_command |
| API Gateway | FastAPI на порту 8000: 26 REST endpoints + WebSocket /ws/events, Swagger UI на /docs, Bearer auth, rate limiting |
| RAG | langchain-postgres PGVector поверх PostgreSQL + pgvector, embeddings OpenAI text-embedding-3-small или mock, LCEL chains |
| Memory | отдельные endpoints /memory/store, /memory/search, /memory/stats |
| Multi-LLM | Mock, YandexGPT, GigaChat, OpenAI, Anthropic через единый LLMProvider contract |
| Compliance | KENT_RUSSIA_COMPLIANCE_MODE=true форсит РФ-only providers: yandex, gigachat |
| Reliability | /health/detailed, cost ceiling, PII redaction в логах, integration guide |
| Evals | regression gold set на 15 запросов, pytest-harness, cost report |
| Автоматизация | cron-задачи для брифингов, health-check, отчётов, SMM и backup |
| Рецепты | 31 KentBytes в 6 категориях |
| Интеграции | Google Workspace, ElevenLabs TTS, DALL-E, Yandex IoT |
| Deployment | Docker Compose, non-root containers, healthchecks, cap_drop ALL, GitHub Actions CI, идемпотентный install.sh |
Скиллы находятся в workspace/skills/ и оформлены как роли с tools и контекстом:
alice-smarthome
broadcast-composer
coder
content-calendar
crm-notes
doc-generator
email-triage
faq-responder
finance-tracker
humanize
idea-reality
lead-capture
pptx-manager
smm-manager
social-drafts
weather-fallback
weekly-roi-report
youtube-summary
Это не 18 LangGraph-агентов. Это role-based design поверх OpenClaw: OpenClaw отвечает за workspace, skills, hooks и runtime-контекст, а Kent добавляет доменную логику, API gateway, RAG, provider routing и проверки.
api/main.py содержит 26 REST endpoints и 1 WebSocket.
| Группа | Endpoints |
|---|---|
| System | /health, /version, /metrics, /openclaw/status, /config |
| Catalog | /skills, /integrations, /kentbytes, /soul |
| Proxy | /agents, /chat, /webhooks/telegram |
| Memory | /memory/store, /memory/search, /memory/stats |
| LangChain | /langchain/info, /langchain/chain, /langchain/rag/add, /langchain/rag/search |
| LangGraph | /langgraph/workflow |
| LLM | /llm/providers, /llm/chat |
| Events | WebSocket /ws/events |
Gateway поддерживает опциональную Bearer auth, rate limiting через slowapi и OpenAPI/Swagger на /docs.
- Ubuntu 24.04 LTS
- 4 GB RAM, 2 vCPU, 40 GB SSD
- Docker 24+
- Telegram Bot Token от @BotFather
- API keys для выбранных LLM-провайдеров
- PostgreSQL + pgvector через Docker Compose
- Подписка OpenAI Codex, если используется соответствующий workflow
| Документ | Описание |
|---|---|
| READINESS.md | Матрица готовности компонентов |
| docs/DEPLOYMENT.md | Гайд по деплою |
| docs/CONFIG-REFERENCE.md | Справочник по конфигурации |
| docs/INTEGRATIONS.md | Настройка интеграций |
| docs/TROUBLESHOOTING.md | Решение проблем |
| docs/CUSTOMIZATION.md | Кастомизация под клиента |
| docs/known_limitations.md | Границы продукта и не закрытые сценарии |
| docs/failure_modes.md | Таксономия отказов: intent, RAG, tools, policy, providers |
| api/reliability/INTEGRATION.md | Подключение reliability-слоя |
bash tests/run-all.sh # static + deploy тесты
bash tests/run-all.sh smoke # smoke-тесты, требуют запущенный инстансРучной чеклист: tests/MANUAL-SMOKE-CHECKLIST.md
Regression harness для LLM-поведения:
python evals/run_regression.pyReliability-слой покрыт 19 тестами. Evals в evals/ проверяют маршрутизацию, policy decisions, RAG-сценарии, prompt injection, long context и PII-sensitive кейсы.
graph TB
User([Telegram User]) --> Bot[Telegram Bot]
Bot --> Gateway[FastAPI Gateway :8000<br/>26 REST endpoints · WebSocket<br/>Bearer auth · slowapi · Swagger]
Gateway --> OpenClaw[OpenClaw Container<br/>workspace · skills · hooks · cron]
OpenClaw --> Skills[18 OpenClaw Skills<br/>role-based design<br/>tools · context · behavior]
OpenClaw --> Bytes[31 KentBytes<br/>6 категорий рецептов]
OpenClaw --> Cron[Cron Jobs<br/>briefing · health · reports · SMM · backup]
Gateway --> LangGraph[LangGraph StateGraph<br/>intent routing]
LangGraph --> Classify[classify_intent<br/>rule-based]
Classify --> Greeting[handle_greeting]
Classify --> Question[handle_question<br/>RAG context enrichment]
Classify --> Command[handle_command]
Question --> RAG[LangChain RAG<br/>LCEL chains]
RAG --> PGVector[(PostgreSQL + pgvector<br/>langchain-postgres PGVector)]
RAG --> Embeddings[Embeddings<br/>text-embedding-3-small or mock]
Gateway --> Memory[(Memory API<br/>store · search · stats)]
Gateway --> LLM{Multi-LLM Provider Factory<br/>LLMProvider ABC}
LLM --> Mock[Mock]
LLM --> OpenAI[OpenAI]
LLM --> Anthropic[Anthropic]
LLM --> Yandex[YandexGPT]
LLM --> GigaChat[GigaChat]
LLM --> Compliance[Russia Compliance Mode<br/>YandexGPT · GigaChat only]
OpenClaw --> Integrations[External Integrations]
Integrations --> Google[Google Workspace]
Integrations --> ElevenLabs[ElevenLabs TTS]
Integrations --> DALLE[DALL-E]
Integrations --> IoT[Yandex IoT]
Gateway --> Reliability[api/reliability<br/>health · cost ceiling · PII redaction]
Reliability --> Metrics[Metrics + structured logs]
Gateway --> Evals[Evals<br/>15 gold queries · pytest harness · cost report]
style User fill:#5b8def,color:#fff
style Gateway fill:#009688,color:#fff
style OpenClaw fill:#f7a072,color:#000
style LangGraph fill:#2563eb,color:#fff
style PGVector fill:#003b57,color:#fff
style LLM fill:#9333ea,color:#fff
style Reliability fill:#0f766e,color:#fff
style Evals fill:#334155,color:#fff
Ключевые архитектурные решения:
- Hardened Docker Compose — non-root containers, healthchecks,
cap_drop ALL, изоляция сервисов и предсказуемый VPS deployment. - Overlay над OpenClaw — Kent не переписывает agent runtime, а добавляет доменную логику, skills, API gateway, RAG, provider routing и эксплуатационные проверки.
- Role-based agent design — 18 OpenClaw skills оформлены как роли с tools и контекстом.
- LangGraph intent routing — реальный
StateGraphсWorkflowState, rule-basedclassify_intentи conditional edges к greeting/question/command handlers. - RAG через PostgreSQL + pgvector —
langchain-postgresPGVector, embeddings OpenAItext-embedding-3-smallили mock, LCEL chains. - Multi-LLM Provider Factory — единый контракт для Mock, YandexGPT, GigaChat, OpenAI, Anthropic и provider tracking в
ChatResponse. - Compliance-aware routing —
KENT_RUSSIA_COMPLIANCE_MODE=trueблокирует OpenAI и Anthropic черезValueError. - Контур проверки — regression gold set, pytest-harness, cost report, reliability tests и failure taxonomy.
- Идемпотентный деплой —
prerequisites.sh → configure.sh → deploy.sh, повторный запуск без ручной чистки окружения.
Структура файлов
kent-overlay/
workspace/ # OpenClaw overlay: личность, правила, память, skills
SOUL.md # Характер и тон
SECURITY.md # Правила безопасности
AGENTS.md # Операционное поведение
skills/ # 18 OpenClaw role-based skills
kentbytes/ # 31 рецепт в 6 категориях
api/ # FastAPI gateway
main.py # 26 REST endpoints + WebSocket /ws/events
langchain_module.py # LangChain, RAG, LangGraph StateGraph
russian_llm.py # Multi-LLM provider factory + compliance routing
reliability/ # healthcheck, cost ceiling, PII redaction
Dockerfile # python:3.12-slim, non-root user, healthcheck
requirements.txt # fastapi + uvicorn + pydantic + langchain
config/
openclaw.json # Конфиг OpenClaw
docker/
docker-compose.yml # openclaw + browser + api + postgres services
demo/ # Конфигурация публичного демо-бота
evals/ # Regression gold set + pytest harness + cost report
tests/ # Автоматические и ручные тесты + k6 load-test
docs/ # Документация, limitations, failure taxonomy
Kent сделан как overlay над OpenClaw, потому что цель проекта — не написать ещё один runtime для агентов. Цель — собрать поставляемую систему: Telegram-бот, skills, память, cron-задачи, интеграции, policy, API gateway, деплой и эксплуатационные проверки.
OpenClaw закрывает базовые вещи, которые легко недооценить: workspace-модель, hooks, skills, cron, операционные правила и структуру runtime. Если писать это с нуля, большая часть времени ушла бы не на поведение Kent, а на инфраструктурное повторение.
Trade-off в том, что overlay наследует ограничения платформы. Kent должен жить в модели OpenClaw skills и не может свободно менять все внутренние абстракции OpenClaw. Для B2B-ассистента это приемлемая цена: предсказуемая поставка и понятный runtime важнее экспериментальной свободы в каждом слое.
Именно поэтому 18 кастомных возможностей Kent оформлены как OpenClaw skills. Это role-based agent design: каждый skill получает свою роль, контекст и набор инструментов.
LangGraph в Kent используется не как список отдельных агентов и не только как RAG-роутер. В api/langchain_module.py реализован StateGraph с состоянием WorkflowState.
Workflow начинается с classify_intent. Это rule-based классификация намерения, после которой conditional edges ведут в один из обработчиков: handle_greeting, handle_question или handle_command.
handle_question обогащает пользовательский запрос RAG-контекстом. handle_greeting и handle_command отвечают за другие классы намерений. Такой workflow показывает главное: маршрутизация явно описана в графе, а не спрятана в одном prompt-е.
Это честная и расширяемая точка для agentic workflow architecture. Следующий шаг роста — добавлять узлы-агенты, tool-use и проверки на уровне отдельных узлов, сохраняя наблюдаемость и контролируемые переходы.
Для RAG можно было использовать Qdrant, Chroma или pgvector. Qdrant хорош как отдельная vector database для крупных workloads. Chroma удобен для локальных прототипов и быстрых LangChain-экспериментов.
Kent — не отдельный RAG-песочник. Ему нужны пользователи, история, документы, метаданные, категории, KentBytes, права доступа и semantic search в одном деплое. PostgreSQL уже нужен проекту, поэтому pgvector уменьшает число stateful-сервисов.
Это упрощает Docker Compose, backup policy, миграции, healthchecks, сетевые права и восстановление. Для продукта, который должен ставиться на VPS клиента, один PostgreSQL с pgvector практичнее, чем отдельная vector DB рядом.
Trade-off понятный: на десятках миллионов чанков Qdrant может стать лучшим выбором. На текущем масштабе правильнее держать данные в PostgreSQL и улучшать retrieval через metadata filtering, hybrid ranking и проверку источников.
Наивный multi-LLM слой выглядит как generate(prompt) -> text. В реальности этого недостаточно. OpenAI, Anthropic, YandexGPT и GigaChat отличаются форматами сообщений, system prompt, latency, ценой, качеством русского языка, tool calling и требованиями к безопасности.
Kent использует абстрактный LLMProvider и 5 реализаций: Mock, YandexGPT, GigaChat, OpenAI, Anthropic. Реестр PROVIDER_CLASSES позволяет выбирать провайдера через единый слой, а ChatResponse сохраняет provider tracking.
Контракт не делает вид, что все провайдеры одинаковые. Провайдер-специфичные ограничения остаются явными: где-то хуже tool calling, где-то выше latency, где-то лучше русский язык, где-то нельзя отправлять персональные данные.
152-ФЗ режим влияет на routing напрямую. При KENT_RUSSIA_COMPLIANCE_MODE=true зарубежные провайдеры блокируются, а fallback не имеет права отправить запрос в OpenAI или Anthropic, даже если они технически доступны.
Первый failure mode — неверная классификация intent. Запрос напомни мне завтра отправить договор может быть задачей, событием календаря, CRM-действием или вопросом о том, как поставить напоминание. Если система сразу делает tool call без уточнения, она может выполнить лишнее действие.
Второй failure mode — RAG достал соседний документ. Пользователь спрашивает про договор с Ивановым, а в базе несколько Ивановых или несколько версий договора. Semantic search может вернуть похожий, но неверный фрагмент. Поэтому важны metadata filters, имена файлов, даты, точные совпадения и ссылки на источник.
Третий failure mode — tool выглядит допустимым, но у пользователя нет прав. Google Workspace может быть не подключен, token может истечь, календарь может быть read-only, Telegram-файл может быть недоступен после истечения срока хранения. Правильный ответ — не готово, а честное состояние: что не выполнено и какое действие нужно от пользователя.
Четвёртый failure mode — провайдер недоступен, а fallback меняет политику данных. Это опасно для файлов с клиентами, договорами и персональными данными. В 152-ФЗ режиме fallback должен учитывать policy, а не только uptime.
Cost control сделан как runtime-ограничение. Модуль api/reliability/cost_ceiling.py работает с дневным лимитом расходов и не даёт router-у продолжать дорогие LLM-вызовы после достижения потолка.
Это важно для Telegram-бота: пользовательский трафик может прийти внезапно, а ошибка в retry loop или prompt loop способна быстро съесть бюджет. Дневной лимит нужен как предохранитель для публичного endpoint-а.
Стоимость считается по провайдерам. Это позволяет увидеть, какой маршрут стал дорогим: RAG summarization, tool retry, fallback, генерация изображений, voice pipeline или long-context обработка.
Trade-off: жёсткий ceiling может отказать нормальному пользователю. Для production-проекта это лучше, чем неограниченный расход. При достижении лимита Kent должен деградировать явно: короткий ответ, дешёвый provider, отказ от image generation, отложенная задача или сообщение о лимите.
Fine-tuning не используется в v1. Для текущих задач Kent важнее RAG, policy, routing, evals и интеграции. Fine-tuning не решает проблему доступа к свежим документам клиента и не заменяет проверку источников.
GraphRAG тоже не включён в v1. Он может быть полезен для корпоративных баз знаний, где есть сущности, связи и устойчивые онтологии. Для текущего продукта это добавило бы сложность в ingestion, хранение, evals и объяснение результатов.
Kent не делает вид, что является fully autonomous employee. Он может выполнять действия через tools, но должен останавливаться на границах прав, денег, персональных данных и необратимых операций. Это продуктовая граница, а не недоработка.
Основной принцип v1: сначала надёжный overlay, понятный деплой, честные failure modes и измеряемое поведение. Более сложные агентные паттерны имеют смысл после того, как базовый workflow стабилен в эксплуатации.
Reliability-слой лежит в api/reliability/ и подключается по инструкции из api/reliability/INTEGRATION.md. Он не заменяет бизнес-логику skills, а добавляет эксплуатационные предохранители вокруг API Gateway и provider routing.
healthcheck расширяет базовый /health до /health/detailed. Он проверяет не только то, что FastAPI отвечает, но и состояние LLM-провайдеров, PostgreSQL, pgvector, ключевых интеграций и конфигурации compliance mode.
cost_ceiling.py контролирует дневной лимит расходов. Лимит задаётся через конфигурацию, а runtime-логика должна останавливать или удешевлять LLM-маршруты до того, как расход станет проблемой.
PII redaction применяется к логам. Система не должна писать в structured logs телефоны, email, токены, фрагменты документов и персональные данные в открытом виде.
Graceful provider fallback работает с учётом policy. Если OpenAI недоступен, fallback может перейти на другого провайдера только если это разрешено задачей и режимом compliance. В 152-ФЗ режиме fallback на зарубежного провайдера блокируется.
Reliability-слой покрыт 19 тестами. Это отдельный эксплуатационный контур, а не часть демо-сценария.
В evals/ хранится regression gold set из 15 эталонных запросов. Он покрывает категории tool_calling, RAG, ambiguous, prompt_injection, long_context, pii_sensitive, edge_case.
Цель evals — не доказать, что модель умная. Цель практичнее: не ломать уже найденные сценарии. Если запрос вчера шёл в RAG, а сегодня вызывает IoT-команду, это regression. Если запрос с персональными данными ушёл в запрещённого провайдера, это regression.
evals/run_regression.py запускает pytest-harness и проверяет маршрутизацию, формат ответа, использование источников, policy decisions и базовые safety-инварианты.
Cost report по провайдерам показывает, куда уходит бюджет: OpenAI, Anthropic, YandexGPT, GigaChat, fallback-и и повторные попытки. Это позволяет обсуждать стоимость как инженерный параметр.
Таксономия отказов описана в docs/failure_modes.md. Там фиксируются повторяющиеся классы проблем: intent mismatch, wrong retrieval, missing permissions, provider outage, compliance block, prompt injection, long-context degradation и PII leakage risk.
Для коммерческих развёртываний с обработкой ПДн российских граждан Kent поддерживает on-prem РФ-only режим. Установи переменную окружения:
KENT_RUSSIA_COMPLIANCE_MODE=trueВ этом режиме:
- доступны только российские LLM-провайдеры:
yandex,gigachat; - запросы к OpenAI и Anthropic блокируются с
ValueErrorна уровне Provider Factory; GET /llm/providersпомечает заблокированные провайдеры какblocked_by_compliance: true;- provider fallback не может менять data residency;
- логи должны проходить через PII redaction перед записью.
Это позволяет деплоить Kent в enterprise-сценариях, где нельзя передавать персональные данные зарубежным LLM-провайдерам.
152-ФЗ режим не означает, что продукт автоматически закрывает все юридические требования клиента. Нужны договоры, регламенты доступа, политика хранения, назначение ответственных и корректная настройка инфраструктуры. Kent закрывает техническую сторону provider routing и блокировки запрещённых маршрутов.
Kent поставляется через Docker Compose и shell-скрипты:
./prerequisites.sh
./configure.sh
./deploy.shinstall.sh объединяет шаги в один идемпотентный сценарий установки. Его можно запускать повторно: он рассчитан на VPS deployment, где важно восстановиться после частичной настройки.
Docker Compose использует non-root containers, healthchecks и cap_drop ALL. FastAPI контейнер собирается на python:3.12-slim и имеет собственный healthcheck.
CI настроен через GitHub Actions:
.github/workflows/static-checks.yml
.github/workflows/ci-python.yml
Проверки включают static checks и Python CI. Для ручного smoke-тестирования есть tests/MANUAL-SMOKE-CHECKLIST.md.
Проверка здоровья:
curl http://localhost:8000/healthСписок провайдеров:
curl http://localhost:8000/llm/providersЗапрос к LLM:
curl -X POST "http://localhost:8000/llm/chat?provider=yandex" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Суммируй встречу в 5 пунктах"}]}'Запуск LangGraph workflow:
curl -X POST http://localhost:8000/langgraph/workflow \
-H "Content-Type: application/json" \
-d '{"message":"Найди в базе договор с Ивановым"}'Добавление документа в RAG:
curl -X POST http://localhost:8000/langchain/rag/add \
-H "Content-Type: application/json" \
-d '{"text":"Документ для индексации","metadata":{"source":"manual"}}'Поиск в RAG:
curl -X POST http://localhost:8000/langchain/rag/search \
-H "Content-Type: application/json" \
-d '{"query":"Что известно по договору?"}'1.0.0 | OpenClaw 2026.4.10 | LangGraph 0.2.59 | LangChain 0.3.10 | CHANGELOG.md
Создан и поддерживается Романом Барминым (@Refusned).
Роман ищет работу AI / LLM Application Engineer | Agentic Workflow Architect.
Фокус: Python, FastAPI, RAG, LangGraph workflows, OpenClaw skills, provider routing, agent tooling, Docker, evals, observability, production deployment.
Контакты:
- Telegram: @ask_kent_bot (демо-бот)
- Email: refusned@gmail.com
- GitHub: github.com/Refusned
Pet projects: Kent, Hyper Bot, WB Bot, Agent Teams и др.

