Android 应用
Note
官方 Android 应用可在 Google Play 获取,也可作为已签名的独立 APK 在部分 GitHub Releases 中侧载安装。并非每个版本都包含 APK 和校验和。请参阅 在 Google Play 之外安装 以查找并验证这两个文件。它是一个配套节点,需要运行中的 OpenClaw Gateway。源代码:apps/android(构建说明)。
支持快照¶
- 角色:配套节点应用(Android 不托管 Gateway)。
- 需要 Gateway:是(在 macOS、Linux 或通过 WSL2 的 Windows 上运行)。
- 安装:Google Play 或从列出了所需资产的 GitHub Release 中获取
OpenClaw-Android.apk(请参阅 在 Google Play 之外安装),Gateway 设置参见 入门指南,然后进行 配对。 - Gateway:Runbook + 配置。
- 协议:Gateway 协议(节点 + 控制平面)。
- 在侧边栏中选择一个代理,即可在 设置 → 提供方与模型 中查看其凭据状态。当 Gateway 发布模型、凭据或配置变更时,页面会自动更新。使用 刷新 可重新检查模型可用性。
- 侧边栏会标记等待回答或审批的会话,包括非活动会话和折叠的分组。点击、悬停或使用键盘聚焦注意力图标,可读取最早的处理中请求及其他同类请求的数量。当请求被解决、取消或过期时,指示器会清除。问题预览从不包含回答草稿。
- 侧边栏和最近的线程视图会将 cron 会话和系统创建的检查排除在普通聊天列表之外,但不会更改已保存的固定项。所选对话仍然可访问;命名工作和人工创建的后台对话仍然可见。打开 线程 → 自动化 可查找并重新打开自动化会话和系统会话,包括以前固定的聊天。这是一个视图过滤器,不是已保存的设置。侧边栏 → 页面铅笔图标 → 自动化 显示计划任务及其最近的运行摘要。其他没有创建元数据的会话仍然可见,不会被按其标题分类。
- 长按符合条件的线程并选择 稍后提醒:1 小时后、3 小时后、今晚(本地时间 18:00,若距此超过一小时)、明天(本地时间 09:00)或 下周(下周一本地时间 09:00,周日不显示)。稍后提醒的会话会从最近、当前和侧边栏最近项中隐藏。稍后提醒 药丸形状标记显示其唤醒时间;唤醒会话 可提前将其恢复。时间到期、真实入站消息或运行完成都会唤醒会话;固定或归档也会清除稍后提醒。稍后提醒通过 Gateway 同步,绝不会停止运行、消息或自动化。已归档、子会话和受保护的会话无法设置稍后提醒。
- 设置 → OpenClaw 在操作员连接具有
operator.admin且 Gateway 支持openclaw.chat时,会打开一个专用的 Gateway 设置助手。其设置对话与普通聊天分开,会在本地对机密回复进行脱敏处理,只有在您点击 打开聊天 后才会移至聊天中。
其回复字段会在机密提示时切换为掩码输入。如果提示变更关闭了键盘,请再次点击该字段。Android 发送敏感回复时不会去除两端空格,并在您离开此页面或将应用置于后台时清除未发送的草稿。
当您位于设置对话末尾时,新回复会保持在视图中。向上滚动阅读更早的步骤而不会被拉走,然后点击 跳到最新 以恢复跟随。如果调整窗口大小使整个对话可见,跟随也会自动恢复。重启 在出错后出现时,会从其最新回复处打开一个新对话。
系统控制(launchd/systemd)位于 Gateway 主机上——请参阅 Gateway。
同时使用多个 Gateway 会话¶
每个 Gateway 仅配对一次,然后打开 设置 → Gateway。对勾标记表示 当前聚焦的 Gateway,每个开关控制非聚焦 Gateway 的 操作员会话是否保持连接。启用的 Gateway 在应用处于 前台时会独立重新连接,因此切换焦点不会断开 其他 Gateway。只有聚焦的 Gateway 拥有 Android 节点会话和设备 能力;这可以防止多个 Gateway 同时向同一部手机发出摄像头、 定位、屏幕或通知命令。应用离开前台后,Android 可能会挂起 次要连接。
侧边栏默认为 首页 → 线程 → 技能 → 概览。已保存的 个性化排序和固定的工作页面会保留;页面铅笔图标 → 编辑固定项 → 重置固定项 可恢复这些默认值。Gateway 选择器旁边的 设置 齿轮图标 可打开所有设置,包括离线时也能打开。设置保留在 页脚中,而不是在页面菜单或固定编辑器中。
使用 页面旁边的铅笔图标 可打开代理、自动化、用量、技能、 技能工作坊、梦境、终端或桌面(如果可用)。使用 编辑固定项 固定您常用的页面。这些工作页面也可以通过搜索访问; 设置专注于本手机、连接、配置和诊断。设置、侧边栏、搜索和详情 标题栏与 Web UI 使用相同的图标含义。连接和审批状态会用文字写明, 而不是用无标签的绿色或灰色圆点表示。
侧边栏页脚的 Gateway 选择器在没有已保存 Gateway 时打开 添加 Gateway, 有已保存的 Gateway 时打开 Gateway 设置。如果保存了多个 Gateway, 它会打开一个原生快速选择器,带有所聚焦路由的对勾标记、 添加 Gateway 和 管理 Gateway。
Add Gateway 会打开二维码扫描器,而不会断开当前 Gateway,也不会重新开始引导流程。你也可以输入设置码、选择二维码图片,或手动输入 Gateway URL。有效的设置码会打开确认界面;只有 Connect 才会开始交接。Cancel 会返回上一个界面,且不会更改当前会话、草稿、附件或已保存的 Gateway。添加已保存的 Gateway 会使用其现有的连接设置;如需替换其设置,请使用 Manage Gateways。已保存的离线条目仍会保留在列表中;连接状态与选择状态相互独立。
在 Manage Gateways 中,点按 Rename 可为 Gateway 选择仅限本手机使用的名称。该名称会显示在侧边栏和选择器中,并在切换 Gateway、重新连接、应用重启以及发现更新后仍然保留。次要地址仍可用于区分同名的 Gateway。清除名称即可恢复默认名称。重命名不会更改 Gateway 的地址、身份或已保存的凭证。降级到较旧的 Android 版本时,该版本启动并重写注册表后可能会丢弃这些本地名称。Gateway 地址和凭证不受影响;再次升级后,如有需要可重新选择本地名称。
当你切换离开再返回时,未发送的文本和已完成的附件会保留在其所属的 Gateway、智能体和会话中。在使用快速选择器之前,请先完成录音、停止听写或 Talk,并等待媒体导入或待处理的发送准入完成。交接期间编辑器会保持受保护状态,但已提交的离线 Gateway 无需等待网络连接即可继续使用。
听写与附件¶
点按编辑器中的麦克风即可开始听写。当识别正在启动、正在聆听或正在转写时,编辑器会显示相应状态,并随着你的说话提供临时转写文本。只有最终转写结果才会添加到草稿中。点按 Stop 结束聆听,或在启动或转写过程中点按 Cancel 丢弃该次尝试。识别错误不会影响你已有的草稿,并会说明如何重试。
选择或分享照片和文件后,Preparing attachments… 会一直显示,直到附件准备就绪。准备期间 Send 保持禁用状态。Queuing message… 涵盖本地发送准入;之后消息的发件箱状态会显示投递结果或任何失败原因。离线消息仍会使用持久队列。
Wear OS 配套应用¶
Wear OS 配套应用使用已配对 Android 手机上经过身份验证的 Gateway 连接;手表永远不会接收或存储 Gateway 凭证。它可以选择智能体会话、读取有界转写记录、发送文本或听写回复、中止正在进行的 run、在所选会话中启动实时 Talk,以及连接或断开已配对手机的 Gateway。它还提供本地回复通知、深色或浅色外观,以及可选的回复语音播报。智能体和 Gateway 控件通过能力协商确定,以适应手机与手表不同步的更新。实时 Talk 会通过临时的 Wear OS Data Layer 通道传输麦克风和播放音频,并在所选手机、Gateway 连接或音频通道丢失时停止。
在 Google Play 之外安装¶
部分选定的 GitHub Releases 包含通用版 OpenClaw-Android.apk 和 OpenClaw-Android-SHA256SUMS.txt。该 APK 由 release tag 构建,使用 OpenClaw Android 发布密钥签名,并带有 GitHub Actions 来源证明。Android 资源可能会在版本公开发布后附加。请根据列出的资源选择版本,而不要根据最新的 Gateway release tag 选择。
列出同时包含这两个必需资源的已发布版本:
gh api --paginate "repos/openclaw/openclaw/releases?per_page=50" \
--jq '.[] | select(.draft | not) | {
tag: .tag_name,
apk: ([.assets[].name] | any(. == "OpenClaw-Android.apk")),
checksum: ([.assets[].name] | any(. == "OpenClaw-Android-SHA256SUMS.txt"))
} | select(.apk and .checksum)'
选择同时列出这两个资源的版本,然后在旁加载之前下载并验证该确切标签:
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
如果没有版本同时列出这两个文件,请使用 Google Play,或使用你自己的签名身份从源代码构建。
Warning
Google Play 和独立 APK 安装使用不同的更新渠道,并且可能具有不同的签名身份。Android 可能需要在切换渠道之前卸载现有应用,这会删除其本地应用数据。请保持使用单一渠道以进行正常更新。
Note
从源代码或 fork 构建发布产物(APK 或 app bundle)需要你自己的 Android 签名身份。调试构建使用自动生成的调试签名密钥。官方 OpenClaw 发布密钥不包含在仓库中。关于如何为发布构建生成和配置签名密钥,请参阅为应用签名。
应用与 Gateway 兼容性¶
Android 应用和 Gateway 不需要匹配的发布版本号。连接兼容性取决于它们所支持的 Gateway 协议版本,而不是包含该 APK 的 release tag。
Android 对聊天和 UI 操作(operator 连接)与设备能力(node 连接)使用独立的连接。operator 连接必须支持 Gateway 当前的协议。经过身份验证的 node 连接可以在文档规定的兼容窗口内使用上一版协议;该例外不适用于聊天或 UI 操作。当前版本和 node 能力限制请参阅 Gateway 协议版本。
成功配对并不保证在任意应用/Gateway 版本组合下所有功能都能正常工作。新功能可能需要双方都进行更新。如果某个连接报告 protocol mismatch,请检查应用和 Gateway 双方的协议要求及可用更新。对于旁加载的应用,请使用上面的 APK 选择和验证步骤,而不要假设最新的 Gateway release 包含更新的应用。
从远程 Mac 镜像并控制 Android¶
scrcpy 在 macOS 窗口中镜像 Android 屏幕,并通过 Android Debug Bridge(ADB)转发键盘和指针输入。这是一个操作员端工作流,与 OpenClaw 节点连接相互独立。当 Android 设备和 Mac 位于不同位置但共享同一个私有 Tailscale 网络时,它很有用。
开始之前¶
- 在 Android 设备和 Mac 上安装 Tailscale,并将两者连接到同一 tailnet。
- 在 Android 上启用 开发者选项 和 USB 调试。Android 16 将 无线调试 放在 设置 → 系统 → 开发者选项 下。请参阅 Android 开发者选项。
- 在 Mac 上安装 scrcpy 和 ADB:
- 首次连接时请保持 Android 设备可用。Android 必须批准每台 Mac 的 ADB 密钥,之后该 Mac 才能控制设备。
启用 TCP 上的 ADB¶
初始设置时,通过 USB 将 Android 设备连接到受信任的计算机,并批准其调试提示。然后运行:
现在可以断开 USB。如果设备重启或调试重置后端口 5555 停止监听,请重复此本地设置步骤。Android 11 及更高版本也可以使用 无线调试 → 使用配对码配对设备 和 adb pair 建立初始信任。
仅允许控制端 Mac¶
具有限制性授权(grants)的 tailnet 必须显式允许控制端 Mac 访问 Android 设备上的 TCP 端口 5555。在 tailnet 策略中添加一条窄规则,并将示例地址替换为两台设备的稳定 Tailscale IP:
{
grants: [
{
src: ["<remote-mac-tailnet-ip>"],
dst: ["<android-tailnet-ip>"],
ip: ["tcp:5555"],
},
],
}
有关主机别名和其他选择器,请参阅 Tailscale grants。不要将此端口授权给公共互联网,也不要使用 Funnel 暴露它:已授权的 ADB 客户端对设备具有广泛控制权。
连接并开始镜像¶
在远程 Mac 上:
从这台 Mac 首次运行 adb connect 时,Android 上会显示授权对话框。解锁设备,确认密钥指纹,并且仅在 Mac 受信任时选择 始终允许来自此计算机。成功的 adb devices 条目以 device 结尾;unauthorized 表示设备上的提示尚未批准。
scrcpy 窗口打开后,可以直接使用它,也可以使用 macOS 屏幕自动化工具(例如 Peekaboo)将其作为目标。scrcpy 负责传输显示和输入;Tailscale 仅提供私有网络路径。
故障排除¶
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参数。
完成后,关闭 scrcpy 并断开 ADB:
连接操作手册¶
Android 节点应用 ⇄ (mDNS/NSD + WebSocket) ⇄ Gateway
Android 直接连接到 Gateway WebSocket,并使用设备配对(role: node)。
对于 Tailscale 或公共主机,Android 需要安全端点:
- 首选:使用
https://<magicdns>/wss://<magicdns>的 Tailscale Serve / Funnel - 也支持:任何其他具有真实 TLS 端点的
wss://Gateway URL - 明文
ws://仍支持私有 LAN 地址 /.local主机,以及localhost、127.0.0.1和 Android 模拟器桥接(10.0.2.2);非回环设置会自动使用受限操作员访问
前提条件¶
- 另一台机器上正在运行 Gateway(或可通过 SSH 访问)。
- Android 设备/模拟器可以访问 Gateway WebSocket:
- 同一 LAN 并使用 mDNS/NSD,或
- 同一 Tailscale tailnet 并使用 Wide-Area Bonjour / 单播 DNS-SD(见下文),或
- 手动指定 Gateway 主机/端口(回退方案)
- Tailnet/公共移动配对不使用原始 tailnet IP
ws://端点。请改用 Tailscale Serve 或其他wss://URL。 - Gateway 机器上(或通过 SSH)可用
openclawCLI,用于批准配对请求。
1. 启动 Gateway¶
使用已认证的 Gateway。如果尚未配置,请先运行 openclaw onboard 配置 token 或密码。
对于受信任的同一 LAN 设置,在启动前持久化 LAN 绑定:
裸机和虚拟机主机默认使用回环,手机无法访问。检测到的容器可以默认使用 auto。请为此设置显式设置绑定。
请使用 config 命令,而不是单独使用 --bind lan:仅启动时使用的标志不会改变单独的 openclaw qr 命令读取的配置。如果没有其他已配置的 URL 路由,设置码创建仍会看到回环并拒绝生成代码。
运行 openclaw gateway status。其 Gateway: 行应显示 bind=lan (0.0.0.0) 和 port=18789。
对于远程 Android 访问,可选择托管 Tailscale Serve 作为 LAN 绑定的替代方案。将其设置保留在配置中,以便设置码创建可以使用相同路由:
openclaw config set gateway.bind loopback
openclaw config set gateway.tailscale.mode serve
openclaw gateway --port 18789
必须安装并登录 Tailscale。托管 Serve 和 Funnel 要求回环绑定;切换到它们时不要保留 gateway.bind=lan 设置。有关 Serve 和密码认证的 Funnel 设置,请参阅 Tailscale。
这将为 Android 提供一个安全的 wss:// / https:// 端点。仅配置 gateway.bind: "tailnet" 对于首次远程 Android 配对是不够的,除非你另外单独终结 TLS。
2. 验证发现(可选)¶
在 Gateway 机器上:
更多调试说明:Bonjour。
如果你还配置了广域发现域名,请将其与以下内容进行对比:
这会一次性显示 local. 以及已配置的广域域名,并使用解析后的服务端点,而不是仅使用 TXT 提示。
通过单播 DNS-SD 进行跨网络发现¶
Android NSD/mDNS 发现无法跨网络。如果 Android 节点和 Gateway 位于不同网络,但通过 Tailscale 连接,请改用 Wide-Area Bonjour / 单播 DNS-SD。仅靠发现不足以完成 tailnet/公共 Android 配对——发现的路由仍然需要一个安全端点(wss:// 或 Tailscale Serve):
- 在 Gateway 主机上设置一个 DNS-SD 区域(例如
openclaw.internal.),并发布_openclaw-gw._tcp记录。 - 为你选择的域名配置 Tailscale 拆分 DNS,使其指向该 DNS 服务器。
详细说明和 CoreDNS 配置示例:Bonjour。
3. 从 Android 连接¶
在 Control UI(设备 → 配对设备)中创建设置代码,或使用 openclaw qr。
该移动端设置代码(及其 QR)就是 Android 扫描 QR 或设置代码 / 输入设置代码 所接受的内容。它与由 openclaw devices join-code 生成的 gateway 加入 URL(https://…/j/<code>)是不同的产物,后者通过 openclaw connect 注册无头节点主机。将加入 URL 或单独的加入代码粘贴到 Android 设置中会被拒绝——请使用 openclaw qr 生成新的移动端 QR/设置代码。
显式的 --url 或 --public-url 覆盖项优先。否则,设置代码 URL 选择按以下顺序进行:
plugins.entries.device-pair.config.publicUrl,除非请求了远程偏好。- 当明确偏好时使用
gateway.remote.url。 - 托管 Tailscale Serve 或 Funnel。
- 普通的
gateway.remote.url设置。 - 可用的已配置绑定,例如第 1 步中的 LAN 绑定。
openclaw qr --remote 选择远程凭据,忽略已配置的 device-pair publicUrl,并在托管 Tailscale 之前优先使用 gateway.remote.url。参见 QR。
URL 选择不会测试网络可达性。解析错误会阻止创建设置代码,而不是触发较低优先级的路由。仅回环的 Gateway 如果没有配置 URL 或托管 Tailscale 路由,将拒绝生成代码。
在 Android 应用中:
- 应用通过前台服务(持久通知)保持其 Gateway 连接处于活动状态。
- 在首次运行设置期间,选择扫描 QR 或设置代码或手动设置。
- 配对后,选择要启用的手机权限。如果 Gateway 需要节点批准,请查看请求的功能,并在出现时点击批准访问并继续。应用验证批准后,设置完成。否则,按照显示的 Gateway 批准命令操作,然后点击我已批准。
- 设置完成后,打开设置 → Gateway。添加 Gateway 允许你扫描或粘贴设置代码,或连接到已发现的 Gateway。
- 如果发现被阻止,请在该页面上使用手动 Gateway:输入主机和端口,选择连接安全性,然后点击保存并连接。私有 LAN 主机支持
ws://;对于 Tailscale/公共主机,请使用安全(TLS)以及wss:/// Tailscale Serve 端点。
Gateway 令牌、引导令牌、密码和设置代码会被掩码显示并接受粘贴。应用请求输入密码时禁用自动更正,但无法保证第三方键盘如何存储或从输入中学习。
首次成功配对后,Android 会在启动时自动重新连接到当前活动的已配对 Gateway(对于已发现的 Gateway,这是尽力而为的,它们必须在网络上可见)。
Android 会自动重试临时连接丢失。若要使用已保存的端点重新尝试,请打开设置 → Gateway 并点击重新连接。断开连接会停止连接,并在当前应用会话中抑制自动重连;它不会忘记配对。身份验证或配对错误可能会暂停重试,直到你解决报告的问题。
Gateway 摘要行会换行显示较长的标签和值。在设置 → Gateway 中点击实例 ID,可复制此手机的完整标识符。
官方设置代码会将 Android 作为节点连接,并默认通过 wss:// 授予完整的 Gateway 操作员访问权限。明文非回环 ws:// 设置会自动使用受限访问,以确保 bearer-token 安全。设置 → Gateway 会显示完整或受限访问。对于受限连接,请配置 wss:// 或 Tailscale Serve,在 Control UI 中或使用 openclaw qr 生成新的完整访问代码,然后在该页面上扫描或粘贴它并重新连接。希望使用受限配置的操作员可以在 Control UI 中选择受限访问,或运行 openclaw qr --limited。
管理已配对的 Gateway¶
应用会维护一个注册表,记录其已配对的每个 Gateway,因此你可以保持操作员会话连接,并在不重新配对的情况下切换焦点:
- 设置 → Gateway 会在Gateway部分列出已配对的 Gateway,并在当前聚焦项旁显示对勾。点击另一个条目以聚焦它;其他已启用的操作员会话仍保持连接。
- 每个开关控制该非聚焦 Gateway 在应用处于前台时是否保持连接。聚焦的 Gateway 保持启用,并拥有手机的节点连接和设备功能。
- 凭据、设备令牌、TLS 信任、聊天记录和排队的离线消息按 Gateway 存储。切换焦点绝不会在不同 Gateway 之间混合状态,离线期间排队的消息只会投递到其写入的目标 Gateway。
- 忘记会删除某个 Gateway 的注册表条目,同时删除其凭据、设备令牌、TLS pin 和缓存的聊天。
打开或回复会话通知时,如有需要会重新连接其已保存的 Gateway。已经处于连接中或已连接的目标会被保留。回复会等待该目标连接就绪,包括所需的 TLS 批准。如果目标不再可用,打开通知会显示 Gateway 不可用,并打开 Gateway 设置,而不会断开另一个 Gateway。在通知回复进入持久发送队列之前,会再次检查断开状态;已排队输入保持其正常恢复行为。
回复已排队 表示回复已进入持久发送队列,而不是表示已送达。通知会保留所提交文本的私有预览,并提供 打开会话。如果回复状态未知,请先打开会话检查,再重新发送;通知不会提供另一个回复操作。反馈只会更新该会话的最新通知,因此较旧的结果无法替换较新的通知。在应用更新之前发布的通知仍可以发送回复。其结果不会重写或关闭该通知,因此请打开会话检查其状态。
频道、Dreaming、健康 日志、技能 和 用量 页面在刷新时会保留上次加载的数据。首次加载失败时显示错误,而不是显示空计数或默认健康值。当刷新请求重叠时,只有最新请求会更新页面的数据、错误和进度。断开连接会清除显示的摘要。
在 健康 中,聊天:未就绪 表示聊天健康状态未确认或其检查失败;Gateway 仍可能为 在线。聊天标题的无障碍状态使用相同的就绪措辞。在聊天操作中使用 刷新聊天 再次检查;刷新日志 只会重新加载日志。概览中的 Gateway 卡片报告连接状态并突出显示已知问题,而不是整体系统健康状态。
Presence 存活信标¶
在已认证节点会话连接后,以及当应用退到后台而前台服务仍保持连接时,Android 会以 event: "node.presence.alive" 调用 node.event。只有在已知已认证节点设备身份后,Gateway 才会将其记录为配对节点/设备元数据上的 lastSeenAtMs/lastSeenReason。
只有当 Gateway 响应包含 handled: true 时,应用才将该信标计为成功记录。如果 Gateway 使用 { "ok": true } 确认 node.event 且没有 handled 字段,则兼容,但该响应不计为持久最后见到更新。
4. 批准配对(CLI)¶
在 Gateway 机器上:
配对详情:配对。
可选:如果 Android 节点始终来自受严格控制的子网,你可以选择启用首次节点自动批准,并指定明确的 CIDR 或精确 IP:
此功能默认禁用。它仅适用于没有请求作用域的全新 role: node 配对。操作员/浏览器配对以及任何角色、作用域、元数据或公钥更改仍需要手动批准。
5. 验证节点已连接¶
6. 聊天 + 历史记录¶
草稿拥有位于附件和语音/发送控件上方的独立全宽行, 因此更大的文本和较窄的屏幕不会将其挤压在按钮之间。空状态 提示保持在一行;草稿最多显示六行,空间有限时会滚动。 输入框的侧边留白比聊天记录更窄。+、模型和 推理保持在左侧;麦克风和 Talk/发送 保持在右侧同一行。控件高度保持 48dp;非常短的视图使用 更窄的图标按钮,为 详情 腾出空间,同时保留可编辑行。 占位符和输入文本共享相同的对齐方式。
打开 + 可查看紧凑图标列表,包括相机、图库、文件、位置和 权限。权限行显示当前访问模式。打开右上角 聊天操作(⋮)菜单可查看实时上下文用量环。选择 上下文 可 打开上下文用量、最近一次运行的 token 数和成本明细。查看用量不需要 更改会话设置的权限。当没有成本明细时,报告的模型调用总数仍会显示。 缺失的用量显示为未知。 轻点模型名称可在输入框上方打开紧凑菜单,按模型名称、 ID 或提供商搜索,并展开提供商分组。搜索接受多个词,以及至少四个字母单词中的小 拼写错误,包括相邻字母互换。每个 词都必须匹配;短词和版本号不会进行拼写纠正。每个提供商内,精确 匹配排在最前,提供商分组则跟随其最佳 匹配。清除搜索会恢复通常的排序,而不会更改你的选择。 选择器没有设置按钮。Gateway 的 已配置默认值会标注在其模型行上。选择命名模型会将该 模型固定到会话;默认模型 单独重置覆盖设置,以跟随 Gateway 的当前默认值。 已固定和最近使用的模型仍可用。较长的模型名称使用中间 省略号,完整名称可在选择器中查看。强度拨盘会打开其 滑块和快速模式,而不会展开输入框。拖动滑块会在 拨盘上预览强度;松开后应用选择。
当草稿为空且没有活动运行时,末尾按钮启动 Talk。输入 文本会将其变为发送;有活动运行但没有草稿时显示停止。 在 Talk 期间,实时波形会替换麦克风,并保持可轻点以 结束 Talk。如果同时有活动运行,一个独立的、柔和着色的停止按钮会留在 末尾边缘,以中止该运行。
从侧边栏的 页面 菜单打开 主页 以进行聊天,或从侧边栏选择现有会话:
- 历史记录:
chat.history(显示已规范化——内联指令标签、纯文本工具调用 XML 载荷(<tool_call>、<function_call>、<tool_calls>、<function_calls>以及截断变体)以及泄漏的 ASCII/全角模型控制令牌会被移除;静默令牌助手行(例如精确的NO_REPLY/no_reply)会被省略;超大行可被占位符替换) - 长回复:在截断的助手回复上轻点 查看全部,可内联加载完整格式化文本。附件仍保留在对话中,消息操作使用展开后的文本。轻点 收起 或按返回键可恢复预览;重新打开时会复用已加载的回复。加载、可重试的失败、不可用消息,以及所需的重连或 Gateway 更新会显示在消息中,而不是弹出提示。合成消息工具和评论预览保留其现有显示和操作,但不提供 查看全部,因为其复制的转录 ID 无法检索该合成文本。这也识别来自已发布 Gateway(例如 v2026.7.1-2)的旧版截断预览格式。Android 每个文本字段最多请求 1,000,000 个字符,与 Gateway 的默认检索限制一致;超大或仍被截断的结果会显示 完整消息过大,无法显示。 而不是不完整的回复。
- 大型代码块会在有界视口内滚动,并提供 代码开头、代码结尾 和 复制代码 控件。开头和结尾还会在对话中显示该代码块的对应端。选择范围保持在当前显示的文本段内;复制代码 会复制整个代码块。独立的 选择文本 消息操作会打开纯文本选择阅读器;长答案使用有界分页,选择仅应用于当前显示页。
- 阅读:向上滚动或使用 查看全部、代码开头 或 代码结尾 会暂停自动跟随。新内容和窗口大小变化会保留你的阅读位置,当空间变小时将文本或图像移入视野。调整空闲对话的大小使所有内容适配时,会恢复跟随。聊天标题中的 跳转到最新 会恢复跟随;它仅在新内容位于可见历史下方时出现,并且不会覆盖消息。
- Mermaid 代码块会在结束围栏到达或回复完成后渲染为图表。轻点图表可打开全屏视图,支持双指缩放和平移。角落的小控件可复制源码,或打开菜单在图表和源码之间切换。渲染可离线使用捆绑资源。失败的图表会保留可读源码,临时失败会提供重试。其他代码块语言仍保持为代码。
- 线程活动:搜索结果和侧边栏行使用每个线程自身报告的活动状态。非活动运行不会仅因为其最后状态为运行中或排队中就保留工作指示器或排队指示器。
- 会话选择:在应用运行期间,每个 Gateway 和代理都会记住你最后明确选择的聊天。返回某个代理时,如果目标聊天不在最近页面中,会直接检查该较早聊天;临时查找失败会显示错误,但不会忘记该选择。
- 归档当前打开的会话只有在同一会话仍被选中时才会返回应用的主聊天。在归档完成期间切换会话、代理或 Gateway 会保留你较新的选择。归档成功后,即使错过其推送通知,也会使被归档聊天的记忆选择失效。
- 侧边栏中的 新建 会为所选代理创建并选择一个独立聊天,而不清除之前的会话。它会保留现有的模型/提供商、思考和 Fast Mode 继承行为,同时单独显示在线程中,而不是显示在之前的聊天或主页下方。现有的普通新建聊天也会独立显示,即使旧版应用曾将之前的聊天记录为它们的父级;它们的历史记录和存储设置不会改变。分支、子代理、显式 worktree 启动以及没有创建元数据的会话会保留其嵌套关系。侧边栏和聊天标题会在创建和初始加载期间显示进度,重复的新建操作会被禁用。历史记录刷新不会取消创建;在创建完成期间选择其他会话、代理或 Gateway 会保留该较新的选择。
- 离线历史记录:缓存的转录会按照实时历史记录被接受的顺序更新,因此延迟的重连健康检查无法恢复较旧的快照。切换会话会保留你离开的那个会话的排队缓存更新。
- 聊天操作中的 刷新聊天 会重新加载历史记录并重新检查 Gateway 健康状态,而不清除待处理消息。聊天就绪状态与 Gateway 连接状态是分开的:空连接线程在健康状态未确认或检查失败时显示 聊天未就绪。使用 刷新聊天 可再次检查;Gateway 离线 表示 Gateway 已断开连接。历史记录失败不会阻止后续健康检查。一旦 Android 观察到已恢复的运行结束,延迟的历史记录响应不会恢复该运行的停止按钮或部分回复。
- 发送:
chat.send。在活跃 Talk 会话之外,你可以在代理工作时发送文本或已暂存的附件。新草稿会重新显示 发送;清除草稿会恢复 停止。Gateway 会应用现有的 队列模式,因此转向不需要停止当前运行。当另一个提交、附件暂存或麦克风采集占用草稿时,发送保持禁用。 - 排队消息控件:删除 会移除本地排队副本,包括重连刷新仍在完成时。它不会撤销 Gateway 已接受的消息;使用 停止 取消活动轮次。
- 持久发送:每次发送(文本、所选图像和语音笔记)在任何网络尝试之前都会记录到每个 Gateway 的设备端发件箱中,因此应用终止不会丢失已提交的输入。离线期间排队的发送会在重连时按顺序投递,并使用稳定的幂等键;只有当该轮次在规范
chat.history中可见后,发送才会被移除——仅确认不被视为投递证明。已确认的重连发送会显示与在线发送相同的流式进度;从未到达套接字队列的请求会保持排队,等待下一次连接。模糊结果(确认丢失、发送中途应用被杀死、Gateway 在转录写入前重启)会显示为可见行,并提供明确的 重试/删除,而不是自动重发。如果刷新后的历史记录改变了分支,之前排队的输入会保留其文本和附件,但需要显式重试;在该历史记录显示后接受的输入在重连到同一分支时可以正常发送。斜杠命令绝不会在重连时自动重放;它们会暂停等待显式重试。队列有上限(每个 Gateway 50 条消息和 48 MB 附件字节),未发送的行在 48 小时后过期。从未提交的编辑器草稿不具备进程持久性。 - 完成的回答会显示最多八个紧凑来源卡片,用于该次运行中成功网页搜索和抓取找到的引用页面。轻点卡片可查看其记录的搜索摘要或页面摘录并打开来源。这些卡片不会抓取页面内容;网站图标通过 Gateway 提供,并遵循
gateway.controlUi.automaticallyFetchFavicons,禁用或不可用时显示地球图标。 - 图像输入可通过选择器和 Android Sharesheet 使用。发送的照片位于你的文本气泡上方;相邻照片会换行成紧凑行。助手照片会按消息顺序保留在相关文本旁边。轻点照片可打开全屏预览。消息一次最多显示四个图像预览;下一张图片 和 上一张图片 可访问其余图片,而不会将所有已解码图像保留在内存中。助手生成的图像通过配对的 Gateway 连接解析,并在离线转录缓存中仅保留其小型工件引用。下载上限为 12 MiB,并解码为有界显示位图。
- 推送更新(尽力而为):
chat.subscribe->event:"chat" - 收听:长按助手消息并选择 收听 即可收听;音频通过 Gateway
tts.speak使用已配置的 TTS 提供商链渲染,当 Gateway 无法渲染音频时使用设备端系统 TTS。播放会在会话切换、新聊天、应用进入后台或聊天关闭时停止。
反应¶
已保存的提示词和助手回复会显示带计数和反应者名称的表情反应标签,并突出显示您自己的反应。轻点标签可切换您的反应,或长按消息(包括仅包含媒体的消息)并选择添加反应。快速面板与控制 UI 一致;更多…接受一个表情,包括组合表情和旗帜。控件遵循 Gateway 的操作员和会话共享权限;只读查看者仍可查看反应。在对话打开期间,更新会实时显示,并且不会创建通知。参见反应。
聊天中的代理浏览器¶
当 Browser 插件返回可识别的标签页时,聊天会在代理浏览器下显示该会话最新浏览器标签页的预览。轻点向上箭头可在不离开对话或不替换草稿的情况下进行交互。向下箭头或 Android 返回键会返回预览。收起会关闭浏览器的键盘,但不会更改您的聊天草稿。在您的浏览器中打开是一个单独的显式操作。 普通网站链接和桌面保持现有行为。
关闭图标会将卡片从聊天中移除,而不会关闭代理的远程标签页。要恢复它,请选择聊天操作 > 代理浏览器。刷新相同的浏览器结果不会重新打开已关闭的卡片;新的浏览器工具展示可以再次显示它。即使浏览器离线或不可用,也可以关闭。
预览使用已连接的 Gateway 以及工具结果中确切的浏览器配置文件、主机或节点和标签页。它绝不会启动另一个浏览器或替换为不同的标签页。切换会话或 Gateway 会替换查看器;离线会移除其控件,直到连接恢复。已停止或已关闭的远程标签页会保持不可用,而不是创建替代项。
这使用 Gateway 现有的 Browser 面板和 operator.admin 浏览器权限。已连接的 Gateway 必须声明支持浏览器焦点,并使用其捆绑的 Control UI。旧版 Gateway、已禁用的 Control UI 和自定义 UI 根会显示不可用通知,而不是加载不支持的页面;请更新 Gateway 并使用其捆绑的 UI 以启用嵌入式控制。卡片仍可关闭。不会创建额外的浏览器服务或会话共享权限。
7. 相机¶
相机命令(仅限前台;受权限控制):camera.snap(jpg)、camera.clip(mp4)。参数和 CLI 辅助工具参见相机节点。
8. 语音 + 扩展的 Android 命令界面¶
- 通过侧边栏的页面菜单进行导航。语音输入属于聊天输入框;没有单独的语音选项卡。
- 轻点输入框中的麦克风,使用设备端语音识别,将转录文本插入草稿。监听期间,停止图标会替换麦克风;轻点它可结束监听。在启动或转录期间,关闭图标会取消该次尝试。长按麦克风可打开语音选项,然后选择录制语音留言以创建附件。UI 会报告识别不可用、缺少权限、忙碌/网络故障以及未检测到语音的结果,而不是静默丢弃该次尝试。如果听写不可用且已选择 Gateway,录制语音留言会在保留草稿的情况下提供新的录音。它不会从失败的听写尝试中恢复语音,也不会自动发送任何内容。
- 要启动连续通话,请在草稿为空且没有活动运行的情况下轻点末尾的通话按钮。麦克风菜单仅包含听写和语音留言。听写、语音留言录制和通话是互斥的麦克风路径。
- 当同一 Gateway 重新连接时,您选择的代理会保持绑定到通话和主聊天,包括其代理列表刷新期间。移除该代理会回退到 Gateway 默认值。切换 Gateway 或重启应用会清除此内存中的选择。
- 通话模式会在捕获开始前将现有前台服务从
connectedDevice提升为connectedDevice|microphone,然后在通话模式停止时将其降级。节点服务声明了带有CHANGE_NETWORK_STATE的FOREGROUND_SERVICE_CONNECTED_DEVICE;Android 14+ 还要求声明FOREGROUND_SERVICE_MICROPHONE、授予RECORD_AUDIO运行时权限,以及在运行时使用麦克风服务类型。 - 默认情况下,Android 通话使用原生语音识别、Gateway 聊天,并通过已配置的 Gateway 通话提供商使用
talk.speak。它会继承会话的思考设置。仅当talk.speak不可用时,才使用本地系统 TTS。 - Gateway 配置更改会在下次使用时刷新 Android 缓存的通话设置,而不会重新连接或中断活动捕获。
- 仅当
talk.realtime.mode为realtime且talk.realtime.transport为gateway-relay时,Android 通话才使用实时 Gateway 中继。 - 启用设置 → 语音 → 监听唤醒词,以在前台使用设备端语音唤醒。仅当已启用、设备端识别和麦克风权限可用,并且唤醒词已与当前 Gateway 同步时,Android 才会声明
voiceWake。 - 其他 Android 命令族(可用性取决于设备、权限和用户设置):
device.status、device.info、device.permissions、device.health- 仅当启用设置 → 手机功能 → 已安装应用时,
device.apps才可用;默认列出启动器可见的应用(传入includeNonLaunchable以获取完整列表)。 notifications.list、notifications.actions(参见下文通知转发)photos.latestcontacts.search、contacts.addcalendar.events、calendar.addcallLog.searchsms.searchmotion.activity、motion.pedometer
9. 工作区文件(只读)¶
打开侧边栏页面菜单中的概览,找到文件卡片。它通过只读的 agents.workspace.list / agents.workspace.get Gateway RPC 浏览活动代理的工作区:目录逐级浏览、文本和图片预览,以及通过 Android 共享面板导出。没有写入操作,并且预览大小受 Gateway 限制。
如果应用无法准备文件或打开共享面板,它会显示无法共享文件,并保持预览打开,以便你重试或返回。
审查命令审批¶
具有 operator.admin 的操作员连接,或被 Gateway 明确指定的配对 operator.approvals 连接,可以在设置 -> 审批下审查待处理的 exec 请求。应用会在启用按钮之前加载 Gateway 的已清理审批记录,显示任何安全警告以及该请求提供的确切决策,并将审批 ID 和所有者类型提交回 Gateway。
审批状态与 Control UI 和受支持的聊天界面共享。第一个已提交的回答生效;即使另一个界面先回答,Android 也会显示该规范结果。如果 resolve 响应丢失或 Gateway 断开连接,应用会保持操作锁定,并在提供另一个决策之前重新读取审批。
早于统一审批方法的 Gateway 会回退到随附的 exec 专用方法。待处理审查仍然可用,但保留的终端状态和更丰富的跨界面结果需要更新的 Gateway。
回答智能体问题¶
对于具有 operator.questions(或 operator.admin)的操作员连接,聊天会将待处理的 Gateway 问题显示为原生卡片。卡片支持单选和多选选项、选项描述、自由文本其他回答以及过期倒计时。重新连接会从 Gateway 重新加载待处理问题。当此设备回答该问题、另一个界面先回答,或问题过期或被取消时,卡片会锁定。
机密回答字段会遮蔽输入或粘贴的值,并请求禁用自动更正的密码输入。Android 提交机密回答时不会修剪前导或尾随空白。
助手入口¶
Android 支持从系统助手触发器(Google Assistant)启动 OpenClaw。按住主屏幕按钮(或其他 ACTION_ASSIST 触发器)会打开应用;说出“Hey Google, ask OpenClaw <prompt>”会匹配应用声明的 App Actions 查询模式,并将提示传入聊天输入框而不自动发送。
这使用在应用清单中声明的 Android App Actions(shortcuts.xml 能力)。无需 Gateway 端配置——助手意图完全由 Android 应用处理。
Note
App Actions 的可用性取决于设备、Google Play Services 版本,以及用户是否已将 OpenClaw 设置为默认助手应用。
通知转发¶
Android 可以将设备通知作为 node.event 项转发到 Gateway。这是在设备上配置的,位于应用的设置面板中——而不是在 Gateway/openclaw.json 配置中。
| 设置 | 描述 |
|---|---|
| 转发通知事件 | 主开关。默认关闭;需要先授予通知监听器访问权限。 |
| 包过滤器 | 允许列表(仅转发列出的包 ID)或阻止列表(默认:除列出的 ID 外所有包)。在阻止列表模式下,OpenClaw 自身的包始终被排除,以防止转发循环。 |
| 免打扰时段 | 本地 HH:mm 开始/结束窗口,用于抑制转发。默认禁用;启用后默认为 22:00-07:00。 |
| 每分钟最大事件数 | 每个设备转发通知的速率限制。默认 20。 |
| 路由会话密钥 | 可选。将转发的通知事件固定到特定会话,而不是设备的默认通知路由。 |
Note
通知转发需要 Android 通知监听器权限。应用会在设置过程中提示此权限。
WhatsApp、WhatsApp Business、Telegram、Telegram X、Discord 和 Signal 的通知始终被排除。它们的消息已由原生 OpenClaw 频道会话拥有;将 Android 通知作为单独的节点事件转发可能会将回复路由到错误的对话。
相关¶
- iOS 应用
- 节点
- Android 节点故障排查
- 稳定 HTTPS URL — 使用 Tailscale Serve 为仅限回环的 Gateway 提供稳定的、仅限 tailnet 的 HTTPS URL
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw