如何用CodexHost进行远程开发：在VPS上SSH运行Claude Code的完整教程
【免费下载链接】codex-hostRun Pi and Claude Code directly in Codex Desktop. 在 Codex Desktop 中直接运行 Pi 和 Claude Code。项目地址: https://gitcode.com/gh_mirrors/co/codex-host
CodexHost 是一个开源框架，它让Claude Code、Pi 等 Agent 直接运行在 Codex Desktop 里，并且支持把 VPS 作为远程工作区，通过 SSH 在远端机器上运行 Claude Code——任务跑在服务器上，界面留在你的电脑。本文将带你从零完成 VPS 远程开发环境的搭建。
一、CodexHost 是什么？为什么适合 VPS 远程开发
传统远程开发需要 SSH 进服务器、装终端工具、手工切换 Agent，体验割裂。CodexHost 的做法是：
- 本机只装一个 Codex Desktop：通过扩展（而非替换）官方桌面端，提供完整的会话列表、Diff 审查、Fork、用量面板。
- 远端只装 codexhost 运行时：Claude Code 只安装、只登录在 VPS 上，凭据不会经过 SSH 传输。
- 多 Harness 统一入口：Claude Code、Pi、Grok 等 10+ 个 Agent 共用同一个窗口，还能用
#把一个任务委派给另一个 Agent。
详细原理见官方文档 README.md 与远程 SSH 指南 docs/platforms/remote/remote-ssh-host.md。
二、开始之前：前置条件清单 📋
| 机器 | 系统要求 | 需要安装 |
|---|---|---|
| 本机（开发电脑） | macOS / Linux / Windows | Codex Desktop + codexhost |
| VPS（被控端） | macOS 或 x64/ARM64 Linux（暂不支持 Windows） | Codex CLI +与本机相同版本的 codexhost |
另外确认两点：
- Claude Code 已在 VPS 上安装并完成登录；
- Codex Desktop 原生 SSH 工作区可用（设置 → 连接 → SSH）。
三、VPS 上安装 codexhost：只需 4 条命令
SSH 登录你的 VPS，依次执行：
npm install -g @codexhost/cli codexhost remote install codexhost remote start codexhost remote status关于remote install可以放心：它只在 SSH 会话的 Shell 配置里加入一段带标记的配置（修改前自动备份），不会动你本地的 Shell 和原有codex命令；在 macOS 上还会装一个当前用户的 LaunchAgent 用于在登录会话中启动 Claude Code，它不读取钥匙串或任何凭据。
如果remote status提示 degraded 或需要重装，重新执行remote install再remote start即可。
四、在 Codex Desktop 中连接 VPS 的 SSH 工作区
- 本机先通过 codexhost 启动 Codex Desktop（
npm install -g @codexhost/cli后运行codexhost）； - 进入设置 → 连接 → SSH，添加你的 VPS：
- 回到主界面，打开这个 SSH 工作区。侧边栏里会出现你的远程项目，所有对话都直接发生在 VPS 上：
五、选择 Claude Code，开始远程编码 🚀
在输入框右下角的Agent / Model 选择器中，切换到 Claude Code（或 Pi 等其它已登录的 Harness）即可：
随后你就能在本地窗口享受完整体验，而实际执行全部发生在 VPS 上：
- 流式回复 + 工具状态：编辑、命令执行实时可见；
- Diff 审查：每一轮变更自动汇总，点 Review 打开完整 Diff 面板；
- 用量面板：上下文占用、缓存命中率、费用估算一目了然。
Claude Code 的适配实现位于 packages/adapters/claude-code/，核心适配器为 claude-code-adapter.ts，通过 Agent SDK 与 Claude Code 原生接口通信。
六、常用命令与版本升级 🔁
codexhost remote status # 查看运行状态和安装完整性 codexhost remote start # 启动（可重复执行） codexhost remote stop # 停止，不影响其他 Codex 进程 codexhost remote uninstall # 卸载，保留 Thread 映射数据版本升级：两台机器用同一包管理器升级到相同版本 → 在 VPS 上重新执行remote install和remote start→ 重新连接 SSH 工作区。
七、常见问题快速排查 🛠️
| 现象 | 解决办法 |
|---|---|
提示codexhost/harness/inspect is unsupported | VPS 未接入 codexhost：确认已安装并启动相同版本，再重连 SSH 工作区 |
| 连接几秒后断开，再连一次才成功 | 旧 listener 残留控制 socket：重连一次通常即可；仍失败则确认 VPS 上无 listener 进程后删除~/.codex/app-server-control/app-server-control.sock再重连 |
| 看不到某个 Harness | 检查它是否在 VPS 上已安装并登录，然后在设置中点击「重新诊断连接」 |
原生 Codex 请求Official request failed | codexhost 会自动退避重启官方进程，重连即重试；持续失败则remote stop后remote start |
更完整的排障清单见中文文档 docs/platforms/remote/remote-ssh-host.zh-CN.md。
八、安全提示：凭据不出 VPS 🔒
这套方案最重要的设计是：Claude Code 只登录在 VPS 上，登录凭据始终留在被控机器，不通过 SSH 转发。本机不持有任何远端 Agent 的密钥，即使笔记本被检查，也不会暴露你的远端账号信息。
结语
用 CodexHost 做 VPS 远程开发，本质上就是把「装 codexhost 的 VPS + 原生 SSH 工作区 + 一个 Agent 选择器」三件事拼起来。装好之后，你就可以坐在家里用桌面级体验，驱动服务器上的 Claude Code 干活了。🎉
【免费下载链接】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），仅供参考
