diff --git a/docs/docs_map.md b/docs/docs_map.md
index a8961c083bb2..a892394946e5 100644
--- a/docs/docs_map.md
+++ b/docs/docs_map.md
@@ -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
diff --git a/docs/nodes/computer-use.md b/docs/nodes/computer-use.md
index bcc1b870a9f4..f68b27f0fac7 100644
--- a/docs/nodes/computer-use.md
+++ b/docs/nodes/computer-use.md
@@ -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:
diff --git a/docs/plugins/codex-computer-use.md b/docs/plugins/codex-computer-use.md
index f9c082f00683..d0c5b6f87eb7 100644
--- a/docs/plugins/codex-computer-use.md
+++ b/docs/plugins/codex-computer-use.md
@@ -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.