浏览器 | Firecrawl

对于代理工作流，请使用 Interact。Interact 是 CLI/MCP 的受支持方案，可在抓取后通过提示词或代码驱动；MCP 也支持直接从 URL 打开。

Surface	用途	入口	代理入口
浏览器沙箱	面向需要沙箱、CDP URL、实时视图或持久会话生命周期的 API/SDK 用户的独立浏览器会话	`POST /v2/interact`	API 和 SDKs；隐藏的 CLI 浏览器命令为旧版
Interact	对已抓取的页面执行操作；MCP 也可通过 `firecrawl_interact` 的 URL 模式直接从 URL 打开	`POST /v2/scrape/{scrapeId}/interact`、抓取后的 CLI `interact`，或 MCP `firecrawl_interact`	推荐用于 CLI/MCP 代理工作流

Firecrawl 浏览器沙箱为 API 和 SDK 用户提供一个安全的浏览器环境，让代理能够与 Web 交互。可以填写表单、点击按钮、进行身份验证等。无需本地配置，无需安装 Chromium，也不存在驱动兼容性问题。代理浏览器和 Playwright 已预先安装。可通过 API、Node SDK、Python SDK 和 Vercel AI SDK 使用。隐藏的 firecrawl browser CLI 命令为旧版；CLI 和 MCP 代理流程应改用 scrape + interact。要为 AI 编码代理 (Claude Code、Codex、Open Code、Cursor 等) 添加 Interact 支持，请安装 Firecrawl skill：

npx -y firecrawl-cli@latest init --all --browser

每个会话都在隔离的一次性或持久化沙箱中运行，并且可在无需管理基础设施的情况下进行扩展。

快速开始

创建会话，执行代码，然后关闭它：

// npm install firecrawl
import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

// 1. Launch a session
const session = await firecrawl.browser();
console.log(session.cdpUrl); // wss://cdp-proxy.firecrawl.dev/cdp/...

// 2. Execute code
const result = await firecrawl.browserExecute(session.id, {
  code: `
    await page.goto("https://news.ycombinator.com");
    const title = await page.title();
    console.log(title);
  `,
  language: "node",
});
console.log(result.result); // "Hacker News"

// 3. Close
await firecrawl.deleteBrowser(session.id);

# pip install firecrawl
from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

# 1. 启动会话
session = app.browser()
print(session.cdp_url)  # wss://cdp-proxy.firecrawl.dev/cdp/...

# 2. Execute code
result = app.browser_execute(
    session.id,
    code='await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',
    language="python",
)
print(result.result)  # "Hacker News"

# 3. Close
app.delete_browser(session.id)

# Install the Firecrawl CLI
npm install -g firecrawl-cli

# 简写方式 - 自动启动会话,无需 "execute"
firecrawl browser "open https://news.ycombinator.com"
firecrawl browser "snapshot"
firecrawl browser "scrape"

# Close when done
firecrawl browser close

# 1. 启动会话
curl -X POST "https://api.firecrawl.dev/v2/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json"

# 2. 执行代码
curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "await page.goto(\"https://news.ycombinator.com\")\ntitle = await page.title()\nprint(title)"
  }'

# 3. 关闭会话
curl -X DELETE "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

无需安装驱动 - 无需 Chromium 二进制文件，无需 playwright install，也没有驱动兼容性问题
Python、JavaScript 和 Bash - 通过 API、CLI 或 SDK 发送代码并获取结果。三种语言都会在远程沙盒中运行
agent-browser - 预装的 CLI，内置 60+ 条命令。AI 代理只需编写简单的 Bash 命令，无需编写 Playwright 代码
已加载 Playwright - Playwright 已预装在沙盒中。代理如果愿意，也可以编写 Playwright 代码。
CDP 访问 - 当你需要完全控制时，可通过 WebSocket 连接你自己的 Playwright 实例
实时视图 - 通过可嵌入的流 URL 实时查看会话
交互式实时视图 - 通过可嵌入的交互式流，让用户直接与浏览器交互

