Codex Computer Use

Computer Use is a Codex-native MCP plugin for local desktop control. OpenClaw does not vendor the desktop app, execute desktop actions itself, or bypass Codex permissions. The bundled

plugin only prepares Codex app-server: it enables Codex plugin support, finds or installs the configured Codex Computer Use plugin, checks that the MCP server is available, and then lets Codex own the native MCP tool calls during Codex-mode turns.

Use this page when OpenClaw is already using the native Codex harness. For the runtime setup itself, see Codex harness.

OpenClaw.app and Peekaboo

OpenClaw.app's Peekaboo integration is separate from Codex Computer Use. The macOS app can host a PeekabooBridge socket so the

CLI can reuse the app's local Accessibility and Screen Recording grants for Peekaboo's own automation tools. That bridge does not install or proxy Codex Computer Use, and Codex Computer Use does not call through the PeekabooBridge socket.

Use Peekaboo bridge when you want OpenClaw.app to be a permission-aware host for Peekaboo CLI automation. Use this page when a Codex-mode OpenClaw agent should have Codex's native

MCP plugin available before the turn starts.

iOS app

The iOS app is separate from Codex Computer Use. It does not install or proxy the Codex

MCP server and it is not a desktop-control backend. Instead, the iOS app connects as an OpenClaw node and exposes mobile capabilities through node commands such as , , , , and .

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

Direct cua-driver MCP

Codex Computer Use is not the only way to expose desktop control. If you want OpenClaw-managed runtimes to call TryCua's driver directly, use the upstream

server through OpenClaw's MCP registry instead of the Codex-specific marketplace flow.

After installing

, either ask it for the OpenClaw command:

bash
Copy
cua-driver mcp-config --client openclaw

or register the stdio server yourself:

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

That path keeps the upstream MCP tool surface intact, including the driver schemas and structured MCP responses. Use it when you want the CUA driver available as a normal OpenClaw MCP server. Use the Codex Computer Use setup on this page when Codex app-server should own plugin installation, MCP reloads, and native tool calls inside Codex-mode turns.

CUA's driver is macOS-specific and still requires the local macOS permissions that its app prompts for, such as Accessibility and Screen Recording. OpenClaw does not install

, grant those permissions, or bypass the upstream driver's safety model.

Quick setup

Set

when Codex-mode turns must have Computer Use available before a thread starts:

json5
Copy
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          computerUse: {
            autoInstall: true,
          },
        },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
        fallback: "none",
      },
    },
  },
}

With this config, OpenClaw checks Codex app-server before each Codex-mode turn. If Computer Use is missing but Codex app-server has already discovered an installable marketplace, OpenClaw asks Codex app-server to install or re-enable the plugin and reload MCP servers. On macOS, when no matching marketplace is registered and the standard Codex app bundle exists, OpenClaw also tries to register the bundled Codex marketplace from

before it fails. If setup still cannot make the MCP server available, the turn fails before the thread starts.

Existing sessions keep their runtime and Codex thread binding. After changing

or Computer Use config, use or in the affected chat before testing.

Commands

Use the

commands from any chat surface where the plugin command surface is available. These are OpenClaw chat/runtime commands, not CLI subcommands:

text
Copy
/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>

is read-only. It does not add marketplace sources, install plugins, or enable Codex plugin support.

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.

Marketplace choices

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

.

Fresh Codex homes may need a short moment to seed their official marketplaces. During install, OpenClaw polls

for up to milliseconds. The default is 60 seconds.

If multiple known marketplaces contain Computer Use, OpenClaw prefers

, then , then . Unknown ambiguous matches fail closed and ask you to set or .

Bundled macOS marketplace

Recent Codex desktop builds bundle Computer Use here:

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

When

is true and no marketplace containing is registered, OpenClaw tries to add the standard bundled marketplace root automatically:

text
Copy
/Applications/Codex.app/Contents/Resources/plugins/openai-bundled

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

bash
Copy
codex plugin marketplace add /Applications/Codex.app/Contents/Resources/plugins/openai-bundled

If you use a nonstandard Codex app path, set

to a local marketplace file path or run once.

Remote catalog limit

Codex app-server can list and read remote-only catalog entries, but it does not currently support remote

. That means can select a remote-only marketplace for status checks, but installs and re-enables still need a local marketplace via or .

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

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

Configuration reference

Turn-start auto-install intentionally refuses configured

values. Adding a new source is an explicit setup operation, so use once, then let handle future re-enables from discovered local marketplaces. Turn-start auto-install can use a configured , because that is already a local path on the host.

What OpenClaw checks

OpenClaw reports a stable setup reason internally and formats the user-facing status for chat:

The chat output includes the plugin state, MCP server state, marketplace, 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:

• Codex app-server is running on the same host where desktop control should happen.
• The Computer Use plugin is enabled in Codex config.
• The
  text

  Copy

  computer-use
  MCP server appears in Codex app-server MCP status.
• macOS has granted the required permissions for the desktop-control app.
• The current host session can access the desktop being controlled.

OpenClaw intentionally fails closed when

is true. A Codex-mode turn should not silently proceed without the native desktop tools that the config required.

Troubleshooting

Status says not installed. Run

. If the marketplace is not discovered, pass or .

Status says installed but disabled. Run

again. Codex app-server install writes the plugin config back to enabled.

Status says remote install is unsupported. 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 install once so MCP servers reload. If it remains unavailable, fix the Codex Computer Use app, Codex app-server MCP status, or macOS permissions.

Status or a probe times out on

. The plugin and MCP server are present, but the local Computer Use bridge did not answer. Quit or restart Codex Computer Use, relaunch Codex Desktop if needed, then retry in a fresh OpenClaw session.

A Computer Use tool says

. The Codex-native tool hook could not reach an active OpenClaw relay through the local bridge or Gateway fallback. Start a fresh OpenClaw session with or . If it keeps happening, restart the gateway so old app-server threads and hook registrations are dropped, then retry.

Turn-start auto-install refuses a source. This is intentional. Add the source with explicit

first, then future turn-start auto-install can use the discovered local marketplace.