CatPaw

开源 · Rust · Apache-2.0 或 MIT

专为 AI agent 设计的 headless-first 浏览器

CatPaw 像普通浏览器一样执行页面的 JavaScript 和 DOM，同时把 agent 真正需要的东西直接交给它：带稳定引用的紧凑快照、每次操作之后页面变了什么，以及页面什么时候算是稳定下来了。它用 Rust 从零写成，不是 Chromium 的封装。

macOS 与 Linux 
curl -fsSL https://catpaw.sh/install.sh | sh
Windows（PowerShell） 
irm https://catpaw.sh/install.ps1 | iex

0.1 版是预览版。安装脚本会先列出要写入的文件，征得你同意后才动手。目前能做什么、还不能做什么。

安装与选项 GitHub 上的源码

为什么

从一开始就为 agent 设计

CatPaw 不是 Chromium 的封装，也不是在渲染引擎外面再套一层自动化接口。它的第一用户是 agent：忠实执行 JavaScript 与 DOM，只在有人需要几何信息时才计算布局，并直接回答 agent 关心的几件事：页面上有什么，刚才变了什么，页面是不是已经稳定了。

  • 紧凑快照，稳定引用

    snapshot 返回 CST（CatPaw Snapshot Text）树，是 Playwright aria snapshot 的超集。元素用 e12 这样的 ref 指代，在元素离开页面之前一直有效，而且永不复用。整份快照上限 4000 token，其余部分折叠起来，由 agent 按需展开。

  • 操作之后给 diff

    每个操作都等页面稳定之后才返回，告诉 agent 发生了什么、页面上变了什么，一步就是一次往返。换了新文档时返回完整快照。

  • 知道页面何时稳定

    CatPaw 清楚每一个在途请求、定时器、动画帧和 microtask。页面迟迟不稳定时，会列出原因，精确到发起它的脚本位置。页面只在等定时器的那段时间会瞬间跳过。

  • 有副作用，先确认

    默认策略下，提交表单和上传文件都要等用户批准。宿主支持 MCP elicitation 时就地询问；否则 CatPaw 在用户自己的浏览器里打开批准页面。agent 始终看不到密钥。

  • 交给用户接管

    遇到需要真人的场合，比如登录或面向人类的验证，handoff 会在用户自己的浏览器里打开这个 tab。用户像在原网页上一样点击、输入、滚动；完成后 agent 拿回页面，用户输入的内容一律遮蔽。

  • 飞行记录仪

    --flight-log 记录每一次调用、确认和决定，需要的话每个操作再附一张截图。输入的密码只记长度。

  • 录制与回放

    --record-har 保存会话的全部流量，--replay-har 不联网按记录回放。固定随机种子和时钟之后，回放结果逐字节一致。

  • 诚实的身份

    CatPaw 如实表明自己的身份；给它密钥时，用 Web Bot Auth 为请求签名；不做指纹伪装，不接打码服务。回环与私网地址默认拒绝访问，需要时可以放行。致站长。

点击“Add to cart”之后 agent 读到的全部内容：操作本身、一行头信息，以及变化的三行。
ok click e16 button "Add to cart"
# s4 diff-from=s3 tab=t1 doc=d1 url=(same) scroll=0,0 settled=yes changed=1 added=1 removed=1 unchanged=27
~ e11 button "Cart, empty" → "Cart, 1 items"
+ e37 button "Remove" (in e13, after e15)
- e16 button "Add to cart"

实测

agent 要读多少

仓库里有 20 个练习站点上的任务，每个都带录制的流量和 agent 看到的完整记录。下表统计 agent 在一个任务中收到的全部工具结果有多少字节，并和 Playwright MCP 走同样步骤时对比。

字节数，token 按每 3.5 字节一个估算
任务CatPawPlaywright MCP
练习站点任务（除一项外，见下文）71 次调用
68099 (~19457)		118 次调用
243282 (~69509)
Hacker News 第二页2 次调用
14618 (~4177)		4 次调用
98113 (~28032)
Wikipedia 搜索并打开文章2 次调用
11224 (~3207)		4 次调用
569358 (~162674)
工具列表（每轮对话都要发送）12.1 KB20.3 KB

测量方法：字节数是 agent 在一个任务中收到的全部工具结果。CatPaw 的数字来自录制的回放；Playwright MCP 为 @playwright/mcp 0.0.83 搭配 headless Chrome，于 2026-10-08 实网走同样的步骤，取三次运行的中位数。Playwright MCP 把页面快照存进文件，页面变化时在结果里给出链接；agent 要看页面、找下一个目标就得读这个文件，所以它也计入，并算作一次调用。CatPaw 的数字包含了等待用户批准的调用，Playwright MCP 没有这一步。用户拒绝确认的那个任务在 Playwright MCP 一侧没有对应，合计不计入。内容站点的两行是同一天用同样方法测得的，这些录制不进仓库。逐项数据和重新生成的命令见 中文 README。

安装

只写一个文件，先问过你

macOS 与 Linux 
curl -fsSL https://catpaw.sh/install.sh | sh
Windows（PowerShell） 
irm https://catpaw.sh/install.ps1 | iex

安装脚本从 GitHub Releases 下载适合你机器的版本，用该版本的 SHA256SUMS 校验，然后列出要写入的文件、是否会替换已有的文件，等你确认。确认之前什么都不写。再次运行即原地升级。也可以先看看 install.sh 和 install.ps1 的内容。

会写入什么

  • macOS 与 Linux：只有一个文件 ~/.catpaw/bin/catpaw。不用 sudo，不改 shell 配置文件，也不改 PATH；目录不在 PATH 里时，会打印需要添加的那一行。
  • Windows：只有一个文件 %LOCALAPPDATA%\Programs\CatPaw\catpaw.exe，并把这个目录加入用户 PATH。不需要管理员权限。

提供预编译版本的平台：Linux x86_64 与 aarch64（glibc）、Apple 芯片的 macOS、Windows x86_64；ARM 版 Windows 11 可以通过仿真运行 x64 版本。Intel 芯片的 Mac 请从源码构建。

选项

装到别的目录
curl -fsSL https://catpaw.sh/install.sh | sh -s -- --dir ~/bin
& ([scriptblock]::Create((irm https://catpaw.sh/install.ps1))) -Dir 'D:\Tools\CatPaw'
不提问（用于脚本和 CI）

加上 --yes（sh）或 -Yes（PowerShell），或者设置 CATPAW_YES=1。既没有可以提问的终端、又没给这些参数时，安装脚本会停下来并说明原因。

指定版本

--version v0.1.0 或 -Version v0.1.0，也可以设置 CATPAW_VERSION。CATPAW_INSTALL_DIR 与 --dir 作用相同；两者都给时以参数为准。

卸载
curl -fsSL https://catpaw.sh/install.sh | sh -s -- --uninstall
& ([scriptblock]::Create((irm https://catpaw.sh/install.ps1))) -Uninstall

它会删除二进制文件（Windows 上还会从 PATH 中移除对应条目）；要不要删除 CatPaw 的批准密钥，会另外再问一次；最后列出需要你在 agent 宿主里手动移除的配置。安装时用过 --dir 或 -Dir，卸载时也要带上。手动卸载：删掉二进制文件即可，Windows 上再把它所在的目录从用户 PATH 中删去。

从源码构建

git clone https://github.com/KernelErr/CatPaw
cd CatPaw
cargo build --release -p catpaw

需要 Rust 1.89 或更新版本，以及 C 编译器。生成的二进制文件在 target/release/catpaw。

接入

交给你的 agent

catpaw mcp --stdio 通过 Model Context Protocol 把浏览器提供给 agent。用 catpaw setup 注册到你的 agent 宿主：

catpaw setup claude-code          # 打印 claude mcp add 命令
catpaw setup claude-code --write  # 或在当前项目写入 .mcp.json
catpaw setup codex --write        # 写入 ~/.codex/config.toml
catpaw setup cursor --write       # 写入 ~/.cursor/mcp.json

不加 --write 时，setup 只打印要运行或添加的内容。-- 之后的参数会交给 catpaw mcp，例如 catpaw setup cursor -- --policy strict：这样在脚本向其他站点发送数据、以及执行 evaluate 之前也会询问。

工具有 navigate、snapshot、click、type、fill、press、select、act、wait、read、screenshot、evaluate、tabs、logs 和 handoff。页面打开的窗口会成为新的 tab。出错时会说明下一步该怎么做。

不经过 agent，自己看一个页面：

catpaw fetch https://example.com --js --snapshot

现状

预览版，实话实说

0.1 版是预览版。前四个里程碑已经完成：抓取与阅读、脚本运行、交互、agent API。还有不少缺口，也会有网站用不了。

已经能做的

  • 基于 Boa 引擎的 JavaScript：经典脚本与模块脚本、DOM、事件、fetch 与 XHR、存储、Worker、WebSocket、Canvas 2D 和 Web Crypto。React、Vue、Svelte、Lit、htmx、Alpine 站点都能运行。
  • 按需布局；截图能画出背景、边框、文字和表单控件。
  • 受信的指针与键盘输入、表单、导航与历史、iframe，弹窗作为 tab。
  • MCP server，带确认、交给用户接管、飞行记录、profile 以及 HAR 录制与回放。20 个练习任务在 CI 中各回放两次，逐字节一致。

还不能做的

  • 没有 JIT。Boa 是解释执行的，单页应用自身的脚本比在 Chrome 里慢很多倍。
  • 截图还画不出图片、渐变和圆角。
  • 不支持媒体和 WebAssembly；表格还不按网格布局，图片没有固有尺寸。
  • 样式表看不到运行时状态：点击之后的 :hover、:focus、:checked 不会匹配。
  • 下载的文件只留在内存里，不写入磁盘。录制会遮蔽请求、cookie、凭据头和 JSON 响应里的密钥，但不处理 HTML 和其他文本。
  • CatPaw 进不了所有网站。放不放行，由网站所有者决定。

路线图接下来是：挑战检测与实测通过率；之后是多租户限额、OpenTelemetry、Docker、供 Puppeteer 使用的 CDP 子集，以及可选的 V8 后端。完整的已知缺口见架构说明（英文）。

延伸阅读

文档