codex-plugin-dsh

中文 | English

在 DeepSeek Harness 里直接使用你本机已经登录的 Codex，无需在 DSH 中配置 OpenAI API Key。安装并重启后，现有模型选择器中会出现 Codex App Server (local)，选择模型即可开始对话。

会话和工具调用仍由 DSH 管理，现有 DSH 插件与工具可以照常使用；模型请求通过本地 Codex App Server 连接当前 Codex 账户。插件也支持图片输入，并能把 Codex 原生图片生成结果直接回写到 DSH 对话。

快速安装：直接让 DSH 完成

如果当前 DSH 会话具有完整的宿主机权限，把下面这段话直接发给它：

请将 github:wingoo/codex-plugin-dsh 安装到当前 DSH 的 web profile，不要修改 DeepSeek Harness 源码。

1. 检查本机是否已经安装符合插件要求的 Codex CLI；如果尚未安装或版本过旧，请先按照 OpenAI 官方方式安装或升级。
2. 运行 codex login status 检查登录状态。如果尚未登录，请让我在运行 DSH 的主机终端执行 codex login；等我完成浏览器登录并回复“已登录”后再继续。
3. 确认 codex app-server --help 可以正常运行。
4. 安装插件，并通过 dsh --profile web --dump-config 确认 codex-app-server-provider 已加载。
5. 沿用当前 DSH Web 服务原来的启动方式完成重启，不要在同一端口启动第二个实例。重启前提醒我连接会暂时中断。
6. 服务恢复后提醒我刷新页面，并在现有模型选择器中选择 Codex App Server (local)。

如果无法可靠判断原来的启动方式，不要猜测或结束无关进程，直接告诉我应该执行的重启命令。

这会修改 DSH profile 并在宿主机上运行插件代码，请先确认仓库来源。重启期间当前连接会暂时中断，服务恢复后刷新页面即可。

通过命令行安装

dsh plugin --profile web add github:wingoo/codex-plugin-dsh

如果从 DeepSeek Harness 源码仓库运行：

pnpm dsh plugin --profile web add github:wingoo/codex-plugin-dsh

正式版本发布前，可以锁定已验证的 commit，让安装结果保持一致：

dsh plugin --profile web add github:wingoo/codex-plugin-dsh#<commit-sha>

安装本地 checkout

dsh plugin --profile web add /absolute/path/to/codex-plugin-dsh

从 DeepSeek Harness 源码仓库运行时：

pnpm dsh plugin --profile web add /absolute/path/to/codex-plugin-dsh

安装后使用

沿用原来的启动方式重启 DSH Web 服务，不要在同一端口启动第二个实例。服务恢复后刷新浏览器，在输入框下方打开现有模型选择器，然后从 Codex App Server (local) 分组中选择模型。

空白工作区会话最初使用当前默认模型；发送第一条消息前也可以先切换到 Codex。

更新已安装插件：直接让 DSH 完成

已经安装过插件时不需要先卸载。把下面这段话发给具有完整宿主机权限的 DSH 会话：

请把当前 DSH web profile 中已经安装的 codex-plugin-dsh 更新到 GitHub main 的最新版本，不要修改 DeepSeek Harness 源码，也不要先卸载插件。

1. 先运行 command -v dsh，确认当前环境能否直接调用 dsh。
2. 如果可以，运行 dsh plugin --profile web update codex-plugin-dsh；如果没有全局 dsh 命令且当前服务通过 npx 启动，改用 npx --yes @deepseek-ai/dsh plugin --profile web update codex-plugin-dsh。
3. 检查 ~/.dsh/profiles/web/pnpm-lock.yaml，确认 codex-plugin-dsh 的 GitHub tarball commit 已更新；同时运行 dsh --profile web --dump-config（npx 启动时使用对应的 npx 命令）确认 codex-app-server-provider 仍然存在。
4. 更新成功后，沿用当前 Web 服务原来的启动方式重启，不要在同一端口启动第二个实例。重启前提醒我连接会暂时中断。
5. 服务恢复后提醒我刷新页面，并新建一个会话测试 Codex 模型。

如果更新命令被 sandbox 拒绝，请只为这个更新操作请求所需权限；如果无法可靠判断原来的启动方式，不要猜测或结束无关进程，直接告诉我应该执行的重启命令。

更新会刷新 GitHub 依赖所解析的 commit，同时保留 web profile 中已有的插件 bundle 配置。

通过终端更新

已经安装全局 dsh 命令：

dsh plugin --profile web update codex-plugin-dsh

通过 npx 运行 DSH：

npx --yes @deepseek-ai/dsh plugin --profile web update codex-plugin-dsh

从 DeepSeek Harness 源码仓库运行：

pnpm dsh plugin --profile web update codex-plugin-dsh

更新完成后必须重启原有 DSH Web 服务，正在运行的进程不会自动加载磁盘上的新插件代码。

环境要求

• Node.js ^22.19.0 或 >=24
• DeepSeek Harness >=0.1.0-rc.5 <0.2.0
• 本地 Codex CLI >=0.147.0
• 已通过 codex login 登录的 Codex 账户

准备 Codex CLI

本插件使用宿主机上的 Codex CLI，不会代为下载、升级或登录。按照 OpenAI Codex CLI 的安装方式准备本机运行时：

npm install -g @openai/codex
codex login

