深入解析CodexHost运行时架构CDP注入透明代理如何实现不重做UI接入10Harness【免费下载链接】codex-hostRun Pi and Claude Code directly in Codex Desktop. 在 Codex Desktop 中直接运行 Pi 和 Claude Code。项目地址: https://gitcode.com/gh_mirrors/co/codex-hostCodexHost是一个让 Pi、Claude Code、Grok 等 10 个 Agent Harness 直接在 Codex Desktop 里运行的开源项目。它的核心思路不是重写界面而是通过CDP 注入把扩展代码塞进官方渲染进程再用透明代理Shim 拦截 Desktop 对官方 CLI 的调用让 Host Runtime 接管协议路由——一套 CodexHost 运行时架构撑起多 Harness 共存。一、不重做 UI 的底气三层协作很多人以为把多个 Agent 装进一个桌面应用就得自己画聊天框、Diff 面板和侧边栏。CodexHost 反其道而行界面 100% 复用 Codex Desktop 原生 UI自己只做三件事。层所在模块职责渲染层扩展packages/renderer-extension/注入 Desktop 页面负责 Agent 切换、委派菜单、会话展示桌面控制层packages/desktop-control/通过 CDP 发现页面目标、注入 Bundle、维持生命周期进程与协议层crates/shim/ packages/host-runtime/透明代理 CLI 调用Host Runtime 转发官方请求并调度 Harness 适配器Pi 的运行时分层也体现了同样的思路原生进程与 Host 之间走轻量桥接而非在 UI 层做适配。二、CDP 注入如何把扩展送进 Codex Desktop1. 为什么绕开 Electron Inspector早期版本通过 Electron 的 Node Inspector 端口访问webContents来安装扩展。但 Codex Desktop 26.901 起用Electron fuse 禁用了 CLI Inspector 参数这条路被官方封死。方案文档记录了这一转折点见 migrate-renderer-injection-to-cdp 提案。好在其时的Chromium Renderer CDPChrome DevTools Protocol仍然可用且恰好提供了所需的页面求值 新文档预注入原语。2. 只信任回环地址的主页面目标控制层的硬性约束写得很直白renderer-cdp-control 规范只接受 loopback CDP 来源非回环地址在注入任何源码前就拒绝连接目标选择只认主页面app://-/index.html排除头像浮层等无关页面多个主目标并存时保持已拥有的 live 目标不变启动 Desktop 时附带一个随机回环调试端口而不是长期暴露的固定端口。3. 注入即持久新文档预注册 当前文档立即求值对选定的主目标Desktop Control 会用Page.addScriptToEvaluateOnNewDocument把生产 Renderer Bundle注册给未来所有文档同时在当前文档里立即求值一次在收到绑定 ready 信号之前绝不宣告安装成功。由于 Desktop 页面是严格 CSP不允许unsafe-eval注入源码会先启用 schema 库的JIT-less 模式保证契约校验在严格策略下正常工作——这是很多注入即崩方案踩不到的细节。4. 重载与目标替换自愈Renderer 刷新、进程被替换时Session 会重新发现主页面关闭旧 CDP 客户端 → 连新目标 → 重新注册并注入 → 重装草稿请求路由 → 校验通过后才更新快照。安装失败不会伪装成已安装这保证了 running-desktop-attachment 里附着成功的真实性。三、透明代理 ShimDesktop 无感知的调用劫持UI 侧解决了看进程侧解决调。Desktop 内部所有能力最终都落到对官方codexCLI 的app-server子进程调用上——CodexHost 就在这条路上架了一座桥。1. CODEX_CLI_PATH 与递归防护启动时Launchercrates/launcher/先把当前 Desktop 对应的官方 CLI 绝对路径解析出来再把本次启动环境的CODEX_CLI_PATH指向实验 Shim。Shim 启动子进程前必须清除/重写CODEX_CLI_PATH防止子工具如 Browser Use拿着 Shim 路径再次回调自己——windows-codex-transparent-proxy-probe 规范 对此有专门场景官方 CLI 解析结果若与 Shim 自身相同形成递归链必须在创建子进程前失败stdout 不得输出任何伪造协议数据。2. 识别该由 Host 接管的 app-serverShim 的核心判断逻辑在 crates/shim/src/lib.rs 的app_server_subcommand_index只在支持的全局选项之后识别app-server子命令例如--label app-server不会误判并排除 Skysight 记忆摘要器等官方辅助服务启动的隔离 app-server。只有确认属于 Host Runtime 的调用才会拉起 Host其余调用原样转发。3. 字节透明不解析、不重序列化这是透明二字的分量所在规范要求双向 stdio 字节泵父进程 stdin → 官方 CLI stdinstdout/stderr 原路返回不添加、删除或规范化任何换行任意 chunk 边界下字节序完全一致stdout 纯净性Shim 自身的日志只能走 stderrstdout 里一个多余字节都不许有退出态传播官方 CLI 的退出码、崩溃、父进程取消都如实映射并在有界时间内清理整个进程树不留孤儿。验证也分了三层不依赖真实 Desktop 的 hermetic 测试、官方 CLI 直连 vs Shim 链路的差分测试字节层必须零差异协议层只允许按评审清单归一化动态字段以及带版本记录的真实 Windows Gate。差分脚本见 tests/differential/codex-transparent-proxy.mjs。四、Harness 适配器插件10 接入像插 U 盘一样Host Runtime 接管app-server流量后具体怎么和 Pi、Claude Code 打交道答案是动态插件化适配器规则详见 harness-plugin-runtime 文档。每个 Harness 都是 packages/adapters/ 下的一个独立包自带manifest.json和统一工厂入口createHarnessAdapter契约定义在 packages/harness-adapter/src/plugin.ts预装集合由发行清单 scripts/release/harness-plugins.json 决定Host 核心不再静态 import 任何具体适配器显式信任每个插件根目录都有enabled.json发现但未启用的插件不执行、不进入目录查询杜绝扫到就跑隔离加载最多 4 个 worker每个插件独立 10 秒超时单插件故障只标记 unavailable不拖垮其他插件。当前预装的适配器包括 Pi、Claude Code、Grok、OpenCode、OMP、DeepSeek Harness、Antigravity、Kiro CLI、CodeBuddy、WorkBuddy、Cursor CLI、Hermes、Qoder海外/中国双插件等。每个适配器各自封装该 Harness 的原生协议stdio ACP、WebSocket、RPC……对外统一映射到 Desktop 原生的 thread / turn / 工具审批模型。对新手最友好的部分是连接设置页会做CLI 自动发现 版本检查 一键更新更新的是 Harness CLI 本身不动 Host 插件。能力边界与缺口汇总在 capability-boundaries 文档。五、协议传输大历史消息如何不断流Desktop 的历史分页可能携带图片和超长工具输出单响应不保证小于 128 MiB。Host 的处理策略app-server-transport 文档packages/host-runtime/src/remote-official-connection.ts 把私有官方 WebSocket 连接转换为LF 分隔字节流接收时不设额外消息上限避免大历史页关闭连接、连坐其他请求packages/protocol-core/src/jsonl.ts 做跨块 JSONL 帧合并只在新收到的数据块里查找换行单块完整帧直接用子视图复制与扫描成本随输入字节线性增长。注意这不是流式 JSON 解析——完整帧仍需要相应内存Host 不截断图片、不改写历史也不靠自动重试掩盖传输失败。诚实的传输层是不重做哲学的最后一块拼图。六、效果速览一个窗口里的多 Agent 协作安装后npm install -g codexhost/cli codexhost在 Desktop 里就能输入#唤起跨 Agent 委派菜单每个任务在独立会话并行运行每个 Turn 末尾汇总文件变更点开右侧完整 Diff 评审。延伸阅读主题路径文档总目录docs/index.mdCDP 控制规范openspec/specs/renderer-cdp-control/spec.md透明代理验证规范openspec/specs/windows-codex-transparent-proxy-probe/spec.md插件运行时契约docs/architecture/harness-plugin-runtime.md大消息传输设计docs/architecture/app-server-transport.md本地控制台排障docs/operations/codexhost-console.md【免费下载链接】codex-hostRun Pi and Claude Code directly in Codex Desktop. 在 Codex Desktop 中直接运行 Pi 和 Claude Code。项目地址: https://gitcode.com/gh_mirrors/co/codex-host创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考