🤖 Wbrowser

你的 AI 看不到登录背后的任何东西。这个工具解决了这个问题——在你真正使用的操作系统上。

你的助手可以搜索网页，但无法打开你的收件箱、你的仪表盘，或你公司的内部工具。一切有价值的东西都在它没有的登录凭据后面。

Wbrowser 在你自己的 Chrome 里为它留了一个座位——也就是你已经登录的那个 Chrome。同一个窗口，同样的标签页。你可以看到每一次点击落下，也能在任务进行中随时取回鼠标。

你的密码永远不会离开你。 你手动登录；Chrome 负责保存；Wbrowser 只是驱动那个已经打开的窗口。

支持 Windows、macOS、Linux 和 WSL——每个平台都在真实硬件上、由编写对应部分之外的人、在不同机器上实测过：

测量于 2026-08-24。并非每项检查都在所有平台运行——详见平台说明。

大约 2,600 行 JavaScript、Python 和 shell 代码。MIT 协议。小到足够你用一下午读完并改成适合自己的样子。

English · 한국어 · 中文 · Español

为什么会有这个项目

AI 浏览器全都采用同一种形态：你要安装一个全新的浏览器，里面嵌着一个助手——Aside、Comet、Dia。这种形态会让你付出三样代价：

我们选择了相反的方案。 不需要新浏览器——还是你现有的 Chrome、你现有的登录凭据，而且助手就在你正在看的那个窗口里工作。你看着每一次点击落下，还能在任务中途把鼠标接回来。没有什么要迁移的，没有什么要交出去的。

这个选择也是它能同时跑在 Windows、macOS、Linux 和 WSL 上的原因：我们不需要为每个平台各自做一个浏览器，所以也就不存在要选哪个平台的问题。

需要什么？那就自己造一个。

这就是全部理念：不是等着别人路线图的产品，而是一个属于你自己的小工具，跑在你已经在用的机器上，在你已经登录的浏览器里。大约 2,600 行 JavaScript、Python 和 shell——小到一下午就能读完。读它、改它、让它变成你的。

Wbrowser 面向 Windows、macOS、Linux 和 WSL——因为“你用的是哪个系统？”永远不应该成为你不能自动化自己浏览器的理由。在 macOS、原生 Linux、WSL2 和 Windows 原生环境下都有实测——不过并非每项检查都在每个平台上运行（见平台说明）。

Related MCP server: Chrome DevTools MCP

这是什么？

大多数自动化工具给你的是 一个全新、空白的 浏览器。所以它看不到你的邮件、你的仪表盘，或者任何需要登录才能看到的内容——除非你把密码交出去，或者为每个服务都配置一遍 API 集成。

Wbrowser 选择了相反的路径：手动登录一次，用一个普通的 Chrome 窗口。 之后你的终端（或者你的 AI 助手）就能驱动这个窗口——处处都已经登录好了。

./wb go https://mail.example.com   # opens in YOUR logged-in session
./wb read                          # tells you what's on screen
./wb click '#compose'              # clicks it

Wbrowser 永远不会看到你的密码。 密码由你输入；Chrome 保管；Wbrowser 只是驱动那个已经打开的窗口。

一次登录往往能解锁很多网站

这就是值得做这套设置的关键所在。在那个窗口里登录一次 Google，然后：

Google itself       google.com · youtube.com · your Workspace apps
Sites using Google SSO   your CRM, your booking system, your dashboards —
                         whatever "Sign in with Google" reaches
Everything else     log in by hand once; it stays

在一个真实配置文件上实测：一次 Google 登录就顺带带来了 YouTube 和两个使用 Google SSO 的内部业务系统——这些系统都没有单独登录过。其余（GitHub、Reddit、一个类银行门户）手动各登录一次以后就一直在。

所以设置成本大致是：一次 Google 登录，外加那些不用 Google 的服务各登录一次。 之后你的 agent 就能访问所有这些服务。

🔴 反面的代价是同样的一个事实：谁能驱动这个浏览器，谁就能在各个站点上以你的身份行动。 见安全。

它不会做什么

• 不会要求或存储你的密码。 你负责登录；Chrome 保管；Wbrowser 驱动那个已经打开的窗口。type 永远不记录输入内容。

