codex plugin only prepares Codex app-server:
it enables Codex plugin support, finds or installs the configured Computer Use
plugin, checks that the computer-use 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 thepeekaboo 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 computer-use 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 Codexcomputer-use 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 canvas.*, camera.*, screen.*,
location.*, and talk.*.
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 upstreamcua-driver mcp server through OpenClaw’s MCP registry instead of the
Codex-specific marketplace flow.
After installing cua-driver, either ask it for the OpenClaw command:
cua-driver, grant those permissions, or bypass the upstream
driver’s safety model.
Quick setup
Setplugins.entries.codex.config.computerUse when Codex-mode turns must have
Computer Use available before a thread starts. autoInstall: true opts
Computer Use in and lets OpenClaw install or re-enable it before the turn:
/Applications/Codex.app/Contents/Resources/plugins/openai-bundled before it
fails. If setup still cannot make the MCP server available, the turn fails
before the thread starts.
After changing Computer Use config, use /new or /reset in the affected
chat before testing if an existing Codex thread has already started.
On macOS managed stdio startup, OpenClaw prefers the signed desktop Codex app
bundle at /Applications/Codex.app/Contents/Resources/codex when it exists.
That keeps Computer Use under the app bundle that owns the local
desktop-control permissions. If the desktop app is not installed, OpenClaw
falls back to the managed Codex binary installed beside the plugin. If an
installed desktop app initializes with an unsupported app-server version,
OpenClaw closes that child and retries the next managed binary candidate
instead of letting a stale desktop app shadow the plugin-local fallback.
Explicit appServer.command config or OPENCLAW_CODEX_APP_SERVER_BIN still
overrides this managed selection.
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:
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.
Marketplace choices
OpenClaw uses the same app-server API that Codex itself exposes. The marketplace fields choose where Codex should findcomputer-use.
| Field | Use when | Install support |
|---|---|---|
| No marketplace field | You want Codex app-server to use marketplaces it already knows. | Yes, when app-server returns a local marketplace. |
marketplaceSource | You have a Codex marketplace source app-server can add. | Yes, for explicit /codex computer-use install. |
marketplacePath | You already know the local marketplace file path on the host. | Yes, for explicit install and turn-start auto-install. |
marketplaceName | You want to select one already registered marketplace by name. | Yes only when the selected marketplace has a local path. |
plugin/list for up to
marketplaceDiscoveryTimeoutMs milliseconds (default 60 seconds).
If multiple known marketplaces contain Computer Use, OpenClaw prefers
openai-bundled, then openai-curated, then local. Unknown ambiguous
matches fail closed and ask you to set marketplaceName or
marketplacePath.
Bundled macOS marketplace
Recent Codex desktop builds bundle Computer Use here:computerUse.autoInstall is true and no marketplace containing
computer-use is registered, OpenClaw tries to add the standard bundled
marketplace root automatically:
/codex computer-use install --source <marketplace-root> once, or set computerUse.marketplacePath to a
local marketplace file path. Use --marketplace-path only when you have the
marketplace JSON file path, not the bundled marketplace root.
Remote catalog limit
Codex app-server can list and read remote-only catalog entries, but it does not currently support remoteplugin/install. That means marketplaceName
can select a remote-only marketplace for status checks, but installs and
re-enables still need a local marketplace via marketplaceSource or
marketplacePath.
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:
Configuration reference
| Field | Default | Meaning |
|---|---|---|
enabled | inferred | Require Computer Use. Defaults to true when another Computer Use field is set. |
autoInstall | false | Install or re-enable from already discovered marketplaces at turn start. |
marketplaceDiscoveryTimeoutMs | 60000 | How long install waits for Codex app-server marketplace discovery. |
marketplaceSource | unset | Source string passed to Codex app-server marketplace/add. |
marketplacePath | unset | Local Codex marketplace file path containing the plugin. |
marketplaceName | unset | Registered Codex marketplace name to select. |
pluginName | computer-use | Codex marketplace plugin name. |
mcpServerName | computer-use | MCP server name exposed by the installed plugin. |
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:
| Field | Env var |
|---|---|
enabled | OPENCLAW_CODEX_COMPUTER_USE |
autoInstall | OPENCLAW_CODEX_COMPUTER_USE_AUTO_INSTALL |
marketplaceDiscoveryTimeoutMs | OPENCLAW_CODEX_COMPUTER_USE_MARKETPLACE_DISCOVERY_TIMEOUT_MS |
marketplaceSource | OPENCLAW_CODEX_COMPUTER_USE_MARKETPLACE_SOURCE |
marketplacePath | OPENCLAW_CODEX_COMPUTER_USE_MARKETPLACE_PATH |
marketplaceName | OPENCLAW_CODEX_COMPUTER_USE_MARKETPLACE_NAME |
pluginName | OPENCLAW_CODEX_COMPUTER_USE_PLUGIN_NAME |
mcpServerName | OPENCLAW_CODEX_COMPUTER_USE_MCP_SERVER_NAME |
What OpenClaw checks
OpenClaw reports a stable setup reason internally and formats the user-facing status for chat:| Reason | Meaning | Next step |
|---|---|---|
disabled | computerUse.enabled resolved to false. | Set enabled or another Computer Use field. |
marketplace_missing | No matching marketplace was available. | Configure source, path, or marketplace name. |
plugin_not_installed | Marketplace exists, but the plugin is not installed. | Run install or enable autoInstall. |
plugin_disabled | Plugin is installed but disabled in Codex config. | Run install to re-enable it. |
remote_install_unsupported | Selected marketplace is remote-only. | Use marketplaceSource or marketplacePath. |
mcp_missing | Plugin is enabled, but the MCP server is unavailable. | Check Codex Computer Use and OS permissions. |
ready | Plugin and MCP tools are available. | Start the Codex-mode turn. |
check_failed | A Codex app-server request failed during status check. | Check app-server connectivity and logs. |
auto_install_blocked | Turn-start setup would need to add a new source. | Run explicit install first. |
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
computer-useMCP 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.
computerUse.enabled 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/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. 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 computer-use.list_apps. 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. If the host previously ran Computer Use
through an older managed Codex app-server, refresh the installed plugin from
the desktop bundled marketplace:
Native hook relay unavailable. 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 /new
or /reset. If it works once and then fails again on a later tool call,
/new is only clearing the current attempt; restart the Codex app-server or
OpenClaw Gateway so old threads and hook registrations are dropped, then
retry in a fresh session.
Turn-start auto-install refuses a source. This is intentional. Add the
source with explicit /codex computer-use install --source <marketplace-source> first, then future turn-start auto-install can use the
discovered local marketplace.