cloud

cloud skill 概览

cloud skill 是做什么用的

cloud skill 是一个以文档导航为核心的辅助技能，面向 Browser Use Cloud——也就是 Browser Use 的托管式浏览器自动化平台和 API。它特别适合这几类需求：通过云服务自动化网站、使用 REST API 或 SDK、通过 CDP 连接外部浏览器工具，或者围绕 sessions、profiles、proxies 与实时监控来设计工作流。

哪些人适合安装这个 cloud skill

如果你的实际工作属于以下场景，建议安装这个 cloud skill：

• 想快速上手 Browser Use Cloud，不想把所有参考文档逐个读完
• 需要在 v2 REST API、v3 agent API、SDK 用法和直接连接浏览器之间做选择
• 想从 Python、TypeScript、cURL 或外部工具发起浏览器自动化任务
• 想在托管基础设施上运行 Browser Automation 相关流程
• 需要处理 sessions、持久化 profiles、住宅代理、CAPTCHA 处理或 webhooks

如果你真正需要的是开源本地版 browser-use Python 库的配置帮助，那就不适合安装它。这个 skill 明确区分了云端用法和开源 agent 包。

这个 cloud skill 和通用 prompt 有什么不同

通用 prompt 可以在高层次上解释浏览器自动化。但当你需要 Browser Use Cloud 的精确信息时，这个 cloud skill 更有价值：该看哪个 API 版本、认证怎么做、liveUrl 从哪里来、云端 sessions 和一次性 runs 的区别、如何开启 CDP 访问、以及哪种集成方式更适合你的技术栈。

它最大的价值不是隐藏工具能力，而是帮你快速定位与判断适配路径。它会直接把你指向正确的参考文件：

• references/quickstart.md：首次配置和定价
• references/api-v2.md：稳定版 REST endpoints
• references/api-v3.md：较新的基于 session 的 agent API
• references/browser-api.md：Playwright、Puppeteer、Selenium 和原始 CDP
• references/sessions.md：session 与 profile 设计
• references/features.md：proxies、webhooks、workspaces、skills、MCP 和 live view
• references/patterns.md：并行运行、streaming、geo-scraping 和结构化输出

适合将 cloud skill 用于 Browser Automation 的场景

当你的目标是面向 Browser Automation 使用云端能力，而不是本地浏览器控制时，这个 cloud skill 尤其有用。常见适配场景包括：

• 需要借助 stealth 和 proxies 的 scraping 或数据提取
• 需要持久化浏览器 profiles 的登录态工作流
• 需要通过 liveUrl 观察的远程浏览器 sessions
• 通过托管 CDP，直接从 Playwright、Puppeteer 或 Selenium 发起自动化
• 与 agent 系统、聊天 UI、no-code 工具或 webhook 驱动后端做集成

安装前先确认的主要阻碍点

大多数安装决策，最后都会落到几个很实际的问题上：

• 你需要的是托管式云端自动化，还是本地开源控制？
• 你想用稳定的 v2 REST endpoints，还是较新的 v3 session/message 模型？
• 你需要简单的 run() 任务，还是显式的 session/profile 管理？
• 你是通过 SDK、cURL，还是通过 CDP 连接外部浏览器框架？
• 你是否需要地理路由、认证持久化，或 webhook 回调？

如果这些问题还没想清楚，这个 skill 就很有帮助，因为仓库本身是按决策路径组织的，而不是一条线性的教程。

如何使用 cloud skill

安装 cloud skill

使用标准 skills 安装命令，并指定 cloud skill：

npx skills add https://github.com/browser-use/browser-use --skill cloud

安装完成后，只有当你的请求明确针对 Browser Use Cloud，而不是本地开源包时，再调用它。

按目标选择起始文件，不要按文件顺序读

阅读方式应该按决策走，而不是按文件顺序走：

• 刚接触平台：references/quickstart.md
• 需要稳定 API 覆盖和 cURL 示例：references/api-v2.md
• 需要较新的 agent/session 模型：references/api-v3.md
• 需要从现有浏览器框架访问托管浏览器：references/browser-api.md
• 需要持久化状态、认证或 profile 策略：references/sessions.md
• 需要 proxies、webhooks 等高级能力：references/features.md
• 需要具体实现模式：references/patterns.md

这一点很关键，因为这个 skill 不会替你掩盖产品复杂度；它的作用是帮你找到最短、最有用的阅读路径。

先搞清楚四条主要的 cloud 使用路径

在发 prompt 之前，先决定你要的是下面哪一种：

1. 通过 SDK 执行 run() 任务
2. 使用 v2 REST API 的 task/session/browser endpoints
3. 使用带有 sessions、messages 和 workspaces 的 v3 agent API
4. 通过直接 CDP 浏览器连接接入 Playwright、Puppeteer 或 Selenium

很多效果不佳的 prompt，问题都出在只说“Browser Use Cloud 怎么用”，却没有明确指定目标路径。

正确设置认证

Browser Use Cloud 使用 X-Browser-Use-API-Key header，而 SDK 通常会从环境变量中读取 BROWSER_USE_API_KEY。

