vibatchium

vibatchium

为常开设备打造的浏览器层。 在真实 Chrome 上，同时运行多个已登录身份，无需人工值守，默认启用隐身功能，并提供安全模型，让 AI 能够安全地接触凭据。

一个守护进程、N 个持久 Chrome 会话、一个 vb CLI 和一个 MCP 服务。 可自托管、免费、Apache-2.0。

pipx install 'vibatchium[all]'
patchright install chrome
vb setup                     # register the MCP server + agent skill (Claude Code, Codex, Cursor)
vb explore https://example.com

适合你吗？

你的需求……	使用
Agent 操控你已登录的浏览器，同时由你监看	Claude in Chrome、Chrome Auto Browse——官方产品、免费、集成更好
隐身性最强的单个浏览器	CloakBrowser——在 Chromium 的 C++ 中修补指纹（并发使用需付费）
为单个 Agent 提供最精简的驱动程序	bladebro——五个工具，一个 Rust 二进制文件
不受反机器人限制的浏览器自动化	playwright-mcp、agent-browser——体量更大、历史更久、测试更充分
在一台设备上运行多个账户，无需人工值守，面向会对抗自动化的网站	vibatchium

最后一行就是它的核心优势。受监督的 Agent 每遇到登录墙和 CAPTCHA 都会把控制权交还给你；而库只提供基础能力，会话、预算、崩溃恢复、凭据等整个集群都要由你来构建。vibatchium 提供的正是这一集群层。

对比

截至 2026-10-06，信息来自各项目自己的 README、源码和发行说明 （MCP 成本一行是我们自行测量的¹）。特意列出了我们不如其他项目的项目。

	vibatchium	CloakBrowser	bladebro	agent-browser	playwright-mcp
同时运行 N 个持久的已登录会话	支持，免费，单个守护进程	1 个免费（最新版构建）· Pro 版支持更多	每个 Agent 会话对应一个 Chrome	支持，每个会话对应一个守护进程	每个配置文件目录对应一个
无人值守运维：崩溃自愈、租约、预算、空闲冻结、目标	全部支持	—	部分支持（崩溃后重新启动、空闲超时）	部分支持（空闲超时、恢复）	空闲超时
Agent 可以使用秘密，但不能读取（按来源填充、拒绝回读、TOTP）	支持	—	—	密钥库、来源检查	--secrets 脱敏
页面内容的提示词注入扫描	支持	—	—	边界标记（可选），不扫描	—
使用会话自身 Cookie 的无浏览器 HTTP、Chrome TLS 指纹 · 无需密钥的网页搜索	支持	—	—	—	—
浏览器	原版 Chrome	自有 Chromium 构建	原版 Chromium	默认使用 Chrome for Testing	原版 Chrome
隐身层	CDP 级（Patchright）	引擎级（87 个 C++ 补丁）	CDP 级（“6 层”），不使用 Runtime.enable	核心中不包含；通过云服务提供商实现	无
已公布的隐身评分	尚未	在其自有检测列表中得分 30/30	Stealth Bench V1 得分 68/80（自行运行）	—	—
在 Claude Code 中的 MCP 启动成本¹	~2.7k 个 token（87 个工具，始终加载 5 个）	不适用	~3.4k 个 token（5 个工具）	未测量	未测量
平台	Linux（macOS：CI 探测，不受支持）	Linux · macOS · Windows	Linux · macOS · Windows	全部	全部

_{¹ 按 stdio 测量，tools/list 的字节数/4 加上服务端指令。没有工具搜索功能的客户端会加载所有工具：vb mcp --caps min 包含 12 个工具，约 3.8k 个 token。bladebro 自己的 README 称约为 1.9k。}

其他项目确实更出色的方面： CloakBrowser 的引擎级补丁比任何 CDP 级方案都深入，而且 vb start --browser-binary 可以驱动你提供的 Chromium 构建。bladebro 有隐身基准测试分数，而我们还没有；在我们取得成绩之前，请将我们的隐身声明视为下文排行榜上的测量结果，而非生产环境中的实际表现。这两者都支持更多操作系统。

vibatchium 独有的功能

1. 在一台机器上运行一组已登录身份。 每个会话都有独立的 Chrome 和配置文件，以及独立的代理、时区和 GPU 节点；如果选择启用 vb persona set，还会有独立的屏幕和窗口，因为默认情况下，同一台机器上的所有无头会话都会报告相同的 800×600 屏幕。vb fleet-check 会测量各会话看起来有多相似。它们由一个负责维持会话运行的守护进程并行运行：渲染进程崩溃后会在同一配置文件中重新启动；闲置会话的渲染进程会停止，并在下次调用时恢复；租约可避免两个 Agent 同时干扰同一会话；目标则会为任务设定步骤数、花费和时间预算，即使守护进程重启也能保留。

