OpenCode 2.0 调用远程 Mac 上的 Xcode 失败时，先确认 OpenCode 的项目执行环境在哪台主机；仅能 SSH 登录远程 Mac，不代表 Agent 的命令和文件操作已自动转发。若你用 Windows 或 Linux 开发，本周先检查主机名、工作目录和 Git 提交，再核对远端工具链与测试结果。
适合谁看：主力开发机是 Windows 或 Linux、但需要构建 iOS 或 macOS 项目的工程师。
维护远程 Mac CI 的 DevOps 工程师，可用本文划分 Agent 工作区与构建节点的责任边界。
正在接入 Apple 工具链的技术负责人，可用排查步骤核对权限和验收证据。
最后更新于 2026 年 10 月 24 日，数据核实自 OpenCode 官方变更记录与工具文档、Apple Xcode 文档。截至该日期，OpenCode 官方变更记录已发布 V2.1.4；“OpenCode 2.0”指的是 2.x 产品线，排查时仍应核对你实际安装的版本。官方文档说明 bash 工具在项目执行环境中运行，因此先确认执行环境，再排查 Xcode，能避免把本机故障误判为远端工具链故障。(OpenCode 官方变更记录；OpenCode 工具文档)
01命令成功时，先查清它在哪台主机运行
OpenCode 的 bash 工具针对项目执行环境运行。SSH 登录成功，只能证明你能建立远程会话；它不能证明 Agent 的 bash、文件读写或项目工作区已经切换到远程 Mac。(OpenCode bash 工具说明)
在触发构建的同一终端上下文中运行以下诊断命令。不要只在另一个手动打开的 SSH 窗口里检查：
hostname
pwd
git rev-parse --show-toplevel
git rev-parse HEAD
用输出确认主机身份、当前目录、仓库根目录和提交号。若主机名指向 Windows 或 Linux 开发机，或目录是本机仓库，这次命令就没有证明它访问了远程 Mac。保存这些输出，作为后续复测的基线。
02仓库副本错位会让 Agent 改错项目
常见情况是：你在本机看到 Agent 已修改文件，远端构建却仍报告旧错误。原因可能不是缓存，而是本机和远端各有一份仓库。Agent 读写当前工作区中的文件；远端 xcodebuild 则按远端命令所在目录寻找项目。
先在两端分别记录 Git 根目录和提交号，再检查文件差异：
git status --short
git diff -- <占位文件路径>
在远程 Mac 上确认相同文件是否出现了相同变更。若要让 Agent 直接操作远端仓库，应将工作区和命令执行环境放在远端，或明确设计 SSH 调度流程。只在提示词里写远端路径，不等于 Agent 已获得该路径的读写权限。
03远程账户的工具链和权限要分开检查
Apple 文档说明，Xcode 命令行工具包含 xcodebuild。但本机能找到命令，不代表远程 Mac 的执行账户也能找到。应在实际远端构建会话中检查命令路径、活动开发者目录和工具版本。(Apple 命令行工具安装文档；Xcode 命令行工具参考)
command -v xcodebuild
xcode-select -p
xcodebuild -version
如果命令路径缺失或开发者目录不符合预期，先修正远端安装或选择状态，再查看项目错误。CI 使用的账户、启动方式和环境变量也可能与交互式 Shell 不同；应以触发构建的账户和会话为准。
权限也要拆开检查：
- 仓库访问：远端账户能否读取项目、子模块和所需依赖。
- 凭据与签名：私有依赖凭据、证书和描述文件是否对远端构建账户可用。
- Agent 权限：OpenCode 是否允许 bash 执行、编辑项目文件，或访问工作区之外的路径。
OpenCode 支持按工具配置权限。根据日志指出的具体缺项授权，不要为了排错放开整个账户或整台主机。(OpenCode 权限配置文档)
04构建通过不代表测试目标可用
xcodebuild build 成功，只能说明对应构建动作完成；它不等同于测试已经启动或通过。测试还依赖匹配的 scheme、destination，以及远程 Mac 上可用的平台支持和模拟器运行时。Apple 文档建议先选择包含目标的 scheme，再选择模拟器或实体设备作为运行目标。(Apple 运行模拟器或实体设备文档)
在远端核验项目可用的 scheme 和目标，再按项目类型选择 .xcodeproj 或 .xcworkspace。执行测试时，用仓库中的真实名称替换占位符：
xcodebuild test \
-project <占位项目名>.xcodeproj \
-scheme <占位方案名> \
-destination '<占位平台与设备>'
若项目使用 workspace，将 -project 换成对应的 -workspace 参数。不要用本机设备清单推断远端目标可用；应在远程 Mac 的实际环境中核验。目标缺失时，先排查 scheme、destination 和所需运行时，不要直接判定 Agent 执行失败。
OpenCode 远程 Mac Xcode 故障分流
按实际现象选择下一步。主机、仓库和提交还没有对应起来之前，不要盲目重装 Xcode。
| 观察到的现象 | 优先确认 | 处理方向 |
|---|---|---|
| 命令成功，但远程 Mac 上没有对应记录 | hostname、pwd、OpenCode 项目工作区 |
改用远端工作区，或明确通过 SSH 调度远端命令 |
| Agent 修改了文件，构建仍像旧版本 | 两端 Git 根目录、提交号和文件差异 | 对齐仓库副本，确认构建读取的是已修改的文件 |
远端提示找不到 xcodebuild |
远端账户的命令路径、活动开发者目录 | 修正远端工具链选择，再复跑诊断 |
| 构建通过但测试目标不可用 | scheme、destination、平台支持和模拟器运行时 | 选择远端实际可用的目标，区分 build 与 test |
| 任务结束却没有可复核结果 | 退出状态、结果包路径和流水线产物收集 | 重跑测试并保存、检查结果包 |
按顺序完成远程任务验收
- 记录版本和主机。保存 OpenCode 版本、实际执行的
hostname和pwd。版本或工具行为变更后，回看官方变更记录确认对应版本状态。(OpenCode 变更记录) - 核对仓库身份。记录远端 Git 根目录、提交号和待修改文件，确认 OpenCode 读写的是实际构建的项目副本。
- 检查工具链。在远端构建会话中运行前述诊断命令，保存
xcodebuild路径、活动开发者目录和版本输出。 - 按日志授权。分别核对仓库、依赖、签名和 Agent 文件操作权限，只补足错误日志指出的缺项。
- 明确测试目标。核实 scheme、destination 和所需运行时，再运行
xcodebuild test。把构建成功与测试目标可用分开记录。 - 留存测试产物。保存退出状态和结果包路径，并确认流水线能访问并收集该路径。Apple 文档说明，使用
xcodebuild在终端运行测试会输出 Xcode 测试结果包，其中包含会话结果等信息，可在 Xcode 中打开查看。(Apple 测试结果文档)
06⚠️ 结果包存在，不代表测试通过；退出状态成功，也不能替代对测试目标和结果摘要的检查。验收记录应能把提交、远程主机、测试命令和结果包对应起来。
常见排查问题
怎么确认终端命令运行在远程 Mac？
在触发命令的同一 OpenCode 执行上下文中检查主机名、当前目录和 Git 根目录。若这些信息指向 Windows 或 Linux 开发机，普通 bash 调用仍然在本机；另开 SSH 窗口能登录远程主机，并不会自动改变 Agent 的执行上下文。
如何让 OpenCode 操作远程 Mac 上的项目目录？
让 OpenCode 在远程 Mac 上针对该目录运行，或建立明确的远程命令调度流程。随后比对两端提交号和文件差异，确认 Agent 修改的路径与 xcodebuild 读取的仓库是同一份。
远程 SSH 会话中找不到 xcodebuild，应检查什么？
检查触发命令的远端账户和会话，而不是只检查本机或交互式登录窗口。核对远端命令路径、活动开发者目录与工具版本，再排查非交互 Shell 的环境差异。(Apple 命令行工具文档)
测试运行结束后，怎样确认结果已保存？
检查命令退出状态、远端结果包路径和流水线产物收集记录，再尝试在 Xcode 中打开结果包。结果包无法访问或未被流水线收集时，测试可能已经运行，却没有留下可交付、可复核的证据。
继续修环境，还是调整执行架构
如果你已确认 Agent、项目副本和远端工具链一致，却仍无法稳定调用 Xcode，再评估调度方式。让 OpenCode 留在 Windows/Linux、本机仓库与远端构建机之间手动同步，容易出现路径和提交错位；只靠 SSH 临时运行命令，也会增加凭据传递、输出收集和结果包留存的运维工作。这种方式适合偶发任务，不适合缺少验收记录的持续 macOS CI。
如果主力机没有 Apple 工具链，而项目需要反复进行 Xcode 构建和测试，可以先查看远程 Mac 接入与选型信息，判断是否需要一台持续可访问的真实 Mac。长期、稳定且高负载的团队节点，应按自身运维方式和使用周期评估自建；需要临时测试环境或短期接入时，再了解 VpsMesh 的 Mac 方案。先确认项目、运行时和结果留存方式，再决定是否改变执行架构。