DroidClaw transforma smartphones Android obsoletos en agentes de IA que ejecutan tareas reales en cualquier aplicación, sin necesidad de integraciones externas.

DroidClaw es una herramienta de código abierto que convierte cualquier teléfono Android en un agente de inteligencia artificial capaz de leer la pantalla, razonar sobre lo que ve y ejecutar acciones mediante instrucciones escritas en inglés simple. No requiere acceso programático a las aplicaciones instaladas: el agente opera la interfaz exactamente como lo haría un usuario, valiéndose del protocolo Android Debug Bridge para interactuar con el sistema. El proyecto está disponible bajo licencia MIT en github.com/unitedbyai/droidclaw y fue desarrollado por la comunidad unitedby.ai.

¿Qué es DroidClaw y qué problema resuelve?

La mayoría de las aplicaciones móviles populares no exponen interfaces de programación accesibles, o las restringen severamente. DroidClaw sortea esa limitación operando directamente sobre la capa de accesibilidad del sistema Android: puede usar WhatsApp, Telegram, Spotify, YouTube o cualquier otra aplicación instalada sin necesitar permisos especiales de desarrollador por parte de cada servicio. Lo cierto es que esta arquitectura resulta más práctica que construir integraciones a medida para cada aplicación, especialmente cuando el objetivo es reutilizar teléfonos que de otra manera quedarían en un cajón.

¿Cómo funciona el ciclo de percepción, razonamiento y acción?

El sistema opera con un ciclo continuo de tres fases. En la fase de percepción, DroidClaw vuelca el árbol de accesibilidad de Android mediante uiautomator dump, lo analiza para extraer los elementos interactivos con sus coordenadas, y lo compara con el estado anterior para detectar cambios. En la fase de razonamiento, ese estado se envía junto con el objetivo y el historial de pasos a un modelo de lenguaje, que responde con un objeto estructurado con tres campos: think, plan y action. Finalmente, en la fase de acción, el sistema ejecuta lo indicado —un toque, escritura, desplazamiento— y alimenta el resultado al modelo en el siguiente ciclo.

Vale la pena destacar los mecanismos de recuperación ante fallos que el sistema incorpora de forma nativa. La detección de bloqueo inyecta sugerencias contextuales al modelo si la pantalla no cambia en tres pasos consecutivos. El seguimiento de repeticiones identifica si el agente toca las mismas coordenadas más de tres veces e instruye al modelo para intentar otra estrategia. La detección de drift actúa cuando el agente encadena acciones de navegación sin interactuar con ningún elemento, forzando una acción directa. El modo visión como respaldo envía capturas de pantalla al modelo cuando el árbol de accesibilidad está vacío, lo cual ocurre en aplicaciones construidas con Flutter, vistas web integradas o videojuegos.

Instalación paso a paso

El método más rápido es el instalador automático, que verifica y descarga todas las dependencias necesarias:

curl -fsSL https://droidclaw.ai/install.sh | sh

Este comando instala Bun y ADB si no están presentes, clona el repositorio y genera el archivo de configuración .env. Es importante señalar que DroidClaw requiere Bun específicamente —Node.js no es compatible— porque utiliza interfaces exclusivas de ese entorno como Bun.spawnSync y la carga nativa de variables de entorno.

Para la instalación manual, los pasos son los siguientes:

1. Instalar ADB: brew install android-platform-tools en macOS o sudo apt install android-tools-adb en Linux. En Windows, descargar desde developer.android.com.
2. Instalar Bun: curl -fsSL https://bun.sh/install | bash
3. Clonar el repositorio: git clone https://github.com/unitedbyai/droidclaw.git
4. Instalar dependencias: cd droidclaw && bun install
5. Copiar la configuración: cp .env.example .env

¿Cómo habilitar la depuración USB en Android?