vb --session alice start && vb --session alice go https://x.com      # log in once, stays logged in
vb --session bob   start && vb --session bob   go https://x.com
vb --session alice act "open notifications" & vb --session bob extract & wait
vb fleet-check --sessions alice,bob                                  # how twinned are they?

2. Agent 可以使用、但永远看不到的凭据。 保管库会将密码或实时 TOTP 验证码填入网页，且不会让其值进入模型上下文、屏幕截图或日志，并且只会填入对应的网站。通过 MCP，受到提示词注入的 Agent 无法把你的 GitHub 密码输入仿冒页面，也无法在密码仍留在字段中时通过 value 或 eval 读回密码，更无法编辑保管库或获取验证码。拥有 shell 的 Agent 就是操作者——CLI 有意提供了绕过限制的途径——因此，如果这条边界对你很重要，请给 Agent 使用 MCP，而不是 Bash。

printf %s "$GH_PASSWORD" | vb secret set github.com password --stdin
printf %s "$GH_TOTP_SEED" | vb secret set github.com totp-seed --stdin
vb --session work fill @e7 --use-secret github.com:password
vb --session work fill @e9 --use-secret github.com:totp
vb wait-email-code github.com      # operator CLI: polls IMAP and prints the code; refused over MCP

3. 将网页文本视为不可信内容。 每个会话都会扫描返回的网页文本，检查其中面向 Agent 的指令，并默认将其标记出来；wrap 会将这些指令隔离，redact 会将其移除。调用方提供的文件路径也会受到限制，因此受到注入的 Agent 无法上传 ~/.ssh 或写入 .git/hooks。

4. 同一身份下的无浏览器通道。 vb fetch 会复用会话的 Cookie 和代理，并使用 Chrome 的 TLS 指纹和客户端提示——以 curl 的速度访问登录后才能访问的 JSON 端点，并在无法匹配浏览器时告知你。vb search 无需 API 密钥，也不占用每个会话的预算，即可查找 URL。

vb --session work fetch https://api.example.com/v1/me
vb search "site reliability postmortem" -n 20 --urls

状态： alpha，积极开发中。CI 中有 2,027 项测试通过（Linux，Python 3.11–3.14）。编码 Agent：请先阅读 AGENTS.md——其中包含值得一读的一调用方案，以及值得避开的陷阱。

_{下方引用的检测器评分（bot.sannysoft、CreepJS、Cloudflare 冷启动）是人工观察结果，并非 CI 断言——测试套件中没有任何测试以这些评分作为门槛，而且这些结果仅反映最近一次人工运行的情况。请以 实测评分 下方的生成内容为准。}

安装

pipx install vibatchium             # core: browse / extract / screenshot / N parallel sessions
pipx install 'vibatchium[all]'      # + fetch/search lanes, credential vault, VLM read, REST shim
                                    #   (or pick extras: [fetch], [secrets], [llm], [rest])
patchright install chrome
vb setup                            # register MCP + an auto-discoverable skill (idempotent)
vb install                          # report which optional lanes are available

在 uv 虚拟环境中（不使用 pip），通过 uv pip install --python <venv>/bin/python curl_cffi 添加额外依赖。从 master 获取最新开发版本：pipx install 'git+https://github.com/trueoriginlabs/vibatchium#egg=vibatchium[all]'。

安装为技能 / 插件

vb setup 会为这台机器上的 Agent 完成配置。要将 Agent 技能单独安装到任何受 skills.sh 支持的 Agent（Claude Code、Codex、Cursor、Gemini CLI、Copilot，……），或将技能和 MCP 服务作为一个 Claude Code 插件安装：

npx skills add trueoriginlabs/vibatchium                  # skill only, any agent

/plugin marketplace add trueoriginlabs/vibatchium         # Claude Code: skill + `vb mcp`
/plugin install vibatchium@vibatchium

两种方式都仍需要在 PATH 上安装 vb CLI（pipx install 'vibatchium[all]'）——技能会调用它，而插件的 MCP 服务就是 vb mcp。在 Claude Code 中，请选择插件或vb setup，不要两者都用，否则会重复注册服务。技能文件由 vibatchium/setup_cmd.py 生成；请在此处编辑，然后运行 python scripts/sync_skill.py。

快速开始

vb explore https://example.com                      # one call: text-first, auto-closes
vb research --target https://example.com \          # parallel fan-out, N intents
  --intent "pricing model" --intent "customers" --intent "tech stack"

真实 Chrome 与仿冒 Chrome

一波面向 AI Agent 的“无头浏览器”工具从头重建浏览器 （Rust + V8，没有 Blink/Skia），以实现极低的内存占用和不到 100 毫秒的页面加载速度。问题 在于其结构本身：**没有渲染引擎，就无法生成真实设备的 指纹——只能合成指纹。**而合成指纹并不稳定。

vibatchium 驱动的是真正的 Google Chrome，因此它的指纹是真实的——更 重要的是，稳定。区分两者的唯一测试，是检查跨页面导航的指纹稳定性。在同一会话中， 对两个页面运行相同的 canvas + WebGL 探测：

	vibatchium（真实 Chrome）	合成指纹引擎
canvas 哈希，页面 A → 页面 B	相同	每次导航都会重新生成
WebGL readPixels	真实、确定性像素	通常使用 Math.random()
WebGL 渲染器	真实的 ANGLE 渲染器¹	存根 / 零值

_{¹ Chrome 默认使用自己的软件渲染器（SwiftShader）——仍然是连贯、确定性的 Chrome 值，而不是存根。要使用硬件 GPU 字符串（例如 ANGLE (Intel …)），需要启用 --gpu 标志。}

真实设备每次加载页面都会返回相同的指纹；基于 Date.now() 的指纹则不会——而这种不一致正是 CreepJS 等测谎指纹工具会标记的内容。实测：vibatchium 的 canvas 哈希和 WebGL 读取结果在不同导航间逐字节完全相同；上次手动运行时，CreepJS 报告的隐匿篡改率为 0 % （未检测到合成环境特征）。该数值未经回归测试——应视为观察结果，而非保证。

**这并不代表隐身。**我们的优势在于指纹的真实性， 而不是隐藏浏览器正处于自动化状态——在无头浏览器特有的检测项上，vibatchium 仍会显示为无头浏览器（请参阅诚实说明），而真实 GPU WebGL （--gpu）需要选择启用。但真实且一致的指纹能够通过合成指纹注定无法通过的一致性检测——而这道检测正是 你与登录墙之间的屏障。

10 行代码实现多会话

vb session new work
vb --session work start
vb --session work go https://github.com           # log in by hand once
vb session new banking
vb --session banking start
vb --session banking go https://bank.example.com
vb --session work click @e3 &                     # truly parallel —
vb --session banking fill @e5 hi &                # separate Chromes, no cookie bleed
wait
vb session list

活动会话解析顺序：--session FLAG → $VIBATCHIUM_SESSION 环境变量 → ~/.config/vibatchium/active-session → default。通过 VIBATCHIUM_MAX_SESSIONS=8 设置上限（默认值为 8）。

多 Agent：共享会话还是私有守护进程

在一个共享守护进程上，会话的状态彼此隔离（使用不同的 Chrome 和配置文件，不会串用 Cookie），但指纹不会自动隔离——在同一台机器上，它们报告的屏幕相同；如果没有 --gpu --node，软件 GPU 也相同，除非你设置了 vb persona；vb fleet-check 可测量这一点。它们还共享主机资源：会话数量预算、内存，以及 OOM 或守护进程重启的影响范围。根据信任级别，可选择两种模式：

• 协作型 Agent（你自己的集群）：共享守护进程是合适的——只需为每个并发 Agent 指定唯一的 --session 名称，避免有状态的工作流都使用 default 而发生冲突。vb session lease 可协调共享名称。
• 独立的影响范围：为每个 Agent 启动一个使用专属套接字和 HOME 的独立守护进程——配置文件、配置和状态彼此隔离，各自拥有会话预算，与共享守护进程完全隔离。vb daemon start --isolated 会打印后续调用要导出的 XDG_RUNTIME_DIR/HOME；vb mcp --isolated 会直接在独立的私有守护进程上运行 MCP 服务。vb daemon reap 可清理已遗弃的守护进程。（相同 UID = 相同信任域——这限制的是影响范围，而非不可信租户之间的安全边界；要实现后者，请使用不同的 UID/容器。）

资源管理。会话上限限制的是进程数量，而非字节数。在共享主机上，设置 VIBATCHIUM_SESSION_RAM_FLOOR_MB，可在可用内存不足时拒绝启动新会话（提供一种可移植的准入保护）。如需硬性上限，可在 cgroup 下运行守护进程——systemd-run --user --scope -p MemoryMax=4G vb daemon start 会将守护进程及其所有 Chrome放入同一个 cgroup，共享内存限制：这是守护进程级别的总量上限（而非每个渲染器的上限）；超限时会在该作用域内触发 OOM 杀进程，守护进程也可能被杀。这是唯一不会产生竞争条件的内存上限，因此设置时要考虑整个扇出规模。

**空闲 CPU。**暂停的会话也不会持续占用 CPU 核心：守护进程会在已启动会话的渲染器进程没有执行任何动词达到 VIBATCHIUM_IDLE_FREEZE_AFTER 秒后发送 SIGSTOP（默认 90 秒），并在下次调用时恢复它们；这样，空闲的 WebGL/动画页面无需拆除即可将 CPU 使用率降至零（默认启用；设置 VIBATCHIUM_IDLE_FREEZE=0 可禁用）。

