Telethon Master#

Скилл для работы с Telegram MTProto через Telethon Bridge. Предоставляет доступ к 23 инструментам ( telegram_*) для отправки сообщений, голосовых (ElevenLabs TTS), истории чатов, реакций, файлов, управления каналами и статистики.

Поддерживает Claude Code (прямые MCP-вызовы) и OpenClaw (через Gateway).

Когда использовать#

• Отправить сообщение через Telegram (не через бота)
• Получить историю чата, список диалогов
• Сгенерировать голосовое (voice note) через ElevenLabs TTS
• Отправить файл или фото
• Поставить реакцию на сообщение
• Получить статистику чата
• Управлять каналами (описание, удаление)
• Скачать медиа из сообщения
• Пользователь спрашивает о работе MCP-инструментов Telethon

Архитектура#

text

Claude Code / OpenClaw
        │
        ▼
MCP Server (telethon-mcp/server.py)  ← HTTP-обёртка над REST API
        │
        ▼
REST API (telethon-bridge/server.py) ← Telethon MTProto + sag (ElevenLabs)
        │
        ▼
SOCKS5 (127.0.0.1:1080) ← SSH-туннель ← VPS (45.13.225.151)
        │
        ▼
Telegram DC

• MCP Server ( ~/.openclaw/mcp-servers/telethon-mcp/server.py) — тонкая обёртка, HTTP-запросы к REST API
• REST API ( ~/.openclaw/workspace/general/telethon-bridge/server.py) — Telethon клиент + sag CLI
• Сессия: session/savant (SQLite), одна активная сессия
• Прокси: SOCKS5 напрямую через SSH-туннель (127.0.0.1:1080)
• TTS: sag CLI → ElevenLabs API → MP3 → FFmpeg (Opus OGG) → Telegram voice note
• Gateway: gateway.mjs (порт 18793) — форвардит входящие от owner в OpenClaw агент
• Systemd: telethon-bridge.service (user, порт 18792), telegateway.service (user, порт 18793)

Безопасность: ALLOWED_CHAT_IDS#

MCP-сервер поддерживает переменную TG_ALLOWED_CHAT_IDS — список разрешённых chat_id через запятую. Если переменная установлена, write-операции (send, edit, delete, forward, react, click, file, voice, pin, read, audio, circle, channel about/delete, join) разрешены только для указанных чатов.

Установка в mcp.json:

json

"env": {
    "TELEGATEWAY_URL": "http://127.0.0.1:18792",
    "TG_ALLOWED_CHAT_IDS": "me,1144466778,kngserious55"
}

Read-операции (messages, chats, search, stats, get_chat, get_photo, get_chatlist, download_media) не ограничены.

Инструменты (Claude Code MCP)#

В Claude Code все инструменты доступны как mcp__telethon-bridge__<имя>.

Сообщения#

ИнструментПараметрыОписаниеtelegram_send``chat_id, textОтправка текстового сообщенияtelegram_edit``chat_id, msg_id, textРедактирование сообщенияtelegram_delete``chat_id, msg_ids[]Удаление сообщенийtelegram_forward``from_chat, to_chat, msg_ids[]Пересылка сообщенийtelegram_pin``chat_id, msg_id, unpin?Закреп/откреп сообщения

Чтение#

ИнструментПараметрыОписаниеtelegram_messages``chat_id, limit?, offset_id?История сообщений с пагинациейtelegram_search``chat_id, query, limit?, from_user?Поиск сообщенийtelegram_read``chat_id, max_id?Отметить как прочитанное

Чаты и пользователи#

ИнструментПараметрыОписаниеtelegram_chats``limit? (default 30)Список диалоговtelegram_get_chat``chat_idИнфо о чате/канале/пользователеtelegram_me—Инфо о текущем пользователеtelegram_get_photo``chat_id? (default "me")Скачать фото профиляtelegram_join_chat``hashВступить по invite-hashtelegram_get_chatlist``slugКаналы из t.me/addlist

Медиа#

ИнструментПараметрыОписаниеtelegram_file``chat_id, file_path, caption?Отправка файла (документ)telegram_voice``chat_id, text, voice? (default "Roger")Voice note через ElevenLabstelegram_send_audio``chat_id, file_path, title?, performer?Аудиофайл с тегамиtelegram_send_circle``chat_id, file_pathКруглое видео (video note)telegram_download_media``chat_id, msg_idСкачать медиа в /tmp/bridge_dl/

Интеракции#

ИнструментПараметрыОписаниеtelegram_react``chat_id, msg_id, reactionРеакция (эмодзи или document_id)telegram_click``chat_id, msg_id, row?, col?Клик по inline-кнопке

Управление каналами#

ИнструментПараметрыОписаниеtelegram_set_channel_about``chat_id, textУстановить описание каналаtelegram_delete_channel``chat_idУдалить канал (только owner)

Аналитика#

ИнструментПараметрыОписаниеtelegram_stats``chat_id? (default "me"), days? (default 7)Статистика чата

