|
| 1 | +--- |
| 2 | +summary: "Set up Codex Computer Use for Codex-mode OpenClaw agents" |
| 3 | +title: "Codex Computer Use" |
| 4 | +read_when: |
| 5 | + - You want Codex-mode OpenClaw agents to use Codex Computer Use |
| 6 | + - You are configuring computerUse for the bundled Codex plugin |
| 7 | + - You are troubleshooting /codex computer-use status or install |
| 8 | +--- |
| 9 | + |
| 10 | +Computer Use is a Codex-native MCP plugin for local desktop control. OpenClaw |
| 11 | +does not vendor the desktop app, execute desktop actions itself, or bypass |
| 12 | +Codex permissions. The bundled `codex` plugin only prepares Codex app-server: |
| 13 | +it enables Codex plugin support, finds or installs the configured Codex |
| 14 | +Computer Use plugin, checks that the `computer-use` MCP server is available, and |
| 15 | +then lets Codex own the native MCP tool calls during Codex-mode turns. |
| 16 | + |
| 17 | +Use this page when OpenClaw is already using the native Codex harness. For the |
| 18 | +runtime setup itself, see [Codex harness](/plugins/codex-harness). |
| 19 | + |
| 20 | +## Quick setup |
| 21 | + |
| 22 | +Set `plugins.entries.codex.config.computerUse` when Codex-mode turns must have |
| 23 | +Computer Use available before a thread starts: |
| 24 | + |
| 25 | +```json5 |
| 26 | +{ |
| 27 | + plugins: { |
| 28 | + entries: { |
| 29 | + codex: { |
| 30 | + enabled: true, |
| 31 | + config: { |
| 32 | + computerUse: { |
| 33 | + autoInstall: true, |
| 34 | + }, |
| 35 | + }, |
| 36 | + }, |
| 37 | + }, |
| 38 | + }, |
| 39 | + agents: { |
| 40 | + defaults: { |
| 41 | + model: "openai/gpt-5.5", |
| 42 | + embeddedHarness: { |
| 43 | + runtime: "codex", |
| 44 | + }, |
| 45 | + }, |
| 46 | + }, |
| 47 | +} |
| 48 | +``` |
| 49 | + |
| 50 | +With this config, OpenClaw checks Codex app-server before each Codex-mode turn. |
| 51 | +If Computer Use is missing but Codex app-server has already discovered an |
| 52 | +installable marketplace, OpenClaw asks Codex app-server to install or re-enable |
| 53 | +the plugin and reload MCP servers. If setup still cannot make the MCP server |
| 54 | +available, the turn fails before the thread starts. |
| 55 | + |
| 56 | +## Commands |
| 57 | + |
| 58 | +Use the `/codex computer-use` commands from any chat surface where the `codex` |
| 59 | +plugin command surface is available: |
| 60 | + |
| 61 | +```text |
| 62 | +/codex computer-use status |
| 63 | +/codex computer-use install |
| 64 | +/codex computer-use install --source <marketplace-source> |
| 65 | +/codex computer-use install --marketplace-path <path> |
| 66 | +/codex computer-use install --marketplace <name> |
| 67 | +``` |
| 68 | + |
| 69 | +`status` is read-only. It does not add marketplace sources, install plugins, or |
| 70 | +enable Codex plugin support. |
| 71 | + |
| 72 | +`install` enables Codex app-server plugin support, optionally adds a configured |
| 73 | +marketplace source, installs or re-enables the configured plugin through Codex |
| 74 | +app-server, reloads MCP servers, and verifies that the MCP server exposes tools. |
| 75 | + |
| 76 | +## Marketplace choices |
| 77 | + |
| 78 | +OpenClaw uses the same app-server API that Codex itself exposes. The |
| 79 | +marketplace fields choose where Codex should find `computer-use`. |
| 80 | + |
| 81 | +| Field | Use when | Install support | |
| 82 | +| -------------------- | --------------------------------------------------------------- | -------------------------------------------------------- | |
| 83 | +| No marketplace field | You want Codex app-server to use marketplaces it already knows. | Yes, when app-server returns a local marketplace. | |
| 84 | +| `marketplaceSource` | You have a Codex marketplace source app-server can add. | Yes, for explicit `/codex computer-use install`. | |
| 85 | +| `marketplacePath` | You already know the local marketplace file path on the host. | Yes, for explicit install and turn-start auto-install. | |
| 86 | +| `marketplaceName` | You want to select one already registered marketplace by name. | Yes only when the selected marketplace has a local path. | |
| 87 | + |
| 88 | +Fresh Codex homes may need a short moment to seed their official marketplaces. |
| 89 | +During install, OpenClaw polls `plugin/list` for up to |
| 90 | +`marketplaceDiscoveryTimeoutMs` milliseconds. The default is 60 seconds. |
| 91 | + |
| 92 | +If multiple known marketplaces contain Computer Use, OpenClaw prefers |
| 93 | +`openai-bundled`, then `openai-curated`, then `local`. Unknown ambiguous matches |
| 94 | +fail closed and ask you to set `marketplaceName` or `marketplacePath`. |
| 95 | + |
| 96 | +## Remote catalog limit |
| 97 | + |
| 98 | +Codex app-server can list and read remote-only catalog entries, but it does not |
| 99 | +currently support remote `plugin/install`. That means `marketplaceName` can |
| 100 | +select a remote-only marketplace for status checks, but installs and re-enables |
| 101 | +still need a local marketplace via `marketplaceSource` or `marketplacePath`. |
| 102 | + |
| 103 | +If status says the plugin is available in a remote Codex marketplace but remote |
| 104 | +install is unsupported, run install with a local source or path: |
| 105 | + |
| 106 | +```text |
| 107 | +/codex computer-use install --source <marketplace-source> |
| 108 | +/codex computer-use install --marketplace-path <path> |
| 109 | +``` |
| 110 | + |
| 111 | +## Configuration reference |
| 112 | + |
| 113 | +| Field | Default | Meaning | |
| 114 | +| ------------------------------- | -------------- | ------------------------------------------------------------------------------ | |
| 115 | +| `enabled` | inferred | Require Computer Use. Defaults to true when another Computer Use field is set. | |
| 116 | +| `autoInstall` | false | Install or re-enable from already discovered marketplaces at turn start. | |
| 117 | +| `marketplaceDiscoveryTimeoutMs` | 60000 | How long install waits for Codex app-server marketplace discovery. | |
| 118 | +| `marketplaceSource` | unset | Source string passed to Codex app-server `marketplace/add`. | |
| 119 | +| `marketplacePath` | unset | Local Codex marketplace file path containing the plugin. | |
| 120 | +| `marketplaceName` | unset | Registered Codex marketplace name to select. | |
| 121 | +| `pluginName` | `computer-use` | Codex marketplace plugin name. | |
| 122 | +| `mcpServerName` | `computer-use` | MCP server name exposed by the installed plugin. | |
| 123 | + |
| 124 | +Turn-start auto-install intentionally refuses configured `marketplaceSource` |
| 125 | +values. Adding a new source is an explicit setup operation, so use |
| 126 | +`/codex computer-use install --source <marketplace-source>` once, then let |
| 127 | +`autoInstall` handle future re-enables from discovered local marketplaces. |
| 128 | + |
| 129 | +## What OpenClaw checks |
| 130 | + |
| 131 | +OpenClaw reports a stable setup reason internally and formats the user-facing |
| 132 | +status for chat: |
| 133 | + |
| 134 | +| Reason | Meaning | Next step | |
| 135 | +| ---------------------------- | ------------------------------------------------------ | --------------------------------------------- | |
| 136 | +| `disabled` | `computerUse.enabled` resolved to false. | Set `enabled` or another Computer Use field. | |
| 137 | +| `marketplace_missing` | No matching marketplace was available. | Configure source, path, or marketplace name. | |
| 138 | +| `plugin_not_installed` | Marketplace exists, but the plugin is not installed. | Run install or enable `autoInstall`. | |
| 139 | +| `plugin_disabled` | Plugin is installed but disabled in Codex config. | Run install to re-enable it. | |
| 140 | +| `remote_install_unsupported` | Selected marketplace is remote-only. | Use `marketplaceSource` or `marketplacePath`. | |
| 141 | +| `mcp_missing` | Plugin is enabled, but the MCP server is unavailable. | Check Codex Computer Use and OS permissions. | |
| 142 | +| `ready` | Plugin and MCP tools are available. | Start the Codex-mode turn. | |
| 143 | +| `check_failed` | A Codex app-server request failed during status check. | Check app-server connectivity and logs. | |
| 144 | +| `auto_install_blocked` | Turn-start setup would need to add a new source. | Run explicit install first. | |
| 145 | + |
| 146 | +The chat output includes the plugin state, MCP server state, marketplace, tools |
| 147 | +when available, and the specific message for the failing setup step. |
| 148 | + |
| 149 | +## macOS permissions |
| 150 | + |
| 151 | +Computer Use is macOS-specific. The Codex-owned MCP server may need local OS |
| 152 | +permissions before it can inspect or control apps. If OpenClaw says Computer Use |
| 153 | +is installed but the MCP server is unavailable, verify the Codex-side Computer |
| 154 | +Use setup first: |
| 155 | + |
| 156 | +- Codex app-server is running on the same host where desktop control should |
| 157 | + happen. |
| 158 | +- The Computer Use plugin is enabled in Codex config. |
| 159 | +- The `computer-use` MCP server appears in Codex app-server MCP status. |
| 160 | +- macOS has granted the required permissions for the desktop-control app. |
| 161 | +- The current host session can access the desktop being controlled. |
| 162 | + |
| 163 | +OpenClaw intentionally fails closed when `computerUse.enabled` is true. A |
| 164 | +Codex-mode turn should not silently proceed without the native desktop tools |
| 165 | +that the config required. |
| 166 | + |
| 167 | +## Troubleshooting |
| 168 | + |
| 169 | +**Status says not installed.** Run `/codex computer-use install`. If the |
| 170 | +marketplace is not discovered, pass `--source` or `--marketplace-path`. |
| 171 | + |
| 172 | +**Status says installed but disabled.** Run `/codex computer-use install` again. |
| 173 | +Codex app-server install writes the plugin config back to enabled. |
| 174 | + |
| 175 | +**Status says remote install is unsupported.** Use a local marketplace source or |
| 176 | +path. Remote-only catalog entries can be inspected but not installed through the |
| 177 | +current app-server API. |
| 178 | + |
| 179 | +**Status says the MCP server is unavailable.** Re-run install once so MCP |
| 180 | +servers reload. If it remains unavailable, fix the Codex Computer Use app, |
| 181 | +Codex app-server MCP status, or macOS permissions. |
| 182 | + |
| 183 | +**Turn-start auto-install refuses a source.** This is intentional. Add the |
| 184 | +source with explicit `/codex computer-use install --source <marketplace-source>` |
| 185 | +first, then future turn-start auto-install can use the discovered local |
| 186 | +marketplace. |
0 commit comments