冻结而非关闭是有意为之的权衡，利弊兼有。playwright-mcp 的 --idle-timeout（v0.0.81，headless 模式默认 1 h）会关闭空闲浏览器：这样可以释放内存，持久化配置文件会保留 Cookie，但已打开的标签页和页面内状态都会丢失，下次调用还要重新冷启动。冻结的会话会保留驻留内存，并在下次执行动词时恢复，保留其标签页、页面状态和登录信息——这正是流程进行到一半时，长时间保持登录状态的会话所需要的行为。内存上限由上述另外两项措施——RAM 下限和 cgroup——控制，而非通过拆除会话来控制。

隐身等级——各等级能通过哪些检测

隐身能力是一个等级梯度，而不是非此即彼。选择能通过目标检测的最低等级 （更高等级需要更多设置／可见浏览器／手动登录）。vibatchium 不声称能在冷启动时突破行为检测屏障——这需要由真人操作的会话，而连接模式才是诚实的选择。

架构注意事项。 以下各等级均在 x86-64 Linux 上测量。 Patchright 已知存在尚未解决的 arm64 / Apple Silicon 检测差距，因此不应假定这些 结果适用于 ARM 主机。如果在 ARM 主机上运行，请先测量，再依赖这些结果。

等级	方式	可通过	无法通过
标准（默认）	无头冷启动，使用真实的 channel=chrome，移除 Headless 标识的 UA	Cloudflare IUAM / 托管式质询、bot.sannysoft 31/31、JS 运行时指纹检测	严格的 Turnstile、DataDome/Kasada、任何需要登录才能访问的内容
强化	重试 --headed；vb humanize on + humanize ambient on（操作之间添加指针活动）；vb persona set（为每个身份设置屏幕）；使用 --backend nodriver（pip install vibatchium[nodriver]，AGPL）应对最严格的 Cloudflare 检测	严格的 Cloudflare/Turnstile、无头模式会暴露的 GPU/屏幕特征	行为生物识别、DataDome/Kasada 传感器融合检测
连接	使用 vb attach 连接到由你启动并已登录的 Chrome	DataDome / Kasada / HUMAN 行为检测屏障，以及任何已认证会话——你的真实指纹 + Cookie	此处没有自动化冷启动；需要先由真人登录

测得分数

vb evals run --update-readme 会将测得的数据写入下方代码块，因此 我们发布的内容是实际生成的，而非主观声称。有人运行之前，这里会保持空白——空白是诚实的；没有运行记录却给出数字，则不诚实。

在 x86-64 Linux 上运行，2026 年 8 月 25 日，Chrome 150，使用 --gpu（真实渲染节点）。 请自行传入 --gpu：如果 GPU 路径不可用，无头 Chrome 会回退到 SwiftShader，而软件 GL 本身就是检测信号，因此不使用它测得的数据只是下限，不能代表启用 GPU 的部署环境。

目标	后端	人性化	GPU	分数	状态	耗时
sannysoft	patchright	off	real	100	OK	17.78s
creepjs	patchright	off	real	44	OK	7.88s
brotector	patchright	off	real	10	OK	7.13s
sannysoft	nodriver	off	real	100	OK	19.85s
creepjs	nodriver	off	real	44	OK	9.72s
brotector	nodriver	off	real	10	OK	7.73s

请如实看待这些结果——三项中有两项表现不佳。

• sannysoft 100 是此类别中的所有方案都能达到的下限；它不构成差异化优势。

• creepjs 44 表现平平。CreepJS 是一种对抗性的谎言检测器：它会交叉核对主线程与工作线程的声明，并评估可信度，因此中等分数意味着我们的环境一致，但并非无法区分。

• brotector 10 表现糟糕，而且我们完全清楚原因。触发的信号是 UA_Override / HighEntropyValues.empty，而这正是我们自己的移除 Headless 标识修复导致的。 在 Chrome 150 上测得，使用无头模式、同一配置文件，分别在启用和未启用我们设置的 --user-agent 标志（用于移除 HeadlessChrome）时进行对比：

  	architecture	bitness	uaFullVersion	UA 字符串
  未启用该标志	x86	64	150.0.7871.114	包含 HeadlessChrome
  启用该标志	空	空	空	显示 Chrome
  传入显式 UA 会让 Chrome 停止推导高熵客户端提示，因此我们用 UA 字符串特征换来了 UA-CH 为空这一特征。这并非无法修复：显而易见的修复方法（通过 Emulation.setUserAgentOverride 设置 userAgentMetadata）是针对目标的，会重新引入主线程与工作线程不一致的问题，这比任一单独泄露都更明显。公开这一点而不是移除该目标，正是我们的用意——只报告胜利的测试套件不过是营销。

• nodriver 在这三项上的得分与 patchright 完全相同。 在静态评分榜上，升级层级毫无可衡量的收益；它的价值在于这些目标未测试的自动化协议维度。先前一次运行中，nodriver 在 creepjs 上略微领先（50 对 44）——但那次运行悄悄禁止它使用 GPU，却给 patchright 配了真正的 GPU，所以它是在劣势下评分的。两边都使用真正的渲染器后，差异便消失了。在选择这一层级前，值得了解的是：上游自 nodriver 0.50.3（2026-05-13） 起就没有发布过新版本，因此 >=0.50.0,<1.0 这一版本范围现在解析到的版本已经有好几个月了。这个层级仍然可用，但已不再发展。