启动一个会话

返回会话 ID、CDP URL 和实时视图 URL。

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const session = await firecrawl.browser({
  ttl: 120,
  activityTtl: 60,
});

console.log(session.id);
console.log(session.cdpUrl);      // wss://cdp-proxy.firecrawl.dev/cdp/...
console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

session = app.browser(
    ttl=120,
    activity_ttl=60,
)

print(session.id)
print(session.cdp_url)        # wss://cdp-proxy.firecrawl.dev/cdp/...
print(session.live_view_url)  # https://liveview.firecrawl.dev/...

# 启动实时视图并自定义 TTL
firecrawl browser launch-session --stream --ttl 120 --ttl-inactivity 60

# 启动并将会话信息保存至文件
firecrawl browser launch-session -o session.json --json

curl -X POST "https://api.firecrawl.dev/v2/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": 120,
    "activityTtl": 60
  }'

Response

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cdpUrl": "wss://browser.firecrawl.dev/cdp/550e8400...?token=abc123...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "expiresAt": "2025-01-15T10:40:00Z"
}

执行代码

在会话中运行 Python、JavaScript 或 bash 代码。输出通过 stdout 返回；对于 Node.js，最后一个表达式的值也可在 result 中获得。

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const result = await firecrawl.browserExecute("YOUR_SESSION_ID", {
  code: 'await page.goto("https://example.com"); const title = await page.title(); console.log(title);',
  language: "node",
});

console.log(result);

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

result = app.browser_execute(
    "YOUR_SESSION_ID",
    code='await page.goto("https://example.com")\ntitle = await page.title()\nprint(title)',
    language="python",
)

print(result)

# agent-browser 命令(默认情况下会自动添加 "agent-browser" 前缀)
firecrawl browser execute "open https://example.com"
firecrawl browser execute "snapshot"
firecrawl browser execute "scrape"

# Execute Playwright Python code
firecrawl browser execute --python 'await page.goto("https://example.com")
print(await page.title())'

# Execute Playwright JavaScript code
firecrawl browser execute --node 'await page.goto("https://example.com"); document.title'

# Execute arbitrary bash in the sandbox
firecrawl browser execute --bash 'ls /tmp'

# Target a specific session
firecrawl browser execute --session <id> "snapshot"

# Execute Playwright Python code
curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "await page.goto(\"https://example.com\")\ntitle = await page.title()\nprint(title)",
    "language": "python"
  }'

# 执行 Playwright JavaScript 代码
curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "await page.goto(\"https://example.com\"); const title = await page.title(); console.log(title);",
    "language": "node"
  }'

# Navigate to a page
curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "agent-browser open https://example.com", "language": "bash" }'

# Get accessibility snapshot with @ref IDs
curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "agent-browser snapshot", "language": "bash" }'

# 使用快照中的 @ref ID 进行交互
curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "agent-browser click @e5", "language": "bash" }'

# Extract page content as markdown
curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "agent-browser scrape", "language": "bash" }'

Response

{
  "success": true,
  "stdout": "",
  "result": "Example Domain",
  "stderr": "",
  "exitCode": 0,
  "killed": false
}

处理文件下载

在会话中下载的文件可以捕获并以 base64 形式返回。可通过 execute 端点使用 Playwright 的下载 API：

import base64

async with page.expect_download() as download_info:
    await page.click('a#download-link')  # 点击触发下载的元素

download = download_info.value
path = await download.path()

# 可选：保存到指定路径
# await download.save_as('/tmp/myfile.pdf')

# 读取文件内容并以 base64 输出
with open(path, "rb") as f:
    content = base64.b64encode(f.read()).decode()
    print(content)

// 从链接元素获取下载 URL
const href = await page.getAttribute('a#download-link', 'href');

// 在浏览器上下文中获取文件并转换为 base64
const b64 = await page.evaluate(async (url) => {
  const resp = await fetch(url);
  const blob = await resp.blob();
  return new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(blob);
  });
}, href);

process.stdout.write(b64);

沙箱文件系统是临时的——会话结束后，已下载的文件就会丢失。若要持久保存文件，请在会话期间读取其内容并保存到你自己的存储中。持久化配置文件会保留浏览器状态 (cookies、localStorage) ，但不会保留磁盘上的文件。

agent-browser (Bash 模式)

agent-browser 是一个无头浏览器 CLI，已预装在每个沙箱中。代理无需编写 Playwright 代码，只需发送简单的 bash 命令。CLI 会自动注入 --cdp，使 agent-browser 自动连接到你的当前会话。

下面的 firecrawl browser CLI 示例适用于旧版浏览器沙箱会话。对于 CLI/MCP 代理工作流，建议优先使用 firecrawl interact 或 MCP firecrawl_interact 工具。

简写

这是使用 browser 的最快方式。简写和 execute 都会自动将命令发送给 agent-browser。简写只是跳过了 execute，并在需要时自动启动会话：

firecrawl browser "open https://example.com"
firecrawl browser "snapshot"
firecrawl browser "click @e5"

CLI

显式用法使用 execute 命令。命令会自动发送到 agent-browser —— 无需手动输入 agent-browser 或使用 --bash：

firecrawl browser execute "open https://example.com"
firecrawl browser execute "snapshot"

firecrawl browser execute "click @e5"
firecrawl browser execute "fill @e3 'search query'"
firecrawl browser execute "scrape"

API 与 SDK

使用 language: "bash"，通过 API 或 SDK 执行 agent-browser 命令：

curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "agent-browser snapshot",
    "language": "bash"
  }'

const result = await app.browserExecute(sessionId, {
  code: "agent-browser snapshot",
  language: "bash",
});

result = app.browser_execute(
    session_id,
    code="agent-browser snapshot",
    language="bash",
)

会话管理

持久化会话

默认情况下，每个浏览器会话都会从全新环境开始。通过 profile，你可以在会话之间保存并复用浏览器状态。这对于保持登录状态和保留偏好设置非常有用。若要保存或选择某个持久化配置文件，请在创建会话时使用 profile 参数。

const session = await firecrawl.browser({
  ttl: 600,
  profile: {
    name: "my-profile",
    saveChanges: true,
  },
});

session = app.browser(
    ttl=600,
    profile={
        "name": "my-profile",
        "save_changes": True,
    },
)

curl -X POST "https://api.firecrawl.dev/v2/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": 600,
    "profile": {
      "name": "my-profile",
      "saveChanges": true
    }
  }'

# 使用配置文件启动（默认保存更改）
firecrawl browser launch-session --profile my-profile

# 以只读模式使用配置文件启动
firecrawl browser launch-session --profile my-profile --no-save-changes

# 简写：使用配置文件启动并一步执行
firecrawl browser --profile my-profile "open https://example.com"

参数	默认值	描述
`name`	—	持久化配置文件的名称。使用相同名称的会话会共享存储。
`saveChanges`	`true`	当为 `true` 时，浏览器状态会在关闭时保存回该配置文件。将其设置为 `false` 可在不写入的情况下加载已有数据——在需要多个并发只读访问时很有用。

同一时间只有一个会话可以向某个配置文件保存数据。如果已有其他会话在保存，你会收到 409 错误。你仍然可以以 saveChanges: false 的方式打开同一配置文件，或者稍后重试。

浏览器会话状态只有在会话关闭时才会保存。因此，我们建议在使用完成后关闭浏览器会话，以便后续复用。会话一旦关闭，其会话 ID 将不再有效——你无法再次使用它。请改为使用相同的配置文件名称创建一个新会话，并使用响应中返回的新会话 ID。要保存并关闭会话：

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

