跳转至

Codex Computer Use

Computer Use 是一个 Codex 原生 MCP 插件,用于本地桌面控制。OpenClaw 不捆绑桌面应用、不自行执行桌面操作,也不绕过 Codex 权限。内置的 codex 插件只负责准备 Codex app-server:它启用 Codex 插件支持,查找或安装已配置的 Computer Use 插件,检查已配置的 MCP server 是否可用,然后让 Codex 在 Codex-mode 轮次中拥有原生 MCP 工具调用。普通非严格轮次会检查安装状态和工具可用性,而不会运行实时探测。显式的状态/安装命令、严格就绪启动以及已启用的定期健康检查会运行实时探测。当 server 暴露旧版 Computer Use 接口时,这些探测使用 list_apps。如果较新的 server 改为暴露 js,则通过一次 await cua.getState(); 调用进行探测。带有 isError: true 的 MCP 响应会使就绪检查失败,而不是被视为成功响应。

当 OpenClaw 已经在使用原生 Codex harness 时,使用本页。关于运行时设置本身,请参阅 Codex harness。

这与 OpenClaw 内置的 基于 node 的 computer 工具 不同。当同一个 agent 契约需要控制配对的 Mac,无论 agent 运行在 Gateway 还是其他 node 上时,使用内置工具。当 Codex app-server 应拥有本地 MCP 安装、权限和原生工具调用时,使用 Codex Computer Use。

OpenClaw.app 与 Peekaboo

OpenClaw.app 的 Peekaboo 集成独立于 Codex Computer Use。macOS 应用可以托管一个 PeekabooBridge socket,使 peekaboo CLI 能够复用该应用本地的 Accessibility 和 Screen Recording 授权,用于 Peekaboo 自身的自动化工具。该 bridge 不会安装或代理 Codex Computer Use,Codex Computer Use 也不会通过 PeekabooBridge socket 调用。

当你希望 OpenClaw.app 成为 Peekaboo CLI 自动化的权限感知 host 时,使用 Peekaboo bridge。当 Codex-mode OpenClaw agent 需要在轮次开始前拥有 Codex 原生 computer-use MCP 插件可用时,使用本页。

iOS 应用

iOS 应用独立于 Codex Computer Use。它不会安装或代理 Codex computer-use MCP server,也不是桌面控制后端。相反,iOS 应用作为 OpenClaw node 连接,并通过 node 命令(例如 camera.*、screen.*、location.* 和 talk.*)暴露移动能力。

当你希望 agent 通过 gateway 驱动 iPhone node 时,使用 iOS。当 Codex-mode agent 应通过 Codex 原生 Computer Use 插件控制本地 macOS 桌面时,使用本页。

直接连接 cua-driver MCP

Codex Computer Use 不是暴露桌面控制的唯一方式。如果你希望 OpenClaw 管理的运行时直接调用 TryCua 的 driver,请通过 OpenClaw 的 MCP registry 使用上游 cua-driver mcp server,而不是使用 Codex 专用的 marketplace 流程。

安装 cua-driver 后,可以请求它生成 OpenClaw 命令:

cua-driver mcp-config --client openclaw

或者直接注册 stdio server:

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

该路径会保持上游 MCP 工具接口完整,包括 driver schemas 和结构化 MCP 响应。当你希望 CUA driver 作为普通 OpenClaw MCP server 可用时,使用它。当 Codex app-server 应拥有插件安装、MCP 重载以及 Codex-mode 轮次内的原生工具调用时,使用本页的 Codex Computer Use 设置。

CUA 的 driver 提供 macOS、Windows(x64 和 ARM64)以及 Linux(x64 和 ARM64,预览层级)的预发布构建。它仍然需要其应用提示的本地 OS 权限,例如 macOS 上的 Accessibility 和 Screen Recording。OpenClaw 不会安装 cua-driver、授予这些权限,或绕过上游 driver 的安全模型。

快速设置

