VS Code Remote Agent Sessions 怎么用？2026 远程 Mac 部署

VS Code 官方资料显示，Agents window 可以管理远程 Agent 会话，并通过 SSH、经过身份认证的 Dev Tunnel 或浏览器入口连接远程主机。远程主机必须保持开机且网络可达，远程目录也必须能被目标账户访问。VS Code Remote Agent Sessions 官方说明

部署前不要只测试“端口是否能通”。你需要把远程 Mac 的状态拆成三层：

• SSH 已连通：ssh <remote-user>@<host> 能登录，退出码正常。
• 工作区可打开：VS Code Agents window 能找到远程主机，并打开 <remote-workspace>。
• 工具链可用：同一账户能够调用 Git、项目依赖、Xcode CLI 和项目脚本。

继续部署的最低条件如下：

• ✅ 使用独立账户，例如 <remote-user>，不要直接复用管理员账户。
• ✅ 仓库访问范围明确，确认 <repo-url>、SSH key 或访问令牌的权限。
• ✅ 使用独立试验目录，不要一开始就指向生产签名目录。
• ✅ 失败后可以清理工作区、撤销凭据并重新建立会话。
• ✅ 已经写好停止条件，出现权限或工具链异常时不继续放大 Agent 权限。

macOS 的 Remote Login 是 SSH 入口的基础。Apple 文档说明，启用 Remote Login 后，其他设备可以通过 SSH 或 SFTP 访问 Mac；你还需要限制允许登录的用户范围，而不是只打开系统开关。Apple Remote Login 官方文档

先在本地终端验证：

ssh <remote-user>@<host>
whoami
pwd

如果这一步失败，不要进入 Agents window 排查。先处理主机名、网络入口、用户权限、SSH key 和 macOS 防火墙问题。

SSH 和 Dev Tunnel 解决的不是同一个问题。你应该根据网络入口、身份认证和运维责任来选，而不是把它们简单排成“速度更快”和“速度更慢”。

SSH：适合可控的网络入口

优先选择 SSH 的条件：

• 你能控制远程 Mac 的网络入口和防火墙策略。
• 团队愿意维护 SSH key、用户权限和主机指纹。
• 你需要从终端先复现问题，再交给 Agents window。
• 你希望登录、目录访问和审计集中在主机侧。

VS Code 的 Remote SSH 文档建议先在终端验证 SSH 登录，再从编辑器中打开同一个主机。这样可以把网络故障、Shell 故障和 Agent 故障分开。Remote SSH 官方配置文档

Dev Tunnel：适合受限网络和移动管理

Dev Tunnel 更适合以下情况：

• 远程 Mac 不适合暴露 SSH 入站端口。
• 你需要从移动设备或浏览器管理会话。
• 网络环境限制入站连接，但允许远程主机建立出站连接。
• 团队已经有统一的账户认证和 Tunnel 生命周期管理。

Dev Tunnel 必须启用账户认证。匿名访问不应进入可接受方案，尤其不能与自动批准模式叠加。你还要记录 Tunnel 停止、远程 Mac 重启和重新发现主机后的实际状态。VS Code Remote Tunnels 官方文档

对照决策清单

选择 SSH，如果：

• 你能稳定维护主机入口。
• 需要明确的用户和目录边界。
• 需要用命令行快速复现 Agent 的失败命令。
• 远程节点长期作为固定开发或构建节点使用。

选择经过认证的 Dev Tunnel，如果：

• 远程 Mac 位于不方便开放 SSH 的网络。
• 你需要从浏览器或移动设备发起会话。
• 团队能统一管理账户登录和 Tunnel 生命周期。
• 你接受额外验证 Tunnel 是否存活、是否重新连接。

两者都不应直接上线，如果：

• 只能使用匿名 Tunnel。
• 所有开发者共用管理员账户。
• 远程目录包含生产证书和长期令牌。
• 断线后没人知道会话是否仍在执行命令。

连接成功后，Agent 的命令会在远程 Mac 的 Agent Host 环境中执行，不是在你本地 Windows、Linux 或移动设备的终端中执行。实际结果会受到登录用户、工作目录、默认 Shell、环境变量和审批状态影响。

