Claude Code Telegram Bot 部署指南：从零到跑通

本文对应项目 claude-telegram-bot.zip，每一步都标注了对应的项目文件。
预计耗时 15–20 分钟。

0. 你会得到什么

配置完成后，你可以在 Telegram 的任意客户端（手机、桌面、网页）给你的 Bot 发消息，Bot 背后跑着 Claude Code，能帮你：

• 收集碎片信息 → 整理成结构化日报
• 根据数据 → 生成格式化报表
• 记备忘、汇总信息、处理杂事

所有输出直接在 TG 对话框里呈现，不需要切到别的工具。

TG = Telegram，后文所有 "TG" 均指 Telegram 即时通讯平台。

1. 环境准备

1.1 安装 Claude Code

如果还没安装过 Claude Code，先装好：

# macOS / Linux
npm install -g @anthropic-ai/claude-code

验证：

claude --version

能看到版本号就行。

1.2 安装 Bun

Telegram 插件强制依赖 Bun 运行时，Node.js 和 Deno 都不行。

curl -fsSL https://bun.sh/install | bash

装完后新开一个终端窗口，验证：

bun --version

1.3 有一个 Telegram 账号

普通个人账号就行，不需要什么特殊权限。

对应文件: CLAUDE.md → "技术栈" 和 "部署流程" 部分记录了这些依赖。

2. 创建 Telegram Bot

2.1 打开 BotFather

在 Telegram 里搜索 @BotFather，或者直接打开链接：https://t.me/BotFather

2.2 创建新 Bot

给 BotFather 发送：

/newbot

它会依次问你两个问题：

问题 1 — Name（显示名称）

这是聊天顶部显示的名字，可以用中文、可以有空格。
建议取一个能让你一眼认出来的名字，比如：

报表助手

问题 2 — Username（用户名）

这是 Bot 的唯一标识，必须以 bot 结尾，只能用英文、数字和下划线。
比如：

my_report_helper_bot

2.3 保存 Token

BotFather 回复的消息里会有一行长这样的东西：

123456789:AAHfiqksKZ8WxYz1a2b3c4d5e6f7g8h9

这就是 Token，完整复制下来，包括开头的数字和中间的冒号。

⚠️ Token 等同密码。拿到这个 Token 的人可以完全控制你的 Bot。不要发到群里，不要提交到 Git。

2.4 记下 Bot 的用户名

把你设的用户名填到后面会用到的配置里。格式是 @my_report_helper_bot。

对应文件: agents/report-bot/config/.env.example — Token 就写在这个文件的格式里。

3. 解压项目 & 填写配置

3.1 解压

unzip claude-telegram-bot.zip
cd claude-telegram-bot

3.2 看一眼目录结构

.
├── CLAUDE.md                          # Claude Code 全局指令
├── agents/
│   └── report-bot/
│       ├── IDENTITY.md                # Bot 的身份和行为定义
│       ├── USER.md                    # ← 你要填的文件
│       ├── config/
│       │   ├── .env.example
│       │   └── access.json.example
│       └── workspace/
│           ├── dailies/
│           ├── reports/
│           ├── templates/
│           │   ├── daily.md
│           │   └── weekly.md
│           └── scratch/
└── scripts/
    ├── setup.sh
    └── start.sh

3.3 填写 USER.md（重要）

打开 agents/report-bot/USER.md，把里面的占位符替换成你的真实信息：

vim agents/report-bot/USER.md
# 或用你习惯的编辑器

必须填的字段：

建议填的字段：

• "常用术语/缩写表" — 如果你团队有行话（PRD、P0、UAT 之类），填在这里，Bot 就不会误解
• "沟通风格偏好" — 默认已经配好了"直接、主动、紧凑"，不满意可以改

3.4 获取你的 Telegram User ID

在 Telegram 里搜索 @userinfobot，给它发任意一条消息，它会立刻回复你的数字 ID，类似：

Id: 412587349

把这个数字记下来，填到 USER.md 的 "TG User ID" 字段。

3.5 检查 IDENTITY.md（可选）

