# 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分钟） ```bash # 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 创建邮件配置文件 ```bash # 在项目根目录创建 .env 文件 touch .env ``` #### 2.2 编辑 .env 文件 将以下内容复制到 `.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**: ```env SMTP_HOST=smtp.gmail.com SMTP_PORT=587 IMAP_HOST=imap.gmail.com IMAP_PORT=993 ``` **Outlook/Hotmail**: ```env SMTP_HOST=smtp-mail.outlook.com SMTP_PORT=587 IMAP_HOST=outlook.office365.com IMAP_PORT=993 ``` **📌 重要：Gmail 用户必须使用应用密码** 1. 访问 [Google 账户设置](https://myaccount.google.com/security) 2. 启用两步验证 3. 生成应用密码 4. 在 `.env` 文件中使用应用密码，而不是账户密码 #### 2.4 测试邮件配置 ```bash # 测试邮件发送功能 node taskping.js test ``` 如果收到测试邮件，说明邮件配置成功！ ### ⚙️ 第三步：配置 Claude Code 钩子（5分钟） #### 3.1 找到 Claude Code 配置文件 ```bash # Claude Code 配置文件位置 ~/.claude/settings.json ``` #### 3.2 编辑配置文件 将以下内容添加到 `~/.claude/settings.json`： ```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 启动邮件监听服务 ```bash # 在项目目录启动邮件监听 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 会话 在新的终端窗口中： ```bash # 创建一个新的 Claude Code 会话 tmux new-session -d -s my-project tmux attach -t my-project # 在 tmux 会话中启动 Claude Code claude ``` #### 4.3 开始远程控制 1. **与 Claude 对话**： ``` > 请帮我分析这个项目的结构 ``` 2. **接收邮件通知**： Claude 完成任务后，你会收到邮件，内容类似： ``` Subject: TaskPing 任务完成通知 [#ABC123] Claude has completed your task: "请帮我分析这个项目的结构" [Claude的完整回复内容...] Reply to this email to send new commands. Token: ABC123 ``` 3. **回复邮件控制**： 直接回复邮件： ``` 请继续优化代码性能 ``` 4. **命令自动执行**： 你的回复会自动注入到 Claude Code 中并执行！ ## 🎯 高级使用技巧 ### 📝 多行命令支持 你可以在邮件回复中使用复杂的多行命令： ``` 请按以下步骤进行： 1. 分析当前代码结构 2. 识别性能瓶颈 3. 提供具体的优化建议 详细要求： - 重点关注数据库查询优化 - 检查内存使用情况 - 提供代码示例 谢谢！ ``` ### 🔄 多项目管理 ```bash # 项目 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，你可以同时控制多个项目！ ### 📊 监控和管理 ```bash # 查看系统状态 node taskping.js status # 查看待处理命令 node taskping.js commands list # 查看活跃会话 tmux list-sessions # 清理命令队列 node taskping.js commands clear ``` ## 🎬 使用场景示例 ### 场景1：代码审查自动化 1. 在办公室启动代码审查任务 2. 回家路上收到完成邮件："发现3个问题" 3. 回复邮件："请修复第一个问题" 4. Claude 自动开始修复 5. 通过邮件持续跟进进度 ### 场景2：长时间项目监控 1. 启动大型重构任务 2. Claude 分模块完成工作 3. 每个阶段完成时收到邮件通知 4. 通过邮件回复指导下一步工作 ### 场景3：多地协作开发 1. 在不同地点都能通过邮件控制同一个 Claude Code 实例 2. 无需 VPN 或复杂的远程桌面设置 3. 只需要邮箱就能远程编程 ## 🔧 系统管理命令 ```bash # 邮件监听服务 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 失败** ```bash # 检查 Node.js 版本 node -v # 需要 14+ # 清理并重新安装 rm -rf node_modules package-lock.json npm install ``` **Q: 邮件发送失败** ```bash # 检查邮件配置 node taskping.js status node taskping.js test # 常见问题： # 1. Gmail 用户必须使用应用密码 # 2. 检查 SMTP/IMAP 端口和安全设置 # 3. 确认网络可以访问邮件服务器 ``` **Q: 命令注入失败** ```bash # 检查 tmux 会话 tmux list-sessions # 检查会话内容 tmux capture-pane -t session-name -p # 检查允许的发件人 grep ALLOWED_SENDERS .env ``` **Q: Claude hooks 不触发** ```bash # 验证 hooks 配置 cat ~/.claude/settings.json # 手动测试 hook node taskping.js notify --type completed # 检查文件路径是否正确 ``` **Q: 收不到邮件通知** ```bash # 检查 SMTP 配置 node taskping.js test # 检查垃圾邮件文件夹 # 确认邮件地址配置正确 ``` ### 🐛 调试模式 ```bash # 启用详细日志 LOG_LEVEL=debug npm run relay:pty # 查看会话映射 cat src/data/session-map.json # 查看处理过的邮件 cat src/data/processed-messages.json ``` ## 🛡️ 安全说明 - ✅ **白名单机制** - 只有 `ALLOWED_SENDERS` 中的邮箱可以发送命令 - ✅ **会话隔离** - 每个 Token 只能控制对应的会话 - ✅ **命令验证** - 自动过滤危险命令 - ✅ **超时机制** - 会话有过期时间，自动清理 ## 🤝 贡献和支持 ### 报告问题 如果遇到问题，请在 [GitHub Issues](https://github.com/JessyTsui/Claude-Code-Remote/issues) 中报告。 ### 功能请求 欢迎提交新功能建议和改进意见。 ### 贡献代码 1. Fork 项目 2. 创建功能分支 3. 提交更改 4. 发起 Pull Request ## 📄 许可证 本项目采用 MIT 许可证。 --- **🚀 让 Claude Code 无处不在，随时随地智能编程！** 如果这个项目对你有帮助，请给我们一个 ⭐ Star！