OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Platforms overview

Android 應用程式

支援概況

系統控制（launchd/systemd）位於閘道主機上——請參閱閘道。

在 Google Play 以外安裝

一般正式版與修正版 GitHub Releases 會包含通用的 OpenClaw-Android.apk 與 OpenClaw-Android-SHA256SUMS.txt。APK 由發行標籤建置、使用 OpenClaw Android 發行金鑰簽署，並附有 GitHub Actions 來源證明。

選擇同時列出這兩項資產的發行版本，然後在側載前下載並驗證該確切標籤：

bash
release_tag=vYYYY.M.PATCHgh release download "$release_tag" \  --repo openclaw/openclaw \  --pattern OpenClaw-Android.apk \  --pattern OpenClaw-Android-SHA256SUMS.txtsha256sum --check OpenClaw-Android-SHA256SUMS.txtgh 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

scrcpy 會將 Android 畫面鏡像到 macOS 視窗中，並透過 Android Debug Bridge（ADB）轉送鍵盤與指標輸入。這是操作端的工作流程，與 OpenClaw 節點連線彼此獨立。當 Android 裝置與 Mac 位於不同地點，但共用私人 Tailscale 網路時，這項功能很實用。

開始之前

  • 在 Android 裝置與 Mac 上安裝 Tailscale，並將兩者連線至同一個 tailnet。

  • 在 Android 上啟用 Developer options 與 USB debugging。Android 16 將 Wireless debugging 放在 Settings > System > Developer options 下。請參閱 Android 開發人員 選項。

  • 在 Mac 上安裝 scrcpy 與 ADB：

    bash
    brew install scrcpybrew install --cask android-platform-tools

  • 第一次連線時，請讓 Android 裝置保持可操作狀態。每台 Mac 必須先讓 Android 核准其 ADB 金鑰，才能控制該裝置。

啟用透過 TCP 的 ADB

初始設定時，請透過 USB 將 Android 裝置連接至受信任的電腦，並核准其偵錯提示。接著執行：

bash
adb devicesadb tcpip 5555

現在可以拔除 USB。如果裝置重新啟動或重設偵錯後，連接埠 5555 不再監聽，請重複此本機設定步驟。Android 11 及更新版本也可以使用 Wireless debugging > Pair device with pairing code 與 adb pair 建立初始信任。

僅允許控制端 Mac

採用限制性授權規則的 tailnet，必須明確允許控制端 Mac 存取 Android 裝置上的 TCP 連接埠 5555。請將一條精確限制的規則新增至 tailnet 原則，並以兩台裝置的穩定 Tailscale IP 取代範例位址：

json5
{  grants: [    {      src: ["<remote-mac-tailnet-ip>"],      dst: ["<android-tailnet-ip>"],      ip: ["tcp:5555"],    },  ],}

如需主機別名與其他選取器，請參閱 Tailscale grants。請勿將此連接埠開放給公用網際網路，也不要使用 Funnel 公開它：獲授權的 ADB 用戶端能廣泛控制裝置。

連線並開始鏡像

在遠端 Mac 上：

bash
adb connect <android-tailnet-ip>:5555adb devicesscrcpy --serial <android-tailnet-ip>:5555

第一次從這台 Mac 執行 adb connect 時，Android 上會顯示授權對話框。解除鎖定裝置、確認金鑰指紋，並且僅在信任該 Mac 時選取 Always allow from this computer。成功的 adb devices 項目會以 device 結尾；unauthorized 表示尚未核准裝置上的提示。

scrcpy 視窗開啟後，可直接使用，或透過 Peekaboo 等 macOS 螢幕自動化工具指定該視窗。scrcpy 負責傳輸顯示畫面與輸入；Tailscale 僅提供私人網路路徑。

疑難排解

  • Connection timed out：確認 tailnet 授權規則允許 TCP 5555。tailscale ping 成功只能證明對等端可達，不能證明原則允許此 TCP 連接埠。請在 Mac 上使用 nc -vz <android-tailnet-ip> 5555 測試。
  • unauthorized：解除鎖定 Android 並核准遠端 Mac 的 ADB 金鑰，或在 Wireless debugging > Paired devices 下移除過時的工作站，然後重新配對。
  • Connection refused：在本機重新連線，並再次執行 adb tcpip 5555。
  • 列出多台裝置：保留明確的 --serial <android-tailnet-ip>:5555 引數。

