跳转到内容
OpenClaw Docs

Codex Computer Use

Computer Use 是一个用于本地桌面控制的 Codex 原生 MCP 插件。OpenClaw 不提供桌面应用程序，不自行执行桌面操作，也不绕过 Codex 权限。捆绑的 OpenClawcodex 插件仅准备 Codex 应用服务器： 它启用 Codex 插件支持，查找或安装配置的 Codex Computer Use 插件，检查 computer-use MCP 服务器是否可用， 然后让 Codex 在 Codex 模式回合中拥有原生 MCP 工具调用。

当 OpenClaw 已在使用原生 Codex harness 时，请使用此页面。有关运行时设置本身，请参阅 Codex harness。

OpenClaw.app 和 Peekaboo

Section titled “OpenClaw.app 和 Peekaboo”

OpenClaw.app 的 Peekaboo 集成与 Codex Computer Use 是分开的。该 macOS 应用可以托管 PeekabooBridge 套接字，以便 peekaboo CLI 可以重用应用的本地辅助功能和屏幕录制权限，用于 Peekaboo 自己的自动化工具。该桥接器不安装或代理 Codex Computer Use，且 Codex Computer Use 也不通过 PeekabooBridge 套接字进行调用。

当您希望 Peekaboo.app 作为 OpenClaw Peekaboo 自动化的权限感知主机时，请使用 CLI bridge。当 Codex 模式的 OpenClaw 代理应该在回合开始之前拥有 Codex 的原生 computer-use MCP 插件时，请使用此页面。

iOS app

Section titled “iOS app”

iOS 应用与 Codex Computer Use 是分开的。它不安装或代理 Codex iOScomputer-useiOSOpenClaw MCP 服务器，也不是桌面控制后端。相反，iOS 应用作为 OpenClaw 节点连接，并通过节点命令（例如 canvas.*、camera.*、screen.*、location.* 和 talk.*）暴露移动端功能。

当您希望代理通过网关控制 iPhone 节点时，请使用 iOS。当 Codex 模式代理应通过 Codex 的原生 Computer Use 插件控制本地 macOS 桌面时，请使用此页面。

直接 cua-driver MCP

Section titled “直接 cua-driver MCP”

Codex Computer Use 并不是暴露桌面控制的唯一方式。如果您希望 OpenClaw 托管的运行时直接调用 TryCua 的驱动程序，请通过 OpenClaw 的 MCP 注册表使用上游 cua-driver mcp 服务器，而不是 Codex 专用的市场流程。

安装 cua-driver 后，您可以向其询问 OpenClaw 命令：

Terminal window
cua-driver mcp-config --client openclaw

或者自行注册 stdio 服务器：

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

这种方式保持了上游 MCP 工具表面（工具 surface）的完整性，包括驱动程序架构和结构化的 MCP 响应。当您希望 CUA 驱动程序作为普通的 OpenClaw MCP 服务器可用时，请使用此方法。当 Codex 应用服务器应负责插件安装、MCP 重载以及 Codex 模式轮次内的原生工具调用时，请使用本页上的 Codex Computer Use 设置。

CUA 的驱动程序特定于 macOS，并且仍然需要其应用程序提示的本地 macOS 权限，例如辅助功能和屏幕录制。OpenClaw 不会安装 macOSmacOSOpenClawcua-driver、授予这些权限或绕过上游驱动程序的安全模型。

快速设置

Section titled “快速设置”

当 Codex 模式回合必须在线程开始之前准备好 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-5.5",
    },
  },
}

使用此配置，OpenClaw 会在每次 Codex 模式回合之前检查 Codex app-server。如果缺少 Computer Use，但 Codex app-server 已发现可安装的 marketplace，OpenClaw 会要求 Codex app-server 安装或重新启用该插件并重新加载 MCP 服务器。在 macOS 上，当没有注册匹配的 marketplace 且存在标准 Codex app bundle 时，OpenClaw 也会尝试在失败之前从 /Applications/Codex.app/Contents/Resources/plugins/openai-bundled 注册捆绑的 Codex marketplace。如果设置仍无法使 MCP 服务器可用，则回合在线程开始之前失败。

更改 Computer Use 配置后，请在受影响的聊天中使用 /new 或 /reset，然后再测试现有的 Codex 线程是否已启动。

命令

Section titled “命令”

在任何 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 插件支持。如果没有配置项启用 Computer Use，status 可以 在执行一次性安装命令后仍报告为已禁用。

install 启用 Codex app-server 插件支持，可选地添加配置的 市场源，通过 Codex app-server 安装或重新启用配置的插件，重新加载 MCP 服务器，并验证 MCP 服务器是否暴露了工具。

Marketplace choices

Section titled “Marketplace choices”

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

字段使用时机安装支持
无市场字段您希望 Codex 应用服务器使用它已知的市场。是，当应用服务器返回本地市场时。
marketplaceSource您有一个应用服务器可以添加的 Codex 市场源。是的，对于明确的 /codex computer-use install。
marketplacePath您已经知道主机上的本地市场文件路径。是，用于显式安装和轮次开始时的自动安装。
marketplaceName您希望按名称选择一个已注册的市场。仅当所选市场具有本地路径时为是。

全新的 Codex 主目录可能需要短暂时间来初始化其官方市场。 在安装过程中，OpenClaw 轮询 OpenClawplugin/list 最长 marketplaceDiscoveryTimeoutMs 毫秒。默认值为 60 秒。

如果多个已知市场包含 Computer Use，OpenClaw 优先选择 OpenClawopenai-bundled，然后是 openai-curated，再然后是 local。未知的模糊匹配 将以失败告终并要求您设置 marketplaceName 或 marketplacePath。