这些测试涵盖什么，又不涵盖什么。 这些是指纹评分榜——衡量静态维度。到 2026 年，各大反机器人厂商已转向按会话生命周期进行行为评分，而这些目标都不会衡量该维度；我们也尚未针对任何商业厂商进行衡量。请将这里的好成绩仅视为环境一致性的证据。

对于行为维度本身，vb oracle run 是一项可自托管的探测：它会先后关闭和开启 humanize，驱动页面并依据符合人类特征的范围评估轨迹曲率、停留时间、击键节奏和滚动动态（vb oracle record 会采集真实操作员的基线；在你完成采集前，使用文献中的默认值）。它衡量的是我们自己的人类行为模型，而非某个指定厂商的模型——但它能将“我们会模拟人类行为”转化为可衡量的开关前后差异，并如实说明合成输入无法触及的那个维度：CDP 输入不会发出原始指针事件或合并事件，只有针对真实硬件的附加模式才能弥补这一点。

触发拦截时的升级阶梯：无头模式 → --headed → 开启 humanize → --backend nodriver → 手动登录后使用附加模式。 Patchright 的 CDP 层补丁适用于所有层级，包括附加模式（connect_over_cdp）。

fetch 动词是独立的快速通道，不属于某个层级：在浏览器中通过拦截后，vb fetch 会复用该会话的 cookie 和代理，以符合 TLS 指纹的速度访问 JSON/API 端点——但它不会运行 JS，因此无法自行解除 JS 挑战。

捕获 — 以 2× 分辨率截取必须点击才能到达的状态

vb --session shots start --scale 2          # devicePixelRatio 2 (1–4, persisted; --scale 1 clears)
vb --session shots go https://example.com
vb --session shots click @e3                # open the modal…
vb --session shots screenshot -o card.png   # …then capture it at 2560×1600
                                            # (2× the 1280×800 pin; vb viewport W H to resize)

默认会话每个 CSS 像素只捕获一个图像像素，因此为 Retina 资源准备的裁剪图，分辨率只有所需的一半。chrome --force-device-scale-factor=2 --screenshot 能忠实还原，但无法点击，所以永远无法捕获模态框、悬停状态或已登录视图。--scale 两者兼顾。

这是一种捕获模式，而非浏览模式。 Chromium 只会在创建上下文时设置 deviceScaleFactor，而 Playwright 拒绝让它与 no_viewport 同时使用，因此缩放会话会固定视口并模拟设备指标——screen == viewport，start 也会通过 screen_coherent: false 说明这一点。不要让缩放会话去访问 Cloudflare/DataDome 拦截页；用普通会话浏览，再用单独的会话进行缩放截图。仅支持冷启动（在运行中的会话上会显示 scale_pending），仅支持 Patchright（在 nodriver 上会显示 scale_ignored），而 max_screenshot_px 以设备像素为单位——缩放到 2× 时，较长页面会在一半的 CSS 高度处截断。详情请参阅 AGENTS.md 中的 Retina / 2× captures。

搜索 — 找到 URL，而不只是读取页面

读取被封锁的网页只是研究流程的一半；另一半是发现内容，而搜索引擎也和其他服务一样会封锁机器人。vb search 通过同一条 curl_cffi 通道执行 SERP 搜索 — 无需浏览器、会话或 API 密钥，也没有每个会话的调用次数上限，不必担心运行中途耗尽。

vb search "playwright stealth detection" -n 5
vb search "cdp leak" --site github.com -n 20
vb search "postmortem" --urls | xargs -I{} vb fetch --no-cookies {}

搜索引擎会按梯队尝试（ddg → ddg-lite → bing），直到有一个返回结果，因为可访问性会变化：此刻提供结果的端点，下次调用时可能就会触发速率限制（HTTP 202）。--json 会返回一个 attempts 数组，列出每个拒绝请求的引擎及原因，并通过 reason 区分所有引擎都被封锁和网上没有相关内容 — 这是不同的问题，需要不同的解决方法；只有第一种情况会导致 CLI 以非零状态码退出。

它绝不会复用会话 Cookie（SERP 无需登录，而且附带 Cookie 会暴露请求者身份），因此它有独立的 search 上限，而不会占用 fetch 的额度。我们有意不提供日期筛选：DuckDuckGo 经常错误标注文章日期，足以扰乱时间线。引擎会按 IP 限制请求速率 — 见下文的代理部分。

代理 — 两条隐匿通道均支持按请求设置出口

出口是大多数人最容易弄错的方面，因此这里明确说明，而非含糊带过。两条 curl_cffi 通道都接受 --proxy scheme://[user:pass@]host:port：

