轻量级浏览器¶

Lightpanda 是一种可选引擎，用于文本和 DOM 浏览器任务。它通过显式配置的配置文件使用相同的 OpenClaw browser 工具。它不能替代可视化浏览器：请保留一个 Chromium 配置文件，用于截图、PDF 输出以及需要不支持浏览器功能的应用程序。

这些示例将 Lightpanda 固定为 0.4.1。它们不会更改你现有的浏览器配置文件、安装服务，也不会迁移已登录的 Chrome 配置文件。

浏览器插件架构¶

内置的 Browser 插件同时拥有两个引擎适配器。Chromium 和 Lightpanda 使用相同的 browser 工具、配置文件选择、路由准入、导航策略和会话生命周期。已注册的适配器选择能力、CDP 规范化、快照默认值和连接生命周期；它不会增加第二个浏览器工具或进程管理器。

浏览器状态会报告 availableEngines 以及所选引擎的 sessionScope 和 screenshotFidelity。Chromium 保留其受管配置文件、现有会话配置文件、扩展中继配置文件和远程 CDP 配置文件。Lightpanda 仍然是一个显式选择、仅附加的外部引擎，每个连接一个页面，并且在会话丢失后不会自动重放读取。

这些是现有插件内部的适配器，不是可单独安装的第三方插件。启用该适配器不会下载、启动或捆绑 Lightpanda 引擎。现有配置文件和引擎配置保持不变。

许可与分发¶

OpenClaw 的适配器仍采用 MIT 许可证。可选的 Lightpanda 引擎采用 AGPL-3.0-or-later，而非 MIT：请参阅其固定源码声明 和许可证。现有的 Playwright 客户端是 Apache-2.0；现有的 ws 客户端是 MIT。它们的许可证和第三方声明仍然适用。

这些示例通过 CDP 连接到独立安装且未经修改的引擎。它们不会在 OpenClaw 的包或镜像中捆绑或重新授权 Lightpanda。引擎及其容器依赖并非仅限 MIT 的发行版。如果你的部署排除 Copyleft 软件，请不要选择此引擎。

镜像或捆绑引擎需要单独的再分发审查，包括许可证声明、对应源码（Corresponding Source）和第三方义务。修改网络服务的引擎还需要审查 AGPL 第 13 条。单独的处理流程并非全面的法律豁免，校验和验证也不能证明许可证合规。有关已验证的固定版本和其余限制，请参阅工件和依赖审查。

已审查的替代方案¶

以下是截至 2026-09-21 的许可证对比，并不表示这些替代方案已通过 OpenClaw 集成测试或跨平台测试。MIT 兼容的应用与完全宽松许可的引擎发行版是两种不同的要求。

自动化客户端不能替代引擎。例如，Vercel 的 agent-browser 提供 Chrome 和 Lightpanda 后端；其自身的 Apache-2.0 许可证不会改变所选引擎的许可证。同样的区别也适用于 Playwright 和 Puppeteer 客户端。

Obscura 审计边界¶

发布 v0.2.3 在提交 1a3169da276d7720732c7b20535474942917fb83 处进行了审查。 其 lockfile 包含 471 个 registry 包。它们的许可证声明中不包含 AGPL， 但其中五个仅为 MPL-2.0：cooked-waker 5.0.0、cssparser 0.34.0、 cssparser-macros 0.6.1、dtoa-short 0.3.5 和 selectors 0.26.0。 这些依赖项仍保留在 no-render 引擎的 DOM/JavaScript 路径中。 MPL 的文件级义务 并不要求无关的 MIT 适配器文件变为 MPL；它们仍然适用于 受覆盖代码及其分发。

下载的 Linux x86-64 no-render 归档与发布 SHA-256 b5e55e8f2c97814127a521cd59af1a84b79dc40cf658fda04df04af81a2d89f3 匹配。 它仅包含 obscura 和 obscura-worker，没有许可证或声明文件。 固定的 发布工作流 仅打包这些可执行文件，并且不使用 Cargo 的 --locked 标志。 因此，source-lock 元数据并不能证明每个发布二进制文件内部的完整依赖集。 在捆绑或推荐集成部署之前，完整的 V8/第三方和平台库审查、 声明、源码可用性以及运行时兼容性仍需验证。

