Hermes-Skills/devops/telethon-proxy-docker/SKILL.md

---
name: telethon-proxy-docker
description: "Deploy Telethon-based Telegram bots/forwarders behind a SOCKS5 proxy (Mihomo/Clash) on a server with no direct Telegram access. Covers Docker networking, proxy injection, and phone verification workflow."
tags: [telethon, telegram, proxy, docker, mihomo, socks5, forwarder]
---

# Telethon + Proxy + Docker Deployment

Deploy Telethon-based Telegram bots/forwarders on a server that requires a proxy (Mihomo/Clash) to reach Telegram API servers.

## When to Use

- User asks to deploy a Telegram bot/forwarder that uses Telethon
- Server has no direct route to Telegram (Mihomo proxy required)
- Telethon-based app needs to run in Docker behind a proxy
- Keywords: "Telegram 转发器", "Telethon proxy", "消息转发", "Telegram forwarder"

## Core Problem

Telethon uses MTProto (raw TCP), NOT HTTP. Standard `HTTP_PROXY` / `HTTPS_PROXY` environment variables do **NOT** work for Telethon connections. You must pass a `proxy` parameter explicitly to `TelegramClient()`.

## Step-by-Step Setup

### 1. Verify proxy is a mixed-port (supports SOCKS5)

Mihomo/Clash `mixed-port` supports both HTTP and SOCKS5 on the same port:

```bash
# Check config
grep "mixed-port" /home/openclaw/clash/config/config.yaml
# Output: mixed-port: 7890
```

### 2. Patch Telethon client creation

Find where `TelegramClient()` is instantiated (usually `main.py`) and add proxy:

```python
import os
try:
    import socks
    HAS_SOCKS = True
except ImportError:
    HAS_SOCKS = False

# Parse proxy from env
proxy_config = None
proxy_addr = os.getenv('HTTP_PROXY') or os.getenv('http_proxy')
if proxy_addr and HAS_SOCKS:
    import re
    m = re.match(r'https?://([\d.]+):(\d+)', proxy_addr)
    if m:
        proxy_config = (socks.SOCKS5, m.group(1), int(m.group(2)))

# Pass to TelegramClient
user_client = TelegramClient('./sessions/user', api_id, api_hash, proxy=proxy_config)
bot_client = TelegramClient('./sessions/bot', api_id, api_hash, proxy=proxy_config)
```

### 3. Docker setup with network_mode: host

Docker containers can't reach `127.0.0.1:7890` on the host by default. Use `network_mode: host`:

```yaml
# docker-compose.yml
services:
  telegram-forwarder:
    build:
      context: .
      dockerfile: Dockerfile.custom
    container_name: telegram-forwarder
    restart: unless-stopped
    network_mode: host          # Required for 127.0.0.1 proxy access
    environment:
      - HTTP_PROXY=http://127.0.0.1:7890
      - HTTPS_PROXY=http://127.0.0.1:7890
      - http_proxy=http://127.0.0.1:7890
      - https_proxy=http://127.0.0.1:7890
      - NO_PROXY=localhost,127.0.0.1
    volumes:
      - ./db:/app/db
      - ./.env:/app/.env
      - ./sessions:/app/sessions
      # ... other volumes
    stdin_open: true            # Required for phone verification
    tty: true                   # Required for phone verification
```

### 4. Custom Dockerfile (adds PySocks)

```dockerfile
FROM heavrnl/telegramforwarder:latest  # or whatever base image
RUN pip install --no-cache-dir PySocks
COPY main.py /app/main.py              # patched version with proxy support
```

### 5. Phone verification (first run)

First run requires interactive phone verification:

```bash
# Run interactively for first-time auth
docker-compose run --rm telegram-forwarder
# → Enter phone code when prompted
# → Session saved to ./sessions/*.session
```

Use `terminal(background=true, pty=true)` and `process(action='submit')` to handle verification code input.

**Pitfall**: Verification codes expire FAST (~30 seconds). Agent-based submission via `process(action='submit')` is unreliable due to latency — the code often expires before the agent can submit it. **Recommend user SSH directly** and run `docker-compose run --rm telegram-forwarder` themselves for the verification step.

**Pitfall**: If 2FA is enabled, Telethon will prompt for password AFTER the code. User needs to enter their Telegram two-step verification password (set in TG Settings → Privacy & Security → Two-Step Verification). If forgotten, it can be reset but requires a 7-day wait.

**Pitfall**: If code expires, clean session files and restart:
```bash
rm -f ./sessions/*.session ./sessions/*.session-journal
docker-compose run --rm telegram-forwarder
```

### 6. After verification, run as daemon

```bash
docker-compose up -d
docker-compose logs -f
```

## Pitfalls

- **`HTTP_PROXY` alone does NOT work for Telethon** — Telethon uses raw TCP (MTProto), not HTTP. Must pass `proxy=(socks.SOCKS5, host, port)` to `TelegramClient()`.
- **`PySocks` must be installed** — add to Dockerfile if not in base image's requirements.
- **`network_mode: host`** is required for `127.0.0.1` proxy access. Without it, the container can't reach the host's Mihomo. Alternative: use `extra_hosts: ["host.docker.internal:host-gateway"]` and change proxy to `host.docker.internal:7890`.
- **Session database lock** — if previous run crashed, `*.session` files may be locked. Delete them before retrying.
- **Don't use same bot token as Hermes** — the forwarder bot needs its own BotFather token. Using the same token causes conflicts.
- **Verification code timeout** — Telegram codes expire in ~30s. The interactive Docker session may time out if user is slow to respond. Have the code ready before starting.

## Reference: Heavrnl/TelegramForwarder

Best full-featured Telegram forwarder (1144+ stars):
- Repo: `https://github.com/Heavrnl/TelegramForwarder`
- Features: `/bind` command, keyword filtering, regex replace, AI processing, RSS, multi-platform push
- Commands: `/bind`, `/settings`, `/add`, `/replace`, `/list_keyword`, etc.
- Docker image: `heavrnl/telegramforwarder:latest`

## Server Context

- Server: Linux (NYC), no direct route to Telegram servers
- Proxy: Mihomo at `127.0.0.1:7890` (mixed-port, SOCKS5 + HTTP)
- Telegram API creds in `~/.bashrc`: `TG_API_ID`, `TG_API_HASH`
- User prefers Chinese UI/commands