Frequently Asked Questions

Answers to common questions about PhoneClaw setup, usage, and features

General Questions

What is PhoneClaw?

PhoneClaw is an Android automation app that runs on-device workflows using ClawScript, a JavaScript-based scripting language. It allows you to automate complex multi-app workflows on Android devices using natural language descriptions and vision-assisted UI targeting.

Key features:

• Generate automation scripts at runtime
• Vision-based UI element targeting
• Voice command support
• Cron-based scheduling
• Multi-app workflow chaining

What Android version is required?

PhoneClaw requires Android 7.0 (API level 24) or higher. For best results, we recommend Android 9.0 or newer.

Tested devices:

• Budget phones like Moto G Play ($30) work great
• Most modern Android smartphones and tablets
• Some features may have limitations on older devices

Does PhoneClaw require root access?

No, PhoneClaw does not require root access. It uses Android’s built-in Accessibility Service API, which is available on all non-rooted devices.

You only need to:

• Enable Developer Options (no root needed)
• Grant Accessibility Service permission
• Allow installation from unknown sources for sideloading

Is PhoneClaw free and open source?

Yes! PhoneClaw is completely free and open source under an MIT-style license. You can:

• Use it for personal or commercial purposes
• View and modify the source code
• Contribute improvements back to the project
• Build custom versions for your needs

View the source code on GitHub.

What API keys do I need?

PhoneClaw requires:

• Moondream API token for vision-based UI targeting (magicClicker/magicScraper)

Optional:

• OpenRouter API key for advanced AI model selection
• Email credentials if using sendAgentEmail function

Add your keys to local.properties:

MOONDREAM_AUTH=your_token_here

Installation and Setup

How do I install PhoneClaw?

Installation steps:

1. Download Android Studio and clone the repository
2. Open the project in Android Studio
3. Go to Build > Generate Bundles/APKs > Generate APK
4. Transfer the APK to your Android device
5. Enable “Install from Unknown Sources” in Settings
6. Install the APK
7. Grant Accessibility Service permission when prompted

Alternatively, download pre-built APKs from GitHub releases (when available).

Why can't I find PhoneClaw on Google Play Store?

PhoneClaw is not available on the Google Play Store. It must be sideloaded because:

• It uses advanced Accessibility Service features
• It’s designed for power users and developers
• Open source development model

You can safely sideload the APK by building from source or downloading from official GitHub releases.

How do I enable Accessibility Service?

Steps to enable Accessibility Service:

1. Open Android Settings
2. Navigate to Accessibility (may be under “System” or search for it)
3. Find PhoneClaw in the list of services
4. Toggle it ON
5. Read and accept the permission warning
6. Verify it shows as “ON”

Troubleshooting:

• If PhoneClaw doesn’t appear, reinstall the app
• Some manufacturers hide accessibility settings in different locations
• Disable battery optimization for PhoneClaw to prevent service from stopping

Which budget Android phone should I buy?

Recommended budget option:

• Moto G Play (~$30 USD at Walmart) - used in all demo videos

Minimum specifications:

• Android 7.0 or higher
• 2GB RAM (3GB+ recommended)
• 16GB storage (32GB+ recommended)

What matters:

• Screen size (larger = easier for vision targeting)
• RAM (more = better for multiple apps)
• Battery capacity (for scheduled automations)

Avoid devices with heavy manufacturer customization (some MIUI, EMUI versions) as they may have restrictions.

Using PhoneClaw

How do I create my first automation?

Quick start:

1. Open PhoneClaw
2. Use voice command: “Open Twitter and click the blue post button every hour”
3. PhoneClaw generates a ClawScript automation
4. Review and edit the generated script if needed
5. The automation will run according to the schedule

Or manually write ClawScript:

// Open Twitter
await magicClicker("Twitter app icon");
await delay(2000);

// Click post button
await magicClicker("blue compose button");
speakText("Clicked post button");

// Schedule to run every hour
schedule("twitter-post", "0 * * * *");

See the First Automation Guide for detailed walkthrough.

What is ClawScript?

ClawScript is a JavaScript-based scripting language that runs inside PhoneClaw using an embedded JS engine.

