План интеграции OpenClaw Channels в Синаполис

План интеграции OpenClaw Channels в Синаполис

Статус: нормативный целевой план и операционный ориентир. Версия от 19 мая 2026. Документ предназначен для внешнего чтения, но написан с достаточной детализацией для операторов.

Назначение

Цель интеграции OpenClaw Channels в Синаполис — повысить приоритетность, связанность и проверяемость коммуникаций между внешними каналами, приёмным контуром и агентами, не разрушая уже действующий официальный Telegram-ingress.

Это означает:

• Синаполис должен принимать обращения из нескольких внешних каналов через OpenClaw Gateway.
• При этом в текущем контуре должен сохраняться один официальный Telegram-вход через @EchoIntakeBot.
• Интеграция должна вести не к “ещё одному хаотичному чату”, а к проверяемому жизненному циклу сообщения: received -> queued -> delivered -> ack_received -> answered/closed.
• Групповые каналы должны работать только по явному обращению, а не через фоновое поглощение всего потока сообщений.

Нормативный принцип

OpenClaw Channels в Синаполисе рассматриваются не как самостоятельная “личность в Telegram”, а как транспортно-маршрутизационный слой между внешними чатами и серверным коммуникационным контуром Синаполиса.

Следовательно:

• каналы подключаются через OpenClaw Gateway;
• каналы могут работать одновременно;
• маршрутизация ответа должна быть детерминированной по исходному чату;
• агенты Синаполиса интегрируются не через прямые Telegram-аккаунты, а через server-side inbox/bus/ack/readback;
• Telegram-токен действующего intake-бота не передаётся OpenClaw без отдельной санкционированной миграции.

Согласно OpenClaw docs, каждый канал подключается через Gateway, текст поддерживается повсеместно, а media/reactions зависят от конкретного канала; несколько каналов могут работать параллельно, а routing идёт per chat.
Источник: OpenClaw Chat channels.

Конечное целевое состояние

Архитектура верхнего уровня

Внешние каналы
  -> OpenClaw Gateway / channel adapters
  -> Synapolis reception
  -> OpenClaw queue
  -> router
  -> agent inbox
  -> ACK / readback
  -> lifecycle dashboard
  -> controlled outbound replies

При этом для Telegram в текущей целевой модели действует важная оговорка:

• официальный live-ingress остаётся на @EchoIntakeBot;
• OpenClaw Telegram channel разрешён только в sandbox/new-token режиме либо в отдельной будущей controlled migration;
• до отдельного решения OpenClaw не должен забирать live Telegram token или webhook действующего intake-контура.

Что значит “как это должно выглядеть в конечном итоге”

В конечном состоянии любой поддержанный канал должен вести себя для Синаполиса одинаково на уровне управления:

• внешнее сообщение получает machine-readable intake receipt;
• сообщение попадает в нормализованную очередь;
• routing выбирает целевого агента по routing map и alias policy;
• доставка в inbox агента фиксируется отдельно от факта отправки;
• агент или его системный адаптер обязан вернуть ACK/readback;
• система умеет контролируемо отправить итоговый ответ обратно в исходный канал;
• оператор видит жизненный цикл тикета на едином dashboard;
• если канал не поддерживает native read receipts, это компенсируется server-side ACK/readback, а не ложной “магией чата”.

Ingress policy

Telegram policy на текущем этапе

Нормативно закрепляется следующее:

• единственный официальный Telegram-ingress сейчас — @EchoIntakeBot;
• @EchoIntakeBot остаётся pure Telegram wrapper / transport shell, а не LLM/agent;
• Filum остаётся primary server-native workhorse для этого контура;
• OpenClaw не получает контроль над live token или live webhook @EchoIntakeBot без отдельной авторизованной миграции;
• OpenClaw Telegram channel допускается только как sandbox/new-token контур или как специально утверждённый миграционный контур с rollback-планом.

Группы и явное обращение

Для Синаполиса обязательна модель explicit-address only:

• никакого blanket ingestion всего группового потока;
• group messages должны обрабатываться только по явному mention/target/prefix;
• в действующем контуре Ductor используется group_mention_only=true;
• @EchoIntakeBot уже обслуживает group messages только при явном @EchoIntakeBot mention;
• эта же логика должна быть сохранена и в OpenClaw-facing policy.

OpenClaw docs подтверждают fail-closed модель для групп:

• по умолчанию группы ограничены через groupPolicy: "allowlist";
• replies в группах требуют mention, если это явно не отключено;
• проверка идёт по цепочке groupPolicy -> group allowlist -> requireMention;
• DM pairing не должен автоматически открывать group authorization;
• DM и group sessions разделены.

Источники:

• OpenClaw Groups
• OpenClaw Telegram

Нормативное правило allowlists

Для всех внешних каналов должны быть разделены:

• allowlist разрешённых group/channel peer IDs;
• allowlist разрешённых sender IDs внутри разрешённых групп;
• mention gating policy;
• optional per-group/per-channel tool restrictions.

Для Telegram это означает:

• chat/group IDs хранятся в allowlist групп, а не в sender allowlist;
• user IDs хранятся в sender allowlist;
• default policy должна оставаться fail-closed;
• requireMention=true должно считаться нормой по умолчанию.

Сессии и routing

OpenClaw хранит DMs и группы раздельно, а routing детерминирован по входному каналу и peer. Для Синаполиса это важно по двум причинам:

• личный DM-контекст не должен смешиваться с group/session контекстом;
• forum topics, group rooms и channel rooms должны сохранять отдельные session keys, чтобы маршрутизация и безопасность были проверяемы.

Источники:

• OpenClaw Channel routing
• OpenClaw Group messages

Policy интеграции агентов

Базовое правило

Агенты Синаполиса интегрируются с OpenClaw Channels не через прямые Telegram-аккаунты и не через “личные бот-личности”, а через server-native шину:

• reception/intake;
• queue;
• router;
• agent inbox;
• ACK/readback;
• lifecycle dashboard.

Routing policy

Нормативно должны существовать:

• canonical routing map;
• alias mapping;
• fallback policy;
• default triage agent.

На текущем этапе default triage agent — Filum.

Если внешний адресат не указан явно или alias не разрешается однозначно, сообщение должно:

• либо попадать в Filum triage;
• либо маркироваться как unmatched без молчаливой потери;
• либо удерживаться как invalid с понятной причиной.

ACK/readback policy

Каждый интегрированный агент должен поддерживать минимальный жизненный цикл:

• received — внешний ingress принял сообщение;
• queued — сообщение положено в каноническую очередь;
• delivered — сообщение доставлено в inbox/bus целевого агента;
• ack_received — агент или его адаптер подтвердил приём;
• answered или closed — по тикету дан итоговый исход;
• при проблеме должен появляться явный failure state, а не тихое исчезновение.

ACK в данной архитектуре — это техническое подтверждение обработки транспорта и inbox, а не автоматически содержательный ответ пользователю.

Safety и security constraints

Что запрещено публиковать или делать

Данный план не авторизует:

• публикацию Telegram token, webhook secret или иных секретов;
• передачу OpenClaw live token действующего intake-бота;
• торговлю, торговые сигналы, исполнение сделок;
• операции в Stellar;
• движение средств;
• отключение резидентов;
• takeover публичных каналов без отдельного решения;
• автоматический выход в новые внешние каналы без allowlist и operator review.

Обязательные ограничения

• OpenClaw Gateway должен оставаться loopback-only, пока не включена отдельная auth model.
• До внешней экспозиции канала должна быть настроена аутентификация.
• Для групп по умолчанию действуют groupPolicy=allowlist и requireMention=true.
• Outbound replies должны быть controlled per ticket/status, а не auto-spam.
• Документация, wiki-страницы и receipts не должны содержать токены, cookies, webhook secrets или прямые пароли.

Roadmap

Phase 0. Sidecar/readback foundation

Статус: выполнено.

Смысл этапа:

• развернуть isolated OpenClaw Gateway sidecar;
• не подключать live Telegram channel;
• наладить export из EchoIntakeBot в OpenClaw-facing state;
• собрать queue/router/ACK/dashboard контур.

Phase 1. Dashboard и status integration

Статус: частично реализовано, требует нормирования интерфейса.

Требуемый результат:

• unified lifecycle dashboard;
• статус по тикетам, очередям и readback;
• операционный read model для операторов;
• понятные failure buckets.

Phase 2. ACK standardization for all agents

Статус: в работе как нормативная цель.

Требуемый результат:

• единый ACK contract для Filum и остальных агентов;
• различение transport ACK, inbox ACK, accepted ACK и final answer status;
• отсутствие “немых” доставок без дальнейшего статуса.

Phase 3. Controlled outbound replies via EchoIntakeBot

Требуемый результат:

• итоговый ответ может быть отправлен обратно в Telegram не напрямую OpenClaw Telegram channel, а через контролируемый outbound path действующего EchoIntakeBot;
• outbound должен зависеть от статуса тикета и policy;
• должно быть видно, что reply разрешён, отправлен и связан с исходным receipt.

Phase 4. Add non-Telegram OpenClaw channels

Приоритетный смысл этапа — не заменить Telegram, а расширить ingress через дополнительные мосты:

• Matrix;
• WebChat;
• Discord;
• другие поддержанные OpenClaw channels по мере необходимости.

Условия допуска:

• allowlists;
• no secret leakage;
• controlled routing;
• отсутствие смешения личных DM и group sessions;
• operator-visible receipts и lifecycle.

Phase 5. Optional controlled Telegram migration

Допускается только если одновременно выполнены все условия:

• есть реальная operational выгода от нативного OpenClaw Telegram channel;
• подготовлен migration plan;
• подготовлен rollback plan;
• есть тест на group gating, allowlists, outbound control и readback;
• отдельно авторизован takeover token/webhook.

До такого решения Telegram migration не считается разрешённой по умолчанию.

Операционная модель, SLO и failure states

Обязательная машинная трасса сообщения

Каждое внешнее сообщение в целевом контуре должно иметь машинно-читаемую трассу:

• received
• queued
• delivered
• ack_received
• answered или closed

Если трасса обрывается, система должна уметь показать, где именно:

• pending_ack
• unmatched
• invalid
• gateway_unreachable
• delivery_failed
• outbound_blocked

Нормативный SLO-подход

Для production-ready интеграции требуется не абстрактное “бот ответил”, а измеримый сервисный контур:

• ни одно принятое внешнее сообщение не должно исчезать без статуса;
• backlog очереди и pending_ack должны быть операционно видимы;
• unmatched/invalid события должны быть малы и проверяемы;
• controlled outbound должен быть отделён от технического ACK;
• если нативный канал не даёт read receipts, серверный ACK/readback считается каноническим источником статуса.

Definition of Done

Полная интеграция OpenClaw Channels в Синаполис считается завершённой только если одновременно выполнено следующее:

• сохраняется один официальный Telegram-ingress или проведена отдельная авторизованная миграция с rollback;
• внешние каналы заходят через OpenClaw Gateway без утечки секретов;
• groups работают только по allowlist + mention gating;
• agents интегрированы через inbox/bus/ack/readback, а не через ручное перекидывание сообщений;
• routing map и alias policy прозрачны;
• каждый тикет имеет lifecycle receipt до answered/closed;
• controlled outbound replies реализованы и ограничены policy;
• dashboard показывает очереди, delivery, ACK и ошибки;
• есть операторская верификация по readback/revid/receipt artifacts;
• нет несанкционированного Telegram token takeover.

Что уже реализовано на 19 мая 2026

Ниже фиксируется текущая живая реализация на Synapolis VPS 167.235.227.254.

1. Telegram ingress сохранён на EchoIntakeBot

• webhook Caddy /tg-intake -> 127.0.0.1:8443 восстановлен;
• сервис echo-intake-bot.service активен.

2. Normalized intake artifacts

EchoIntakeBot пишет нормализованные reception artifacts рядом с legacy inbox:

