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

Nodes and media

Uso del ordenador

El uso del ordenador permite que el agente del Gateway vea y controle un escritorio vinculado con las capacidades necesarias. La elegibilidad se basa en capacidades: el nodo conectado debe anunciar tanto computer.act como screen.snapshot, cuyo resultado debe incluir un displayFrameId. La herramienta captura una pantalla como marco de referencia y, a continuación, controla el puntero y el teclado mediante el comando peligroso computer.act. El conjunto de acciones sigue las acciones principales de uso del ordenador de Anthropic; el zoom opcional computer_20251124 no está disponible. Un modelo con capacidad de visión lo controla mediante la herramienta de agente integrada computer.

El agente emite un único comando uniforme, computer.act; no puede saber cómo lo ejecuta un nodo. La aplicación macOS incluida gestiona el comando dentro del proceso mediante servicios Peekaboo integrados y primitivas específicas de CoreGraphics (permisos TCC correctos, sin procesos adicionales). Windows y Linux pueden utilizar el Plugin opcional y experimental cua-computer con un binario cua-driver instalado por separado. Ambos ejecutores utilizan la misma política de vinculación y activación.

Requisitos

  • Un nodo vinculado y conectado que anuncie tanto computer.act como screen.snapshot, y en el que screen.snapshot devuelva displayFrameId.
  • Ejecutor de macOS: ajuste de la aplicación Allow Computer Control habilitado (valor predeterminado: desactivado).
  • Ejecutor de macOS: permiso Accessibility concedido a OpenClaw (para la inyección del puntero y el teclado) y permiso Screen Recording (para screen.snapshot).
  • Ejecutor de Windows/Linux: Plugin cua-computer incluido habilitado y un ejecutable compatible cua-driver 0.10.x instalado.
  • El comando computer.act activado en el Gateway (es peligroso y está desactivado de forma predeterminada).
  • Un modelo de agente con capacidad de visión.
  • Una política de herramientas que exponga computer. El perfil predeterminado coding no lo hace. Añada computer a tools.alsoAllow; los agentes en entorno aislado también lo necesitan en tools.sandbox.tools.alsoAllow.

La herramienta de agente computer

La herramienta integrada computer admite una acción por llamada. Las coordenadas son píxeles enteros no negativos de la captura de pantalla más reciente; el nodo las asigna a puntos de la pantalla. Las acciones de coordenadas deben reproducir el frameId del resultado de la captura de pantalla, y un screenIndex explícito debe coincidir con ese marco. OpenClaw también transmite a la acción una identidad de pantalla emitida por el nodo a partir de la captura de pantalla, de modo que la reconexión de una pantalla o un cambio de geometría produzcan un fallo seguro en lugar de redirigir silenciosamente la acción al mismo índice. Estas comprobaciones rechazan los tokens inventados y los tokens de otro marco o pantalla entregados. Un token no garantiza la vigencia: las aplicaciones pueden cambiar los píxeles de la misma pantalla después de la captura, por lo que debe realizarse una nueva captura siempre que la escena pueda haber cambiado.

  • Lecturas: screenshot.
  • Puntero: left_click, right_click, middle_click, double_click, triple_click, mouse_move, left_click_drag (con startCoordinate), left_mouse_down, left_mouse_up.
  • Desplazamiento: scroll con scrollDirection (up|down|left|right) y scrollAmount (pasos de la rueda).
  • Teclado: type (texto), key (combinación como cmd+shift+t o Return), hold_key (combinación text mantenida durante duration segundos).
  • Ritmo: wait (duration segundos).

Las teclas modificadoras se transmiten en el campo text de las acciones de clic y desplazamiento (shift, ctrl, alt, cmd). Tras una acción de entrada, la herramienta devuelve una nueva captura de pantalla para que el modelo pueda observar el resultado. Si hay más de un nodo con capacidad de uso del ordenador conectado, proporcione node explícitamente.

Las capturas de pantalla se mantienen solo para el modelo: nunca se entregan automáticamente al canal de chat. Todo el contenido en pantalla debe tratarse como entrada no fiable; la herramienta advierte al modelo que no siga instrucciones en pantalla que entren en conflicto con la solicitud del usuario.

Windows y Linux (experimental, mediante cua-driver)

El Plugin incluido cua-computer proporciona un ejecutor experimental para hosts de nodo Windows y Linux. Está deshabilitado de forma predeterminada y requiere el contrato de controlador preliminar 0.10.x:

  1. Instale un binario cua-driver 0.10.x desde las versiones publicadas del proyecto original y asegúrese de que esté disponible en PATH. Para utilizar otra ubicación del ejecutable, establezca plugins.entries.cua-computer.config.driverPath.

  2. Habilite el Plugin:

    bash
    openclaw plugins enable cua-computer

  3. Inicie openclaw node run desde la sesión de escritorio interactiva. El Plugin inicia el demonio local del controlador de forma diferida cuando llega la primera captura o acción.

Este ejecutor controla actualmente solo la pantalla principal. X11/XWayland es la opción principal en Linux. Wayland nativo sigue siendo una opción voluntaria del proyecto original: establezca CUA_DRIVER_RS_ENABLE_WAYLAND manualmente antes de iniciar el nodo; OpenClaw nunca lo establece automáticamente. KDE/KWin no es compatible con la ruta de entrada nativa de Wayland del proyecto original. hold_key, left_mouse_down y left_mouse_up no están disponibles porque cua-driver 0.10.x no tiene un contrato multiplataforma para mantener entradas en el ámbito del escritorio. El desplazamiento y el arrastre con modificadores mantenidos no están disponibles en ninguna de las dos plataformas, y los clics con modificadores mantenidos no están disponibles en Linux. La acción key acepta teclas con nombre, letras y combinaciones de modificadores (por ejemplo, cmd+c o Return); las teclas de dígitos y puntuación se rechazan porque el controlador descarta su estado de mayúsculas dependiente de la distribución, por lo que ese texto debe enviarse mediante la acción type. La escritura de texto no puede cancelarse durante una llamada del controlador type_text.

Como cua-driver no informa de una identidad de pantalla estable, la autorización del marco se vincula a la conexión del controlador y a la geometría activa de la pantalla principal. La reconexión de un demonio o una sesión invalida los marcos pendientes, pero no puede detectarse una sustitución de la pantalla principal con la misma geometría que mantenga abierta la conexión; para este ejecutor, es preferible utilizar una sesión estable con una sola pantalla.

OpenClaw deshabilita la telemetría y las comprobaciones de actualizaciones de cua-driver para los procesos mcp y serve que administra. No descarga ni actualiza el binario del controlador.

Solución de problemas

El ejecutor cua-computer muestra códigos de error tipados en el resultado de la herramienta y en los registros del nodo. Algunos habituales son:

Código Causa Solución
COMPUTER_DRIVER_UNAVAILABLE El binario cua-driver no está en PATH (o driverPath es incorrecto), el demonio no estuvo listo a tiempo o el nodo no es Windows/Linux. Instale cua-driver 0.10.x en PATH o establezca driverPath. Ejecute openclaw node run dentro de la sesión de escritorio interactiva; en Linux, asegúrese de que haya un DISPLAY de X11 (o un WAYLAND_DISPLAY con CUA_DRIVER_RS_ENABLE_WAYLAND).
COMPUTER_DRIVER_UNSUPPORTED El controlador conectado no es cua-driver 0.10.x o su versión de capacidades/esquema es diferente. Instale una compilación 0.10.x compatible. El Plugin vuelve a sondearla unos 30 segundos después de corregirla, por lo que no es necesario reiniciar el nodo.
COMPUTER_REFUSED_<code> El controlador rechazó la acción con un código estructurado como background_unavailable, background_occluded o foreground_unavailable (Wayland de KDE/KWin). Ponga la ventana de destino en primer plano, cambie a X11 o utilice un compositor compatible. Consulte las notas de compatibilidad anteriores.
COMPUTER_STALE_FRAME Las coordenadas hacían referencia a una captura de pantalla que ya no está vigente (Compaction del contexto, un cambio de geometría de pantalla o un cambio de anchura de referencia). Realice una nueva screenshot antes de la acción de coordenadas.
COMPUTER_UNSUPPORTED_ACTION Una acción que este ejecutor no puede reproducir fielmente: hold_key, left_mouse_down, left_mouse_up, arrastre/desplazamiento con modificador mantenido o clic con modificador mantenido en Linux. Utilice una acción compatible. cua-driver 0.10.x no tiene un contrato de entrada mantenida en el ámbito del escritorio.
COMPUTER_UNSUPPORTED_DISPLAY Un screenIndex que no es el principal, una discrepancia entre la geometría de captura y la de pantalla, o un cursor fuera de la pantalla principal. Controle únicamente la pantalla principal.
COMPUTER_UNSUPPORTED_KEY Un valor key que el controlador no puede reproducir de forma fiable: una tecla de dígito o puntuación cuyo estado de mayúsculas depende de la distribución, o una tecla desconocida. Envíe ese texto mediante la acción type.
COMPUTER_DRIVER_ERROR / COMPUTER_INVALID_REQUEST El controlador falló sin un código estructurado o los argumentos de la acción tenían un formato incorrecto. Compruebe el estado del controlador y vuelva a realizar una captura de pantalla; corrija los argumentos de la acción.

El comando de nodo computer.act

computer.act es el único comando de nodo por el que la herramienta enruta la entrada (node.invoke con command: "computer.act"). Es:

  • Peligroso de forma predeterminada: aparece entre los comandos de nodo peligrosos integrados y se excluye de la lista de permitidos del entorno de ejecución hasta que se activa explícitamente. Los nodos de escritorio de macOS, Windows y Linux pueden declararlo durante la vinculación para que la superficie se apruebe una sola vez.
  • Basado en capacidades: la herramienta requiere que un nodo conectado anuncie tanto computer.act como screen.snapshot. La aplicación macOS incluida y el Plugin experimental cua-computer, que requiere activación explícita, ejecutan el mismo par de comandos.

Las lecturas reutilizan screen.snapshot; no existe una segunda ruta de captura. Consulte Nodos de cámara y pantalla para conocer el comando de captura compartido.

Habilitación y activación

  1. Habilite el ejecutor de la plataforma: en macOS, habilite Settings → Allow Computer Control y, a continuación, conceda Accessibility y Screen Recording en Settings → Permissions; en Windows/Linux, siga la configuración experimental de cua-computer indicada anteriormente.

  2. Apruebe la actualización del emparejamiento en el Gateway (un comando nuevo fuerza un nuevo emparejamiento).

  3. Exponga la herramienta al agente con capacidad de visión. Para el perfil predeterminado de coding:

    json5
    {  tools: {    alsoAllow: ["computer"],    // Los agentes en entorno aislado también necesitan esta segunda autorización:    sandbox: { tools: { alsoAllow: ["computer"] } },  },}

  4. Active computer.act durante un periodo limitado. El Plugin phone-control expone un grupo computer:

    text
    /phone arm computer 30m/phone status/phone disarm

    La activación requiere operator.admin (o ser el propietario) y caduca automáticamente. El grupo heredado /phone arm all excluye intencionadamente el control del escritorio; use el grupo explícito computer. La activación solo cambia lo que puede invocar el Gateway; la aplicación del Node sigue aplicando su configuración específica de la plataforma y los permisos del sistema operativo, incluidos Allow Computer Control, Accessibility y Screen Recording en macOS.

Para obtener una autorización persistente, añada computer.act a gateway.nodes.commands.allow y elimínelo de gateway.nodes.commands.deny; la lista de denegación tiene prioridad. La autorización persistente no caduca automáticamente. Las entradas que ya estaban presentes antes de /phone arm permanecen después de /phone disarm; no convierta una concesión temporal en persistente mientras esté activa.

La autorización se divide deliberadamente entre la habilitación y el uso. Activar o configurar de forma persistente computer.act requiere autoridad administrativa. Una vez activado, un operador autenticado con operator.write puede invocar computer.act mediante node.invoke hasta que la concesión caduque o se desactive; no se realiza ninguna comprobación administrativa por acción. Aprobar un Node que declara computer.act solo registra la superficie para que pueda activarse más adelante y no habilita por sí mismo la invocación.

Seguridad

  • Antes de la autorización, todas las capas (la política de herramientas, la política de comandos del Gateway, la configuración de la aplicación del Node y los permisos de la plataforma) deben estar de acuerdo. Para el ejecutor actual de macOS, esto incluye Allow Computer Control, Accessibility y Screen Recording. Una vez activado, las acciones se ejecutan sin confirmación por acción hasta que caduque o se ejecute /phone disarm.
  • El ejecutor de macOS introduce el texto grafema por grafema, por lo que una cancelación, desconexión, pausa, deshabilitación o sustitución del endpoint lo detiene antes del siguiente grafema. El ejecutor experimental cua-driver no puede cancelar una llamada a type_text mientras se está escribiendo.
  • Las capturas de pantalla son solo para el modelo y nunca se envían automáticamente al chat (incidencia #44759).
  • Trate el contenido de la pantalla como no confiable; puede contener una inyección de instrucciones.

Relación con otras vías de control del escritorio

Esta es la vía controlada por el agente. Consulte puente Peekaboo para saber cómo se relaciona con el host PeekabooBridge, Codex Computer Use y el MCP directo cua-driver.

Was this useful?
On this page

On this page