await firecrawl.deleteBrowser("YOUR_SESSION_ID");

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

app.delete_browser("YOUR_SESSION_ID")

# 关闭当前会话
firecrawl browser close

# 关闭指定会话
firecrawl browser close --session <id>

curl -X DELETE "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

列出会话

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const { sessions } = await firecrawl.listBrowsers();
console.log(sessions);

// 按状态过滤
const { sessions: active } = await firecrawl.listBrowsers({ status: "active" });
console.log(active);

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

response = app.list_browsers()
print(response.sessions)

firecrawl browser list
firecrawl browser list active

curl -X GET "https://api.firecrawl.dev/v2/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# 按状态过滤
curl -X GET "https://api.firecrawl.dev/v2/interact?status=active" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

Response

{
  "success": true,
  "sessions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "active",
      "cdpUrl": "wss://browser.firecrawl.dev/cdp/550e8400...?token=abc123...",
      "liveViewUrl": "https://liveview.firecrawl.dev/...",
      "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
      "createdAt": "2025-01-15T10:30:00Z",
      "lastActivity": "2025-01-15T10:35:00Z"
    }
  ]
}

TTL 配置

会话有两个 TTL 参数：

参数	默认值	描述
`ttl`	600s (10 分钟)	会话的最长存续时间 (30-3600s)
`activityTtl`	300s (5 分钟)	会话空闲达到该时长后自动关闭 (10-3600s)

广告拦截

与抓取中的 blockAds 一样，会话默认会拦截广告、跟踪器和 Cookie 弹窗。创建会话时传入 "blockAds": false，即可加载未经过滤的页面。通过启用 interact 的抓取启动的会话，会沿用该抓取的 blockAds 设置。

位置

会话默认从美国发起浏览。如需从其他国家/地区浏览，请在创建会话时传入 location 参数并指定 ISO 3166-1 alpha-2 国家代码，用法与抓取中的 location 相同：

curl -X POST "https://api.firecrawl.dev/v2/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "location": { "country": "GB" } }'

会话仅接受国家/地区代码：传入 languages 或抓取支持的特殊值 (如 us-generic) 都会被拒绝，并返回 400。通过带交互的抓取开始的会话，会沿用该抓取的 location.country。

零数据保留

创建会话时传入 "zeroDataRetention": true，即可以零数据保留 (ZDR) 模式运行该会话。会话生命周期结束后，Firecrawl 不会持久化任何页面内容或执行输出，并且后续对该会话的所有调用都将保持 ZDR 模式。你的团队必须已启用 ZDR，否则请求将返回 403。ZDR 模式下不支持会话录制和持久化配置文件 (返回 400) ，已有的非 ZDR 会话也无法切换为 ZDR (返回 409) 。详情请参见交互 ZDR。

结束会话

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

await firecrawl.deleteBrowser("YOUR_SESSION_ID");

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

app.delete_browser("YOUR_SESSION_ID")

# 关闭当前会话
firecrawl browser close

# 关闭指定会话
firecrawl browser close --session <id>

curl -X DELETE "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

实时视图

每个会话的响应中都会包含一个 liveViewUrl，你可以将其嵌入以实时查看浏览器行为。适用于调试、演示或构建由浏览器驱动的 UI。

Response

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cdpUrl": "wss://browser.firecrawl.dev/cdp/550e8400...?token=abc123...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "expiresAt": "2025-01-15T10:40:00Z"
}

<iframe src="LIVE_VIEW_URL" width="100%" height="600" />

交互式实时视图

响应中还包含一个 interactiveLiveViewUrl。与仅支持查看的标准实时视图不同，交互式实时视图允许用户通过嵌入的流直接点击、输入并与浏览器会话进行交互。这对于构建面向用户的浏览器界面、协同调试，或任何需要查看者直接控制浏览器的场景都非常有用。

<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />

通过 CDP 连接