Antes de conectar el teléfono, es necesario activar las opciones de desarrollador: entrar a Ajustes → Acerca del teléfono y pulsar siete veces sobre Número de compilación. Luego, en Ajustes → Opciones de desarrollador, activar Depuración USB. Al conectar el cable, el teléfono mostrará un diálogo de autorización que debe aceptarse. La verificación se realiza con adb devices, que debe mostrar el identificador del dispositivo conectado.

Proveedores de modelos compatibles

Toda la configuración del agente reside en el archivo .env. DroidClaw soporta cinco proveedores de modelos de lenguaje con características distintas según el caso de uso:

• Groq: nivel gratuito disponible, sin capacidad de visión; ideal para comenzar rápidamente
• Ollama: ejecución completamente local, sin clave de acceso, soporta visión con modelos como llama3.2-vision o llava
• OpenRouter: acceso a más de 200 modelos con una única interfaz, pago por uso
• OpenAI: modelos como GPT-4o con razonamiento avanzado y soporte de visión
• AWS Bedrock: Claude y Llama en infraestructura de Amazon, pago por uso

Para iniciar con Groq, basta agregar dos líneas al .env:

LLM_PROVIDER=groq
GROQ_API_KEY=gsk_tu_clave_aqui

Para una configuración completamente local con Ollama:

ollama pull llama3.2
LLM_PROVIDER=ollama
OLLAMA_MODEL=llama3.2

Parámetros de configuración disponibles

El archivo .env admite nueve parámetros ajustables que controlan el comportamiento del agente. Conocerlos evita comportamientos inesperados en tareas largas o en dispositivos con resoluciones poco comunes:

• MAX_STEPS (valor predeterminado: 30): pasos máximos antes de que el agente abandone la tarea
• STEP_DELAY (2): segundos de espera entre acciones para que la interfaz se estabilice
• STUCK_THRESHOLD (3): pasos sin cambio antes de activar la recuperación por bloqueo
• VISION_MODE (fallback): off desactiva la visión; fallback la usa solo cuando el árbol está vacío; always envía capturas en cada paso
• MAX_ELEMENTS (40): número máximo de elementos de interfaz enviados al modelo por paso
• MAX_HISTORY_STEPS (10): pasos anteriores conservados en el historial de conversación
• STREAMING_ENABLED (true): muestra el progreso del modelo en tiempo real
• LOG_DIR (logs): directorio donde se guardan los registros de sesión en formato JSON
• ADB_PATH: ruta manual al ejecutable ADB cuando no está en el PATH del sistema

¿Cuáles son los tres modos de uso?

DroidClaw ofrece tres modalidades operativas que cubren desde la ejecución espontánea hasta la automatización determinista.

El modo interactivo es el punto de entrada natural: se ejecuta bun run src/kernel.ts, se escribe el objetivo y el agente lo resuelve en tiempo real. Es adecuado para tareas puntuales como abrir una aplicación, buscar contenido o cambiar ajustes del sistema.

Los flujos de trabajo con inteligencia artificial son archivos JSON que encadenan múltiples subobjetivos, cada uno opcionalmente en una aplicación diferente. El modelo de lenguaje gestiona la navegación en cada paso y se adapta si la interfaz cambia. Se ejecutan con bun run src/kernel.ts --workflow archivo.json. El repositorio incluye 35 ejemplos listos para usar organizados en cinco categorías: mensajería (10), redes sociales (4), productividad (8), investigación (6) y estilo de vida (8). Algunos casos concretos: enviar un resumen del clima a WhatsApp, publicar actualizaciones diarias en Slack, comparar precios en aplicaciones de comercio, o compilar resúmenes de canales de Telegram.

Los flujos deterministas son archivos YAML que definen secuencias fijas de acciones sin intervención del modelo. Son instantáneos y no consumen créditos de ningún proveedor, funcionando como macros precisas. Se ejecutan con bun run src/kernel.ts --flow archivo.yaml. El repositorio incluye 5 plantillas: enviar un mensaje por WhatsApp, realizar una búsqueda en Google, crear un contacto, limpiar notificaciones y activar o desactivar el WiFi.

Las 28 acciones disponibles para el agente

