跳轉到主要內容
官方 Android 應用程式可在 Google Play 取得。它是伴隨節點，需要執行中的 OpenClaw 閘道。來源：apps/android（建置說明）。

​
支援快照

  • 角色：伴隨節點應用程式（Android 不代管閘道）。
  • 需要閘道：是（透過 WSL2 在 macOS、Linux 或 Windows 上執行）。
  • 安裝：應用程式請見 Google Play，閘道請見開始使用，接著見配對。
  • 閘道：執行手冊 + 設定。
系統控制（launchd/systemd）位於閘道主機上 — 請見閘道。

​
從遠端 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： 
    brew install scrcpy
brew install --cask android-platform-tools
  • 第一次連線時，請讓 Android 裝置保持可用。Android 必須核准每台 Mac 的 ADB 金鑰，該 Mac 才能控制裝置。

​
透過 TCP 啟用 ADB

初始設定時，請透過 USB 將 Android 裝置連接到受信任的電腦，並核准其偵錯提示。接著執行： 
adb devices
adb tcpip 5555
現在可以中斷 USB 連線。如果裝置重新啟動或重設偵錯後，連接埠 5555 停止監聽，請重複此本機設定步驟。Android 11 及更新版本也可以使用無線偵錯 > 使用配對碼配對裝置與 adb pair 建立初始信任。

​
只允許控制端 Mac

採用限制性授權的 tailnet 必須明確允許控制端 Mac 連線到 Android 裝置上的 TCP 連接埠 5555。請在 tailnet 政策中加入窄範圍規則，將範例位址替換成兩台裝置穩定的 Tailscale IP： 
{
  grants: [
    {
      src: ["<remote-mac-tailnet-ip>"],
      dst: ["<android-tailnet-ip>"],
      ip: ["tcp:5555"],
    },
  ],
}
主機別名與其他選擇器請見 Tailscale 授權。不要將此連接埠授權給公開網際網路，也不要使用 Funnel 對外公開：已授權的 ADB 用戶端對裝置具有廣泛控制權。

​
連線並開始鏡像

在遠端 Mac 上： 
adb connect <android-tailnet-ip>:5555
adb devices
scrcpy --serial <android-tailnet-ip>:5555
此 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 連線： 
adb disconnect <android-tailnet-ip>:5555

​
連線執行手冊

Android 節點應用程式 ⇄ (mDNS/NSD + WebSocket) ⇄ 閘道 Android 直接連線到閘道 WebSocket，並使用裝置配對（role: node）。 對於 Tailscale 或公開主機，Android 需要安全端點：
  • 建議：使用 https://<magicdns> / wss://<magicdns> 的 Tailscale Serve / Funnel
  • 也支援：任何其他具有真實 TLS 端點的 wss:// 閘道 URL
  • 明文 ws:// 仍支援私有 LAN 位址 / .local 主機，以及 localhost、127.0.0.1 和 Android 模擬器橋接位址（10.0.2.2）

​
先決條件

  • 閘道在另一台機器上執行（或可透過 SSH 連線）。
  • Android 裝置/模擬器可以連線到 gateway WebSocket：
    • 使用 mDNS/NSD 的同一 LAN，或
    • 使用 Wide-Area Bonjour / 單點傳播 DNS-SD 的同一 Tailscale tailnet（見下方），或
    • 手動 gateway 主機/連接埠（備援）
  • Tailnet/公開行動配對不使用原始 tailnet IP ws:// 端點。請改用 Tailscale Serve 或其他 wss:// URL。
  • gateway 機器上可用的 openclaw 命令列介面（或透過 SSH），用於核准配對請求。

​
1. 啟動閘道

openclaw gateway --port 18789 --verbose
確認日誌中看到類似內容：
  • listening on ws://0.0.0.0:18789
若要透過 Tailscale 讓遠端 Android 存取，建議使用 Serve/Funnel，而不是原始 tailnet 綁定： 
openclaw gateway --tailscale serve
這會為 Android 提供安全的 wss:// / https:// 端點。單純的 gateway.bind: "tailnet" 設定不足以進行首次遠端 Android 配對，除非你也另外終止 TLS。

​
2. 驗證探索（選用）

