Telegram 远程控制 Claude Code - 我的个人定制方案

在任何地方通过 Telegram 发送命令，控制家中 Mac 上运行的 Claude Code

🚀 快速启动清单

每次使用前，必须确保以下服务都在运行：

✅ 检查清单

#	服务	位置	检查命令	状态
1	NAS Docker 容器	绿联 NAS	`docker-compose ps`	必须 Running
2	Mac Webhook 服务	Mac 电脑	`curl http://192.168.10.18:3001/health`	必须返回 ok
3	tmux 会话	Mac 电脑	`tmux list-sessions`	必须有 `claude` 会话
4	Claude Code	Mac tmux 内	在 tmux 里运行	必须在 tmux 里启动
5	Cloudflare Worker	Cloudflare	`curl https://cc.brmys.cn/`	自动运行（无需管理）
6	Telegram Webhook	Telegram	自动配置	已配置好（无需管理）

📝 完整启动步骤

步骤 1：启动 NAS Docker 容器

SSH 连接到 NAS：

ssh 你的NAS用户@你的NAS地址
cd /volume1/docker/claude-telegram-webhook

启动容器：

docker-compose up -d

验证运行状态：

docker-compose ps
# 输出应显示: State = Up
 
docker-compose logs --tail=20
# 应看到: ✅ Webhook 服务已启动

如果容器没启动：

# 重启容器
docker-compose restart
 
# 查看错误日志
docker-compose logs

步骤 2：启动 Mac Webhook 服务

打开 iTerm2 或 Terminal，新建窗口：

cd ~/苏苏知识库/Claude-Code-Remote
node webhook-receiver.js

预期输出：

============================================================
🖥️  Mac Webhook Receiver
============================================================
Port: 3001
Allowed Chat ID: 894135050
Tmux Session: claude
============================================================

✅ Webhook 接收服务已启动
等待来自 NAS 的命令...

⚠️ 注意：

这个终端窗口不能关闭
如果关闭，远程命令将无法注入
可以最小化，但不要退出

后台运行方式（推荐）：

cd ~/苏苏知识库/Claude-Code-Remote
nohup node webhook-receiver.js > webhook.log 2>&1 &
 
# 查看是否启动成功
tail -f webhook.log
 
# 检查服务状态
curl http://192.168.10.18:3001/health

步骤 3：启动 tmux 会话并运行 Claude Code

新建或连接 tmux 会话：

# 如果是第一次使用，创建新会话
tmux new-session -s claude
 
# 如果会话已存在，连接到会话
tmux attach -t claude

在 tmux 里启动 Claude Code：

claude

⚠️ 重要：

Claude Code 必须在 tmux 里运行
不在 tmux 里，命令无法注入
不要直接在普通终端运行 claude

验证 tmux 状态：

打开新终端窗口执行：

tmux list-sessions
# 应该看到: claude: 1 windows (created ...) [attached]
 
curl http://192.168.10.18:3001/health
# 返回: {"status":"ok","tmuxStatus":"running",...}

步骤 4：测试整个系统

在 Telegram 给你的 Bot 发送：

/cmd TEST123 echo "Hello from Telegram"

预期流程：

Telegram Bot 收到消息
Cloudflare Worker 转发（自动）

NAS Docker 日志显示：

📨 收到 Telegram Webhook
🎫 Token: TEST123
📝 Command: echo "Hello from Telegram"
✅ Mac 已接收命令

Mac Webhook 日志显示：

📨 收到命令
Token: TEST123
Command: echo "Hello from Telegram"
✅ 命令已注入到 tmux 会话: claude

tmux 里的 Claude Code 自动输入命令并执行

Telegram 收到回复：

✅ 命令已发送到 Mac
📝 命令: echo "Hello from Telegram"
⏳ Claude 正在执行...

❌ 常见的”失效”情况

情况 1：关闭所有终端窗口

后果：

❌ Mac Webhook 服务停止
❌ tmux 会话可能还在（取决于如何关闭）
❌ Telegram 命令无法到达 Mac

解决：

# 检查 tmux 是否还在
tmux list-sessions
 
# 如果还在，重启 Webhook 服务
cd ~/苏苏知识库/Claude-Code-Remote
node webhook-receiver.js
 
# 如果 tmux 也没了，重新创建
tmux new-session -s claude
claude

情况 2：Mac 休眠或关机