捆绑的 macOS 市场

Section titled “捆绑的 macOS 市场”

最近的 Codex 桌面版本在此处捆绑了 Computer Use：

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

当 computerUse.autoInstall 为 true 且没有注册包含 computer-useOpenClaw 的市场时，OpenClaw 会尝试自动添加标准捆绑的 市场根目录：

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

您也可以在 Shell 中使用 Codex 显式注册它：

Terminal window
codex plugin marketplace add /Applications/Codex.app/Contents/Resources/plugins/openai-bundled

如果您使用非标准的 Codex 应用路径，请运行 /codex computer-use install --source <marketplace-root> once or set computerUse.marketplacePath 指向 本地市场文件路径。仅当您拥有 市场 JSON 文件路径而非捆绑的市场根目录时，才使用 --marketplace-path。

远程目录限制

Section titled “远程目录限制”

Codex 应用服务器可以列出并读取仅限远程的目录条目，但目前不支持远程 plugin/install。这意味着 marketplaceName 可以选择仅限远程的 marketplace 进行状态检查，但安装和重新启用仍需通过 marketplaceSource 或 marketplacePath 使用本地 marketplace。

如果状态显示插件在远程 Codex 市场中可用但不支持远程安装，请使用本地源或路径运行安装：

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

配置参考

Section titled “配置参考”
字段默认值含义
enabled推断需要计算机使用。当设置了另一个计算机使用字段时，默认为 true。
autoInstallfalse在回合开始时从已发现的市场安装或重新启用。
marketplaceDiscoveryTimeoutMs60000安装等待 Codex 应用服务器市场发现的时间。
marketplaceSource未设置传递给 Codex 应用服务器的源字符串 marketplace/add。
marketplacePath未设置包含该插件的本地 Codex 市场文件路径。
marketplaceName未设置要选择的已注册 Codex 市场名称。
pluginNamecomputer-useCodex 市场插件名称。
mcpServerNamecomputer-use已安装插件暴露的 MCP 服务器名称。

回合开始时的自动安装会故意拒绝已配置的 marketplaceSource 值。添加新源是一个显式的设置操作，因此请使用 /codex computer-use install --source <marketplace-source> 一次，然后让 autoInstall 处理从已发现的本地 marketplace 进行的未来重新启用。回合开始时的自动安装可以使用已配置的 marketplacePath，因为这已经是主机上的本地路径。

OpenClaw 检查的内容

Section titled “OpenClaw 检查的内容”

OpenClaw 在内部报告稳定的设置原因，并为聊天格式化面向用户 的状态：

原因含义下一步
disabledcomputerUse.enabled 解析为 false。设置 enabled 或其他 Computer Use 字段。
marketplace_missing没有可用的匹配市场。配置源、路径或市场名称。
plugin_not_installedMarketplace 存在，但插件未安装。运行安装或启用 autoInstall。
plugin_disabled插件已安装，但在 Codex 配置中被禁用。运行 install 以重新启用它。
remote_install_unsupported选定的 marketplace 仅限远程。使用 marketplaceSource 或 marketplacePath。
mcp_missing插件已启用，但 MCP 服务器不可用。检查 Codex Computer Use 和操作系统权限。
ready插件和 MCP 工具可用。开始 Codex 模式回合。
check_failed在状态检查期间，Codex app-server 请求失败。检查 app-server 连接和日志。
auto_install_blockedTurn-start setup would need to add a new source.Run explicit install first.

The chat output includes the plugin state, MCP server state, marketplace, tools when available, and the specific message for the failing setup step.

macOS 权限

Section titled “macOS 权限”

Computer Use 是特定于 macOS 的。Codex 拥有的 MCP 服务器在检查或控制应用之前，可能需要本地操作系统 权限。如果 OpenClaw 显示 Computer Use 已安装，但 MCP 服务器不可用，请首先验证 Codex 端的 Computer Use 设置：

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

OpenClaw 故意在 OpenClawcomputerUse.enabled 为 true 时以失败关闭。在缺少配置所需的本机桌面工具的情况下，Codex 模式回合不应静默继续。

故障排除

Section titled “故障排除”

状态显示未安装。 运行 /codex computer-use install。如果未发现市场，请传递 --source 或 --marketplace-path。

状态显示已安装但已禁用。 再次运行 /codex computer-use install。Codex 应用服务器安装会将插件配置重新写为已启用。

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.

状态或探测在 computer-use.list_appsOpenClaw 上超时。 插件和 MCP 服务器存在，但本地 Computer Use 网桥未响应。退出或重启 Codex Computer Use，如有需要请重新启动 Codex Desktop，然后在新的 OpenClaw 会话中重试。

Computer Use 工具显示 Native hook relay unavailableOpenClawGateway(网关)OpenClaw。 Codex 原生工具挂钩无法通过本地网桥或 Gateway(网关) 备选到达活跃的 OpenClaw 中继。使用 /new 或 /reset 启动一个新的 OpenClaw 会话。如果它成功一次但在随后的工具调用中再次失败，/newOpenClawGateway(网关) 只是清除当前尝试；重启 Codex 应用服务器或 OpenClaw Gateway(网关) 以便丢弃旧线程和挂钩注册，然后在新的会话中重试。

回合开始时的自动安装拒绝某个来源。 这是故意的。首先使用显式的 /codex computer-use install --source <marketplace-source> 添加来源，然后未来的回合开始自动安装可以使用已发现的本地市场。

相关

Section titled “相关”