PhoneClaw Skill 使用指南

概述

PhoneClaw Skill 是一个 OpenClaw 插件，用于将你的 OpenClaw Gateway 与 PhoneClaw iOS App 连接。安装后，Skill 会自动建立与中继服务器的连接，使你可以从手机远程控制你的 AI Agent。

快速开始

前置条件

• OpenClaw Gateway 已安装并运行
• Node.js >= 18.0.0
• 可以访问中继服务器（默认 wss://relay.phoneclaw.com）

安装

# 1. 克隆或下载 Skill 代码
git clone https://github.com/your-org/phoneclaw-skill.git
cd phoneclaw-skill

# 2. 安装依赖
npm install

# 3. 构建
npm run build

# 4. 安装到 OpenClaw
openclaw skills install ./dist

配置

编辑 config.json 文件：

{
  "relayServer": "wss://relay.phoneclaw.com",
  "autoConnect": true,
  "heartbeatInterval": 30000,
  "reconnectAttempts": 5,
  "reconnectDelay": 5000,
  "gatewayUrl": "ws://127.0.0.1:18789",
  "gatewayToken": ""
}

| 配置项 | 说明 | 默认值 | |--------|------|--------| | relayServer | 中继服务器地址 | wss://relay.phoneclaw.com | | autoConnect | 是否自动连接 | true | | heartbeatInterval | 心跳间隔（毫秒） | 30000 | | reconnectAttempts | 最大重连次数 | 5 | | reconnectDelay | 重连基础延迟（毫秒） | 5000 | | gatewayUrl | OpenClaw Gateway 地址 | ws://127.0.0.1:18789 | | gatewayToken | Gateway 认证 Token（可选） | "" |

启动

# 启动 Skill
npm start

# 或使用 openclaw 命令
openclaw skills enable phoneclaw-connector
openclaw skills start phoneclaw-connector

使用方式

生成配对码

# 生成 6 位配对码和二维码
npm run pair

# 输出示例：
# === PhoneClaw Pairing Code ===
# Code: 123456
# Expires: 2024-01-01 12:00:00
# 
# QR Code:
# ██████████████████████████████
# ...
# ==============================

查看状态

# 查看连接状态
npm run status

# 输出示例：
# === PhoneClaw Skill Status ===
# Device ID: abc123def456
# Gateway: Connected
# Relay: Connected
# Active Sessions: 2
# ===============================

日常使用

1. 启动 Skill：运行 npm start
2. 打开 PhoneClaw App：在 iPhone 上打开 App
3. 扫码配对：扫描 Skill 终端显示的二维码，或手动输入配对码
4. 开始聊天：配对成功后即可从手机发送消息

命令参考

| 命令 | 说明 | |------|------| | npm start | 启动 Skill（守护进程模式） | | npm run pair | 生成配对码和二维码 | | npm run status | 查看连接状态 | | npm run build | 构建 TypeScript 代码 | | npm run dev | 开发模式（带热重载） |

故障排查

无法连接到中继服务器

# 检查网络连接
ping relay.phoneclaw.com

# 检查防火墙设置
# 确保出站 WebSocket 连接（端口 443）未被阻止

无法连接到 Gateway

# 检查 Gateway 是否运行
openclaw gateway status

# 检查 Gateway 地址和端口
# 默认: ws://127.0.0.1:18789

# 检查 Token 是否正确
# 如果配置了 gatewayToken，确保与 Gateway 配置一致

配对失败

# 检查配对码是否过期（10 分钟有效）
# 重新生成配对码: npm run pair

# 检查设备是否在线
npm run status

# 确保 Skill 已连接到中继服务器

消息发送失败

# 检查 Gateway 连接状态
npm run status

# 检查中继服务器连接状态
npm run status

# 查看日志输出
# Skill 会在终端输出详细的连接和消息日志

高级配置

自定义中继服务器

如果你部署了自己的中继服务器，修改 config.json：

{
  "relayServer": "wss://your-relay-server.com"
}

自定义 Gateway 地址

如果 Gateway 运行在非默认地址或远程服务器：

{
  "gatewayUrl": "ws://your-gateway-server.com:18789",
  "gatewayToken": "your-gateway-token"
}

日志级别

Skill 默认输出 INFO 级别日志。要启用调试日志：

# 设置环境变量
DEBUG=phoneclaw:* npm start

安全注意事项

• 设备密钥：device.json 文件包含设备认证密钥，请妥善保管
• 配对码：配对码 10 分钟有效，使用后自动失效
• 网络连接：确保中继服务器使用 WSS（WebSocket Secure）加密连接
• Token 保护：如果配置了 gatewayToken，不要将其提交到版本控制系统

更新

# 拉取最新代码
git pull

# 重新安装依赖
npm install

# 重新构建
npm run build

# 重启 Skill
npm start

技术支持

• 文档：PhoneClaw 技术方案
• 问题反馈：[email protected]