Skip to content
lzh博客

Models

配置 Stagehand 使用的模型提供方、模型网关、自定义端点与高级模型选项。

文档索引

可在此获取完整文档索引：https://docs.stagehand.dev/llms.txt

在进一步浏览前，可使用该文件发现所有可用页面。

Models

Section titled “Models”

在 Stagehand 中使用任意 LLM 模型

Model Gateway

Section titled “Model Gateway”

Model Gateway 让你无需自行接入各模型提供方，也能使用 Stagehand。你不必为每个提供方分别管理 API Key，只需传入 Browserbase API Key 并选择一个模型，Browserbase 会为你把请求路由到上游提供方。

设置

Section titled “设置”
import { Stagehand } from "@browserbasehq/stagehand";


const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "openai/gpt-5",
});


await stagehand.init();

当你只提供 Browserbase API Key 时（而未提供特定模型提供方的 API Key），Stagehand 会自动通过 Model Gateway 路由模型请求。无需额外配置。

切换模型

Section titled “切换模型”

使用 Model Gateway 时，在不同提供方之间切换只需要修改配置——不需要新账号、API Key，也不需要重新改写代码：

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "openai/gpt-5",
});

主要优势

Section titled “主要优势”
  • 一个 Key，一张账单 —— LLM 推理、浏览器基础设施与缓存都通过你的 Browserbase API Key 统一计费。
  • 按市场价计费的 token —— 我们的价格与直接调用模型提供方一致，不加价。
  • 内置可靠性 —— 重试、退避和速率限制处理都由系统代管。
  • 无等级门槛 —— 无需满足提供方的消费门槛，也能立即使用新模型。
  • 操作缓存 —— Model Gateway 可与 Stagehand 的托管操作缓存配合使用，重复步骤会被复用，而不是重新执行。

支持的提供方

Section titled “支持的提供方”
提供方示例模型
OpenAIopenai/gpt-5
Anthropicanthropic/claude-sonnet-4-6
Googlegoogle/gemini-2.5-flash

配置设置

Section titled “配置设置”

快速开始

Section titled “快速开始”

你可以先从 Google Gemini 开始（在速度与成本方面都很推荐）：

import { Stagehand } from "@browserbasehq/stagehand";


const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "google/gemini-2.5-flash",
  // API key auto-loads from GOOGLE_GENERATIVE_AI_API_KEY - set in your .env
});


await stagehand.init();

一等公民模型

Section titled “一等公民模型”

你可以直接使用以下已支持提供方中的任意模型。

import { Stagehand } from "@browserbasehq/stagehand";


const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "google/gemini-2.5-flash",
  // API key auto-loads from GOOGLE_GENERATIVE_AI_API_KEY - set in your .env
});


await stagehand.init();

查看所有支持的 Google 模型 →

自定义模型

Section titled “自定义模型”

支持 Amazon Bedrock、Cohere、全部一等公民模型，以及 Vercel AI SDK 中的任意模型。

当你需要自定义端点、自定义重试逻辑或缓存逻辑时，可以使用这种配置方式。

下面以 Amazon Bedrock 和 Google 为例。

Amazon Bedrock

步骤 1：安装依赖

Section titled “步骤 1：安装依赖”

为你的提供方安装对应的 Vercel AI SDK。

Terminal window
npm install @ai-sdk/amazon-bedrock

步骤 2：导入、创建 provider，并创建 client

Section titled “步骤 2：导入、创建 provider，并创建 client”
import { createAmazonBedrock } from '@ai-sdk/amazon-bedrock';
import { AISdkClient } from '@browserbasehq/stagehand';


const bedrockProvider = createAmazonBedrock({
  region: 'us-east-1',
  accessKeyId: 'xxxxxxxxx',
  secretAccessKey: 'xxxxxxxxx',
  sessionToken: 'xxxxxxxxx',
});


const bedrockClient = new AISdkClient({
  model: bedrockProvider("amazon/nova-pro-latest"),
});

步骤 3：将 client 传给 Stagehand

Section titled “步骤 3：将 client 传给 Stagehand”
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  llmClient: bedrockClient,
});


await stagehand.init();
Google

步骤 1：安装依赖

Section titled “步骤 1：安装依赖”

为你的提供方安装对应的 Vercel AI SDK。

Terminal window
npm install @ai-sdk/google

步骤 2：导入、创建 provider，并创建 client

Section titled “步骤 2：导入、创建 provider，并创建 client”
import { createGoogle } from '@ai-sdk/google';
import { AISdkClient } from '@browserbasehq/stagehand';


const googleProvider = createGoogle({
  apiKey: process.env.GEMINI_API_KEY,
});


const googleClient = new AISdkClient({
  model: googleProvider("google/gemini-2.5-flash"),
});

步骤 3：将 client 传给 Stagehand

