Agweb：给 coding agent 一台不抢键盘的浏览器

2026 年 11 月 14 日，Show HN 上出现「Agweb – a browser for agents that stays out of your way」，作者 paul-nameless，仓库同名。它不是又一个给 AI 用的无头浏览器，而是反过来：一台真正的 WebKit 窗口，看得见，但永远不抢你的焦点。agent 从 shell 里用 agweb 命令驱动它，语法尽量贴近 playwright-cli。

它解决的是哪个具体麻烦

同时跑几个 coding agent 时，Playwright 的 Chrome 窗口会冒出来抢键盘；切成 headless 之后，有些站点直接拦截，出错也只能猜。agweb 的取舍是：窗口始终存在，但从不激活；每个 agent 用自己的 workspace，标签页按 agent 分组；你在 dashboard 里同时看所有 agent 在做什么。

README 里作者给了自己的数字：5 个空闲页面在 agweb 里是 0% CPU，而 Chrome 的 GPU 进程会占着 5 到 7 个核心。内存表是 590 MB 对 730 MB 对 1.6 GB，分别是 agweb、headless Chrome、Playwright Chrome。这是作者一台 Mac 上的观察，不是基准测试，但方向很清楚：空闲标签应该被挂起。

接进自己的 Agent

最小接法有两步：装 app，装 skill。需要 macOS 26 或更新；下载 DMG，拖进 Applications，然后在 Help 菜单里装命令行工具和 Agent Skill。后者是给 Claude Code 和 Codex 用的；如果你用自己的 Agent，可以把仓库里的 skill/SKILL.md 作为工具说明塞进系统提示，再给它 agweb:* 的 Bash 权限。这个 skill 只允许这一类工具调用，边界写得很死。

从源码构建也行，需要 Xcode 26 或更新，跑 scripts/build.sh，再执行 install-cli、install-skill。从 Help 菜单装的两个入口是指向 app 的链接，app 更新时会跟着更新。

workspace 是这套东西的核心

一个 agent 一个 workspace，workspace 里可以有很多标签页。名字不是装饰：两个 agent 挤进同一个 workspace，就会互相点对方页面上的元素。SKILL.md 的建议很具体：先用 agweb list 看谁在，名字优先用 ticket 号、分支名或 PR 号，实在没有就加随机后缀。每条命令都带 -w，或者干脆 export AGWEB_WORKSPACE。收尾只关自己的 workspace，别人的标签页不要碰。

这套隔离也解释了它为什么能同时跑很多 agent：浏览器只有一个窗口，但每个 workspace 有自己的标签组和当前页，dashboard 只是把它们并排展示。你看得见所有窗口，但没有任何一个会突然跳到前台。对于「让 agent 在后台干活，我继续写代码」这个场景，这比多开几个浏览器靠谱。

一次网页任务的链路

下面是最小闭环，workspace 名用任务名，不要和别人撞：

agweb -w fix-login open https://app.example.com
agweb -w fix-login snapshot
agweb -w fix-login click e12
agweb -w fix-login wait --text="Saved"
agweb -w fix-login --raw text
agweb -w fix-login close

-w 指定 workspace，每条命令都要带，或者 export AGWEB_WORKSPACE=fix-login。先跑 agweb list：已经存在的名字属于别的 agent，不要动。open 会在 app 没启动时把它拉起来；snapshot 返回带 [ref=eN] 的页面树；click e12 的回复自己会说清楚发生了什么——它等这次点击引发的 fetch，然后在 ### Changes 下列出新增和删除的树行。多数情况下不需要再补一次 snapshot。

几个限制要记在脑子里：动作最多等 5 秒让目标出现；snapshot 到 2000 行就截断；标签页在命令之间 30 秒后隐藏、约 4 分钟后挂起，下一条命令会把它唤醒。所以「页面是不是没了」通常不是问题，「我等的元素是不是还没出现」才是。慢页面用 wait 等条件，不要靠固定 sleep。

最后一步 --raw text 把页面正文转成 markdown，适合让 agent 读取结果；close 收掉自己的 workspace。真实任务里再加 console error 和 requests，前者看页面报错，后者看 fetch 和 XHR 的状态码。

选择器与变更摘要

snapshot 返回的树里，每个可操作元素带一个 ref。ref 只在元素还留在页面上时有效；页面一导航或重渲染，旧 ref 就报 not found。这时候用 find 找文本，或者重新 snapshot，不要硬点。

除了 ref，还能用 role=button[name="Save"]、text=Save、CSS 选择器。role 和 text 必须刚好匹配一个可见元素，匹配到多个会报错并列出候选，省得 agent 猜。同源 iframe 和开放的 shadow root 也会被搜到，跨域的 iframe 只显示一个空壳，得单独开标签页。

