结论：适合用 codex exec 把 Codex CLI 接入远程 Mac CI，但先锁定工作目录、沙箱和审批策略，再用受控任务验证；不适合把 Agent 的修改摘要当作 Xcode 验收，也不应让不可信 PR 接触持有凭据的持久节点。Codex 任务运行的位置，决定它能读取哪些文件、调用哪些工具。
适合从本机交互式使用转向脚本任务的 iOS／macOS 开发者。
适合维护 GitHub Actions macOS 流水线、需要管理 Runner 权限的 CI 工程师。
适合评估节点隔离、凭据管理与构建验收责任的研发平台负责人。
最后更新于 2026 年 11 月 12 日；命令与非交互模式、Runner 安全规则及 Apple 工具链要求，分别依据 OpenAI、GitHub 和 Apple 官方文档核对。
00划清 Codex、构建与调度边界
接入之前，先区分 Agent 任务、Xcode 构建测试和 GitHub Actions 调度。这些是流水线中的不同环节，不能把它们统称为“AI 构建”。
| 环节 | 负责什么 | 应用什么证据确认 |
|---|---|---|
| Codex Agent 任务 | 在指定工作区读取上下文、提出或执行代码修改 | 任务退出状态、执行日志与 Git 差异 |
| macOS 上的 Xcode 构建和测试 | 使用 Xcode 工具链编译项目、执行测试 | 构建／测试状态、日志与产物 |
| GitHub Actions | 触发作业并将其分配给 Runner | 工作流事件、Runner 标签与作业记录 |
OpenAI 将 codex exec 作为脚本和 CI 中运行 Codex 的非交互方式，并支持预先设定沙箱与审批策略。它解决的是 Agent 如何执行，并不替流水线完成 Xcode 构建或发布验收。具体行为见 OpenAI Codex 非交互模式文档。
因此，GitHub Actions 的 macOS 作业可以运行 Codex CLI，但仍须确认任务实际运行在哪台机器、哪个仓库副本和哪个提交上。Agent 修改成功、Xcode 测试通过和产物可交付，是三项不同的结果。
01准备仓库、工作区与任务输入
远程节点上的隐性问题之一，是路径正确却选错了仓库副本。同一台 Mac 可能同时存在手动克隆目录、Runner 工作目录和缓存副本；Codex 会依据实际运行位置访问文件和工具。启动前先核实工作区，避免 Agent 改了一个目录，流水线却在另一个目录构建。
| 启动前核对项 | 需要明确的内容 | 未确认时的风险 |
|---|---|---|
| 仓库与工作目录 | 本次作业的检出路径、分支和提交标识 | Agent 修改另一份克隆，流水线仍验收旧副本 |
| 触发来源 | 可信分支、内部 PR 或外部 PR | 不可信输入进入持有凭据的常驻节点 |
| 工具与交付物 | Xcode、scheme、测试目标、日志与产物保存位置 | 任务结束后缺少可复核的构建证据 |
GitHub Actions 自托管 Runner 可通过标签或组选择作业目标。Runner 默认标签包括 self-hosted、macOS 和硬件架构标签；标签用于作业路由，不证明主机上的 Xcode 已安装或版本符合项目要求。可参照 GitHub 自托管 Runner 工作流文档。
启动 Codex 前，建议先输出仓库根目录、分支和提交标识，并把任务输入作为明确的提示词或文件传入。命令里的路径、项目名与 scheme 都应替换为团队的实际值，不要依赖 Runner 默认当前目录。
02配置 Codex CLI 远程 Mac CI 的非交互权限
关键不是单纯让命令不提问，而是先决定 Codex 能读取什么、能修改什么，以及遇到哪些情况需要人工处理。Codex CLI 命令参考说明，--cd 可指定工作区根目录，--sandbox 用于指定沙箱模式；自动化应从满足任务的最小权限开始。参数细节以 Codex CLI 命令参考 为准。
| 任务类型 | 权限起点 | 配置判断 |
|---|---|---|
| 代码阅读、方案分析 | read-only |
适合首次试跑及只读检查 |
| 受控工作区修改 | workspace-write |
仅在任务确需改文件时启用，并核对差异 |
| 工作区之外或更高权限操作 | 不作为默认配置 | 仅在需求明确、代码可信且有额外隔离措施时评估 |
只读任务可从以下形式开始：
cd "$GITHUB_WORKSPACE"
codex exec \
--cd "$GITHUB_WORKSPACE" \
--sandbox read-only \
--json \
"检查项目结构并指出构建入口，不要修改文件"
--cd 明确指定工作区，避免从错误目录启动；--json 适合将结构化输出交给后续脚本处理。若任务确需改仓库文件，可在权限评审后改用 --sandbox workspace-write。不要把关闭沙箱或开放全部权限作为无人值守任务的通用配置。
认证方式也要纳入权限设计。Codex 非交互模式文档提醒，不要在会检出或运行仓库控制代码的作业级环境中暴露 OPENAI_API_KEY 或 CODEX_API_KEY；应将凭据限制在确实需要它的执行环节，并确保同一进程环境不运行不可信代码。
03试跑任务并检查工作区变化
第一次接入先跑只读任务，再验证受控写入。以下步骤是团队建议的验收流程，不是 Codex 或 GitHub 对执行结果的保证：
- [ ] 确认
$GITHUB_WORKSPACE指向本次作业检出的目录，而非节点上的其他项目副本。 - [ ] 记录仓库、分支、提交标识和触发事件，核对任务输入对应本次代码。
- [ ] 检查 Codex CLI、Xcode 和项目依赖能否从当前 Runner 环境调用。
- [ ] 运行只读任务，核对输出、工作区内容与执行日志。
- [ ] 只读结果符合预期后，用一项可审查、可撤销的修改测试写入范围。
- [ ] 保存命令退出状态、JSONL 输出和
git diff；异常时先定位原因，不要直接扩大权限。
确认工作区尤其重要：即使 Codex 在它收到的目录中完成任务，如果流水线随后在另一个检出目录运行 xcodebuild，两步也不能证明同一份代码通过验证。
04FAQ：接入前的常见判断
在 Actions 的 macOS 作业里运行 Codex CLI，需要哪些条件？
作业需要分配到具备所需 macOS 环境的 Runner，并在正确的仓库检出目录中调用 codex exec。Runner 标签只是调度条件；作业开始后仍须核对实际主机、提交标识和工具链。Codex 任务成功结束，也不代表 Xcode 构建已经通过。
如何在远程作业中指定工作区和执行权限？
用 --cd 指向本次作业检出的项目路径，并根据任务选择只读或 workspace-write。只读适合分析任务；写入权限只在任务确需修改文件时开启。不要为了让任务顺利结束，直接开放工作区之外的路径或移除沙箱。
Codex 修改代码之后，怎样核验 Xcode 结果？
由独立的流水线步骤调用项目要求的 Xcode 构建或测试命令，检查该步骤的退出状态和日志。保存提交标识、工具链调用与产物位置，确认被测试的代码和 Agent 处理的是同一工作区；Agent 的文字摘要不能替代构建和测试状态。
如何限制 CI 任务访问凭据和网络资源？
只向任务提供完成工作所必需的凭据，并收紧 GITHUB_TOKEN 权限及 Runner 的资源访问范围。对外部 PR，应使用与凭据及内部资源隔离、且不在不同信任级别任务间复用的执行环境。仅靠审批或清理工作目录，不能替代 Runner 隔离。
05独立验收远程 Mac Xcode 构建
Agent 完成代码任务后，流水线仍须独立运行 Xcode 构建和测试步骤。远程 Mac Xcode 构建的交付记录应能对应到本次代码，而不是只有一段“测试通过”的 Agent 回复。
| 验收证据 | 建议记录 | 能回答的问题 |
|---|---|---|
| 代码身份 | 仓库、分支、提交标识与工作区路径 | 修改和构建的是不是同一份代码 |
| Agent 执行 | 命令、权限模式、退出状态与 JSONL | Agent 做了什么，是否异常结束 |
| Apple 工具链 | Xcode 调用、构建／测试状态、日志 | 项目是否通过独立工具链验证 |
| 产物归属 | 产物路径及关联的作业记录 | 交付物是否对应本次提交与构建 |
工具链版本必须与节点环境匹配。Apple 当前系统要求列明，Xcode 27 需要 macOS Tahoe 26.6 或更高版本；Xcode 27 发行说明也列出了这一要求。上线前应核对实际安装版本与项目目标，并复查 Apple Xcode 系统要求 和 Xcode 27 发行说明。
06按代码来源决定节点准入
先区分可信分支与外部 PR。GitHub 提醒，自托管 Runner 不保证每次都运行在干净、临时的虚拟机中；不可信代码可能影响 Runner 环境，并接触其中可访问的秘密。具体风险与防护建议见 GitHub Actions 安全使用说明。
特别审查 pull_request_target 等高权限工作流：如果工作流检出并执行来自不可信 PR 的代码，可能让该代码处于可访问仓库秘密或高权限令牌的上下文中。GitHub 对这一事件的风险和防护方式见安全使用 pull_request_target 的说明。
据此决定是否准入：
- 可试跑：代码来源可信，工作目录明确，只开放任务必需权限，并能独立保存 Xcode 构建和测试证据。
- 限制使用：外部 PR 仅进入隔离且可回收的环境；凭据按最小权限提供，任务不接触内部资源。
- 暂缓上线：持久节点保存签名材料或长期凭据，却没有隔离与访问控制方案；或流水线无法证明被构建提交与 Agent 处理提交一致。
审批和工作目录清理都不能单独构成不可信代码隔离。若现有方案让不同信任级别的任务复用同一个持久 Runner，或让高权限凭据长期留在共享环境中，应先解决节点隔离，再考虑扩大自动化范围。
若团队正在评估执行环境，可先查看 NUKCLOUD 远程 Mac 服务说明。如果已经确认需要在 macOS 上持续执行 Codex CLI 与 Xcode 任务，再结合工作流评估是否采用独立远程 Mac；可从 NUKCLOUD 远程 Mac 方案 了解选择。长期稳定、持续重负载或必须连接物理设备的团队，也应把自购专用 Mac 纳入比较；短期试跑、临时测试或阶段性扩容，租赁则能先验证节点是否适合现有 CI，而不必一开始就把临时需求变成长期硬件运维。