本页是 OpenClaw Android 节点应用的完整使用指南。Android 作为伴侣节点（不托管网关），通过 WebSocket 连接网关。涵盖局域网 mDNS 发现、Tailscale 跨网络连接、配对审批、Chat/Voice/Canvas/Camera 命令，以及通知转发配置。

OpenClaw Android 节点应用

注意： Android 应用尚未公开发布。源代码在 OpenClaw 仓库 apps/android 目录下，可用 Java 17 和 Android SDK 自行构建（./gradlew :app:assemblePlayDebug）。

功能概览

• 角色： 伴侣节点（Android 不托管网关）
• 前提： 需要在 macOS、Linux 或 Windows（WSL2）上运行网关
• 支持协议： mDNS/NSD + WebSocket
• 文档： 快速入门 · 配对 · 网关配置

连接架构

Android 应用 ⇄ (mDNS/NSD + WebSocket) ⇄ 网关

Android 直接连接到网关 WebSocket，使用 role: node 进行设备配对。

TLS 要求（Tailscale 或公网主机）：

• 推荐：Tailscale Serve / Funnel，获取 wss:// 端点
• 支持其他带真实 TLS 的 wss:// URL
• 私有局域网地址（.local、localhost、127.0.0.1、安卓模拟器 10.0.2.2）支持明文 ws://
• Tailnet/公网手机配对不使用原始 tailnet IP 的 ws:// 端点，需使用 Tailscale Serve 或其他 wss:// URL

完整连接流程

步骤 1：启动网关

openclaw gateway --port 18789 --verbose

日志应显示 listening on ws://0.0.0.0:18789。

Tailscale 远程 Android 访问推荐使用：

openclaw gateway --tailscale serve

这给 Android 提供安全的 wss:// 端点。单纯的 gateway.bind: "tailnet" 设置不足以首次远程配对（除非你单独终止 TLS）。

步骤 2：验证发现（可选）

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

更多调试信息：Bonjour 文档

如果也配置了 wide-area 发现域，可以与以下命令对比：

openclaw gateway discover --json

该命令在一次输出中同时展示 local. 和已配置的 wide-area 域，并使用解析后的服务端点（而非仅 TXT 提示）。

如果 Android 和网关分处不同网络但通过 Tailscale 相连，mDNS 无法跨网络——需要配置 Wide-Area Bonjour / unicast DNS-SD。

仅发现还不足以在 tailnet/公网 Android 上完成配对，发现到的路由仍需要安全端点（wss:// 或 Tailscale Serve）：

1. 在网关主机上设置 DNS-SD 区域（如 openclaw.internal.），发布 _openclaw-gw._tcp 记录
2. 为 Tailscale 配置指向该 DNS 服务器的分割 DNS

步骤 3：从 Android 连接

在 Android 应用中：

• App 通过前台服务（持久通知）保持网关连接
• 打开 Connect 标签
• 使用 Setup Code 或 Manual 模式
• 发现受阻时，在 Advanced controls 中手动输入主机/端口；私有局域网主机可使用 ws://，Tailscale/公网主机请开启 TLS 并使用 wss:// / Tailscale Serve 端点

首次配对成功后，Android 在启动时自动重连：先尝试手动端点（如已启用），否则尝试上次发现的网关。

步骤 4：审批配对（CLI）

在网关主机上：

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

配对详情：配对文档

步骤 5：验证节点已连接

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

Chat 与历史记录

Android Chat 标签支持会话选择（默认 main，也可选其他已有会话）：

• 历史记录：chat.history（显示标准化，去除内联指令标签、工具调用 XML、泄露的 ASCII 控制 token，过滤纯静默 token 的助手行）
• 发送：chat.send
• 实时更新（尽力）：chat.subscribe → event:"chat"

Canvas 与摄像头

网关 Canvas 主机（推荐，用于 Web 内容）

如果想让节点显示 Agent 可以编辑的真实 HTML/CSS/JS：

1. 在网关主机创建 ~/.openclaw/workspace/canvas/index.html

2. 导航节点到该页面（局域网）：

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

Tailscale（可选）：用 MagicDNS 名或 tailnet IP 替换 .local。

Gateway Canvas 服务器会向 HTML 注入热更新客户端，文件变更时自动重载。A2UI 主机地址：http://<gateway-host>:18789/__openclaw__/a2ui/

Canvas 命令（仅前台）：

• canvas.eval、canvas.snapshot、canvas.navigate
• canvas.a2ui.push、canvas.a2ui.reset

摄像头命令（仅前台，需权限）：

• camera.snap（jpg）
• camera.clip（mp4）

详情：Camera 节点

语音与扩展命令面

• 语音： Android 在 Voice 标签使用单一麦克风开/关流程，支持转录捕获和 talk.speak 播放（本地 TTS 仅在 talk.speak 不可用时使用）；离开前台时语音停止
• 其他命令（根据设备和权限）：
  • device.status、device.info、device.permissions、device.health
  • notifications.list、notifications.actions
  • photos.latest
  • contacts.search、contacts.add
  • calendar.events、calendar.add
  • callLog.search
  • sms.search
  • motion.activity、motion.pedometer

系统助手集成

Android 支持从系统助手触发器（Google Assistant）启动 OpenClaw。配置后，长按 Home 键或说"Hey Google，问 OpenClaw..."会打开应用并将 prompt 传入聊天框。

这通过 Android App Actions 元数据实现，网关侧无需额外配置。

注意：App Actions 可用性取决于设备、Google Play Services 版本，以及用户是否将 OpenClaw 设为默认助手 App。

通知转发

Android 可将设备通知作为事件转发到网关：

配置项	类型	说明
notifications.allowPackages	string[]	只转发这些包名的通知（未设置则不过滤）
notifications.denyPackages	string[]	永不转发这些包名的通知（在 allowPackages 之后应用）
notifications.quietHours.start	string (HH:mm)	静默时间开始（设备本地时间），该时段内通知不转发
notifications.quietHours.end	string (HH:mm)	静默时间结束
notifications.rateLimit	number	每个包每分钟最大转发数，超额丢弃

示例配置：

{
  notifications: {
    allowPackages: ["com.slack", "com.whatsapp"],
    denyPackages: ["com.android.systemui"],
    quietHours: {
      start: "22:00",
      end: "07:00",
    },
    rateLimit: 5,
  },
}

注意：通知转发需要 Android 通知监听权限，App 在设置时会提示授权。

常见问题

Q: Android 和网关在同一局域网但发现不到网关，怎么办？

A: 确认网关已启动并监听（openclaw gateway status 显示 Runtime: running），再运行 dns-sd -B _openclaw-gw._tcp local. 确认 mDNS 服务已发布。如果 mDNS 被路由器屏蔽，用手动模式输入网关 IP 和端口。

Q: Tailscale 网络下配对提示需要 HTTPS，但我没有证书怎么办？

A: 使用 openclaw gateway --tailscale serve 启动网关，Tailscale Serve 会自动提供 HTTPS 端点（MagicDNS 域名 + 自动证书）。无需手动配置证书。

Q: Android 语音功能在切换 App 后停了，正常吗？

A: 是正常行为。Android 语音功能设计为"前台专用"，App 离开前台（切换到后台或锁屏）时语音自动停止。如需后台持续工作，请查看 OpenClaw 后续版本的更新。