Complete Guide to Using Codex Computer Use with OpenClaw

What This Guide Covers

This guide walks through the complete process of getting OpenClaw to drive Codex Computer Use on macOS — from installing the Codex desktop app and configuring system permissions, through MCP server integration, to letting the agent actually take control of your machine. By the end, your OpenClaw should be able to invoke GUI control directly via /codex.

Important prerequisite: Computer Use is macOS-only. Windows and Linux are not supported, and the last section explains why.

1. What Is Computer Use

Computer Use is OpenAI Codex's GUI control capability. It lets an AI agent directly operate your Mac — clicking buttons, typing text, opening applications, performing actions, just as if a real user were sitting at the keyboard.

The full call chain looks like this:

Codex App (desktop / app-server)
    ↓
Computer Use MCP server
    ↓
OpenClaw /codex plugin

Note: Computer Use is not a CLI feature.

It depends on /Applications/Codex.app running in the background as a local app-server, which exposes control capabilities via the MCP protocol so OpenClaw's /codex plugin can call into them. npm install -g @openai/codex installs the command-line tool, which is a different thing entirely — don't confuse the two.

2. System Requirements

If any of these are missing, get them sorted before going further.

3. Install the Codex Desktop App

Download and install Codex.app from the official OpenAI distribution channel. After installing, confirm the app lives at:

/Applications/Codex.app

If you installed it somewhere non-default (a dev folder, an external drive, etc.), register it manually with the marketplace:

codex plugin marketplace add /path/to/Codex.app

Launch Codex once and make sure its app-server is running in the background. The app-server has to stay running — everything downstream depends on it. Quit Codex and Computer Use stops working.

4. macOS Permissions

Computer Use needs two macOS permissions, and both are mandatory. This is the step most people get stuck on, so go through it carefully.

1. Grant Accessibility Permission

1. Open System Settings → Privacy & Security → Accessibility
2. Find Codex in the list
3. Toggle the switch on

2. Grant Screen Recording Permission

1. Open System Settings → Privacy & Security → Screen Recording & System Audio
2. Find Codex in the list
3. Toggle the switch on

Tip: If permissions don't seem to take effect after toggling, fully quit Codex.app (Cmd+Q to kill the process — closing the window isn't enough) and relaunch it. macOS occasionally needs a process restart to pick up permission changes.

The permission must be granted to Codex itself, not Terminal, not iTerm, not any other shell. If you grant it to the wrong app, Codex will still error out as if it had no permission at all.

5. Install the Computer Use Component

Once permissions are set, hop back to OpenClaw and run:

/codex computer-use install

This downloads and installs the Computer Use MCP server, then registers it with the OpenClaw plugin system.

Verify Installation

After the install finishes, run:

/codex computer-use status

You should see something like:

✓ Codex app-server: running
✓ Computer Use MCP server: online
✓ OpenClaw plugin binding: active

Three green checks means you're good. If anything looks off, go back to section 4 and double-check permissions, or skip down to section 9 for troubleshooting.

6. OpenClaw Integration Config

After installation, add two snippets to OpenClaw's settings.json so Codex Computer Use can actually take over the agent runtime.

1. Enable Auto-Install for Computer Use

{
  "plugins": {
    "entries": {
      "codex": {
        "config": {
          "computerUse": {
            "autoInstall": true
          }
        }
      }
    }
  }
}

autoInstall: true means: next time OpenClaw starts up, if it finds the Computer Use MCP server isn't running, it'll re-install automatically — you don't have to remember to rerun the install command yourself.

2. Configure the Agent Runtime

{
  "agentRuntime": {
    "id": "codex",
    "fallback": "none"
  }
}

fallback: "none" is the important bit: if the Codex app-server isn't reachable, OpenClaw will not silently downgrade to a different runtime — it'll throw an error instead. This is what you want, because it surfaces problems immediately rather than letting you think you're using Codex when you're actually running on something else.

Both snippets go into the same settings.json file. No need to split them.

7. Verify the MCP Server

One last check after the integration config.

Run:

/codex mcp

Find computer-use in the output and confirm its status is online:

NAME            TYPE    STATUS
computer-use    stdio   online
github          stdio   online

If computer-use isn't in the list, or shows offline, run the install again:

/codex computer-use install

If everything checks out at this point — congrats, you can start using Codex Computer Use. A good first try is asking the agent to open an app and click around something simple, just to confirm the loop works end to end.

8. Command Reference

The commands below are the ones you'll reach for most often:

9. Troubleshooting

1. plugin_not_installed

Cause: OpenClaw can't find the Computer Use plugin binding.

Fix:

1. Run /codex computer-use install
2. Confirm computerUse.autoInstall: true is set in settings.json
3. Restart OpenClaw

2. mcp_missing

Cause: The Computer Use MCP server isn't running, or isn't registered in the MCP list.

Fix:

1. Confirm Codex.app is running — quitting the app kills the app-server, which kills MCP
2. Run /codex mcp to check the server list
3. If computer-use is missing, run /codex computer-use install to reinstall

3. remote_install_unsupported

Cause: You're trying to install Computer Use in a remote environment — a cloud VM, an SSH session, anything that isn't a local Mac.

Fix: Computer Use only runs on local macOS. It can't run on a remote server, and it can't be driven over SSH against another Mac. You have to run it on the Mac sitting in front of you.

4. /codex computer-use install reports a permissions error

Go back to section 4 and confirm both of the following permissions are granted to the Codex app (not Terminal, not iTerm):

• Accessibility
• Screen Recording & System Audio

Granting permission to the wrong app is the most common cause of this error.

5. Can Windows / Linux Use Computer Use?

No.

Computer Use depends on macOS's Accessibility API to read the screen and synthesise clicks and keystrokes. That API is Apple-exclusive — Windows and Linux don't have an equivalent — so for now Computer Use is macOS-only.

If you're on Windows or Linux only, your options are:

• Use other OpenClaw skills (browser, tmux, etc.) instead of GUI automation
• Or keep a Mac around dedicated to Computer Use tasks

Closing Thoughts

Codex Computer Use is currently the closest thing OpenClaw has to "actually letting the agent use your computer for you." The install isn't really complicated — the two things that trip people up are granting permissions to the wrong app and letting Codex.app close in the background. If you get stuck, check those two first, then look at MCP status; most problems land in one of those buckets.

Once it's running, try having the agent walk through some repetitive desktop workflow — opening apps, filling forms, tidying folders. It's a fundamentally different interaction style from CLI, and worth spending an evening getting comfortable with.