9.0 KiB

Raw Blame History

Claude Code Remote - 远程邮件控制系统

一个强大的 Claude Code 远程控制工具，让你可以通过邮件回复来远程操控 Claude Code，实现真正的无人值守智能编程助手。

🌟 核心功能

📧 智能邮件通知 - Claude 完成任务时自动发送邮件通知
🔄 邮件回复控制 - 回复邮件内容自动注入到 Claude Code 中执行
📱 完全远程操作 - 在任何地方通过邮件控制你的 Claude Code
🛡️ 安全可靠 - 白名单机制确保只有授权用户可以发送命令
📋 多行支持 - 支持复杂的多行命令和格式化内容

🚀 新手完整教程

📋 前置要求

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

✅ macOS (推荐) 或 Linux
✅ Node.js 14+
✅ Claude Code 已安装并可正常使用
✅ tmux 已安装 (brew install tmux)
✅ 邮箱账号 (Gmail、Outlook 或其他 SMTP/IMAP 支持的邮箱)

🎯 第一步：快速体验（5分钟）

# 1. 克隆项目
git clone https://github.com/JessyTsui/Claude-Code-Remote.git
cd Claude-Code-Remote

# 2. 安装依赖
npm install

# 3. 测试基本功能
node taskping.js --help
node taskping.js status
node taskping.js test

如果看到桌面通知弹出，说明基础功能正常！

📧 第二步：配置邮件（10分钟）

2.1 创建邮件配置文件

# 在项目根目录创建 .env 文件
touch .env

2.2 编辑 .env 文件

将以下内容复制到 .env 文件中，并替换为你的邮箱信息：

# ===== SMTP 发送邮件配置 =====
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

# ===== IMAP 接收邮件配置 =====  
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
IMAP_USER=your-email@gmail.com
IMAP_PASS=your-app-password

# ===== 邮件路由配置 =====
EMAIL_TO=your-notification-email@gmail.com
ALLOWED_SENDERS=your-notification-email@gmail.com

# ===== 系统配置 =====
SESSION_MAP_PATH=/Users/your-username/path/to/Claude-Code-Remote/src/data/session-map.json
INJECTION_MODE=pty
CLAUDE_CLI_PATH=claude
LOG_LEVEL=info

2.3 常见邮箱配置

Gmail:

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

Outlook/Hotmail:

SMTP_HOST=smtp-mail.outlook.com
SMTP_PORT=587
IMAP_HOST=outlook.office365.com
IMAP_PORT=993

📌 重要：Gmail 用户必须使用应用密码

访问 Google 账户设置
启用两步验证
生成应用密码
在 .env 文件中使用应用密码，而不是账户密码

2.4 测试邮件配置

# 测试邮件发送功能
node taskping.js test

如果收到测试邮件，说明邮件配置成功！

⚙️ 第三步：配置 Claude Code 钩子（5分钟）

3.1 找到 Claude Code 配置文件

# Claude Code 配置文件位置
~/.claude/settings.json

3.2 编辑配置文件

将以下内容添加到 ~/.claude/settings.json：

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "node /Users/your-username/path/to/Claude-Code-Remote/taskping.js notify --type completed",
        "timeout": 5
      }]
    }],
    "SubagentStop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "node /Users/your-username/path/to/Claude-Code-Remote/taskping.js notify --type waiting",
        "timeout": 5
      }]
    }]
  }
}

🔥 重要：替换路径

将 /Users/your-username/path/to/Claude-Code-Remote 替换为你的实际项目路径
可以用 pwd 命令获取当前目录的完整路径

🎮 第四步：开始使用（马上开始！）

4.1 启动邮件监听服务

# 在项目目录启动邮件监听
npm run relay:pty

你会看到类似输出：

🚀 Starting TaskPing PTY Relay service...
📧 IMAP server: imap.gmail.com
👤 Email account: your-email@gmail.com
🔒 Whitelist senders: your-email@gmail.com

4.2 创建 Claude Code 会话

在新的终端窗口中：

# 创建一个新的 Claude Code 会话
tmux new-session -d -s my-project
tmux attach -t my-project

# 在 tmux 会话中启动 Claude Code
claude

4.3 开始远程控制

与 Claude 对话：
```
> 请帮我分析这个项目的结构
```

接收邮件通知： Claude 完成任务后，你会收到邮件，内容类似：

