1. Telegram gateway поддерживает много чатов одним bot token

Документация Telegram integration описывает один BotFather token и allowlists:

TELEGRAM_BOT_TOKEN=...
TELEGRAM_ALLOWED_USERS=...

Один бот может работать в DMs, группах, супергруппах и forum topics.

Для групп есть отдельные gates:

• TELEGRAM_ALLOWED_USERS / allow_from — глобальный доступ;
• TELEGRAM_GROUP_ALLOWED_USERS / group_allow_from — кто может вызывать бота в группах;
• TELEGRAM_GROUP_ALLOWED_CHATS / group_allowed_chats — какие группы разрешены целиком.

Это уже позволяет использовать одного Telegram бота для многих клиентских чатов, если все они должны попадать в один Hermes profile.

2. Session routing уже различает чат, пользователя и thread/topic

В gateway/session.py есть SessionSource:

platform
chat_id
chat_type
user_id
thread_id

И build_session_key() строит ключи вида:

agent:main:{platform}:dm:{chat_id}
agent:main:{platform}:dm:{chat_id}:{thread_id}
agent:main:{platform}:{chat_type}:{chat_id}:{thread_id}:{user_id?}

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

• DM с разными пользователями — разные сессии;
• DM topic/thread — отдельная сессия;
• group/forum topic — отдельная сессия;
• обычная группа может быть shared или per-user в зависимости от правил.

3. Telegram topics уже решают “много сессий в одном боте”

Hermes docs описывают:

• Private Chat Topics — фиксированные топики в DM, заданные оператором через config;
• Multi-session DM mode /topic — пользователь сам включает topics и создаёт параллельные Hermes-сессии через Telegram UI;
• Group Forum Topic Skill Binding — topic в супергруппе может auto-load конкретный skill.

Это полезно, если нужно много рабочих пространств внутри одного Hermes profile.

Но это не равно “десятки независимых Hermes профилей/клиентов”, потому что память, конфиг, credentials, toolsets и state всё ещё принадлежат одному profile.

4. Profiles дают настоящую изоляцию агентов

Hermes profiles — это отдельные home directories:

• config.yaml;
• .env;
• SOUL.md;
• memory;
• sessions;
• skills;
• cron jobs;
• gateway state;
• logs.

Команды:

hermes profile create client-a
hermes profile create client-b
hermes -p client-a gateway
hermes -p client-b gateway

Для независимых клиентских агентов profiles — правильная единица изоляции.

5. API Server позволяет каждому profile быть backend-agent’ом

API Server включается env vars:

API_SERVER_ENABLED=true
API_SERVER_PORT=8643
API_SERVER_KEY=client-a-secret
hermes -p client-a gateway

Для многих профилей:

hermes profile create client-a
hermes profile create client-b

# client-a/.env
API_SERVER_ENABLED=true
API_SERVER_PORT=8643
API_SERVER_KEY=client-a-secret
API_SERVER_MODEL_NAME=client-a

# client-b/.env
API_SERVER_ENABLED=true
API_SERVER_PORT=8644
API_SERVER_KEY=client-b-secret
API_SERVER_MODEL_NAME=client-b

hermes -p client-a gateway &
hermes -p client-b gateway &

API Server поддерживает:

• /v1/chat/completions;
• /v1/responses;
• /v1/runs;
• SSE streaming;
• X-Hermes-Session-Id для session continuity;
• X-Hermes-Session-Key для долгоживущего per-channel memory scope.

6. Gateway proxy mode уже есть, но сейчас он один-к-одному

В gateway/run.py есть proxy mode:

GATEWAY_PROXY_URL
# или gateway.proxy_url

Когда он задан, gateway становится thin relay:

Telegram/Matrix/etc adapter
  → GatewayRunner
  → POST remote /v1/chat/completions

Но текущая реализация _get_proxy_url() возвращает один URL. Значит, это подходит для split deployment одного backend-agent’а, но не для routing map “чат A → profile A, чат B → profile B”.

Telegram users/groups/topics
  → one Telegram bot token
  → central Telegram Router / Ingress
  → routing DB: chat_id/user_id/thread_id/customer → Hermes profile endpoint
  → Hermes profile API Server per client/agent
  → answer back to same Telegram chat/topic