当 Codex-mode 轮次必须在线程开始前拥有 Computer Use 可用时,设置 plugins.entries.codex.config.computerUse。autoInstall: true 会启用 Computer Use,并让 OpenClaw 在轮次开始前安装或重新启用它:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          computerUse: {
            autoInstall: true,
          },
        },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-6-astra",
    },
  },
}

使用此配置时,OpenClaw 会在每个 Codex-mode 轮次前检查 Codex app-server。如果 Computer Use 缺失,但 Codex app-server 已经发现可安装的 marketplace,OpenClaw 会要求 Codex app-server 安装或重新启用该插件并重载 MCP servers。在 macOS 上启动隔离的 Codex app-server 之前,auto-install 还会从选定的桌面应用 bundle 中,将官方签名的 Computer Use service app 配置到该 Codex home 的 computer-use 目录。OpenClaw 会验证外层 service 和嵌套 client 的签名、bundle 身份、版本、build 和代码哈希。它会安装缺失或不完整的副本,或者在替换一个完整副本之前暂存并验证替换副本;该完整副本的签名身份不再与选定的桌面发行版匹配。失败的替换会回滚,而不改变隔离 Codex home 的其余部分。此原生应用同步仅针对 OpenClaw 拥有的隔离 agent home 运行。用户范围 home 和显式 CODEX_HOME 覆盖保留其现有原生 bundle 所有权。agent 目录是受信任的所有权边界。在其中,native-service 配置会拒绝符号链接的 Codex-home、computer-use 和 service-app 路径,并在每次暂存替换周围重新验证受拥有的父目录。 在 macOS 上,OpenClaw 通过位于 $CODEX_HOME/.tmp/bundled-marketplaces/openai-bundled 的真实、由隔离 home 拥有的 wrapper,暴露选定桌面应用的捆绑 marketplace。Codex 将该路径保留给 openai-bundled marketplace。旧版桌面 bundle 使用指向其 manifest 和 plugin 目录的链接。当较新的桌面 bundle 用 unified-computer-use 替换旧版 MCP 插件时,wrapper 会使用同一选定桌面的 Node、Node REPL 和 CUA 包,实例化该插件的 launch descriptor。其 cua_repl server 使用隔离 home 的签名 Computer Use service。原生安装和重新安装会复制此准备好的 source;桌面 bundle 和桌面用户的 plugin cache 不会被修改或复制。其他插件(包括独立的浏览器集成)保留其 source 链接。然后 OpenClaw 要求 Codex app-server 注册该 wrapper。如果设置仍无法使 MCP server 可用,则轮次会在线程开始前失败。

旧版默认插件/服务器组合会自动遵循此替换,包括显式配置了 pluginName: "computer-use" 且使用默认服务器名称的情况。自定义的插件、服务器或市场选择保持不变。对 computer-use@openai-bundled 的显式原生禁用会在特性启用前阻止自动替换。自动安装会在市场发现和插件检查之后、发送原生安装请求之前,立即重新检查该禁用状态。禁用状态下,安装会被报告为“未检查”,因为策略阻止了检查;这并不表示插件不存在。

启动缓存准备会保留请求的身份标识,直到原生有效策略可用。显式的原生 mcp_servers.computer-use 条目或旧版插件 MCP 工具策略会保留旧版身份标识,因此重命名的服务器无法绕过这些限制。在选择统一服务器之前,请显式更新该原生策略。原生 cua_repl 覆盖项继续优先于插件。

托管统一运行时启用其 computer 表面,保留桌面应用发现与控制功能。它不会将代理附加到桌面应用的浏览器会话,也不会公布统一的浏览器表面。原生 MCP 策略、工具限制和 macOS 权限仍然适用。桌面更新会同时刷新已准备的源和客户端代次。

在默认的 strictReadiness: false 下,启动不会创建临时探测线程,也不会等待就绪工具调用。使用 /codex computer-use status 验证实时桌面访问,或启用 healthCheckEnabled 以进行由活动 app-server 客户端负责的周期性检查。当每一轮都必须在其线程启动前等待成功的实时探测时,请设置 strictReadiness: true。严格就绪失败属于 harness 预检失败,因此模型回退不会为每个 Codex 候选重复相同的本地就绪序列。解析到另一个 harness 的候选仍然合格,并通过其正常策略检查进入该运行时。

