CodexHost

在 Codex Desktop 中运行 Pi 和其他 Harness

我们认为 Codex Desktop 提供了目前最好的桌面开发交互体验。

但 Codex 并不是唯一优秀的 Agent Harness，也有人偏好 Claude Code 和 Pi Agent。

CodexHost 让你在 Codex Desktop 中选择真正执行任务的 Agent，同时保留 Codex 的原生体验，并让它们协作完成任务

⭐ 如果这个项目对你有帮助，请给我们一个 Star！⭐

_{简体中文 · English · 한국어}

快速导航： 界面预览 • 快速使用 • 功能状态 • 跨 Agent 协作 • 远程连接 • 加入交流群 • 开发

界面预览

无需切换应用，Pi、Claude Code、OpenCode、OMP、Grok Build 和 DeepSeek Harness 都可以在同一个 Codex Desktop 窗口中直接使用。

codexhost-demo-github.mp4

界面

快速使用

使用 npm

支持 macOS、Windows 和 x64/ARM64 Linux。

npm install -g @codexhost/cli
codexhost

或下载 安装包（macOS、Windows）

安装问题排查

macOS - Apple 验证问题

首次打开时如提示应用无法验证，请执行：

xattr -dr com.apple.quarantine /Applications/codexhost.app

Windows - 绿色解压版 Codex Desktop

如使用绿色版本，将 CODEXHOST_INSTALL_ROOT 设置为 Codex Desktop 的解压目录：

[Environment]::SetEnvironmentVariable("CODEXHOST_INSTALL_ROOT", "D:\CodexPortable", "User")

然后完全退出 Codex Desktop，重新打开终端并启动 codexhost。

外观设置

在 设置 → 外观 中可以开启 换行显示思考文本，让思考块中的长行自动换行。该选项默认关闭，选择保存在本机并立即生效，普通 Shell 输出不受影响。

更新检查与 GitHub 限流

codexhost 优先通过已登录的 GitHub CLI（gh auth login --hostname github.com）检查最新 Release，使用账户的 API 额度，减少共享代理出口的匿名限流影响。凭证由 gh 管理，codexhost 不读取或保存 Token。

未安装、未登录或调用失败时会回退到公开 API；单次 gh 调用最多等待 5 秒。支持 PATH、macOS Homebrew 和常见 Windows/Linux 安装位置；也可通过 Host 环境变量 CODEXHOST_GH_COMMAND 指定可执行文件路径（不带参数）。安装包下载和校验流程保持不变；认证请求仍受 GitHub 账户及次级限流约束。

交互展示

完整工作界面
Agent、账号与 Model 选择	Usage 与费用信息
多账号与额度管理
macOS 会在原生 ChatGPT 菜单栏图标内追加剩余额度百分比，Windows 则使用任务栏覆盖图标；优先使用 5 小时窗口，没有时回退到 7 天窗口。
Mermaid 图表可视化渲染

功能状态

能力
流式回复	原生	✅	✅	✅	✅	✅	✅	✅	✅	✅
工具状态	原生	✅	✅	✅	✅	✅	✅	✅	✅	✅
Edit Diff	原生	✅	✅	✅	✅	✅	✅	✅	✅	✅
提问 / 取消	原生	✅	— / ✅	✅	✅	✅	✅	✅	✅	✅
Model / Thinking 选择	原生	✅	✅	✅	✅	✅	✅	✅	✅	✅ / —
工具审批	原生	✅	—	✅	✅	✅	✅	—¹	✅	✅
权限模式	原生	—	✅	✅	✅	✅	✅	✅	✅	✅
Agent 间任务协作	✅	✅	✅	✅	✅	✅	✅	✅	—	—
Usage	原生	✅	✅	✅	✅	✅	✅	✅	✅	—
Fork	原生	✅	✅	✅	✅	✅	✅	✅	—	—
上下文压缩	原生	✅	✅	✅	✅	✅	✅	—	—	—
斜杠命令	原生	✅	✅	✅	✅	✅	✅	✅	—	—
修订上一条消息	原生	✅	✅	✅	✅	✅	✅	✅	—	—

**Antigravity：**¹ 仅提供 Skip permissions（危险），使用原生 --dangerously-skip-permissions；codexhost 不添加工具审批、权限规则或工作区读写限制，请仅在可信环境中使用。旧的 Configured permissions / Desktop approvals 不再支持，需明确选择 Skip permissions。提问仍支持单选和文本，子代理支持原生卡片与只读过程记录。详见权限说明和子代理说明。

