codex-cu

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex computer use

Codex 电脑使用

cua_repl

is the MCP server inside the ChatGPT Mac app's Computer Use plugin. Claude Code, Cursor, and agy call it under the name

codex-cu

. Clicks go into the target app. They do not move the user's pointer.

The long write-up is the Claude artifact

codex-cu 接線手冊

. Open it in Arc when this file does not answer a case.

https://claude.ai/artifact/VQQdp75aeC1PzqRwK581PU?sk=Usf3jftJdhrPrHUCB76Nuw

cua_repl

是 ChatGPT Mac 应用的 Computer Use 插件内置的 MCP 服务器。 Claude Code、Cursor 和 agy 以

codex-cu

为名调用它。点击操作会作用于目标应用，不会移动用户的鼠标指针。

详细说明文档是 Claude 工件

codex-cu 接線手冊

。当本文档无法解答某个问题时，请在 Arc 中打开它。

https://claude.ai/artifact/VQQdp75aeC1PzqRwK581PU?sk=Usf3jftJdhrPrHUCB76Nuw

Setup (once per machine)

安装设置（每台机器只需执行一次）

Codex does not need this:

cua_repl

is native there. For Claude Code, Cursor and agy, run the check first:

bash ~/.agents/skills/codex-cu/scripts/check-codex-cu.sh

PASS: setup is done. Skip this section. The check never opens an app, so a PASS is not proof that an app call works. SKIP with

no Computer Use plugin

: the user must install the ChatGPT Mac app and its Computer Use plugin, then use computer use there once (that grants Screen Recording and Accessibility). A FAIL

launcher cannot resolve a usable version

(the installer says SKIP

no usable Computer Use version yet

): show the user the reason text after the colon. Only a missing or empty plugin cache means "still downloading, try later". In both cases stop and tell them. Any other FAIL, or no

codex-cu

tool: ASK the user which mode. Never pick for them:

```
all
```
: accept every prompt from codex-cu with no question, including any that is not an app prompt. Logged-in pages in a browser app become readable.
```
safe
```
: auto-accept Calculator, TextEdit, Preview, Freeform. It is an auto-accept list, not a sandbox: Claude still asks the user for other apps and the user may accept them; agy and Cursor are refused for other apps. The browser surface has no per-app approval in either mode.

Then run:

bash ~/.agents/skills/codex-cu/scripts/install-codex-cu.sh all   # or: safe

It installs into

~/.local/bin

, registers

codex-cu

at user scope for Claude Code and Cursor when their config file exists and for agy when the

agy

command exists (the check prints a line per registered runtime), writes

~/.config/codex-cu/approve

, and ends with the check. If you cannot ask (print mode, worker), stop and show the user both commands. After setup, tell the user to start a new session: MCP servers load at session start. To switch mode later, run the installer with the other word, or edit the policy file (it takes effect at the next prompt, no restart).

The installer skips the first gate on purpose. Terminal, system settings and Codex itself stay

forbidden

until the user runs

defaults write -g ComputerUseAllowForbiddenTargets -bool YES

themselves.

Codex 无需此操作：

cua_repl

是其原生内置的。对于 Claude Code、Cursor 和 agy，请先运行检查脚本：

bash ~/.agents/skills/codex-cu/scripts/check-codex-cu.sh

PASS：设置已完成，可跳过本节。该检查不会打开任何应用，因此 PASS 不代表应用调用一定能正常工作。检查结果为 SKIP 且提示

no Computer Use plugin

：用户必须安装 ChatGPT Mac 应用及其 Computer Use 插件，然后在其中使用一次电脑使用功能（这会授予屏幕录制和辅助功能权限）。检查结果为 FAIL 且提示

launcher cannot resolve a usable version

（安装程序会显示 SKIP

no usable Computer Use version yet

）：向用户展示冒号后的原因文本。只有插件缓存缺失或为空时才意味着「仍在下载，请稍后再试」。出现以上两种情况都请停止操作并告知用户。其他任何 FAIL 情况，或不存在

codex-cu

工具时：询问用户要使用哪种模式，切勿替用户选择：