完成後，關閉 scrcpy 並中斷 ADB 連線：

bash
adb disconnect <android-tailnet-ip>:5555

連線操作手冊

Android 節點應用程式 ⇄（mDNS/NSD + WebSocket）⇄ 閘道

Android 會直接連線至閘道 WebSocket，並使用裝置配對（role: node）。

對於 Tailscale 或公用主機，Android 需要安全端點：

  • 建議：使用 Tailscale Serve / Funnel 搭配 https://<magicdns> / wss://<magicdns>
  • 亦支援：任何其他具有真正 TLS 端點的 wss:// 閘道 URL
  • 明文 ws:// 仍支援私人區域網路位址／.local 主機，以及 localhost、127.0.0.1 和 Android 模擬器橋接位址（10.0.2.2）

先決條件

  • 閘道在另一台機器上執行（或可透過 SSH 存取）。
  • Android 裝置／模擬器可以連線至閘道 WebSocket：
    • 位於同一個區域網路，並使用 mDNS/NSD，或
    • 位於同一個 Tailscale tailnet，並使用廣域 Bonjour／單點傳播 DNS-SD（請見下文），或
    • 手動指定閘道主機／連接埠（備援方式）
  • tailnet／公用行動裝置配對不會使用原始 tailnet IP 的 ws:// 端點。請改用 Tailscale Serve 或其他 wss:// URL。
  • 閘道機器上（或透過 SSH）必須可使用 openclaw 命令列介面，以核准配對要求。

1. 啟動閘道

bash
openclaw gateway --port 18789 --verbose

確認記錄中出現類似以下內容：

  • listening on ws://0.0.0.0:18789

若要讓遠端 Android 透過 Tailscale 存取，建議使用 Serve/Funnel，而不是直接繫結原始 tailnet：

bash
openclaw gateway --tailscale serve

這會為 Android 提供安全的 wss:// / https:// 端點。除非你另外終止 TLS，否則僅設定 gateway.bind: "tailnet" 並不足以進行第一次遠端 Android 配對。

2. 驗證探索（選用）

在閘道機器上：

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

更多偵錯說明：Bonjour。

如果你也設定了廣域探索網域，可與以下輸出比較：

bash
openclaw gateway discover --json

這會一次顯示 local. 與已設定的廣域網域，並使用解析後的服務端點，而不是僅使用 TXT 提示。

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

Android NSD/mDNS 探索無法跨越網路。如果 Android 節點與閘道位於不同網路，但透過 Tailscale 連線，請改用廣域 Bonjour／單點傳播 DNS-SD。僅有探索並不足以進行 tailnet／公用 Android 配對——探索到的路由仍需安全端點（wss:// 或 Tailscale Serve）：

  1. 在閘道主機上設定 DNS-SD 區域（例如 openclaw.internal.），並發布 _openclaw-gw._tcp 記錄。
  2. 為所選網域設定 Tailscale 分割 DNS，並將其指向該 DNS 伺服器。

詳細資訊與 CoreDNS 設定範例：Bonjour。

3. 從 Android 連線

在 Android 應用程式中：

  • 應用程式會透過前景服務（常駐通知）維持閘道連線。
  • 開啟 Connect 分頁。
  • 使用 Setup Code 或 Manual 模式。
  • 如果探索遭到封鎖，請在 Advanced controls 中手動指定主機／連接埠。對於私人區域網路主機，ws:// 仍可使用。對於 Tailscale／公用主機，請開啟 TLS 並使用 wss:// / Tailscale Serve 端點。

第一次成功配對後，Android 會在啟動時自動重新連線至目前使用中的已配對閘道（對探索到的閘道採盡力而為模式，且該閘道必須可在網路上被偵測到）。

多個閘道