Section titled “步骤 3：将 client 传给 Stagehand”
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  llmClient: googleClient,
});


await stagehand.init();
所有提供方

要实现自定义模型，请按照你所使用提供方的步骤进行。可以参考上面的 Amazon Bedrock 与 Google 示例。所有受支持的提供方与模型都可在 Vercel AI SDK 中找到。

步骤 1：安装依赖

Section titled “步骤 1：安装依赖”

安装对应提供方的 Vercel AI SDK。

步骤 2：导入、创建 provider，并创建 client

Section titled “步骤 2：导入、创建 provider，并创建 client”
import { createProvider } from '@ai-sdk/provider';
import { AISdkClient } from '@browserbasehq/stagehand';


const provider = createProvider({
  apiKey: 'xxxxxxxxx',
});


const providerClient = new AISdkClient({
  model: provider("model/name"),
});

步骤 3：将 client 传给 Stagehand

Section titled “步骤 3：将 client 传给 Stagehand”
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  llmClient: providerClient,
});


await stagehand.init();

选择模型

Section titled “选择模型”

不同模型各自擅长不同任务。请根据你的使用场景综合考虑速度、准确率与成本。

模型选择指南

在模型评测页面查看更详细的模型对比与推荐。

快速推荐

使用场景推荐模型原因
生产环境google/gemini-2.5-flash速度快、准确且成本效益高
智能性google/gemini-3-pro-preview在复杂任务上准确率最佳
速度google/gemini-2.5-flash响应时间最快
成本google/gemini-2.5-flash单位 token 性价比最佳
本地/离线ollama/qwen3无 API 成本，完全可控

高级选项

Section titled “高级选项”

Agent 模型（支持 CUA）

Section titled “Agent 模型（支持 CUA）”

默认行为

Stagehand agent 默认会使用传给 Stagehand 的同一个模型。所有模型（一等公民模型与自定义模型）都支持。下面是一个使用 Gemini 的示例：

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "google/gemini-2.5-flash",
  // GOOGLE_GENERATIVE_AI_API_KEY is auto-loaded from .env
  // ... other stagehand options
});


// Agent 将使用 google/gemini-2.5-flash
const agent = stagehand.agent();

覆盖模型（支持 CUA）

不过，stagehand agent 也接受 model 参数，它可以接收任意一等公民模型，包括计算机使用代理（CUA）。当你希望 agent 使用与 Stagehand 主实例不同的模型时，这会非常有用。

警告

弃用提示： cua: true 选项已弃用，未来版本将移除。请改用 mode: "cua"。

const agent = stagehand.agent({
  mode: "cua",
  model: "google/gemini-2.5-computer-use-preview-10-2025",
  // GOOGLE_GENERATIVE_AI_API_KEY is auto-loaded from .env
  // ... other agent options
});
所有支持的 CUA 模型
提供方模型
Anthropicanthropic/claude-haiku-4-5-20251001
Anthropicanthropic/claude-sonnet-4-6
Anthropicanthropic/claude-sonnet-4-5-20250929
Anthropicanthropic/claude-opus-4-5-20251101
Anthropicanthropic/claude-opus-4-6
Googlegoogle/gemini-2.5-computer-use-preview-10-2025
Googlegoogle/gemini-3-flash-preview
Googlegoogle/gemini-3-pro-preview
Microsoftmicrosoft/fara-7b
OpenAIopenai/computer-use-preview
OpenAIopenai/computer-use-preview-2025-03-11

自定义端点

Section titled “自定义端点”

如果你需要使用 Azure OpenAI 部署或企业内部部署，可以参考以下方式。

对于 OpenAI，你可以通过 model 参数直接传入配置，而不必使用 llmClient：

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: {
    modelName: "openai/gpt-5",
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: "https://custom-openai-endpoint.com/v1",
  }
});

AI Gateway

Section titled “AI Gateway”

Vercel AI Gateway 允许你通过单一 API Key 与统一接口访问多个提供方（OpenAI、Anthropic、Google 等）的模型。无需额外安装提供方 SDK，也不需要为每个提供方单独配置 API Key。

主要优势：

  • 使用单个 AI_GATEWAY_API_KEY 即可访问所有主流提供方的模型
  • 根据可用性与延迟自动进行提供方回退和动态路由
  • 通过 Vercel 控制台进行用量跟踪与可观测性分析
  • 支持自带 Key（BYOK），可继续使用你现有的提供方凭据

使用 gateway/ 前缀，后面接提供方与模型名：

import { Stagehand } from "@browserbasehq/stagehand";


const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "gateway/openai/gpt-5",
  // API key auto-loads from AI_GATEWAY_API_KEY - set in your .env
});


await stagehand.init();

适用于网关上提供的任意模型：