agents/report-bot/IDENTITY.md 定义了 Bot 的角色、行为规范和输出格式。默认配置已经很完整了，但你可以根据需要微调：

• 日报模板格式（"日报整理规范"部分）
• 禁止事项（不想 Bot 做的事）
• 示例对话（让 Bot 理解你期望的交互方式）

对应文件: agents/report-bot/IDENTITY.md + agents/report-bot/USER.md

4. 安装 Telegram 插件

4.1 启动 Claude Code

claude

进入 Claude Code 的交互会话。

4.2 安装插件

在会话里输入：

/plugin install telegram@claude-plugins-official

等它装完。然后输入：

/reload-plugins

4.3 验证安装

试着输入 /telegram: 然后按 Tab 键。如果能补全出 configure 等命令，说明装好了。

如果不能补全，退出会话（输入 exit），重新运行 claude，再试一次。

5. 配置 Token

5.1 在 Claude Code 会话中配置

把第 2 步拿到的 Token 填进去：

/telegram:configure 123456789:AAHfiqksKZ8WxYz1a2b3c4d5e6f7g8h9

这个命令会把 Token 写入 ~/.claude/channels/telegram/.env。

5.2 或者手动写文件

如果你更喜欢手动操作：

mkdir -p ~/.claude/channels/telegram
echo "TELEGRAM_BOT_TOKEN=123456789:AAHfiqksKZ8WxYz1a2b3c4d5e6f7g8h9" > ~/.claude/channels/telegram/.env
chmod 600 ~/.claude/channels/telegram/.env

chmod 600 确保只有你能读这个文件。

对应文件: agents/report-bot/config/.env.example 就是这个文件的模板。

6. 配置访问控制

把项目里的访问控制模板复制到 Telegram 插件的配置目录：

cp agents/report-bot/config/access.json.example ~/.claude/channels/telegram/access.json

然后编辑，把 YOUR_TELEGRAM_USER_ID 替换成你在第 3.4 步拿到的数字 ID：

vim ~/.claude/channels/telegram/access.json

改这一行：

"allowFrom": ["412587349"],

对应文件: agents/report-bot/config/access.json.example

里面还有 mentionPatterns 字段配了 "日报"、"报表"、"整理"、"记一下" 作为群组触发词。如果你只用私聊，这个不影响。

7. 带 Channel 参数启动

这一步很关键。不带 --channels 参数，插件不会连接 Telegram。

先退出当前的 Claude Code 会话：

exit

然后用以下命令重启：

claude --channels plugin:telegram@claude-plugins-official

或者直接用项目里的脚本：

./scripts/start.sh

启动后你应该能看到 Claude Code 正常进入会话，没有报错。

对应文件: scripts/start.sh 封装了这个命令，带前置检查。

8. 配对

8.1 发起配对

打开 Telegram，找到你创建的 Bot（搜索 @my_report_helper_bot 或你设的用户名），给它发一条消息，随便什么都行：

你好

8.2 收到配对码

Bot 会回复一个 6 位的配对码，类似：

Your pairing code is: a4f91c

8.3 在 Claude Code 中确认

回到 Claude Code 会话，输入：

/telegram:access pair a4f91c

配对成功后，你在 Telegram 发的下一条消息就会直接到达 Claude Code 助手了。

8.4 测试一下

在 Telegram 给 Bot 发：

今天做了代码审查和产品评审会

Bot 应该会回复整理后的内容。如果 Bot 用 👀 react 了你的消息然后回复了结构化的日报，恭喜，配置完成。

9. 锁定安全

配对只是为了获取你的 User ID。完成后，必须切换到 allowlist 模式，否则任何找到你 Bot 用户名的人都能获取配对码。

在 Claude Code 会话中输入：

/telegram:access policy allowlist

或者直接编辑 ~/.claude/channels/telegram/access.json，确认：

"dmPolicy": "allowlist"

从此只有 allowFrom 列表里的用户才能跟 Bot 交互。

10. 日常使用

启动

每次使用前需要启动 Claude Code：

cd claude-telegram-bot
./scripts/start.sh

日报流程

