Skip to content

README-cn.md

Latest commit

 

History

History
323 lines (242 loc) · 7.79 KB

README-cn.md

File metadata and controls

323 lines (242 loc) · 7.79 KB
Raw

claudecode-telegram

English

demo

Claude Code 的 Telegram 机器人桥接工具。通过 Telegram 发送消息，获取 Claude 的响应。

工作原理

flowchart TB
    subgraph Telegram["Telegram 端"]
        TG[Telegram App]
        API[Telegram Bot API]
    end

    subgraph Internet["互联网"]
        CF[Cloudflare Tunnel]
    end

    subgraph Local["本地系统"]
        subgraph Bridge["Bridge Server (bridge.py)"]
            HTTP[HTTP Handler<br/>端口 8091]
            CMD[命令处理器<br/>/status /clear /resume /stop]
            TMUX_CTRL[Tmux 控制器<br/>send-keys 注入]
        end

        subgraph Files["文件系统 (~/.claude/)"]
            CHAT[telegram_chat_id]
            PEND[telegram_pending]
            SETTINGS[settings.json<br/>Stop Hook 配置]
            HOOK_FILE[hooks/send-to-telegram.sh]
        end

        subgraph Claude["Claude Code"]
            CC[claude --dangerously-skip-permissions]
            HOOK[Stop Hook 触发]
            TRANSCRIPT[transcript.jsonl]
        end

        SESS[tmux Session: claude]
    end

    TG --> API
    API --> CF
    CF --> HTTP
    HTTP --> CMD
    CMD --> TMUX_CTRL
    TMUX_CTRL -->|"tmux send-keys"| SESS
    SESS --> CC
    CC -->|"Stop Hook"| HOOK
    HOOK -->|"读取 transcript"| TRANSCRIPT
    HOOK -->|"发送响应"| API

    CMD -->|"写入"| CHAT
    CMD -->|"写入"| PEND
    HOOK -->|"读取"| CHAT
    HOOK -->|"读取/删除"| PEND
    CC -->|"加载"| SETTINGS
Loading

数据流

  1. 消息接收: Telegram → Cloudflare Tunnel → Bridge Server
  2. 消息注入: Bridge Server → tmux send-keys → Claude Code
  3. 响应获取: Claude Code Stop Hook → 读取 transcript.jsonl → 解析输出
  4. 响应发送: Stop Hook → Telegram Bot API → Telegram

前置条件

# macOS
brew install tmux cloudflared

# 确认 claude 已安装
claude --version

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

快速开始

1. 克隆项目

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

2. 创建 Telegram Bot

  1. 在 Telegram 中搜索 @BotFather
  2. 发送 /newbot 并按提示操作
  3. 获取 Bot Token（格式如 123456789:ABCdefGHIjklMNOpqrsTUVwxyz）

3. 一键启动（推荐）

# 设置 Bot Token
export TELEGRAM_BOT_TOKEN="your_token_from_botfather"

# 运行启动脚本
./start-bridge.sh

启动脚本会自动：

  • 检查环境变量和依赖
  • 创建 ~/.claude/hooks 目录
  • 安装 Hook 脚本并更新 Bot Token
  • 将 Hook 配置合并到 ~/.claude/settings.json（保留现有设置）
  • 创建 tmux 会话并启动 Claude Code
  • 启动 Cloudflare Tunnel 并设置 Telegram Webhook
  • 启动 Bridge Server

停止所有服务：

./stop-clean-bridge.sh

4. 手动配置（可选）

安装 Hook 脚本

# 创建目录
mkdir -p ~/.claude/hooks

# 复制 Hook 脚本
cp hooks/send-to-telegram.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/send-to-telegram.sh

# 设置 Bot Token
nano ~/.claude/hooks/send-to-telegram.sh
# 修改 TELEGRAM_BOT_TOKEN="your_token_here"

或通过环境变量设置（推荐）：

export TELEGRAM_BOT_TOKEN="your_token"

配置 settings.json