确认运行 DSH 的环境能够找到 Codex，并且 App Server 可用：

codex --version
codex app-server --help

Codex CLI 自己管理账户认证和产品设置；插件不读取或保存 API Key，也不要求把 OpenAI API Key 填入 DSH。

当前状态

目前已在 macOS 上使用 DeepSeek Harness 0.1.0-rc.5 源码包、0.1.0-rc.6 发布包和 Codex CLI 0.147.0 完成验证。本地 bundle 安装、模型发现、Web 端现有模型选择器、真实图片输入、App Server 图片生成回写，以及 DSH 工具调用、结果续跑、附加上下文和工具目录更新均已通过真实 App Server 测试。

Windows 批处理 shim 启动已有单元测试，首个版本发布前仍需在真实 Windows 主机上运行一次。当前 DSH 0.1.0-rc 安装 service package 时可能输出 peer-dependency warning；插件已显式声明运行时依赖，全新 profile 的 GitHub 安装、Web 启动、模型发现和真实 Codex 回合均已验证通过。

配置

安装后会使用安全默认值自动启用。profile 可以在自己的 cordis.patch.yml 中覆盖已插入的插件行：

- id: codex-app-server-provider
  config:
    executable: codex
    env: {}
    modelCacheMs: 30000
    catalogTimeoutMs: 10000
    turnTimeoutMs: 600000
    disposeGraceMs: 3000
    stderrMaxBytes: 16384
    modelPageSize: 100

executable 由 DSH 在 subprocess provider 的执行环境中解析，因此如果未来使用远程或沙箱 subprocess provider，Codex 也必须安装在同一个执行环境中。env 是显式子进程环境覆盖，不要把凭证写进已提交的 profile。

运行行为

• DSH Agent Loop 不会固定调用某个 HTTP API。它使用当前会话选中的 provider／model 调用 DSH LLM service；选择 Codex 后，请求路由到本插件，再通过 stdio 交给本地 Codex App Server。DSH 默认模型只影响尚未显式选择模型的新会话，不是 Codex 路由的第二个上游。
• DSH 会照常完成系统提示和工具组装。插件只接收本次请求的 options.tools，不会再次枚举全局工具，因此 preset、scope、allow／deny 和 code mode 的结果不会被绕过或重复。
• App Server 请求 dsh namespace 中的动态工具时，插件先返回普通 DSH tool-call。DSH Agent Loop 负责权限、调度、执行和 tool/call／tool/result 日志；下一步 Provider 调用再把结果送回仍在运行的同一个 App Server turn。插件不会自己再执行一遍工具。
• DSH 工具产生的图片结果会作为动态工具图片输出返回给 Codex；additionalContexts 会通过 turn/steer 进入同一个 turn，而不是被错误拼进工具结果。
• App Server thread 保留动态工具目录。同一目录的后续回合直接从 checkpoint fork，不重复发送；目录变化时会创建新 thread 并从 DSH 持久消息重建可导入历史。
• DSH 会话的工作区会成为 App Server thread 的工作目录，但 App Server 固定使用只读 sandbox 和 never approval。Codex 自带 shell、文件修改、Web、MCP、Apps、Plugins、view-image 和 multi-agent 能力会被关闭或拒绝；这些动作只能走 DSH 工具生态。
• Codex 原生 imagegen 是有意保留的例外，它由 App Server 直接完成，不进入 DSH 工具循环。
• DSH 图片附件会先由 attachment service 校验，再以内联 data URL 传给 App Server；不依赖双方共享本地文件路径。
• App Server 完成的图片生成结果会保存为 DSH 图片附件，并作为 assistant 图片显示在原有对话中。能否调用图片生成工具取决于当前 Codex 账户、模型和 App Server 能力，不要求在 DSH 中另配 OpenAI API Key。
• 成功回合会把 App Server thread、turn 和工具目录签名写入 DSH 模型 replay state；后续回合从这个精确 checkpoint 分叉。
• 会话从其他 DSH provider 切换到 Codex 时，已完成的文本、用户图片和工具历史会通过 App Server thread/inject_items 方法导入。
• App Server 进程由 DSH subprocess service 管理；一个进程可以跨越同一 DSH turn 的多个工具 step，回合、会话或插件生命周期结束时会按进程树终止。

已知限制

• 尚未实现 DSH 交互问题桥接，因此 App Server 的 item/tool/requestUserInput 会明确失败。
• 其他 provider 产生的 reasoning block 或 assistant 图片无法导入 App Server；工具目录变化而必须重建 thread 时，已有 Codex reasoning／assistant 图片也无法无损导入。插件会明确失败并要求新建会话，而不是静默丢弃。
• App Server 无法兑现的配置字段（temperature、maxTokens、stop）会被拒绝，不会被静默忽略。

所有权和协议细节见 docs/architecture.md。

开发

pnpm install
pnpm run typecheck
pnpm test
pnpm run build
RUN_CODEX_LIVE=1 pnpm run test:live
RUN_CODEX_TOOL_LIVE=1 pnpm run test:live
RUN_CODEX_IMAGE_LIVE=1 pnpm run test:live

三条 live 测试分别验证真实图片输入、DSH 动态工具的暂停／续跑／steer／目录继承与更新，以及图片生成和 PNG 回写。它们都会使用宿主机现有的 Codex 登录；图片生成测试只应在确实需要验证该能力时执行。

License

MIT