Obscura（实验性）

此适配器不会修复上游引擎的缺陷，也不表示与 Chrome 对等。在选择 Obscura 之前，请先阅读下面的限制说明。

Obscura 是一个用 Rust 编写的无头浏览器引擎。它通过 V8 运行真实的 JavaScript，支持 Chrome DevTools Protocol，并面向网页抓取和 AI 代理自动化。

agent-browser 以与管理 Chrome 相同的方式管理 Obscura。它会启动 obscura serve 进程，通过 CDP 连接，并在完成后将其关闭。所有下游命令（snapshot、click、fill、screenshot 等）都通过相同的 CDP 路径运行。

安装¶

在将 Obscura 与 agent-browser 一起使用之前，请先安装 Obscura 二进制文件：

将二进制文件移动到 PATH 中的某个位置（例如 /usr/local/bin/obscura 或 ~/.local/bin/obscura）。

更多安装选项（包括 Docker 和从源码构建）请参阅 Obscura README。

用法¶

使用 --engine 标志选择 Obscura：

agent-browser --engine obscura open example.com
agent-browser --engine obscura snapshot
agent-browser --engine obscura screenshot

或通过环境变量将其设置为默认引擎：

export AGENT_BROWSER_ENGINE=obscura
agent-browser open example.com

或者放在 ~/.agent-browser/config.json 或通过 --config 加载的文件中：

{
  "engine": "obscura"
}

自定义二进制文件路径¶

如果 obscura 二进制文件不在你的 PATH 中，请使用 --executable-path：

agent-browser --engine obscura --executable-path /path/to/obscura open example.com

隐身模式¶

Obscura 自带一个可选的隐身模式，可提供以隐私为先、一致的浏览器指纹，并阻止已知跟踪器。通过设置 AGENT_BROWSER_OBSCURA_STEALTH 为 Obscura 引擎启用该模式：

AGENT_BROWSER_OBSCURA_STEALTH=1 agent-browser --engine obscura open example.com

设置后，agent-browser 会以 --stealth 启动 obscura serve。接受的值有 1、true、yes 和 on。隐身模式默认关闭，并且需要支持隐身模式的 Obscura 构建版本；禁用隐身模式并不表示与 Chrome 对等。

与 Chrome 的差异¶

Obscura 是专为特定用途打造的无头引擎。某些 Chrome 特有的功能不可用：

如果你将 --engine obscura 与不受支持的标志组合使用，agent-browser 会返回明确的错误。

何时使用 Obscura¶

值得评估的潜在用途包括：

• 通过真实 JavaScript 执行进行网页抓取和数据提取
• 需要轻量级 CDP 目标的 AI 代理工作流
• 希望使用单个自包含二进制文件的 CI/CD 环境
• 希望获得以隐私为先、一致浏览器指纹的配置（Obscura 自带可选隐身模式）

当你需要完整的浏览器保真度、扩展或持久化配置文件时，请使用 Chrome。

实验性 Obscura 提供程序¶

选择 --engine obscura --executable-path /path/to/obscura 来启动本地 Obscura 二进制文件。此提供程序是实验性的。Obscura v0.2.2 在无障碍命名、隐藏元素、iframe 和截图保真度方面存在已知差距；成功的 CDP 连接并不代表与 Chrome 对等。对于依赖这些功能的工作流，请在针对目标页面验证之前使用 Chrome。

本地开发页面需要在会话启动前在环境中设置 OBSCURA_ALLOW_PRIVATE_NETWORK=1。更改引擎启动设置时，请关闭并重新启动该指定名称的会话。隐身模式支持取决于 Obscura 二进制文件的构建方式。不支持的选项（包括 --webgpu、--ca-cert、--args 和 --proxy-bypass）会被拒绝。来自 proxyBypass 配置、AGENT_BROWSER_PROXY_BYPASS、NO_PROXY 或 no_proxy 的代理绕过规则也会被拒绝，即使没有设置代理。只有在不需要绕过时才应移除这些设置；否则请使用 Chrome。显式的 --engine obscura 启动会验证当前调用解析后的绕过设置，即使已有守护进程在运行；清除这些设置不会复用陈旧的守护进程环境值。启动发现和 CDP 初始化各有 10 秒的截止时间，并在初始化失败时进行有界的连接清理。

MCP 工具使用相同的提供程序：在 MCP 服务器的环境中设置 AGENT_BROWSER_EXECUTABLE_PATH，并传递 extraArgs: ["--engine", "obscura"]，因为 --executable-path 在 extraArgs 中会被拒绝。由于工具会委托给标准的 CLI 解析器，因此不需要单独的引擎专用 MCP 工具。

如需进行源码构建测试，请参阅 Obscura 适配器贡献者指南。