头像

白日梦与诗

林深时见鹿，海蓝深见鲸

Claude Code 远程操作完整指南 - 邮件 + Telegram 双通道通知系统

17分钟阅读

Claude Code 远程操作完整指南

让 Claude Code 在家里运行，通过邮件和 Telegram 随时控制，任务完成自动通知你

📋 目录

一、为什么需要远程操作？

典型场景

场景 1：长任务执行

晚上睡觉前：发命令给 Claude Code "生成今天的日报"
早上醒来：收到邮件 "日报已生成"

场景 2：外出时继续工作

在外面时：收到 Telegram 通知 "代码重构完成"
回复邮件：发送新命令 "运行测试并修复错误"
回家时：所有工作已完成

场景 3：多任务并行

同时运行多个 Claude Code 会话
每个完成时都会通知你
不用一直盯着屏幕

核心价值

  • ⏰ 解放时间 - 不需要一直等待 Claude 完成任务
  • 📱 随时掌控 - 手机收通知，立即知道进度
  • 🔄 持续工作 - 外出时 AI 依然在帮你工作
  • 💡 提高效率 - 异步工作，充分利用时间

二、方案对比

官方 vs 社区方案

方案Claude Code on the Web (官方)Claude Code Remote (社区)Happy (社区)
执行位置Anthropic 云端你的电脑你的电脑
数据隐私⚠️ 代码上传云端✅ 本地执行✅ 本地执行
通知方式网页📧 邮件 + 📱 Telegram📱 移动 App
回复命令❌ 无✅ 邮件回复✅ App 聊天
费用需要 Pro/Max免费开源免费开源
网络要求需要联网需要联网 + 公网 IP (邮件除外)需要联网
移动端❌ 仅网页📱 Telegram📱 专用 App
适用场景云端执行，无需本地环境异步任务通知实时移动控制

推荐方案

Claude Code Remote 最适合：

  • ✅ 需要任务完成通知
  • ✅ 不想把代码上传云端
  • ✅ 主要需求是异步工作流
  • ✅ 习惯用邮件/Telegram

三、Claude Code Remote 介绍

项目信息

核心功能

1. 多渠道通知

Claude 完成任务
    ↓
自动触发钩子
    ↓
📧 邮件通知
📱 Telegram 通知
🖥️ 桌面通知

2. 远程命令控制

收到通知邮件
    ↓
直接回复邮件发送命令
    ↓
命令注入到 tmux 里的 Claude Code
    ↓
Claude 执行新任务

3. 安全机制

  • ✅ 白名单验证（只有授权用户可以控制）
  • ✅ 令牌验证（24小时有效期）
  • ✅ 发件人地址验证
  • ✅ Chat ID 验证（Telegram）

四、完整安装配置

前置要求

  • macOS / Linux
  • Node.js >= 14.0.0
  • 邮箱账号（QQ/Gmail/163 等）
  • Telegram 账号（可选）
  • tmux（自动安装）

步骤 1：安装项目

# 克隆项目
cd ~/你的工作目录
git clone https://github.com/JessyTsui/Claude-Code-Remote.git
cd Claude-Code-Remote
 
# 安装依赖
npm install
 
# 复制配置文件
cp .env.example .env

步骤 2：配置邮箱

2.1 QQ 邮箱配置

获取授权码：

  1. 登录 QQ 邮箱网页版：https://mail.qq.com
  2. 设置 → 账户 → POP3/IMAP/SMTP 服务
  3. 开启 IMAP/SMTP服务
  4. 点击 生成授权码，发送短信验证
  5. 保存 16 位授权码（如：abcdEFGH12345678）

2.2 Gmail 配置

获取应用密码：

  1. 启用两步验证：https://myaccount.google.com/security
  2. 生成应用密码：https://myaccount.google.com/apppasswords
  3. 选择”邮件”和”其他设备”
  4. 保存 16 位密码

2.3 编辑 .env 文件

# 邮件配置
EMAIL_ENABLED=true
 
# SMTP 发送配置（QQ 邮箱）
SMTP_HOST=smtp.qq.com
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=your-email@qq.com
SMTP_PASS=your-16-digit-auth-code
 
# IMAP 接收配置
IMAP_HOST=imap.qq.com
IMAP_PORT=993
IMAP_SECURE=true
IMAP_USER=your-email@qq.com
IMAP_PASS=your-16-digit-auth-code
 
# 接收通知的邮箱
EMAIL_TO=your-email@qq.com
 
# 白名单（只有这些邮箱可以发送命令）
ALLOWED_SENDERS=your-email@qq.com

Gmail 配置：

SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
IMAP_HOST=imap.gmail.com
IMAP_PORT=993

163 邮箱配置：

SMTP_HOST=smtp.163.com
SMTP_PORT=465
IMAP_HOST=imap.163.com
IMAP_PORT=993

步骤 3：配置 Telegram（可选）

3.1 创建 Telegram Bot

与 @BotFather 对话：

  1. 打开 Telegram，搜索 @BotFather

  2. 发送命令：/newbot

  3. 输入 Bot 名称（如：我的 Claude Code 助手）

  4. 输入 Bot 用户名（如：my_claude_code_bot）

    • 必须以 bot 结尾
    • 只能包含字母、数字、下划线

  5. 保存 Bot Token（如：1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-1234567）

3.2 获取 Chat ID

  1. 给刚创建的 Bot 发送一条消息（随便什么都行）
  2. 浏览器打开（替换 Token）：
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
  1. 找到 JSON 中的 "chat":{"id":123456789} - 这就是你的 Chat ID

3.3 编辑配置文件

.env 文件：

TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-1234567
TELEGRAM_CHAT_ID=123456789
TELEGRAM_WHITELIST=123456789
TELEGRAM_FORCE_IPV4=true  # 国内网络建议开启

config/channels.json 文件：

{
  "telegram": {
    "type": "chat",
    "enabled": true,
    "config": {
      "botToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-1234567",
      "chatId": "123456789",
      "groupId": "",
      "whitelist": ["123456789"],
      "forceIPv4": true
    }
  }
}

步骤 4：配置 Claude Code 钩子

编辑 ~/.claude/settings.json：

