Pagerunner — The Browser Layer That Learns

Pagerunner

一款 Chrome 浏览器自动化 MCP 服务。将 Claude（或任何 MCP 客户端）连接到真实的 Chrome 会话，使用你现有的配置文件及其中的 Cookie、保存的密码和历史记录。

警告

Pagerunner 仍处于早期开发阶段（v0.x）。不同版本之间的 API 和配置格式可能会发生变化。

目录

• 工作原理
• 设置
• 在项目中使用
• 工具
• 网站智能
• 会话检查点
• macOS 菜单栏应用
• 匿名化（PII 保护）
• 隐身模式
• 守护进程（多个 Claude Code 会话 / 持久化状态）
• 快照
• 会话示例
• 法律与负责任的使用

工作原理

Pagerunner 通过 CDP（Chrome DevTools Protocol）使用你现有的用户配置文件启动 Chrome，并通过标准输入/标准输出将其作为 MCP 服务提供。随后，Claude 可以在运行中的浏览器中导航、点击、输入、截屏和运行 JavaScript。

设置

1. 安装

# Option A — Homebrew (easiest on macOS/Linux):
brew tap enreign/pagerunner
brew install pagerunner

# Option B — Cargo (if you have Rust):
cargo install pagerunner
# Note: if you get "requires rustc 1.91+" despite having a newer Rust installed,
# Homebrew's Rust may be shadowing rustup's. Fix: export PATH="$HOME/.cargo/bin:$PATH"

# Option C — Pre-built binary (no dependencies):

# macOS arm64 (Apple Silicon):
curl -L https://github.com/Enreign/pagerunner/releases/latest/download/pagerunner-macos-arm64 \
  -o pagerunner && chmod +x pagerunner

# macOS x86_64 (Intel):
curl -L https://github.com/Enreign/pagerunner/releases/latest/download/pagerunner-macos-x86_64 \
  -o pagerunner && chmod +x pagerunner

# Linux x86_64:
curl -L https://github.com/Enreign/pagerunner/releases/latest/download/pagerunner-linux-x86_64 \
  -o pagerunner && chmod +x pagerunner

# macOS: if Gatekeeper blocks the binary on first run:
xattr -d com.apple.quarantine pagerunner

# Option B — install via cargo (requires Rust):
cargo install --git https://github.com/Enreign/pagerunner --locked

# Option C — build locally:
cargo build --release

2. 自动检测 Chrome 配置文件

pagerunner init

此操作会读取 Chrome 的配置文件列表，并自动写入 ~/.pagerunner/config.toml。 运行 pagerunner status 进行验证。

或者，手动编写 ~/.pagerunner/config.toml——格式请参见 pagerunner example-config。

3. 注册为 MCP 服务

# If installed (Options A or B — binary is in PATH):
claude mcp add pagerunner "$(which pagerunner)" mcp

# If built locally (Option C):
claude mcp add pagerunner "$(pwd)/target/release/pagerunner" mcp

对于 Claude Desktop，将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "pagerunner": {
      "command": "/absolute/path/to/pagerunner",
      "args": ["mcp"]
    }
  }
}

**注意：**必须使用 mcp 子命令——仅注册二进制文件路径而不添加 mcp 将无法正常工作。

**注意：**Chrome 会锁定配置文件目录。在使用 Pagerunner 会话打开某个配置文件之前，请关闭正在使用该配置文件的所有 Chrome 窗口。

4. 在项目中设置（可选）

在包含 CLAUDE.md 或 AGENTS.md 的任意项目目录中：

pagerunner init

Pagerunner 会打印一段可直接使用的用法说明，并询问是否自动将其追加到项目文件中。用于脚本操作时，可运行：pagerunner init --json。

5. （可选，仅在使用 --features ner 构建时）下载 NER 模型

pagerunner download-model   # ~65MB, enables PERSON/ORG name detection

在项目中使用

将示例 Agent 指令复制到项目根目录，让 Claude（或任何 Agent）立即了解如何使用 Pagerunner：

# Claude Code projects:
curl -sL https://raw.githubusercontent.com/Enreign/pagerunner/main/docs/examples/CLAUDE.md -o CLAUDE.md

# Other agents (Gemini, Codex, etc.):
curl -sL https://raw.githubusercontent.com/Enreign/pagerunner/main/docs/examples/AGENTS.md -o AGENTS.md

或者手动粘贴内容，并根据项目的具体需求扩展指令。

在 Claude Code 中使用 Pagerunner

如需适用于 4 种不同用例的全面指南、工作流和示例，请安装 Pagerunner Skill：

# Install the skill (once available in skills.sh registry)
claude skill install pagerunner-skill

或者直接查看 Skill 仓库：pagerunner-skill