• 不会把 cookie 值打印出来。 输出里没有，日志里也没有——cookie 本身就是登录态。

• 不会毫无根据地猜测你要的是哪个账号。 你指定一个未打开的账号，它就是失败。在错误的账号里发邮件比看到一个错误提示更严重。

• 不会在无人看管的情况下点击提交/支付/删除。 无人值守的任务会拒绝这类步骤，除非那个特定任务主动选择了允许。cron 任务出错时没有任何人在旁边看着。

一个我们实测过并如实告知的局限

Chrome 的调试端口没有认证。在这台机器上以你的身份运行的任何进程都可以接管并驱动你的会话——这一点是我们通过从一个无关进程连接并列出打开的标签页来验证的。127.0.0.1 并不是一堵墙；它意味着“任何以你的身份出现的东西都能进入”。

这是 Chrome 的设计，不是我们加上去的，而且这一类工具都继承了这一点。我们宁愿把它写出来，也不想让你以后自己发现——完整的威胁模型见安全。

快速开始

git clone https://github.com/<you>/Wbrowser.git
cd Wbrowser
# Wbrowser drives your *system* Chrome, so Playwright's own browser
# download is unnecessary — skip it and save ~400MB:
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install

node launch.js       # 1. opens a dedicated Chrome window
                     # 2. log into your sites in that window (by hand!)
node engine.js       # 3. start the control engine
./wb go https://example.com

就这样。第 2 步是唯一需要你手动做的操作。

如果 ./wb 提示 “Permission denied”——可执行权限位可能在克隆时没有保留出来（有些环境会去掉）。修复一次即可：

chmod +x wb install.sh autostart.sh sync-session.sh

无头服务器（无显示器）： Wbrowser 会检测到缺少 $DISPLAY 并自动以无头模式启动 Chrome。你也可以用 WBROWSER_HEADLESS=1 或 =0 显式强制。注意，没有屏幕就无法手动登录——可以用 ./sync-session.sh import 从桌面机器把会话带过来。

Windows 用户： 可以在 WSL 里运行这些命令，也可以直接在 Windows 上用 node 运行——两种方式都行。见平台说明。

为什么要单独开一个 Chrome 窗口？

Chrome 136（2025 年 3 月）之后，Chrome 会忽略为默认配置文件目录设置 --remote-debugging-port 参数。Google 这样做是因为攻击者一直在利用远程调试来窃取 cookies。

因此，现在非默认的 --user-data-dir 是必需的。Wbrowser 会在 ~/.wbrowser 创建一个用户数据目录，并在这个目录中启动 Chrome。

这意味着你现有的登录信息不会自动带过去。 在新窗口里登录一次，之后这些登录就会一直保存在那里。

⚠️ 直接复制你的 Chrome 配置文件文件夹是不行的。我们试过：685 个 cookie 变成了 3 个，而且所有 session cookie 都被丢弃了。Chrome 会丢弃它识别不了的配置文件。请重新登录一次——这只需要一分钟，而且确实管用。

命令

./wb go <url>              open a page, return its structure
./wb read                  summarize the current page
./wb click <selector>      click an element
./wb type <selector> <text>   fill an input
./wb press <key>           Enter, Tab, Escape, ArrowDown…
./wb eval '<js>'           run JavaScript in the page
./wb console [regex]       console logs + uncaught exceptions
./wb network               failed requests (4xx/5xx, CORS, timeouts)
./wb shot [file.png]       screenshot
./wb tabs                  open tabs, grouped by agent
./wb close                 close only the tabs you opened
./wb status                is everything up? which profile?
./wb show                  bring the browser window to the front

不要猜测选择器

./wb read 返回的是页面上真正的可点击元素：

inputs(1):
  - #searchbox_input  (Search the web without being tracked)
buttons(3): Search, Sign in, Settings

从这里复制选择器。（有一次我们猜了一个搜索框的 input[name=q]——结果它是 textarea。而 read 从一开始就给的就是正确的答案。）

直接告诉你的助手要做什么

连接好之后，你就不再需要一个一个敲命令，而是描述你想要的：

“打开我的面板，帮我汇总一下今天的数字。” “那个购物网站的购物车里有什么？” “看看那个预订到最终是不是真的订上了。”

