症状： Codex App 能显示远程 Mac，iOS 构建却失败。 最快解法： 先确定 SSH 认证、项目目录访问、Xcode 构建三者中最早失败的一层；不要把 SSH 连通当成构建、模拟器和发布链路都已就绪。
OpenAI 于 2026 年 4 月 16 日发布的说明，将 Codex App 通过 SSH 连接远程开发机的能力标为 alpha；这条说明本身不能证明你当前账号的开放范围或界面入口。(OpenAI 对 Codex App SSH 能力的公开说明) 适合使用 Windows 或 Linux 开发、希望用 Codex App 调度远程 Mac 的独立开发者；正在排查连接、目录或命令执行问题的小团队；以及需要确认远程 Xcode 构建和测试边界的开发者。
最后更新于 2026 年 10 月 7 日；复核了 OpenAI 对 Codex App SSH 能力的公开说明，以及 Apple 关于 Xcode 系统要求和命令行工具的官方文档。功能开放范围和界面步骤仍应以你当前安装版本的实际状态为准。
先定位 Codex App SSH 远程 Mac 构建失败的最早一层
别从重装 Xcode 或反复改签名开始。先记录四件事：Codex App 是否识别远程主机、独立 SSH 客户端能否认证、预期仓库是否可读写、实际构建命令是否启动并返回错误。找到第一个不成立的环节，就从那里排查。
| 可观察到的现象 | 更可能的故障层 | 下一步检查 | 暂停条件 |
|---|---|---|---|
| Codex App 没有可用的远程主机入口 | 功能开放或应用状态 | 核对当前应用版本、账号状态和官方说明 | 尚未确认功能对当前账号开放时，不据此判断 Mac 故障 |
| 独立 SSH 客户端也无法登录 | 地址、网络或认证 | 核对主机地址、用户名、密钥选择及服务端登录权限 | 不要通过关闭主机校验或扩大登录权限来绕过问题 |
| SSH 已登录，但项目不可读写 | 用户身份、仓库或目录 | 核实远程用户、仓库位置、分支与文件权限 | 确认变更落在预期工作副本后再构建 |
| 命令已执行，但 Xcode 报错 | 开发者目录、版本或项目配置 | 核对 Xcode 路径、系统兼容性和完整构建日志 | 找到具体首条错误前，不要只凭最后一行改环境 |
| 构建成功，测试或发布失败 | 模拟器、设备、签名或上传 | 将各发布阶段分开验收 | 单次构建成功不代表整条交付链路可用 |
SSH 已连通但项目目录不可用时，先核实实际工作副本
如果独立 SSH 客户端登录正常，而 Codex App 找不到 iOS 项目，先比对两个执行上下文：你手动登录后看到的用户和目录，是否与 Codex App 实际执行任务时一致。还要确认远程仓库检出位置、当前分支和项目文件权限；不要因为某个终端能看到仓库，就推断 Agent 也能读取、修改并保存相同目录。
可以在你已确认安全的远程终端中检查当前身份、目录和 Git 状态；请将项目路径替换为脱敏占位符，不要把真实主机名、用户名或仓库地址贴进日志：
whoami
pwd
git -C "<项目目录>" status --short --branch如果 git status 显示的分支或改动位置不符合预期，先停下，确认任务没有落到另一份克隆或旧工作区。只有在项目路径、分支和读写结果都吻合后，才让 Codex App 重试构建。检查权限时优先按最小必要范围修复目标目录访问，不要把整个用户目录开放给额外账户。
提醒：排障记录里应脱敏主机地址、账号、私钥内容、仓库 URL、Bundle ID、Team ID 和敏感日志。SSH 私钥不应粘贴进对话或提交到仓库。
第二步：SSH 认证失败时，独立做一次对照测试
先核对主机名或地址、端口设置、网络可达性、SSH 用户、客户端实际选用的密钥，以及服务器是否允许该用户登录。使用独立 SSH 客户端进行对照：若两边都失败，优先查网络和服务端；若独立客户端可用而 Codex App 不行，再核对应用当前支持状态和连接配置，不要贸然更改服务器安全策略。
连接示例只保留占位符，输出日志前也应检查是否包含真实凭据：
ssh -v "<SSH 用户>@<主机地址>"重点看连接停在哪一步：无法建立连接，通常还没到密钥认证；出现认证拒绝，再检查用户与密钥是否对应；登录成功但随后命令失败，则回到工作目录和命令执行层。日志只保留错误类型和必要上下文，移除地址、用户名、密钥路径等可识别信息。
第三步：命令能执行但 Xcode 不工作，核对开发者目录
远程 Mac 上“有命令行工具”不等于安装并选中了完整 Xcode。Apple 文档说明，xcodebuild、simctl 等工具随 Xcode 提供，而单独的 Command Line Tools 包并不包含全部这些工具；该边界可以在 Apple 命令行工具参考和安装命令行工具说明中核对。
先查看当前开发者目录和工具版本：
xcode-select --print-path
xcodebuild -version
xcrun --find simctl若路径落在 Command Line Tools 目录，而项目需要 Xcode 专属工具，先确认完整 Xcode 已安装，再由有权限的管理员按团队约定切换开发者目录。xcode-select --print-path 能显示当前生效位置；Apple 也说明可通过 xcode-select 选择 Xcode。可对照命令行工具设置文档。
随后对照 Apple 的Xcode 系统要求表，确认远程 Mac 的 macOS 版本支持目标 Xcode。不要从“安装完成”推断兼容：如果系统不满足目标版本要求，应先选用受支持的 Xcode/macOS 组合，再重试项目构建。
在中间环节拆开验收：构建、模拟器、设备、签名与上传
当 SSH、项目目录和 Xcode 命令都通过后，仍需把“编译成功”和“能完成测试发布”分开看。下表按失败结果给出下一步，避免构建命令返回成功后就直接认定远程环境完整可用。
| 目标环节 | 怎样确认 | 常见边界 | 失败后先查 |
|---|---|---|---|
| 命令行构建 | 使用项目预期的 scheme 和目标执行构建，保留首条错误及退出状态 | 目标、配置和依赖必须与任务相符 | 工具链、项目设置、依赖解析 |
| 模拟器测试 | 检查对应 Simulator Runtime 与可用运行目标，再尝试启动测试 | 仅能编译，不表示所需运行时已安装或模拟器能启动 | Xcode 组件、运行目标、图形会话 |
| 实体设备测试 | 检查设备是否已连接、受信任且可被远程 Mac 识别 | 远程 SSH 会话不等于实体设备已连接到主机 | 设备连接、配对与调试权限 |
| Archive 与签名 | 检查 Bundle ID、Team、证书、私钥和 profile | 证书或 profile 缺失、过期或不匹配会使归档或分发失败 | 团队资产和签名配置 |
| 上传验收 | 上传后在 App Store Connect 查看交付与处理状态 | 命令完成不代表 Apple 后台已处理或构建已可选 | 交付日志、账号角色和后台处理状态 |
签名检查也不能只看构建是否编译通过。分发到已注册设备时，通常要核对 App ID、证书、profile 和设备注册；自动签名与手动签名的操作边界见 Apple 设备分发文档。如果要用远程 Mac 保存团队签名身份，须限制访问者并保护私钥；Apple 提醒，获得导出的签名身份并掌握其密码的人，可能以你的开发者身份分发签名软件。(Apple 签名证书共享说明)
上传则是单独的验收环节。Apple 的 App Store Connect 上传说明列出 Xcode、Transporter 等上传方式，并说明上传的构建需要经过 Apple 系统处理后才会显示。验证是否上传成功时，应同时查看交付记录和 App Store Connect 构建状态，而不是只看本地命令返回。
用条件分支决定停在哪一步
- 若独立 SSH 客户端也无法认证，先修复网络、用户名、密钥或服务端登录权限；否则不要继续排查 Xcode。
- 若 SSH 登录成功但工作副本不匹配，先定位 Codex App 使用的远程用户、目录和分支；确认文件可读写后再构建。
- 若项目可访问但
xcodebuild不可用或版本不符，先核对完整 Xcode、活动开发者目录与 macOS 兼容关系；命令行工具包不能替代所有 Xcode 专属命令。 - 若命令行构建成功而模拟器失败，转查目标 Runtime 和运行环境；不要把这一结果解释为构建失败。
- 若构建、测试通过但签名或上传失败，检查证书、私钥、profile、账号权限与交付状态；不要为排障扩大凭据权限。
- 若你的工作只要求不带模拟器的构建，记录这个验收边界；若任务包含模拟器、实体设备或上架，则逐项实际测试后再决定远程 Mac 是否合格。
留下一份可复现的远程构建记录
在你自己的脱敏项目上，按下面的次序保存结果。每一步都记录“执行环境、命令或操作、可观察结果、失败时停止位置”，下次出错就能区分是新回归还是环境从未配置完成。
- 确认当前 Codex App 实际提供 SSH 连接入口；如入口不可用，先核对官方公开状态和账号开放情况。
- 用独立 SSH 客户端验证远程登录，并记录认证成功或失败的阶段，不保存密钥和可识别地址。
- 核对远程用户、项目目录、分支与工作区改动，确认 Agent 操作会落在预期仓库。
- 检查
xcode-select路径、Xcode 版本及xcodebuild、simctl是否可调用，再对照 Apple 系统要求。 - 使用真实项目分别验收命令行构建、所需模拟器或设备测试、Archive、签名和上传；不需要的环节明确标注为未覆盖，而非默认通过。
如果你现在依靠 Windows 或 Linux 本机处理这条链路，实际短板是本机不能直接提供完整 macOS/Xcode 环境；临时借用开发机又容易遇到目录与凭据不一致；通用云端构建也未必能满足你对交互式调试、特定设备或可控签名材料的要求。反过来，若你需要全年稳定运行的高负载打包机，或必须连接手边的物理设备，先评估自购 Mac 或本地 Mac 是否更合适。仅在需要临时 Xcode 构建、复现问题或验证发布流程时，租赁 MACGPU 的远程 Mac 才可能比专门购置设备更灵活；你可以从 MACGPU 远程 Mac 入口了解可选方案，并用自己的项目逐项验收。