Android 应用

​

支持概览

• 角色：伴随节点应用（Android 不托管 Gateway）。
• 需要 Gateway：是（在 macOS、Linux 或通过 WSL2 的 Windows 上运行它）。
• 安装：Google Play 或从受支持的 GitHub Release 获取 OpenClaw-Android.apk，Gateway 的入门指南，然后进行配对。
• Gateway：运行手册 + 配置。
  • 协议：Gateway 协议（节点 + 控制平面）。
• 设置 → OpenClaw 会在操作员连接具备 operator.admin 且 Gateway 支持 openclaw.chat 时打开一个专用的 Gateway 设置助手。其设置对话与普通 Chat 保持分离，在本地会对机密回复进行脱敏，并且只有在你点击 Open Chat 后才会切换到 Chat。

​

同时网关会话

​

Wear OS 伴侣应用

​

安装到 Google Play 之外

release_tag=vYYYY.M.PATCH
gh release download "$release_tag" \
  --repo openclaw/openclaw \
  --pattern OpenClaw-Android.apk \
  --pattern OpenClaw-Android-SHA256SUMS.txt
sha256sum --check OpenClaw-Android-SHA256SUMS.txt
gh attestation verify OpenClaw-Android.apk \
  --repo openclaw/openclaw \
  --signer-workflow openclaw/openclaw/.github/workflows/android-release.yml \
  --source-ref "refs/tags/${release_tag}" \
  --deny-self-hosted-runners

​

从远程 Mac 镜像并控制 Android

​

开始之前

• 在 Android 设备和 Mac 上安装 Tailscale，并将两者连接到同一个 tailnet。
• 在 Android 上，启用 开发者选项 和 USB 调试。Android 16 将 无线调试 放在 设置 > 系统 > 开发者选项 下。参见 Android 开发者选项。
• 在 Mac 上安装 scrcpy 和 ADB：
  brew install scrcpy
  brew install --cask android-platform-tools
  
• 在首次连接时保持 Android 设备可用。Android 必须先批准每台 Mac 的 ADB 密钥，然后该 Mac 才能控制设备。

​

启用通过 TCP 的 ADB

adb devices
adb tcpip 5555

​

仅允许控制端 Mac

{
  grants: [
    {
      src: ["<远程 Mac 的 tailnet IP>"],
      dst: ["<Android 的 tailnet IP>"],
      ip: ["tcp:5555"],
    },
  ],
}

​

连接并开始镜像

adb connect <android-tailnet-ip>:5555
adb devices
scrcpy --serial <android-tailnet-ip>:5555

​

故障排除

• Connection timed out：验证 TCP 5555 的 tailnet 授权规则。成功的 tailscale ping 只能证明对等端可达，并不能证明策略允许此 TCP 端口。请在 Mac 上使用 nc -vz <android-tailnet-ip> 5555 测试。
• unauthorized：解锁 Android 并批准远程 Mac 的 ADB 密钥，或者在 无线调试 > 已配对的设备 下移除过期的工作站，然后重新配对。
• Connection refused：重新本地连接并再次运行 adb tcpip 5555。
• 列出了多个设备：保留明确的 --serial <android-tailnet-ip>:5555 参数。

adb disconnect <android-tailnet-ip>:5555

​

连接运行手册

• 优先：使用 Tailscale Serve / Funnel，并通过 https://<magicdns> / wss://<magicdns>
• 也支持：任何其他带真实 TLS 端点的 wss:// Gateway URL
• 仍支持明文 ws://：适用于私有 LAN 地址 / .local 主机，以及 localhost、127.0.0.1 和 Android 模拟器桥接地址 (10.0.2.2)；非回环地址的设置会自动使用受限操作者权限

​

前提条件

• Gateway 在另一台机器上运行（或可通过 SSH 访问）。
• Android 设备/模拟器可以连接到 gateway WebSocket：
  • 同一局域网内，使用 mDNS/NSD，或
  • 同一 Tailscale tailnet，使用广域 Bonjour / 单播 DNS-SD（见下文），或
  • 手动指定 gateway 主机/端口（回退方案）
• tailnet/公网移动端配对 不 使用原始 tailnet IP ws:// 端点。请改用 Tailscale Serve 或其他 wss:// URL。
• gateway 机器上可用 openclaw CLI（或通过 SSH），用于批准配对请求。

​

1. 启动 Gateway

openclaw gateway --port 18789 --verbose

• listening on ws://0.0.0.0:18789

openclaw gateway --tailscale serve

​

2. 验证发现（可选）

dns-sd -B _openclaw-gw._tcp local.

openclaw gateway discover --json

​

通过单播 DNS-SD 跨网络发现

1. 在 gateway 主机上设置一个 DNS-SD 区域（示例 openclaw.internal.），并发布 _openclaw-gw._tcp 记录。
2. 为你选择的域名配置 Tailscale split DNS，使其指向该 DNS 服务器。

​

3. 从 Android 连接

• 应用通过前台服务（常驻通知）保持与 gateway 的连接。
• 打开 Connect 选项卡。
• 使用 Setup Code 或 Manual 模式。
• 如果发现被阻止，请在 Advanced controls 中手动填写 host/port。对于私有局域网主机，ws:// 仍然可用。对于 Tailscale/公网主机，请开启 TLS 并使用 wss:// / Tailscale Serve 端点。

​

管理已配对的 gateway