Важно: chat_id принимает username ( kngserious55), ID ( 1184174498), или "me" для сохранёнок.

TTS / Voice Notes (ElevenLabs)#

Как это работает#

telegram_voice вызывает sag CLI, который обращается к ElevenLabs API:

text

sag speak -v <voice> --model-id eleven_multilingual_v2 --format mp3_44100_192 -o <wav> <text>
ffmpeg -i <wav> -c:a libopus -b:a 192k -ar 48000 -ac 1 <ogg>
Telethon send_file(voice_note=True)

Параметры качества (настроены в server.py)#

ПараметрЗначениеМодельeleven_multilingual_v2Форматmp3_44100_192 (192 kbps)OGG кодекOpus 192k, 48000 Hz, mono

Доступные голоса (24 шт., ElevenLabs-аккаунт @savantbeats)#

Голос передаётся напрямую в sag (без маппинга). Имя должно существовать в ElevenLabs-аккаунте.

Женские: Sarah, Laura, Alice, Matilda, Jessica, Bella, Lily Мужские: Adam, Roger, Charlie, George, Callum, River, Harry, Liam, Will, Eric, Chris, Brian, Daniel, Bill

Выбор голоса под задачу#

ЗадачаРекомендацияРазговорный, casualRoger, AdamДеловой, профессиональныйBella, MatildaЯркий, эмоциональныйJessica, LauraСпокойный, тёплыйSarah, Lily

Устранение проблем#

ОшибкаПричинаРешение500: Internal Server ErrorГолос не существует в аккаунте ElevenLabsИспользовать голос из таблицы выше500: Voice error: ffmpeg ...Неподдерживаемый sample rateOpus поддерживает: 8000/12000/16000/24000/48000sag: missing API key``ELEVENLABS_API_KEY не установленПроверить .env бриджаdatabase is lockedДва клиента Telethon одновременноБридж держит одну сессию — не подключаться параллельноFloodWaitБридж автоматически ретраит до 3 раз (capped 60s)Ждать или уменьшить частоту

Быстрые рецепты#

Отправить сообщение#

text

mcp__telethon-bridge__telegram_send(chat_id="username", text="Привет!")

Отправить голосовое#

text

mcp__telethon-bridge__telegram_voice(chat_id="me", text="Привет, мир!", voice="Jessica")

Получить последние сообщения#

text

mcp__telethon-bridge__telegram_messages(chat_id="username", limit=10)

Найти чат по имени#

text

mcp__telethon-bridge__telegram_chats(limit=30)
// → ищем в выдаче нужный username/ID

Отправить файл#

text

mcp__telethon-bridge__telegram_file(chat_id="username", file_path="/path/to/file.pdf")

Поставить реакцию#

text

mcp__telethon-bridge__telegram_react(chat_id="username", msg_id=12345, reaction="🔥")

Claude Code vs OpenClaw#

Claude CodeOpenClawВызов инструментовmcp__telethon-bridge__<tool>()``mcp.call_tool("telethon-bridge", "<tool>", {})TTSЧерез telegram_voice``sag speak напрямую или telegram_voiceДоступ к файламПрямой (локальная ФС)Через OpenClaw workspaceПерезапуск бриджаsystemctl --user restart telethon-bridge.serviceТоже самоеЛоги бриджаjournalctl --user -u telethon-bridge.serviceТоже самое

Обслуживание бриджа#

bash

# Статус
systemctl --user status telethon-bridge.service

# Перезапуск (после правок server.py)
systemctl --user restart telethon-bridge.service

# Логи
journalctl --user -u telethon-bridge.service -f

# Ручной запуск (отладка)
cd ~/.openclaw/workspace/general/telethon-bridge
python3 server.py

# Убить зависший процесс
fuser -k 18792/tcp

# Проверить здоровье
curl -s http://127.0.0.1:18792/health

Безопасность и ограничения#

ПравилоОписаниеНикакого спамаНе отправлять рекламные сообщения без явного запросаЧувствительные данныеНе логировать содержимое сообщенийRate limitingНе более ~30 сообщений в минутуПриватные чатыНе читать ЛС без явного разрешения владельца аккаунтаFLOOD_WAITБридж ретраит автоматически (до 3 попыток, capped 60s)ALLOWED_CHAT_IDSОграничивает write-операции заданным списком чатов

Референсы#

• Telethon Bridge REST API: ~/.openclaw/workspace/general/telethon-bridge/server.py
• MCP Server: ~/.openclaw/mcp-servers/telethon-mcp/server.py
• Gateway Bridge: ~/.openclaw/workspace/general/telethon-bridge/gateway.mjs
• .env бриджа: ~/.openclaw/workspace/general/telethon-bridge/.env
• Systemd unit: ~/.config/systemd/user/telethon-bridge.service
• ElevenLabs голоса: ELEVENLABS_API_KEY в .env → https://api.elevenlabs.io/v1/voices
• sag CLI: /home/linuxbrew/.linuxbrew/bin/sag speak --help
• Формат voice note: OGG Opus, 48000 Hz, mono, 192k