跨 Agent 协作

你可以让当前 Agent 把独立任务交给另一个 Harness。例如：

让 claude-code 独立审查这次修改，并指出兼容性风险。

让 pi 调查这个测试为什么偶发失败。

让 omp 实现这个功能，我继续整理文档。

让 opencode 在独立 Thread 中验证这个修复，并运行相关测试。

CodexHost 会为目标 Harness 创建独立的 Native Session。委派会话将出现在 Codex Desktop 的会话列表中，你可以随时打开、查看进度或继续对话。

远程连接 Harness

在本机的 Codex Desktop 中使用远程节点上的 Harness，在远程机器执行任务，同时继续使用 Codex Desktop 的统一界面。两端需要安装相同版本的 codexhost。

支持两种连接方式：

1️⃣ SSH 远程（推荐用于 Mac/Linux 服务器）

通过 SSH 连接并控制其他开发节点上的 Harness，需要 Codex Desktop 原生 SSH 工作区。

客户端 ↓ / 远程 Host →	macOS	Linux	Windows
macOS	✅	✅	❌
Linux	✅	✅	❌
Windows	✅	✅	❌

在 SSH 远程主机上执行：

npm install -g @codexhost/cli
codexhost remote install
codexhost remote start
codexhost remote status

然后通过本地 codexhost 启动 Codex Desktop，打开 SSH 工作区，在远程输入框的 Agent/Model 选择器中选择目标 Harness。

查看 SSH 配置、诊断与卸载文档 →

2️⃣ Remote Control 远程（实验 · 推荐用于 Windows）

Windows 作为被控 Host 时，可以保留 Codex Desktop 官方配对、账号认证和 relay，在另一台已配对电脑的 Codex Desktop 中使用 Windows 上的 Harness。需先确保官方 Remote Control 已经可以运行原生 Codex 任务。

这条链路不新增公网服务或 TCP 端口；Harness 凭据仍保留在被控 Windows 上。

查看 Remote Control 配置、传输边界与诊断文档 →

怎么做的

多数「多 Agent 客户端」通过 ACP 协议接入不同 Harness。接入快，但工具、审批、权限、Diff、提问等原生能力会先被削平。

CodexHost 尽量不走这条路：

• Desktop 侧：用 CDP / Electron Inspector 在官方 Codex Desktop 上增强 Agent 选择与会话界面，不重做聊天壳，也不改官方安装包
• 协议侧：用 CLI Shim 透明接入官方 app-server；Codex 请求原样转发
• Harness 侧：按各自原生接口接入。Pi 走官方 RPC，Claude Code 走 Agent SDK / CLI，再投影到 Desktop 已有的流式输出、工具、Diff、审批和提问
• 编排侧：为被委派的 Harness 创建独立 Native Session 与普通可写 Thread，并单独保存委派关系。创建与结果观察彼此分离，发起方显式选择读取、等待或后台运行

目标是保真，不只「能聊」。流式、工具状态、可靠 Patch、原生审批和提问，都尽量来自 Harness 自己，而不是 Host 猜测或伪造。

加入交流群

加入交流群 对 CodexHost 用法、功能感兴趣的开发者可以扫码加入微信群交流。 安装问题可以加群询问 功能建议与反馈 开发问题讨论 Bug 问题建议提交 issue 欢迎一起贡献~

开发

提交 Issue 或 PR 前可阅读贡献说明；PR 标题标签、简短 CI 结果和发布前校验见仓库维护自动化。

环境要求：官方 Codex Desktop、Node.js 22.19+ 或 24、Rust。

git clone https://github.com/BytePioneer-AI/codex-host
cd codex-host
npm ci
npm start

运行架构

以 Pi 为例。从左到右是一次请求的调用链：Desktop → 公共层 → Pi 插件 → 原生进程。

新增 Harness

主要实现插件的 Manifest、工厂、Adapter、Session 及原生通信与转换逻辑。当前 Renderer 仍有静态接线，完整 Desktop 接入还需单独处理。 新增 Harness 时，可以让编码 Agent 使用仓库内的 codexhost-add-harness Skill。它说明了插件结构、公共 Adapter 接口、能力实现与测试要求。

鸣谢

• 感谢 LINUX DO 社区一直以来的支持。
• 感谢 Paseo 项目在多 Harness 接入思路与架构设计方面带来的启发与参考。