2026 Warp Agent CLI 部署云 Mac:上线前怎么验收?

官方 Oz CLI 文档当前列出的 CLI 命令已经从 warp-cli 切换为 oz,并明确说明前者已弃用。
因此,2026 Warp Agent CLI 云 Mac 部署的获胜方案是:直接在云端 macOS 主机安装当前 Oz CLI,使用非交互式认证、专用账号、受限目录和可恢复任务完成验收。不要只在本地 Warp 终端里建立 SSH 会话,就把它当成已经上线的 Agent 环境。
本文适合三类人:
- 想把 Warp Agent 任务从个人 Mac 转移到独立云端环境的开发者;
- 需要向团队交付可复核 Agent 运行环境的技术负责人;
- 正在评估云 Mac 是否适合持续集成、代码维护或后台自动化的小型研发团队。
最后更新于 2026 年 9 月 10 日,命令名称、安装方式、认证方式与远程执行边界核实自 Warp Oz CLI 官方参考、Warp API Key 文档、Warp SSH 功能说明 与 Apple Remote Login 文档。
先锁定执行位置:SSH、Oz CLI 与 run-cloud 不是一回事
上线前最常见的错误,是只看到本地终端里出现了远程提示符,就误以为 Agent 已经部署到云 Mac。
实际上需要区分三条路径:
- 本地 Warp 应用 + Warpified SSH:界面运行在本地,SSH 连接到远程主机。命令、代码读取和文件修改发生在远端,但部分依赖本地文件系统的功能不可用。
- 云 Mac 直接运行 Oz CLI:在远程 macOS 主机上安装
oz,由云 Mac 负责认证、执行任务、访问工作目录和保存日志。 oz agent run-cloud:任务提交到远程云端环境,由环境配置决定代码、依赖和执行位置。它不等于“登录一台云 Mac 后在当前目录运行”。
Warp 官方说明,Warpified SSH 可以提供输入编辑、补全、历史搜索和 Agent 对话,但 Codebase Context、原生文件读取、代码差异面板、内置编辑器和文件树等功能在 SSH 会话中存在限制。
这会直接影响方案选择:
- 代码必须留在指定云 Mac,并依赖 Xcode、macOS SDK 或本机工具链:优先考虑直接部署 Oz CLI。
- 只是临时查看远端日志或手动执行命令:Warpified SSH 足够。
- 任务必须脱离本地电脑运行,且希望通过环境配置统一依赖:评估
run-cloud。 - 任务需要访问本地未上传的代码:不要误选
run-cloud,先确认代码同步、仓库权限和环境边界。
上线前的最小环境:先隔离账号、目录和测试仓库
云 Mac 不应使用管理员账号承载日常 Agent 任务。第一轮交付至少要准备:
- 一个专用 macOS 系统账号;
- 一个独立工作目录;
- 一个不含真实客户代码的测试仓库;
- 一组测试用 API Key;
- 一份系统版本、Oz CLI 版本和开发工具清单。
远程登录本身也要单独验收。macOS 的 Remote Login 支持通过 SSH 或 SFTP 访问主机,并允许限制为指定用户,而不是默认开放给所有用户。
建议按照以下条件分支决策:
- 若任务需要修改指定仓库,且代码必须留在云 Mac:选择“云 Mac 直接安装 Oz CLI”。
- 若任务只需要人工进入远程主机处理一次问题:选择 Warpified SSH,暂不做长期 Agent 部署。
- 若任务需要本地终端关闭后继续执行:回退到独立远程进程或
run-cloud,不要依赖普通 SSH 前台进程。 - 若团队无法提供密钥轮换、日志留存和失败回滚:先不上生产,继续使用受限测试环境。
- 若多个成员要共用同一工作区:先验证目录隔离、账号边界和未提交修改清理,否则优先使用独占环境。
第一轮测试数据必须与生产隔离。不要把真实客户仓库、生产 API Key 或不可撤销的部署凭据带入安装验证。
第一个小时:安装当前 Oz CLI 并完成远程认证
当前官方文档将 Oz CLI 定义为运行、配置和管理 Agent 的命令行入口。macOS 可以通过 Warp 应用获得 CLI,也可以使用独立安装包;官方推荐通过 Homebrew 安装稳定版:
brew tap warpdotdev/warp
brew update
brew install --cask oz
安装后先确认命令和版本:
which oz
oz --version
oz help
自动化脚本不要继续写入旧的 warp-cli。官方说明旧命令已弃用,并建议在脚本与工作流中改用 oz。
认证方式取决于云 Mac 是否有人操作:
- 有浏览器、有人值守:运行
oz login,完成交互式登录。 - 无浏览器、无人值守、定时任务或 CI:使用 API Key。
- 需要团队归属、但不代表个人身份的自动化分析:优先评估 Team API Key。
- Agent 必须以某个用户身份写入代码仓库:再评估 Personal API Key 的权限影响。
官方 API Key 文档支持通过环境变量或命令参数认证,但更适合使用环境变量,因为命令参数容易出现在 Shell 历史和进程记录中。
推荐的最小验证方式:
export WARP_API_KEY="wk-xxxx"
oz agent run --prompt "只读取当前测试仓库,列出项目结构,不修改任何文件"
生产环境不要把密钥写入 .zshrc、项目 .env、Git 仓库或共享脚本。更稳妥的方式是由密钥管理工具在任务开始时注入环境变量,任务结束后清除。若使用 Warp 的环境变量能力,也要注意静态变量不能替代真正的密钥管理工具,敏感凭据应使用动态变量或外部密钥管理方案。
首次运行:用受限仓库验证 Agent 的真实边界
安装成功不代表交付成功。第一项 Agent 测试应拆成可观察的动作,而不是只输入“分析这个项目”并等待成功提示。
推荐按以下顺序运行:
-
读取验证
要求 Agent 读取测试仓库中的指定文件,并输出文件路径。检查它是否处于预期工作目录。 -
身份验证
同时记录whoami、pwd、git remote -v和当前分支。确认执行身份不是管理员账号,远端仓库也不是生产仓库。 -
修改验证
让 Agent 修改一个无风险测试文件,例如补充文档中的一处说明。检查git diff,确认修改范围只有预期文件。 -
测试验证
运行一条快速、可重复的测试命令。不要首轮就启动长时间构建或触发真实部署。 -
摘要验证
要求 Agent 输出执行过的命令、修改文件、测试结果和未解决问题。把命令记录、差异文件和失败日志一并保存。 -
越界验证
在提示中明确禁止访问仓库外目录、读取系统凭据和调用未批准的外部服务,再观察 Agent 是否遵守。 -
清理验证
测试结束后恢复工作区,删除临时文件,撤销测试密钥,确认没有残留后台进程。
这里的重点不是让 Agent “完成一个看起来复杂的任务”,而是确认它到底能访问什么。若 Agent 尝试读取仓库外目录、调用未批准工具,或把代码片段发送到未审核的外部服务,任务就不能进入正式环境。
使用 MCP 时要单独审查权限。官方 CLI 支持通过 --mcp 传入 MCP 服务器,但 MCP 连接可能扩大 Agent 对外部系统的访问范围。Warp MCP 服务器文档 第一周验收前,建议先禁用非必要 MCP,只保留完成测试任务所需的最小连接。
断线与失败测试:验证任务能否安全恢复
“本地终端关闭后,远程任务随之中止”是最典型的失败案例。
例如,开发者通过本地 Warp 建立 SSH,会话中启动一个 Agent 修改任务。随后关闭 MacBook、断开网络或退出终端。如果任务只是 SSH 前台进程,它可能立即停止;如果 Agent 已经转交给独立远端进程,代码可能继续修改;如果使用 run-cloud,则应通过任务状态和运行记录查看,而不是重新猜测。
因此需要主动做四类中断测试:
- 中断本地终端:关闭终端窗口,重新 SSH 登录,检查 Oz CLI 进程、任务状态和未提交修改。
- 中断 SSH 连接:模拟网络断开,确认任务是否被杀死,是否留下锁文件或半完成文件。
- 中断认证:使用过期或已撤销的 API Key,确认系统是否明确报错,而不是静默重试。
- 中断依赖:暂时移除测试仓库写权限、关闭外部服务或制造依赖缺失,检查错误是否可定位。
Warp 官方故障排查文档建议先使用 oz --version 检查安装路径与版本,并将认证失败、Agent 失败、环境问题和 GitHub 权限问题分开处理。Warp CLI 故障排查文档
恢复策略至少要包含:
- 提交前复核,禁止 Agent 直接覆盖未提交的人工作业;
- 每个任务使用独立分支或临时工作树;
- 任务失败后保存日志和差异,再决定重跑;
- 重跑前清理半完成文件、锁文件和临时目录;
- 对不可重复操作设置人工确认;
- 对长时间任务记录运行 ID、工作目录和最后一次成功步骤。
如果采用 run-cloud,官方 API 支持异步提交任务,并返回 run_id,之后可以查询 QUEUED、INPROGRESS、SUCCEEDED 或 FAILED 等状态。Warp API 快速入门 这类任务的验收重点是状态可追踪、结果可复核,而不是 SSH 窗口是否一直打开。
第一周正式交付:把一次成功变成可重复流程
完成首轮测试后,不能立即把正式代码库挂上去。第一周需要把验收结果固化为团队清单:
- 版本:记录 macOS、Oz CLI、Shell、Git 和必要开发工具版本。
- 安装:确认安装来源、更新方式和回滚方式。
- 权限:确认系统账号、工作目录、仓库范围和外部工具权限。
- 认证:确认 API Key 类型、有效期、注入位置、轮换和撤销流程。
- 日志:保存任务提示、命令记录、文件差异、测试结果和失败原因。
- 恢复:至少完成一次 SSH 断线、终端关闭和网络中断测试。
- 回滚:确认未提交修改可以清理,错误任务不会污染下一次运行。
- 资源观察:只记录本团队真实任务中的 CPU、内存、磁盘和网络变化,不套用没有来源的通用阈值。
- 重复运行:用一项低风险、可重复的真实任务连续执行,观察多次运行后的稳定性。
- 隔离比较:分别测试独占云 Mac 与多人共用工作区,确认并发任务不会互相覆盖文件或复用错误凭据。
如果团队还没有固定的远程登录和账号权限流程,可以先参考 ProxyMac 的远程 Mac 登录说明 与 ProxyMac 帮助中心,再把其中的主机交付步骤补充进内部验收单。
当前方案与云 Mac 方案:最后一项取舍
本地 Warp + SSH 的优势是启动快、交互自然,适合人工排查和短任务。但它有三个真实缺点:任务生命周期容易依赖本地会话;SSH 模式下部分代码理解和文件功能受限;多人共用时,账号、目录和未提交修改容易混在一起。
直接在云 Mac 上部署 Oz CLI,代价是需要自己负责账号隔离、密钥注入、版本记录和失败恢复。但对于长时间 Agent 任务、指定 macOS 工具链和需要脱离本地电脑运行的场景,这种边界更清楚,也更容易交付给团队复核。
因此,完成受限仓库测试后,可以按验收单租用一台短周期云 Mac,实际验证 Oz CLI 安装、任务恢复和权限隔离。若安装、认证、回滚或审计中任何一项无法通过,就先调整部署方式或资源方案,不要直接迁移正式代码库。需要比较短周期环境时,可进一步查看 ProxyMac 的云 Mac 方案,再根据任务持续时间决定是否进入长期使用。