Appium Android Bridge

Generic Appium bridge for any Android app. Reads screens as structured JSON, executes taps/scrolling/typing via accessibility service clicks (bypasses WebView touch filtering).

Quick Start

# Once per session (28s, starts Appium + daemon):
bash ~/.openclaw/workspace/skills/appium-android-adb/start_bridge.sh

# Then every action (~1-2s each):
python3 ~/.openclaw/workspace/skills/appium-android-adb/bridge_daemon.py dump
python3 ~/.openclaw/workspace/skills/appium-android-adb/bridge_daemon.py tap '{"text": "查询"}'
python3 ~/.openclaw/workspace/skills/appium-android-adb/bridge_daemon.py scroll '{"direction": "down"}'

Commands

All from ~/.openclaw/workspace/skills/appium-android-adb/. All return JSON.

dump — read the screen

python3 bridge_daemon.py dump

Returns:

{
  "ok": true,
  "package": "com.example.app",
  "activity": "...",
  "title": "...",
  "alerts": [{"text": "温馨提示"}],
  "buttons": [{"text": "查询", "id": "btn_search", "bounds": "[99,750][981,882]"}],
  "trains": [{"text": "...", "bounds": "...", "clickable": true}],
  "webview_contexts": ["NATIVE_APP"]
}

• buttons[] — all clickable elements with text, id, bounds
• alerts[] — dialogs/popups needing dismissal
• trains[] — elements containing "次列车" (app-agnostic; rename for other apps)
• title — page title if present

tap — click an element

python3 bridge_daemon.py tap '{"text": "查询车票"}'       # by text (substring match)
python3 bridge_daemon.py tap '{"text": "预订", "index": 0}' # first match
python3 bridge_daemon.py tap '{"id": "btn_submit"}'         # by resource-id

scroll — swipe the screen

python3 bridge_daemon.py scroll '{"direction": "down"}'               # normal
python3 bridge_daemon.py scroll '{"direction": "down", "distance": "short"}' # fine
python3 bridge_daemon.py scroll '{"direction": "up"}'                 # go back

Uses fast drag (100ms) — works best for WebView content.

type — input text

python3 bridge_daemon.py type '{"text": "上海"}'

wait — poll until element appears

python3 bridge_daemon.py wait '{"text": "提交订单", "timeout": 30}'

When to Use This

Use appium-android-adb when:

• The app uses WebView (ADB taps are ignored)
• You need structured screen reading (not screenshot-based)
• You need reliable element clicking (accessibility service, not raw touch)
• You're automating a hybrid app (native + WebView)

Do NOT use for:

• Simple native-only apps where adb shell input tap works fine
• One-off screenshots (use adb shell screencap)

Troubleshooting

Daemon died: Run start_bridge.sh again to restart. Device not found: Check USB connection: adb devices App not launching: The daemon attaches to the running app. Cold-start the app manually if needed: adb shell monkey -p \x3Cpackage> 1