從 gateway 機器： 
dns-sd -B _openclaw-gw._tcp local.
更多偵錯備註：Bonjour。 如果你也設定了廣域探索網域，請與下列結果比較： 
openclaw gateway discover --json
這會在一次執行中顯示 local. 加上已設定的廣域網域，並使用已解析的服務端點，而不是只使用 TXT 提示。

​
透過單點傳播 DNS-SD 進行跨網路探索

Android NSD/mDNS 探索不會跨越網路。如果 Android 節點與 gateway 位於不同網路但透過 Tailscale 連接，請改用 Wide-Area Bonjour / 單點傳播 DNS-SD。單靠探索不足以進行 tailnet/公開 Android 配對 — 探索到的路由仍需要安全端點（wss:// 或 Tailscale Serve）：
  1. 在 gateway 主機上設定 DNS-SD 區域（範例 openclaw.internal.），並發布 _openclaw-gw._tcp 記錄。
  2. 為你選擇的網域設定 Tailscale split DNS，指向該 DNS 伺服器。
詳細資料與 CoreDNS 設定範例：Bonjour。

​
3. 從 Android 連線

在 Android 應用程式中：
  • 應用程式透過前景服務（持續通知）維持其 gateway 連線。
  • 開啟連線分頁。
  • 使用設定碼或手動模式。
  • 如果探索遭封鎖，請在進階控制項中使用手動主機/連接埠。對於私有 LAN 主機，ws:// 仍可運作。對於 Tailscale/公開主機，請開啟 TLS 並使用 wss:// / Tailscale Serve 端點。
第一次成功配對後，Android 會在啟動時自動重新連線：若啟用則使用手動端點，否則使用最後探索到的 gateway（盡力而為）。

​
存在狀態存活信標

驗證的節點工作階段連線後，以及當應用程式移至背景且前景服務仍連線時，Android 會以 event: "node.presence.alive" 呼叫 node.event。只有在已知驗證節點裝置身分之後，gateway 才會將此記錄為已配對節點/裝置中繼資料上的 lastSeenAtMs/lastSeenReason。 只有當 gateway 回應包含 handled: true 時，應用程式才會將信標計為已成功記錄。較舊的 gateway 可能會以 { "ok": true } 確認 node.event；該回應相容，但不會計為持久的最後可見更新。

​
4. 核准配對（命令列介面）

在 gateway 機器上： 
openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
配對詳細資料：配對。 選用：如果 Android 節點一律從嚴格控管的子網路連線，你可以選擇使用明確 CIDR 或確切 IP 來啟用首次節點自動核准： 
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
這預設為停用。它只適用於沒有請求範圍的新 role: node 配對。操作員/瀏覽器配對，以及任何角色、範圍、中繼資料或公開金鑰變更，仍需要手動核准。

​
5. 驗證節點已連線

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

​
6. 聊天 + 歷史記錄

Android 聊天分頁支援工作階段選取（預設 main，以及其他既有工作階段）：
  • 歷史記錄：chat.history（顯示已正規化 — 會移除內嵌指令標籤、純文字工具呼叫 XML 承載（<tool_call>、<function_call>、<tool_calls>、<function_calls> 與截斷變體），以及洩漏的 ASCII/全形模型控制權杖；會省略靜默權杖助理列，例如精確的 NO_REPLY / no_reply；過大的列可能會以佔位符取代）
  • 傳送：chat.send
  • 推送更新（盡力而為）：chat.subscribe -> event:"chat"

​
7. Canvas + 相機

​
閘道 Canvas 主機（建議用於網頁內容）

若要讓節點顯示代理人可在磁碟上編輯的真實 HTML/CSS/JS，請將節點指向閘道 canvas 主機。
節點會從閘道 HTTP 伺服器載入 canvas（與 gateway.port 相同的連接埠，預設為 18789）。
  1. 在 gateway 主機上建立 ~/.openclaw/workspace/canvas/index.html。
  2. 將節點導覽到該位置（LAN）：
