Sergei Mikhailov Tg Channel Reader

tg-channel-reader

Read posts and comments from Telegram channels using MTProto (Pyrogram or Telethon). Works with any public channel and private channels the user is subscribed to. Supports fetching discussion replies (comments) for individual posts.

Security notice: This skill requires TG_API_ID and TG_API_HASH from my.telegram.org. The session file grants full Telegram account access — store it securely and never share it.

Exec Approvals

Just installed via clawhub install? Complete Setup & Installation (below) first — the skill needs pip install, credentials, and a session file before exec approvals matter.

OpenClaw blocks unknown CLI commands by default. The user must approve tg-reader commands before they can run. If the command hangs or the user says nothing is happening — exec approval is likely pending.

Quick setup (recommended)

Run from the skill directory — checks prerequisites, installs pip packages if needed, and prints the approval commands to run:

cd ~/.openclaw/workspace/skills/sergei-mikhailov-tg-channel-reader
bash setup-tg-reader.sh

Manual CLI approval

openclaw approvals allowlist add --gateway "$(which tg-reader)"
openclaw approvals allowlist add --gateway "$(which tg-reader-check)"
openclaw approvals allowlist add --gateway "$(which tg-reader-telethon)"

Alternative: approve on first use

1. Control UI — open http://localhost:18789/, find the pending approval for tg-reader, click "Always allow". Docs
2. Messenger (Telegram, Slack, Discord) — the bot sends an approval request with an <id>. Reply: /approve <id> allow-always. Other options: allow-once, deny.

The approval prompt appears in the Control UI or as a bot message — not in the agent's conversation. This is a common source of confusion.

When to Use

• User asks to "check", "read", or "monitor" a Telegram channel
• Wants a digest or summary of recent posts
• Asks "what's new in @channel" or "summarize last 24h from @channel"
• Wants to track or compare multiple channels
• Wants channel info (title, description, subscribers) — use tg-reader info

Quick Start

# 1. Run pre-flight diagnostic (fast, no Telegram connection)
tg-reader-check

# 2. Get channel info
tg-reader info @channel_name

# 3. Fetch recent posts
tg-reader fetch @channel_name --since 24h

tg-reader: command not found? Run bash setup-tg-reader.sh from the skill directory (it will install the package), or manually: cd ~/.openclaw/workspace/skills/sergei-mikhailov-tg-channel-reader && pip install .

Commands

tg-reader-check — Pre-flight Diagnostic

Always run before fetching. Fast offline check — no Telegram connection needed.

tg-reader-check
tg-reader-check --config-file /path/to/config.json
tg-reader-check --session-file /path/to/session

Returns JSON with "status": "ok" or "status": "error" plus a problems array.

Verifies:

• Credentials available (env vars or ~/.tg-reader.json)
• Session file exists on disk (with size, modification date)
• At least one MTProto backend installed (Pyrogram or Telethon)
• Detects stale sessions (config points to older file while a newer one exists)

tg-reader info — Channel Info

tg-reader info @channel_name

Returns title, description, subscriber count, and link.

tg-reader fetch — Read Posts

# Last 24 hours (default)
tg-reader fetch @channel_name --since 24h

# Last 7 days, up to 200 posts
tg-reader fetch @channel_name --since 7d --limit 200

# Multiple channels (fetched sequentially with 10s delay between each)
tg-reader fetch @channel1 @channel2 @channel3 --since 24h

# Custom delay between channels (seconds)
tg-reader fetch @channel1 @channel2 @channel3 --since 24h --delay 5

# Fetch posts with comments (single channel only, limit auto-drops to 30)
tg-reader fetch @channel_name --since 7d --comments

# More comments per post, custom delay between posts
tg-reader fetch @channel_name --since 24h --comments --comment-limit 20 --comment-delay 5

# Skip posts without text (media-only, no caption)
tg-reader fetch @channel_name --since 24h --text-only

# Human-readable output
tg-reader fetch @channel_name --since 24h --format text

# Write output to file instead of stdout (saves tokens)
tg-reader fetch @channel_name --since 24h --output
tg-reader fetch @channel_name --since 24h --comments --output comments.json

# Use Telethon instead of Pyrogram (one-time)
tg-reader fetch @channel_name --since 24h --telethon

# Read unread mode — only fetch new (unread) posts, no --since needed
# Requires "read_unread": true in ~/.tg-reader.json
tg-reader fetch @channel_name

# Override read_unread mode (fetch everything, don't update state)
tg-reader fetch @channel_name --since 7d --all

# Custom state file location
tg-reader fetch @channel_name --since 24h --state-file /path/to/state.json

tg-reader auth — First-time Authentication

tg-reader auth

Creates a session file. Only needed once.

Read Unread Mode

Only return new (unread) posts — the skill remembers what you've already seen. Useful for daily digests and monitoring workflows.

Setup