先让 Agent 执行只读命令：

whoami
pwd
echo "$SHELL"
echo "$PATH"
git status --short

然后按顺序验证执行闭环：

1. 读取代码：只允许检查 <remote-workspace> 下的目标文件。
2. 受控修改：只允许修改 <allowed-path>。
3. 依赖检查：执行项目规定的依赖检测命令。
4. 最小测试：先运行单个测试或静态检查。
5. 差异审查：使用 git diff 检查修改范围。
6. 回退验证：确认可以撤销改动，并重新建立干净工作区。

如果本地终端能成功，但 Agent 会话失败，优先检查以下证据：

• 登录 Shell 是否加载了不同的配置文件。
• PATH 是否包含正确的 Xcode、Homebrew 和语言运行时路径。
• Agent 当前目录是否与手动执行命令的目录一致。
• 命令是否被工具审批、文件访问或外部 URL 访问规则拦截。
• 当前用户是否能读取仓库、写入构建目录和访问所需的钥匙串项目。

VS Code 将终端命令、文件操作、URL 访问和其他工具的批准拆分管理。预览阶段建议使用手动批准，确认命令参数后，再按会话或工作区范围放行。VS Code Agent 审批官方说明

远程 Mac 能执行 xcodebuild，不代表完整的 iOS 开发链路已经就绪。你必须在同一账户下验证活动开发者目录、Xcode CLI、项目依赖和目标构建环境。

先执行：

xcode-select -p
xcodebuild -version
xcrun --find xcodebuild
xcrun simctl list devices

Apple 的 Xcode 命令行工具文档说明，命令行构建依赖正确安装的 Xcode 和活动开发者目录。若 xcode-select -p 指向错误位置，Agent 可能能够连接主机，却无法完成项目命令。Apple Xcode 命令行工具参考

把结果分成四级，不要用一个成功命令代替全部验收：

1. 命令可执行：xcodebuild -version 能返回版本信息。
2. 项目可构建：指定 <workspace>、<scheme> 和 <destination> 完成非发布构建。
3. Simulator 可用：能发现目标运行时，并完成受控测试。
4. 签名与发布可用：证书、Provisioning Profile、钥匙串和 Team ID 在目标账户下均可工作。

前两级适合 Agent 试跑。涉及图形会话、Simulator 状态、真机连接、签名资产或生产发布时，应转入独立验收流程。Xcode 的构建设置、签名身份和团队标识并不会因为 Remote Agent Sessions 已连接而自动具备。Apple Xcode 构建设置参考

建议使用不含生产凭据的测试项目执行第一轮构建。等到代码修改、依赖检查和非签名构建都稳定后，再单独安排归档、导出和发布验证。

共享远程 Mac 的主要风险不是 Agent 会不会写代码，而是它能读取什么、能执行什么，以及权限是否会长期保留。

个人节点可以使用独立工作目录。共享节点则至少隔离以下对象：

• 账户：为项目或团队使用独立 <remote-user>。
• 仓库：使用独立 clone 或 Git worktree，避免直接修改主分支工作区。
• 目录：将源码、构建产物、缓存和临时文件分开。
• 凭据：不要把签名证书、发布令牌和云服务长期密钥放在项目目录。
• 审批：命令、文件和 URL 访问分别控制。
• 记录：保存批准动作、变更 diff、失败原因和回退结果。

VS Code 的安全文档提醒，自动批准或全自动运行模式会减少高风险操作前的人工确认。即使使用沙箱，也不能替代账户隔离、凭据最小化和独立试验节点。VS Code Agent 安全说明

⚠️ 不要把“Agent 能访问项目”扩大成“Agent 能访问整台 Mac”。签名证书、发布令牌、钥匙串和生产配置应分别设置审批边界，并准备撤销入口。

对于共享仓库，可以先建立一个只含测试代码的 worktree：

git worktree add <agent-worktree> <branch-name>
cd <agent-worktree>
git status --short

Agent 只在该目录中读写。完成任务后审查差异，再决定是否合并。不要让 Agent 直接修改包含生产配置的默认工作区。