后果：

❌ 所有服务停止
❌ Telegram 命令返回错误

解决：

必须保持 Mac 开机且不休眠
设置：系统偏好设置 → 节能 → 防止自动休眠

情况 3：NAS Docker 容器停止

后果：

❌ Cloudflare Worker 无法转发到 Mac
❌ Telegram 无响应

解决：

# SSH 到 NAS
ssh 你的NAS用户@你的NAS地址
cd /volume1/docker/claude-telegram-webhook
 
# 启动容器
docker-compose up -d
 
# 查看状态
docker-compose ps

情况 4：Claude Code 不在 tmux 里运行

后果：

✅ Telegram 命令能到达 Mac
❌ 命令无法注入到 Claude Code
❌ 命令丢失

解决：

# 停止普通终端里的 Claude Code（Ctrl + C）
 
# 启动 tmux
tmux new-session -s claude
 
# 在 tmux 里启动 Claude Code
claude

🔧 自动启动脚本（推荐）

为了简化启动流程，我创建了一键启动脚本。

Mac 端自动启动

创建文件 ~/start-claude-remote.sh：

#!/bin/bash
 
echo "🚀 启动 Claude Code Remote 服务..."
echo ""
 
# 进入项目目录
cd ~/苏苏知识库/Claude-Code-Remote || exit 1
 
# 1. 启动 Webhook 服务（后台）
echo "1️⃣ 启动 Mac Webhook 接收服务..."
pkill -f "node webhook-receiver.js" 2>/dev/null
nohup node webhook-receiver.js > webhook.log 2>&1 &
WEBHOOK_PID=$!
sleep 2
 
# 检查 Webhook 是否启动成功
if curl -s http://192.168.10.18:3001/health > /dev/null 2>&1; then
    echo "✅ Webhook 服务已启动 (PID: $WEBHOOK_PID)"
else
    echo "❌ Webhook 服务启动失败"
    exit 1
fi
 
echo ""
 
# 2. 检查 tmux 会话
echo "2️⃣ 检查 tmux 会话..."
if tmux has-session -t claude 2>/dev/null; then
    echo "✅ tmux 会话 'claude' 已存在"
    echo ""
    echo "💡 连接到 tmux 会话："
    echo "   tmux attach -t claude"
else
    echo "⚠️  tmux 会话不存在，正在创建..."
    tmux new-session -d -s claude
    echo "✅ tmux 会话已创建"
    echo ""
    echo "💡 连接到 tmux 并启动 Claude Code："
    echo "   tmux attach -t claude"
    echo "   claude"
fi
 
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "🎉 服务启动完成！"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "📋 后续步骤："
echo "1. 连接到 tmux: tmux attach -t claude"
echo "2. 启动 Claude Code: claude"
echo "3. 开始使用 Telegram 远程控制"
echo ""
echo "📊 查看 Webhook 日志:"
echo "   tail -f ~/苏苏知识库/Claude-Code-Remote/webhook.log"
echo ""

使用方式：

# 添加执行权限
chmod +x ~/start-claude-remote.sh
 
# 运行脚本
~/start-claude-remote.sh

NAS 端自动启动

NAS Docker 容器设置了 restart: unless-stopped，会自动启动。

如果需要手动启动：

ssh 你的NAS用户@你的NAS地址
cd /volume1/docker/claude-telegram-webhook
docker-compose up -d

🛑 完整停止脚本

创建文件 ~/stop-claude-remote.sh：

#!/bin/bash
 
echo "🛑 停止 Claude Code Remote 服务..."
echo ""
 
# 1. 停止 Mac Webhook 服务
echo "1️⃣ 停止 Mac Webhook 服务..."
pkill -f "node webhook-receiver.js"
if [ $? -eq 0 ]; then
    echo "✅ Webhook 服务已停止"
else
    echo "⚠️  Webhook 服务未运行"
fi
 
echo ""
 
# 2. 提示 tmux 会话
echo "2️⃣ tmux 会话状态:"
if tmux has-session -t claude 2>/dev/null; then
    echo "⚠️  tmux 会话 'claude' 仍在运行"
    echo ""
    echo "💡 如需停止 tmux 会话："
    echo "   tmux kill-session -t claude"
else
    echo "✅ 没有运行中的 tmux 会话"
fi
 
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "🎉 服务停止完成！"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

