沙箱里的编码智能体,读不了网页。它跑在隔离的虚拟机里,沙箱控制它能访问哪些主机,凭据留在宿主机上、藏在代理后面。同一套控制也让它打不开文档页、读不了更新日志、查不到训练截止日期之后才发布的 API——于是它只能照着记忆里的版本来写代码。

打开网易新闻 查看精彩图片

常见的解法是把允许列表一路放宽,直到智能体能抓取任何东西。代价是,沙箱当初拿走的东西,大部分又还了回去。

打开网易新闻 查看精彩图片

Firecrawl 的沙箱套件换了个思路:只新增一个主机 api.firecrawl.dev,就为智能体提供网页搜索、页面抓取和站点爬取能力,而且每个页面都以干净的 markdown 返回。

打开网易新闻 查看精彩图片

套件是怎么接进去的

Firecrawl 套件是一个 mixin(kind: mixin):它扩展你已经在跑的工作负载,而不是定义一个新的沙箱。它的描述文件 firecrawl/firecrawl.yaml 声明了四项带类型的能力:

  • 安装步骤(lifecycle@1):以智能体用户身份安装 Firecrawl Python SDK firecrawl-py,版本锁定在 4.44.0;安装或导入检查失败,沙箱创建即失败。
  • 凭据(credential@1):申请一个由代理管理的 firecrawl API 密钥。沙箱内 FIRECRAWL_API_KEY 只持有占位符 proxy-managed,代理在请求 api.firecrawl.dev 时替换成真实密钥,密钥因此从不进入镜像或沙箱。
  • 网络权限(network-policy@1):按阶段拆分。安装步骤可访问 pypi.org 和 files.pythonhosted.org;运行时智能体可访问 api.firecrawl.dev。
  • 智能体指令(agent-context@1):一个上下文文件告诉智能体这项能力存在、怎么调用、哪些限制来自沙箱。工作负载从自己的 AGENTS.md 里索引它。

套件只往沙箱的允许列表里加东西,不缩小它,其余一切仍由全局的 sbx 策略决定。Docker 的 balanced 预设允许包仓库、GitHub 和一份精选的厂商域名清单,对一般网站(包括大多数文档站)返回 403,Firecrawl 就是智能体通往这些站点的路。在 deny-all 下,它是智能体唯一的网页主机。

套件目前是实验性的,处于 Early Access 阶段,套件格式和 sbx 命令都可能变化。以下步骤以 2026 年 10 月为准,最新信息以仓库 README 为准。

上手流程

前置条件:sbx CLI 版本 0.46 或更高,并用 sbx login 登录;用 sbx policy init balanced 设置一次全局网络策略,没有它任何沙箱都起不来;一个来自 firecrawl.dev/app/api-keys 的 Firecrawl API 密钥(fc-...);以及一个可以挂载套件的工作负载。

第一步,在宿主机上存一次密钥。命令会提示输入。服务密钥默认是全局的,你批准之后,每个申请 firecrawl 服务的沙箱都能用。套件永远看不到密钥值,代理在请求时注入。

第二步,带套件启动沙箱。套件就是一个普通的 OCI 镜像,描述文件在 manifest 里,所以只需要一个版本标签。每个 --kit 往工作负载上加一个 mixin,末尾的 . 挂载你的项目目录。首次运行时,sbx 会请求你批准把 firecrawl 凭据发送到 api.firecrawl.dev,接受默认值即可。凭据是必需的:没有存密钥时,sbx 会拒绝创建沙箱,而不是让智能体在任务中途撞上 401。分离运行或 CI 运行无法回答批准提示,所以要么交互式批准一次,要么先把绑定写进 ~/.config/sbx/credentials.yaml。

第三步,给智能体一个需要实时网页的任务。balanced 下文档站是被挡住的,所以这个任务必须走 Firecrawl。套件的指令会告诉智能体通过 Firecrawl 抓取被挡的主机,于是它未经提示就调用了 fc.scrape(...)。

第四步,逐层验证。在同一个会话里,! 会在沙箱内执行 shell 命令。检查 firecrawl-py 版本应为 4.44.0;检查环境变量应显示 FIRECRAWL_API_KEY=proxy-managed,如果这里出现真实的 fc-... 值,说明密钥来自套件之外的地方;再抓一次页面,应返回以 # Changelog 开头的 markdown。同一个 URL 在沙箱内用 curl 访问会返回 403,所以这里的输出同时证明了 SDK、凭据和网络规则三者都通了。

套件也会在沙箱内描述自己,打印出已发布的描述文件,智能体指令就在旁边的 firecrawl-context.md 里。如果想在运行前审查或修改套件,克隆仓库并把 --kit 指向 firecrawl/ 目录,sbx 会按需构建源码套件。

已知限制

  • balanced 下一般网站对 curl 返回代理 403,所以抓取结果里出现的 URL 也得通过 Firecrawl 再抓一次。
  • 截图和其他媒体格式返回的是 Firecrawl 存储主机上的链接,该主机不在允许列表里,这些文件无法在沙箱内下载。
  • 在组织治理下,托管策略会覆盖套件的允许规则,抓取会以代理侧 403 失败,直到组织允许 api.firecrawl.dev。
  • HTTP 402 表示 Firecrawl 账户额度用尽,智能体会被告知停止而不是重试。

这解锁了什么

装上套件后,智能体可以在干活时上网查东西。沙箱只需要多跟一个地址说话,页面由 Firecrawl 代为抓取。这件事之所以重要,是因为默认的 balanced 策略挡住了大多数文档站。没有套件,你要么让智能体凭记忆工作,要么一个个放行站点,而每放行一个新站点,沙箱就松一分。套件避开了这个选择:Firecrawl API 密钥留在你的机器上、藏在代理后面,智能体读到的仍是今天的网页。

具体来说,智能体可以:在调用某个库或 SaaS API 之前先抓它的参考页和更新日志,用今天的参数名,并发现训练截止之后才出现的弃用;被要求升级依赖时,读完中间每个版本的发布说明,列出破坏性变更,改完代码再跑测试;为新集成爬取厂商文档的相关章节并以 markdown 取回,从整份指南而不是单页出发;遇到不认识的构建或测试报错时搜索它,读对应的 GitHub issue 或论坛帖,套用有记录的修复或绕行方案;因为每个答案都来自抓取到的页面,它可以引用原文并附上 URL,方便你核对。

结果是更少的编造 API、更少的失败升级,以及更少花在纠正一个自信过时的智能体上的时间。

套件以 firecrawl 组织名义发布在 Docker Hub 上,源码、变更日志和 CI 在 GitHub 上,采用 Apache-2.0 许可。SDK 的版本锁定在安装时对照 PyPI 的包哈希校验,每个发布版本都在 CI 中通过 Docker 的 kit-tck 一致性测试套件。和任何套件一样,运行前先审查描述文件和允许列表。