连接基于 Model Context Protocol ——如果你的助手支持 MCP（Claude、Cursor 等都支持），那只需要几行配置，然后就可以直接用。

本地（stdio）：

{
  "mcpServers": {
    "wbrowser": {
      "command": "node",
      "args": ["/path/to/Wbrowser/mcp-server.js"]
    }
  }
}

远程（HTTP）：

export WBROWSER_MCP_TOKEN=$(openssl rand -hex 32)
node mcp-server.js --http --port 7982 --host 127.0.0.1

然后直接和你的助手说：

“打开我的仪表板，帮我汇总一下今天的数字。” “那个购物网站的购物车里有内容？”

工具： 有可执行代码浏览器 browser_read browser_click browser_type browser_press browser_eval browser_console browser_tabs browser_status

🔴 远程服务器没有 token 就不会启动。 这是必要的——因为它驱动的是一个装有你所有登录信息的浏览器。任何能访问那个端口的人，干的事儿你也干不了，以你的身份。

一个 agent 在驱动前应该知道的

这些来自构建过程中犯下的实际错误，如果你要为 Wbrowser 写自己的 skill 或 prompt，请把它们放进去：

1. 不要猜选择器。 使用 browser_read 获取页面上真实存在的选择器。我们用 input[name=q] 去选一个搜索框，结果实际上它是 textarea，而 read 往前走就一直告诉我们了。

2. 提交前把表单先读一遍。 在一个批量表单里，因为“保留”复选框没能覆盖所有行，第 2-10 行的客户字段会是空的。点击之前把每一行都读一遍就能捕获这个问题；直接先点击会创建 9 条错误记录。

3. 重复时不断数数。 连发 8 次回车键，结果生成了 40 行——页面处理它们的速度比我们预期的快。按一次、数一次，到目标就停下来。

4. 对于 framework 形式的表单，eval 优于 type；如果还是不行，type 又绝对优于 eval。 React 会忽略直接赋值 value——务必使用原生 setter 加上 input/change 事件。如果这还不生效，browser_type 会发送真实击键。

5. 检查你所连到的是什么。 browser_status 会告诉你窗口是否真的加载了登录信息。一个空的 profile 会对每个命令都成功响应，但并没有做任何有效的事情。

计划任务（cron）

创建 jobs/morning-check.json：

{
  "schedule": "0 9 * * 1-5",
  "tab": "morning",
  "steps": [
    { "goto": "https://dashboard.example.com", "wait": 2000 },
    { "eval": "document.querySelector('.total').innerText" },
    { "shot": true }
  ]
}

node cron.js list      # what's registered
node cron.js next      # when each job runs next
node cron.js run <name>   # run once, now
node cron.js daemon    # run on schedule

0 9 * * 1-5 = 第 0 分钟，第 9 点，每个工作日。 标准5字段 cron。

不可逆的操作默认会被禁止

无人值守的自动操作，意味着当出错时没有人盯着看。因此，看起来像 cephemer 提交/支付/删除的步骤都会被拒绝：