El agente dispone de 28 acciones divididas en dos grupos. Las 22 acciones básicas mapean directamente a comandos ADB: interacciones de pantalla (tap, type, enter, longpress, clear, paste, swipe, scroll), navegación del sistema (home, back, launch, switch_app, open_url, open_settings, notifications), portapapeles (clipboard_get, clipboard_set) y acciones de sistema (screenshot, shell, keyevent, pull_file, push_file).

Las 6 habilidades de múltiples pasos condensan secuencias de 5 a 10 acciones individuales en una sola llamada. read_screen desplaza automáticamente toda la pantalla, recopila el texto visible y lo copia al portapapeles. compose_email rellena los campos de destinatario, asunto y cuerpo en el orden correcto usando los mecanismos internos de Android. Estas habilidades compuestas reducen el número de decisiones que el modelo debe tomar, mejorando tanto la velocidad como la fiabilidad del agente. Las otras cuatro son: submit_message, copy_visible_text, wait_for_content y find_and_tap.

¿Qué funciona bien y qué no?

La documentación oficial del proyecto incluye una evaluación honesta de las capacidades actuales del sistema. Conviene conocerla antes de diseñar flujos de trabajo complejos.

Funciona de forma confiable con aplicaciones nativas de Android que usan componentes de interfaz estándar, flujos de trabajo con múltiples aplicaciones, ajustes del sistema mediante comandos de consola, y entrada de texto y navegación general. El sistema de recuperación ante bloqueos y el modo de visión como respaldo funcionan correctamente en la mayoría de los casos.

Por el contrario, el funcionamiento es poco confiable en aplicaciones construidas con Flutter o React Native, vistas web integradas, gestos de arrastre o múltiples dedos, interacción con notificaciones, y operaciones con el portapapeles en Android 12 o superior. Además, hay operaciones que el sistema no puede realizar: aplicaciones bancarias que activan la bandera de seguridad del sistema, autenticación biométrica, acceso a datos privados de otras aplicaciones, transmisión de audio o video, y gestos de zoom con dos dedos.

Control remoto con Tailscale

Una de las capacidades más útiles de DroidClaw es la posibilidad de controlar el teléfono de forma remota. Instalando Tailscale tanto en el dispositivo Android como en un servidor o laptop, ambos quedan en la misma red privada virtual. Luego se activa la depuración inalámbrica en las opciones de desarrollador, se anota la dirección IP y el puerto mostrados, y se conecta con adb connect IP:PUERTO.

Esta configuración convierte un teléfono Android antiguo en un agente siempre activo, conectado a la corriente y controlable desde cualquier lugar. Es posible ejecutar flujos de trabajo desde una tarea programada cada mañana, desde un servidor remoto, o desde una laptop en cualquier red, sin que el teléfono y el equipo de control estén en el mismo lugar físico.

¿Cómo resolver los errores más comunes?

Antes de explorar soluciones complejas, vale revisar estos tres escenarios que concentran la mayoría de los problemas reportados. Si el sistema indica “adb: command not found”, ADB no está instalado o no está en el PATH del sistema; instalar android-platform-tools o especificar la ruta completa con ADB_PATH en el .env resuelve el problema. Si aparece “no devices found”, hay que verificar que la depuración USB esté activa, que se haya aceptado el diálogo de autorización en el teléfono, y que el cable soporte transferencia de datos y no solo carga.

Cuando el agente repite la misma acción en ciclo sin avanzar, el sistema de recuperación debería gestionarlo automáticamente, pero si el problema persiste, cambiar a un modelo más capaz como llama-3.3-70b de Groq o gpt-4o de OpenAI generalmente lo resuelve. Si el árbol de accesibilidad aparece vacío —habitual en aplicaciones Flutter o con vistas web integradas— activar VISION_MODE=always en el .env hace que el agente opere mediante capturas de pantalla en cada paso. Si las coordenadas de los toques parecen incorrectas, conviene verificar en la consola la resolución detectada por el sistema al inicio, ya que puede diferir de la resolución nominal del dispositivo.