// 通过 gateway 使用 Anthropic
model: "gateway/anthropic/claude-sonnet-4.5"


// 通过 gateway 使用 Google
model: "gateway/google/gemini-3-flash-preview"

查看所有可用的 AI Gateway 模型 →

扩展 AI SDK Client

Section titled “扩展 AI SDK Client”

对于自定义重试逻辑或缓存逻辑等高级场景，你可以扩展 AISdkClient：

import { LLMClient } from "@browserbasehq/stagehand";


class CustomRetryClient extends LLMClient {
  async createChatCompletion(options) {
    let retries = 3;
    while (retries > 0) {
      try {
        return await super.createChatCompletion(options);
      } catch (error) {
        retries--;
        if (retries === 0) throw error;
        await new Promise((r) => setTimeout(r, 1000 * (4 - retries)));
      }
    }
  }
}

旧版模型格式

Section titled “旧版模型格式”

以下模型出于兼容旧版本的目的，仍然支持在 model 参数中不带 provider/ 前缀：

Google
  • gemini-2.5-flash-preview-04-17
  • gemini-2.5-pro-preview-03-25
  • gemini-2.0-flash
  • gemini-2.0-flash-lite
  • gemini-1.5-flash
  • gemini-1.5-flash-8b
  • gemini-1.5-pro
Anthropic
  • claude-sonnet-4-6
  • claude-sonnet-4-5-20250929
  • claude-haiku-4-5-20251001
OpenAI
  • gpt-4o
  • gpt-4o-mini
  • o1
  • o1-mini
  • o3
  • o3-mini
  • gpt-4.1
  • gpt-4.1-mini
  • gpt-4.1-nano
  • o4-mini
  • gpt-4.5-preview
  • gpt-4o-2024-08-06
  • o1-preview
Cerebras
  • cerebras-llama-3.3-70b
  • cerebras-llama-3.1-8b
Groq
  • groq-llama-3.3-70b-versatile
  • groq-llama-3.3-70b-specdec
  • moonshotai/kimi-k2-instruct

故障排查

Section titled “故障排查”
错误：找不到 API Key

错误： API key not found

解决方案：

  • 检查 .env 文件中是否使用了与你当前提供方匹配的变量名
  • 确保环境变量已正确加载（例如使用 dotenv）
  • 更新 .env 后重启应用
提供方环境变量
Model GatewayBROWSERBASE_API_KEY（无需提供方 Key）
GoogleGOOGLE_GENERATIVE_AI_API_KEY 或 GEMINI_API_KEY
Vertex服务账号凭据（见设置）
AnthropicANTHROPIC_API_KEY
OpenAIOPENAI_API_KEY
AzureAZURE_API_KEY
CerebrasCEREBRAS_API_KEY
DeepSeekDEEPSEEK_API_KEY
GroqGROQ_API_KEY
MistralMISTRAL_API_KEY
Ollama无（本地）
PerplexityPERPLEXITY_API_KEY
TogetherAITOGETHER_AI_API_KEY
xAIXAI_API_KEY
AI GatewayAI_GATEWAY_API_KEY
错误：模型不受支持

错误： Unsupported model

解决方案：

  • 使用 provider/model 格式，例如：openai/gpt-5
  • 确认该模型名存在于对应提供方文档中
  • 检查模型名拼写是否正确
  • 确认你的模型 API Key 有权限访问该模型
模型不支持结构化输出

错误： Model does not support structured outputs

解决方案：

成本高或性能慢

症状： 自动化执行成本高或速度慢

解决方案：

  • 切换到更具成本效益的模型（可参考 evals 对比）
  • 简单任务使用更快模型，复杂任务使用更强模型
  • 对重复模式启用缓存
Python SDK 或自定义模型

Stagehand v3 现已支持 Python。Python SDK 采用 BYOB（Bring Your Own Browser，自带浏览器）架构。

解决方案：

需要帮助？联系支持团队

Section titled “需要帮助？联系支持团队”

找不到解决方案，或还有其他问题？欢迎联系支持团队：

下一步

Section titled “下一步”

提示词指南

学习如何为 LLM 编写提示词，以获得最佳结果。

运行评测

测试哪些模型最适合你的具体使用场景。

缓存指南

通过缓存响应来降低成本并提升速度。

优化成本

借助缓存与智能模型选择来降低 LLM 开销。

-
0:000:00
Blog Docs Books About
概览

First Steps

Introduction Quickstart Installation AI Rules

The Basics

Agent Act Extract Observe Evals

Configuration

Browser Observability Logging Models

Best Practices

Caching Actions Cost Optimization Deterministic Agent Using Multiple Tabs Deploying Stagehand History Tracking Computer Use Agents Agent Fallbacks Prompting Best Practices MCP Integrations Speed Optimization

Integrations

Playwright Puppeteer Selenium