Veil 完全指南：给 AI Agent 一双不会被网站识别的「真 Chrome」眼睛
你的 AI Agent 想访问 Instagram、Reddit 甚至 Google——然后被 Cloudflare 拦下来，被
navigator.webdriver=true标记，被行为检测模型识别为机器人。Veil 用真正的 Chrome 浏览器绕过这些检测，让 AI Agent 像真人一样浏览网页。
为什么 AI Agent 需要「隐身」浏览？
当你的 AI Agent（Claude Code、Codex、OpenCode）需要从网页获取信息时，通常会走两条路：
- HTTP 请求 + HTML 解析 — 简单但无法处理 JS 渲染、SPA（如 React/Vue）站点、Cloudflare 防护
- Playwright/Puppeteer — 可以渲染 JS，但暴露了明显的自动化特征
问题出在第二条路上。Playwright 和 Puppeteer 虽然好用，但它们有结构性的指纹缺陷——navigator.webdriver=true、--enable-automation 启动参数、HeadlessChrome 的 User-Agent 字符串。如果一个网站用了 Cloudflare、DataDome 或 Akamai，你的 Agent 在第一条请求就会被标记为自动化程序。
Veil 选择了一条不同的路：不发明新浏览器引擎，不模拟浏览器行为——直接用真正的 Chrome/Chromium，通过原始 CDP（Chrome DevTools Protocol）驱动它。免安装依赖、免防检测补丁、零额外依赖。
Veil vs Playwright/Puppeteer：关键差异
| 维度 | Playwright / Puppeteer | Veil |
|---|---|---|
| 可检测性 | navigator.webdriver=true, --enable-automation, Runtime.enable CDP 特征、HeadlessChrome UA | 擦除 webdriver 标记、无自动化开关、统一 UA + Client-Hints |
| 输入行为 | 瞬间点击、固定节拍键盘输入 → 行为检测直接暴露 | 贝塞尔曲线鼠标路径、变速按键节奏、模拟人类操作 |
| 选择器稳定性 | CSS/XPath 选择器随页面改版即断 | 无障碍树快照 → 稳定的整数 ref，Agent 不需要写任何选择器 |
| 安装依赖 | npm 包 + 浏览器二进制下载 + 系统依赖（libgtk、libnss 等） | 零运行时依赖，仅需 WebSocket（Node 24/Bun 原生）和本机 Chrome |
| 生态适配 | Python/Node 各一套，与 MCP 无原生集成 | 内置 MCP Server，任何 Agent 直接获得隐身浏览工具 |
Veil 的定位很清晰：不试图在隐身性上超过所有竞品（Camoufox 用 C++ 修改 Firefox，隐身性更强；Python 的 nodriver 也实现了原始 CDP），而是填补 TypeScript/Node 生态中的隐身浏览器空白——JS/TS Agent 生态（Vercel AI SDK、LangChain.js、MCP）一直缺乏一个强力的原始 CDP 驱动。
快速上手
安装
Veil 是 TypeScript 项目，使用 Bun 运行（Bun 是推荐的运行时，Node 24 也支持）：
git clone https://github.com/acunningham-ship-it/veilbrowser cd veilbrowser bun install
确保本机已安装 Chrome/Chromium 并在 PATH 中，或者设置环境变量：
export VEIL_CHROME=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
自测
Veil 提供了一个开箱即用的自测脚本，启动真实 Chrome 并执行完整的隐身链路检测：
bun run examples/selftest.ts
这个脚本会打开 Chrome，访问 bot.sannysoft.com 和 Cloudflare 的 JS Challenge 页面，验证所有检测项是否全绿通过。
在你的 Agent 中集成
import { Browser } from "veilbrowser";
const browser = await Browser.launch({ headless: false });
const page = await browser.newPage();
// 使用无障碍 ref 导航（Agent 不需要写选择器）
await page.goto("https://example.com");
const heading = await page.accessibilityTree();
console.log(heading);
await browser.close();
headless: false 模式下隐身性最强（真实窗口 + 真实 GPU 渲染），适合生产环境使用。
MCP 集成：一条命令让所有 Agent 获得隐身浏览能力
Veil 自带 MCP Server，安装后任何支持 MCP 协议的 Agent（Claude Code、Cline、Continue 等）都能直接使用隐身浏览工具：
bun run src/mcp-server.ts
然后在 Agent 的 MCP 配置中添加：
{
"mcpServers": {
"veil": {
"command": "bun",
"args": ["run", "src/mcp-server.ts"],
"env": {
"VEIL_CHROME": "/path/to/chrome"
}
}
}
}
配置完成后，Agent 可以通过 browser_navigate、browser_click、browser_extract_text 等工具调用隐身浏览器，所有操作都经过防检测处理。
核心架构：为什么「真 Chrome + 原始 CDP」才是正解
很多自动化工具（包括早期的 Selenium、现代的 Playwright）都尝试过用 CDP 驱动浏览器。但常见的实现方式在 CDP 调用级别就留下了漏洞：
--enable-automation启动参数会设置navigator.webdriver = trueRuntime.enableCDP 调用会被浏览器标记为自动化行为- Chrome 的
HeadlessChrome字样仍然出现在 UA 中
Veil 的处理方式：
- 启动参数净化：不让 Chrome 知道它在被驱动——去除
--enable-automation和--remote-debugging-port等暴露型参数 - CDP 调用过滤：不调用
Runtime.enable、Page.addScriptToEvaluateOnNewDocument等容易暴露的命令 - 输入行为仿真：所有鼠标操作走贝塞尔曲线路径（不是瞬间跳转到目标点），键盘操作模拟人类节拍
- UA + Client-Hints 统一：与正常 Chrome 的 User-Agent 完全一致，不附加任何版本后缀
适用场景
| 场景 | Veil 效果 |
|---|---|
| AI Agent 需要爬取 SPA 应用（React/Vue/Angular） | ✅ 真实渲染，JS 执行完全 |
| Agent 需要登录社交媒体（Twitter、Reddit、Instagram） | ✅ 通过反爬检测 |
| 获取 No-Code 平台（Airtable、Notion）的数据 | ✅ 完整渲染 + 交互 |
| 访问受 Cloudflare/CDN 保护的文档站点 | ✅ 通过 JS Challenge |
| 需要批量抓取电商/比价数据 | ✅ 真人行为轨迹 |
注意事项
- 需安装真实 Chrome/Chromium：不在 PATH 中时需设置
VEIL_CHROME环境变量 headless: false模式下隐身最佳：无头模式虽然节省资源，但更易被检测- 适用生态：Veil 目前是 TypeScript 项目，Node 24 或 Bun 运行。Python Agent 生态建议使用
nodriver或 Camoufox - 许可证：需查看仓库 LICENSE 确认商用限制
- Bun 依赖：推荐使用 Bun 运行时，Node 24 的全局
WebSocket也支持但未完全测试
总结
Veil 解决了一个很具体但很重要的痛点：AI Agent 不能被网站「一眼认出是机器人」。它不走插件/补丁路线，而是用真正 Chrome + 原始 CDP 的架构，从根本上消除可检测性。对于 TypeScript/Node 生态中的 Agent 开发者来说，这是目前最原生的隐身浏览器方案——尤其在你需要 Agent 登录社交媒体、访问受保护站点或渲染 SPA 内容时，值得一试。