Codex Computer Use Plugin Setup for OpenClaw Agents

Computer Use is a plugin built into Codex that enables local desktop control through the MCP protocol. OpenClaw does not distribute a desktop application, perform desktop actions directly, or circumvent Codex's permission system. The included codex plugin solely prepares the Codex app-server environment: it activates Codex plugin support, locates or installs the designated Computer Use plugin, confirms that the computer-use MCP server is running, and then allows Codex to manage native MCP tool calls during Codex-mode interactions.

Refer to this page only when OpenClaw is already operating with the native Codex harness. For details on the runtime configuration itself, consult the Codex harness.

This setup differs from OpenClaw's integrated node-backed computer tool. Choose the built-in tool when a consistent agent contract should manage a paired Mac regardless of whether the agent runs on the Gateway or a different node. Opt for Codex Computer Use when the Codex app-server should handle local MCP installation, permissions, and native tool calls.

OpenClaw.app and Peekaboo

The Peekaboo integration within OpenClaw.app is distinct from Codex Computer Use. The macOS application can host a PeekabooBridge socket, allowing the peekaboo CLI to reuse the app's local Accessibility and Screen Recording permissions for Peekaboo's automation tools. This bridge neither installs nor proxies Codex Computer Use, and Codex Computer Use does not communicate through the PeekabooBridge socket.

Choose Peekaboo bridge when you need OpenClaw.app to function as a permission-aware host for Peekaboo CLI automation. Use this page when a Codex-mode OpenClaw agent requires Codex's native computer-use MCP plugin to be ready before the turn starts.

iOS app

The iOS application is separate from Codex Computer Use. It does not install or proxy the Codex computer-use MCP server and does not serve as a desktop control backend. Instead, the iOS app connects as an OpenClaw node and provides mobile capabilities through node commands like canvas.*, camera.*, screen.*, location.*, and talk.*.

Select iOS when you want an agent to control an iPhone node through the gateway. Use this page when a Codex-mode agent should manage the local macOS desktop using Codex's native Computer Use plugin.

Direct cua-driver MCP

Codex Computer Use is not the exclusive method for exposing desktop control. If you prefer OpenClaw-managed runtimes to invoke TryCua's driver directly, use the upstream cua-driver mcp server via OpenClaw's MCP registry instead of the Codex-specific marketplace process.

After installing cua-driver, either request the OpenClaw command:

cua-driver mcp-config --client openclaw

or register the stdio server directly:

openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'

This approach preserves the upstream MCP tool interface, including driver schemas and structured MCP responses. Use it when you want the CUA driver accessible as a standard OpenClaw MCP server. Choose the Codex Computer Use setup on this page when the Codex app-server should manage plugin installation, MCP reloads, and native tool calls within Codex-mode turns.

CUA's driver ships prerelease builds for macOS, Windows (x64 and ARM64), and Linux (x64 and ARM64, preview tier). It still requires the local OS permissions its application requests, such as Accessibility and Screen Recording on macOS. OpenClaw does not install cua-driver, grant those permissions, or bypass the upstream driver's safety model.

Quick setup

Configure plugins.entries.codex.config.computerUse when Codex-mode turns must have Computer Use available before a thread starts. autoInstall: true enables Computer Use and allows OpenClaw to install or reactivate it before the turn:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          computerUse: {
            autoInstall: true,
          },
        },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.6-sol",
    },
  },
}

With this configuration, OpenClaw checks the Codex app-server before each Codex-mode turn. If Computer Use is absent but the Codex app-server has already found an installable marketplace, OpenClaw requests that the Codex app-server install or reactivate the plugin and reload MCP servers. Before starting an isolated Codex app-server on macOS, auto-install also copies the official signed Computer Use service app from the selected desktop app bundle into that Codex home's computer-use directory when the native client is missing. On macOS, when no matching marketplace is registered and a standard desktop app bundle exists, OpenClaw also attempts to register the bundled Codex marketplace from /Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled, with /Applications/Codex.app/Contents/Resources/plugins/openai-bundled kept as a fallback for legacy standalone installations. If setup still cannot make the MCP server available, the turn fails before the thread starts. Strict readiness failures are harness preflight failures, so model fallback does not repeat the same local readiness sequence for every model candidate.

