Stagehand 教程

按 Stagehand 官方 Quickstart 走一遍。跑通标准：本机弹出 Chrome，脚本对 stagehand.dev 跑完 extract → act → observe。需要你自己的模型 API Key。官方写明：SDK 不会替你读环境变量，必须自己读 Key 再传给 Stagehand.create。

本机没有 OPENAI_API_KEY，没有执行 pnpm dlx tsx index.ts。下面命令与官方 TypeScript 路径一致。

1. 建项目并安装

本机还要已装 Chrome。官方 TypeScript：

mkdir my-stagehand-app && cd my-stagehand-app
pnpm init -y
pnpm install @browserbasehq/stagehand 'zod@~4.4.3'

文档要求 Zod 钉在 4.4.x。Python：pip install stagehand。

2. 写脚本

在项目根目录新建 index.ts，按官方示例：localBrowser.launch() → Stagehand.create（把 process.env.OPENAI_API_KEY 传入 model.apiKey）→ page.goto("https://stagehand.dev") → extract → act("Click the 'Evals' button.") → observe。完整代码以官方 Quickstart 页面为准，不要改模型字段名。

3. 跑通一次

export OPENAI_API_KEY="sk-..."
pnpm dlx tsx index.ts

官方：会在本机开一个看得见的 Chrome 窗口。云端换 browserbase.launch()，那是进阶，不当主路径。

4. 翻车点

act / observe / extract 页面改版会重找元素。确定的步骤用 locator，不确定的用自然语言。本地浏览器不能走 Model Gateway，必须自己传模型和 Key。

出处：Quickstart · README