• Settings → Gateway 会列出已配对的 gateway，并标记当前聚焦的那个。点击某项即可切换焦点；其他已启用的操作者会话仍保持连接。
• 每个开关控制的是：当应用处于前台时，该非聚焦的 Gateway 是否保持连接。当前聚焦的 Gateway 始终保持启用，并拥有手机的节点连接和设备能力。
• Connect 选项卡在配对了多个 gateway 时会显示一个快速切换器。
• 凭据、设备 token、TLS 信任、聊天历史以及离线排队消息都按每个 Gateway 单独存储。切换焦点不会混合不同 Gateway 的状态，而离线期间排队的消息只会发送到其写入时对应的 Gateway。
• Forget 会删除某个 gateway 的注册表项，以及其凭据、设备 token、TLS pin 和缓存的聊天内容。

​

存活信标

​

4. 批准配对（CLI）

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

​

5. 验证节点已连接

openclaw nodes status
openclaw gateway call node.list --params "{}"

​

6. 聊天 + 历史记录

• History: chat.history（显示规范化——内联指令标签、纯文本工具调用 XML 负载（<tool_call>、<function_call>、<tool_calls>、<function_calls> 及其截断变体），以及泄露的 ASCII/全角模型控制 token 会被清除；像精确 NO_REPLY / no_reply 这样的静默 token 助手行会被省略；超大的行可替换为占位符）
• Send: chat.send
• Durable sending: every send (text, picked images, and voice notes) is journaled to a per-gateway on-device outbox before any network attempt, so app termination cannot lose submitted input. Sends queued while offline deliver in order on reconnect with stable idempotency keys, and a send is retired only after the turn is visible in canonical chat.history — an acknowledgement alone is not treated as proof of delivery. Ambiguous outcomes (lost acknowledgement, app killed mid-send, gateway restart before the transcript write) surface as visible rows with explicit Retry/Delete instead of auto-resending. Slash commands never auto-replay across a reconnect; they park for explicit retry. The queue is bounded (50 messages and 48 MB of attachment bytes per gateway) and unsent rows expire after 48 hours. Composer drafts that were never submitted are not process-durable.
• Image input works through the picker and Android Sharesheet. Assistant-generated images resolve through the paired Gateway connection, render inline with a full-screen preview, and retain only their small artifact references in the offline transcript cache. Downloads are capped at 12 MiB and decoded to bounded display bitmaps.
• Push updates (best-effort): chat.subscribe -> event:"chat"
• Listen: 长按某条助手消息并选择 Listen 即可收听；音频通过 gateway tts.speak 和已配置的 TTS provider chain 渲染，当 gateway 无法渲染音频时会使用设备上的系统 TTS。切换会话、开始新聊天、应用进入后台或关闭聊天时，播放都会停止。

​

7. Canvas + camera

​

Gateway Canvas Host（推荐用于网页内容）

1. 在 gateway 主机上创建 ~/.openclaw/workspace/canvas/index.html。
2. 将节点导航到它（局域网）：

openclaw nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__openclaw__/canvas/"}'

• canvas.eval, canvas.snapshot, canvas.navigate（使用 {"url":""} 或 {"url":"/"} 返回默认骨架）。canvas.snapshot 返回 { format, base64 }（默认 format="jpeg"）。
• A2UI: canvas.a2ui.push, canvas.a2ui.reset（canvas.a2ui.pushJSONL 为旧别名）。这些命令使用内置的、由应用拥有的 A2UI 页面进行可执行动作的渲染。

​

8. 语音 + 扩展的 Android 命令面

• Android 的 shell 导航包括 Home、Chat 和 Settings。语音输入属于 Chat 编辑器；没有单独的 Voice 选项卡。
• 点按编辑器麦克风可使用设备上的语音识别，并将转写内容插入草稿。长按麦克风可录制语音笔记附件。UI 会报告无法识别、权限缺失、繁忙/网络失败以及无语音等结果，而不是静默丢弃尝试。
• 从 Chat 波形开始持续 Talk。听写、语音笔记录制和 Talk 是互斥的麦克风路径。
• Talk Mode 会在捕获开始前将现有前台服务从 connectedDevice 提升为 connectedDevice|microphone，在 Talk Mode 停止时再降级。节点服务声明 FOREGROUND_SERVICE_CONNECTED_DEVICE 以及 CHANGE_NETWORK_STATE；Android 14+ 还需要 FOREGROUND_SERVICE_MICROPHONE 声明、RECORD_AUDIO 运行时授权，以及运行时的 microphone service type。
• 默认情况下，Android Talk 使用原生语音识别、Gateway chat，以及通过已配置的 gateway Talk provider 的 talk.speak。仅当 talk.speak 不可用时才使用本地系统 TTS。
• 只有当 talk.realtime.mode 为 realtime 且 talk.realtime.transport 为 gateway-relay 时，Android Talk 才使用实时 Gateway relay。
• Android 不会声明 voiceWake 能力。请使用 Chat 听写、语音笔记或 Talk 进行语音输入。
• 其他 Android 命令族（可用性取决于设备、权限和用户设置）：
  • device.status, device.info, device.permissions, device.health
  • 仅当启用 Settings > Phone Capabilities > Installed Apps 时，device.apps 才可用；默认列出启动器可见的应用（传入 includeNonLaunchable 可获取完整列表）。
  • notifications.list, notifications.actions（见下文 通知转发）
  • photos.latest
  • contacts.search、contacts.add
  • calendar.events、calendar.add
  • callLog.search
  • sms.search
  • motion.activity、motion.pedometer

​

9. Workspace files（只读）

​

审核命令批准

​

回答代理问题

​

助手入口

​

通知转发

​

相关

• iOS 应用
• 节点
• Android 节点故障排除