```
all
```
：无疑问地接受 codex-cu 的所有提示，包括非应用类提示。浏览器应用中的登录态页面将变为可读取状态。
```
safe
```
：自动接受计算器（Calculator）、文本编辑（TextEdit）、预览（Preview）、无边记（Freeform）。这是一个自动接受列表，而非沙箱限制：Claude 仍会就其他应用向用户请求授权，用户可以选择接受；但 agy 和 Cursor 会被拒绝访问其他应用。两种模式下，浏览器层面都没有按应用审批的机制。

然后运行：

bash ~/.agents/skills/codex-cu/scripts/install-codex-cu.sh all   # or: safe

该脚本会安装到

~/.local/bin

目录；当 Claude Code 和 Cursor 的配置文件存在时，会在用户作用域为它们注册

codex-cu

；当

agy

命令存在时，会为 agy 注册（检查脚本会为每个已注册的运行时打印一行信息）。脚本还会写入

~/.config/codex-cu/approve

文件，最后以检查步骤结束。如果你无法询问用户（如打印模式、worker 模式），请停止操作并向用户展示这两条命令。设置完成后，告知用户需要启动新会话：MCP 服务器会在会话启动时加载。后续如需切换模式，可使用另一个模式参数重新运行安装脚本，或编辑策略文件（更改会在下一次提示时生效，无需重启）。

安装程序会故意跳过第一道门禁。终端、系统设置和 Codex 本身会保持「禁止」状态，直到用户自行运行

defaults write -g ComputerUseAllowForbiddenTargets -bool YES

命令。

Two surfaces

两个操作层面

Computer surface treats the target as an app. Read the AX tree, then click or type. This surface does not need turn metadata.

scripts/codex-cu-mcp

is the launcher.

Browser surface enters the page. Read the DOM, run JS, use Playwright locators. Each

tools/call

needs Codex turn metadata.

scripts/codex-cu-proxy

injects

_meta["x-codex-turn-metadata"]

. Computer surface does not need the metadata, but its app approvals also go through the proxy (see below).

cua.getState()

can return a full

apps

list and a

browsers

error together. A metadata error on

browsers

does not mean the computer surface failed.

电脑层面（Computer surface） 将目标视为应用。读取 AX 树，然后执行点击或输入操作。该层面不需要轮次元数据（turn metadata）。启动器为

scripts/codex-cu-mcp

。

浏览器层面（Browser surface） 会进入页面内部。读取 DOM、运行 JS、使用 Playwright 定位器。每次

tools/call

都需要 Codex 轮次元数据。

scripts/codex-cu-proxy

会注入

_meta["x-codex-turn-metadata"]

。电脑层面不需要元数据，但其应用授权也会通过代理处理（见下文）。

cua.getState()

可能同时返回完整的

apps

列表和

browsers

Pick Chrome, not Arc

选择 Chrome，而非 Arc

Arc and Chrome both report

name: "Chrome"

. The numeric

id

is not stable.

profileName

can be absent. Do not use either as the only test.

Call
```
cua.listBrowsers()
```
.
Read
```
metadata.extensionInstanceId
```
.
Confirm the host parent before a long call.

ps -o ppid= -p $(pgrep -f "ChatGPT for Chrome")

The parent path is Arc or Google Chrome. Sample from 2026-10-05. Re-check after a reload. Do not reuse these values once the parent check disagrees.

Arc:
```
33f909be-429f-479e-b1c2-20bba462cbf3
```
Chrome:
```
75ef88d3-a921-455b-b39e-b40ed5ec2771
```

createBrowserTab

and

nameSession

on the Arc instance do not return. A 120s wait still fails, and the call can leave

about:blank

Arc 和 Chrome 都会返回

name: "Chrome"

。数字

id

不稳定，

profileName

可能不存在。请勿将这两者作为唯一判断依据。

调用
```
cua.listBrowsers()
```
。
读取
```
metadata.extensionInstanceId
```
。
进行长时间调用前确认宿主父进程。

ps -o ppid= -p $(pgrep -f "ChatGPT for Chrome")