远程 Mac 的重启恢复必须单独测试。至少覆盖以下场景：

• 关闭本地 Agents window，再重新打开。
• 中断本地网络，再恢复连接。
• 停止 Dev Tunnel，再重新启动。
• 重启远程 Mac，等待网络和登录服务恢复。
• 删除临时会话后，重新选择工作目录。

每次测试记录四项：

• 会话是否仍能被发现。
• 远程主机是否重新出现在 SSH 或 Tunnel 列表。
• Agent 是否回到正确的 <remote-workspace>。
• 第一条只读命令是否在预期账户下执行。

如果使用 Dev Tunnel 长期在线，需要确认 Tunnel 进程是否作为服务运行，并确认 Mac 不会进入睡眠。即使 Tunnel 重新上线，也不能假设 Agent 会话、Xcode 状态、Simulator 和签名流程自动恢复。

最终把节点归入三档：

• ✅ 继续试跑：SSH 或认证 Tunnel 稳定，目录正确，Agent 能完成最小代码闭环。
• ⚠️ 限制使用：代码修改和无签名命令可用，但 Simulator、签名或重启恢复仍不稳定。
• ❌ 暂缓生产接入：存在匿名 Tunnel、共享管理员账户、凭据无法隔离，或重启后无法恢复到可审查状态。

如果你使用的是普通 Linux 云主机，它在网络服务、脚本执行和通用 CI 上可能更容易维护，但不能替代真实 macOS 节点上的 Xcode 工具链、Simulator 和 Apple 签名环境。自购 Mac mini 适合长期稳定负载，却需要承担硬件采购、远程联网、故障恢复和闲置成本。

当你的目标只是验证 VS Code Remote Agent Sessions、Xcode 命令和重启路径时，短周期租赁真实 Mac 更容易控制试验范围。你可以先查看 CALMVPS 的远程 Mac 方案，再根据节点需求了解 Mac 租赁配置。完成最小会话、Xcode 命令和重启恢复验收后，再决定是否续用节点或接入长期自动化流程。

VS Code Remote Agent Sessions 可以连接 Mac 主机吗？

可以。Agents window 目前处于预览状态，能够通过 SSH 或经过身份认证的 Dev Tunnel 连接远程 Mac。远程主机必须保持开机且网络可达，Mac 还需要启用 Remote Login 或提前运行经过认证的 Dev Tunnel。会话连通不代表 Xcode、Simulator 或签名发布已经完成验收。

远程 Agent 会话能直接执行 xcodebuild 吗？

可以尝试，但前提是远程 Mac 的同一用户能够在 Shell 中调用 xcodebuild，并且已经安装 Xcode、设置正确的活动开发者目录。建议先运行 xcode-select -p、xcodebuild -version 和一个无签名构建，再判断项目是否能继续。签名证书、钥匙串、Simulator 和发布权限必须单独验证。

SSH 和 Dev Tunnel 接入远程 Mac，应该怎么选？

能控制网络入口并维护 SSH key 时，优先选择 SSH，审计路径和主机边界更直接。跨网络、移动设备或无法开放 SSH 入口时，可以使用 Dev Tunnel，但必须启用账户认证。匿名访问不应进入可接受方案，尤其不能与自动批准模式叠加。

远程 Mac 重启后，Agent 会话会自动恢复吗？

不要把自动恢复当作默认能力。Mac 重启会中断 SSH、Dev Tunnel 和远程 CLI 进程，恢复结果取决于主机是否重新联网、Tunnel 是否重新启动、工作目录是否仍可访问，以及 Agents window 能否重新发现会话。应把重启后的重新连接、目录选择和最小命令执行列为独立验收项。

共享 Mac 上运行 Agent，怎样隔离仓库和凭据？

优先使用独立账户和独立工作目录，必要时为 Agent 使用单独的 Git worktree。不要把签名证书、发布令牌和长期云凭据放在 Agent 默认可读路径中。权限采用手动审批或会话级授权，避免在共享节点上启用全局自动批准。每次放宽权限都应留下记录和回退入口。