ewilliams28/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-08-12 21:53:00 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs(computer-use): add cua-computer troubleshooting/error-code reference and fix stale Codex macOS claim (#112502)

Browse Source
This commit is contained in:
Peter Steinberger
2026-07-21 21:07:01 -07:00
committed by GitHub
parent c5c9cb056a
commit c1a313676b
3 changed files with 22 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docs_map.md
+1
View File
@@ -4955,6 +4955,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
- H2: Requirements
- H2: The computer agent tool
- H2: Windows and Linux (experimental, via cua-driver)
- H3: Troubleshooting
- H2: The computer.act node command
- H2: Enable and arm
- H2: Safety
docs/nodes/computer-use.md
+15
View File
@@ -54,6 +54,21 @@ Because cua-driver reports no stable display identity, frame authorization binds
OpenClaw disables cua-driver telemetry and update checks for the `mcp` and `serve` processes it manages. It does not download or update the driver binary.
### Troubleshooting
The `cua-computer` fulfiller surfaces typed error codes in the tool result and node logs. Common ones:
| Code | Cause | Fix |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `COMPUTER_DRIVER_UNAVAILABLE` | The `cua-driver` binary is not on `PATH` (or `driverPath` is wrong), the daemon did not become ready in time, or the node is not Windows/Linux. | Install `cua-driver` 0.10.x on `PATH` or set `driverPath`. Run `openclaw node run` inside the interactive desktop session; on Linux ensure an X11 `DISPLAY` (or a `WAYLAND_DISPLAY` with `CUA_DRIVER_RS_ENABLE_WAYLAND`) is present. |
| `COMPUTER_DRIVER_UNSUPPORTED` | The connected driver is not `cua-driver` 0.10.x, or its capability/schema version differs. | Install a supported 0.10.x build. The plugin re-probes about 30 seconds after you correct it, so no node restart is needed. |
| `COMPUTER_REFUSED_<code>` | The driver refused the action with a structured code such as `background_unavailable`, `background_occluded`, or `foreground_unavailable` (KDE/KWin Wayland). | Bring the target window forward, switch to X11, or use a supported compositor. See the compatibility notes above. |
| `COMPUTER_STALE_FRAME` | The coordinates referenced a screenshot that is no longer current (context compaction, a display geometry change, or a reference-width change). | Take a fresh `screenshot` before the coordinate action. |
| `COMPUTER_UNSUPPORTED_ACTION` | An action this fulfiller cannot faithfully deliver: `hold_key`, `left_mouse_down`, `left_mouse_up`, modifier-held drag/scroll, or modifier-held click on Linux. | Use a supported action. cua-driver 0.10.x has no desktop-scope held-input contract. |
| `COMPUTER_UNSUPPORTED_DISPLAY` | A non-primary `screenIndex`, a capture/screen geometry mismatch, or a cursor outside the primary display. | Drive the primary display only. |
| `COMPUTER_UNSUPPORTED_KEY` | A `key` value the driver cannot reproduce reliably: a digit or punctuation key whose shift state is layout-dependent, or an unknown key. | Send that text through the `type` action instead. |
| `COMPUTER_DRIVER_ERROR` / `COMPUTER_INVALID_REQUEST` | The driver failed without a structured code, or the action arguments were malformed. | Check the driver state and retake a screenshot; correct the action arguments. |
## The `computer.act` node command
`computer.act` is the single node command the tool routes input through (`node.invoke` with `command: "computer.act"`). It is:
docs/plugins/codex-computer-use.md
+6 -4
View File
@@ -320,10 +320,12 @@ tools when available, and the specific message for the failing setup step.
## macOS permissions
Computer Use is macOS-specific. The Codex-owned MCP server may need local OS
permissions before it can inspect or control apps. If OpenClaw says Computer
Use is installed but the MCP server is unavailable, verify the Codex-side
Computer Use setup first:
This Codex-owned Computer Use path runs on macOS, where the MCP server may need
local OS permissions before it can inspect or control apps. (For cross-platform
desktop control on Windows and Linux node hosts, see the
[cua-computer fulfiller](/nodes/computer-use#windows-and-linux-experimental-via-cua-driver).)
If OpenClaw says Computer Use is installed but the MCP server is unavailable,
verify the Codex-side Computer Use setup first:
- Codex app-server is running on the same host where desktop control should
happen.