更改 Computer Use 配置后,如果现有 Codex 线程已启动,请先在被影响的聊天中使用 /new 或 /reset,然后再进行测试。

在 macOS 上,托管的 Computer Use 启动优先选择 ChatGPT.app,对于独立安装则选择 Codex.app。在每个应用的 Contents/Resources 内,它会先检查 codex-cli/CodexCLI.app/Contents/MacOS/codex,再检查较旧的 codex 布局。对于任一可执行文件布局,Computer Use 依赖项都保持位于该应用的 Contents/Resources 中。这也适用于会自行启动客户端的单次 Computer Use status 和 install 命令。这使得桌面控制保持在拥有本地 macOS 权限的应用包(app bundle)之下。如果桌面应用未安装,OpenClaw 会回退到插件旁边安装的托管 Codex 二进制文件。使用默认隔离代理主目录的普通托管 Codex 轮次会优先选择该固定(pinned)包,以免较旧的桌面应用遮蔽当前的模型支持。用户范围(user-scoped)的主目录保持桌面优先,因为它们可以加载原生 Computer Use 状态。生效的 Codex 配置启用了 Computer Use 的隔离代理主目录也保持桌面优先。显式的 appServer.command 配置或 OPENCLAW_CODEX_APP_SERVER_BIN 仍然会覆盖此托管选择。

OpenClaw 会在单个运行中的 Gateway 内串行化原生 Codex 配置读取和 Computer Use 安装。单独的 Codex 进程或另一个 Gateway 不在此隔离范围(fence)内。如果在 Gateway 外部更改了原生 Codex 插件配置,请在依赖新选择之前重启 Gateway 并开始新的聊天。

Gateway 会监视所有可提供 app-server 或 Computer Use 产物的标准 ChatGPT 和 Codex 桌面候选应用。它不会轮询请求路径。在检测到的更新稳定后,现有轮次继续使用其当前的 app-server 代次,新的获取操作将停止使用该代次。对于每个符合条件的隔离主目录,OpenClaw 会等待最后一个旧代次轮次释放其客户端,然后再刷新已签名的 Computer Use 服务、共享缓存和托管市场包装器(wrapper)。随后排队的新轮次会在替换版本上启动;另一个主目录的活动轮次不会阻塞它们。如果捆绑包在启动期间再次变化,OpenClaw 会在登录或 thread/start 之前隔离(fence)过期客户端,并使用正常的有限启动重试。

显式的 appServer.command 和 OPENCLAW_CODEX_APP_SERVER_BIN 客户端仍归操作员所有,并且不会被标准桌面更新事件停用。替换自定义可执行文件后,请重启 Gateway。

这使得在检测到并稳定的标准桌面替换之后,第一个新请求在正常更新程序行为下是透明的。这并不是针对无关 Computer Use 传输失败的一般重试承诺。监视器(watcher)故障或不支持的带外(out-of-band)路径仍可能需要重启 Gateway。autoInstall: false 继续禁止自动原生服务和市场配置。autoRepair 仅控制就绪探测失败后的一次性过期 MCP 子进程修复;它不控制桌面代次收敛。

命令

在任意提供 codex 插件命令表面的聊天表面,使用 /codex computer-use 命令。这些是 OpenClaw 聊天/运行时命令,不是 openclaw codex ... CLI 子命令:

/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 是默认操作且为只读:它不会添加市场源、安装插件或启用 Codex 插件支持。如果没有任何配置选择启用(opt in)Computer Use,status 即使在执行了一次性 install 命令后也可能报告为 disabled。

install 启用 Codex app-server 插件支持,可选择添加已配置的市场源,通过 Codex app-server 安装或重新启用已配置的插件,重新加载 MCP 服务器,并验证 MCP 服务器是否公开了工具。由于安装会更改受信任的主机资源,只有所有者或 operator.admin Gateway 客户端可以运行 install。其他授权发送者可以继续使用只读的 status 命令,包括使用覆盖项。