每个会话都会暴露一个 CDP WebSocket URL。execute API 和 --bash 参数覆盖了大多数用例，但如果你需要完全的本地控制，可以直接进行连接。

import { Firecrawl } from 'firecrawl';
import { chromium } from "playwright-core";

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const session = await firecrawl.browser();

const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] || (await context.newPage());

await page.goto("https://example.com");
console.log(await page.title());

await browser.close();
await firecrawl.deleteBrowser(session.id);

from firecrawl import Firecrawl
from playwright.sync_api import sync_playwright

app = Firecrawl(api_key="fc-YOUR-API-KEY")
session = app.browser()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(session.cdp_url)
    context = browser.contexts[0]
    page = context.pages[0] if context.pages else context.new_page()

    page.goto("https://example.com")
    print(page.title())

    browser.close()

app.delete_browser(session.id)

# 使用会话响应中的 cdpUrl
CDP_URL=YOUR_SESSION_CDP_URL

agent-browser open https://example.com --cdp "$CDP_URL"
agent-browser snapshot --cdp "$CDP_URL"

何时使用浏览器

使用场景	合适工具
从已知 URL 提取内容	Scrape
在网上搜索并获取结果	Search
执行分页导航、填写表单、点击操作流程	浏览器
包含交互的多步工作流	浏览器
在多个网站上并行浏览	浏览器 (每个会话彼此隔离)

使用场景

竞争情报 - 浏览竞争对手网站，操作搜索表单和筛选器，将价格和功能信息提取为结构化数据
知识库接入 - 浏览需要点击操作、分页或登录认证的帮助中心、文档和支持门户
市场调研 - 启动并行浏览器会话，从招聘网站、房产列表或法律数据库中构建数据集

定价

定价取决于驱动会话的方式：如果会话使用 prompt，每浏览器分钟消耗 7 个额度；如果不使用 (仅使用 Playwright code) ，每浏览器分钟消耗 2 个额度。按浏览器分钟计费，最低计费时长为 1 分钟。零数据保留会话每浏览器分钟额外收取 2 个额度：使用 prompt 的会话每浏览器分钟消耗 9 个额度，不使用的则消耗 4 个额度，最低计费时长同样为 1 分钟。

速率限制

在初始发布阶段，所有套餐均支持最多 20 个并发浏览器会话。

API 参考文档

有反馈或需要帮助？请发送邮件至 help@firecrawl.com 或在 Discord 上联系我们。

你是需要 Firecrawl API 密钥的 AI 代理吗？请参阅 firecrawl.dev/agent-onboarding/SKILL.md 了解自动化引导说明。

快速上手

核心端点

更多

快速入门

开发者指南

Webhooks

使用场景

其他

参与贡献

浏览器沙箱

快速开始

启动一个会话

执行代码

处理文件下载

agent-browser (Bash 模式)

简写

CLI

API 与 SDK

会话管理

持久化会话

列出会话

TTL 配置

广告拦截

位置

零数据保留

结束会话

实时视图

交互式实时视图

通过 CDP 连接

何时使用浏览器

使用场景

定价

速率限制

API 参考文档

​快速开始

​启动一个会话

​执行代码

​处理文件下载

​agent-browser (Bash 模式)

​简写

​CLI

​API 与 SDK

​会话管理

​持久化会话

​列出会话

​TTL 配置

​广告拦截

​位置

​零数据保留

​结束会话

​实时视图

​交互式实时视图

​通过 CDP 连接

​何时使用浏览器

​使用场景

​定价

​速率限制

​API 参考文档

快速开始

启动一个会话

执行代码

处理文件下载

agent-browser (Bash 模式)

简写

CLI

API 与 SDK

会话管理

持久化会话

列出会话

TTL 配置

广告拦截

位置

零数据保留

结束会话

实时视图

交互式实时视图

通过 CDP 连接

何时使用浏览器

使用场景

定价

速率限制

API 参考文档