sergei-mikhailov-tg-channel-reader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

通过MTProto（Pyrogram或Telethon）读取Telegram频道的帖子和评论。适用于所有公开频道以及用户已订阅的私有频道。支持获取单条帖子的讨论回复（评论）。

安全提示： 本技能需要从my.telegram.org获取
TG_API_ID
和
TG_API_HASH
。会话文件拥有Telegram账户的完全访问权限——请妥善保管，切勿分享。

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.

刚通过
clawhub install
安装完成？请先完成下方的设置与安装步骤——本技能需要先完成
pip install
、配置凭证和生成会话文件，之后才需要考虑执行权限审批的问题。

OpenClaw默认会拦截未知的CLI命令。用户必须先批准

tg-reader

相关命令才能运行。如果命令卡住或用户反馈没有任何反应，很可能是执行权限审批处于待处理状态。

Quick setup (recommended)

快速设置（推荐）

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

bash

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

进入技能目录运行以下命令——会检查前置条件、按需安装pip包，并打印需要运行的权限审批命令：

bash

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

Manual CLI approval

手动CLI审批

bash

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)"

bash

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

替代方案：首次使用时审批

Control UI — open
```
http://localhost:18789/
```
, find the pending approval for
```
tg-reader
```
, click "Always allow". Docs
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.

控制UI——打开
```
http://localhost:18789/
```
，找到
```
tg-reader
```
的待审批请求，点击**“始终允许”**。文档
通讯工具（Telegram、Slack、Discord）——机器人会发送带
```
<id>
```
的审批请求。回复：
```
/approve <id> allow-always
```
。其他选项：
```
allow-once
```
（允许一次）、
```
deny
```
（拒绝）。

审批提示会出现在控制UI或机器人消息中，而非Agent的对话界面。这是常见的混淆点。

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
```

用户要求“查看”“读取”或“监控”某个Telegram频道
需要频道近期帖子的摘要或汇总
用户询问“@channel频道有什么新内容”或“总结@channel频道过去24小时的内容”
需要跟踪或对比多个频道
需要获取频道信息（标题、描述、订阅人数）——使用
```
tg-reader info
```
命令

Quick Start

快速开始

bash

undefined

bash

undefined

1. Run pre-flight diagnostic (fast, no Telegram connection)

1. 运行预检诊断（快速，无需连接Telegram）

tg-reader-check

2. Get channel info

2. 获取频道信息

tg-reader info @channel_name

3. Fetch recent posts

3. 获取近期帖子

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 .`

---

tg-reader fetch @channel_name --since 24h


> **提示：如果出现`tg-reader: command not found`？** 进入技能目录运行`bash setup-tg-reader.sh`（会自动安装包），或手动执行：`cd ~/.openclaw/workspace/skills/sergei-mikhailov-tg-channel-reader && pip install .`

---

Commands

命令说明

tg-reader-check

— Pre-flight Diagnostic

tg-reader-check

— 预检诊断

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

bash

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"

"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)

获取内容前请务必运行此命令。快速离线检查——无需连接Telegram。

bash

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

返回包含

"status": "ok"

或

"status": "error"

的JSON，以及

problems

数组。

验证内容包括：

是否有可用凭证（环境变量或
```
~/.tg-reader.json
```
）
磁盘上是否存在会话文件（包含文件大小、修改日期）
是否至少安装了一个MTProto后端（Pyrogram或Telethon）
检测过期会话（配置指向旧文件，但存在更新的文件）

tg-reader info

— Channel Info

tg-reader info

— 频道信息

bash

tg-reader info @channel_name

Returns title, description, subscriber count, and link.

bash

tg-reader info @channel_name

返回频道标题、描述、订阅人数和链接。

tg-reader fetch

— Read Posts

tg-reader fetch

— 读取帖子

bash

undefined

bash

undefined

Last 24 hours (default)

过去24小时的内容（默认）

tg-reader fetch @channel_name --since 24h