After modifying the Computer Use configuration, use /new or /reset in the affected chat before testing if an existing Codex thread has already started.

On macOS, managed startup for Computer Use prefers the desktop app binary at /Applications/ChatGPT.app/Contents/Resources/codex, then falls back to /Applications/Codex.app/Contents/Resources/codex for legacy standalone installations. This also applies to one-off Computer Use status and install commands that start their own client. It keeps desktop control under the app bundle that owns the local macOS permissions. If the desktop app is not installed, OpenClaw falls back to the managed Codex binary installed beside the plugin. Ordinary managed Codex turns with the default isolated agent home prefer that pinned package first so an older desktop app cannot shadow current model support. User-scoped homes remain desktop-first because they can load native Computer Use state. An isolated agent home whose effective Codex configuration enables Computer Use also remains desktop-first. Explicit appServer.command configuration or OPENCLAW_CODEX_APP_SERVER_BIN still overrides this managed selection.

OpenClaw serializes native Codex configuration reads and Computer Use installation within a single running Gateway. A separate Codex process or another Gateway is not part of that fence. After changing native Codex plugin configuration outside the Gateway, restart the Gateway and start a new chat before relying on the new selection.

Commands

Use the /codex computer-use commands from any chat surface where the codex plugin command surface is available. These are OpenClaw chat or runtime commands, not openclaw codex ... CLI subcommands:

/codex computer-use status
/codex computer-use install
/codex computer-use install --source <marketplace-source>
/codex computer-use install --marketplace-path <path>
/codex computer-use install --marketplace <name>

status is the default action and is read-only: it does not add marketplace sources, install plugins, or enable Codex plugin support. If no configuration opts Computer Use in, status can report disabled even after a one-off install command.

install enables Codex app-server plugin support, optionally adds a configured marketplace source, installs or reactivates the configured plugin through the Codex app-server, reloads MCP servers, and confirms that the MCP server exposes tools. Because installation changes trusted host resources, only an owner or an operator.admin Gateway client can run install. Other authorized senders can continue to use the read-only status command, including with overrides.

Older releases accepted one-off --plugin, --server, and --mcp-server identity overrides. Configure computerUse.pluginName and computerUse.mcpServerName persistently instead. When a legacy identity flag is used, the command identifies the exact setting to persist and repeats the requested action plus any supported marketplace flags in its migration guidance.

Marketplace choices

OpenClaw uses the same app-server API that Codex itself exposes. The marketplace fields determine where Codex should find computer-use.

Fresh Codex homes may need a short moment to seed their official marketplaces. During install, OpenClaw polls plugin/list for up to marketplaceDiscoveryTimeoutMs milliseconds (default 60 seconds).

When multiple known marketplaces include Computer Use, OpenClaw selects openai-bundled first, followed by openai-curated, and then local. Unknown ambiguous matches fail closed, requiring you to specify either marketplaceName or marketplacePath.

Bundled macOS marketplace

Current ChatGPT desktop releases bundle Computer Use here; older standalone Codex desktop releases use the same layout under Codex.app:

/Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled/plugins/computer-use
/Applications/Codex.app/Contents/Resources/plugins/openai-bundled/plugins/computer-use

When computerUse.autoInstall is true and no registered marketplace contains computer-use, OpenClaw attempts to add the first standard bundled marketplace root that is present:

/Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled
/Applications/Codex.app/Contents/Resources/plugins/openai-bundled

You can also register it explicitly from a shell using Codex:

codex plugin marketplace add /Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled

If your Codex app path is nonstandard, run /codex computer-use install --source <marketplace-root> once, or set computerUse.marketplacePath to a local marketplace file path. Only use --marketplace-path when you have the marketplace JSON file path, not the bundled marketplace root.

Shared plugin cache