Backend agents

Каждый клиент/агент — отдельный Hermes profile:

client-a: http://127.0.0.1:8643/v1  API_SERVER_KEY=a
client-b: http://127.0.0.1:8644/v1  API_SERVER_KEY=b
client-c: http://127.0.0.1:8645/v1  API_SERVER_KEY=c

Router DB

Минимальная таблица:

CREATE TABLE telegram_agent_routes (
  id INTEGER PRIMARY KEY,
  telegram_chat_id TEXT NOT NULL,
  telegram_user_id TEXT,
  telegram_thread_id TEXT,
  route_scope TEXT NOT NULL,        -- chat | user | thread | manual
  agent_id TEXT NOT NULL,
  api_base_url TEXT NOT NULL,
  api_key_ref TEXT NOT NULL,
  session_key TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'active',
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  UNIQUE(telegram_chat_id, telegram_user_id, telegram_thread_id)
);

Практический route priority:

1. exact chat_id + thread_id + user_id;
2. chat_id + thread_id;
3. chat_id + user_id;
4. chat_id;
5. user_id;
6. default / ask user.

Что отправлять в Hermes API Server

Для каждого сообщения router вызывает нужный backend:

POST http://127.0.0.1:8643/v1/chat/completions
Authorization: Bearer client-a-secret
X-Hermes-Session-Id: tg:{chat_id}:{thread_id_or_root}:{user_id}:transcript
X-Hermes-Session-Key: tg:{chat_id}:{thread_id_or_root}:{user_id}
Content-Type: application/json

Body:

{
  "model": "hermes-agent",
  "stream": true,
  "messages": [
    {"role": "user", "content": "..."}
  ]
}

Для обычного multi-turn можно использовать X-Hermes-Session-Id, чтобы backend сам грузил историю из своего state.db. X-Hermes-Session-Key полезен, чтобы long-term memory понимала, что это тот же канал даже после /new или смены transcript.

Вариант A — по чату

Лучший для клиентских групп:

• каждый клиент добавляет одного общего бота в свою группу;
• admin один раз делает /bind client-a;
• дальше весь chat_id маршрутизируется в client-a profile.

Плюсы:

• просто;
• меньше ошибок;
• клиент не выбирает агента каждый раз;
• подходит для B2B “один клиент = один чат”.

Минусы:

• если в одном чате нужно несколько агентов, нужны topics или команды переключения.

Вариант B — по Telegram topic/thread

Лучший для одного общего супергруппового “портала”:

• topic “Client A” → Hermes profile A;
• topic “Client B” → Hermes profile B;
• topic “Support” → support-agent.

Плюсы:

• один Telegram group/forum как консоль управления;
• thread_id является естественным route key.

Минусы:

• нужно аккуратно настроить Telegram topics и права;
• в topic shared context между участниками, если не включать per-user logic.

Вариант C — по пользователю

Подходит для личного DM:

• user_id 123 всегда маршрутизируется в его личный Hermes;
• /switch client-b меняет default route пользователя.

Плюсы:

• хороший UX для “у каждого клиента/сотрудника свой агент”.

Минусы:

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

Вариант D — бот спрашивает

Если route не найден:

К какому агенту подключить этот чат?
[client-a] [client-b] [создать нового] [одноразовый запрос]

После выбора router сохраняет binding.

Плюсы:

• удобно при onboarding;
• меньше ручной настройки.

Минусы:

• надо реализовать pending state;
• нужна защита от того, что обычный пользователь привяжет чат к чужому агенту.

Если нужна быстро работающая схема

Выбрать внешний Telegram router + Hermes API Server per profile.

Если хочется сделать upstream feature в Hermes

Делать gateway.proxy_routes / route resolver внутри Hermes gateway.

Если клиенты не требуют строгой изоляции

Можно начать с одного Hermes profile, одного Telegram bot и route-by-chat/session topics. Это самый быстрый путь, но слабее по безопасности и кастомизации.

Если один оператор управляет многими агентами в личке

Использовать Telegram DM topics или команды /switch, где каждый topic/user binding указывает на backend profile.