Claude Code 远程

通过多个消息平台远程控制 Claude Code。您可以在本地启动任务，在 Claude 完成任务时接收通知，并只需回复消息即可发送新命令。

支持的平台：

• 📧 电子邮件 - 传统的 SMTP/IMAP 集成，附带执行轨迹
• 📱 Telegram - 带有智能按钮的交互式机器人 ✅ 新增
• 💬 LINE - 基于令牌的丰富消息指令
• 🖥️ 桌面 - 声音提醒和系统通知

🐦 关注 @Jiaxi_Cui，获取最新动态和 AI 开发见解

✨ 功能

• 📧 多种消息平台：
  • 电子邮件通知，附带完整执行轨迹及回复发送命令
  • Telegram 机器人，带有交互式按钮和斜杠命令
  • LINE 消息，支持基于令牌的命令
  • 桌面通知，附带声音提醒
• 🔄 双向控制：回复消息或邮件即可发送新命令
• 📱 远程访问：随时随地控制 Claude
• 🔒 安全性：所有平台均采用基于 ID 的白名单验证
• 👥 团队支持：可在 LINE 群组或 Telegram 群组中使用，便于团队协作
• 🤖 智能命令：各平台提供直观的命令格式
• 📋 多行支持：支持格式化的复杂命令
• ⚡ 智能监控：智能检测 Claude 的响应，并可进行历史追踪
• 🔄 tmux 集成：无缝将命令注入到正在运行的 tmux 会话中
• 📊 执行轨迹：电子邮件通知中完整捕获终端输出

📅 更改记录

2025 年 8 月

• 2025-08-02：在电子邮件通知中添加完整的执行轨迹（#14，由 @vaclisinc 提交）
• 2025-08-01：增强多渠道通知系统（#1，由 @laihenyi 和 @JessyTsui 提交）
  • ✅ Telegram 集成完成：交互式按钮、实时命令、智能处理个人与群聊
  • ✅ 多渠道通知：同时推送到桌面、Telegram、电子邮件和 LINE
  • ✅ 智能声音提醒：始终开启的音频反馈，支持自定义声音
  • ✅ 智能会话管理：自动检测、识别对话内容、24 小时有效期令牌
• 2025-08-01：修复 #9 和 #12：增加禁用子代理通知的配置（#10，由 @vaclisinc 提交）
• 2025-08-01：为电子邮件通知实现终端风格的 UI（#8，由 @vaclisinc 提交）
• 2025-08-01：修复工作目录问题——使 claude-remote 能够从任意目录运行（#7，由 @vaclisinc 提交）

2025 年 7 月

• 2025-07-31：修复使用同一邮箱作为收发邮箱时的自回复循环问题（#4，由 @vaclisinc 提交）
• 2025-07-28：移除硬编码值，实施基于环境变量的配置（#2，由 @kevinsslin 提交）

📋 待办事项清单

通知渠道

• 📱 Telegram 集成 ✅ 已完成：机器人集成，支持交互式按钮和实时命令
• 💬 Discord 集成：为消息平台集成机器人
• ⚡ Slack 工作流：原生 Slack 应用程序，支持斜杠命令

开发工具

• 🤖 AI 工具支持：与 Gemini CLI、Cursor 等其他 AI 开发工具集成
• 🔀 Git 自动化：自动提交功能、PR 创建、分支管理

使用分析

• 💰 成本跟踪：监控令牌使用情况并估算成本
• ⚡ 性能指标：跟踪执行时间并分析资源使用情况
• emailer 报告：每日/每周使用摘要通过电子邮件发送

原生应用

• 📱 移动应用：iOS 和 Android 应用程序，用于远程控制 Claude
• 🖥️ 桌面应用：macOS 和 Windows 原生客户端，支持系统集成

🚀 快速入门

1. 先决条件

系统要求：

• Node.js >= 14.0.0
• 对于默认 PTY 模式：无需 tmux（推荐直接在本地使用）
• 对于 tmux 模式：需要 tmux 和一个正在运行 Claude Code 的会话

2. 安装

git clone https://github.com/JessyTsui/Claude-Code-Remote.git
cd Claude-Code-Remote
npm install

3. 交互式设置（推荐）

npm run setup

• 引导式填写电子邮件、Telegram 和 LINE 的配置，生成 .env
• 自动将 Claude 钩子合并到 ~/.claude/settings.json
• 可随时重新运行以更新密钥或切换渠道
• 如需手动配置或离线编辑 .env 文件，请参阅下方“手动配置”

4. 手动配置（可选，如果已运行 npm run setup 则可跳过）

选项 A：配置电子邮件（推荐给初学者）

# 复制示例配置文件
cp .env.example .env

# 使用您的电子邮件凭据编辑
nano .env

必需的电子邮件设置：

EMAIL_ENABLED=true
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
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=/your/path/to/Claude-Code-Remote/src/data/session-map.json

📌 Gmail 用户：请使用应用专用密码，而非常规密码。

选项 B：配置 Telegram ✅ 新增

快速设置：

chmod +x setup-telegram.sh
./setup-telegram.sh

手动设置：

1. 通过 @BotFather 创建机器人
2. 从机器人 API 获取您的 Chat ID
3. 配置 Webhook URL（本地测试可使用 ngrok）

必需的 Telegram 设置：

TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=your-bot-token-here
TELEGRAM_CHAT_ID=your-chat-id-here
TELEGRAM_WEBHOOK_URL=https://your-ngrok-url.app
SESSION_MAP_PATH=/your/path/to/Claude-Code-Remote/src/data/session-map.json

可选的 Telegram 设置：

# 强制使用 IPv4 连接至 Telegram API（默认为假）

# 如果您遇到 IPv6 连接问题，请启用此项
TELEGRAM_FORCE_IPV4=true

网络配置说明：

• IPv4 与 IPv6：某些网络环境可能存在 Telegram API 服务器的 IPv6 连接不稳定的情况。
• 何时使用 TELEGRAM_FORCE_IPV4=true：
  • 发送消息时出现连接超时或失败；
  • Webhook 消息传递不一致；
  • 网络环境未正确支持 IPv6。
• 默认行为：使用系统默认设置（通常在可用时优先使用 IPv6，不可用时回退到 IPv4）。
• 性能影响：极小——仅影响初始连接建立。

选项 C：配置 LINE

必需的 LINE 设置：

LINE_ENABLED=true
LINE_CHANNEL_ACCESS_TOKEN=your-token
LINE_CHANNEL_SECRET=your-secret
LINE_USER_ID=your-user-id

配置 Claude Code Hooks（仅在跳过 npm run setup 时需要）

创建 hooks 配置文件：

方法 1：全局配置（推荐）

# 添加到 ~/.claude/settings.json
{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "node /your/path/to/Claude-Code-Remote/claude-hook-notify.js completed",
        "timeout": 5
      }]
    }],
    "SubagentStop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "node /your/path/to/Claude-Code-Remote/claude-hook-notify.js waiting",
        "timeout": 5
      }]
    }]
  }
}

方法 2：项目特定配置

# 设置环境变量
export CLAUDE_HOOKS_CONFIG=/your/path/to/Claude-Code-Remote/claude-hooks.json

注意：子代理通知默认是关闭的。如需启用，请在配置中设置 enableSubagentNotifications: true。详情请参阅 子代理通知指南。

5. 启动 Claude（按你的注入模式选择）

• 默认 PTY 模式（无需 tmux）：直接在终端运行 claude-code --config /path/to/your/claude/settings.json
• 如果你选择 tmux 模式：

  tmux new-session -d -s claude-session
  tmux attach-session -t claude-session
  claude-code --config /path/to/your/claude/settings.json
  

  分离会话：Ctrl+B 然后 D

注意：交互式设置已将 hooks 合并到 ~/.claude/settings.json。若跳过，请确保手动配置 hooks。

6. 启动服务

对所有平台（推荐）

# 自动启动所有已启用的平台
npm run webhooks
# 或
node start-all-webhooks.js

对于单个平台

对于电子邮件：

npm run daemon:start
# 或
node claude-remote.js daemon start

对于 Telegram：

npm run telegram
# 或
node start-telegram-webhook.js

对于 LINE：

npm run line
# 或
node start-line-webhook.js

7. 测试您的设置

快速测试：

# 测试所有通知渠道
node claude-hook-notify.js completed
# 应该通过所有已启用的平台收到通知

完整测试：

1. 在启用了 hooks 的 tmux 会话中启动 Claude；
2. 在 Claude 中执行任意命令；
3. 检查通知（电子邮件/Telegram/LINE）；
4. 回复新命令以测试双向控制。

🎮 工作原理

1. 在 tmux 会话中正常使用 Claude；
2. 当 Claude 完成任务时接收通知，方式包括：
   • 🔊 桌面声音提醒；
   • 📧 带有执行轨迹的电子邮件通知（如果启用）；
   • 📱 带有按钮的 Telegram 消息（如果启用）；
   • 💬 LINE 消息（如果启用）；
3. 使用任意平台回复命令；
4. 命令会在 Claude 中自动执行。

各平台的命令格式

电子邮件：

只需回复通知邮件即可发送命令
无需特殊格式

Telegram： ✅ NEW

点击智能按钮获取格式：
📝 个人聊天：/cmd TOKEN123 您的命令在这里
👥 群组聊天：@bot_name /cmd TOKEN123 您的命令在这里

LINE：

回复通知内容：您的命令在这里
（令牌会自动从对话上下文中提取）

本地回退（无 tmux）

• 默认 INJECTION_MODE=pty：命令通过 PTY/智能粘贴注入，不依赖 tmux
• macOS 可自动复制/粘贴到 Claude/终端；若自动注入失败，会把命令复制到剪贴板并弹出提醒

高级配置

电子邮件通知选项

1. 电子邮件中的子代理活动

   默认情况下，电子邮件通知仅显示执行轨迹。您可以选择启用单独的子代理活动摘要部分：

   // 在您的 config/config.json 中
   {
     "showSubagentActivitiesInEmail": true  // 默认：false
   }
   

   启用后，电子邮件将包含：

   • 子代理活动摘要：所有子代理活动的结构化列表；
   • 完整的执行轨迹：完整的终端输出。

   由于执行轨迹已经包含了所有信息，此功能默认关闭，以保持邮件简洁。

2. 执行轨迹显示

   您可以控制是否在电子邮件通知中包含执行轨迹：

   // 在您的电子邮件通道配置中
   {
     "email": {
       "config": {
         "includeExecutionTrace": false  // 默认：true
       }
     }
   }
   

   • 当为 true（默认）时：电子邮件中会显示可滚动的执行轨迹部分；
   • 当为 false时：完全移除电子邮件中的执行轨迹部分。

   如果您觉得执行轨迹过于冗长，或者您的电子邮件客户端对可滚动内容有兼容性问题，此功能非常有用。

💡 使用场景

• 远程代码评审：在办公室开始评审，然后在家通过任何平台继续；
• 长时间运行的任务：远程监控进度并指导下一步操作；
• 多地点开发：无需 VPN 即可在任何地方控制 Claude；
• 团队协作：共享 Telegram 群组以进行团队通知；
• 移动开发：通过 Telegram 从手机发送命令。

🔧 命令

设置

npm run setup   # 交互式向导，用于创建 .env 文件并将 hooks 合并到 ~/.claude/settings.json

测试与诊断

# 测试所有通知渠道
node claude-hook-notify.js completed

# 测试特定平台
node test-telegram-notification.js
node test-real-notification.js
node test-injection.js

# 系统诊断
node claude-remote.js diagnose
node claude-remote.js status
node claude-remote.js test

服务管理

# 启动所有已启用的平台
npm run webhooks

# 单独的服务
npm run telegram         # Telegram webhook
npm run line            # LINE webhook  
npm run daemon:start    # Email daemon

# 停止服务
npm run daemon:stop     # 停止 email 守护进程

🔍 故障排除

常见问题

未收到来自 Claude 的通知？

1. 检查 tmux 会话中的 hooks 配置：

   echo $CLAUDE_HOOKS_CONFIG
   

2. 确认 Claude 正在运行且启用了 hooks；
3. 手动测试通知：

   node claude-hook-notify.js completed
   

Telegram 机器人没有响应？ ✅ NEW

# 测试机器人连通性
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \
  -H "Content-Type: application/json" \
  -d "{\"chat_id\": $TELEGRAM_CHAT_ID, \"text\": \"Test\"}"

# 检查 webhook 状态
curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo"

Claude 中命令未执行？

# 检查 tmux 会话是否存在
tmux list-sessions

# 验证注入模式
grep INJECTION_MODE .env  # 应为 'tmux'

# 测试注入
node test-injection.js

未收到邮件？

• 运行 node claude-remote.js test 来测试邮件设置
• 检查垃圾邮件文件夹
• 验证 .env 文件中的 SMTP 设置
• 对于 Gmail：确保使用应用专用密码

调试模式

# 启用详细日志记录
LOG_LEVEL=debug npm run webhooks
DEBUG=true node claude-hook-notify.js completed

🛡️ 安全性

多平台认证

• ✅ 邮箱: 通过 ALLOWED_SENDERS 环境变量进行发件人白名单管理
• ✅ Telegram: Bot Token 和 Chat ID 验证
• ✅ LINE: Channel Secret 和 Access Token 验证
• ✅ 会话令牌: 8 位字母数字组合的令牌用于命令验证

会话安全

• ✅ 会话隔离: 每个令牌仅控制其特定的 tmux 会话
• ✅ 自动过期: 会话在 24 小时后自动超时
• ✅ 基于令牌的命令: 所有平台均需有效的会话令牌
• ✅ 最小化数据存储: 会话文件仅包含必要信息

🤝 贡献

发现 bug 或有功能需求？

• 🐛 问题: GitHub Issues
• 🐦 更新: 关注 Twitter 上的 @Jiaxi_Cui
• 💬 讨论: 分享您的使用场景和改进建议

📄 许可证

MIT 许可证 - 欢迎自由使用和修改！

---

🚀 让 Claude 代码真正实现远程化，随时随地访问！

⭐ 星标历史

⭐ 如果这个项目帮助您更高效地编码，请给它点个星吧！

💡 提示: 启用多个通知渠道以增加冗余——再也不错过 Claude 的任何完成结果了！

Claude-Code-Remote 快速上手指南

环境准备

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

• Node.js: 版本 >= 14.0.0
• 运行模式选择:
  • 默认 PTY 模式（推荐）: 无需安装额外工具，适合本地直接运行。
  • tmux 模式: 需安装 tmux 并保持一个活跃会话（适用于远程服务器场景）。
• 网络环境: 若使用 Telegram 渠道且遇到连接超时，可能需要在配置中强制启用 IPv4。

安装步骤

1. 克隆项目与安装依赖

git clone https://github.com/JessyTsui/Claude-Code-Remote.git
cd Claude-Code-Remote
npm install

💡 国内加速提示: 若 npm install 速度较慢，可临时切换至国内镜像源： npm config set registry https://registry.npmmirror.com 然后重新运行 npm install。

2. 交互式配置（推荐）

运行以下命令启动向导，自动完成邮箱/Telegram/LINE 配置及 Claude Hooks 注入：

npm run setup

该脚本将：

• 引导填写各平台凭证，生成 .env 文件。
• 自动将通知钩子合并至 ~/.claude/settings.json。
• 支持随时重跑以更新密钥或切换通知渠道。

3. 手动配置（可选）

若跳过上述步骤，需手动编辑 .env 文件并配置 Hooks。

A. 配置环境变量 (.env) 复制示例文件并编辑：

cp .env.example .env
nano .env

• Email 配置示例:

  EMAIL_ENABLED=true
  SMTP_USER=your-email@gmail.com
  SMTP_PASS=your-app-password
  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=/your/path/to/Claude-Code-Remote/src/data/session-map.json
  

  📌 注意: Gmail 用户请使用 应用专用密码，而非登录密码。

• Telegram 配置示例:

  TELEGRAM_ENABLED=true
  TELEGRAM_BOT_TOKEN=your-bot-token-here
  TELEGRAM_CHAT_ID=your-chat-id-here
  TELEGRAM_WEBHOOK_URL=https://your-ngrok-url.app
  SESSION_MAP_PATH=/your/path/to/Claude-Code-Remote/src/data/session-map.json
  # 若遇网络连接问题，可开启此项
  TELEGRAM_FORCE_IPV4=true
  

B. 配置 Claude Hooks (若未运行 setup) 确保 ~/.claude/settings.json 包含以下内容（路径需替换为实际绝对路径）：

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

基本使用

1. 启动服务

根据需求选择启动方式：

• 启动所有已启用的平台（推荐）:

  npm run webhooks
  # 或
  node start-all-webhooks.js
  

• 仅启动特定平台:

  • Email: npm run daemon:start
  • Telegram: npm run telegram
  • LINE: npm run line

2. 运行 Claude

• PTY 模式: 直接在终端运行：

  claude-code --config /path/to/your/claude/settings.json
  

• tmux 模式:

  tmux new-session -d -s claude-session
  tmux attach-session -t claude-session
  claude-code --config /path/to/your/claude/settings.json
  

  (分离会话快捷键：Ctrl+B 然后 D)

3. 测试与交互

验证通知: 运行以下命令测试通知渠道是否通畅：

node claude-hook-notify.js completed

您应收到来自已启用平台（邮件/Telegram/LINE/桌面弹窗）的通知。

完整工作流:

1. 在 Claude 中执行任意代码任务。
2. 任务完成后，您将收到通知（含执行轨迹）。
3. 直接回复该消息即可发送新指令给 Claude：
   • Email: 直接回复邮件正文。
   • Telegram: 点击智能按钮或使用 /cmd <TOKEN> 你的指令。
   • LINE: 直接回复消息内容。
4. Claude 将自动接收并执行您的回复指令。