夜雨聆风
iOS 安装并配对 OpenClaw Node 完整指南
OpenClaw 是一个开源的远程智能体框架，iOS Node 是其纯 Node 客户端，主要负责将 iPhone 的麦克风、摄像头、GPS、屏幕等硬件能力暴露给家里的 Agent 使用。配合 Gateway 远程访问，即使出门在外也能远程唤醒家里的小龙虾系统。
注意：目前 iOS App 处于极早期 Alpha 阶段，未上架 App Store，只能通过 TestFlight 或自行编译安装。请作为尝鲜使用，勿用于生产环境。
1. 前置准备
硬件要求
• 一台运行 Xcode 16+ 的 Mac（建议 macOS Sequoia 或更高）
• 一台 iPhone（真机，必须用数据线连接 Mac 安装）
• 推荐安装 Tailscale（用于远程访问 Gateway）
软件工具
• Xcode 16+
• pnpm（OpenClaw 仓库使用的包管理器）
• xcodegen（brew install xcodegen）
• Apple 开发者账号（免费个人账号即可）
2. 编译并安装 iOS App
1. 克隆 OpenClaw 仓库并安装依赖：
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
2. 配置本地签名（生成唯一 bundle
./scripts/ios-configure-signing.sh
3. 生成并打开 Xcode 项
cd apps/ios
xcodegen generate
open OpenClaw.xcodeproj
（也可直接在仓库根目录运行快捷命令 pnpm ios:open）
4. 在 Xcode 中进行以下设置：
• Scheme 选择 OpenClaw
• Destination 选择你用数据线连接的 iPhone 真机（强烈建议使用真机，模拟器无法正常测试摄像头、麦克风、定位等功能）
• Build Configuration 选择 Debug
5. 点击 Product → Run 编译运行。
编译成功后，App 会自动安装到你的 iPhone 上，桌面上会出现红色小龙虾图标。
提示：个人免费开发者证书有效期通常只有 7 天，过期后 App 无法打开，重新在 Xcode 中 Run 一次即可刷新证书。
3. 配对 iOS Node 到 Gateway
首次打开 App 会看到欢迎引导页，包含三步流程和安全提醒。请认真阅读安全提示，只有在完全信任 Gateway 和 Agent 时才继续。
配对方式一：手动输入 Setup Code（推荐远程使用）
1. 在 WebChat（或 Gateway 对应聊天界面）中向 Agent 发送 /pair 命令，获取 Setup Code。
2. 复制整段 Setup Code（base64 格式的 JSON，包含 url 和 bootstrapToken）。
3. 在 iOS App 中进入 Settings → Gateway，粘贴 Setup Code。
4. 连接成功后状态会显示已连接。
配对方式二：扫描二维码（更便捷）
1. 在 WebChat 中发送 /pair qr，生成二维码。
2. 在 App 的 Connect Gateway 页面点击 Scan QR Code，扫描二维码即可自动完成连接。
配对方式三：同局域网 Bonjour 自动发现（无需 Setup Code）
适用于手机和 Gateway 在同一局域网内：
• Gateway 启动后会通过 Bonjour 广播服务。
• App 在 Settings 中会自动搜索并显示 Gateway，点击连接。
• 然后在 Gateway 主机上运行以下命令批准设备：
openclaw devices list
openclaw devices approve <requestId>
注意：跨网络（如通过 Tailscale）时必须使用方式一或二。
4. 配置 iOS Node 能力
配对成功后，进入 Settings → Device → Features 配置权限：
• Voice Wake：唤醒词模式（持续监听麦克风）
• Talk Mode：连续语音对话模式
• Speech Language：选择中文（中国）
• Background Listening：允许后台监听（iOS 限制较严，锁屏后可能失效）
• Wake Words：唤醒词列表（从 Gateway 同步）
• Allow Camera：摄像头权限（前台可用）
• Location Access：位置权限（推荐 While Using）
• Prevent Sleep：防止屏幕自动锁定
重要提醒：iOS 系统限制，摄像头、屏幕等功能要求 App 保持在前台，后台调用会返回 NODE_BACKGROUND_UNAVAILABLE。
5. 验证与使用
1. 在 Gateway 主机验证节点：
openclaw nodes status
openclaw nodes location get –node “你的iOS设备名”
2. 设置 Active Agent（首页可选择 main / personal / work 等）。
3. 测试语音唤醒和对话功能。
常见问题
• 证书过期：重新在 Xcode Run 即可。
• 后台监听不稳定：iOS 系统行为，属于正常现象。
• 远程无法连接：检查 Tailscale 是否正常，确保使用 wss:// 地址。
• 编译报错：确保 Xcode 版本足够新，pnpm 依赖已安装完整。
通过以上步骤，你就可以将 iPhone 变成 OpenClaw 的移动 Node，随时随地调用手机的感官能力，让你的智能体系统真正“装进口袋”。