⛔ step 2 blocked — looks irreversible (click: #submit-payment)
   If you meant it, add "allowIrreversible": true to the job file.

你需要为每个任务单独选择允许，而不是全局允许。

是谁在驱动？ (视觉提示)

当 agent 控制浏览器的时候，你可以看到：

• 页面周围是半透明的边框，带有一个标注：🤖 my-agent 正在控制

• 标签页标题前加了前缀：[my-agent] Dashboard

无操作 6 秒后，边框会淡出——所以“控制中”其实就是指当下这一刻。颜色来自 agent 名称，让你一眼就能区分多个 agent。

标签页标题前缀会保留在导航过程中——一个 MutationObserver 会在页面重写自己的标题时重新应用改回前缀（SPA 这么干很频繁）。

多账号

在同窗口打开多个 Chrome profile（用 Chrome 的 profile 切换器），让 Wbrowser 可以单独逐个控制：

./wb -a work@example.com go https://mail.example.com
./wb windows                    # list open profiles

或者把站点映射到多账号，放进 accounts.json：

{
  "sites": {
    "mail.example.com": { "account": "work@example.com" }
  }
}

🔴 如果你指定了一个没有打开的账号，Wbrowser 会直接失败，而不是乱猜。从错误账号给你发邮件比看到一个错误信息更糟多了。

平台备注

如果检测失败，可设置 WBROWSER_CHROME=/path/to/chrome 来覆盖。

已在真实硬件上实测（2026-08-24）：

平台	Chrome	验证者	测量的内容
macOS 15	151	独立操作员	启动 · 引擎 · CLI · 状态路径
Linux（原生、无头）headless	148	独立操作员	上述全部 + 安全审查
WSL2 + Windows Chrome	151	维护者	上述全部
Windows 10（原生）	151	独立操作员	上述全部 + 端到端

并非每项检查都在每个平台上执行。安全审查（用 ss 验证：没有 token 时 MCP 拒绝启动，引擎在回环接口之外不可达）在 Linux 上完成。端到端运行（/health → /act → 真实页面提取）在 Windows 上完成。UNC 路径（\\wsl.localhost\...）同样可用——已实测，这与我们最初的预期相反。

安全审查是在 Linux 的另一台机器上完成的：没有 token 时，MCP HTTP 服务器会退出，从不打开 socket（已用 ss 验证）；引擎只绑定到 127.0.0.1，无法通过 tailnet 访问。

安全

此工具驱动着一个保有您所有登录凭证的浏览器。请务必谨慎对待。

• 🔴 127.0.0.1 并非安全防线——它的意思是“任何以您的身份运行的进程都能进入”。 Chrome 调试端口（9222）没有任何身份验证。该机器上的任何本地进程——另一个应用的另一进程、npm 的 postinstall 钩子、一段散落的脚本——都能附着并驾驶你已登录的每一个会话。我们已经实测：一个无关进程能够访问 GET http://127.0.0.1:9222/json/list，并在没有任何凭据的情况下列出打开的标签页。因此，请确保在此运行的只有你信任的程序才使用。

• 引擎只绑定 127.0.0.1，绝不要直接暴露它。

• 🔴 mcp-server.js --host 0.0.0.0 是存在的，并且会绑定到所有网络接口。虽然代码会打印警告，但此时端口已经开放。除非你处于可信任的私有网络（VPN/tailnet），否则请使用 127.0.0.1，且一定要使用 token。

• MCP HTTP 服务器强制要求 token，没有 token 拒绝启动。

• ./wb type 不会记录输入的内容——因为它可能是一个密码。

• 任何命令都绝不会打印、记录或返回 cookie 值。

• 请勿使用它输入密码、卡号或政府 ID。请手动登录；Wbrowser 会复用您的会话。

会话备份

GXP14、GXP15（预留占位，翻译时可保留原文）

🔴 Cookie 与密码同等敏感——它们就是登录凭据。脚本拒绝写入，除非目标位置确实被加密，也拒绝从它无法解密的密文中恢复。

环境变量

开机启动

GX 保持原样? 注意原文中有 GXP14 和 GXP15 不加保留翻译若为占位符

The engine starts automatically. The browser still needs a starting start — it's a desktop process, and this is your choice when to open it.

引擎已经 自动启动；浏览器仍需手动启动——它是桌面进程，所以何时打开它，应由你决定。

已知限制

• 没有自动化测试套件。 CI 只检查语法和少量不变量；所有涉及真实浏览器的测试都是由人工在四个平台上进行的。这一点不可扩展，因此贡献者最有价值的贡献就是补充自动化测试。

• 没有内置自然语言循环。 智能体自己选择选择器，read 命令会提供真实的 selector，这样也就不必进行猜测。

• 仅支持 Chrome/Chromium。 Firefox 没有 CDP。

• 一个 CDP 端口对应一个 Chrome 进程。 该窗口内打开的配置目录可见；另一个单独启动的 Chrome 则不可见。

贡献与安全

• CONTRIBUTING.md — 决定了这份代码的规则，以及如何测试它。

• SECURITY.md — 🔴 威胁模型。请先在共享机器上阅读此文件再运行：Chrome 调试端口没有身份验证，因此任何以你身份运行的本地过程都能控制您的会话。

发现安全问题？请提交 private advisory，而不是公开的 issue。

许可证

MIT — 见 LICENSE。