openclaw nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__openclaw__/canvas/"}'
Tailnet（選用）：如果兩台裝置都位於 Tailscale 上，請使用 MagicDNS 名稱或 tailnet IP 取代 .local，例如 http://<gateway-magicdns>:18789/__openclaw__/canvas/。 此伺服器會將即時重新載入用戶端注入 HTML，並在檔案變更時重新載入。閘道也會提供 /__openclaw__/a2ui/，但 Android 應用程式會將遠端 A2UI 頁面視為僅供轉譯。可執行動作的 A2UI 命令會使用隨附的應用程式自有 A2UI 頁面。 Canvas 命令（僅限前景）：
  • canvas.eval、canvas.snapshot、canvas.navigate（使用 {"url":""} 或 {"url":"/"} 返回預設 scaffold）。canvas.snapshot 會回傳 { format, base64 }（預設 format="jpeg"）。
  • A2UI：canvas.a2ui.push、canvas.a2ui.reset（canvas.a2ui.pushJSONL 舊版別名）。這些命令使用隨附的應用程式自有 A2UI 頁面進行可執行動作的轉譯。
相機命令（僅限前景；受權限保護）：camera.snap (jpg)、camera.clip (mp4)。參數與命令列介面輔助工具請見相機節點。

​
8. 語音 + 擴充的 Android 命令介面

  • 語音分頁：Android 有兩種明確的擷取模式。麥克風是手動的語音分頁工作階段，會將每次停頓作為聊天回合傳送，並在應用程式離開前景或使用者離開語音分頁時停止。對話是連續的對話模式，會持續聆聽直到關閉切換或節點中斷連線。
  • 對話模式會在擷取開始前，將現有前景服務從 connectedDevice 提升為 connectedDevice|microphone，然後在對話模式停止時降級。節點服務會以 CHANGE_NETWORK_STATE 宣告 FOREGROUND_SERVICE_CONNECTED_DEVICE；Android 14+ 也需要 FOREGROUND_SERVICE_MICROPHONE 宣告、RECORD_AUDIO 執行階段授權，以及執行階段的麥克風服務類型。
  • 預設情況下，Android 對話使用原生語音辨識、閘道聊天，以及透過已設定的閘道對話提供者使用 talk.speak。只有在 talk.speak 無法使用時，才會使用本機系統 TTS。
  • Android 對話只有在 talk.realtime.mode 為 realtime 且 talk.realtime.transport 為 gateway-relay 時，才會使用即時閘道轉送。
  • 語音喚醒已在原始碼中實作（VoiceWakeMode），但出貨應用程式執行階段在連線時一律強制設為 off，目前沒有面向使用者的切換控制。
  • 其他 Android 指令系列（可用性取決於裝置、權限和使用者設定）：
    • device.status、device.info、device.permissions、device.health
    • 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

​
助理進入點

Android 支援從系統助理觸發器（Google Assistant）啟動 OpenClaw。按住主畫面按鈕（或其他 ACTION_ASSIST 觸發器）會開啟應用程式；說出「Hey Google，詢問 OpenClaw <prompt>」會符合應用程式宣告的 App Actions 查詢模式，並將提示交給聊天撰寫器，而不會自動傳送。 這使用 Android App Actions（shortcuts.xml capability），並在應用程式資訊清單中宣告。不需要任何閘道端設定，助理意圖完全由 Android 應用程式處理。
App Actions 的可用性取決於裝置、Google Play Services 版本，以及使用者是否已將 OpenClaw 設為預設助理應用程式。

​
通知轉送

Android 可以將裝置通知作為 node.event 項目轉送至閘道。這是在裝置上，於應用程式的設定面板中設定，而不是在閘道/openclaw.json 設定中設定。
設定說明
轉送通知事件主切換。預設關閉；必須先授予通知監聽器存取權。
套件篩選器允許清單（只轉送列出的套件 ID）或 封鎖清單（預設：除列出 ID 以外的所有套件）。在封鎖清單模式中，OpenClaw 自己的套件一律會被排除，以避免轉送迴圈。
安靜時段本機 HH:mm 開始/結束時間範圍，會抑制轉送。預設停用；啟用後預設為 22:00-07:00。
每分鐘事件上限每部裝置的轉送通知速率限制。預設 20。
路由工作階段金鑰選用。將轉送的通知事件固定到特定工作階段，而不是裝置的預設通知路由。
通知轉送需要 Android 通知監聽器權限。應用程式會在設定期間提示授予此權限。

​
相關