{
  "alwaysThinkingEnabled": false,
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node /你的路径/Claude-Code-Remote/claude-hook-notify.js completed",
            "timeout": 10
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node /你的路径/Claude-Code-Remote/claude-hook-notify.js waiting",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

重要：将 /你的路径/ 替换为实际路径！

步骤 5：安装 tmux

# macOS
brew install tmux
 
# Ubuntu/Debian
sudo apt-get install tmux
 
# CentOS/RHEL
sudo yum install tmux

步骤 6：测试配置

6.1 测试邮件通知

cd Claude-Code-Remote
 
# 方法 1：使用 Node.js 脚本
node -e "
require('dotenv').config();
const nodemailer = require('nodemailer');
const transporter = nodemailer.createTransport({
    host: process.env.SMTP_HOST,
    port: parseInt(process.env.SMTP_PORT),
    secure: process.env.SMTP_SECURE === 'true',
    auth: {
        user: process.env.SMTP_USER,
        pass: process.env.SMTP_PASS
    }
});
transporter.sendMail({
    from: process.env.EMAIL_FROM,
    to: process.env.EMAIL_TO,
    subject: '🎉 Claude Code Remote 测试',
    text: '邮件配置成功！'
}).then(() => console.log('✅ 发送成功')).catch(err => console.error('❌ 失败:', err.message));
"

6.2 测试 Telegram 通知

node test-telegram-notification.js

预期结果：

  • ✅ Telegram 收到测试消息
  • ✅ 包含 Token 和命令格式说明

五、使用指南

基础使用流程

1. 启动 tmux 会话

# 创建名为 claude 的会话
tmux new-session -s claude
 
# 或者使用自定义名称
tmux new-session -s my-project

2. 在 tmux 里启动 Claude Code

claude

3. 启动邮件监听服务

新开一个终端窗口：

cd Claude-Code-Remote
npm run relay:start

或者在后台运行：

cd Claude-Code-Remote
nohup npm run relay:start > relay.log 2>&1 &

4. 使用 Claude Code

正常使用 Claude Code，当任务完成时：

  • 📱 Telegram 自动收到通知
  • 📧 邮箱自动收到通知

邮件回复命令

收到通知邮件

主题：[Claude-Code-Remote #ABC123] Claude Code Task Completed

内容：
📝 Your Question: 生成今天的日报
🤖 Claude's Response: 日报已生成

How to Continue:
Reply to this email with your new command.

直接回复邮件

生成今天的博客文章大纲

系统会自动：

  1. 验证发件人（白名单）
  2. 提取命令
  3. 注入到 tmux 里的 Claude Code
  4. Claude 执行命令

命令注入过程

你回复邮件
    ↓
邮件监听服务检测到新邮件（每 20 秒检查一次）
    ↓
验证发件人在白名单 ✅
    ↓
通过 tmux 注入命令到 Claude Code 会话
    ↓
Claude 开始执行
    ↓
完成后再次发送通知

Telegram 通知（仅接收）

当前配置：

  • ✅ 接收通知 - 任务完成时收到消息
  • ❌ 回复命令 - 需要公网 HTTPS URL（暂不支持）

如果需要 Telegram 回复功能：
需要使用内网穿透工具（如 ngrok、frp）提供公网 URL。

实用技巧

多会话管理

# 创建多个 tmux 会话
tmux new-session -s project1
tmux new-session -s project2
 
# 切换会话
tmux switch -t project1
 
# 查看所有会话
tmux list-sessions
 
# 分离当前会话（后台运行）
Ctrl + B, 然后按 D
 
# 重新连接会话
tmux attach -t project1

批量任务

邮件 1：

分析项目架构并生成文档

收到通知后，邮件 2：

根据文档生成单元测试

收到通知后，邮件 3：

运行所有测试并修复失败的测试

定时任务

结合 cron 实现定时发送邮件：

# 每天早上 9 点生成日报
0 9 * * * echo "生成昨天的日报" | mail -s "Claude Task" your-email@qq.com

六、常见问题

Q1：邮件回复没反应？

检查清单：

  1. 邮件监听服务是否运行
ps aux | grep relay-pty

  1. 发件人是否在白名单
    检查 .env 的 ALLOWED_SENDERS

  2. Claude Code 是否在 tmux 里运行

tmux list-sessions
  1. 查看日志
# 邮件监听服务日志
tail -f relay.log
 
# 或者前台运行查看实时日志
npm run relay:start

Q2：Telegram 收不到通知？

检查步骤：

  1. Bot Token 正确
curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe
  1. Chat ID 正确
    给 Bot 发消息后访问：
https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

  1. config/channels.json 已配置
    确保 Telegram 配置存在且 enabled: true

  2. 测试发送

node test-telegram-notification.js

Q3：权限被拒绝？

AppleScript 权限（macOS）：

  1. 系统偏好设置 → 安全性与隐私 → 隐私
  2. 自动化 → 允许 Terminal/iTerm2 控制 System Events
  3. 辅助功能 → 添加 Terminal/iTerm2

Q4：邮件检查间隔太长？

修改 .env：

# 默认 20 秒检查一次
CHECK_INTERVAL=20
 
# 改为 10 秒
CHECK_INTERVAL=10

Q5：如何停止服务？

# 停止邮件监听
ps aux | grep relay-pty | grep -v grep | awk '{print $2}' | xargs kill
 
# 或者使用 pkill
pkill -f relay-pty
 
# 停止 tmux 会话
tmux kill-session -t claude

Q6：邮件通知太多怎么办？

设置邮件过滤规则：

Gmail：

  1. 搜索 from:(brmys@foxmail.com) subject:(Claude-Code-Remote)
  2. 创建过滤器 → 跳过收件箱，添加标签

QQ 邮箱：

  1. 设置 → 收信规则
  2. 发件人包含 → 自动归类

Q7：如何多台电脑使用？

  1. 在每台电脑上安装 Claude Code Remote
  2. 使用相同的 .env 配置
  3. 每台电脑使用不同的 tmux 会话名
  4. 邮件主题会包含机器名，可以区分

七、进阶技巧

7.1 自定义通知模板

编辑 config/email-template.json：

{
  "subject": "[自定义] 任务完成 - {project}",
  "body": "您的任务已完成\n命令：{command}\n结果：{result}"
}

7.2 集成其他工具

与 GitHub Actions 集成：

# .github/workflows/claude-notify.yml
name: Notify Claude Task
on:
  workflow_dispatch:
    inputs:
      command:
        description: 'Command for Claude'
        required: true
 
jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Send email
        uses: dawidd6/action-send-mail@v3
        with:
          server_address: smtp.qq.com
          server_port: 465
          username: ${{ secrets.EMAIL_USER }}
          password: ${{ secrets.EMAIL_PASS }}
          subject: Claude Task
          to: your-email@qq.com
          from: GitHub Actions
          body: ${{ github.event.inputs.command }}

7.3 语音输入 + Claude Code

结合闪电说等语音输入工具：

  1. 用语音录入命令
  2. 自动转文字
  3. 发送邮件给 Claude Code
  4. 完全解放双手

7.4 自动生成日报

cron 定时任务：

# 编辑 crontab
crontab -e
 
# 每天晚上 23:00 生成日报
0 23 * * * echo "生成今天的日报" | mail -s "Claude Daily Report" your-email@qq.com

结合 Obsidian + ATracker：

# Claude 自动读取时间记录生成日报
echo "根据 ATracker 数据生成今天的日报，包含时间分析和收获总结" | mail -s "Daily Report" your-email@qq.com

7.5 多人协作

团队使用：

  1. 共享 tmux 会话
# 创建共享会话
tmux -S /tmp/shared-claude new -s team
 
# 修改权限
chmod 777 /tmp/shared-claude
 
# 其他用户连接
tmux -S /tmp/shared-claude attach -t team
  1. 每个人使用自己的邮箱
  2. 在白名单中添加所有成员邮箱

7.6 安全加固

1. 使用专用邮箱：

不要用主邮箱，创建专门用于 Claude Code 的邮箱

2. 定期更换授权码：

# 每月更换一次邮箱授权码
# 更新 .env 文件

3. 限制命令权限：

# 在钩子脚本中添加命令白名单验证

4. 日志审计：

# 定期检查日志
tail -100 relay.log | grep "Command injected"

八、完整工作流示例

示例 1：Obsidian 日报自动化

早上出门前：

邮件主题：Daily Report
邮件内容：生成昨天的日报，包含时间记录、CFlow 卡片和人物互动记录

上班路上：

  • 📱 收到 Telegram 通知：“日报已生成”
  • 📧 收到邮件，包含完整的日报内容

看完日报后：

邮件回复：将昨天的三个重点收获发布到博客

中午休息：

  • 📱 收到通知：“博客文章已发布”

示例 2：代码重构

晚上睡觉前：

邮件：重构 user 模块，提取共用逻辑，优化性能

第二天早上：

  • 📱 收到通知：“重构完成”

查看结果后：

邮件回复：为重构的代码生成单元测试

中午：

  • 📱 收到通知：“测试已生成”

继续：

邮件回复：运行所有测试，修复失败的测试用例

示例 3：学习新技术

周末：

邮件 1：研究 React Server Components，写一份学习笔记
邮件 2：基于笔记创建一个实战项目
邮件 3：部署项目到 Vercel

每个任务完成都收到通知，周末结束时：

  • ✅ 技术笔记已完成
  • ✅ 实战项目已创建
  • ✅ 项目已部署上线

九、资源链接

官方资源

相关工具

邮箱服务商

十、总结

核心优势

  1. 异步工作流 - 让 AI 在后台工作，你做其他事情
  2. 多渠道通知 - 邮件 + Telegram，不会错过任何通知
  3. 邮件回复控制 - 最自然的交互方式
  4. 本地执行 - 代码不上传云端，隐私安全
  5. 完全免费 - 开源项目，无需付费

适用人群

  • ✅ 需要长任务异步执行的开发者
  • ✅ 希望充分利用碎片时间
  • ✅ 重视代码隐私和安全
  • ✅ 习惯用邮件管理工作流

不适合的场景

  • ❌ 需要实时交互的场景（建议用 Happy）
  • ❌ 需要频繁的短任务（直接用 Claude Code 更快）
  • ❌ 没有稳定的网络环境

附录：快速命令参考

# 安装
git clone https://github.com/JessyTsui/Claude-Code-Remote.git
cd Claude-Code-Remote && npm install
 
# 测试
node test-telegram-notification.js
node test-real-notification.js
 
# 启动服务
npm run relay:start
 
# 启动 tmux
tmux new-session -s claude
 
# 启动 Claude Code
claude
 
# 查看 tmux 会话
tmux list-sessions
 
# 连接会话
tmux attach -t claude
 
# 分离会话
Ctrl + B, D
 
# 停止服务
pkill -f relay-pty
 
# 查看日志
tail -f relay.log

创建时间：2025-11-24
作者：苏苏
版本：v1.0
项目 Star：844+

最后更新：2025-11-24

总结：Claude Code Remote 通过邮件和 Telegram 双通道通知，实现了”离开电脑，AI 继续工作”的理想工作流。配置一次，终身受益！🎉

关系图谱

1

反向链接