應用程式會保留所有已配對閘道的登錄資料，因此你可以在不重新配對的情況下切換：

  • Settings -> Gateways 會列出已配對的閘道，並標示目前使用中的閘道。點選項目即可切換；應用程式會終止目前的工作階段，並重新連線至所選閘道。
  • 配對超過一個閘道時，Connect 分頁會顯示快速切換器。
  • 認證資訊、裝置權杖、TLS 信任、聊天記錄和排入佇列的離線訊息會依閘道分別儲存。切換時絕不會混用不同閘道的狀態，離線時排入佇列的訊息也只會傳送至其原本要傳送的閘道。
  • Forget 會移除閘道的登錄項目，以及其認證資訊、裝置權杖、TLS 釘選與快取的聊天內容。

存在狀態存活信標

經過驗證的節點工作階段連線後，以及應用程式移至背景但前景服務仍保持連線時，Android 會使用 event: "node.presence.alive" 呼叫 node.event。只有在得知經驗證的節點裝置身分後，閘道才會將此資訊記錄為已配對節點／裝置中繼資料的 lastSeenAtMs/lastSeenReason。

只有在閘道回應包含 handled: true 時，應用程式才會將信標視為已成功記錄。較舊的閘道可能會以 { "ok": true } 確認 node.event；此回應相容，但不會計為持久的最後上線時間更新。

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

在閘道機器上：

bash
openclaw devices listopenclaw 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 statusopenclaw gateway call node.list --params "{}"

6. 聊天 + 記錄

Android 的 Chat 分頁支援選取工作階段（預設為 main，以及其他現有工作階段）：

  • 歷史記錄：chat.history（已針對顯示正規化——會移除行內指令標籤、純文字工具呼叫 XML 承載資料（<tool_call>、<function_call>、<tool_calls>、<function_calls> 及其截斷變體），以及外洩的 ASCII／全形模型控制權杖；會省略精確為 NO_REPLY／no_reply 等靜默權杖的助理資料列；過大的資料列可能會以預留位置取代）
  • 傳送：chat.send
  • 持久傳送：每次傳送（文字、選取的圖片和語音留言）都會在任何網路嘗試前，記錄到各閘道的裝置端寄件匣中，因此即使應用程式終止，也不會遺失已提交的輸入。離線時排入佇列的傳送項目會在重新連線後依序送出，並使用穩定的等冪鍵；只有當該回合出現在標準 chat.history 中後，才會移除傳送項目——僅收到確認並不視為已送達的證明。結果不明確時（確認遺失、應用程式在傳送途中遭終止、閘道在寫入逐字記錄前重新啟動），會顯示可見的資料列並提供明確的重試／刪除選項，而不會自動重新傳送。斜線命令絕不會在重新連線後自動重播；它們會暫停，等待明確重試。佇列設有上限（每個閘道 50 則訊息及 48 MB 的附件位元組），未傳送的資料列會在 48 小時後到期。從未提交的編寫器草稿不會跨程序持久保存。
  • 推播更新（盡力而為）：chat.subscribe -> event:"chat"
  • 聆聽：長按助理訊息並選擇聆聽即可播放；音訊會透過閘道 tts.speak，使用已設定的 TTS 提供者鏈進行算繪；當閘道無法算繪音訊時，則使用裝置端系統 TTS。切換工作階段、開始新聊天、應用程式進入背景或關閉聊天時，播放都會停止。

7. 畫布 + 相機

閘道畫布主機（建議用於網頁內容）

若要讓節點顯示代理程式可在磁碟上編輯的實際 HTML/CSS/JS，請將節點指向閘道畫布主機。

  1. 在閘道主機上建立 ~/.openclaw/workspace/canvas/index.html。
  2. 將節點導覽至該位置（區域網路）：
