Codex Computer Use Setup for OpenClaw Agents

Computer Use is a Codex-native MCP plugin that handles local desktop control. OpenClaw does not ship the desktop app, perform desktop actions on its own, or circumvent Codex permissions. The included codex plugin only prepares the Codex app-server: it activates Codex plugin support, locates or installs the configured Computer Use plugin, confirms that the computer-use MCP server is reachable, and then hands off native MCP tool calls to Codex during Codex-mode turns.

Refer to this page when OpenClaw is operating with the native Codex harness. For runtime configuration details, see Codex harness.

This differs from OpenClaw's integrated node-backed computer tool. Choose the built-in tool when the same agent contract should drive a paired Mac regardless of whether the agent runs on the Gateway or another node. Choose Codex Computer Use when the Codex app-server should take charge of local MCP installation, permissions, and native tool calls.

OpenClaw.app and Peekaboo

OpenClaw.app's Peekaboo integration is unrelated to Codex Computer Use. The macOS app can expose a PeekabooBridge socket so the peekaboo CLI can reuse the app's local Accessibility and Screen Recording grants for Peekaboo's automation tools. That bridge neither installs nor proxies Codex Computer Use, and Codex Computer Use never communicates through the PeekabooBridge socket.

Use Peekaboo bridge when you want OpenClaw.app to serve as a permission-aware host for Peekaboo CLI automation. Use this page when a Codex-mode OpenClaw agent should have Codex's native computer-use MCP plugin available before the turn begins.

iOS app

The iOS app is distinct from Codex Computer Use. It neither installs nor proxies the Codex computer-use MCP server, and it does not act as a desktop-control backend. Instead, the iOS app joins as an OpenClaw node and offers mobile capabilities via node commands like camera.*, screen.*, location.*, and talk.*.

Use 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 via Codex's native Computer Use plugin.

Direct cua-driver MCP

Codex Computer Use is not the sole method for exposing desktop control. If you want OpenClaw-managed runtimes to invoke TryCua's driver directly, use the upstream cua-driver mcp server through OpenClaw's MCP registry rather than the Codex-specific marketplace flow.

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

cua-driver mcp-config --client openclaw

or register the stdio server directly:

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

That approach preserves the upstream MCP tool surface intact, including the driver schemas and structured MCP responses. Choose it when you want the CUA driver available as a standard OpenClaw MCP server. Choose the Codex Computer Use setup on this page when the Codex app-server should handle 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 depends on the local OS permissions its app 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

Set plugins.entries.codex.config.computerUse when Codex-mode turns must have Computer Use available before a thread starts. autoInstall: true opts Computer Use in and allows OpenClaw to install or re-enable 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 inspects 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 asks the Codex app-server to install or re-enable the plugin and reload MCP servers. Before launching an isolated Codex app-server on macOS, auto-install also places the official signed Computer Use service app from the selected desktop app bundle into that Codex home's computer-use directory. OpenClaw validates the outer service and nested client signatures, bundle identities, versions, builds, and code hashes. It installs a missing or incomplete copy, or stages and verifies a replacement before swapping out a complete copy whose signed identity no longer matches the selected desktop distribution. Failed swaps roll back without altering the rest of the isolated Codex home. This native-app synchronization runs only for OpenClaw-owned isolated agent homes. User-scoped homes and explicit CODEX_HOME overrides keep their existing native bundle ownership. The agent directory is the trusted ownership boundary. Within it, native-service provisioning rejects symlinked Codex-home, computer-use, and service-app paths, and revalidates the owned parent around each staged swap. 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 installs. 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 Codex candidate. A candidate resolved to another harness remains eligible and enters that runtime through its normal policy checks.

After modifying Computer Use config, 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 installs. 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 stay desktop-first because they can load native Computer Use state. An isolated agent home whose effective Codex config enables Computer Use also stays desktop-first. Explicit appServer.command config or OPENCLAW_CODEX_APP_SERVER_BIN still overrides this managed selection.

OpenClaw serializes native Codex config reads and Computer Use installation inside one running Gateway. A separate Codex process or another Gateway is not part of that fence. After changing native Codex plugin config outside the Gateway, restart the Gateway and start a new chat before relying on the new selection. Restart the Gateway after updating the selected ChatGPT or Codex desktop app as well; cold app-server startup then verifies and, when needed, refreshes each isolated home's signed Computer Use service before launching it. Warm clients are intentionally not polled for desktop bundle changes.

Commands

Use the /codex computer-use commands from any chat surface where the codex plugin command surface is available. These are OpenClaw chat/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 config 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 re-enables the configured plugin through Codex app-server, reloads MCP servers, and verifies 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

