Hermes Remote Device

一个 Agent，多台设备。通过 MCP 协议让 Hermes Agent 直接操作远程设备的文件系统、终端和 Git。

这是什么

让一个 Hermes Agent 同时操控多台电脑（Win、Mac、Linux），就像操作本地一样。

不是两个 Agent 互相对话（会丢上下文），而是一个 Agent 通过 MCP 协议直接操作远程设备。

与其他方案的区别

方案	原理	问题
两个 Agent 互相对话	A 输出一段文本 → 传给 B	上下文丢失、信息压缩
MQTT/Redis 消息队列	Agent 间发消息	需要额外基础设施，本质还是传话
本方案	一个 Agent + 远程 MCP 工具	零信息损失，无需额外组件

架构

┌──────────────────────────────────────────────────────┐
│              Hermes Agent (单一 Agent)                │
│                                                       │
│  用户: "帮我在 Mac 上跑测试，Win 上改代码"             │
│                                                       │
│  Agent 自主决策:                                       │
│    1. 调用 win:write_file() → 修改 Win 上的文件        │
│    2. 调用 mac:run_command("pytest") → Mac 上跑测试    │
│    3. 调用 win:git_push() → Win 上推送代码             │
│                                                       │
│  所有工具调用的结果都在同一个对话上下文里               │
└──────────────┬───────────────────┬────────────────────┘
               │                   │
        ┌──────▼──────┐     ┌──────▼──────┐
        │  Win MCP    │     │  Mac MCP    │
        │  Server     │     │  Server     │
        └──────┬──────┘     └──────┬──────┘
               │                   │
          Win 文件系统          Mac 文件系统
          Win 终端              Mac 终端
          Win Git               Mac Git

功能列表

工具	描述	示例
remote_list_files	列出远程目录	"看看 Mac 上 ~/projects 有什么"
remote_read_file	读取远程文件	"读一下 Mac 上的 config.yaml"
remote_write_file	写入远程文件	"在 Mac 上创建一个 test.py"
remote_run_command	执行远程命令	"在 Win 上跑 pytest"
remote_git_status	Git 状态	"看看 Mac 上的 git 状态"
remote_git_diff	Git diff	"Mac 上改了什么"
remote_git_log	Git 日志	"Mac 最近的 commit 记录"
remote_git_commit	Git commit	"在 Mac 上提交代码"
remote_git_pull	Git pull	"Mac 上拉取最新代码"
remote_git_push	Git push	"Mac 上推送代码"
remote_system_info	系统信息	"Mac 的磁盘空间和 CPU"

快速开始

前提条件

• 两台（或以上）设备都安装了 Hermes Agent
• 两台设备都安装了 Tailscale 并登录同一账号
• Python 3.8+

第 1 步：两台设备都安装 Tailscale

# Linux (WSL)
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# Mac
# 去 https://tailscale.com/download/mac 下载安装
# 安装后登录同一账号

验证两台设备互通：

# 设备 A 上 ping 设备 B
tailscale ping <设备B的IP>

# 查看本机 Tailscale IP
tailscale ip -4
# 输出类似 100.x.x.x

第 2 步：部署 MCP Server

在每台设备上执行：

# 克隆仓库
git clone https://github.com/beibei030/hermes-remote-device-mcp.git
cd hermes-remote-device-mcp/remote-device-mcp

# 一键部署（自动检测 Python 环境、安装依赖、创建目录）
bash setup-device.sh --name <设备名> --port 9100 --whitelist ~/

# 例如：
# bash setup-device.sh --name win --port 9100 --whitelist ~/projects
# bash setup-device.sh --name mac --port 9100 --whitelist ~/projects

setup-device.sh 会自动：

1. 检测 Hermes venv Python（如果系统 Python 太老会自动切换）
2. 安装 mcp Python 包
3. 创建 ~/.hermes-coordinator/ 目录
4. 复制 server.py 到部署目录
5. 显示启动命令

第 3 步：启动 MCP Server

# 手动启动
~/.hermes/hermes-agent/venv/bin/python3 ~/.hermes-coordinator/server.py --host 0.0.0.0 --port 9100

# 后台启动
nohup ~/.hermes/hermes-agent/venv/bin/python3 ~/.hermes-coordinator/server.py \
  --host 0.0.0.0 --port 9100 > ~/.hermes-coordinator/logs/server.log 2>&1 &

⚠️ 必须用 --host 0.0.0.0，否则只监听 localhost，远程设备无法连接。

第 4 步：配置 Hermes

在每台设备的 ~/.hermes/config.yaml 里添加其他设备的 MCP Server：

mcp_servers:
  mac-device:
    url: "http://<Mac的Tailscale IP>:9100/mcp"
    timeout: 180

  win-device:
    url: "http://<Win的Tailscale IP>:9100/mcp"
    timeout: 180

例如：

# Win 上的 config.yaml（添加 Mac）
mcp_servers:
  mac-device:
    url: "http://100.96.132.111:9100/mcp"
    timeout: 180

# Mac 上的 config.yaml（添加 Win）
mcp_servers:
  win-device:
    url: "http://100.76.86.40:9100/mcp"
    timeout: 180

第 5 步：重启 Hermes Gateway

hermes gateway stop
hermes gateway start

第 6 步：验证

在任一设备的 Hermes 对话中：

"用 mac-device 的 remote_system_info 看看 Mac 的系统信息"
"用 win-device 的 remote_list_files 列出 Win 的 ~/projects 目录"

开机自启

Linux / WSL

# 克隆仓库后，部署脚本会生成自启脚本
# 添加到 crontab
(crontab -l 2>/dev/null; echo "@reboot $HOME/hermes-coordinator/start-mcp-server.sh") | crontab -

macOS

# 部署脚本会生成 plist 文件
# 复制到 launchd 目录
cp ~/hermes-coordinator/com.hermes.mcp-server.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.hermes.mcp-server.plist

高级功能

目录白名单

限制 MCP Server 只能访问指定目录：

python3 server.py --host 0.0.0.0 --port 9100 --whitelist ~/projects,~/code

不设置则允许访问所有目录。

HMAC 认证

防止未授权访问（两台设备必须使用相同的密钥）：

# 设备 A
python3 server.py --host 0.0.0.0 --port 9100 --secret my-secret-key

# 设备 B 的 Hermes config.yaml
mcp_servers:
  device-a:
    url: "http://100.x.x.x:9100/mcp"
    timeout: 180
    headers:
      X-MCP-Auth: "my-secret-key"

自定义端口

每台设备可以用不同端口：

python3 server.py --host 0.0.0.0 --port 9200

双 Agent 协作模式

除了日常使用（你跟一个 Hermes 对话，它操控多台设备），还支持无人值守的自动协作：

两个 Hermes Agent 各自独立运行，通过 GitHub 同步对话历史和代码，自动轮流执行任务。

设置

# 1. 在 GitHub 创建一个协作仓库（私有即可）

# 2. 两台设备都克隆工作区
git clone [email protected]:<your-github-username>/<collab-repo>.git ~/collab-workspace

# 3. 两台同时启动 Worker
# Win 终端：
cd ~/hermes-coordinator
python3 collab-worker.py --name Win --task "你的任务描述"

# Mac 终端：
cd hermes-remote-device-mcp
python3 collab-worker.py --name Mac --task "你的任务描述"

Worker 会自动轮流执行：Win 写代码 → push → Mac 拉取并审查 → push → Win 拉取修改 → 循环直到完成。

协作原理

┌──────────────┐         GitHub          ┌──────────────┐
│  Win Worker  │◄────────────────────────►│  Mac Worker  │
│              │   push/pull 代码和历史    │              │
│  hermes -q   │                          │  hermes -q   │
│  (完整上下文) │                          │  (完整上下文) │
└──────────────┘                          └──────────────┘

• 每轮执行时，Worker 读取完整的历史记录（history.jsonl）
• 把历史注入 hermes -q 的 prompt，让 Agent 看到之前的所有工作
• Agent 完成后，Worker 把本轮的完整输出追加到历史
• 通过 Git 同步到 GitHub，另一台设备自动拉取

使用示例

部署完成后，你可以直接在 Hermes 对话中这样用：

跨设备文件操作

"看看 Mac 上 ~/projects 里有什么项目"
"把 Win 上 ~/code/app.py 的内容读出来"
"在 Mac 上创建 ~/projects/new-project/main.py"

跨设备执行命令

"在 Mac 上跑一下 pytest"
"看看 Win 的磁盘空间"
"在两台设备上都执行 git pull"

跨设备代码协作

"在 Win 上改完代码后，帮我在 Mac 上跑测试"
"Mac 上那个项目的测试结果怎么样"
"把 Win 上的配置文件复制到 Mac 的同名位置"

Git 操作

"看看 Mac 上最近的 git 提交记录"
"Mac 上有什么未提交的改动"
"帮我在 Mac 上提交并推送代码"

项目结构

hermes-remote-device-mcp/
├── README.md                           # 本文件（完整文档）
├── remote-device-mcp/                  # MCP Server 核心
│   ├── server.py                       # MCP Server 主程序
│   ├── setup-device.sh                 # 一键部署脚本
│   └── .gitignore
├── collab-worker.py                    # 双 Agent 协作 Worker
├── collab-setup.sh                     # 协作初始化脚本
├── start-mcp-server.sh                 # Linux 开机自启脚本
├── com.hermes.mcp-server.plist         # macOS 开机自启配置
└── .gitignore

FAQ

Q: 两台设备不在同一局域网怎么办？

安装 Tailscale，免费，自动穿透 NAT。两台设备登录同一账号后获得 100.x.x.x 的虚拟 IP，可以直接互通。

Q: Mac 上 pip3 install mcp 报错 "No matching distribution"？

Mac 系统自带的 Python 太老。使用 Hermes 的 venv Python：

~/.hermes/hermes-agent/venv/bin/python3 server.py --host 0.0.0.0 --port 9100

Q: 远程设备连接不上（Connection refused）？

1. 确认 MCP Server 用了 --host 0.0.0.0（不是默认的 127.0.0.1）
2. 确认 Tailscale 已连接：tailscale ip
3. Mac 可能需要关闭防火墙：

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off

Q: WSL2 上 Tailscale 连上了但端口不通？

WSL2 在 NAT 后面，其他设备可能无法访问 WSL 的端口。解决方案：

1. 在 Windows 宿主机上也安装 Tailscale，然后端口转发
2. 或在 Windows 上执行：

netsh interface portproxy add v4tov4 listenport=9100 listenaddress=0.0.0.0 connectport=9100 connectaddress=<WSL IP>

Q: 如何查看 MCP Server 是否在运行？

# Linux
lsof -i :9100

# macOS
lsof -i :9100

Q: 如何查看日志？

cat ~/.hermes-coordinator/logs/server.log

Q: 如何停止 MCP Server？

pkill -f "server.py.*--port 9100"

安全说明

• 所有通信通过 Tailscale 加密隧道（WireGuard）
• 建议启用 HMAC 认证（--secret）
• 建议设置目录白名单（--whitelist）
• 不要在公网暴露端口，仅通过 Tailscale 内网访问

License

MIT