Telethon Master

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

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

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

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

Архитектура

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:

"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__<имя>.

Сообщения

Чтение

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

Медиа

Интеракции

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

Аналитика

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

TTS / Voice Notes (ElevenLabs)

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

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

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)

Доступные голоса (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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Claude Code vs OpenClaw

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

# Статус
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

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

Референсы

• 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