显式的、由所有者授权的 install 命令即使旧的 computer-use@openai-bundled 插件被禁用,也可以恢复受管理的统一替换。它安装或重新启用所选替换,而不会清除该旧设置。自动就绪和安装仍会遵循旧的禁用设置;若要恢复自动替换,请在原生 Codex 配置中启用 computer-use@openai-bundled。显式安装仍会遵循原生服务器和工具策略。

旧版本接受一次性的 --plugin、--server 和 --mcp-server 身份覆盖。请改为持久配置 computerUse.pluginName 和 computerUse.mcpServerName。当使用旧身份标志时,命令会识别需要持久化的确切设置,并在其迁移指南中重复请求的操作以及任何受支持的市场标志。

市场选择

OpenClaw 使用 Codex 自身公开的相同 app-server API。市场字段用于选择 Codex 应在何处查找 computer-use。

字段 使用场景 安装支持
无市场字段 你希望 Codex app-server 使用它已知的市场。 是,来自已发现的本地或远程市场。
marketplaceSource 你有一个 Codex 市场源,app-server 可以添加。 是,用于显式 /codex computer-use install。
marketplacePath 你已经知道主机上的本地市场文件路径。 是,用于显式安装和回合开始时的自动安装。
marketplaceName 你想按名称选择一个已注册的市场。 是,来自所选的本地或远程市场。

新的 Codex 主目录可能需要短暂时间来初始化其官方市场。安装期间,OpenClaw 会轮询 plugin/list,最长 marketplaceDiscoveryTimeoutMs 毫秒(默认 60 秒)。当 Codex 报告 features.plugins 已禁用时,OpenClaw 会跳过此发现等待。

如果多个已知市场包含 Computer Use,OpenClaw 优先选择 openai-bundled,然后是 openai-curated,最后是 local。未知且存在歧义的匹配会失败关闭,并要求你设置 marketplaceName 或 marketplacePath。

捆绑的 macOS 市场

当前 ChatGPT 桌面版本在此处捆绑 Computer Use;旧版独立 Codex 桌面版本在 Codex.app 下使用相同布局:

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

当 computerUse.autoInstall 为 true 且没有注册包含 computer-use 的市场时,OpenClaw 会按相同的 ChatGPT 优先于 Codex 的顺序选择第一个有效的标准桌面捆绑包,并创建此保留的本地包装器:

$CODEX_HOME/.tmp/bundled-marketplaces/openai-bundled

不要将 /Applications/.../openai-bundled 根目录直接添加到保留的 openai-bundled 名称下。Codex 仅接受来自 CODEX_HOME 下受管理路径的该保留市场;OpenClaw 负责隔离主目录中包装器的生命周期。

如果你使用非标准的 Codex 应用路径,请运行一次 /codex computer-use install --source <marketplace-root>,或将 computerUse.marketplacePath 设置为本地市场文件路径。仅当你拥有市场 JSON 文件路径(而不是捆绑市场根目录)时,才使用 --marketplace-path。

共享插件缓存

默认 pluginCacheMode: "independent" 会使每个 Codex 主目录及其插件缓存保持不受管理。设置 pluginCacheMode: "shared" 可在 app-server 启动前,将捆绑的 Computer Use 插件复制到活动 Codex 主目录中可发现的插件缓存。即使捆绑源是符号链接,缓存版本也是一个真实目录,并且在同一桌面代中重复启动会保持最新副本不变。共享模式会保留旧缓存版本,因为正在运行的 Codex 客户端仍可能引用其版本化插件目录;失败的替换复制也会保留活动缓存。显式 marketplaceName 或 marketplacePath 配置会禁用此协调,以免 OpenClaw 覆盖该选择。

当桌面用 Unified Computer Use 替换旧版 Computer Use 时,自动就绪只有在原生策略允许替换后才会刷新统一共享缓存。当统一插件已在相同版本下安装并启用时,这还会修复过时的生成启动器路径,而无需重新安装它。已是最新的副本保持不变;禁用的旧插件或旧 MCP/工具限制会阻止自动替换和缓存刷新。