选择引擎运行位置¶

OpenClaw 容器内的 localhost 指的是该容器，而不是主机，也不是 Lightpanda 边车容器。容器到容器的连接请使用服务名。在 Windows 上，请以 Linux container 模式运行 Docker Desktop，或者在 WSL 内同时运行 OpenClaw 和 Linux 引擎。Lightpanda 不提供原生 Windows 二进制文件。 macOS 和 Linux 提供官方 x86-64 和 ARM64 发布二进制文件； 官方容器镜像提供 Linux amd64 和 arm64 变体。 上游安装信息。

在主机上使用 Docker 运行 OpenClaw¶

从仓库根目录运行：

docker compose -f deploy/lightpanda/compose.yaml -f deploy/lightpanda/compose.host.yaml up -d
docker compose -f deploy/lightpanda/compose.yaml -f deploy/lightpanda/compose.host.yaml exec lightpanda /bin/lightpanda version

示例仅在 127.0.0.1:9222 上发布 CDP。设置 LIGHTPANDA_PORT 可选择 另一个主机端口，并相应更新配置文件 URL。镜像通过其多平台摘要固定， 因此 Docker 会选择主机架构，而不会拉取不断变化的 latest 或 nightly 版本。

CDP 让客户端能够控制浏览器；示例未添加 CDP 身份验证。请勿将回环绑定 更改为公共地址。如需从另一台主机访问，请使用经过身份验证的隧道。

要仅停止并删除此示例的容器和网络：

docker compose -f deploy/lightpanda/compose.yaml -f deploy/lightpanda/compose.host.yaml down

在容器中使用 Docker Compose 运行 OpenClaw¶

将边车容器合并到仓库现有的 Compose 项目中：

docker compose -f docker-compose.yml -f deploy/lightpanda/compose.yaml up -d lightpanda

在下方配置文件中，将 OpenClaw Gateway 配置为 cdpUrl: "ws://lightpanda:9222"。 启动 Gateway 时，请使用相同的 Compose 文件和项目名称。 此变体不会向主机发布浏览器端口。容器共享项目的桥接网络， 并保留出站互联网访问；该网络未声明为 internal: true， 因为那样会阻止浏览公共网站。

对于其状态目录、身份验证和 Gateway 启动，请使用你正常的 OpenClaw Docker 配置。 边车容器不会挂载你的 OpenClaw 状态、浏览器 Cookie 或主机 Docker socket。

对于 Podman，请使用已安装的 Compose 提供程序，并在选择边车 URL 之前 验证服务名 DNS。未安装其 aardvark-dns 辅助程序的 netavark 安装 可以启动一个回环发布的引擎，但容器 DNS 可能仍然损坏； 引擎启动成功并不能证明边车连通性。

原生 Linux 和 macOS¶

从 Lightpanda 0.4.1 下载适用于你的操作系统和 CPU 的发布二进制文件。 示例的 deploy/lightpanda/SHA256SUMS 记录了发布资产的摘要。

对于 Linux x86-64，从仓库根目录运行：

curl --fail --location --output lightpanda-x86_64-linux https://github.com/lightpanda-io/browser/releases/download/0.4.1/lightpanda-x86_64-linux &&
  sha256sum --check --ignore-missing deploy/lightpanda/SHA256SUMS &&
  chmod +x lightpanda-x86_64-linux &&
  LIGHTPANDA_DISABLE_TELEMETRY=1 LIGHTPANDA_DISABLE_CORE_DUMP=1 ./lightpanda-x86_64-linux serve --host 127.0.0.1 --port 9222

对于 macOS Apple 芯片：

curl --fail --location --output lightpanda-aarch64-macos https://github.com/lightpanda-io/browser/releases/download/0.4.1/lightpanda-aarch64-macos &&
  shasum --algorithm 256 --check --ignore-missing deploy/lightpanda/SHA256SUMS &&
  chmod +x lightpanda-aarch64-macos &&
  LIGHTPANDA_DISABLE_TELEMETRY=1 LIGHTPANDA_DISABLE_CORE_DUMP=1 ./lightpanda-aarch64-macos serve --host 127.0.0.1 --port 9222