父进程路径为 Arc 或 Google Chrome。以下是 2026-10-05 的示例值。重新加载后请再次检查。一旦父进程检查结果不一致，请勿再复用这些值。

Arc:
```
33f909be-429f-479e-b1c2-20bba462cbf3
```
Chrome:
```
75ef88d3-a921-455b-b39e-b40ed5ec2771
```

在 Arc 实例上调用

createBrowserTab

和

nameSession

不会返回结果。即使等待 120 秒仍会失败，且调用可能会留下

about:blank

空白页。

Browser surface

浏览器层面

Use the Chrome instance from the parent check. One

js

call per step.

```
cua.getBrowser({ extensionInstanceId })
```
.
```
browser.nameSession
```
with a short name, before any new tab.
Record ids from
```
browser.user.openTabs()
```
.
Open one new tab and go to the URL.

Check the page. On example.com,

getByRole("link", { name: "Learn more", exact: true })

is visible.

Close only that tab.
Read
```
openTabs()
```
again. Prior ids match. The new id is gone.

A tab stays on the

session_id

that created it. A refused

createBrowserTab

can still leave

about:blank

. Close it in that same session. Set

CU_SID

on the proxy when you must reuse the session.

document.cookie

is not available.

chrome://

URLs are not allowed. There is no hover method. Browser surface does not ask for per-app approval.

Rehearsal that passed 2026-10-05: select

75ef88d3-…

nameSession

returns at once,

URL=https://example.com/

learnMoreVisible=true

, the new tab is closed, the prior tab ids are unchanged.

使用通过父进程检查确认的 Chrome 实例。每步执行一次

js

调用。

调用
```
cua.getBrowser({ extensionInstanceId })
```
。
在打开任何新标签页前，使用短名称调用
```
browser.nameSession
```
。
记录
```
browser.user.openTabs()
```
返回的标签页 ID。
打开一个新标签页并访问目标 URL。
检查页面。在 example.com 上，
```
getByRole("link", { name: "Learn more", exact: true })
```
元素应可见。
仅关闭该新标签页。
再次读取
```
openTabs()
```
。之前的 ID 应保持一致，新的 ID 已消失。

标签页会归属于创建它的

session_id

。即使

createBrowserTab

被拒绝，仍可能留下

about:blank

页面，请在同一会话中关闭它。如需复用会话，请在代理上设置

CU_SID

。

不支持

document.cookie

操作。不允许访问

chrome://

开头的 URL。没有悬停方法。浏览器层面不会发起按应用授权的请求。

2026-10-05 通过的演练流程：选择

75ef88d3-…

实例，

nameSession

立即返回，

URL=https://example.com/

，

learnMoreVisible=true

，新标签页被关闭，原有标签页 ID 保持不变。

Computer surface

电脑层面

Arc on this surface is an app, not a browser target.

Open a URL with
```
open -a Arc "<url>"
```
. Command-T is less stable.
```
cua.getApp("Arc")
```
. Use the display name. Do not use a bundle id.
After a page change,
```
getAXState({ disableDiffing: true })
```
. The first read can show the old page.
Click by element index. Use
```
setValue
```
when
```
typeText
```
changes case.

cua.computer.launch_app

and

cua.listWindows

are not in this runtime.

getApp

needs the second approval,

Allow Computer Use to use X?

. The proxy answers it from

~/.config/codex-cu/approve

, for every client (Claude, agy, Cursor):

```
all
```
on its own line: accept every prompt (full mode, the deploy default).
One display name per line: accept only those apps (safe mode).
```
all
```
mixed with names means only those names.
Any other app, or no policy file: the prompt goes to the client. agy and cursor-agent cannot answer, so the proxy declines it for them. With no file, every app is refused in agy and Cursor.
A Claude
```
Elicitation
```
hook that accepts codex-cu prompts overrides
```
safe
```
for forwarded apps. Remove such a hook; the policy file is the single source.

scripts/test-codex-cu-proxy

runs the proxy against a fake child (accept, forward, child death, slow client, two-way backpressure, bad policy, shutdown).

Shutdown: once the proxy has seen the client close stdin, it drops (and logs) an approval prompt instead of answering or forwarding it. A prompt already forwarded can still meet the close.

