前言¶
写网页自动化脚本时，最磨人的是选择器。页面一改版，#submit-btn 就可能失效，重新抓元素、改代码、回归测试，一轮下来比功能本身还费时间。如果要让大模型去操作浏览器，靠模型硬猜选择器同样不可靠。
下面介绍的 Agent Browser - Stagehand 换了个思路：把浏览器操作压缩成几条 CLI 命令，动作用自然语言描述（click the Sign In button），不写选择器，也不要求模型理解 DOM。适合需要让 Agent 浏览站点、取数据、截图的场景。
这是什么¶
Agent Browser - Stagehand 是一个基于 SKILL.md 格式的 Agent Skill，坐标 @peytoncasper/agent-browser-stagehand，由 peytoncasper 发布在 ClawHub 上，当前版本 v1.0.0，许可证 MIT-0。它是 @peytoncasper/browser-automation 的副本，能力一致。
它解决的问题是：让 Agent 用自然语言完成网页交互，覆盖浏览、导航、提取数据、截图、填表、点击、与 Web 应用交互。底层调用 Stagehand CLI，前端是 browser 这个全局命令。
在 SkillHub 上该 Skill 的分类为 ai-agent，标签显示 requires_api_key=false，即本地模式不需要密钥（远程模式另说）。
核心功能¶
1、自然语言动作。用 browser act "<action>" 表达意图，例如 click the Sign In button，由 Stagehand 解析页面并决定点哪里。
2、结构化提取。browser extract "<instruction>" 可以按可选 JSON schema 抽取字段，返回结构化结果而不是一段文本。
3、元素探查。browser observe "<query>" 用来发现页面上可用的元素，动作失败时是排查入口。
4、截图。browser screenshot 在任意命令后截屏，用于人工核对执行结果。
5、本地 / 远程双环境。Skill 自动按配置选择：存在 BROWSERBASE_API_KEY 和 BROWSERBASE_PROJECT_ID 时走远程 Browserbase，否则回退本地 Chrome。
安装与启用¶
安装走 ClawHub 的 CLI，官方命令如下：
$ openclaw skills install @peytoncasper/agent-browser-stagehand
页面也提示可以通过 npx skills 方式使用。
首次启用需要完成一次本地准备。查看目录下的 setup.json，若 setupComplete 为 false，执行：
npm install # 安装依赖
npm link # 创建全局 browser 命令
这一步的作用是把 browser 暴露到 PATH，后续所有命令都基于它。
是否需要 API Key 取决于环境选择：
- 本地模式：不需要任何 Key，但要求机器上装了 Chrome。
- 远程模式：需要在
.env中配置BROWSERBASE_API_KEY和BROWSERBASE_PROJECT_ID。
环境选择是自动的，没有交互提示，判定依据就是这两个配置是否存在。
典型用法¶
官方给的最小示例，命令顺序就是使用顺序：
browser navigate https://example.com
browser act "click the Sign In button"
browser extract "get the page title"
browser close
先导航再交互，最后关闭。完整命令集如下：
browser navigate <url> # 打开 URL
browser act "<action>" # 自然语言动作
browser extract "<instruction>" ['{}'] # 提取数据，可选 schema
browser observe "<query>" # 探查元素
browser screenshot # 截图
browser close # 关闭浏览器
所有命令在本地和远程模式下行为一致，区别只在执行环境和附加能力：
| 能力 | 本地 Chrome | Browserbase 远程 |
|---|---|---|
| 速度 | 更快 | 略慢 |
| 准备成本 | 需要 Chrome | 需要 API Key |
| 隐身模式 | 不支持 | 支持 |
| 代理 / CAPTCHA | 不支持 | 支持 |
| 适用 | 开发调试 | 生产、抓取 |
适用场景与注意¶
适合：Agent 需要自助浏览站点、抓数据、截图验证；本地开发调试；需要代理或反爬能力的采集任务。
注意事项：
1、始终先 navigate 再执行其他操作，否则页面不存在，动作必然失败。
2、每个命令后建议 screenshot 核对，尤其是 act 和 extract。
3、动作描述要具体，click the Sign In button 比 click it 可靠。
4、结束时显式 browser close，避免残留进程占用资源。
常见问题：
- Chrome 找不到：本地模式需先安装 Chrome，或切到 Browserbase 模式。
- 动作执行失败：先用
browser observe查看页面上实际可用的元素，再调整描述。 - Browserbase 报错：确认
.env中的 API Key 与 Project ID 是否正确。
结尾¶
这个 Skill 的价值在于把浏览器自动化从”写选择器”降级为”说意图”，命令少、顺序清晰，本地零配置即可跑通，需要隐身与代理时再切远程。它不解决反爬策略本身，但把环境切换的成本省掉了。
官方地址：https://clawhub.ai/peytoncasper/agent-browser-stagehand