使用方式：

chmod +x ~/stop-claude-remote.sh
~/stop-claude-remote.sh

为什么需要这套方案？

痛点

Claude Code 是一个强大的 AI 编程助手，但它只能在终端运行。当我不在电脑前时：

❌ 无法知道任务是否完成
❌ 无法发送新的命令
❌ 任务完成后无法继续下一步

解决方案

通过 Telegram Bot 实现：

✅ 任务完成时自动收到通知
✅ 直接在 Telegram 回复发送新命令
✅ 命令自动注入到 Claude Code 执行
✅ 随时随地远程控制

我的环境配置

设备/服务	配置
Mac 电脑	192.168.10.18（运行 Claude Code）
绿联 NAS	Docker + Lucky 反向代理
网络环境	公网 IPv6
域名	cc.brmys.cn / cc.brmys.top（Cloudflare 托管）
Telegram Bot	@ClaudeCodeRemote_bot

系统架构

📱 Telegram Bot
     ↓ (HTTPS POST)
☁️  Cloudflare Worker (cc.brmys.cn)
     ↓ (解决端口限制：443 → 1234)
🔄 Lucky 反向代理 (cc.brmys.top:1234)
     ↓ (HTTPS → HTTP)
🐳 NAS Docker 容器 (localhost:3000)
     ↓ (LAN HTTP)
💻 Mac Webhook Receiver (192.168.10.18:3001)
     ↓ (tmux send-keys)
🖥️  Claude Code (tmux session: claude)

为什么需要这么多层？

Telegram 限制：Webhook 只支持端口 80, 88, 443, 8443
Lucky 限制：我的反向代理使用自定义端口 1234
Mac 限制：没有公网 IP，只能通过局域网访问
解决方案：Cloudflare Worker 作为公网入口，转发到 NAS，再转发到 Mac

文件结构

~/苏苏知识库/Claude-Code-Remote/
├── .env                          # 环境变量配置
├── webhook-receiver.js           # Mac 端 Webhook 接收服务
├── cloudflare-worker/
│   ├── telegram-forwarder.js     # Cloudflare Worker 转发脚本
│   └── README.md                 # Worker 部署指南
└── nas-deployment/
    ├── docker-compose.yml        # Docker 配置
    └── app/
        ├── index.js              # NAS Webhook 服务
        └── package.json          # 依赖配置

配置详解

1. Mac Webhook 接收服务

文件：webhook-receiver.js

功能：

监听 3001 端口，接收来自 NAS 的命令
验证 Chat ID（白名单）
通过 tmux send-keys 将命令注入到 Claude Code 会话

关键代码：

// 注入命令到 tmux
execSync(`tmux send-keys -t ${TMUX_SESSION} -l "${escapedCommand}"`, { stdio: 'ignore' });
execSync(`tmux send-keys -t ${TMUX_SESSION} Enter`, { stdio: 'ignore' });

启动命令：

cd ~/苏苏知识库/Claude-Code-Remote
node webhook-receiver.js

预期输出：

============================================================
🖥️  Mac Webhook Receiver
============================================================
Port: 3001
Allowed Chat ID: 894135050
Tmux Session: claude
============================================================

✅ Webhook 接收服务已启动
📡 监听地址: http://0.0.0.0:3001
🔗 局域网访问: http://192.168.10.18:3001

2. NAS Docker 容器

文件：nas-deployment/docker-compose.yml

version: '3.8'
 
services:
  claude-telegram-webhook:
    image: node:18-alpine
    container_name: claude-telegram-webhook
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./app:/app
    working_dir: /app
    command: sh -c "npm install && node index.js"
    environment:
      - NODE_ENV=production
      - TELEGRAM_BOT_TOKEN=你的Bot Token
      - TELEGRAM_CHAT_ID=你的Chat ID
      - MAC_IP=192.168.10.18
      - MAC_PORT=3001

功能：

接收来自 Cloudflare Worker 的 Telegram 消息
解析 /cmd TOKEN 命令 格式
转发命令到 Mac Webhook 服务
发送确认消息回 Telegram

部署命令（在 NAS 上执行）：

cd /volume1/docker/claude-telegram-webhook
docker-compose up -d
docker-compose logs -f

预期日志：

============================================================
🐳 NAS Telegram Webhook Service
============================================================
Port: 3000
Telegram Bot Token: ✅ 已配置
Allowed Chat ID: 894135050
Mac IP: 192.168.10.18:3001
============================================================

