claudecode-telegram

Claude Code 的 Telegram 机器人桥接。通过 Telegram 发送消息，获取回复。

工作原理

flowchart LR
    A[Telegram] --> B[Cloudflare 隧道]
    B --> C[桥接服务器]
    C -->|tmux send-keys| D[Claude Code]
    D -->|Stop Hook| E[读取对话记录]
    E -->|发送回复| A

1. 桥接服务接收 Telegram Webhook，通过 tmux 将消息注入 Claude Code。
2. Claude Code 的 Stop hook 读取对话记录，并将回复发送回 Telegram。
3. 只响应由 Telegram 发起的消息（使用 pending 文件作为标志）。

安装

# 先决条件
brew install tmux cloudflared

# 克隆
git clone https://github.com/hanxiao/claudecode-telegram
cd claudecode-telegram

# 设置 Python 环境
uv venv && source .venv/bin/activate
uv pip install -e .

配置

1. 创建 Telegram 机器人

机器人用于接收你的消息，并将 Claude 的回复发送回去。

# 在 Telegram 中联系 @BotFather，创建机器人并获取 token

2. 配置 Stop hook

Hook 在 Claude 完成响应时触发，读取对话记录并发送到 Telegram。

cp hooks/send-to-telegram.sh ~/.claude/hooks/
nano ~/.claude/hooks/send-to-telegram.sh  # 设置你的机器人 token
chmod +x ~/.claude/hooks/send-to-telegram.sh

添加到 ~/.claude/settings.json：

{
  "hooks": {
    "Stop": [{"hooks": [{"type": "command", "command": "~/.claude/hooks/send-to-telegram.sh"}]}]
  }
}

3. 启动 tmux + Claude

tmux 使 Claude Code 持续运行；桥接服务通过 send-keys 注入消息。

tmux new -s claude
claude --dangerously-skip-permissions

4. 运行桥接服务

桥接服务接收 Telegram Webhook，并将消息注入 Claude Code。

export TELEGRAM_BOT_TOKEN="your_token"
python bridge.py

5. 使用 Cloudflare 隧道暴露服务

隧道将本地桥接服务暴露到互联网，以便 Telegram 能够访问。

cloudflared tunnel --url http://localhost:8080

6. 设置 Webhook

告知 Telegram 将消息更新发送到哪里。

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook?url=https://YOUR-TUNNEL-URL.trycloudflare.com"

机器人命令

命令	描述
/status	检查 tmux 会话
/clear	清除对话
/resume	选择要恢复的会话（内联键盘）
/continue_	自动继续最近的对话
/loop <prompt>	启动 Ralph Loop（5 次迭代）
/stop	中断 Claude

环境变量

变量	默认值	描述
TELEGRAM_BOT_TOKEN	必填	来自 BotFather 的机器人 token
TMUX_SESSION	claude	tmux 会话名称
PORT	8080	桥接服务端口

claudecode-telegram 快速上手指南

将 Claude Code 接入 Telegram，实现通过聊天机器人发送指令并获取代码生成结果。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统：macOS 或 Linux（需支持 tmux）
• 前置依赖：
  • tmux：用于保持 Claude Code 会话持久运行
  • cloudflared：用于将本地服务暴露到公网以接收 Telegram 回调
  • Python (推荐 3.10+) 及 uv：用于管理虚拟环境和依赖
  • Claude Code CLI：已安装并配置好 API Key

安装依赖命令 (macOS):

brew install tmux cloudflared

安装步骤

1. 克隆项目

   git clone https://github.com/hanxiao/claudecode-telegram
   cd claudecode-telegram
   

2. 配置 Python 环境 使用 uv 创建虚拟环境并安装依赖：

   uv venv && source .venv/bin/activate
   uv pip install -e .
   

   国内加速提示：如果下载缓慢，可指定国内源： uv pip install -e . --index-url https://pypi.tuna.tsinghua.edu.cn/simple

3. 创建 Telegram Bot

   • 在 Telegram 中搜索并打开 @BotFather。
   • 发送 /newbot 按提示创建机器人。
   • 复制生成的 API Token 备用。

4. 配置 Stop Hook (关键步骤) 该脚本会在 Claude 回答结束时自动将结果发回 Telegram。

   • 复制脚本模板：

     cp hooks/send-to-telegram.sh ~/.claude/hooks/
     

   • 编辑脚本，填入你的 Bot Token：

     nano ~/.claude/hooks/send-to-telegram.sh
     # 找到 TELEGRAM_BOT_TOKEN 变量并填入你的 token
     

   • 赋予执行权限：

     chmod +x ~/.claude/hooks/send-to-telegram.sh
     

   • 注册 Hook 到 Claude 配置： 编辑 ~/.claude/settings.json，添加以下内容：

     {
       "hooks": {
         "Stop": [{"hooks": [{"type": "command", "command": "~/.claude/hooks/send-to-telegram.sh"}]}]
       }
     }
     

基本使用

完成以下四个终端操作即可启动服务：

1. 启动 Claude Code 会话

在一个终端窗口中创建名为 claude 的 tmux 会话并启动 Claude（跳过权限确认以便自动化）：

tmux new -s claude
claude --dangerously-skip-permissions

保持此窗口运行，不要关闭。

2. 运行桥接服务

新建一个终端窗口，激活虚拟环境并启动桥接程序：

source .venv/bin/activate
export TELEGRAM_BOT_TOKEN="你的_Bot_Token"
python bridge.py

默认监听端口为 8080。

3. 暴露公网地址

新建一个终端窗口，使用 Cloudflare Tunnel 将本地服务暴露给互联网：

cloudflared tunnel --url http://localhost:8080

等待输出中出现类似 https://xxxx-xxxx.trycloudflare.com 的网址，复制该网址。

4. 设置 Telegram Webhook

告诉 Telegram 将消息转发到你的公网地址：

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook?url=https://你的-TUNNEL-网址.trycloudflare.com"

若返回 "ok": true 则表示设置成功。

开始对话

现在，直接在 Telegram 中向你创建的机器人发送消息，它将自动输入到 tmux 中的 Claude Code，并在生成完毕后回复你。

常用指令：

• /status：检查 tmux 会话状态
• /clear：清空当前对话上下文
• /stop：中断 Claude 当前的生成