CodexHost 能让您在 Codex Desktop 中直接运行 Pi、Claude Code 等不同 AI 编程代理 (Harness) 的工具
这份详细的部署教程将指引您安装和使用 CodexHost——一个能让您在 Codex Desktop 中直接运行 Pi、Claude Code 等不同 AI 编程代理 (Harness) 的工具。它保留了 Codex Desktop 优秀的原生体验，同时拓展了底层 Agent 的选择。
CodexHost 的核心价值在于统一入口和体验保真。您无需在多个应用间切换，就能在 Codex Desktop 的界面中，自由选择 Pi、Claude Code 等不同代理来执行任务。它通过技术手段尽可能保留了各代理原生的流式响应、工具调用、代码 Diff 和审批流程，而不是简单地做一个聊天外壳。
整个部署流程非常简单，您只需通过 npm 全局安装 CLI 工具即可。
📥 安装
使用 npm 安装 (推荐)
打开终端，执行以下命令即可完成安装。此方式支持 macOS、Windows 以及 x64/ARM64 架构的 Linux。
1 | npm install -g @codexhost/cli |
下载独立安装包
您也可以从项目的 Releases 页面 下载适用于 macOS 或 Windows 的安装包。
⚙️ 首次配置 (针对特定情况)
macOS - 绕过应用验证
首次打开 codexhost 时，如果系统提示应用无法验证，请在终端执行以下命令：
1 | xattr -dr com.apple.quarantine /Applications/codexhost.app |
Windows - 使用绿色便携版 Codex Desktop
如果您使用的是免安装的绿色版 Codex Desktop，需要在启动 codexhost 前，设置一个环境变量来指向 Codex 的安装目录。
1 | [Environment]::SetEnvironmentVariable("CODEXHOST_INSTALL_ROOT", "D:\CodexPortable", "User") |
设置完成后，重新打开终端并启动 codexhost。
🚀 使用方式
安装并启动后，您会看到 CodexHost 的界面。您可以在其中选择要使用的 Agent (如 Pi 或 Claude Code)，并像使用原生 Codex Desktop 一样进行交互。
- 选择 Agent：在主界面中的 Agent/Model 选择器中，选取您想使用的 Harness (例如 Pi 或 Claude Code)。
- 工作流程：随后，您可以通过 Codex Desktop 的原生界面输入指令，CodexHost 会将其转发给您选择的 Agent 执行，并将结果（流式输出、工具调用、代码修改等）实时反馈在 Codex 窗口中。
🌐 远程连接 (高级功能)
CodexHost 支持在本机的 Codex Desktop 中，使用远程服务器上的 Harness。这允许您在本地界面操作，但任务在远程更强的机器上执行。两端需要安装相同版本的 codexhost。
1. SSH 远程 (推荐用于 Mac/Linux 服务器)
在远程主机上：安装并启动 codexhost 的远程服务。
1
2
3
4npm install -g @codexhost/cli
codexhost remote install
codexhost remote start
codexhost remote status在本地：通过 codexhost 启动 Codex Desktop，打开一个 SSH 工作区连接到远程主机，然后在 Agent 选择器中选择目标 Harness 即可。
2. Remote Control 远程 (实验性，推荐用于 Windows 作为被控端)
此方式允许您在一台已经配对的电脑上，使用另一台 Windows 电脑上的 Harness。它利用 Codex 官方的 Remote Control 通道，不新增公网服务或端口。具体配置请参考项目文档。
🛠️ 开发者指南
如果您想从源码构建或为 CodexHost 贡献代码，请按以下步骤操作：
环境要求：需要安装官方 Codex Desktop、Node.js 22.19+ 或 24 版本，以及 Rust。
克隆并启动：
1
2
3
4git clone https://github.com/BytePioneer-AI/codex-host
cd codex-host
npm ci
npm start
📚 了解更多
- 功能状态：项目文档中的“功能状态”表格详细列出了对不同 Harness (如 Pi, Claude Code) 的各个原生功能（如流式回复、Edit Diff、工具审批等）的支持程度。
- 交流与反馈：您可以通过加入项目的微信群进行交流，或通过 GitHub Issues 提交问题和建议。