远程市场

远程市场支持在 Codex 0.146.1 中引入,并在 OpenClaw 固定的 Codex 0.158.0 中仍然可用。OpenClaw 将 Codex 返回的不透明远程插件 ID 传递给 plugin/read 和 plugin/install;人类可读的插件名称不是有效替代。

/codex computer-use install 可以显式安装或重新启用已发现的远程插件。回合开始的 autoInstall 也可以使用已发现的本地或远程市场。状态检查和没有 autoInstall 的回合不会安装插件或修改 Codex 配置。

配置参考

字段 默认值 含义
enabled 推断 要求 Computer Use。当设置了另一个 Computer Use 字段时,默认为 true。
autoInstall false 在回合开始时配置原生客户端,并安装或重新启用插件。
字段 默认值 含义
marketplaceDiscoveryTimeoutMs 60000 安装等待 Codex app-server 市场发现的时间。
liveTestTimeoutMs 60000 临时就绪线程及其清理请求的超时时间。
toolCallTimeoutMs 60000 与能力匹配的 Computer Use 就绪工具调用的超时时间。
healthCheckEnabled false 在所属 app-server 客户端处于活动状态时,运行周期性就绪探测。
healthCheckIntervalMinutes 60 探测频率;可接受的值为 30、60、120 或 240 分钟。
pluginCacheMode independent 使用 shared 可从捆绑的桌面插件刷新 Codex-home 缓存。
strictReadiness false 在启动时运行实时探测,如果失败则停止启动。
autoRepair false 重新加载 Codex 拥有的 MCP 运行时,并对失败的探测重试一次。
marketplaceSource 未设置 传递给 Codex app-server marketplace/add 的源字符串。
marketplacePath 未设置 包含该插件的本地 Codex 市场文件路径。
marketplaceName 未设置 要选择的已注册 Codex 市场名称。
pluginName computer-use Codex 市场插件名称。
mcpServerName computer-use 已安装插件暴露的 MCP 服务器名称。

启动时自动安装会故意拒绝已配置的 marketplaceSource 值。添加新源是一项显式设置操作,因此请一次性使用 /codex computer-use install --source <marketplace-source>,然后让 autoInstall 处理未来从已发现的本地或远程 市场重新启用。 启动时自动安装可以使用已配置的 marketplacePath,因为该 路径已经是主机上的本地路径。

每个字段还接受环境变量覆盖,当对应的配置键未设置时进行检查:

字段 环境变量
enabled OPENCLAW_CODEX_COMPUTER_USE
autoInstall OPENCLAW_CODEX_COMPUTER_USE_AUTO_INSTALL
marketplaceDiscoveryTimeoutMs OPENCLAW_CODEX_COMPUTER_USE_MARKETPLACE_DISCOVERY_TIMEOUT_MS
liveTestTimeoutMs OPENCLAW_CODEX_COMPUTER_USE_LIVE_TEST_TIMEOUT_MS
toolCallTimeoutMs OPENCLAW_CODEX_COMPUTER_USE_TOOL_CALL_TIMEOUT_MS
healthCheckEnabled OPENCLAW_CODEX_COMPUTER_USE_HEALTH_CHECK_ENABLED
healthCheckIntervalMinutes OPENCLAW_CODEX_COMPUTER_USE_HEALTH_CHECK_INTERVAL_MINUTES
pluginCacheMode OPENCLAW_CODEX_COMPUTER_USE_PLUGIN_CACHE_MODE
strictReadiness OPENCLAW_CODEX_COMPUTER_USE_STRICT_READINESS
autoRepair OPENCLAW_CODEX_COMPUTER_USE_AUTO_REPAIR
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

OpenClaw 检查的内容

OpenClaw 内部报告一个稳定的设置原因,并为聊天格式化面向用户的状态:

原因 含义 下一步
disabled computerUse.enabled 解析为 false。 设置 enabled 或其他 Computer Use 字段。
marketplace_missing 没有可用的匹配市场。 配置源、路径或市场名称。
plugin_not_installed 市场存在,但插件未安装。 运行安装或启用 autoInstall。
plugin_disabled 原生策略禁用了该插件或其自动替换;安装可能未勾选。 运行仅限所有者的安装以显式恢复。启用旧版原生插件以恢复自动替换。
mcp_missing 插件已启用,但 MCP 服务器不可用。 检查 Codex Computer Use 和操作系统权限。
原因 含义 下一步
ready 插件和 MCP 工具可用。 开始 Codex 模式回合。
check_failed 状态检查期间,Codex app-server 请求失败。 检查 app-server 连接和日志。
auto_install_blocked 回合开始设置需要添加新源。 先运行显式安装。

聊天输出包括插件状态、MCP 服务器状态、marketplace、可用时的工具,以及失败设置步骤的具体消息。

macOS 权限

此 Codex 拥有的 Computer Use 路径运行在 macOS 上,MCP 服务器可能需要本地操作系统权限,才能检查或控制应用。(对于 Windows 和 Linux 节点主机上的跨平台桌面控制,请参阅 cua-computer fulfiller。) 如果 OpenClaw 显示 Computer Use 已安装但 MCP 服务器不可用,请先验证 Codex 侧的 Computer Use 设置:

  • Codex app-server 正在应执行桌面控制的主机上运行。
  • Computer Use 插件已在 Codex 配置中启用。
  • computer-use MCP 服务器出现在 Codex app-server MCP 状态中。
  • macOS 已授予桌面控制应用所需权限。
  • 当前主机会话可以访问被控制的桌面。

当 computerUse.enabled 为 true 时,如果插件或其 MCP 工具缺失,OpenClaw 会失败关闭。实时桌面就绪状态仅在 computerUse.strictReadiness 为 true 时才会阻止启动。非严格启动不保证桌面桥接会响应;实际工具调用仍会报告失败。

故障排除

状态显示未安装。 运行 /codex computer-use install。如果未检测到 marketplace,请传入 --source 或 --marketplace-path。

状态显示已安装但已禁用。 再次运行 /codex computer-use install。Codex app-server 安装会将插件配置写回为已启用。

已发现的远程插件无法安装。 确认 Codex 报告了 marketplace 和该插件的不透明远程 ID,然后运行 /codex computer-use install。仅通过显式安装添加新的 marketplaceSource;回合开始时的 autoInstall 使用 Codex 已发现的远程 marketplace。

状态显示 MCP 服务器不可用。 重新运行一次安装,以便 MCP 服务器重新加载。如果仍不可用,请修复 Codex Computer Use 应用、Codex app-server MCP 状态或 macOS 权限。

状态或探测在 computer-use.list_apps 或 cua_repl.js 上超时。 插件和 MCP 服务器存在,但本地 Computer Use 桥接未响应。 退出或重启 Codex Computer Use,如有需要重新启动 Codex Desktop,然后在全新的 OpenClaw 会话中重试。如果主机之前通过旧版受管理的 Codex app-server 运行 Computer Use,请从桌面捆绑 marketplace 刷新已安装的插件(对于独立 Codex 桌面安装,请使用 Codex.app 路径):

/codex computer-use install --source /Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled

某个 Computer Use 工具显示 Native hook relay unavailable。 Codex 原生工具钩子无法通过本地桥接或 Gateway 回退到达活动的 OpenClaw 中继。使用 /new 或 /reset 启动全新的 OpenClaw 会话。如果它成功一次,然后在后续工具调用中再次失败,/new 只是清除当前尝试;请重启 Codex app-server 或 OpenClaw Gateway,以丢弃旧线程和钩子注册,然后在全新会话中重试。

回合开始自动安装拒绝某个源。 这是有意为之。先使用显式 /codex computer-use install --source <marketplace-source> 添加该源,之后未来的回合开始自动安装就可以使用已发现的本地或远程 marketplace。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw