Claude Relay

克劳德接力

Claude Code实例通过WebSocket+MCP跨多台机器进行实时通信。

这有什么作用

使不同机器上的Claude Code会话能够实时相互发送消息。适用于：

• 上下文共享 -在会话之间共享发现、文件内容或调查结果
• 任务交接 -在一台机器上启动一个任务，在另一台上继续
• 协调 -让一个Claude Code实例知道另一个实例在做什么

建筑

Machine A                              Machine B (Server Host)
┌─────────────────┐                   ┌─────────────────┐
│  Claude Code    │                   │  Claude Code    │
│      ↓          │                   │      ↓          │
│  MCP Server     │                   │  MCP Server     │
│      ↓          │                   │      ↓          │
│  WebSocket  ────┼── SSH Tunnel ─────┼─→ Relay Server  │
│  (localhost)    │   or direct       │   (port 9999)   │
└─────────────────┘                   └─────────────────┘

组件

安装

git clone https://github.com/gvorwaller/claude-relay.git
cd claude-relay
npm install

快速开始

1.启动中继服务器（在一台机器上）

node server.js
# [Claude Relay] Ready! Listening on ws://localhost:9999

2.配置克劳德代码（在每台机器上）

添加到您的Claude Code MCP配置中(~/.claude.json):

{
  "mcpServers": {
    "claude-relay": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/claude-relay/mcp-server.js"],
      "env": {
        "RELAY_URL": "ws://localhost:9999"
      }
    }
  }
}

3.通过SSH隧道连接远程机器

如果机器不在同一网络上，请使用SSH端口转发：

# On the remote machine, tunnel to the server host
ssh -N -L 9999:localhost:9999 server-host &

# Or use autossh for auto-reconnecting
autossh -M 0 -N -L 9999:localhost:9999 server-host &

______________________________________________________________________

会话识别系统

为Claude会话（CC-1、CC-2、CODEX等）分配人类可读的ID，以便于协调。

设置外壳别名

添加到您的 ~/.zshrc 或 ~/.bashrc:

# Claude Relay Session Management
alias claude-session='source ~/claude-relay/sessions/register.sh'
alias claude-sessions='~/claude-relay/sessions/list.sh'

用法

注册会话（在启动Claude Code之前在终端中）：

claude-session CC-1
# ✓ Registered: CLAUDE_RELAY_SESSION_ID=CC-1

列出所有已注册的会话：

claude-sessions
# === Registered Claude Sessions ===
#   CC-1       PID: 12345  Started: 1/12/2026, 3:30:00 PM
#              CWD: /Users/you/project
#   CODEX      PID: 67890  Started: 1/12/2026, 4:15:00 PM
#              CWD: /Users/you/other-project

会话ID优先级

MCP服务器按以下顺序确定客户端ID：

1. CLAUDE_RELAY_SESSION_ID -Shell别名设置此
2. --client-id 命令行参数
3. RELAY_CLIENT_ID 环境变量
4. 自动生成： hostname-pid

会话注册表

会话在中跟踪 ~/claude-relay/sessions/registry.json 因此所有AI实例都可以看到彼此。

______________________________________________________________________

MCP工具

配置后，Claude Code将拥有以下工具：

示例用法

发送消息：

Use relay_send to tell CC-2: "Found the bug - it's in auth.js line 42"

检查消息：

Use relay_receive to see if there are any messages from peers

查看谁在线：

Use relay_peers to list connected instances

查看所有已注册的会话：

Use relay_sessions to see all Claude sessions, online and offline

______________________________________________________________________

macOS自动启动（LaunchAgent）

中继服务器（在服务器主机上）

# Copy the LaunchAgent
cp com.claude-relay.plist ~/Library/LaunchAgents/

# Edit the plist to fix paths for your system:
# - Update /usr/local/bin/node to your node path (use `which node`)
# - Update /Users/yourname/claude-relay to your install path

# Load it
launchctl load ~/Library/LaunchAgents/com.claude-relay.plist

验证它是否正在运行：

launchctl list | grep claude-relay
# PID  Status  Label
# 1234 0       com.claude-relay

SSH隧道（在远程计算机上）

# Install autossh
brew install autossh

# Copy and edit the tunnel LaunchAgent
cp com.claude-relay-tunnel.plist ~/Library/LaunchAgents/

# Edit to set your server hostname and paths

# Load it
launchctl load ~/Library/LaunchAgents/com.claude-relay-tunnel.plist

______________________________________________________________________

测试

使用交互式测试客户端：

# Terminal 1: Start server
node server.js

# Terminal 2: Connect as client A
node test-client.js MACHINE_A

# Terminal 3: Connect as client B
node test-client.js MACHINE_B

# In either client:
send Hello from here!
peers
history

______________________________________________________________________

配置

环境变量

命令行参数

# Server
node server.js [port]
node server.js 8888

# MCP Server
node mcp-server.js --client-id=LAPTOP --relay-url=ws://192.168.1.100:9999

______________________________________________________________________

文件结构

claude-relay/
├── server.js                 # WebSocket relay server
├── mcp-server.js             # MCP protocol server for Claude Code
├── test-client.js            # Interactive test client
├── package.json              # Node.js dependencies
├── sessions/
│   ├── register.sh           # Shell script to register session ID
│   ├── list.sh               # Shell script to list sessions
│   └── registry.json         # Session registry (auto-generated)
├── logs/
│   ├── relay.log             # Relay server logs
│   └── relay-error.log       # Relay server errors
├── com.claude-relay.plist    # macOS LaunchAgent for relay server
└── com.claude-relay-tunnel.plist  # macOS LaunchAgent for SSH tunnel

______________________________________________________________________

故障排除

连接被拒绝：

• 确保中继服务器正在运行： lsof -i :9999
• 如果使用SSH隧道，请验证它是否处于活动状态： ps aux | grep ssh

MCP工具未出现：

• 添加MCP配置后重新启动Claude代码
• 检查MCP服务器是否正在连接：在日志中查找“已连接！”

未到达的消息：

• 使用 relay_peers 验证两个实例是否已连接
• 通过以下方式检查消息历史记录 relay_receive

孤立MCP过程：

• MCP服务器包括一个父进程监视器
• 如果Claude Code意外退出，MCP服务器将在10秒内自动终止
• 要手动清理，请执行以下操作： pkill -f "claude-relay/mcp-server.js"

会话未显示正确的ID:

• 确保你跑了 claude-session CC-1 启动Claude Code之前
• 请检查： echo $CLAUDE_RELAY_SESSION_ID
• 会话ID继承自shell环境

______________________________________________________________________

安全注意事项

• 默认情况下，中继服务器没有身份验证
• 专为可信本地网络或SSH隧道而设计
• SSH隧道上的所有流量都是加密的
• 在不添加身份验证的情况下，不要将端口9999暴露给互联网

______________________________________________________________________

许可证

麻省理工学院