Linux ARM64 请使用 lightpanda-aarch64-linux， Intel macOS 请使用 lightpanda-x86_64-macos。仅在校验和匹配后 执行下载的二进制文件。Linux 发布二进制文件需要 glibc；在 Alpine 等 基于 musl 的系统上，请使用官方容器镜像。这些命令在前台运行引擎； 使用 Ctrl+C 停止它。

配置一个主动启用的配置文件¶

将此浏览器配置块合并到你的现有配置中：

{
  browser: {
    profiles: {
      lightpanda: {
        engine: "lightpanda",
        cdpUrl: "ws://127.0.0.1:9222",
        attachOnly: true,
      },
    },
  },
}

在浏览器工具调用中使用 profile: "lightpanda"。当所选工作负载通过你的检查后，将 browser.defaultProfile 设置为 "lightpanda"，使其成为默认值。保留你的 Chromium 配置文件，并为可视化或不支持的工作显式选择它。恢复之前的 defaultProfile 以撤销该选择。

engine 声明能力契约；仅有 CDP 端点并不意味着兼容 Chromium。attachOnly 表示 OpenClaw 会附加到你启动的服务，而不是启动或接管本地 Chrome 进程。不要将 executablePath 设置为 Lightpanda：其 CLI 不是 Chrome 的启动 CLI。

会话和能力限制¶

• 一个 Lightpanda CDP 连接拥有其页面状态。关闭连接、停止容器或重启引擎都会丢失该状态；重新连接不会恢复之前的页面或登录状态。
• 一个 CDP 连接支持一个页面目标。多个连接可以共存，但 Lightpanda 配置文件不是一般的多标签 Chromium 会话。
• 操作失败后不会自动进行跨引擎重放。点击或表单提交可能已经发生；在重复操作之前，先检查其结果。
• Lightpanda 的文本布局预览不是渲染后的截图。它无法证明 CSS、图像、字体或视觉布局的正确性。
• 已验证的快照路径是带有 aria 引用的 AI 格式。引擎默认选择这些引用，包括高效快照模式。此适配器不支持显式角色引用、选择器/框架范围快照、带标签的截图以及独立的 aria 快照格式。
• JavaScript 和 Web API 并不保证每个网站都能正常工作。请验证你实际使用的网站和交互模式。

引擎及其会话模型记录在 固定的 Lightpanda 源代码 中。有关共享配置文件和路由规则，请参阅 浏览器配置文件 和 远程浏览器。

验证和基准测试¶

引擎启动、CDP 连接性、任务完成以及完整的 OpenClaw 集成是独立的检查项。正在运行的容器或成功的 Browser.getVersion 并不能证明快照、引用和操作可以通过 OpenClaw 正常工作。

Chromium 无头外壳基线¶

作为不使用 Lightpanda AGPL 引擎的替代方案，首先通过现有 Chromium 配置文件测试 Chromium 无头外壳。它仍保留 Chromium 的第三方许可证义务；这不是一个仅 MIT 许可的二进制文件。它不需要另一个自动化守护进程或 OpenClaw 引擎适配器。

使用仓库固定的 Playwright 安装程序，而不是未固定的包装器：

node node_modules/playwright-core/cli.js install chromium-headless-shell
node node_modules/playwright-core/cli.js install --dry-run chromium-headless-shell

第二条命令会打印所选版本、平台下载和安装目录。在该目录中定位 chrome-headless-shell（在 Windows 上为 chrome-headless-shell.exe）。Linux 还需要浏览器的系统库和字体；请参阅 Linux 故障排除。从仓库根目录运行，并为包含空格的路径添加引号：

node --import ./scripts/tsx.mjs extensions/browser/scripts/bench-lightweight.ts --headless-shell "/path/to/chrome-headless-shell" --iterations 10 --output headless-shell-benchmark.json

报告将请求的发行版与其 Chromium 协议引擎以及观察到的浏览器版本分开标注。--headless-shell 仅选择基准测试可执行文件：它不会安装生产浏览器、更改配置文件或建立二进制来源。在审查部署时，请保留其完整发行版和 LICENSE.headless_shell。安装程序还会下载平台辅助资源，包括 FFmpeg；请单独审查并保留它们各自的声明。对完整 Chromium 和无头外壳的对比请使用单独的调用；内存或启动节省必须通过测量得出，而不能从下载大小推断。