• /opt/agent-workspace/agents/reception/intake-events
• /opt/agent-workspace/agents/reception/tickets
• /opt/agent-workspace/state/reception/intake-status.json
• /opt/agent-workspace/state/reception/intake-status.md

3. Isolated OpenClaw Gateway sidecar

Развёрнут sidecar:

• /opt/agent-workspace/openclaw/sidecar
• сервис openclaw-gateway-sidecar.service
• loopback-only endpoint ws://127.0.0.1:19011
• Telegram channel не подключён
• configured channels count = 0
• token takeover отсутствует

4. EchoIntake/OpenClaw sidecar-export

• /opt/agent-workspace/scripts/openclaw/echo_intake_openclaw_sidecar.py
• /opt/agent-workspace/state/openclaw/echo-intake-bridge-status.json
• /opt/agent-workspace/state/openclaw/echo-intake-bridge-status.md
• /opt/agent-workspace/state/openclaw/echo-intake-export-latest.json

5. Consumer queue

• /opt/agent-workspace/scripts/openclaw/echo_intake_openclaw_consumer.py
• openclaw-echo-intake-consumer.timer каждые 2 минуты
• /opt/agent-workspace/state/openclaw/echo-intake-consumer-queue.json
• /opt/agent-workspace/state/openclaw/echo-intake-consumer-queue.jsonl

6. Router

• /opt/agent-workspace/scripts/openclaw/openclaw_reception_router.py
• openclaw-agent-router.timer каждые 2 минуты
• /opt/agent-workspace/state/openclaw/agent-routing-map.json
• /opt/agent-workspace/state/openclaw/openclaw-agent-delivery-ledger.jsonl

7. ACK/readback

• /opt/agent-workspace/scripts/openclaw/openclaw_delivery_ack_collector.py
• openclaw-ack-collector.timer
• /opt/agent-workspace/scripts/openclaw/filum_openclaw_inbox_ack.py
• filum-openclaw-inbox-ack.timer
• /opt/agent-workspace/agents/filum/outbox/openclaw-acks/

8. Lifecycle dashboard

• /opt/agent-workspace/scripts/openclaw/openclaw_ticket_lifecycle_dashboard.py
• openclaw-ticket-dashboard.timer
• /opt/agent-workspace/state/openclaw/openclaw-ticket-lifecycle-dashboard.json
• /opt/agent-workspace/state/openclaw/openclaw-ticket-lifecycle-dashboard.md
• latest summary: /opt/agent-workspace/state/openclaw/openclaw-ticket-lifecycle-latest-summary.json

Live receipt

Проверенный live test:

@EchoIntakeBot to:filum проверка связи, сколько будет 1+1?

Результат:

• EchoIntakeBot вернул REC-0095;
• внутренний путь зафиксирован как:

 * REC-0095 queued
 * delivered
 * ack_received

• canonical_agent=filum
• delivery_id=ocrd-66d26dc4d4304f12
• read_status=read
• ack_status=accepted

Это технический ACK/readback, а не содержательный outbound reply пользователю.

Dashboard totals после live test

• queued=4
• skipped_synthetic=2
• delivered=2
• ack_received=2
• pending_ack=0
• errors=0
• unmatched=0

Рекомендуемое место страницы в карте Синаполиса

Эта страница логически относится к коммуникационному контуру и должна быть связана как минимум из:

• Карта Синаполиса/Коммуникации

При допустимом объёме правки можно также ссылаться из:

• Карта Синаполиса

Если правка главной карты рискованна, достаточно сохранить standalone page и ссылку из коммуникационного раздела.

Явные неавторизации

Этот документ сам по себе НЕ authorizes:

• takeover live Telegram token/webhook;
• публикацию токенов;
• запуск торговых или финансовых действий;
• Stellar-подписи и submission;
• fund movement;
• отключение резидентов;
• перевод любых public channels под OpenClaw без отдельного решения.

Источники

• OpenClaw Chat channels
• OpenClaw Groups
• OpenClaw Group messages
• OpenClaw Channel routing
• OpenClaw Telegram