vb fetch --no-cookies https://api.example/v1 --proxy http://user:pass@gw:12323
vb search "site reliability postmortem" -n 20 --proxy http://user:pass@gw:12323
vb --session work proxy set http://user:pass@gw:12323    # or per-session, for the browser

这是实测结果，而非推测 — 同一台机器、同一条命令，仅 --proxy 不同：

	出口 IP
直连	115.70.50.70
--proxy（经过身份验证的网关）	212.69.0.85

以下四点值得了解：

• 未设置表示直连，而且系统会强制执行。 守护进程会向 libcurl 传入显式的空代理，这是唯一能阻止它读取启动时继承的环境变量中的 HTTP(S)_PROXY / ALL_PROXY 的值。长期运行的守护进程会继承最初启动它的 shell 环境，因此如果没有这项设置，意外残留的 HTTPS_PROXY 就会悄悄重定向每个请求，而响应却声称使用直连出口。（在 0.19.0 之前确实如此 — 见更新日志。）
• 这对 search 尤其重要。 引擎会按 IP 限制请求速率，因此从一个地址发出大量并行研究请求，是让所有查询都落到引擎梯队最后一档的最快方式。响应会报告 proxied: true|false，让你判断结果稀少时使用的是哪个 IP。
• 代理地址和目标 URL 一样受 SSRF 防护， 可通过 --allow-internal 允许使用自己局域网内的代理。未受防护的代理可以访问内部服务，并返回其响应正文，而不只是连接错误。
• 代理不可用时会报错，绝不会回退。 当你指定了特定 IP 时，悄悄改用主机 IP 出口比直接失败更糟，因为指定代理的核心目的就是不能使用主机 IP。代理 URL 会在动词日志中隐藏；响应只包含布尔值，不会包含 URL。

使用浏览器会话时，vb proxy set 还会启用 WebRTC 泄漏防护 — 否则，即使 HTTP 请求通过隧道传输，STUN 仍会泄漏真实 IP。

附加模式 — 实用的 Cloudflare 绕过方案

适用于会封锁冷启动自动化的 DataDome / Kasada / 加固型身份验证：

google-chrome --remote-debugging-port=9222 \
              --disable-blink-features=AutomationControlled \
              --user-data-dir=/tmp/cdp-profile &
# log into the walled site by hand
vb attach http://localhost:9222
vb go https://target.example.com        # now reads as your real browser

通过 connect_over_cdp 连接时，Patchright 在 CDP 层的隐匿处理仍然有效 — 附加模式拥有与冷启动相同的协议级补丁，还具备你真实浏览器的指纹以及手动登录留下的 Cookie。

此模式下由你负责启动参数。 冷启动时，后端会为你提供 --disable-blink-features=AutomationControlled。附加模式连接的是 已经运行的 Chrome，因此 vibatchium 无法事后添加启动参数 — 如果启动 Chrome 时没有加上该参数，这个暴露自动化痕迹的信号就会在整个会话中存在。请将其加入上方的命令中。

--remote-debugging-port 是一扇敞开的门。 它允许机器上的任何进程完全控制浏览器，而且你访问的网页可以探测 localhost 来发现它。请仅在你信任的机器上使用，并在完成后关闭 Chrome。

安全模型

vibatchium 专为在不受信任的 Agent 循环中驱动真实登录而构建，因此 威胁模型是“凭据绝不能传到模型、截图或日志中”：

• 加密保险库。 密码和 TOTP 密钥存储在 XSalsa20-Poly1305 保险库中，密钥取自 OS 密钥环或 VIBATCHIUM_SECRETS_KEY。解析后的密钥 绝不会出现在日志、HAR 捕获内容、观察缓存或任何 Agent 可见的 响应字段中（已在 CI 中通过 grep 测试）。
• 密钥绝不会以明文形式渲染。 fill --use-secret 会在页面中遮蔽字段 （使用 -webkit-text-security），并在写入值之前应用遮蔽，因此所有将视口 转换为字节的途径——screenshot 动词、每秒 5 帧的 实时视图流，以及将帧发送给模型的 VLM vision_* 调用—— 捕获到的都是圆点，而不是密钥。遮蔽机制默认拒绝写入（无法确认时不写入）， 会覆盖密码字段，防止“显示密码”切换操作解除遮蔽；并且 map / diff_map 返回的 无障碍快照会剔除已遮蔽的值，因此密钥也无法以文本形式泄露到模型的上下文中。
• 密钥与来源绑定。 fill --use-secret github.com:password 只会将值写入该站点上的文档——使用 https、 github.com 或其子域名，并根据拥有该字段的框架判定（因此 iframe 无法借用顶层页面的来源）—— 或写入条目明确列出的 origins。其他任何位置都会在解析密钥之前拒绝操作， 以防受到提示词注入的 Agent 将你的密码输入到仿冒页面中。框架内的登录页面、about:blank 框架 以及 Agent 已运行过 eval 的页面也会被拒绝；密钥处于字段中时，会拒绝 value / eval，防止密钥被读回；写入时使用字段自身的值设置器，而非聚焦
  • 键盘输入，因此页面脚本无法重定向写入。如果字段在填入过程中被替换，系统会清空该字段并使调用 失败。绕过限制的选项（--allow-cross-origin、两个守护进程环境变量）仅限 shell 使用；MCP 会拒绝这些选项，也会拒绝修改保险库和执行 secret totp。