export BROWSER_USE_API_KEY=your-key

参考文档里会明确给出这些实用细节：

• v2 的 API base：https://api.browser-use.com/api/v2
• v3 的 API base：https://api.browser-use.com/api/v3
• 创建 API key：https://cloud.browser-use.com/new-api-key

如果你的 prompt 没说明希望如何处理认证，回答往往会停留在比较抽象的层面。

在要示例之前，先选好 SDK、REST 还是 CDP

如果你想要最省事的开发体验，就用 SDK 示例。
如果你需要 endpoint 级别的控制，就用 REST。
如果你已经有浏览器自动化代码，只是需要一个托管浏览器目标，就用 CDP。

这个区分会直接改变回答内容：

• SDK 类型的回答会聚焦 run()、sessions、profiles 和结构化输出
• REST 类型的回答会聚焦 endpoints、polling、schemas 和 headers
• CDP 类型的回答会聚焦 WebSocket URLs，以及如何接入浏览器工具

把模糊目标改写成高质量的 cloud 使用 prompt

弱 prompt：

Help me use Browser Use Cloud.

更好的 prompt：

I want cloud usage guidance for Python. I need a hosted browser workflow that logs into a site, persists cookies across runs, uses a US proxy, and lets me monitor progress live. Show whether I should use run() with auto-created sessions or manual sessions with a profile, and point me to the exact repo files to read first.

为什么这个版本更好：

• 指明了语言
• 指明了工作流类型
• 提到了 session 持久化
• 包含了 proxy 需求
• 明确要求实时监控
• 要求给出文件导航，而不只是代码

哪些输入信息能提升输出质量

想让 cloud skill 给出更高质量的结果，建议补充这些信息：

• 语言：Python、TypeScript、cURL
• API 模式：v2、v3，或尚未确定
• 执行方式：一次性任务、多步骤 session，还是直接浏览器控制
• 状态需求：无状态，还是持久化 profile
• 基础设施需求：代理国家、自定义代理、timeout、屏幕尺寸
• 监控需求：liveUrl、streaming、webhooks
• 输出形式：自由文本还是结构化 schema
• 集成目标：Playwright、Puppeteer、Selenium、聊天 UI、subagent、no-code 工具

缺少这些信息时，回答通常仍然是对的，但会过于宽泛，难以快速落地。

用 cloud skill 设计 session 和 profile

cloud skill 一个非常实用的价值，在于帮你避开糟糕的 session 设计。

根据参考文档：

• run() 通常会自动创建一个 session
• 手动创建 session 更适合多步骤工作流
• profile 会在不同 sessions 之间持久化 cookies 和 local storage
• 多个并发 session 如果共用同一个 profile，它们只是从同一个快照启动，彼此看不到对方后续的状态变更

最后这一点在快速浏览时很容易忽略，但对需要认证态的并行任务非常关键。

将 cloud skill 用于 Browser Automation 框架

如果你已经在用 Playwright、Puppeteer 或 Selenium，最佳路径可能不是 agent tasks，而是直接使用云端浏览器连接。

仓库中给出的 CDP 入口类似这样：

wss://connect.browser-use.com?apiKey=YOUR_KEY&proxyCountryCode=us&timeout=30

这一点很重要，因为浏览器可以在连接时自动启动、断开时自动停止，这和手动创建、销毁 tasks 是完全不同的运行模型。

用 cloud skill 评估高级云端能力

当你的决策取决于平台能力本身，而不是语法写法时，这个 skill 也很有用：

• stealth 默认能力
• 覆盖多个国家的住宅代理
• 自定义代理
• CAPTCHA 处理
• 带签名验证的 webhooks
• live viewing 和分享链接
• workspaces
• skills 与 marketplace 支持
• 与 MCP 相关的平台参考内容

这些细节，往往才是真正决定 Browser Use Cloud 是否适合生产环境的关键。

安装后的推荐首个工作流

给新用户的一条实用路径：

1. 阅读 references/quickstart.md
2. 通过 SDK 或 cURL 跑一个最简单的首个任务
3. 再判断你的真实工作流是否需要手动 sessions
4. 只有在确实需要持久化登录或状态时，再引入 profiles
5. 只有在确实需要时，再添加 proxy 和地理设置
6. 在基础路径跑通后，再加结构化输出或 webhooks
7. 需要并发或 streaming 时，再转到 references/patterns.md

这个顺序能有效减少混乱，避免你在第一次成功运行之前就把方案设计得过重。

cloud skill 常见问题

这个 cloud skill 只是文档导航，还是会改变行为？

它本质上是一个参考资料路由型 skill。它的价值在于帮助 agent 或用户选择正确的 Browser Use Cloud 文档路径，并减少错误假设。它不会替代平台本身的 SDK 或 API。

cloud skill 适合新手吗？

适合，前提是你是 Browser Use Cloud 这个产品的新手。最好的起点是 references/quickstart.md。但即便如此，你仍然需要先搞清楚自己要的是简单任务执行、session 管理，还是框架级浏览器控制。

