Codex Computer Use Plugin 不可用
摘要 ：本文详细分析了 Codex 桌面应用中 Computer Use 功能不可用的故障现象、根本原因及完整修复方案。问题根源在于 Codex 的插件同步机制未能正确将 computer-use 插件和 cua_node 运行时从 WindowsApps 应用包部署到用户数据目录。修复方案包括手动复制缺失文件、运行修复脚本、验证关键文件结构，并提供标准操作流程、手动操作步骤及故障排查清单。文章还包含详细的架构图、目录权限说明和文件结构参考，帮助用户彻底解决此问题。
日期: 2026-07-01
场景: Codex 桌面应用中 Computer Use 功能无法启动
相关版本: Codex 桌面应用
26.623.11225/ 插件26.623.61825
1. 问题现象
在 Codex 会话中尝试使用 Computer Use 功能（控制 Windows 桌面应用）时，提示无法连接或功能不可用。@oai/sky 模块找不到，或者 native pipe 无法创建连接。
具体表现为：
setupComputerUseRuntime()启动时报错Computer Use native pipe is unavailable- 找不到
scripts/computer-use-client.mjs中的核心模块 - Node REPL 中无法 import
@oai/sky运行时
2. 问题原因
2.1 整体架构
Codex 的 Computer Use 功能依赖两个核心组件：
┌─────────────────────────────────────────────────────────────────┐
│ WindowsApps 应用包 (只读) │
│ │
│ C:\Program Files\WindowsApps\OpenAI.Codex_26.623.11225.0_...\ │
│ ├── app\resources\cua_node\bin\ │
│ │ ├── node.exe (专用 Node.js 运行时) │
│ │ ├── node_repl.exe (Node REPL 宿主) │
│ │ └── node_modules\@oai\sky\ (Computer Use Sky API) │
│ │ │
│ └── app\resources\plugins\openai-bundled\plugins\computer-use\│
│ ├── .codex-plugin\plugin.json (插件清单) │
│ ├── scripts\computer-use-client.mjs (入口脚本) │
│ └── skills\computer-use\SKILL.md (Skill 指令) │
└─────────────────────────────────────────────────────────────────┘
│
Codex 启动时自动同步
▼
┌─────────────────────────────────────────────────────────────────┐
│ 用户数据目录 (可读写) │
│ │
│ C:\Users\<用户>\.codex\plugins\cache\openai-bundled\ │
│ ├── browser\26.623.61825\ (✅ 已同步) │
│ └── computer-use\26.623.61825\ (❌ 缺失) │
│ │
│ C:\Users\<用户>\AppData\Local\OpenAI\Codex\runtimes\cua_node\ │
│ ├── node.exe (❌ 缺失) │
│ ├── node_repl.exe (❌ 缺失) │
│ └── node_modules\@oai\sky (❌ 缺失) │
└─────────────────────────────────────────────────────────────────┘2.2 根因
Codex 桌面应用的插件同步机制 没有正确将 computer-use 插件和 cua_node 运行时从 WindowsApps 包部署到用户数据目录。
已知可以正常同步的对比项：browser 插件（已正确部署在 plugins\cache\openai-bundled\browser\26.623.61825\）。
可能的原因：
- Codex 首次启动时插件同步过程中断（例如网络短暂中断、系统重启）
cua_node运行时部署因权限问题被阻止- 应用版本更新后增量同步未覆盖新插件
2.3 目录权限说明
两个目标目录的权限为：
| 用户/组 | 权限 |
|---|---|
CodexSandboxUsers |
ReadAndExecute（只读） |
Junbai（当前用户） |
FullControl（完全控制） |
SYSTEM / Administrators |
FullControl |
关键约束 ：Codex 的 sandbox 进程以 CodexSandboxUsers 身份运行，该用户对目标目录只有读取权限 。因此 sandbox 内的 agent 无法直接修复此问题，需要用户以本人身份（Junbai）直接运行修复脚本。
3. 修复方案
3.1 原理
从 WindowsApps 应用包中手动复制缺失的两个组件到用户数据目录：
| 组件 | 源路径 | 目标路径 |
|---|---|---|
| cua_node 运行时 | ...\app\resources\cua_node\bin\ |
%LOCALAPPDATA%\OpenAI\Codex\runtimes\cua_node\ |
| computer-use 插件 | ...\plugins\openai-bundled\plugins\computer-use\ |
%USERPROFILE%\.codex\plugins\cache\openai-bundled\computer-use\26.623.61825\ |
3.2 修复脚本
参见同目录下的 <fix-computer-use.ps1>，脚本功能：
- 使用
robocopy递归复制cua_node运行时会话 - 创建插件缓存目录并复制
computer-use插件文件 - 验证所有关键文件就位（
node.exe、node_repl.exe、plugin.json、computer-use-client.mjs、SKILL.md）
4. 操作步骤
4.1 标准修复流程
powershell
# 1. 完全退出 Codex 桌面应用
# - 任务栏 Codex 图标右键 → "退出"
# - 或任务管理器结束所有 Codex.exe 进程
# 2. 以当前用户身份打开 PowerShell（不需要管理员）
# 进入工作区目录后：
cd D:\resource\automation-tools-Web
# 3. 运行修复脚本
powershell -ExecutionPolicy Bypass -File .\fix-computer-use.ps1
# 4. 验证脚本输出确认所有文件安装成功
# 5. 重启 Codex 桌面应用
# 6. 尝试使用 Computer Use 功能4.2 手动操作（不依赖脚本）
如果脚本无法运行，可以手动执行以下操作：
powershell
# 定义源和目标路径
$appPkg = "C:\Program Files\WindowsApps\OpenAI.Codex_26.623.11225.0_x64__2p2nqsd0c76g0"
$pluginVer = "26.623.61825"
# 1. 复制 cua_node 运行时
robocopy "$appPkg\app\resources\cua_node\bin" `
"$env:LOCALAPPDATA\OpenAI\Codex\runtimes\cua_node" `
/E /R:2 /W:3
# 2. 复制 computer-use 插件
robocopy "$appPkg\app\resources\plugins\openai-bundled\plugins\computer-use" `
"$env:USERPROFILE\.codex\plugins\cache\openai-bundled\computer-use\$pluginVer" `
/E /R:2 /W:3
# 3. 验证
$checks = @(
"$env:LOCALAPPDATA\OpenAI\Codex\runtimes\cua_node\node.exe",
"$env:LOCALAPPDATA\OpenAI\Codex\runtimes\cua_node\node_repl.exe",
"$env:USERPROFILE\.codex\plugins\cache\openai-bundled\computer-use\$pluginVer\.codex-plugin\plugin.json",
"$env:USERPROFILE\.codex\plugins\cache\openai-bundled\computer-use\$pluginVer\scripts\computer-use-client.mjs"
)
$checks | ForEach-Object { if (Test-Path $_) { Write-Host "OK: $_" } else { Write-Host "MISSING: $_" } }4.3 彻底重置（可选）
如果需要完全重置 Computer Use 环境：
powershell
# 1. 退出 Codex 后删除已失效的目录
Remove-Item "$env:LOCALAPPDATA\OpenAI\Codex\runtimes\cua_node" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.codex\plugins\cache\openai-bundled\computer-use" -Recurse -Force -ErrorAction SilentlyContinue
# 2. 重启电脑
Restart-Computer
# 3. 重新运行修复脚本5. 故障排查清单
如果修复后仍无法使用 Computer Use，请依次检查：
| # | 检查项 | 命令/方案 |
|---|---|---|
| 1 | cua_node 运行时文件是否存在 | `Get-ChildItem "$env:LOCALAPPDATA\OpenAI\Codex\runtimes\cua_node" -Recurse |
| 2 | computer-use 插件缓存是否存在 | `Get-ChildItem "$env:USERPROFILE.codex\plugins\cache\openai-bundled\computer-use" -Recurse |
| 3 | Codex 版本是否匹配 | 检查 $env:USERPROFILE\.codex\.codex-global-state.json 中的版本信息 |
| 4 | Codex 是否需要重启 | 修复后必须重启 Codex 桌面应用 |
| 5 | 是否有其他插件冲突 | 检查 ~\.codex\plugins\cache\openai-bundled\ 下是否有异常的空目录 |
6. 文件结构参考
修复后应确认的关键文件
%LOCALAPPDATA%\OpenAI\Codex\runtimes\cua_node\
├── node.exe
├── node_repl.exe
├── nodevars.bat
├── npm / npm.cmd / npm.ps1
├── npx / npx.cmd / npx.ps1
├── CHANGELOG.md
├── LICENSE
├── README.md
├── setup.ps1 / setup.sh
├── corepack / corepack.cmd
├── install_tools.bat
└── node_modules\
└── @oai\
└── sky\ # 核心 Computer Use Sky API 模块
├── dist\
│ └── project\cua\sky_js\src\targets\windows\internal\
│ └── computer_use_client_base.js
└── ...
%USERPROFILE%\.codex\plugins\cache\openai-bundled\computer-use\26.623.61825\
├── .codex-plugin\
│ └── plugin.json # 插件清单（名称、版本、描述、接口声明等）
├── assets\
│ └── app-icon.png # 应用图标
├── scripts\
│ └── computer-use-client.mjs # 核心入口脚本（启动 sky API）
└── skills\
└── computer-use\
└── SKILL.md # Skill 指令文件7. 一些技术细节
computer-use-client.mjs通过 Node REPL 的nodeRepl.nativePipe.createConnection()建立 native pipe 通信- Native pipe 路径由环境变量
SKY_CUA_NATIVE_PIPE_DIRECTORY指定 WindowsComputerUseClientBase从@oai/sky包动态 import- 插件版本
26.623.61825与 Codex 桌面应用版本26.623.11225同属一个发布轨道
本文档供后续排查类似问题时参考。