Claw Control Server

自托管的 Claw Control 中继服务器，用于 Claw Manager iOS App 远程访问 OpenClaw Gateway。

架构

Claw Manager (iOS)  ←WebSocket→  Claw Control Server (你的服务器)  ←WebSocket→  OpenClaw Host (Mac)  ←→  OpenClaw Gateway

快速部署

一键部署（推荐）

# 在你的云服务器上运行：
curl -fsSL https://raw.githubusercontent.com/ip81198/claw-control-server/main/deploy.sh | bash

自定义端口：

PORT=3900 curl -fsSL https://raw.githubusercontent.com/ip81198/claw-control-server/main/deploy.sh | bash

手动安装

# 1. 安装
npm install -g claw-control-server

# 2. 启动
claw-control-server start --port 5201

# 3. 查看帮助
claw-control-server --help

systemd 服务

# 生成 service 文件
claw-control-server deploy --port 5201

# 安装并启动
sudo systemctl daemon-reload
sudo systemctl enable --now claw-control-server

# 查看状态
sudo systemctl status claw-control-server
sudo journalctl -u claw-control-server -f

API

注册网关

curl -X POST http://your-server:5201/api/relay/register \
  -H "Content-Type: application/json" \
  -d '{"displayName": "我的 Mac"}'

返回：

{
  "gatewayId": "abc123...",
  "relaySecret": "secret...",
  "accessCode": "ABCDEFGH"
}

刷新配对码

curl -X POST http://your-server:5201/api/relay/accesscode \
  -H "Content-Type: application/json" \
  -d '{"gatewayId": "abc123...", "relaySecret": "secret..."}'

服务器状态

curl http://your-server:5201/api/relay/status

健康检查

curl http://your-server:5201/health

配套工具

claw-control-client（CLI 客户端）

npm install -g claw-control-client

clawcontrol pair              # 注册/配对
clawcontrol pairing           # 显示配对信息 + QR码
clawcontrol status            # 连接状态

WebSocket 协议

Mac 端连接

ws://your-server:5201/relay/{gatewayId}?secret={relaySecret}

iOS 端（Claw Manager）连接

ws://your-server:5201/relay/{gatewayId}?accessCode={accessCode}

消息格式

中继服务器透明转发两端之间的 JSON 消息：

• iOS → Mac: cmd 消息（RPC 请求）
• Mac → iOS: res 消息（RPC 响应）、event 消息（事件推送）
• 心跳: tick 事件保持连接

配置

| 环境变量 | 默认值 | 说明 | |---------|-------|------| | PORT | 5201 | 服务端口 |

安全

• 每个网关有独立的 relaySecret（32字节随机）
• iOS 配对码（accessCode）可随时刷新
• 断开重复连接，同一网关同时只允许一个 Mac 端和一个 iOS 端
• 建议在生产环境使用 nginx 反向代理 + HTTPS

nginx 配置示例

server {
    listen 443 ssl;
    server_name relay.your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:5201;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
}

License

MIT