Last 7 days, up to 200 posts

过去7天的内容，最多200条帖子

tg-reader fetch @channel_name --since 7d --limit 200

Multiple channels (fetched sequentially with 10s delay between each)

多个频道（按顺序获取，频道间间隔10秒）

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)

获取带评论的帖子（仅支持单个频道，自动将限制数降至30）

tg-reader fetch @channel_name --since 7d --comments

每条帖子获取更多评论，自定义帖子间的间隔时间

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)

使用Telethon而非Pyrogram（单次生效）

tg-reader fetch @channel_name --since 24h --telethon

Read unread mode — only fetch new (unread) posts, no --since needed

未读模式——仅获取新的未读帖子，无需指定--since

Requires "read_unread": true in ~/.tg-reader.json

需要在~/.tg-reader.json中设置"read_unread": true

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

undefined

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

undefined

tg-reader auth

— First-time Authentication

tg-reader auth

— 首次认证

bash

tg-reader auth

Creates a session file. Only needed once.

bash

tg-reader auth

生成会话文件。仅需运行一次。

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

json

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

Option B — env var (works with

~/.openclaw/openclaw.json

bash

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).

选项A — 配置文件（

~/.tg-reader.json

）：

json

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

选项B — 环境变量（可配合

~/.openclaw/openclaw.json

使用）：

bash

export TG_READ_UNREAD=true

环境变量优先级高于配置文件。这允许你通过

openclaw.json

的Docker

env

配置项，与

TG_API_ID

TG_API_HASH

一起启用未读模式。

状态存储在

~/.tg-reader-state.json

中（可通过配置文件中的

"state_file"

、环境变量

TG_STATE_FILE

或

--state-file

参数修改路径）。

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

启用
```
read_unread
```
时无需指定
--since
——技能会自动返回所有未读帖子，不受时间限制
首次运行（频道无历史状态）：
```
--since
```
参数正常生效（默认24小时）；同时创建状态文件
后续运行：仅返回比上次读取时间更新的帖子；
```
--since
```
参数会被忽略
--all
参数：绕过未读模式——按
```
--since
```
指定的范围获取所有内容，且不更新状态（保留上次读取位置）
新频道：行为与首次运行一致（无历史状态）
无新帖子：状态不变，返回
```
count: 0
```

Examples

使用示例

bash

undefined

bash

undefined

With read_unread enabled — just fetch, no --since needed

启用未读模式时——直接获取，无需--since

tg-reader fetch @channel_name

First run for a new channel — --since determines initial window

新频道首次运行——--since指定初始时间范围

tg-reader fetch @new_channel --since 7d

Override: fetch everything, don't update tracking state

覆盖未读模式：获取所有内容，不更新跟踪状态

tg-reader fetch @channel_name --since 7d --all

undefined

tg-reader fetch @channel_name --since 7d --all

undefined

Output

输出格式

When read_unread mode is active, the JSON output includes a

read_unread

field:

json

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

With

--all

"read_unread": {"enabled": true, "overridden": true}

启用未读模式时，JSON输出会包含

read_unread

字段：

json

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

使用

--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:

json

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

tg-reader-check

会报告跟踪状态：

json

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

Output Format

输出格式

info

info

命令输出

json

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

json

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

fetch

fetch

命令输出

json

{
  "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"
    }
  ]
}

json

