为 Agent 沙箱
换上隐身浏览器

三句话:发生了什么

这是一份调研 + 落地一体的报告。结论已经写进代码 —— 分支 feat/sandbox-cloakbrowser 的 commit 27eea379 已把替换做完。下面三条是全部要点, 后续章节是它们的展开与依据。

OMNE 怎么上网:点击,不是调 API

第一个调研问题:OMNE 有没有一条独立的「浏览器自动化」通路?答案是 —— 设计有, 实现还没到位。ADR-007(已 Accepted)定义了 browser-use: 基于 browser-use 框架、走 CDP / DOM 的结构化浏览器控制; domain 层也已经有 BrowserAction 枚举(navigate、click_element 等 18 个动作)。但它尚未作为独立能力落地 —— browser_use_enabled 目前以 computer_use_enabled 为前提。

所以今天 agent 真正「上网」的方式只有一种:computer use。 它把浏览器当成桌面上的一个普通 GUI 窗口 —— 用模拟出来的鼠标键盘去点、去输, 用截图去看。整条链路是这样的:

沙箱镜像里,原本装的是什么浏览器

第二个调研问题:computer use 的沙箱镜像里,默认带着哪些浏览器? 镜像由 docker/local-e2e/Dockerfile.sandbox.kasmvnc 构建, 基础镜像是 kasmweb/ubuntu-noble-desktop:1.18.0 —— 一个自带 KasmVNC、XFCE 桌面与常用工具的 Ubuntu 24.04 桌面镜像。

它默认带两类浏览器:在 amd64 上是 Google Chrome、在 arm64 上是 Chromium,另外两个架构都带一份 Firefox。 镜像构建时只对它们做了「升级到最新版」,没有动指纹。

问题不在「能不能跑」,在「像不像机器」

这些是标准发行版 Chromium。即便 agent 用的是真实点击, 浏览器二进制本身仍会向网站泄露一组可被关联的指纹 —— canvas / WebGL 渲染特征、字体度量、navigator 属性、各类 API 的细微行为差异。 Cloudflare、DataDome、PerimeterX 这类反爬服务正是靠这组指纹, 把「疑似自动化环境」从真人里筛出来。换句话说:点击是真的, 浏览器的「长相」却是一眼能认出的标准款。这就是要换浏览器的动机。

CloakBrowser:补丁打在源码里的 Chromium

CloakBrowser 是一个真正的 Chromium 二进制 —— 它的关键区别在于反检测指纹补丁打在 C++ 源码层, 再编译成二进制。它不是注入页面的 JS shim,不是改一组启动参数或配置, 而是「出厂时长相就不一样」。这正是它能稳定通过 Cloudflare / DataDome / PerimeterX 检查的原因 —— 那些检查针对的恰恰是标准自动化 Chromium 的指纹。

对 OMNE 来说,这个性质很关键:它意味着 CloakBrowser 适合直接作为二进制替换。 不需要改 agent、不需要改交互协议 —— 把桌面上那个浏览器换掉,stealth 就跟着进来了。 CloakBrowser 自己把能力分成两层,而这两层对 computer use 的意义并不相同 —— 这是下一节的主题。

实现:四个文件,一次干净的替换

替换在 commit 27eea379 完成,改动集中在 docker/local-e2e/ 之下 —— 共 4 个文件、+180 −1。没有触碰 agent 代码, 也没有触碰交互协议。整个改动可以拆成两步。

step 7.5 的核心:预下载 + 钉链接 + 构建期冒烟测试

# 反检测的隐身 Chromium —— 取代基础镜像的 Chrome / Chromium
ENV CLOAKBROWSER_HOME=/opt/cloakbrowser \
    BROWSER=/usr/local/bin/cloakbrowser

COPY --chmod=0755 cloakbrowser/cloakbrowser-launch.sh /usr/local/bin/cloakbrowser
COPY cloakbrowser/cloakbrowser.desktop  /usr/share/applications/

RUN uv venv --python 3.12 "$CLOAKBROWSER_HOME/venv" \
 && uv pip install --python "$CLOAKBROWSER_HOME/venv/bin/python" cloakbrowser \
 && "$CLOAKBROWSER_HOME/venv/bin/python" -m cloakbrowser install \
 # 解析出 Chromium 可执行文件,钉一个稳定符号链接给启动器
 && ln -sfn "$CLOAK_BIN" "$CLOAKBROWSER_HOME/chrome" \
 # 构建期冒烟测试:证明二进制能在该架构上真正跑起来
 && timeout 90 "$CLOAKBROWSER_HOME/chrome" --no-sandbox --version

最后那行 --version 是 fail-fast 设计:二进制只要在当前架构上 跑不起来,镜像构建当场失败,不会把一个坏掉的浏览器带进产物。

启动器:直接裸跑二进制,绕开 CDP driver 层

# computer use 走 XTest + 截图,从不说 CDP ——
# 所以直接拉起 stealth 二进制本身:binary 层指纹补丁全程在线,
# 又因为绕过 Playwright/CDP 包装层,不会引入任何自动化痕迹。
exec /opt/cloakbrowser/chrome \
  --no-sandbox \
  --no-first-run \
  --disable-dev-shm-usage \
  --password-store=basic \
  --user-data-dir="${profile_dir}" \
  "$@"

这些都是容器内安全、且页面侧不可观测的 Chromium 参数 —— 它们不会破坏 binary 层的指纹隐身。每个会话用各自可写的 --user-data-dir,而预下载的二进制与缓存保持只读。

替换前后,一眼看清

跨架构:uname -m 自动选,别在错的架构上硬熬

CloakBrowser 为 Linux 同时提供一等公民的 x86_64 与 arm64 构建。 cloakbrowser 包在安装时按 uname -m 选对应二进制 —— 而那一步 RUN 是在目标平台的构建上下文里执行的。 所以 linux/amd64 构建(包括在 Apple Silicon 上用 buildx 模拟) 会拉 x86_64 版,linux/arm64 构建会拉 arm64 版,不需要手动判断。

验证状态与遗留项

如实记录当前进度 —— 替换代码已落地,端到端验证还在收尾。