Subject: TaskPing 任务完成通知 [#ABC123]

Claude has completed your task:
"请帮我分析这个项目的结构"

[Claude的完整回复内容...]

Reply to this email to send new commands.
Token: ABC123

回复邮件控制：直接回复邮件：
```
请继续优化代码性能
```
命令自动执行：你的回复会自动注入到 Claude Code 中并执行！

🎯 高级使用技巧

📝 多行命令支持

你可以在邮件回复中使用复杂的多行命令：

请按以下步骤进行：

1. 分析当前代码结构
2. 识别性能瓶颈
3. 提供具体的优化建议

详细要求：
- 重点关注数据库查询优化
- 检查内存使用情况
- 提供代码示例

谢谢！

🔄 多项目管理

# 项目 A
tmux new-session -d -s project-a
tmux send-keys -t project-a "cd /path/to/project-a && claude" Enter

# 项目 B  
tmux new-session -d -s project-b
tmux send-keys -t project-b "cd /path/to/project-b && claude" Enter

每个会话都会有独立的邮件 Token，你可以同时控制多个项目！

📊 监控和管理

# 查看系统状态
node taskping.js status

# 查看待处理命令
node taskping.js commands list

# 查看活跃会话
tmux list-sessions

# 清理命令队列
node taskping.js commands clear

🎬 使用场景示例

场景1：代码审查自动化

在办公室启动代码审查任务
回家路上收到完成邮件："发现3个问题"
回复邮件："请修复第一个问题"
Claude 自动开始修复
通过邮件持续跟进进度

场景2：长时间项目监控

启动大型重构任务
Claude 分模块完成工作
每个阶段完成时收到邮件通知
通过邮件回复指导下一步工作

场景3：多地协作开发

在不同地点都能通过邮件控制同一个 Claude Code 实例
无需 VPN 或复杂的远程桌面设置
只需要邮箱就能远程编程

🔧 系统管理命令

# 邮件监听服务
npm run relay:pty              # 启动邮件监听（前台运行）

# 系统状态检查
node taskping.js status        # 查看整体状态
node taskping.js test          # 测试所有功能

# 命令队列管理  
node taskping.js commands list    # 查看待处理命令
node taskping.js commands status  # 查看处理状态
node taskping.js commands clear   # 清空命令队列

# 会话管理
tmux list-sessions             # 查看所有会话
tmux attach -t session-name    # 连接到会话
tmux kill-session -t session-name  # 删除会话

🔍 故障排除

❓ 常见问题

Q: npm install 失败

# 检查 Node.js 版本
node -v  # 需要 14+

# 清理并重新安装
rm -rf node_modules package-lock.json
npm install

Q: 邮件发送失败

# 检查邮件配置
node taskping.js status
node taskping.js test

# 常见问题：
# 1. Gmail 用户必须使用应用密码
# 2. 检查 SMTP/IMAP 端口和安全设置
# 3. 确认网络可以访问邮件服务器

Q: 命令注入失败

# 检查 tmux 会话
tmux list-sessions

# 检查会话内容
tmux capture-pane -t session-name -p

# 检查允许的发件人
grep ALLOWED_SENDERS .env

Q: Claude hooks 不触发

# 验证 hooks 配置
cat ~/.claude/settings.json

# 手动测试 hook
node taskping.js notify --type completed

# 检查文件路径是否正确

Q: 收不到邮件通知

# 检查 SMTP 配置
node taskping.js test

# 检查垃圾邮件文件夹
# 确认邮件地址配置正确

🐛 调试模式

# 启用详细日志
LOG_LEVEL=debug npm run relay:pty

# 查看会话映射
cat src/data/session-map.json

# 查看处理过的邮件
cat src/data/processed-messages.json

🛡️ 安全说明

✅ 白名单机制 - 只有 ALLOWED_SENDERS 中的邮箱可以发送命令
✅ 会话隔离 - 每个 Token 只能控制对应的会话
✅ 命令验证 - 自动过滤危险命令
✅ 超时机制 - 会话有过期时间，自动清理

🤝 贡献和支持

报告问题

如果遇到问题，请在 GitHub Issues 中报告。

功能请求

欢迎提交新功能建议和改进意见。

贡献代码

Fork 项目
创建功能分支
提交更改
发起 Pull Request

📄 许可证

本项目采用 MIT 许可证。

🚀 让 Claude Code 无处不在，随时随地智能编程！

如果这个项目对你有帮助，请给我们一个 ⭐ Star！

9.0 KiB Raw Blame History Unescape Escape