云代理概述

云代理是自主的后台代理，运行在 Warp 的云基础设施或您自己的基础设施上，由系统事件、调度或 Slack 和 GitHub 等集成触发。它们以完全的可观测性执行任务 — 每一项运行都可被追踪、审计，并在团队内共享。

刚接触云代理？ 从 云代理快速入门 开始，约 10 分钟内即可运行您的第一个云代理。

云代理的设计用途

云代理适用于以下情况

• 您需要代理响应系统事件。
  • 例子包括崩溃、错误报告、Slack 交互、Cron 定时器或 CI 步骤。
• 您希望对整个团队或系统的代理活动进行可观测性管理。
  • 这包括能够查看运行的内容、运行的时间以及执行的操作。
• 您需要的并行能力超出了本地执行的通常范围。
  • 例如，在云端并发运行多个代理任务、将跨仓库任务分片为多个运行，或将同一任务扇出到多个目标。
• 您希望代理作为工程基础设施的一部分持续运行。
  • 这包括计划内的维护任务和集成驱动的自动化。

---

什么是云代理运行？

云代理运行以代理任务的形式呈现。当触发器触发时（例如 Webhook 事件或调度），或者当用户明确启动运行时，就会创建任务。

每个任务包括

• 输入：提示词，以及通常来自触发系统的额外上下文（例如 Slack 消息、PR 元数据或 CI 日志）。
• 执行上下文（可选）：一个 环境，用于定义代理应在其中运行的仓库、镜像和启动命令。
• 生命周期状态：创建 → 运行中 → 完成/失败。
• 持久记录：状态、元数据和任务完成后可审查的会话记录。

注意

如果您正在评估某项工作是否应成为云代理，一个好的测试方法是确认您是否能定义
(1) 触发条件，(2) 所需上下文，以及 (3) 团队如何检查或验证输出。

云代理的工作原理

云代理运行在 Oz 平台上，该平台提供了用于触发工作、编排任务、执行代理（可选在环境中）、注入密钥和检查结果的原语。

• 某事物触发了一个代理任务。
• 编排器创建并跟踪该任务。
• 代理在主机上执行，可选在 环境 内，使用所需的任何 密钥 和凭据。

任务的具体触发和执行方式取决于您的部署模式（例如仅 CLI、Warp 托管编排或自托管执行）。这些选项在 部署模式 页面中有详细介绍。

对于需要将执行保持在网络边界内的团队，自托管支持两种架构：一种是 托管 的工作进程守护程序，允许 Oz 在您机器上的 Docker 容器中编排代理；另一种是 非托管 模式，即您直接在 CI、Kubernetes 或开发环境中运行 oz agent run。详情请参阅 自托管。

默认功能

由于云代理运行在 Oz 平台上，每次运行都会被跟踪并产生可被观察、共享和审计的持久记录（即使执行是在 Warp 应用之外发生的）。

代码库上下文

云代理运行会自动受益于 代码库上下文 以进行语义代码理解和搜索，只要您的账户启用了代码库上下文。有关详情，请参阅 云代理运行中的代码库上下文。

可观测性和可控性

云代理任务旨在供团队检查

• 代理会话共享 允许授权的队友加入正在运行的任务以监控进度，并在支持的情况下在任务运行期间引导代理。
• 每次运行都会产生会话记录和任务元数据，提供代理所执行操作的记录。
• 一种 管理体验 可以呈现任务状态和历史记录。

集中式配置

云代理工作流通常依赖于共享配置，如 MCP 服务器、规则、保存的提示词、环境变量和 密钥。

Warp 支持集中式配置，因此同一工作流在不同触发器（例如 Slack + CI + 调度）下表现一致，无需在每个系统中重复设置。

有关为云代理配置 MCP 服务器的详细信息，请参阅 MCP 服务器。

API 访问任务

Oz 平台通过 Oz API 和 SDK 公开任务可见性，因此团队可以

• 查询哪些任务正在运行或已运行。
• 获取任务元数据和结果。
• 构建内部仪表板或监控（例如成功率、运行时间、失败原因）。

在有或没有 Warp 应用的情况下使用云代理

云代理不需要 Warp 桌面应用。团队可以通过 Oz 平台 使用以下方式部署和操作它们

• Oz CLI — 从脚本、CI 或终端运行代理
• Oz Web 应用 — 用于管理运行、调度、环境和集成的可视化界面（可在移动设备上使用）
• 代理会话共享 — 加入正在运行的任务以监控或引导
• 代理管理 UX — 查看代理活动和运行历史记录
• API 和 SDK — 用于自定义集成的编程访问权限

如果您的团队也使用 Warp 终端，您将获得额外的工作流：通过 CLI 启动的任务可以移交给交互式会话进行审查、编辑或继续。

---

计费与计划要求

云代理和 集成 运行在 Oz 平台 控制平面上，使用额度进行计费。

注意

自带 API 密钥 (BYOK) 不支持云代理运行。BYOK 密钥存储在您的设备本地，云托管代理无法访问。所有云代理运行均消耗 Warp 额度。

对于通过 CLI/API 使用云代理的情况

个人用户无需加入团队即可运行云代理。要求

• 您至少需要拥有 20 个可用额度
• 云代理运行在 Warp 托管的基础设施上
• 自托管代理需要团队订阅

对于集成 (Slack/Linear)

集成要求您成为 Warp 团队 的一员，并满足额外要求

• 计划要求
  • 支持的计划：Build、Max、Business
  • 您的计划必须支持附加额度。
• 额度要求
  • 您的团队必须至少拥有 20 个可用额度才能运行云代理和集成。

有关详细信息，请参阅 访问、计费和身份权限。

注意

如果您的额度余额降至零，云代理运行将无法执行，直到额度补充为止。

---

了解更多

• 云代理快速入门 — 在约 10 分钟内运行带环境的第一个云代理。
• Oz 平台 — CLI、Oz API/SDK、编排、任务、环境、主机、集成等。
• Harnesses — 为任何云代理运行选择 Warp Agent、Claude Code 或 Codex。
• 代理身份 — 拥有并执行云代理运行的团队范围内的机器人账户。
• 多代理编排 — 在本地和云端运行中协调父代理及其子代理，以构建监督者/工作者、扇出、评估者、DAG 和群体工作流。
• 技能即代理 — 基于 CLI、Web 应用、API 或按计划运行的可重用技能定义来运行代理。
• Oz CLI — 展示如何从 CI、脚本或远程机器以非交互模式运行代理，包括身份验证和常用命令。
• 环境 — 解释环境如何为代理任务提供运行时上下文（仓库、镜像、启动命令）。
• Oz API 和 SDK — 记录用于以编程方式创建、查询和监控代理任务的 REST API。
• 代理密钥 — 涵盖如何安全地存储、限制作用域并将凭据注入代理运行中。
• MCP 服务器 — 如何配置 MCP 服务器以实现代理工具访问，以及 MCP 配置如何在不同运行中应用。
• 部署模式 (beta) — 比较部署云代理的常用方法及其适用场景。
• 访问、计费和身份权限 — 解释个人和团队级别的要求、额度计费行为，以及关于谁可以运行、查看和引导云代理任务的权限模型。