elicitation accept

in the log means the reply was queued to the child. After the child exits, the proxy waits while output still reaches the client; after 30 s with no progress it ends non-zero (output may be incomplete), at most 5 s later if stderr is blocked.

A refusal reads

Computer Use was not approved to use X

. Add the display name to the file; the next prompt reads it, no restart. The Chrome display name is

Google Chrome

该层面下的 Arc 是一个应用，而非浏览器目标。

使用
```
open -a Arc "<url>"
```
打开 URL。Command-T 快捷键的稳定性较差。
调用
```
cua.getApp("Arc")
```
。请使用显示名称，不要使用 bundle ID。
页面变更后，调用
```
getAXState({ disableDiffing: true })
```
。首次读取可能仍显示旧页面。
通过元素索引进行点击。当
```
typeText
```
会改变大小写时，请使用
```
setValue
```
。

该运行时中不包含

cua.computer.launch_app

和

cua.listWindows

。

getApp

需要第二次授权，即「是否允许 Computer Use 使用 X？」。代理会从

~/.config/codex-cu/approve

文件读取配置，为所有客户端（Claude、agy、Cursor）应答授权请求：

单独一行写
```
all
```
：接受所有提示（完整模式，部署默认值）。
每行一个显示名称：仅接受这些应用（安全模式）。
```
all
```
与应用名称混合存在时，仅接受列出的应用。
其他任何应用，或不存在策略文件时：提示会转发给客户端。agy 和 cursor-agent 无法应答，因此代理会替它们拒绝请求。没有策略文件时，agy 和 Cursor 会被拒绝访问所有应用。
若 Claude 有一个接受 codex-cu 提示的
```
Elicitation
```
钩子，会覆盖转发应用的
```
safe
```
模式限制。请移除这类钩子；策略文件是唯一的可信来源。

scripts/test-codex-cu-proxy

脚本会通过模拟子进程测试代理（覆盖接受、转发、子进程退出、客户端缓慢、双向背压、策略错误、关闭等场景）。

关闭逻辑：一旦代理检测到客户端关闭了标准输入，它会丢弃（并记录）授权提示，而不是应答或转发。已经转发的提示仍可能遇到关闭事件。日志中的

elicitation accept

表示回复已排入子进程的队列。子进程退出后，代理会继续等待，直到输出全部送达客户端；若 30 秒内无进展，代理会以非零状态退出（输出可能不完整）；如果标准错误流被阻塞，最多再等待 5 秒后退出。

拒绝提示的内容为

Computer Use was not approved to use X

。将应用的显示名称添加到策略文件中即可，下一次提示时会自动读取，无需重启。Chrome 的显示名称是

Google Chrome

。

Do not

禁止事项

WARNING:

getApp

returns the window text. Do not bind Notes, Mail, Messages, Keychain Access, a password manager, or a terminal unless the user names that app in the current message.

Do not treat a metadata error as a dead computer surface.
Do not pick a browser by numeric id.
Do not call
```
nameSession
```
or
```
createBrowserTab
```
on the Arc instance.
Do not close tabs that were already open.

警告：

getApp

会返回窗口文本。除非用户在当前消息中明确指定了应用，否则不要绑定备忘录（Notes）、邮件（Mail）、信息（Messages）、钥匙串访问（Keychain Access）、密码管理器或终端。

不要将元数据错误视为电脑层面操作失效。
不要通过数字 ID 选择浏览器。
不要在 Arc 实例上调用
```
nameSession
```
或
```
createBrowserTab
```
。
不要关闭已经打开的标签页。

Not tested

未测试场景

Logged-in Chrome pages, a Stop hook that sends

turn_ended

, many Chrome profiles, Arc and Chrome at the same time, Freeform drag, AppleScript JS inside Arc, and

claude setup-token

over SSH.

Chrome 登录态页面、发送

turn_ended

的 Stop 钩子、多 Chrome 配置文件、Arc 和 Chrome 同时运行、Freeform 拖拽、Arc 内的 AppleScript JS、通过 SSH 运行

claude setup-token

。