古法编程

Appearance

Android 作为伴侣节点（不托管网关），通过 WebSocket 直接连接 OpenClaw 网关。配对前需启动网关并确保 Android 可达（同网 mDNS 或 Tailscale wss:// 端点）。关键命令：openclaw gateway --port 18789 启动，dns-sd -B _openclaw-gw._tcp local. 验证发现，openclaw devices approve <requestId> 批准配对，openclaw nodes status 验证连接。Tailscale 下必须使用 wss:// 端点；通知转发需配置 allowPackages 和 quietHours。

OpenClaw Android 节点配对与连接配置指南 ​

INFO

官方 Android 应用已上架 Google Play。它作为伴侣节点运行，要求已启动的 OpenClaw 网关。源码也在 OpenClaw 仓库 的 apps/android 目录下，构建说明见 apps/android/README.md。

功能概览 ​

  • 角色：伴侣节点（Android 不托管网关）
  • 前提：网关需在 macOS、Linux 或 Windows（WSL2）上运行
  • 安装：Android 应用从 Google Play 安装；网关部署见 快速入门，配对见 配对
  • 协议：网关协议（节点 + 控制面）

连接架构 ​

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

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

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

  • 推荐：Tailscale Serve / Funnel，提供 wss:// 端点（如 https://&lt;magicdns&gt;）
  • 也支持任何带真实 TLS 的 wss:// 网关 URL
  • 私有局域网地址（.local 主机、localhost、127.0.0.1、安卓模拟器桥接 10.0.2.2）仍支持明文 ws://
  • Tailnet/公网手机配对不使用原始 tailnet IP 的 ws:// 端点，必须用 Tailscale Serve 或其他 wss:// URL

前提条件 ​

  • 网关在“主”机器上可运行
  • Android 设备/模拟器能到达网关 WebSocket：
    • 同一局域网（mDNS/NSD），或
    • 同一 Tailscale tailnet（使用 Wide-Area Bonjour / unicast DNS-SD，见下文），或
    • 手动指定网关主机/端口（回退方案）
  • 能在网关机器上（或通过 SSH）运行 CLI 命令 openclaw

连接步骤 ​

1) 启动网关 ​

bash
openclaw gateway --port 18789 --verbose

日志应包含类似 listening on ws://0.0.0.0:18789 的内容。

用于 Tailscale 远程 Android 访问时，推荐使用：

bash
openclaw gateway --tailscale serve

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

2) 验证发现（可选） ​

在网关机器上：

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

更多调试信息：Bonjour 文档。

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

bash
openclaw gateway discover --json

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

Tailnet（如 Vienna ⇄ London）发现通过 unicast DNS-SD ​

Android NSD/mDNS 无法跨网络。如果 Android 节点和网关在不同网络但通过 Tailscale 连接，使用 Wide-Aware Bonjour / unicast DNS-SD。

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

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

配置示例见 Bonjour 文档。

3) 从 Android 连接 ​

在 Android 应用中：

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

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

存活信标 ​

认证节点会话连接后，应用进入后台但前台服务仍连接时，Android 调用 node.event 发送 event: "node.presence.alive"。网关在认证节点设备身份已知后，才在配对节点/设备元数据中记录 lastSeenAtMs/lastSeenReason。

只有当网关响应包含 handled: true 时，应用才认为信标成功记录。旧版网关可能回复 { "ok": true }，该响应兼容但不作为持久的最后存活更新。

4) 审批配对（CLI） ​

在网关机器上：

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

配对详情：配对文档。

可选：如果 Android 节点始终来自严格控制的子网，可以选择启用首次节点自动审批，显式指定 CIDR 或精确 IP：

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

默认禁用。仅适用于不含请求作用域的 role: node 新鲜配对。操作员/浏览器配对以及任何角色、作用域、元数据或公钥更改仍需手动审批。

5) 验证节点已连接 ​

  • 通过节点状态：

    bash
    openclaw nodes status

  • 通过网关：

    bash
    openclaw gateway call node.list --params "{}"

6) Chat 与历史记录 ​

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

  • 历史记录：chat.history（显示标准化：内联指令标签被剥离，纯文本工具调用 XML 负载被剥离，纯静默 token 的助手行被省略，超大行替换为占位符）
  • 发送：chat.send
  • 实时更新（尽力）：chat.subscribe → event:"chat"