Option A — config file (~/.tg-reader.json):

{
  "api_id": 12345,
  "api_hash": "...",
  "read_unread": true
}

Option B — env var (works with ~/.openclaw/openclaw.json):

export TG_READ_UNREAD=true

Env vars take priority over the config file. This lets you enable read_unread via openclaw.json Docker env alongside TG_API_ID/TG_API_HASH.

State is stored in ~/.tg-reader-state.json (configurable via "state_file" in config, TG_STATE_FILE env var, or --state-file flag).

Behavior

• --since is not needed when read_unread is enabled — the skill automatically returns all unread posts regardless of time
• First run (no prior state for channel): --since applies as usual (default 24h); state file created
• Subsequent runs: only posts newer than the last read are returned; --since is ignored
• --all flag: bypasses read_unread mode — fetches everything by --since without updating state (preserves your position)
• New channel: behaves like a first run (no prior state)
• No new posts: state unchanged, count: 0 returned

Examples

# With read_unread enabled — just fetch, no --since needed
tg-reader fetch @channel_name

# First run for a new channel — --since determines initial window
tg-reader fetch @new_channel --since 7d

# Override: fetch everything, don't update tracking state
tg-reader fetch @channel_name --since 7d --all

Output

When read_unread mode is active, the JSON output includes a read_unread field:

{
  "channel": "@channel_name",
  "read_unread": {"enabled": true},
  "count": 5,
  "messages": [...]
}

With --all: "read_unread": {"enabled": true, "overridden": true}

Limitations

• Tracking is post-level only — new comments on already-read posts are not caught
• If a channel changes its username, tracking resets (state is keyed by username)
• Concurrent runs for the same channel are safe but last writer wins

Diagnostic

tg-reader-check reports tracking status:

{
  "tracking": {
    "read_unread": true,
    "state_file": "~/.tg-reader-state.json",
    "state_file_exists": true,
    "tracked_channels": 3
  }
}

Output Format

info

{
  "id": -1001234567890,
  "title": "Channel Name",
  "username": "channel_name",
  "description": "About this channel...",
  "members_count": 42000,
  "link": "https://t.me/channel_name"
}

fetch

{
  "channel": "@channel_name",
  "fetched_at": "2026-02-22T10:00:00Z",
  "since": "2026-02-21T10:00:00Z",
  "count": 12,
  "messages": [
    {
      "id": 1234,
      "date": "2026-02-22T09:30:00Z",
      "text": "Post content...",
      "views": 5200,
      "forwards": 34,
      "link": "https://t.me/channel_name/1234",
      "has_media": true,
      "media_type": "MessageMediaType.PHOTO"
    }
  ]
}

fetch with --comments

{
  "channel": "@channel_name",
  "fetched_at": "2026-02-28T10:00:00Z",
  "since": "2026-02-27T10:00:00Z",
  "count": 5,
  "comments_enabled": true,
  "comments_available": true,
  "messages": [
    {
      "id": 1234,
      "text": "Post content...",
      "has_media": false,
      "comment_count": 2,
      "comments": [
        {
          "id": 5678,
          "date": "2026-02-28T09:35:00Z",
          "text": "Great post!",
          "from_user": "username123"
        }
      ]
    }
  ]
}

Notes:

• comments_available: false — channel has no linked discussion group (no comments possible)
• comments_error on a message — rate limit hit for that post's comments
• from_user may be null for anonymous comments
• Images/videos in comments are not analyzed — only text is captured
• Default post limit drops to 30 when --comments is active (override with --limit)

After Fetching

1. Parse the JSON output
2. Posts with images/videos have has_media: true and a media_type field. Their text is in the text field (from the caption). Do not skip posts just because they have media — they often contain important text.
3. Images and videos are not analyzed (no OCR/vision) — only the text/caption is returned.
4. Summarize key themes, top posts by views, notable links
5. If comments_enabled: true, analyze comment sentiment and key themes alongside the main posts
6. Save summary to memory/YYYY-MM-DD.md if user wants to track over time

Saving to File (Token Economy)

Use --output when the result is large (especially with --comments) and you don't need to analyze it immediately. The full data goes to a file, and stdout returns only a short confirmation — this saves tokens.

Periodic updates pattern: set up a cron task that runs tg-reader fetch @channel --comments --output comments.json on schedule. The file gets updated regularly. When the user asks to analyze comments — read the file instead of re-fetching. This avoids consuming tokens on every fetch.

When --output is used without a filename, the default is tg-output.json. Stdout confirmation:

{"status": "ok", "output_file": "/absolute/path/to/tg-output.json", "count": 12}

Saving Channel List

Store tracked channels in TOOLS.md:

## Telegram Channels
- @channel1 — why tracked
- @channel2 — why tracked

Error Handling

Errors include an error_type and action field to help agents decide what to do automatically.

Channel Errors