The app-server API that Codex exposes is the same one OpenClaw relies on. Which marketplace Codex should search for computer-use is determined by the marketplace fields.

A freshly created Codex home might need a brief delay to populate its official marketplaces. While installing, OpenClaw polls plugin/list for as long as marketplaceDiscoveryTimeoutMs milliseconds, which defaults to 60 seconds.

When several known marketplaces carry Computer Use, the order of preference is openai-bundled, followed by openai-curated, and then local. Ambiguous matches that are not recognized fail closed, prompting you to specify either marketplaceName or marketplacePath.

Bundled macOS marketplace

Computer Use is bundled in current ChatGPT desktop builds at this location; the same layout applies to legacy standalone Codex desktop builds 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

If computerUse.autoInstall is set to true and no registered marketplace includes 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

From a shell, you can also register it explicitly with Codex:

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

For a nonstandard Codex app path, run /codex computer-use install --source <marketplace-root> once, or point 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

By default, pluginCacheMode: "independent" leaves each Codex home and its plugin cache untouched. To copy the bundled Computer Use plugin into the active Codex home's discoverable plugin cache before app-server startup, set pluginCacheMode: "shared". Shared mode keeps older cached versions intact, since running Codex clients may still reference their versioned plugin directories; a failed replacement copy also leaves the active cache unchanged. Setting marketplaceName or marketplacePath explicitly disables this reconciliation, so OpenClaw will not override that choice.

Remote marketplaces

Codex 0.146.1 introduced remote marketplace support, and it remains available in OpenClaw's pinned Codex 0.148.0. The opaque remote plugin ID that Codex returns is passed by OpenClaw to plugin/read and plugin/install; a human-readable plugin name cannot be used in its place.

A discovered remote plugin can be explicitly installed or re-enabled via /codex computer-use install. Turn-start autoInstall can also make use of a local or remote marketplace that has already been discovered. Status checks and turns without autoInstall do not install plugins or alter Codex configuration.

Configuration reference

Configured marketplaceSource values are deliberately rejected by turn-start auto-install. Because adding a new source counts as an explicit setup action, run /codex computer-use install --source <marketplace-source> once, then let autoInstall manage future re-enables from discovered local or remote marketplaces. A configured marketplacePath is acceptable for turn-start auto-install, since it is already a local path on the host.

Each field can also be overridden by an environment variable, which is consulted only when the corresponding config key has not been set:

What OpenClaw checks

Internally, OpenClaw records a fixed setup reason and then builds the status text shown to users in chat:

The chat output shows the plugin state, MCP server state, marketplace, tools when present, and the exact message tied to the failing setup step.

macOS permissions

This Codex-owned Computer Use path operates on macOS, where the MCP server may require 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.) If OpenClaw indicates Computer Use is installed but the MCP server is unavailable, check the Codex-side Computer Use setup first:

• The Codex app-server runs on the same host where desktop control should occur.
• The Computer Use plugin is enabled in the Codex config.
• The computer-use MCP server shows up in the Codex app-server MCP status.
• macOS has granted the necessary permissions for the desktop-control app.
• The current host session can reach the desktop under control.

OpenClaw deliberately fails closed when computerUse.enabled is true. A Codex-mode turn should not silently continue without the native desktop tools that the config demanded.

Troubleshooting

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

Status reports installed but disabled. Run /codex computer-use install once more. The Codex app-server install rewrites the plugin config to enabled.

A discovered remote plugin cannot be installed. Verify Codex lists the marketplace and the plugin's opaque remote ID, then run /codex computer-use install. Introduce a new marketplaceSource only via explicit install; turn-start autoInstall relies on remote marketplaces already discovered by Codex.

Status reports the MCP server is unavailable. Re-run install once to reload MCP servers. If it stays unavailable, address the Codex Computer Use app, Codex app-server MCP status, or 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 try again 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

A Computer Use tool returns Native hook relay unavailable.
The Codex-native tool hook failed to connect to an active OpenClaw relay, whether through the local bridge or the Gateway fallback. Begin a new OpenClaw session using /new or /reset. If the tool succeeds once but fails again on a subsequent call, /new only resets the current attempt; restart the Codex app-server or OpenClaw Gateway to clear stale threads and hook registrations, then try again in a fresh session.

Turn-start auto-install rejects a source. This behavior is by design. First, add the source explicitly with /codex computer-use install --source <marketplace-source>, after which future turn-start auto-install can utilize the discovered local or remote marketplace.

Related

• Codex harness
• Peekaboo bridge
• iOS app