Key features:

• Standard JavaScript syntax
• Helper functions for automation (magicClicker, magicScraper, etc.)
• Direct access to Android Accessibility Service
• Support for async/await
• Runtime script generation and execution

Example:

speakText("Starting automation");
await magicClicker("Login button");
await delay(2000);
const code = await magicScraper("The verification code");
speakText("Code is: " + code);

Learn more in the ClawScript documentation.

How does magicClicker find UI elements?

magicClicker uses vision AI to locate and tap UI elements based on natural language descriptions:

1. Takes a screenshot of the current screen
2. Sends the screenshot and your description to vision AI
3. Vision AI identifies the matching UI element
4. Calculates tap coordinates
5. Uses Accessibility Service to tap the element

Best practices:

• Be specific: “blue login button at bottom” > “button”
• Include visual cues: colors, positions, icons
• Ensure element is visible on screen
• Add delays for UI loading

Example:

await magicClicker("red rectangular submit button at bottom right");

How does magicScraper extract data?

magicScraper uses vision AI to read and extract specific information from the screen:

1. Takes a screenshot
2. Sends screenshot and your question to vision AI
3. AI analyzes the image and extracts the requested information
4. Returns the answer as a string

Use cases:

• Reading verification codes
• Extracting prices or numbers
• Checking status messages
• Reading form values

Example:

const otp = await magicScraper("What is the 6-digit code in the SMS?");
speakText("OTP code: " + otp);

Can PhoneClaw automate apps that block accessibility?

Some apps actively block or limit Accessibility Service interactions for security reasons:

Apps that may block automation:

• Banking apps
• Payment apps
• Password managers
• Some security-focused apps

Workarounds:

• Vision-based targeting (magicClicker) works on most apps
• Some apps only block specific accessibility features
• Test your target app before building complex automations
• Consider alternative approaches (web version, APIs)

Legal note: Always respect app terms of service and use automation responsibly.

How do I schedule recurring automations?

Use the schedule() function with cron expressions:

// Every hour at minute 0
schedule("hourly-task", "0 * * * *");

// Every day at 9 AM
schedule("morning-task", "0 9 * * *");

// Every 5 minutes
schedule("frequent-task", "*/5 * * * *");

// Every Monday at 8 AM
schedule("weekly-task", "0 8 * * 1");

Requirements:

• Disable battery optimization for PhoneClaw
• Keep accessibility service enabled
• Device should not be in deep sleep during scheduled time

Use crontab.guru to build cron expressions.

Troubleshooting

Why aren't my automations working?

Common causes:

1. Accessibility service disabled

   • Check Settings > Accessibility > PhoneClaw

2. UI elements not loading

   • Add delays: await delay(2000);

3. Vague element descriptions

   • Be more specific: “blue login button” vs “button”

4. App blocking automation

   • Test with different apps
   • Some apps actively prevent accessibility interactions

5. Battery optimization killing service

   • Disable battery optimization for PhoneClaw

See Common Issues for detailed solutions.

Why do scheduled tasks stop running?

Reasons and solutions:

1. Battery optimization (most common)

   • Settings > Battery > PhoneClaw > Don’t optimize

2. Accessibility service auto-disabled

   • Add PhoneClaw to protected apps list (manufacturer-specific)

3. Device in deep sleep

   • Keep device charging or adjust sleep settings

4. Invalid cron expression

   • Validate at crontab.guru

5. Manufacturer restrictions (Xiaomi, Huawei, Samsung)

   • Enable autostart permissions
   • Disable background restrictions

See Common Issues - Scheduling for detailed steps.

How do I debug my ClawScript?

Debugging techniques:

1. Use speakText for logging:

speakText("Starting step 1");
await magicClicker("Button");
speakText("Completed step 1");

2. Add error handling:

try {
  await magicClicker("Submit");
} catch (error) {
  speakText("Error: " + error);
}

3. Test incrementally:

• Start with single action
• Add actions one at a time
• Test after each addition

4. Check variables:

const result = await magicScraper("Code");
speakText("Result is: " + result);

See full Debugging Guide for advanced techniques.