7) Canvas 与摄像头 ​

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

如果想让节点显示 Agent 可以编辑的真实 HTML/CSS/JS，将节点指向网关 Canvas 主机。

INFO

节点从网关 HTTP 服务器加载 Canvas（与 gateway.port 同端口，默认 18789）。

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

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

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

Tailscale（可选）：如果两台设备都在 Tailscale 上，用 MagicDNS 名称或 tailnet IP 替换 .local，例如 http://&lt;gateway-magicdns&gt;:18789/__openclaw__/canvas/。

此服务器向 HTML 注入热更新客户端，文件变更时自动重载。A2UI 主机地址：http://&lt;gateway-host&gt;:18789/__openclaw__/a2ui/

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 是遗留别名）

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

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

参数和 CLI 帮助见 Camera 节点文档。

8) 语音与扩展命令面 ​

  • 语音标签：Android 有两种显式捕获模式。Mic 是手动语音标签会话，每次暂停作为一次聊天轮次发送，离开前台或离开语音标签时停止。Talk 是连续语音模式，持续监听直到关闭或节点断开。
  • Talk 模式在捕获开始前将现有前台服务从 dataSync 提升为 dataSync|microphone，Talk 停止后降级。Android 14+ 需要 FOREGROUND_SERVICE_MICROPHONE 声明、RECORD_AUDIO 运行时授权以及运行时麦克风服务类型。
  • 默认情况下，Android Talk 使用原生语音识别、网关聊天和 talk.speak（通过配置的网关 Talk provider）。仅当 talk.speak 不可用时使用本地系统 TTS。
  • Android Talk 仅在 talk.realtime.mode 为 realtime 且 talk.realtime.transport 为 gateway-relay 时使用实时网关中继。
  • 语音唤醒在 Android UX/运行时中保持禁用。
  • 其他 Android 命令族（可用性取决于设备和权限）：
    • 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, ask OpenClaw...”会打开应用并将提示词传入聊天框。

这使用 Android App Actions 元数据（在应用清单中声明）。网关侧无需额外配置——助手意图完全由 Android 应用处理，并转发为普通聊天消息。

INFO

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

通知转发 ​

Android 可将设备通知作为事件转发到网关。以下控制项限定哪些通知被转发以及何时转发。

配置键类型描述
notifications.allowPackagesstring[]只转发这些包名的通知。如果设置，其他所有包被忽略。
notifications.denyPackagesstring[]永不转发这些包名的通知。在 allowPackages 之后应用。
notifications.quietHours.startstring (HH:mm)静默时段开始（本地设备时间）。该时段内通知被抑制。
notifications.quietHours.endstring (HH:mm)静默时段结束。
notifications.rateLimitnumber每个包每分钟最大转发数，超出丢弃。

通知选择器还对转发的通知事件使用更安全的行为，防止意外转发敏感系统通知。

示例配置：

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

INFO

通知转发需要 Android 通知监听权限，应用在设置时会提示授权。

常见问题 ​

Android 设备和网关在同一局域网但发现不到网关，怎么办？ ​

确认网关已启动并监听（openclaw gateway status 显示 Runtime: running），运行 dns-sd -B _openclaw-gw._tcp local. 验证 mDNS 服务已发布。如果 mDNS 被路由器屏蔽，在 Android 应用 Advanced controls 中手动输入网关 IP 和端口（使用 ws://）。如果仍失败，检查防火墙是否允许 18789 端口。

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

使用 openclaw gateway --tailscale serve 启动网关。Tailscale Serve 会自动提供 HTTPS 端点（MagicDNS 域名 + 自动证书），无需手动配置证书。之后 Android 连接时，在 Manual 模式中填入 wss://&lt;your-magicdns&gt;:18789 并开启 TLS。

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

正常。Android 语音功能设计为“前台专用”，应用离开前台（切换到后台或锁屏）时语音自动停止。仅当 Talk 模式运行时，前台服务会临时提升为 microphone 类型，但离开语音标签后仍会停止。如需后台持续监听，请关注 OpenClaw 后续版本。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策