✅ Webhook 服务已启动
📡 监听端口: 3000
等待 Telegram 消息...

3. Lucky 反向代理

配置：

字段	值
名称	Claude Telegram Webhook
监听类型	HTTPS
监听端口	1234
域名	cc.brmys.top
路径	/webhook/telegram
目标地址	http://localhost:3000/webhook/telegram
SSL 证书	Let’s Encrypt 自动申请

测试：

curl -k https://cc.brmys.top:1234/health
# 返回：{"status":"ok",...}

4. Cloudflare Worker

文件：cloudflare-worker/telegram-forwarder.js

功能：

提供标准 443 端口入口（满足 Telegram 要求）
转发请求到 Lucky 反向代理（自定义端口）
处理错误，确保 Telegram 收到 200 响应

部署步骤：

登录 Cloudflare Dashboard
Workers & Pages → Create Worker
粘贴 telegram-forwarder.js 代码
设置环境变量：NAS_WEBHOOK_URL = https://cc.brmys.top:1234/webhook/telegram
绑定域名：cc.brmys.cn

测试：

# 浏览器访问（GET 请求会返回错误，这是正常的）
curl https://cc.brmys.cn/
# 返回：{"error":"Method not allowed","message":"Only POST requests are accepted"}

5. 设置 Telegram Webhook

# 设置 Webhook URL
curl -X POST "https://api.telegram.org/bot你的Token/setWebhook" \
  -d "url=https://cc.brmys.cn/"
 
# 验证设置
curl "https://api.telegram.org/bot你的Token/getWebhookInfo"

预期返回：

{
  "ok": true,
  "result": {
    "url": "https://cc.brmys.cn/",
    "has_custom_certificate": false,
    "pending_update_count": 0
  }
}

使用方式

日常使用流程

1. 启动所有服务

Mac 端：

# Terminal 1：启动 tmux 并运行 Claude Code
tmux new-session -s claude
claude
 
# Terminal 2：启动 Webhook 接收服务
cd ~/苏苏知识库/Claude-Code-Remote
node webhook-receiver.js

NAS 端：确保 Docker 容器运行中

docker-compose ps
# 状态应为 Up

2. 正常使用 Claude Code

在 tmux 里的 Claude Code 中执行任务，完成后会自动通过 Hook 发送 Telegram 通知。

3. 收到通知后远程回复

通知格式：

🎉 Claude Code Task Completed

📝 Your Question:
生成今天的日报

🤖 Claude's Response:
日报已生成，保存在 70 每日日报/...

━━━━━━━━━━━━━━━━
Token: ABC123XY
Reply with: /cmd ABC123XY <your command>

回复命令：

/cmd ABC123XY 将日报发布到博客

4. 命令自动执行

Telegram → Cloudflare → Lucky → NAS → Mac → Claude Code
                                          ↓
                                    命令自动输入并执行

命令格式

/cmd <TOKEN> <命令内容>

示例：

/cmd ABC123 生成今天的日报
/cmd XYZ789 运行所有测试
/cmd TEST01 将代码推送到 GitHub

注意：

TOKEN 可以是任意字符串（用于追踪会话）
命令内容会原样发送给 Claude Code
支持中文和特殊字符

故障排查

问题 1：Telegram 无响应

检查清单：

✅ Cloudflare Worker 运行正常
```
curl https://cc.brmys.cn/
```

✅ Lucky 反向代理正常

curl -k https://cc.brmys.top:1234/health

✅ NAS Docker 容器运行中

docker-compose ps
docker-compose logs -f

✅ Webhook URL 设置正确

curl "https://api.telegram.org/bot你的Token/getWebhookInfo"

问题 2：Mac 无法接收命令

检查清单：

✅ Webhook 服务运行中
```
curl http://192.168.10.18:3001/health
```

✅ Mac 和 NAS 在同一局域网

# 在 NAS 上测试
curl http://192.168.10.18:3001/health

✅ 防火墙允许 3001 端口

问题 3：命令没有回车执行

原因：tmux send-keys 的 Enter 键没有被正确发送

解决：检查 webhook-receiver.js 是否使用了正确的命令注入方式：

