Codex Remote SSH 怎么连接远程 Mac？2026 新手教程

症状：普通终端能登录远程 Mac，但 Codex 主机列表为空，或连接后文件仍在本地。 最快解法：先验证普通 SSH，再让 Codex 接管远端项目；不要一开始排查模型、Xcode 或提示词。

这篇教程适合只有 Windows、学校电脑或旧 Mac，但课程项目需要 macOS 或 Xcode 的学生。你已经拿到远程 Mac 的登录信息，却不知道怎样加入 Codex，也可以按下面的故障层级逐步检查。

如果你的 Codex Remote SSH 连接远程 Mac 失败，最重要的判断不是“Codex 有没有显示绿色连接”，而是：SSH 能不能登录、远端 Shell 能不能找到 Codex、项目文件夹是不是远程目录、命令结果是不是远程返回。

Last updated：2026 年 9 月 7 日。文中的连接规则、主机发现和远端执行流程已根据[官方 Remote connections 文档](https://developers.openai.com/codex/remote-connections)、[Codex 使用说明](https://help.openai.com/en/articles/11369540)和相关 macOS 文档复核。

第一步：先分清 Remote Control 和 Remote SSH

Remote Control 与 Remote SSH 不是同一个功能。

Remote Control 更接近“从另一台设备控制已经运行 Codex 的电脑”；Remote SSH 则是让桌面应用通过 SSH 进入另一台主机，并在那台主机的文件系统和 Shell 中运行项目任务。官方文档明确说明，SSH 项目可以在远端读取文件、执行命令并写入修改，而不是只把本地窗口投射到远程设备上。具体可参考远程项目执行说明。

可以把它们理解成两种不同的教室安排：

Remote Control：你远程操作自己的书桌。
Remote SSH：你从当前电脑进入另一间教室，在那里的书桌上完成作业。
Codex Remote SSH：Codex 不只是帮你看远程教室，而是把远程 Mac 当成项目的实际执行环境。

因此，远程 Mac 已经可以通过 VNC 打开桌面，并不代表 Codex 自动知道它的 SSH 地址、账号和项目路径。VNC 能看见桌面，SSH 才负责建立终端通道；两者的权限、登录方式和故障点都不同。

第二步：先把普通 SSH 连接单独跑通

远程 Mac 需要先启用合规的远程登录能力。macOS 的设置位置通常是“系统设置 → 通用 → 共享 → 远程登录”，并且可以限制允许登录的用户。官方说明中给出的基础格式是：

ssh username@hostname

你可以先在运行 Codex 桌面应用的那台电脑上打开终端。Windows 电脑可以使用系统自带的 OpenSSH 客户端、PowerShell 或你已经在使用的 SSH 工具；重点是，测试必须发生在运行 Codex 的这台电脑上，而不是在另一台已经能登录的设备上。

建议先执行：

ssh 用户名@远程Mac地址

首次连接时，如果终端要求确认主机指纹，应先核对主机来源，再决定是否接受。不要为了“赶紧连上”而关闭主机指纹校验，也不要直接把无关端口暴露到公网。远程登录的开启方式和用户限制可参照macOS Remote Login 官方说明。

根据终端表现，先做低风险判断：

终端表现	说明	下一步
超时或无法建立连接	地址、网络路径、防火墙或 SSH 服务仍未打通	先确认远程 Mac 在线，并向管理员核对地址与端口
Connection refused	主机可达，但 SSH 服务没有接受连接	检查远程登录是否开启，暂时不要改动无关服务
Permission denied	用户名、密码、密钥或账号权限不匹配	核对账号和密钥，确认该账号被允许远程登录
成功进入 Shell	基础 SSH 已通过	继续检查远端 Codex 和 SSH 配置

**如果普通 SSH 还不能登录，是否应该直接在 Codex 里反复重试？** 不应该。Codex 只是使用 SSH 这条通道的“助教”，不能替你修复地址错误、账号错误或远程登录未开启的问题。先确认能进入教室，再让助教开始读取项目。

如果你想先处理 Windows 侧的登录安全设置，可以参考 MACGPU 的Windows 连接远程 Mac 新手入口，先把远程登录、账号和连接方式整理清楚。

第三步：让 Codex 找到具体的 SSH 主机

普通终端能登录，但 Codex 主机列表为空，最常见的原因是：你只记住了地址、账号和密码，却没有把主机写成 Codex 能读取的 SSH 配置别名。

官方文档说明，Codex 会从 ~/.ssh/config 读取具体的主机别名，并通过 OpenSSH 解析；只有通配规则的配置不会被当成可直接选择的主机。你可以在本机 SSH 配置中加入类似内容：

Host study-mac
  HostName 远程Mac地址
  User 远程用户名
  IdentityFile ~/.ssh/id_ed25519

这里的 study-mac 就是门牌号。Codex 需要看到这个具体门牌，才能把它列入可用主机；只有“某类主机都适用”的模糊规则，通常不能直接变成一个可选连接。

保存后，在运行 Codex 的电脑上测试：

ssh study-mac

如果这个命令能够进入远程 Mac，再打开 Codex 桌面应用，进入“设置 → 连接”，查看 SSH 主机列表。根据当前版本和账号灰度情况，界面名称或位置可能略有变化；如果完全没有 SSH 连接入口，先更新应用并确认账号具备 Codex 使用权限，不要直接套用社区中未经验证的配置开关。

Codex 为什么看不到我已经能登录的 SSH 主机？ 通常不是因为 Codex 不支持这台 Mac，而是因为主机没有写进当前运行 Codex 的电脑上的 ~/.ssh/config，或者配置里只有通配符、没有可识别的具体别名。还要注意，你在学校电脑上配置过 SSH，不代表家里的 Windows 电脑也有同一份配置。

第四步：在远程 Mac 上确认 Codex 本身可用

主机能被发现，只说明 Codex 找到了 SSH 门牌；它还需要通过 SSH 在远程 Mac 上启动远端 Codex 服务。

官方连接流程要求在远端主机安装并完成 Codex 授权，而且远端登录 Shell 的 PATH 必须能够找到 codex 命令。换句话说，本地电脑装好了 Codex，不代表远程 Mac 也装好了；这其实是两间教室里的两套工具。

登录远程 Mac 后，先执行：

command -v codex

如果能返回 Codex 命令路径，再检查：

codex --version

如果出现“command not found”，优先检查三件事：

远程 Mac 是否完成官方安装流程；
远程账号是否完成登录或授权；
SSH 登录使用的 Shell 是否加载了包含 Codex 的 PATH。

这里最容易踩坑的是“交互式终端能找到，Codex 却找不到”。你手动打开的终端可能读取了额外的启动文件，但桌面应用通过 SSH 启动服务时，使用的是远程用户的登录 Shell。官方文档特别要求 codex 在该 Shell 的 PATH 中可用，因此不要只在 VNC 桌面里双击过一次应用，就认为远端命令已经配置完成。

远程 Mac 需要安装 Codex 吗？ 如果你使用的是桌面应用的 Remote SSH 流程，远程 Mac 通常需要具备可被 SSH 启动和授权的 Codex 命令。仅在 Windows 本机安装 Codex，不能自动把远程 Mac 变成完整的 Codex 执行环境。具体安装命令和账号条件，应以发布时的官方 Codex 使用说明为准。

第五步：连接后必须选择远程项目文件夹

当 Codex 显示 SSH 主机已连接，不要立刻打开正式课程仓库。先在远程 Mac 上准备一个没有密码、密钥和个人资料的测试目录，例如：

mkdir -p ~/codex-remote-check
cd ~/codex-remote-check
printf "remote-check\n" > location.txt
pwd

然后在 Codex 中选择已经连接的 SSH 主机，并明确选择远程项目文件夹。官方流程要求在连接主机后选择远程项目目录；只有选定项目后，Codex 才有明确的文件范围和运行位置。远程项目会使用远程文件系统和远程 Shell，而不是继续沿用本地打开的文件夹。相关行为可查看官方 SSH 主机连接步骤。

为了确认命令确实发生在远程 Mac，可以让 Codex 完成三项无破坏检查：

pwd
uname -s
ls -la

你需要看到：

pwd 指向远程 Mac 的测试目录；
uname -s 返回远程系统信息，而不是 Windows 本地环境；
ls -la 能看到刚刚在远程目录创建的 location.txt。

**Codex 已经连接远程 Mac，但项目还是在本地运行，应该怎么办？** 先看当前聊天或项目底部显示的运行位置，再确认你是否从 SSH 主机中选择了远程项目文件夹。仅有“主机已连接”并不等于当前任务已经切换；如果项目目录仍是本地路径，先关闭当前本地项目，再重新从远程主机打开测试目录，最后用 pwd 和 uname -s 验证。

这一步可以用一个简单类比理解：绿色连接状态只是说明你拿到了教室钥匙，选择远程项目文件夹才是你真正坐到那间教室的书桌前。

第六步：用可撤销的小任务验收远端执行

第一次不要把正式课程仓库、支付项目或包含个人密钥的目录交给 Codex。先使用可丢弃的示例项目，要求它完成一个很小、可检查、可回退的任务：

先解释当前目录结构，不允许修改文件；
新建一个简单的说明文件，或在已有示例中增加一行注释；
展示修改差异；
执行项目自带的无破坏验证命令；
由你确认后，再决定是否保留修改。

验收时重点检查四项：

✅ Codex 能读取正确的远程项目目录；
✅ 修改前后差异清楚，并且可以通过 Git 或手动删除回退；
✅ 命令输出来自远程 Mac；
✅ 断开连接后，文件仍保存在你预期的远程路径。

第一次不要授权以下操作：

❌ 删除整个目录或批量清理文件；
❌ 读取、上传或改写 SSH 私钥、API 密钥和课程账号凭证；
❌ 修改系统目录、登录 Shell 或网络配置；
❌ 执行来源不明、用途解释不清的安装命令。

如果项目需要 Xcode，Remote SSH 可以让 Codex 在远程 Mac 的文件系统和 Shell 中运行项目命令，但它不等于完整的图形界面远程控制，也不保证所有模拟器、签名和图形交互流程都能只靠 SSH 完成。

Codex Remote SSH 能不能运行 Xcode 项目？ 可以运行适合命令行执行的构建、检查和测试任务，前提是远程 Mac 已正确安装 Xcode、项目依赖和必要的开发组件。官方资料也说明，远程执行 Xcode 测试可能依赖远程 Mac 上已有的用户图形会话；涉及 iOS 模拟器或图形界面时，不能只把“SSH 能登录”当成全部条件。可参考远程构建 macOS 项目的官方说明和Xcode 远程测试说明。

用条件分支决定是否继续使用远程 Mac

完成最小任务后，不要只凭“连接成功”决定长期方案。按下面的条件判断：

若课程必须使用 macOS、Xcode 或 iOS 工具，且你每周都会连接多次，则继续使用远程 Mac，并固定项目目录和保存方式。
若你只是在学习 SSH、Shell 或 Codex 基础功能，则可以先使用短期环境，不必立刻投入长期设备成本。
若项目代码需要持续访问本地 USB 设备、真机调试或稳定图形界面，则优先考虑本地 Mac，远程 SSH 只作为补充。
若你经常找不到主机、项目路径反复切回本地，或远程 Mac 无法保持在线，则先修复交付和连接稳定性，再把正式课程仓库迁移过去。
若你完成不了“读取远程文件、修改可回退、命令在远端执行、文件能落盘”这四项验收，则不要把远程 Mac 当作已经可用的学习环境。

方案	适合的学习任务	主要限制	连接后的判断
Windows 本地 + 本地 Codex	Python、网页、基础算法和不依赖 macOS 的课程	无法提供 macOS 专属工具	课程不需要 Xcode 时优先
Windows + Codex Remote SSH + 远程 Mac	需要远程读取项目、运行 Shell、使用 macOS 工具	依赖 SSH、远端 Codex、项目目录和网络连续性	完成四项最小验收后再用正式项目
本地旧 Mac	需要持续图形界面、模拟器或真机调试	系统版本、存储空间和性能可能受限	能安装课程要求的软件时更直接
MACGPU 的远程 Mac	没有合适本地 Mac，但想按周或按月测试真实环境	仍需学习远程连接和项目保存方法	适合先验证课程是否真的需要 macOS

如果你目前的电脑方案是 Windows 加本地工具，它的真实缺点通常是：不能直接提供完整 macOS 环境、遇到 Xcode 课程时需要临时换设备、项目文件可能在多个环境之间来回同步。虚拟机或旧 Mac 也可能受到硬件兼容、系统版本和权限限制。对于只想先完成课程实验、验证 Codex Remote SSH 工作流的学生，使用 MACGPU 的[远程 Mac 方案入口](https://macgpu.com/zh/m4-dinggou.html)先做一次最小项目验收，通常比直接购买一台长期设备更容易控制投入；但如果你长期高频运行重负载任务，或必须连接实体设备，本地 Mac 仍然更合适。

先把四项验收结果保存下来：普通 SSH 成功、Codex 能发现主机、远端命令可用、项目文件能在远程目录落盘。 这四项都通过后，你再决定是继续使用当前环境，还是进一步了解 MACGPU 的远程 Mac 连接与租用方式。