• 实时视图经过身份验证。 WebSocket 需要每个服务专属的令牌，并会拒绝来自外部 Origin 的 连接（CSWSH 类型攻击）；而驱动页面所需的令牌与仅供观看的令牌不同——可分享只读链接，而无需交出 键盘控制权。默认绑定到 127.0.0.1（可使用 --insecure-public 覆盖）。
• 抓取的内容会标记为不可信。 返回页面文本的 MCP 动词会带有 openWorldHint，以便宿主将输出标记为可能包含提示词注入，而不是将抓取的页面视为指令；纯探测操作带有 readOnlyHint， 而修改数据的动词（stop、secret_delete、storage_restore）带有 destructiveHint。
• REST 适配层。 如果不传入 --caps，持有令牌即可调用所有动词，包括 eval、secret_* 和写入文件的动词——其权限相当于本地代码，因此托管模式下务必传入 --caps=...。所有由 vibatchium 写入的文件权限均为 0600； 目录权限为 0700。

诚实的限制

• 5 个以上并发会话 = 1-2GB RAM。 每个持久上下文 Chrome 约占用 200-400MB。使用 VIBATCHIUM_MAX_SESSIONS=8 提高上限。

• 视觉预算上限是进程级的。 N 个扇出 Agent 共用一个每日／终身预算。

• 初始化脚本在 patchright 后端上不起作用。 chrome.runtime 会保持 undefined——这是为隐身效果作出的权衡。

• 登录墙（X、LinkedIn）需要 attach 模式。 冷启动扇出无法绕过要求已认证会话的网站。

• 合成输入具有 CDP 坐标特征。 每次 click／type／hover／scroll 都通过 CDP Input.dispatchMouseEvent／dispatchKeyEvent 由 Playwright 发送（pageX==screenX，没有 CoalescedEvents）。Patchright 修补的是 JS 上下文泄漏，而不是 Input 域；humanize on 能改善轨迹和时间上的逼真度，但不会改变每个事件的特征。会对其进行指纹识别的行为检测墙（DataDome／Kasada／HUMAN）要求针对由你操控的真实有头 Chrome 使用 attach 模式——OS 级合成输入（CDP-Patches）仅适用于有头且活动的标签页，不适合无头、N 路并行的守护进程。

• fetch 是静态指纹通道，不是浏览器。 curl_cffi fetch 动词与 Chrome 的 JA3／HTTP2 匹配，但不运行 JavaScript——它能通过 TLS 指纹检测，不会通过 DataDome／Kasada／Turnstile JS 挑战。遇到这些情况时，改用 go。

• 单守护进程 = 单点故障。 内置功能不提供高可用。

• 行为检测如今会直接针对人性化处理。 Cloudflare 2026 年的机器人检测工作指出，数学上过于理想的贝塞尔光标轨迹和超人般精准的点击都是破绽。humanize 比完全不做人性化处理要好，但它是指针轨迹模型，而非生理模型——而且默认关闭；对于按行为评分的网站，这两种状态中更容易引起注意的是关闭状态。

• 一个被标记的配置文件可能污染所有共用它的账户。 供应商如今会跨会话和账户关联设备遥测数据。每个账户使用一个配置文件，绝不要让不同身份共用配置文件，也不要重复使用已经受到质询的配置文件。

• fetch 和 search 通道不受提示注入扫描覆盖。 扫描器覆盖页面内容动词（text、html、extract、map 等）。SERP 标题和抓取的正文是直接进入 Agent 上下文的第三方文本，当前不会经过扫描。请将其视为不可信输入。

• Cloudflare 于 2026-09-15 启用的默认设置属于策略，而非检测。 对于新域名和免费套餐区域，Cloudflare 现在默认会在广告变现页面上屏蔽 Training 和 Agent 爬虫。它针对的是主动声明自身身份的爬虫（通过 user-agent 或 Web Bot Auth 签名），因此不会改变真实 Chrome 会话的表现——但上文提到的指纹和行为评分是另一条独立维度，不受博客文章公告内容的影响。

更新

vb update                  # upgrade + bounce the daemon + refresh the agent skill
vb update --version 0.19.0   # or pin a specific version

vb update 会检测 vibatchium 的安装方式（pipx、uv tool install、不依赖 pip 的 uv 虚拟环境，或使用 PEP-668 --break-system-packages 回退方式的 pip），停止正在运行的守护进程，以便下次调用时加载新代码，并重写 Agent 技能／文档区块，确保编码 Agent 知道新版本提供的动词（可通过 --no-restart／--no-setup 选择退出）。手动操作等效命令：