Why is PhoneClaw using so much battery?

Battery optimization:

1. Vision API calls

   • magicClicker/magicScraper use vision AI (network + processing)
   • Minimize unnecessary calls

2. Frequent scheduled tasks

   • Reduce frequency where possible
   • Combine multiple actions into single scheduled task

3. Accessibility service overhead

   • Normal for accessibility-based automation
   • Disable when not actively using automations

4. Long delays in loops

   • Use efficient timing
   • Avoid busy-waiting loops

Tips:

• Use dedicated automation device if running 24/7
• Keep device plugged in for scheduled tasks
• Optimize scripts to reduce API calls

Advanced Usage

Can I chain automations across multiple apps?

Yes! PhoneClaw excels at multi-app workflows:

// Check email for verification code
await magicClicker("Gmail app");
await delay(3000);
const code = await magicScraper("The verification code in the email");
speakText("Code found: " + code);

// Switch to browser
await magicClicker("Chrome app");
await delay(2000);

// Enter code
await magicClicker("Verification code field");
// ... enter code

speakText("Multi-app workflow complete");

See Multi-App Workflows Guide for examples.

Can I use PhoneClaw with other automation tools?

PhoneClaw can complement other tools:

Integration approaches:

• Use sendAgentEmail() to notify external systems
• Trigger PhoneClaw from external tools via intents (advanced)
• Share data through files or network calls
• Use PhoneClaw for UI automation, other tools for API calls

Compatible with:

• Tasker (via intents)
• IFTTT (via webhooks/email)
• Home Assistant (via notifications)
• Custom Python/Node.js scripts

How do I handle CAPTCHAs?

CAPTCHA automation:

1. Vision-based solving:

   • Use magicScraper to read CAPTCHA challenges
   • Process with vision AI
   • Use magicClicker to select answers

2. Image CAPTCHAs:

const question = await magicScraper("What does the CAPTCHA ask to select?");
speakText("CAPTCHA asks: " + question);
// Use vision to identify matching images
await magicClicker("Correct image tile");

3. reCAPTCHA:
   • Harder to automate
   • May require CAPTCHA solving services
   • Consider accessibility alternatives

See CAPTCHA Solving Example for detailed implementation.

Can I build a business using PhoneClaw?

Yes, PhoneClaw is open source and can be used commercially:

Potential use cases:

• Social media management services
• Testing and QA automation
• Data collection and monitoring
• Personal productivity tools
• Accessibility solutions

Important considerations:

• Respect terms of service of automated apps
• Don’t use for spam or malicious purposes
• Consider rate limits and API usage costs
• Ensure compliance with relevant laws and regulations

Legal note: You are responsible for ensuring your use case complies with applicable laws and service terms.

Community and Support

Where can I get help?

Support channels:

Discord Community

Active community for quick help and discussions

GitHub Issues

Report bugs and request features

Documentation

Comprehensive guides and API reference

YouTube Channel

Video tutorials and demos

How can I contribute to PhoneClaw?

Contributions are welcome!

Ways to contribute:

• Report bugs and issues
• Submit feature requests
• Fix bugs and add features
• Improve documentation
• Share automation examples
• Help other users in Discord

See the Contributing Guide for detailed instructions.

Where can I find automation examples?

Resources:

1. Documentation Examples - Examples section
2. Demo Videos - YouTube channel
3. Discord #showcase - Community-shared automations
4. GitHub repository - Sample scripts in the repo

Popular examples:

• Social media posting
• Account creation with 2FA
• Email automation
• TikTok video uploads
• CAPTCHA solving

Is there a PhoneClaw community?

Yes! Join our active community:

Discord Server: discord.gg/n9nbZUrw

• Get support from experienced users
• Share your automations
• Request features
• Stay updated on new releases

Twitter Community: Join on Twitter

• Discussions and updates

YouTube: @getsuperpowers

• Tutorials and demos

See Community page for more information.

Still Have Questions?

Join Discord

Ask questions in real-time

Browse Docs

Explore comprehensive documentation

Common Issues

Find solutions to common problems

GitHub Discussions

Join community discussions