原生引擎对比¶

安装开发依赖项后，从仓库根目录运行主动启用的合成路由基准测试：

node --import ./scripts/tsx.mjs extensions/browser/scripts/bench-lightweight.ts --lightpanda /path/to/lightpanda --chromium /path/to/chrome --iterations 10 --output lightweight-benchmark.json

任何二进制标志都可以单独使用。该脚本会创建隔离的 OpenClaw 状态和浏览器数据，提供一个本地表单，然后通过浏览器路由分发器验证导航、默认的高效 AI 快照、基于引用的输入/点击、恰好一次表单提交、等待以及文本提取。Chromium 基线使用 OpenClaw 管理的无头启动标志，并为此隔离的本地测试夹具禁用沙箱；它不会更改生产浏览器配置。最小化 Linux 主机仍需要 Chromium 的共享库和字体。可以使用 LD_LIBRARY_PATH 和 FONTCONFIG_FILE 选择任务本地安装，而无需更改主机的软件包。Lightpanda 还会检查不支持操作的拒绝、其单页限制以及断开连接后对过期目标的拒绝。这些检查不使用 LLM，也不测量模型推理或端到端代理 token 成本。

--iterations 接受 1 到 100，并统计 热任务。单独的首个任务包括初始页面打开和 CDP 附加；每个热任务都包括导航和相同的表单工作流。原生运行还会报告进程启动以及从启动到第一个完成任务的时间。热任务百分位数排除首个任务。能力/会话检查在测量窗口之后运行。

组合运行使用一个 Node 控制器并记录引擎顺序；其后续引擎可以复用先前引擎已经加载的控制器模块。first-task 和 process-start 数值不是冷启动 CLI/控制器测量值。比较独立初始化的控制器时，请使用单独调用。

内存字段是采样的进程树 PSS/RSS 最大值，并非真实峰值。它们使用 Linux /proc，每 50 ms 以及任务边界处尝试采样。短生命周期进程或瞬时分配可能未被捕获。不支持的主机和外部托管引擎会报告 null，进程内存不可读的运行也会报告 null，绝不会给出推测的引擎内存数值。Controller RSS 是工作负载结束时的单独采样，不是增量控制器开销；不要将独立采样的最大值相加并称之为总峰值主机内存。

外部托管引擎¶

使用专用引擎实例。外部模式会关闭基准测试的控制连接及其自身的 Chromium 标签页，但不会停止引擎进程：

node --import ./scripts/tsx.mjs extensions/browser/scripts/bench-lightweight.ts --endpoint ws://127.0.0.1:9222 --engine lightpanda --fixture-bind 0.0.0.0 --fixture-host host.docker.internal --iterations 10 --output lightweight-container-benchmark.json

此示例从主机端访问 Docker Desktop 引擎。合成测试夹具监听器被显式暴露在主机上，以便容器能够访问它；--fixture-host 必须指定浏览器网络中控制器的名称，而不是控制器自身网络中的名称。Linux Docker 需要一个可到达的主机地址或已配置的 host-gateway 映射。当省略这些标志时，默认测试夹具监听器/主机名仍为 127.0.0.1。

外部模式将引擎启动和内存报告为 null。请随报告单独记录固定的容器/二进制版本。Windows Node 控制器可以使用相同的外部引擎接口，但此示例未验证 Windows Docker 运行时行为。

使用固定的 Chromium 基线比较相同的确定性任务。在报告速度或内存改进之前，记录任务完成情况；不支持或失败的工作不得计为成功的快速结果。分别报告热运行和冷运行、引擎版本、主机操作系统/架构、客户端开销，以及内存是否包含整个进程树或容器。

对于 Docker Desktop，容器内存不包括 VM 的主机开销。不要将原生进程 RSS 数值与仅容器数值进行比较，并将差异称为总主机节省。保持所有基准测试夹具为公开或本地；不要导出已登录的现有浏览器配置文件以使基准测试通过。

上述列出的平台支持描述的是上游分发和部署拓扑，并非声称每个平台都通过了相同的运行时测试。请随基准测试报告记录实际的平台和容器运行时结果。