ClawdBot App

iOS 客户端，连接用户自己的 Clawdbot Gateway（通常运行在 Mac mini 上），支持对话、与 Mac mini + Tailscale 部署。

功能

• Chat：与 Gateway 背后的 AI 对话，支持文字；流式回复（chat.chunk）
• 连接：Clawdbot Gateway v3 over WebSocket，支持 Tailscale、局域网、公网（wss）
• 角色：Operator 设备（role=operator），通过 chat.send 与 AI 对话

要求

• iOS 16.0+
• Xcode 15.0+
• 一台运行 Clawdbot Gateway 的主机（推荐 Mac mini + Tailscale）

快速开始

1. Mac mini 上运行 Gateway

• 安装并启动 Clawdbot Gateway（见官方文档）
• 无公网 IP 时：在 Mac 上安装 Tailscale，网关配置中开启 tailscale.mode: "serve" 暴露端口 18789

2. iPhone 与 Mac 同网

• 推荐：iPhone 安装 Tailscale，加入与 Mac 相同的 tailnet，使用 Tailscale IP 或 MagicDNS（如 ws://100.x.x.x:18789 或 ws://my-mac.tail12345.ts.net:18789）
• 同 WiFi：填写 Mac 的局域网地址，如 192.168.1.100:18789（可只填 host:port，App 会自动补 ws://）
• 公网（如阿里云）：填写服务器地址，建议使用 wss:// 并配置 TLS

3. 打开工程并运行

cd ClawdBotApp
open ClawdBotApp.xcodeproj

在 Xcode 中选择开发团队、连接设备或模拟器，按 ⌘R 运行。

4. 配置 App

1. 打开 Settings，填写 Gateway URL（如 100.x.x.x:18789 或 ws://100.x.x.x:18789）
2. 填写 Gateway Token（openclaw onboard 时自动生成，存于 gateway.auth.token）：
   • 在 Gateway 主机上查看：cat ~/.openclaw/openclaw.json | grep -A 2 '"gateway"'
   • 或查看 JSON 中的 gateway.auth.token 字段
3. 开启 Auto Connect 可在启动时自动连接
4. 点击 Connect 连接网关

5. 首次连接（设备审批）

若首次连接或未配对，需在运行 Gateway 的机器上审批设备：

openclaw devices list
openclaw devices approve <requestId>

审批通过后会下发 device token，之后无需重复审批。

Token 使用规则（按 Gateway 协议文档）：

• connect.params.auth.token：优先使用 Gateway Token（Settings 中填写）。若未填写 Gateway Token，则使用 Device Token（hello-ok 下发的）。
• Gateway Token：openclaw onboard 时自动生成，存于 gateway.auth.token，用于 connect 认证。
• Device Token：审批通过后 hello-ok 下发，存入 Keychain，仅在用户未配置 Gateway Token 时用于 connect。
• Token 不放在 WebSocket URL 内。

无 Token 连接：认证默认开启时必须填写 Gateway Token；仅在 Gateway 显式关闭认证时可不填（不推荐）。

项目结构

ClawdBotApp/
├── App/                    # 入口、ContentView、Node 首页
├── Gateway/                # WebSocket、v3 协议、DeviceIdentity
├── Capabilities/           # 相机、定位、录屏
├── Canvas/                 # WebView 画布
├── Chat/                   # 对话 UI、流式消息
├── Settings/               # 设置（URL、Token、权限）
└── Resources/              # Info.plist、Assets

开发阶段说明

• 阶段一：连接 Mac mini（Tailscale/局域网），connect.challenge → 签名 → hello-ok
• 阶段二：Node 能力（camera/canvas/location/screen）与权限、活动日志
• 阶段三：Operator 对话（chat.send、chat.chunk、chat.message）、Gateway Token（onboard 时必生成）
• 阶段四：URL 规范化（自动补 ws://）、流式展示、Tailscale 文档与体验

协议

• Clawdbot Gateway v3（req/res/event）over WebSocket
• 角色：Operator 设备（role=operator），支持 chat.send；非 Node 角色（Node 能力如相机/画布需双连接方案，暂未实现）
• 认证：设备 Ed25519 签名 + deviceToken（首次连接需 gatewayToken，onboard 时自动生成）

gateway token mismatch

错误提示：unauthorized: gateway token mismatch (provide gateway auth token)

说明：connect 时 connect.params.auth.token 优先使用 Gateway Token。若 Settings 中已填写 Gateway Token，则一定用它；未填写时才用 Device Token。

处理：确保 Settings 中 Gateway Token 与 Gateway 主机 ~/.openclaw/openclaw.json 的 gateway.auth.token 完全一致（无空格、无换行）。

设备看不到 / openclaw devices list 为空

排查步骤：

1. 确认 App 已发 connect 请求：用 Xcode 运行 App，连真机时在 Xcode 控制台看 [ClawdBot] 日志：

   • 有 connect.challenge received → WebSocket 已连通，Gateway 发了 challenge
   • 有 >>> deviceId 完整值 → 已发送 connect 请求，记下该 deviceId
   • 若以上都没有 → 可能是网络/URL/Token 问题，连接未成功

2. 在 Gateway 主机上执行（需与 App 填的 Gateway 在同一台机）：

   openclaw devices list
   openclaw devices list --json   # 看完整 JSON

   若 Gateway 在别机，需加 --url ws://host:18789 --token <gateway_token>。

3. 检查 Gateway 日志：Gateway 进程的 stdout 或日志文件，是否有设备连接/待审批记录。

4. 确认 pending 未过期：待审批请求约 5 分钟过期，过期需在 App 里重试 Connect。

调试日志

调试阶段关键步骤（连接、协议、Chat、认证、Node 能力）会输出 [ClawdBot] 前缀的日志。关闭方式：

• 在 DebugLog.swift 中设置 DebugLog.enabled = false
• 或用 Release 构建（默认关闭）

测试

1. 用 Xcode 打开 ClawdBotApp.xcodeproj
2. 在 Signing & Capabilities 中选择你的 Development Team
3. 选择模拟器或真机，按 ⌘R 运行
4. 在 Settings 中填写 Gateway URL（如 100.x.x.x:18789 或 ws://...），点击 Connect 测试连接

License

MIT