{
  "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

带

--comments

参数的

fetch

输出

json

{
  "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
```
)

json

{
  "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"
        }
      ]
    }
  ]
}

注意事项：

```
comments_available: false
```
——频道未关联讨论组（无法获取评论）
帖子出现
```
comments_error
```
——获取该帖子评论时触发了速率限制
匿名评论的
```
from_user
```
可能为
```
null
```
评论中的图片/视频不会被分析——仅捕获文本内容
启用
```
--comments
```
时，默认帖子限制数会降至30（可通过
```
--limit
```
参数覆盖）

After Fetching

获取内容后的处理建议

Parse the JSON output
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.
Images and videos are not analyzed (no OCR/vision) — only the text/caption is returned.
Summarize key themes, top posts by views, notable links
If
```
comments_enabled: true
```
, analyze comment sentiment and key themes alongside the main posts
Save summary to
```
memory/YYYY-MM-DD.md
```
if user wants to track over time

解析JSON输出
含图片/视频的帖子会标记
```
has_media: true
```
并带有
```
media_type
```
字段，文本内容在
```
text
```
字段（来自媒体标题）。不要仅因为帖子含媒体就跳过——它们通常包含重要文本信息。
图片和视频不会被分析（无OCR/视觉识别）——仅返回文本/标题。
总结核心主题、高浏览量帖子和重要链接
如果
```
comments_enabled: true
```
，结合主帖子分析评论的情感和核心主题
如果用户需要长期跟踪，将摘要保存到
```
memory/YYYY-MM-DD.md
```

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:

json

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

当结果较大时（尤其是启用

--comments

时），使用

--output

参数，无需立即分析。完整数据会写入文件，标准输出仅返回简短确认——这能节省令牌。

定期更新模式： 设置定时任务，定期运行

tg-reader fetch @channel --comments --output comments.json

。文件会定期更新。当用户要求分析评论时——直接读取文件而非重新获取。这样可以避免每次获取都消耗令牌。

使用

--output

但不指定文件名时，默认输出文件为

tg-output.json

。标准输出的确认信息如下：

json

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

Saving Channel List

保存频道列表

Store tracked channels in

TOOLS.md

markdown

undefined

将跟踪的频道存储在

TOOLS.md

中：

markdown

undefined

Telegram Channels

@channel1 — why tracked
@channel2 — why tracked

---

@channel1 — 跟踪原因
@channel2 — 跟踪原因

---

Error Handling

错误处理

Errors include an

error_type

and

action

field to help agents decide what to do automatically.

错误信息包含

error_type

和

action

字段，帮助Agent自动判断处理方式。

Channel Errors

频道相关错误

`error_type`	Meaning	`action`
`access_denied`	Channel is private, you were kicked, or access is restricted	`remove_from_list_or_rejoin` — ask user if they still have access; if not, remove the channel
`banned`	You are banned from this channel	`remove_from_list` — remove the channel, tell the user
`not_found`	Channel doesn't exist or username is wrong	`check_username` — verify the @username with the user
`invite_expired`	Invite link is expired or invalid	`request_new_invite` — ask user for a new invite link
`flood_wait`	Telegram rate limit	`wait_Ns` — waits ≤ 60 s are retried automatically; longer waits return this error
`comments_multi_channel`	`--comments` used with multiple channels	`remove_extra_channels_or_drop_comments` — use one channel at a time

`error_type`	含义	`action`
`access_denied`	频道为私有、用户被踢出或访问受限	`remove_from_list_or_rejoin` — 询问用户是否仍有访问权限；若无则移除该频道
`banned`	用户被该频道封禁	`remove_from_list` — 移除该频道并告知用户
`not_found`	频道不存在或用户名错误	`check_username` — 与用户确认@用户名是否正确
`invite_expired`	邀请链接过期或无效	`request_new_invite` — 向用户索要新的邀请链接
`flood_wait`	Telegram速率限制	`wait_Ns` — ≤60秒的等待会自动重试；更长等待会返回此错误
`comments_multi_channel`	多频道场景下使用了 `--comments` 参数	`remove_extra_channels_or_drop_comments` — 一次仅使用一个频道

System Errors

系统相关错误

Error	Action
`Session file not found`	Run `tg-reader-check` — use the `suggestion` from output
`Missing credentials`	Guide user through Setup (Step 1-2 below)
`tg-reader: command not found`	Run `bash setup-tg-reader.sh` from the skill directory, or manually: `pip install .` Fallback: `python3 -m tg_reader_unified`
`AUTH_KEY_UNREGISTERED`	Session expired — delete and re-auth (see below)

错误	处理方式
`Session file not found`	运行 `tg-reader-check` ——根据输出中的 `suggestion` 解决
`Missing credentials`	引导用户完成设置步骤（下方步骤1-2）
`tg-reader: command not found`	进入技能目录运行 `bash setup-tg-reader.sh` ，或手动执行： `pip install .` 。备选方案： `python3 -m tg_reader_unified`
`AUTH_KEY_UNREGISTERED`	会话过期——删除并重新认证（见下方说明）

Session Expired

会话过期处理

bash

rm -f ~/.tg-reader-session.session
tg-reader auth

bash

rm -f ~/.tg-reader-session.session
tg-reader auth

Auth Code Not Arriving

认证码未收到

Use the verbose debug script for full MTProto-level logs:

bash

python3 debug_auth.py

Warning:
debug_auth.py
deletes existing session files before re-authenticating. It will ask for confirmation first.

使用 verbose 调试脚本查看完整MTProto层级日志：

bash

python3 debug_auth.py

警告：
debug_auth.py
会在重新认证前删除现有会话文件。运行前会要求确认。

Library Selection

后端库选择

Two MTProto backends are supported:

Backend	Command	Notes
Pyrogram (default)	`tg-reader` or `tg-reader-pyrogram`	Modern, actively maintained
Telethon	`tg-reader-telethon`	Alternative if Pyrogram has issues

Switch persistently:

export TG_USE_TELETHON=true

Switch one-time:

tg-reader fetch @channel --since 24h --telethon

支持两种MTProto后端：

后端	命令	说明
Pyrogram（默认）	`tg-reader` 或 `tg-reader-pyrogram`	现代、持续维护
Telethon	`tg-reader-telethon`	Pyrogram出现问题时的替代方案

永久切换：

export TG_USE_TELETHON=true

单次切换：

tg-reader fetch @channel --since 24h --telethon

Setup & Installation

设置与安装

Full details in README.md.

详细说明见README.md。

Step 1 — Get API Credentials

步骤1 — 获取API凭证

Go to https://my.telegram.org → API Development Tools → create an app → copy

api_id

and

api_hash

访问https://my.telegram.org → API Development Tools → 创建应用 → 复制

api_id

和

api_hash

。

Step 2 — Save Credentials

步骤2 — 保存凭证

Recommended (works in agents and servers):

bash

cat > ~/.tg-reader.json << 'EOF'
{
  "api_id": YOUR_ID,
  "api_hash": "YOUR_HASH"
}
EOF
chmod 600 ~/.tg-reader.json

Alternative (interactive shell only):

bash

export TG_API_ID=YOUR_ID
export TG_API_HASH="YOUR_HASH"

Set these in your current shell session. Avoid writing

TG_API_HASH

to shell profiles (

~/.bashrc

) — use

~/.tg-reader.json

instead for persistent storage.

Note: Agents and servers don't load shell profiles. Use
~/.tg-reader.json
(the recommended method above) for non-interactive environments.

推荐方式（适用于Agent和服务器）：

bash

cat > ~/.tg-reader.json << 'EOF'
{
  "api_id": YOUR_ID,
  "api_hash": "YOUR_HASH"
}
EOF
chmod 600 ~/.tg-reader.json

替代方式（仅适用于交互式Shell）：

bash

export TG_API_ID=YOUR_ID
export TG_API_HASH="YOUR_HASH"

在当前Shell会话中设置。避免将

TG_API_HASH

写入Shell配置文件（

~/.bashrc

）——推荐使用

~/.tg-reader.json

进行持久化存储。

注意： Agent和服务器不会加载Shell配置文件。非交互式环境请使用上述推荐的
~/.tg-reader.json
方式。

Step 3 — Install & Configure

步骤3 — 安装与配置

bash

npx clawhub@latest install sergei-mikhailov-tg-channel-reader
cd ~/.openclaw/workspace/skills/sergei-mikhailov-tg-channel-reader
bash setup-tg-reader.sh

The setup script: installs Python packages (

pip install .

), checks credentials and session, runs

tg-reader-check

, and prints the exec approval commands for you to run manually.

On Linux with managed Python (Ubuntu/Debian), use a venv before running the setup script:

bash

python3 -m venv ~/.venv/tg-reader
echo 'export PATH="$HOME/.venv/tg-reader/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

<details> <summary>Manual install (without setup script)</summary>

bash

cd ~/.openclaw/workspace/skills/sergei-mikhailov-tg-channel-reader
pip install pyrogram tgcrypto telethon && pip install .
openclaw approvals allowlist add --gateway "$(which tg-reader)"
openclaw approvals allowlist add --gateway "$(which tg-reader-check)"

</details>

bash

npx clawhub@latest install sergei-mikhailov-tg-channel-reader
cd ~/.openclaw/workspace/skills/sergei-mikhailov-tg-channel-reader
bash setup-tg-reader.sh

设置脚本会：安装Python包（

pip install .

）、检查凭证和会话、运行

tg-reader-check

、并打印需要手动运行的权限审批命令。

在使用托管Python的Linux系统（Ubuntu/Debian）上，运行设置脚本前请先创建虚拟环境：

bash

python3 -m venv ~/.venv/tg-reader
echo 'export PATH="$HOME/.venv/tg-reader/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

<details> <summary>手动安装（不使用设置脚本）</summary>

bash

cd ~/.openclaw/workspace/skills/sergei-mikhailov-tg-channel-reader
pip install pyrogram tgcrypto telethon && pip install .
openclaw approvals allowlist add --gateway "$(which tg-reader)"
openclaw approvals allowlist add --gateway "$(which tg-reader-check)"

</details>

Step 4 — Authenticate

步骤4 — 认证

bash

tg-reader auth

Pyrogram will ask to confirm the phone number — answer

. The code arrives in the Telegram app (not SMS).

bash

tg-reader auth

Pyrogram会要求确认手机号码——回复

。验证码会发送到Telegram应用（而非短信）。

Step 5 — Verify

步骤5 — 验证

bash

tg-reader-check

Should return

"status": "ok"

. If not — fix the reported issues and re-run

bash setup-tg-reader.sh

bash

tg-reader-check

应返回

"status": "ok"

。若未返回，请修复报告的问题并重新运行

bash setup-tg-reader.sh

。

Scheduled Tasks & Cron

定时任务与Cron

This skill needs network access (MTProto connection to Telegram servers) and a session file. How you configure OpenClaw cron depends on the session target.

Important: When setting up a scheduled task that uses
tg-reader
, tell the user which approach you're using and what it means — so they can make an informed choice.

本技能需要网络访问（与Telegram服务器的MTProto连接）和会话文件。OpenClaw定时任务的配置方式取决于会话目标。

重要提示： 设置使用
tg-reader
的定时任务时，请告知用户你使用的方式及其含义——以便用户做出知情选择。

Option A —

sessionTarget: "main"

(recommended)

选项A —

sessionTarget: "main"

（推荐）

The cron task sends a reminder to the main agent session. The agent then runs

tg-reader

in the main environment where the skill, credentials, and session file are already available.

Pros: No extra configuration — everything works out of the box. Cons: Not fully autonomous — the task sends a system event, the agent picks it up and executes. Requires

payload.kind: "systemEvent"

(OpenClaw cron API limitation for main target).

How to set up:

Create a cron task with

sessionTarget: "main"

and

payload.kind: "systemEvent"

In the task description, include the exact
```
tg-reader
```
command to run
The agent receives the reminder and executes the command in its main session

定时任务会向主Agent会话发送提醒。Agent随后会在已安装技能、配置凭证和会话文件的主环境中运行

tg-reader

。

优点： 无需额外配置——开箱即用。 缺点： 并非完全自主——任务发送系统事件，Agent接收后执行。受限于OpenClaw定时任务API，需要设置

payload.kind: "systemEvent"

（针对main目标的限制）。

设置方法：

创建定时任务，设置

sessionTarget: "main"

和

payload.kind: "systemEvent"

在任务描述中包含要运行的
```
tg-reader
```
命令
Agent接收提醒后，在主会话中执行命令

Option B —

sessionTarget: "isolated"

(autonomous, complex setup)

选项B —

sessionTarget: "isolated"

（完全自主，配置复杂）

The cron task runs in a Docker container — fully autonomous, no agent interaction needed. However, the container starts empty: no skill, no credentials, no session file.

Pros: Fully autonomous — runs on schedule without agent involvement. Cons: Requires Docker setup; session file must be mounted into the container (may not work reliably — session files are tied to the machine and Telegram may invalidate them in a new environment).

Required configuration in
~/.openclaw/openclaw.json
:

json

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "setupCommand": "clawhub install sergei-mikhailov-tg-channel-reader && cd ~/.openclaw/workspace/skills/sergei-mikhailov-tg-channel-reader && pip install pyrogram tgcrypto telethon && pip install .",
          "env": {
            "TG_API_ID": "YOUR_ID",
            "TG_API_HASH": "YOUR_HASH",
            "TG_READ_UNREAD": "true"
          }
        }
      }
    }
  }
}

Session file caveat: The Telegram session file (

~/.tg-reader-session.session

) must also be available inside the container. This may require Docker volume mounting and might not work reliably — Telegram can invalidate sessions when they appear from a different environment. If you encounter

AUTH_KEY_UNREGISTERED

errors in isolated mode, switch to Option A.

定时任务在Docker容器中运行——完全自主，无需Agent交互。但容器启动时为空：无技能、无凭证、无会话文件。

优点： 完全自主——按计划运行，无需Agent参与。 缺点： 需要Docker配置；会话文件必须挂载到容器中（可能无法可靠工作——会话文件与机器绑定，Telegram可能会在新环境中使会话失效）。

~/.openclaw/openclaw.json
中所需配置：

json

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "setupCommand": "clawhub install sergei-mikhailov-tg-channel-reader && cd ~/.openclaw/workspace/skills/sergei-mikhailov-tg-channel-reader && pip install pyrogram tgcrypto telethon && pip install .",
          "env": {
            "TG_API_ID": "YOUR_ID",
            "TG_API_HASH": "YOUR_HASH",
            "TG_READ_UNREAD": "true"
          }
        }
      }
    }
  }
}

会话文件注意事项： Telegram会话文件（

~/.tg-reader-session.session

）必须在容器内可用。这可能需要Docker卷挂载，但可能无法可靠工作——当会话在不同环境中出现时，Telegram可能会使会话失效。如果在隔离模式下遇到

AUTH_KEY_UNREGISTERED

错误，请切换到选项A。

Explicit paths (both options)

显式路径（两种选项通用）

When

~/

is not available or points to a different location, use explicit paths:

bash

tg-reader-check \
  --config-file /home/user/.tg-reader.json \
  --session-file /home/user/.tg-reader-session

tg-reader fetch @channel --since 6h \
  --config-file /home/user/.tg-reader.json \
  --session-file /home/user/.tg-reader-session

Both flags work with all subcommands and both backends.

当

~/

不可用或指向其他位置时，使用显式路径：

bash

tg-reader-check \
  --config-file /home/user/.tg-reader.json \
  --session-file /home/user/.tg-reader-session

tg-reader fetch @channel --since 6h \
  --config-file /home/user/.tg-reader.json \
  --session-file /home/user/.tg-reader-session

这两个参数适用于所有子命令和两种后端。

Security

安全注意事项

Session file (
```
~/.tg-reader-session.session
```
) grants full account access — keep it safe
Never share or commit
```
TG_API_HASH
```
or session files
```
TG_API_HASH
```
is a secret — store in env vars or config file, never in git

会话文件（
```
~/.tg-reader-session.session
```
）拥有账户完全访问权限——请妥善保管
切勿分享或提交
```
TG_API_HASH
```
或会话文件
```
TG_API_HASH
```
是机密信息——请存储在环境变量或配置文件中，切勿提交到git

sergei-mikhailov-tg-channel-reader

Original

Translation

tg-channel-reader

tg-channel-reader

Exec Approvals

执行权限审批

Quick setup (recommended)

快速设置（推荐）

Manual CLI approval

手动CLI审批

Alternative: approve on first use

替代方案：首次使用时审批

When to Use

使用场景

Quick Start

快速开始

1. Run pre-flight diagnostic (fast, no Telegram connection)

1. 运行预检诊断（快速，无需连接Telegram）

2. Get channel info

2. 获取频道信息

3. Fetch recent posts

3. 获取近期帖子

Commands

命令说明

tg-reader-check — Pre-flight Diagnostic

tg-reader-check — 预检诊断

tg-reader info — Channel Info

tg-reader info — 频道信息

tg-reader fetch — Read Posts

tg-reader fetch — 读取帖子

Last 24 hours (default)

过去24小时的内容（默认）

Last 7 days, up to 200 posts

过去7天的内容，最多200条帖子

Multiple channels (fetched sequentially with 10s delay between each)

多个频道（按顺序获取，频道间间隔10秒）

Custom delay between channels (seconds)

自定义频道间的间隔时间（秒）

Fetch posts with comments (single channel only, limit auto-drops to 30)

获取带评论的帖子（仅支持单个频道，自动将限制数降至30）

More comments per post, custom delay between posts

每条帖子获取更多评论，自定义帖子间的间隔时间

Skip posts without text (media-only, no caption)

跳过无文本的帖子（仅含媒体、无标题）

Human-readable output

人类可读格式输出

Write output to file instead of stdout (saves tokens)

将输出写入文件而非标准输出（节省令牌）

Use Telethon instead of Pyrogram (one-time)

使用Telethon而非Pyrogram（单次生效）

Read unread mode — only fetch new (unread) posts, no --since needed

未读模式——仅获取新的未读帖子，无需指定--since

Requires "read_unread": true in ~/.tg-reader.json

需要在~/.tg-reader.json中设置"read_unread": true

Override read_unread mode (fetch everything, don't update state)

覆盖未读模式（获取所有内容，不更新状态）

Custom state file location

自定义状态文件路径

tg-reader auth — First-time Authentication

tg-reader auth — 首次认证

Read Unread Mode

未读消息读取模式

Setup

设置方法

Behavior

行为规则

Examples

使用示例

With read_unread enabled — just fetch, no --since needed

启用未读模式时——直接获取，无需--since

First run for a new channel — --since determines initial window

新频道首次运行——--since指定初始时间范围

Override: fetch everything, don't update tracking state

覆盖未读模式：获取所有内容，不更新跟踪状态

Output

输出格式

Limitations

局限性

Diagnostic

`tg-reader-check`
— Pre-flight Diagnostic

`tg-reader-check`
— 预检诊断

`tg-reader info`
— Channel Info

`tg-reader info`
— 频道信息

`tg-reader fetch`
— Read Posts

`tg-reader fetch`
— 读取帖子

`tg-reader auth`
— First-time Authentication

`tg-reader auth`
— 首次认证

`info`

`info`
命令输出

`fetch`

`fetch`
命令输出

`fetch`
with
`--comments`

带
`--comments`
参数的
`fetch`
输出

Option A —
`sessionTarget: "main"`
(recommended)

选项A —
`sessionTarget: "main"`
（推荐）

Option B —
`sessionTarget: "isolated"`
(autonomous, complex setup)

选项B —
`sessionTarget: "isolated"`
（完全自主，配置复杂）