claudecode-telegram

claudecode-telegram 是一个轻量级桥接器，让你通过 Telegram 机器人远程与本地运行的 Claude Code 交互。所有推理在你的设备上完成，无需暴露 API 密钥，也无需依赖云端服务——只需一条消息，即可触发本地 Claude 的完整响应流程。

该方案特别适合希望在移动设备上使用 Claude Code、又不愿放弃本地运行隐私优势的用户。

工作原理

整个系统由三部分组成：

1. Telegram 机器人：接收用户消息，通过 webhook 发送给本地桥接器
2. Bridge 服务：运行在本地，监听 Telegram 请求，并通过 tmux send-keys 将消息注入 Claude Code 的终端会话
3. Claude Code + Stop 钩子：当 Claude 完成回复后，自动触发 send-to-telegram.sh 脚本，将转录文本发回 Telegram

⚠️ 仅响应由 Telegram 发起的消息（通过 pending 文件标记），避免循环或误触发。

安装与配置

第一步：安装依赖

# macOS（Linux 用户可替换为对应包管理器）
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 .

第二步：创建 Telegram 机器人

1. 在 Telegram 中搜索 @BotFather
2. 发送 /newbot，按提示创建机器人
3. 保存返回的 BOT_TOKEN

第三步：配置 Claude Code 钩子

# 复制钩子脚本
cp hooks/send-to-telegram.sh ~/.claude/hooks/

# 编辑脚本，填入你的 BOT_TOKEN
nano ~/.claude/hooks/send-to-telegram.sh
chmod +x ~/.claude/hooks/send-to-telegram.sh

在 ~/.claude/settings.json 中添加：

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

此配置确保 Claude 每次完成输出后，自动将结果推送回 Telegram。

第四步：启动 Claude Code（持久化）

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

使用 tmux 可让 Claude 在后台持续运行，即使断开 SSH 也不会中断。

第五步：启动桥接器

export TELEGRAM_BOT_TOKEN="your_bot_token_here"
python bridge.py

默认监听 http://localhost:8080。

第六步：通过 Cloudflare Tunnel 暴露服务

由于 Telegram 需要公网地址调用 webhook，使用 Cloudflare Tunnel 安全暴露本地服务：

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

记下返回的 https://xxxx.trycloudflare.com 地址。

第七步：设置 Telegram Webhook

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

成功后，所有发给机器人的消息将被转发到你的本地桥接器。

支持的机器人命令

环境变量

安全与隐私说明

• 所有 AI 推理在本地完成，不上传任何输入或输出到第三方
• Telegram 仅作为消息通道，内容不经过 Claude 官方服务器
• Cloudflare Tunnel 提供加密反向代理，无需开放防火墙端口
• 钩子机制确保只有你发起的请求才会触发响应

claudecode-telegram 不是一个“云代理”，而是一个本地智能体的远程遥控器。它让你在手机上也能安全、私密地使用完整的 Claude Code 功能。