// 正确写法：分两步发送
execSync(`tmux send-keys -t ${TMUX_SESSION} -l "${escapedCommand}"`, { stdio: 'ignore' });
execSync(`tmux send-keys -t ${TMUX_SESSION} Enter`, { stdio: 'ignore' });

问题 4：Chat ID 验证失败

原因：Telegram Chat ID 不匹配

解决：

发送消息给 Bot
访问 https://api.telegram.org/bot你的Token/getUpdates
确认 Chat ID 与配置一致

快速命令参考

# ========== Mac 端 ==========
 
# 启动 tmux 会话
tmux new-session -s claude
 
# 连接已有会话
tmux attach -t claude
 
# 分离会话（后台运行）
Ctrl + B, D
 
# 查看会话
tmux list-sessions
 
# 启动 Webhook 服务
cd ~/苏苏知识库/Claude-Code-Remote
node webhook-receiver.js
 
# 后台运行 Webhook 服务
nohup node webhook-receiver.js > webhook.log 2>&1 &
 
# 测试健康检查
curl http://192.168.10.18:3001/health
 
# ========== NAS 端 ==========
 
# 启动容器
docker-compose up -d
 
# 查看日志
docker-compose logs -f
 
# 重启容器
docker-compose restart
 
# 停止容器
docker-compose down
 
# 测试 Mac 连接
curl http://localhost:3000/test-mac
 
# ========== Telegram API ==========
 
# 设置 Webhook
curl -X POST "https://api.telegram.org/bot你的Token/setWebhook" \
  -d "url=https://cc.brmys.cn/"
 
# 查看 Webhook 状态
curl "https://api.telegram.org/bot你的Token/getWebhookInfo"
 
# 删除 Webhook
curl -X POST "https://api.telegram.org/bot你的Token/deleteWebhook"

安全注意事项

Chat ID 白名单：只有配置的 Chat ID 可以发送命令
局域网隔离：Mac Webhook 服务只在局域网暴露
HTTPS 加密：Cloudflare 和 Lucky 都使用 HTTPS
Token 保密：Telegram Bot Token 存储在环境变量中

总结

核心优势

📱 移动端控制：Telegram 随时可用
🔒 安全可靠：多层验证 + 局域网隔离
🏠 本地执行：代码不离开家
⚡ 实时响应：命令秒达

适用场景

✅ 外出时继续远程工作
✅ 长任务执行后发送新命令
✅ 通勤路上处理简单任务
✅ 晚上睡觉前安排任务，早上查看结果

局限性

❌ 无法查看 Claude Code 的实时输出
❌ 需要保持所有服务运行
❌ 依赖网络连接

创建时间：2025-11-24
作者：苏苏
方案版本：v1.0

一句话总结：通过 Telegram → Cloudflare Worker → NAS Docker → Mac Webhook → tmux Claude Code 的链路，实现了随时随地通过手机控制家中电脑上的 AI 编程助手。🚀

白日梦与诗

探索

Telegram 远程控制 Claude Code - 我的个人定制方案

Telegram 远程控制 Claude Code - 我的个人定制方案

🚀 快速启动清单

✅ 检查清单

📝 完整启动步骤

步骤 1：启动 NAS Docker 容器

步骤 2：启动 Mac Webhook 服务

步骤 3：启动 tmux 会话并运行 Claude Code

步骤 4：测试整个系统

❌ 常见的”失效”情况

情况 1：关闭所有终端窗口

情况 2：Mac 休眠或关机

情况 3：NAS Docker 容器停止

情况 4：Claude Code 不在 tmux 里运行

🔧 自动启动脚本（推荐）

Mac 端自动启动

NAS 端自动启动

🛑 完整停止脚本

为什么需要这套方案？

痛点

解决方案

我的环境配置

系统架构

为什么需要这么多层？

文件结构

配置详解

1. Mac Webhook 接收服务

2. NAS Docker 容器

3. Lucky 反向代理

4. Cloudflare Worker

5. 设置 Telegram Webhook

使用方式

日常使用流程

1. 启动所有服务

2. 正常使用 Claude Code

3. 收到通知后远程回复

4. 命令自动执行

命令格式

故障排查

问题 1：Telegram 无响应

问题 2：Mac 无法接收命令

问题 3：命令没有回车执行

问题 4：Chat ID 验证失败

快速命令参考

安全注意事项

总结

核心优势

适用场景

局限性

关系图谱

目录

反向链接