# DSH Codex Computer Use 使用说明

适用版本：插件 0.1.4；Windows；DSH 0.2.0-rc.2。

## 可以做什么

让 DSH 当前模型通过本机 Codex 的 Computer Use 运行时读取窗口、查看截图和控件、点击、输入、按键、滚动、拖动及启动应用。图片会作为 DSH 原生附件返回给模型。插件本身不向 OpenAI 请求模型回复。

输入框的“＋”菜单提供 **Computer Use** 入口，也支持 **`/computer`**。入口会填入任务提示，你补充任务后发送。

## 安装和启动

1. 安装 Windows 版 Codex，并在 Codex 中初始化一次 Computer Use，确保本机运行时已经下载。
2. 从 [Releases](https://github.com/Han-1413141/dsh-codex-computer-use/releases) 下载 `dsh-codex-computer-use-0.1.4.tgz`。
3. 执行下面的命令，将路径替换为实际下载路径。

```powershell
dsh plugin --profile desktop add "C:\下载目录\dsh-codex-computer-use-0.1.4.tgz" --ignore-scripts
```

4. 重新启动 DSH。输入框左下角“＋”→“指令”列表末尾会出现 Computer Use。窗口较小时，需要向下滚动列表。

**日常使用不需要先打开 Codex 主窗口。** 第一次工具调用时，插件自动启动后台工作进程，Computer Use 原生辅助程序会启动所需的 `codex app-server`。插件自动查找本机 CLI；同一轮操作复用工作进程，本轮结束后退出，下次需要时重新启动。

选择菜单本身不会发送消息或启动电脑操作。插件不会修改系统 PATH，也不会修改 DSH 的全局权限设置。

## 第一次使用

可以直接发送：

> 使用 Codex Computer Use 检查运行时，列出窗口。等我指定目标窗口后再操作。

确认能够列出窗口后，再发送具体任务，例如：

> 使用 Codex Computer Use，在记事本的新文档里输入“你好，DSH”。

首次访问应用时，在 **DeepSeek Harness - Computer Use** 独立窗口中点击「允许本次会话」或「拒绝」。插件只在当前 DSH 会话中保存该应用的许可；重启或卸载后清除。

如果使用菜单前已有草稿，将光标放到文字末尾再选择，提示会添加在草稿前。DSH 原生菜单会消费当前选中的文字范围。

## 状态与权限

`codex_computer_read` 的 `status` 返回的是接口加载状态。`runtime_loaded: true` 表示 JavaScript 接口已加载且 CLI 路径已找到；`native_call_verified: false` 表示尚未实际调用原生进程。接着成功执行 `list_windows`，才能确认连接可用。

**可以一直使用「完全权限」，无需切换到审批模式。** 应用授权与普通工具审批分开。0.1.4 默认使用独立 Windows 窗口，同一会话的同一应用后续复用许可。拒绝、Esc、关闭窗口、取消任务或进程异常退出都不会批准。若某次操作需要单独确认，会再弹出操作确认窗口。

0.1.2 及以前把应用许可交给普通审批服务，因此 `never` 会直接拒绝。升级插件并重启 DSH 即可。工作区和只读模式下的桌面访问审批仍然保留。独立窗口需要本机交互桌面；若系统禁止执行 PowerShell 脚本，可将插件配置 `approvalUi` 设为 `dsh`，改用桌面或 Web 聊天内的问答卡片。

## 常见问题

### 任务已经完成，蓝色电脑操作状态条还在

0.1.4 已补上任务结束清理：DSH 发出本轮结束或空闲事件后，插件调用 SDK 的 `close()`，关闭自己的工作进程和原生连接。取消调用、卸载插件和原生运行时停止本轮时也会清理。模型可主动调用 `codex_computer_read`，参数为 `{"action":"stop"}`，提前退出电脑操作。

更新后重新启动 DSH，让旧版常驻进程退出并加载新代码。新版本不会通过关闭其他 Codex 会话的进程来清理自己的连接。停止后的旧 `observation_id` 失效；之后需要操作时，重新观察目标窗口。

### 蓝色条仍显示 ChatGPT / Codex

蓝色条由 Codex 原生程序绘制，目前没有找到可供插件使用的文字配置。0.1.4 的独立授权窗口已使用 DeepSeek Harness 名称；顶部原生状态条的品牌文字尚未修改，Esc 取消提示保持可见。

### 浏览器提示无法核验当前 URL

错误示例：`could not determine the current browser URL on Windows with enough confidence to enforce policy`。

这是 Codex 原生运行时的浏览器 URL 核验失败，发生在应用许可之后。OpenAI 仓库已有 [问题 #25271](https://github.com/openai/codex/issues/25271)，截至 2026-10-01 查阅时仍为 Open。插件没有实现或修改该原生检查，也不能用完全权限、再次批准或反复重启工作进程消除错误。

遇到这个错误应停止本轮桌面操作。当前版本已验证普通 Windows 应用的完整调用链，不能据此承诺 Chrome / Edge 可用。浏览器功能需要对应运行时的修复；不要把同一故障当成应用授权问题重复操作。

### 提示找不到 Codex app-server

错误示例：`failed to launch codex app-server: program not found`。

0.1.0–0.1.1 依赖外部进程传入 CLI 路径。在 Codex 内测试时可能正常，独立启动 DSH 时会失败。更新到 0.1.2 并重启 DSH，即可使用自动查找。需要自定义安装路径时，在插件配置中设置 `codexPath`，值为 `codex.exe` 的完整绝对路径；也可以设置 `DSH_CODEX_CLI_PATH`。

### 提示没有 Computer Use 运行时

在 Codex 中初始化一次 Computer Use。插件默认查找 `%LOCALAPPDATA%\OpenAI\Codex\runtimes\cua_node`；自定义位置可通过 `skyDir` 或 `DSH_CODEX_SKY_DIR` 指向 `@oai/sky` 包目录。

### 安装后菜单没有变化

重新启动 DSH，让正在运行的进程加载新插件。确认安装使用的是桌面版的 `desktop` profile。

### 操作超时或刷新失败

先重新读取窗口，不要直接重试输入或点击，以免重复执行。应用可能尚未处理完输入队列，因此刚输入后的快照可能暂未显示文字；先观察实际状态再决定下一步。若原生错误明确说明「本轮已停止」，则停止本轮 Computer Use，不能按普通刷新失败重试。

## 开发与验证

```powershell
npm install
npm run build
npm test
npm run check
npm run test:startup
```

`test:startup` 会在清除 Codex 专用环境变量和 PATH 条目的子进程中执行原生窗口枚举，不截图、不点击、不输入。原生界面操作测试为 `npm run test:host -- --approved-fixture`，只应在用户授权操作自建测试窗口后运行。

已验证内容和边界见 [验证记录](validation.md)。插件使用的 Codex 宿主授权回调不是稳定第三方接口，Codex 更新后可能需要适配。

## 卸载

```powershell
dsh plugin --profile desktop remove dsh-codex-computer-use
```

卸载后重新启动 DSH。