此 Skill 包含：

• **适用于 4 类 ICP 的快速入门：**独立开发者、进阶用户、注重安全的用户、服务端
• **11 种工作流模式：**填写表单、身份验证、滚动、多步骤交互
• **完整参考：**全部 38 个工具及其参数和示例
• **安全指南：**PII 匿名化、审计日志、加密
• **真实案例：**包含错误处理的端到端工作流
• **故障排除：**常见问题及解决方案

从该 Skill 的 SKILL.md 开始，找到适合你的用例和快速入门路径。

工具

会话与标签页

工具	描述
list_profiles	列出已配置的 Chrome 配置文件
open_session	为某个配置文件启动 Chrome，并返回 session_id
attach_session	通过 --remote-debugging-port 附加到现有 Chrome 实例
close_session	终止 Chrome 会话
list_sessions	列出活动会话
list_tabs	列出会话中打开的标签页
new_tab	打开新标签页，并返回 target_id
close_tab	关闭指定标签页

导航与内容

工具	描述
navigate	将标签页导航到某个 URL
wait_for	等待 CSS 选择器、URL 模式或固定时长
get_content	获取标签页中可见的文本内容
screenshot	将标签页截图为 PNG（保存到临时文件或以内联 base64 格式返回）
evaluate	在标签页中运行 JavaScript，并返回结果

交互

工具	描述
click	根据 CSS 选择器点击元素
type_text	在获得焦点的元素或指定选择器处输入文本
fill	使用 React/Vue/Angular 合成事件设置输入值
select	根据值选择下拉选项
scroll	按像素滚动页面，或将某个元素滚动到可见区域

快照与标签页状态

工具	描述
save_snapshot	将当前页面的 cookies/localStorage 保存到加密数据库
restore_snapshot	将已保存的快照恢复到当前标签页
list_snapshots	列出已保存的快照（可选跨所有配置文件）
delete_snapshot	删除已保存的快照
save_tab_state	将所有已打开标签页的 URL 保存到数据库
restore_tab_state	重新打开之前保存的标签页

键值存储

工具	描述
kv_set	在持久化命名空间中存储值
kv_get	根据键检索值
kv_delete	删除键
kv_list	列出命名空间中的键（可选按前缀筛选）
kv_clear	删除命名空间中的所有键

网络与控制台

工具	描述
get_network_log	检查会话中捕获的 HTTP 请求
get_console_log	捕获标签页中的 JavaScript 控制台输出

站点智能

工具	描述
get_site_knowledge	检查 Pagerunner 对某个站点的了解（适配器、身份验证令牌、选择器健康状况）
register_adapter	存储用于直接调用站点 API 的 JS 适配器
call_site_api	在浏览器标签页中执行已存储的适配器
generate_adapter	使用 Claude 根据网络流量自动生成 JS 适配器（需要 ANTHROPIC_API_KEY）

会话检查点

工具	描述
save_session_checkpoint	保存会话中所有标签页的完整状态（URL + 滚动位置）
restore_session_checkpoint	重新打开所有已保存的标签页，并导航到存储的 URL
list_session_checkpoints	列出某个配置文件的已保存检查点
delete_session_checkpoint	根据 ID 删除检查点

站点智能

Pagerunner 会在使用过程中了解各个站点，并可直接使用会话凭据调用站点 API，无需单独设置身份验证。

适配器是存储在加密数据库中的简短 JS 函数，并在浏览器标签页中执行。可用它们调用站点提供的 API（通常是网页 UI 使用的同一 API）：

register_adapter(origin="https://github.com", name="list-issues",
  description="List open issues for a repo",
  js_code="async ({owner, repo}) => { const r = await fetch(...); return r.json() }")

call_site_api(session_id, target_id, origin="https://github.com",
  name="list-issues", params={"owner": "Enreign", "repo": "pagerunner"})

内置了适用于 GitHub、Linear、Jira、Notion 和 Gmail 的预置适配器。

身份验证令牌检测——在网络流量中发现的 Bearer 令牌、API 密钥和会话 cookie 会存储在加密站点保险库中。适配器可通过 credentials 参数自动访问这些凭据。

选择器稳定性——click、fill 和 select 会跟踪每个选择器的成功/失败率。当某个选择器在使用至少 5 次后，失败率超过 30% 时，工具响应中会显示脆弱性警告。

会话检查点

保存完整的浏览器状态（所有打开的标签页及其 URL 和滚动位置），并在任何未来的会话中恢复：

save_session_checkpoint(session_id, name="before-review")
  → checkpoint_id: cp_abc123

restore_session_checkpoint(session_id, checkpoint_id="cp_abc123")
  → reopens all saved tabs at their stored URLs

