ClawPaw Setup Guide

Walk the user through the complete setup step by step. Check each step before proceeding to the next. Use the scripts in the scripts/ directory to automate checks.

Step 1 — Check Prerequisites

Run the adb check script:

CODEBLOCK0

If STATUS:NO_ADB: guide user to install adb, then re-run.
If STATUS:NO_DEVICE: guide user to connect USB and enable USB Debugging.
If STATUS:DEVICE_FOUND: proceed to Step 2.

Step 2 — Install APK

Ask the user if the ClawPaw app is already installed on the phone.

If not installed, build and install via adb:
CODEBLOCK1

Or guide the user to install manually from Android Studio (Run button).

After install, ask the user to:

1. 1. Open the ClawPaw app
2. Tap Connect
3. Wait for Backend connection and SSH tunnel to show green dots

Step 3 — Grant Permissions (USB connected)

Run the permissions script:

CODEBLOCK2

This grants 3 permissions:

• - WRITESETTINGS — brightness control
• WRITESECURE_SETTINGS — auto-enable accessibility service
• adb tcpip 5555 — enable wireless ADB over SSH tunnel

Then ask the user to check the phone for any permission dialogs and tap Allow.

Step 4 — Verify SSH Tunnel

Ask the user to open the ClawPaw app and confirm both rows show a green dot:

• - Backend connection (WebSocket)
• SSH tunnel (SSH reverse tunnel)

If SSH tunnel shows Disconnected or Error:

• - Tap the Retry button next to the SSH tunnel status
• If still failing, restart the app

Step 5 — Connect ADB (first time or after Pod restart)

Get the user's UID and Secret from the ClawPaw app main screen, then run:

CODEBLOCK3

If output shows failed to authenticate:

• - Tell user to look at the phone screen for an "Allow USB debugging?" dialog
• Tap Always allow from this computer, then OK
• Run the script again

If output shows already connected or connected to: proceed.

Step 6 — End-to-End Verification

Run these curl commands with the user's credentials to confirm the full chain works:

CODEBLOCK4

Read /tmp/phone_screen.png and show it to the user to confirm.

Step 7 — Configure MCP (optional)

To use ClawPaw tools directly in Claude Code (snapshot, tap, screenshot, etc.), add to ~/.claude.json:

CODEBLOCK5

Then restart Claude Code.

Troubleshooting

Error	Cause	Fix
INLINECODE9	ADB TCP mode not set	Re-run Step 3 with USB connected
INLINECODE10

USB debugging (Security settings) not enabled | Settings → Developer Options → USB debugging (Security settings) → ON | | WRITE_SETTINGS not granted | Step 3 was skipped | Run grant-permissions.sh with USB connected | | SSH: Disconnected | MIUI killed the service | Settings → Battery → ClawPaw → No restrictions; lock app in recents | | failed to authenticate | New adb server, phone needs to approve | Check phone for Allow USB debugging dialog | | Screenshot is black | Screen is off | Press power key first, or adb shell input keyevent KEYCODE_WAKEUP |