每次 click、fill、type 之后，回复里的 ### Changes 会列出这次动作触发的 fetch 和 XHR，以及页面树新增、删除了哪些行。行数多了会截断，剩下的用 snapshot --diff 看。这个设计的意义是省 token：多数步骤不需要再拍一张完整快照，agent 直接读变更就够了。

密码、登录和多 agent

密码不该出现在 agent 的对话记录里。agweb 的写法是：

agweb -w task fill 'role=textbox[name="Password"]' --secret-cmd 'pass show site'

--secret-cmd 取命令输出的第一行，pass、1Password 和 Bitwarden 的 CLI 都能用。值不会进回复：snapshot 里显示成隐藏占位，eval、console、request-body 也会把它打码。不要写成 $(pass show site)，那样值会先落进 shell 和 transcript，再传给浏览器，前功尽弃。

登录态靠命名 profile：-p work 的 cookie 和 localStorage 会被所有使用它的 workspace 共享，而且可以并发。profile 在 open 时固定，中途不能换；换之前先 close。需要人来做 MFA、验证码或扫码时，用 ask 把标签页交回给你，不抢焦点，你点完成再继续。

多个 agent 并行时，dashboard 用 ⌘D 打开，能同时看到每个 agent 的标签页和最后一条命令。广告和追踪器默认被 uBlock Origin 的规则拦掉，规则每 4 天更新一次；要测分析脚本，就在自己的 workspace 里 adblock off。route 可以 mock fetch 和 XHR，video-start 能把操作录成 MP4，指针和点击会画进去，适合留证据。

调试与验证

页面出问题时，先看 console error，再看 requests。requests 列出页面加载以来的 fetch、XHR 和文档请求，带状态码；广告拦截器拦下的请求会标成 blocked by adblock。要测分析脚本或错误上报，就在自己的 workspace 里关掉拦截，再 reload。

要 mock 接口，用 route 设状态码和响应体，unroute 清掉。截图用 screenshot，整页加 --full-page，单个元素后面跟 ref。highlight 只给真人看，不改变页面。这些都算辅助命令，真正的主线还是 open → snapshot → act → wait → text：先让页面稳定，再做动作，再用变更摘要或条件等待确认结果。

举个具体例子：让 agent 修一个登录后跳转失败的问题。它先在 fix-login workspace 打开登录页，snapshot 找到邮箱和密码框，用 profile 里的登录态直接进 dashboard；如果被登出，就用 ask 把页面交给你，你手点一次，它继续。进入后点触发跳转的按钮，读回复里的跳转与事件提示，再用 requests 看登录接口的状态码。整个过程中窗口不抢你的键盘，你可以同时在另一个 workspace 里干别的。

和 playwright-cli 的差别

命令名尽量对齐：-w 替代 -s，-p 替代 --profile、--persistent 和 --config；没有 run-code，也没有 localstorage-*，后者用 eval 代替。state-load 能读 playwright-cli 的 state-save 文件，登录态可以搬过来。它永远是 WebKit、永远有窗口，这两点既是优点也是限制。

边界

• 只有 WebKit。没有 Chrome DevTools Protocol，Playwright 和 Chrome 扩展接不进来，只支持 Chrome 的站点可能表现不对。
• route 只 mock fetch 和 XHR；requests --static 只能按 URL 列出图片、脚本和样式。
• 广告拦截跑不了 uBlock 的脚本，YouTube 广告和一些「请关闭广告拦截」的墙会漏过去。
• 需要 macOS 26 或更新；项目还年轻，命令会变。真做不了的事，README 的建议很直接：用 Playwright。

我们没在 macOS 上装它，命令和行为以 README 与仓库内 SKILL.md 为准。如果你的 agent 已经在用 playwright-cli，迁移主要是把 -s name 换成 -w name、--profile 换成 -p。它不值得替代 Playwright 的所有场景，但能把「抢焦点」和「headless 出错靠猜」这两个日常摩擦从常见链路里拿掉。

本文基于以下公开报道整理。

参考来源

• paul-nameless/agweb — GitHub（2026-11-14）
• agweb Agent Skill（SKILL.md）— GitHub（2026-11-14）
• Show HN: Agweb – a browser for agents that stays out of your way — Hacker News（2026-11-14）

本文由 AI 辅助整理，事实来自项目 README 与仓库内 SKILL.md；我们未在 macOS 上安装 agweb，安装步骤与命令行为以这两个文件为准。