The default pluginCacheMode: "independent" leaves each Codex home and its plugin cache unmanaged. Set pluginCacheMode: "shared" to copy the bundled Computer Use plugin into the active Codex home's discoverable plugin cache before app-server startup. Shared mode keeps older cached versions intact because running Codex clients can still reference their versioned plugin directories; a failed replacement copy also preserves the active cache. Explicit marketplaceName or marketplacePath configuration disables this reconciliation so OpenClaw does not override that choice.

Remote catalog limit

Codex app-server can list and read remote-only catalog entries, but it does not currently support remote plugin/install. Consequently, marketplaceName can select a remote-only marketplace for status checks, but installs and re-enables still require a local marketplace via marketplaceSource or marketplacePath.

If status shows the plugin is available in a remote Codex marketplace but remote install is not supported, run install with a local source or path:

/codex computer-use install --source <marketplace-source>
/codex computer-use install --marketplace-path <path>

Configuration reference

Turn-start auto-install intentionally refuses configured marketplaceSource values. Adding a new source is an explicit setup operation, so use /codex computer-use install --source <marketplace-source> once, then let autoInstall handle future re-enables from discovered local marketplaces. Turn-start auto-install can use a configured marketplacePath, because that is already a local path on the host.

Each field also accepts an environment variable override, checked when the matching config key is unset.

What OpenClaw checks

Internally, OpenClaw records a stable setup reason and formats the status shown to users in chat:

The chat output shows the plugin state, MCP server state, marketplace, tools when they are available, and the specific message for whichever setup step failed.

macOS permissions

This Codex-owned Computer Use path runs on macOS. The MCP server may need local OS permissions before it can inspect or control applications. (For cross-platform desktop control on Windows and Linux node hosts, refer to the cua-computer fulfiller.) If OpenClaw reports that Computer Use is installed but the MCP server is unavailable, first confirm the Codex-side Computer Use setup:

• The Codex app-server runs on the same host where desktop control should take place.
• The Computer Use plugin is enabled in the Codex configuration.
• The computer-use MCP server appears in the Codex app-server MCP status.
• macOS has granted the required permissions for the desktop-control application.
• The current host session can access the desktop being controlled.

OpenClaw intentionally fails closed when computerUse.enabled is true. A Codex-mode turn should not proceed silently without the native desktop tools that the configuration requires.

Troubleshooting

Status says not installed. Execute /codex computer-use install. If the marketplace is not discovered, pass --source or --marketplace-path.

Status says installed but disabled. Run /codex computer-use install again. The Codex app-server install writes the plugin configuration back to enabled.

Status says remote install is not supported. Use a local marketplace source or path. Remote-only catalog entries can be inspected but not installed through the current app-server API.

Status says the MCP server is unavailable. Re-run the install once to reload MCP servers. If it remains unavailable, fix the Codex Computer Use app, the Codex app-server MCP status, or the macOS permissions.

Status or a probe times out on computer-use.list_apps. The plugin and MCP server are present, but the local Computer Use bridge did not respond. Quit or restart Codex Computer Use, relaunch Codex Desktop if needed, then retry in a new OpenClaw session. If the host previously ran Computer Use through an older managed Codex app-server, refresh the installed plugin from the desktop bundled marketplace (use the Codex.app path for standalone Codex desktop installs):

/codex computer-use install --source /Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled

When a Computer Use tool returns Native hook relay unavailable, it means the Codex-native tool hook was unable to contact an active OpenClaw relay via either the local bridge or the Gateway fallback. To resolve this, launch a new OpenClaw session using /new or /reset. If the tool works once but then fails again during a subsequent call, note that /new only cancels the current attempt. You must restart the Codex app-server or OpenClaw Gateway to discard old threads and hook registrations, then try again in a fresh session.

Turn-start auto-install rejects a source on purpose. This behavior is by design. First, add the source explicitly with /codex computer-use install --source <marketplace-source>. After that, future turn-start auto-install operations can use the local marketplace it discovered.

Related

• Codex harness
• Peekaboo bridge
• iOS app