什么情况下不该使用这个 cloud skill？

如果你的问题是关于开源 browser-use 本地库的内部机制、agent 配置，或非云端包的安装与设置，就不要用这个 cloud skill。这个 skill 已经明确说明，这类问题应该改用 open-source skill。

我该选 v2 还是 v3？

如果你想要稳定的 REST API，并且需要更广泛的 endpoint 覆盖，就选 v2。
如果你想要较新的 BU Agent API 模型，需要 sessions、messages、files 和 workspaces，并且可以接受它在参考文档中被标为 experimental，那就选 v3。

这个 cloud skill 能帮助普通浏览器框架集成吗？

可以。仓库里有专门的 references/browser-api.md，就是给 Playwright、Puppeteer、Selenium 和直接连接托管浏览器的 CDP 用的。

对于 Browser Automation，cloud skill 比普通 prompt 更好吗？

通常是的，尤其是在 Browser Use Cloud 场景下。普通 prompt 很容易漏掉平台特有的信息，比如认证 headers、endpoint 版本、liveUrl、profile 行为、webhook 签名，或 CDP 连接时自动启动的运行模型。

cloud skill 会覆盖定价和运行约束吗？

会。quickstart 参考文档包含定价和 FAQ 内容，其他参考文件还会覆盖 timeout、session 处理、并发注意事项，以及各项功能本身的限制条件。

如何进一步提升 cloud skill 的使用效果

不要只问解释，要让它帮你做决策

提升 cloud skill 输出质量最快的方法，就是让它在选项之间做判断：

• “Should I use v2, v3, or CDP?”
• “Should this be auto-session or manual session?”
• “Should I use a profile or keep it stateless?”

这样得到的会是可执行的实施建议，而不是泛泛的总结。

提供具体任务和运行环境

更好的写法：

I need cloud install and usage help for a TypeScript backend. The workflow logs into a dashboard weekly, downloads a file, and posts completion to my server. I need persistent auth, webhook notifications, and a recommendation between SDK and REST.

这样效果更好，因为它明确暴露了语言、执行频率、状态需求和完成通知方式。

明确告诉 skill 哪些状态必须跨运行保留

一个常见失败点，是状态描述不充分。如果登录态、cookies、local storage 或保存的凭证很重要，请明确说出来，并要求它基于 references/sessions.md 给出 profile 方案建议。

如果状态不重要，也要明确说明。这样 skill 才能推荐更简单的一次性运行方案。

说明你需要观察执行过程，还是需要回调

很多用户其实很在意下面某一项，但常常忘了提：

• 通过 liveUrl 实时查看执行过程
• 获取 step 级的 streaming 更新
• 在任务完成时接收 webhook 回调

这些需求会对应不同的实现模式，也会对应不同的参考文件。

先要最小可行路径

一个很好的改进方法是：

1. 先让它给出最小可运行示例
2. 自己先跑通
3. 再继续问如何加 profiles、proxies 或 webhooks

这个 skill 最强的地方，是帮助你按顺序推进落地，而不是一次性设计完整的生产架构。

注意 API 版本混淆

最容易导致输出变弱的问题之一，就是在同一个请求里混用 v2 和 v3 概念。如果你要比较，就明确要求比较；如果你要实现方案，就只指定一个版本。

好的 prompt 示例：

Compare Browser Use Cloud v2 vs v3 for a multi-step agent workflow, then recommend one and give only that version's starter example.

直接询问文件级阅读路径

仓库里的参考资料不少，按目标定向阅读会节省大量时间。你可以直接这样问：

• “Which file should I read first for webhook verification?”
• “Which reference covers CDP and Playwright setup?”
• “Which document explains concurrent sessions with the same profile?”

这样 cloud 指南会比泛泛总结更有执行价值。

用明确的成功标准提升输出质量

不要这样问：

Show me cloud usage.

更好的方式是：

Show me a cloud usage path that gets from API key to first successful task in under 10 minutes, then list the next file to read if I need structured output.

成功标准会逼着回答朝更实用的采用路径靠拢。

第一轮回答后，补缺口，不要重开题

拿到第一轮回答后，最好的优化方式是直接指出缺了什么，而不是从头再问一遍：

• 缺少 auth 处理
• 缺少 polling 示例
• 缺少 session cleanup
• 缺少 proxy 配置
• 缺少 structured output schema
• 缺少 webhook verification
• 缺少 Playwright 连接细节

这种方式比重新从零提问，更容易得到高质量的第二轮指导。

获取高价值 cloud 指导的最佳方式

当你的 prompt 包含以下信息时，cloud skill 表现最好：

• 你的技术栈
• 你的浏览器自动化目标
• 是否必须持久化状态
• 更偏向托管浏览器控制，还是 agent 执行
• 是否需要监控、streaming 或 webhooks
• 是否关心 geo-routing 或 stealth 相关限制

这组信息足以让 skill 把你准确引导到合适的 Browser Use Cloud 资料，并产出你可以立即上手实施的建议。