在 ~/.claude/settings.json 中添加 Hook 配置：

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

启动 tmux + Claude Code

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

运行 Bridge Server

在另一个终端：

export TELEGRAM_BOT_TOKEN="your_token"
python3 bridge.py

暴露到互联网

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

设置 Telegram Webhook

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

Bot 命令

命令 描述 行为
/status 检查状态 返回 tmux 会话运行状态
/clear 清除对话 向 Claude Code 发送 /clear 命令
/stop 中断操作 发送 Escape 键中断当前操作
/resume 恢复会话 显示最近会话的内联键盘
/continue_ 继续最近会话 自动继续最近一次会话
/loop <prompt> Ralph Loop 使用提示词运行，最多 5 次迭代

环境变量

变量 默认值 描述
TELEGRAM_BOT_TOKEN 必需 BotFather 提供的 Bot Token
TMUX_SESSION claude tmux 会话名称
PORT 8091 Bridge Server 监听端口
SKIP_TUNNEL 未设置 设为 1 跳过 cloudflared 隧道
WEBHOOK_URL 未设置 手动指定 Webhook URL（配合 SKIP_TUNNEL=1 使用）

文件结构

.
├── bridge.py                           # Bridge Server
├── start-bridge.sh                     # 一键启动脚本
├── stop-clean-bridge.sh                # 停止和清理脚本
├── hooks/
│   └── send-to-telegram.sh             # Claude Code Stop Hook 脚本
├── pyproject.toml                      # Python 项目配置
├── README.md                           # 英文文档
└── README-cn.md                        # 本文档

运行时文件

文件 路径 描述
设置文件 ~/.claude/settings.json Claude Code 设置，定义 Stop Hook
Hook 脚本 ~/.claude/hooks/send-to-telegram.sh 响应发送脚本
Chat ID ~/.claude/telegram_chat_id 当前 Telegram 聊天 ID
Pending 标记 ~/.claude/telegram_pending 待处理消息时间戳
历史记录 ~/.claude/history.jsonl Claude 会话历史（用于 /resume）

Hook 配置说明

Claude Code 使用 ~/.claude/settings.json 配置 Hook：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/send-to-telegram.sh"
          }
        ]
      }
    ]
  }
}
  • hooks.Stop: 定义 Stop Hook，在 Claude Code 响应完成时触发
  • Hook 从 stdin 读取 transcript_path 来提取助手的响应
  • 响应从 Markdown 转换为 HTML 后发送到 Telegram

故障排除

检查 tmux 会话

# 列出会话
tmux ls

# 连接到会话
tmux attach -t claude

检查 Pending 文件状态

# 查看 pending 文件
cat ~/.claude/telegram_pending

# 手动清理（如果卡住）
rm ~/.claude/telegram_pending

端口冲突

如果端口 8091 已被占用，会看到：

Error: Port 8091 is already in use
Please specify a different port: export PORT=<port> (current default: 8091)

解决方案：通过环境变量指定其他端口：

PORT=9091 ./start-bridge.sh

或者查看并停止占用端口的进程：

lsof -i :8091
kill -9 <PID>

常见问题

问题 原因 解决方案
消息发送后无响应 tmux 会话不存在 运行 tmux new -s claude 启动会话
Hook 不触发 settings.json 未配置 检查 ~/.claude/settings.json 中的 Stop Hook
响应超时 Pending 文件过期（>10分钟） 检查系统时间，清理 pending 文件
HTML 格式错误 Markdown 转换失败 Hook 会自动回退到纯文本格式
Address already in use 端口 8091 被占用 使用 PORT=9091 ./start-bridge.sh

错误处理

Pending 文件超时

如果 pending 文件超过 10 分钟未处理，Stop Hook 会自动删除该文件并跳过响应发送。

Telegram API 错误

如果 HTML 格式发送失败，Hook 会自动回退到纯文本格式发送。

tmux 会话断开

如果 tmux 会话不存在，Bridge Server 会返回 "tmux not found" 错误消息到 Telegram。

License

MIT