1. 一天中随时给 Bot 发碎片信息："上午开了 XX 会"、"改了 3 个 bug"、"写了一半 PRD"
2. 下班前发 "整理日报" 或 "今天都干了啥"
3. Bot 输出结构化日报
4. 需要修改就直接说 "XX 改成 YY"，Bot 用 edit_message 原地修改

报表流程

1. 发数据给 Bot（文字、截图、或文件）
2. 说 "按 XX 维度整理一下" 或 "做个报表"
3. Bot 输出格式化报表

备忘

• "记一下：明天 10 点跟张总开会"
• "提醒我下周交 XX 文档"（Bot 会记录但说明它没有定时提醒能力）

对应文件: agents/report-bot/IDENTITY.md → "你的行为准则" 部分定义了这些工作流程。
agents/report-bot/workspace/templates/ 里有日报和周报的输出模板。

11. 进阶配置

11.1 添加更多用户

/telegram:access allow 628194073

或者编辑 access.json：

"allowFrom": ["412587349", "628194073"]

11.2 启用群组

/telegram:access group add -1001654782309

群组中 Bot 默认只响应 @提及。如果想让它响应所有消息：

/telegram:access group add -1001654782309 --no-mention

注意：--no-mention 还需要在 BotFather 里禁用隐私模式：给 @BotFather 发 /setprivacy → 选你的 Bot → 选 Disable。

11.3 自定义确认表情

收到消息时的确认表情，默认是 👀，可以换：

/telegram:access set ackReaction ❤

可用的表情是 Telegram 的固定白名单：👍 👎 ❤ 🔥 👏 🤔 🤯 😢 🎉 👀 等。

11.4 自定义触发词（群组用）

/telegram:access set mentionPatterns '["^日报", "^报表", "^hey bot"]'

11.5 运行多个 Bot

每个 Bot 需要不同的 TELEGRAM_STATE_DIR：

# Bot 1: 报表助手
TELEGRAM_STATE_DIR=~/.claude/channels/telegram-report claude --channels plugin:telegram@claude-plugins-official

# Bot 2: 其他用途
TELEGRAM_STATE_DIR=~/.claude/channels/telegram-other claude --channels plugin:telegram@claude-plugins-official

在项目里就是新建一个 agents/other-bot/ 目录，写好它自己的 IDENTITY.md 和 USER.md。

12. 故障排查

Bot 完全不响应

1. 确认 Claude Code 是用 --channels plugin:telegram@claude-plugins-official 启动的
2. 确认 Token 正确：cat ~/.claude/channels/telegram/.env
3. 确认 Bot 没被其他程序占用（一个 Token 同时只能被一个进程使用）

配对码没收到

1. 确认 dmPolicy 是 pairing（而不是 allowlist），配对期间需要用 pairing 模式
2. 确认你是直接 DM Bot，不是在群组里发的

Bot 响应了但输出很奇怪

检查 IDENTITY.md 是否被正确读取。在 Claude Code 里问一句：

你的身份是什么？你负责什么？

如果回答和 IDENTITY.md 描述不符，可能是 Claude Code 没有读到项目文件，确认你是在项目目录下启动的。

图片模糊

Telegram 会自动压缩图片。需要原图的话，发送时长按 → 选"发送为文件"。

文件速查表

完整命令速查

# ========== 安装阶段（只做一次）==========
curl -fsSL https://bun.sh/install | bash        # 装 Bun
claude                                            # 启动 Claude Code
/plugin install telegram@claude-plugins-official  # 装插件
/telegram:configure <TOKEN>                       # 配 Token
exit                                              # 退出

# ========== 日常启动 ==========
cd claude-telegram-bot
./scripts/start.sh                                # 启动

# ========== 配对 & 安全 ==========
/telegram:access pair <code>                      # 配对
/telegram:access policy allowlist                 # 锁定

# ========== 管理 ==========
/telegram:access                                  # 查看状态
/telegram:access allow <id>                       # 加人
/telegram:access remove <id>                      # 删人
/telegram:access group add <group_id>             # 加群
/telegram:access set ackReaction 👀               # 改表情

files.zip

TG-Bot-Deploy-Guide.txt