pipx upgrade vibatchium    # or: uv tool upgrade vibatchium / pip install -U vibatchium
vb shutdown                # bounce the daemon — it serves old code until you do
vb setup                   # refresh the agent skill + docs
vb --version               # confirm

守护进程重启这一步最容易被遗漏：长时间运行的守护进程会持续提供旧版本服务，直到它重启。vb update 会替你完成这一步；如果你手动升级，请运行 vb shutdown（下次调用 vb 时会自动重新启动新版本）。可选功能可通过 pipx install 'vibatchium[all]' --force 升级。

从 git 检出版本运行

git pull 会更新源代码；它是否会更新 vb 实际运行的内容， 取决于安装方式，而且三种可能失败的方式中有两种不会发出提示：

vb --version && git describe --tags   # do they agree? if not, the install COPIED
                                      # the source — reinstall editable:
                                      #   uv pip install -e '.[all]'
vb status                             # warns when the daemon predates the source
                                      # ("stale_code") — bounce with `vb shutdown`

比较版本字符串无法检测检出版本：git pull 会更改代码，但不会更改 __version__。vb status 会改为比较守护进程的启动时间与最新源文件的时间，而 vb update 只有在能确定守护进程落后时才会重启它，因此不会无故中断正在运行的会话。

新增能力分组需要重新注册

MCP 服务的 --caps 列表会在首次注册时固定到 Agent 的配置中，因此后续版本新增的分组（0.19.0 新增了 search）会一直不可见，无论升级多少次。重新运行 vb setup 会报告配置差异，但不会覆盖你手动设置的 --caps：

vb setup                              # reports any cap drift, changes nothing
vb setup --force --caps lean,search   # apply it — exposes `vb search` as a tool

之后重启 Agent 会话：MCP 工具列表只会在启动时读取一次。

服务模式

模式	接口	身份验证
vb mcp	stdio JSON-RPC；默认使用精简的 87 个动词配置（--caps min = 面向不支持工具搜索的客户端的 12 个工具；--caps=full/all = 163 个；--caps=... 用于自定义分组集合）	不适用（stdio）
vb serve	运行于 127.0.0.1:8000 的 FastAPI；每个动词均可通过 POST /v1/<verb> 调用；WebSocket 实时视图位于 /v1/stream/<session>	Bearer 令牌（~/.cache/vibatchium/rest-token，权限模式 0600）

REST 能力限制：vb serve --caps=core,nav,input,vision 会像 mcp --caps 一样限制 HTTP 接口。若不设置此项，REST 将授予与本地代码等同的访问权限（暴露 eval、secret_* 和所有写文件动词）——适用于本地主机开发，不适用于托管环境／多租户场景。

文档

• AGENTS.md — 编码 Agent 规范（Codex / Cursor / Claude Code）

授权使用

vibatchium 专为驱动你拥有的会话而构建，使用你的凭据，在你的机器上运行——无论是你的账户、雇主的账户，还是获得书面许可的客户账户。它用于自动化你已经拥有的访问权限。

不过，这条界限并非形式问题，尽管相关法律在 2026 年有所变化。一家美国联邦地区法院曾对某 AI Agent 发布初步禁令，该 Agent 通过用户本人已登录的账户访问了受密码保护的页面；法院认为，用户的许可不等于平台的授权。2026 年 8 月 4 日，第九巡回上诉法院撤销了该禁令并发回重审（Amazon.com Services, LLC v. Perplexity AI, Inc.，第 26-1444 号，已公布），认定运营方并未依据 CFAA「访问」原告的计算机——「访问这些计算机的是用户，[AI Agent] 只是提供了帮助。」加州 CDAFA 诉求也基于同样理由未能成立。

应当谨慎解读这一裁决。它判定的是谁访问了计算机，而不是规避技术封锁是否构成「未经授权」的访问；合议庭并未审理规避行为。发回重审后撤销初步禁令并非实体判决，也完全没有涉及合同、服务条款、侵入或版权方面的主张。该裁决所支持的是这款工具的设计理念：浏览器在你的机器上、使用你的登录凭据运行，而裁决理由恰恰依赖这一点——运营方的计算机从未接触对方的服务器。

抓取网站的公开页面、规避你没有账户可登录的网站屏障，或自动化违反账户条款的操作，仍然是由你做出的决定，后果也由你承担。

请查看你要自动化的网站条款。如果你是代表他人行事，请取得书面许可。

许可证

核心部分采用 Apache-2.0 许可证。默认安装包含的所有额外组件也都采用宽松许可证——fetch 通道中的 curl_cffi 采用 MIT 许可证。唯一的 copyleft 选项是可选的 nodriver 后端（AGPL-3.0）；用于商业集成前请先咨询许可证相关事宜。基础安装或 [all] 中均不包含 GPL/AGPL 代码。