检查点存储在加密数据库中，并按配置文件隔离。

macOS 菜单栏应用

原生 Swift 配套应用位于 apps/menubar/。它可在菜单栏中显示所有 Chrome 配置文件、活动会话、打开的标签页和守护进程状态，无需使用终端。

功能：

• 一键打开／关闭会话并保存检查点
• 在单独的区域中用独特的 CPU 图标显示 Agent 配置文件
• 添加配置文件流程：发现未配置的 Chrome 配置文件或创建新的 Agent 配置文件
• macOS 原生通知：守护进程已停止、会话崩溃、检查点已保存
• 全局快捷键和通过 Sparkle 2.x 自动更新

构建并运行：

pagerunner daemon &
cd apps/menubar
bash scripts/package.sh   # builds + bundles into scripts/Pagerunner.app
open scripts/Pagerunner.app

匿名化（PII 保护）

向 open_session 传递 anonymize: true，即可在所有 get_content 和 evaluate 结果到达 Claude 之前清除其中的 PII。匿名化模式下会屏蔽屏幕截图。

{ "tool": "open_session", "profile": "personal", "anonymize": true }

默认检测： EMAIL、PHONE、CREDIT_CARD、IBAN、SSN、IP 使用 --features ner 构建时： 还会通过本地 ONNX 模型检测 PERSON 和 ORG 名称

模式

• tokenize（默认）：将 PII 替换为 [EMAIL:a3f9b2] 之类的令牌。将令牌传回 fill／type_text 后，Pagerunner 会在写入 DOM 前还原令牌。
• redact：单向替换为 [EMAIL]，不使用保险库，也不会还原令牌。

NER 设置（PERSON 和 ORG 名称检测）

# 1. Build with NER support:
cargo build --release --features ner

# 2. Download the model (one-time, ~65MB):
pagerunner download-model

在 ~/.pagerunner/config.toml 中全局禁用：

[ner]
enabled = false

隐身模式

向 open_session 传递 stealth: true 以启用反检测功能：隐藏自动化信号，注入脚本来掩盖 navigator.webdriver，并在输入操作之间加入类似人类的延迟。

{ "tool": "open_session", "profile": "personal", "stealth": true }

会话示例

open_session(profile="personal")          → session_id: abc123
new_tab(session_id, url="https://...")    → target_id: TAB456
get_content(session_id, target_id)        → "page text..."
click(session_id, target_id, "#button")
type_text(session_id, target_id, "hello", selector="#input")
screenshot(session_id, target_id)         → "data:image/png;base64,..."
close_session(session_id)

守护进程（多个 Claude Code 会话／持久化状态）

默认情况下，每个 pagerunner mcp 进程都会直接打开数据库，一次只能运行一个进程。如果在第二个 Claude Code 窗口中打开 Pagerunner，就会遇到数据库锁定错误。

启动一次守护进程，即可在任意数量的会话之间共享状态：

pagerunner daemon &

每个 pagerunner mcp 实例都会自动检测守护进程，通过 Unix 套接字（~/.pagerunner/daemon.sock）连接，并通过它代理所有工具调用。所有 Claude Code 窗口共享相同的已打开浏览器、KV 存储和快照。

停止：

pkill -f "pagerunner daemon"

安装为后台服务（登录时启动，崩溃后重启）：

./scripts/install-launchd.sh

脚本会自动检测已安装的 pagerunner 二进制文件。日志位于 ~/.pagerunner/daemon.log。

注意： 安装守护进程服务后，请重启 Claude Code。下次启动时， 守护进程会先通过 launchd 启动，MCP 服务随后以代理模式连接到它。 如果安装守护进程时 Claude Code 已在运行，则需要重启两次： 第一次让 launchd 启动守护进程，第二次让 MCP 服务重新连接到它。

快照

将已通过身份验证的浏览器状态保存到加密的本地数据库：

save_snapshot(session_id, target_id, origin="https://github.com")

在任何未来的会话中恢复：

restore_snapshot(session_id, target_id, origin="https://github.com")

快照使用 AES-256-GCM 加密。密钥存储在 macOS 钥匙串的 pagerunner / db_key 项中，绝不会以明文形式写入磁盘。

法律声明与负责任的使用

Pagerunner 使用你自己的凭据自动操作你拥有的浏览器。你有责任遵守你所自动操作的任何网站的服务条款、适用的数据保护法律（GDPR、CCPA）以及授权访问要求（CFAA 及其同类法律）。

对于涉及处理他人个人数据的任何工作流，建议使用 anonymize: true。

完整的法律免责声明、责任限制和负责任使用义务，请参阅 DISCLAIMER.md。

---

如果这个项目对你有帮助，请为仓库点亮星标，帮助其他人发现它。