bash
openclaw nodes invoke --node "&lt;Android Node&gt;" --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.eval、canvas.snapshot、canvas.navigate（使用 {"url":""} 或 {"url":"/"} 返回預設鷹架）。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 有兩種明確的擷取模式。Mic 是手動啟動的語音分頁工作階段，會將每次停頓作為一個聊天回合傳送，並在應用程式離開前景或使用者離開語音分頁時停止。Talk 是持續式對話模式，會持續聆聽，直到將其關閉或節點中斷連線。
  • 對話模式會在擷取開始前，將現有前景服務從 connectedDevice 提升為 connectedDevice|microphone，並在對話模式停止時將其降級。節點服務會使用 CHANGE_NETWORK_STATE 宣告 FOREGROUND_SERVICE_CONNECTED_DEVICE；Android 14+ 還需要 FOREGROUND_SERVICE_MICROPHONE 宣告、RECORD_AUDIO 執行階段授權，以及執行階段的麥克風服務類型。
  • Android 對話預設使用原生語音辨識、閘道聊天，以及透過已設定之閘道對話提供者執行的 talk.speak。僅當 talk.speak 無法使用時，才會使用本機系統 TTS。
  • 僅當 talk.realtime.mode 為 realtime，且 talk.realtime.transport 為 gateway-relay 時，Android 對話才會使用即時閘道中繼。
  • Android 不會公告 voiceWake 功能。請使用 Mic 或 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. 工作區檔案（唯讀）

首頁概覽包含一張檔案卡片，可透過唯讀的 agents.workspace.list／agents.workspace.get 閘道 RPC 瀏覽作用中代理程式的工作區：可逐層瀏覽目錄、預覽文字與圖片，並透過 Android 分享介面匯出。不提供任何寫入操作，且閘道會限制預覽大小。

檢閱命令核准

具有 operator.admin 的操作者連線，或由閘道明確指定目標的已配對 operator.approvals 連線，可以在 Settings -> Approvals 下檢閱 待處理的執行要求。應用程式會先載入閘道已清理的核准記錄，再啟用其按鈕，顯示所有 安全性警告及該要求所提供的確切決策，並將 核准 ID 和擁有者種類提交回閘道。

核准狀態會與控制介面及支援的聊天介面共用。 第一個提交的答案生效；即使其他介面先回答，Android 仍會顯示該標準結果。 如果解析回應遺失或閘道中斷連線， 應用程式會維持動作鎖定，並再次讀取核准， 之後才提供其他決策。

早於統一核准方法的閘道會退回使用已發布的 執行專用方法。待處理檢閱仍可運作，但保留的終端機狀態 及更豐富的跨介面結果需要更新版閘道。

助理進入點

Android 支援從系統助理觸發器（Google Assistant）啟動 OpenClaw。長按首頁按鈕（或其他 ACTION_ASSIST 觸發器）會開啟應用程式；說出 "Hey Google, ask OpenClaw <prompt>" 時，會符合應用程式宣告的 App Actions 查詢模式，並將提示詞帶入聊天編寫器，但不會自動傳送。

這會使用應用程式資訊清單中宣告的 Android App Actions（shortcuts.xml 功能）。不需要任何閘道端設定——助理意圖完全由 Android 應用程式處理。

通知轉送

Android 可將裝置通知作為 node.event 項目轉送至閘道。此功能是在應用程式的設定面板中，於裝置上進行設定，而不是在閘道／openclaw.json 設定中。

設定 說明
Forward Notification Events 主開關。預設關閉；必須先授予 Notification Listener Access。
Package Filter Allowlist（僅轉送列出的套件 ID）或 Blocklist（預設：轉送所有套件，但列出的 ID 除外）。在 Blocklist 模式下，一律排除 OpenClaw 自身的套件，以防止轉送迴圈。
Quiet Hours 停止轉送的本機 HH:mm 開始／結束時段。預設停用；啟用後預設為 22:00-07:00。
Max Events / Minute 每部裝置轉送通知的速率限制。預設為 20。
Route Session Key 選用。將轉送的通知事件固定送入特定工作階段，而非裝置的預設通知路由。

一律排除 WhatsApp、WhatsApp Business、Telegram、Telegram X、Discord 和 Signal 通知。這些訊息已由 OpenClaw 原生頻道工作階段管理；將 Android 通知作為獨立節點事件轉送，可能會使回覆被路由至錯誤的對話。

相關內容

Was this useful?
On this page

On this page