PinchTab

PinchTab
面向 AI Agent 的浏览器控制
小巧的 Go 二进制文件 • HTTP API • 节省令牌

---

PinchTab 是什么？

PinchTab 是一个独立的 HTTP 服务，可让 AI Agent 直接控制 Chrome。

对于日常本地使用，通常会将该服务安装为用户级守护进程，让 Agent 工具能够重复使用在后台运行的同一浏览器控制平面。

curl -fsSL https://pinchtab.com/install.sh | bash
# or
pinchtab daemon install

这会安装控制平面服务并启动默认的无头 Chrome 实例，随时可以接收来自 Agent 的请求或手动 API 调用。

PinchTab 首先面向你管理的机器上的本地单用户控制场景。它也支持远程和分布式部署，但这些属于高级的、由运维人员管理的部署方式。如果你将服务绑定到回环地址以外的地址、发布端口或连接远程桥接器，就需要负责管理令牌、网络边界、TLS 或反向代理，以及要公开哪些端点类别。

如果你在另一台机器上运行 PinchTab，请务必先了解其安全模型。将其限制在私有或其他封闭网络中，避免直接暴露到公共互联网；除非明确需要，否则应禁用高风险端点类别。如果确实需要启用，请做好访问限制，确保只有需要访问的系统才能连接。

警告

仪表板、HTTP API、MCP 服务和远程 CLI 集成都是具有特权的运维控制界面。它们并非为不受信任的用户、多租户暴露或直接访问公共互联网而设计。如果你不确定如何保护非本地部署，请查看 docs/guides/security.md，并在公开服务前通过 SECURITY.md 中的私密安全联系渠道寻求帮助。

如果你不想运行守护进程，或者使用的是 Windows，也可以改为运行：

pinchtab server — 直接运行控制平面服务
pinchtab bridge — 将单个浏览器实例作为轻量级运行时运行

直接运行 pinchtab 会在首次使用时执行安全设置，然后显示服务状态、安全状况和建议的后续步骤：

pinchtab

安全

PinchTab 默认采用本地优先的安全策略：

• server.bind = 127.0.0.1
• 仅当仪表板通过 HTTPS 实际提供服务时，会话 Cookie 才会设置为 Secure
• 默认禁用敏感端点系列
• 默认禁用 attach
• 启用 IDPI，并使用仅限本地的网站允许列表

如果你有意通过非回环地址上的普通 HTTP 访问仪表板，PinchTab 现在会在 UI 中警告你，会话未使用传输加密。请尽可能使用 HTTPS 或 localhost。如果强制设置 server.cookieSecure = true，仪表板登录将要求使用 HTTPS；如果使用普通 HTTP，登录会明确失败，而不会悄无声息地陷入循环。

注意

默认情况下，IDPI 会将浏览限制在仅限本地托管的网站。 这样可以防止 Agent 在你明确允许之前访问公共互联网。 设置此限制是为了在启用更广泛的访问权限之前，清楚说明浏览器自动化带来的安全影响。

将浏览范围扩展到非本地或不受信任的网站会降低安全性。即使启用了 PinchTab 的内容防御，恶意页面仍可能扩大浏览器攻击面，并与已启用的自动化功能产生不良交互。

请参阅完整指南：docs/guides/security.md

远程、容器和分布式部署均可实现，但 PinchTab 并非面向互联网的开箱即用浏览器服务。请将任何非本地部署视为高级设置，并明确做好安全防护。

可以用它做什么

无头浏览

安装守护进程并配置好 Agent 技能后，Agent 可以执行以下任务：

"What are the main news about aliens on news.com?"

PinchTab 提供浏览器工具，允许 Agent 浏览页面、提取结构化内容并与 DOM 交互，而无需浪费令牌处理原始 HTML 或图像。

有头浏览

除了无头自动化，PinchTab 还支持有头 Chrome 配置文件。

你可以创建配置了身份验证、Cookie、扩展程序或特定环境的配置文件。每个配置文件都可以有名称和描述。

例如，Agent 收到这样的请求：

"Log into my work profile and download the weekly report"

便可以自动选择合适的配置文件并执行操作。

网站审计与视觉比较

PinchTab 可以在浏览器层面审计整个网站——包括屏幕截图、控制台 错误、损坏的资源、无障碍评分、Core Web Vitals 和安全 问题——并在发布前对两个网站版本进行视觉比较：

pinchtab audit https://example.com --output-dir ./audit          # report.json + screenshots/
pinchtab audit https://example.com/sitemap.xml --sitemap --sample-size 2 --output-dir ./audit
pinchtab compare https://example.com https://staging.example.com --fail-on-diff   # CI gate

请参阅 docs/audit.md，了解完整的命令参考、报告 结构和 CI 示例。

本地容器隔离

如果你倾向于采用更强的隔离方式，PinchTab 可以在 Docker 中运行。

这样，Agent 就可以在沙盒环境中控制浏览器，从而降低在本地运行自动化任务时的风险。

分布式自动化

PinchTab 可以在容器或远程机器上管理多个 Chrome 实例（无头或有头）。

典型用例包括：

• QA 自动化
• 测试环境
• 分布式浏览任务
• 开发工具

你可以连接到多个 PinchTab 服务，也可以连接到以远程调试模式运行的 Chrome 实例。

进程模型

PinchTab 采用服务优先模式：

1. 安装守护进程，或运行 pinchtab server 以启动完整控制平面
2. 由服务管理配置文件和实例
3. 由每个受管理的实例在轻量级 pinchtab bridge 运行时下运行

实际组成如下：

• 服务 — 主要产品入口和控制平面
• Bridge — 管理单个浏览器实例的运行时
• Attach — 用于注册外部管理的 Chrome 实例的高级模式

主要用法

主要用户流程如下：

1. 安装 Pinchtab
2. 使用 pinchtab daemon install 安装并启动守护进程
3. 将你的 Agent 或工具指向 http://localhost:9867
4. 让 PinchTab 充当你的本地浏览器服务

这是默认的“替换浏览器运行时”场景。 大多数用户无需直接使用 pinchtab bridge，只有在首次运行设置或查看状态概览时才需要使用裸命令 pinchtab。

Agent 插件（仍需单独安装二进制文件）：

# Grok Build, after listing in the official xAI marketplace
grok plugin install pinchtab --trust

# OpenClaw
openclaw plugins install @pinchtab/pinchtab

Grok 用户可以从 PinchTab 仓库的市场或直接从 GitHub 安装。请参阅 Grok 插件安装和使用指南。

主要功能

• CLI 或 Curl — 通过命令行或 HTTP API 控制
• 节省 Token — 使用文本提取时每页仅需 800 个 Token（比截图便宜 5–13 倍）
• 无头或有头 — 无窗口运行，或使用可见的 Chrome 运行
• 多实例 — 运行多个并行的 Chrome 进程，并使用隔离的配置文件
• 自包含 — 单个约 30 MB 的二进制文件；驱动本地安装的 Chrome 或 Chromium
• 无障碍优先 — 元素引用指向 DOM 节点而非行：筛选器、选择器或深度变化后，同一个 e5 仍然有效（筛选后的视图是稀疏的），只有导航到新文档时才会失效
• 针对 ARM64 优化 — 全面支持 Raspberry Pi，并自动检测 Chromium
• 支持 CloakBrowser — 可选的即插即用提供程序，适用于会对原版 Chromium 进行指纹识别的网站。PinchTab 会启动用户提供的 CloakBrowser 二进制文件；发布的构件不包含 CloakBrowser。请参阅 docs/guides/cloakbrowser.md。

---

快速开始

安装

macOS / Linux：

curl -fsSL https://pinchtab.com/install.sh | bash

Homebrew（macOS / Linux）：

brew install pinchtab/tap/pinchtab

npm：

npm install -g pinchtab

Agent 技能

npm 包附带 pinchtab Agent 技能，并会在安装和升级时将其复制到检测到的每个 Agent 主目录（~/.claude/skills、~/.cursor/skills、~/.windsurf/skills、~/.codex/skills、OpenClaw），同时打印写入位置。随包提供的副本在 frontmatter 中包含发布版本和内容哈希，因此无需检出源代码即可检测出过期或手动编辑过的副本：

pinchtab skill status           # each detected copy vs the bundled skill; exit 1 if any is stale
pinchtab skill update           # install or refresh; an edited copy is kept and reported
pinchtab skill update --force   # replace an edited copy

在代码库检出目录中，scripts/install-skills.sh 会改为创建指向仓库技能文件的符号链接，使编辑立即生效；同步过程不会通过符号链接写入文件。

平台支持

PinchTab 主要经过测试的操作流程适用于本地 macOS 和 Linux。

虽然会发布 Windows 二进制文件，但目前 Windows 支持有限，尽力提供；这是因为项目在 Windows 上没有同等程度的自动化和手动测试覆盖。在 Windows 上，建议直接运行 pinchtab server 或 pinchtab bridge，而不是依赖守护进程工作流。

在 macOS 上，建议使用专用的自动化浏览器（Google Chrome for Testing 或 Chromium），而不是日常使用的 Google Chrome。在 PinchTab 运行期间，以无头模式驱动主用 Chrome 可能会阻止它打开普通窗口。PinchTab 现在会自动优先选择专用浏览器；如果自动化将回退到主用 Chrome，pinchtab doctor browsers 会发出警告——请安装 Chrome for Testing，或将 browser.binary 设置为另一个构建版本。请参阅 docs/reference/config.md。

Shell 补全

将 pinchtab 加入 PATH 后，生成并安装 Shell 补全：

# Generate and install zsh completions
pinchtab completion zsh > "${fpath[1]}/_pinchtab"

# Generate bash completions
pinchtab completion bash > /etc/bash_completion.d/pinchtab

# Generate fish completions
pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish

Docker：

docker run -d \
  --name pinchtab \
  -p 127.0.0.1:9867:9867 \
  -v pinchtab-data:/data \
  --shm-size=2g \
  pinchtab/pinchtab

随附容器会将其管理的配置持久化到 /data/.config/pinchtab/config.json。 如果要改为提供自己的配置文件，请挂载该文件并将 PINCHTAB_CONFIG 指向它：

docker run -d \
  --name pinchtab \
  -p 127.0.0.1:9867:9867 \
  -e PINCHTAB_CONFIG=/config/config.json \
  -v "$PWD/config.json:/config/config.json:ro" \
  -v pinchtab-data:/data \
  --shm-size=2g \
  pinchtab/pinchtab

使用

第一个实用命令——如有需要，会自动启动本地服务：

pinchtab nav https://pinchtab.com --snap

或者，想在前台查看日志时，显式启动服务：

pinchtab server

推荐用于日常本地使用——只需安装一次守护进程：

pinchtab daemon install
pinchtab daemon

这样 PinchTab 就会在后台运行，你的 Agent 工具无需打开终端即可重复使用它。

终端 2——控制浏览器：

# Navigate; starts the server automatically if needed
pinchtab nav https://pinchtab.com

# Get page structure
pinchtab snap -i -c

# Click an element
pinchtab click e5

# Extract text
pinchtab text

或者直接使用 HTTP API（每个请求都需要服务令牌）：

export PINCHTAB_TOKEN=$(pinchtab config token --stdout)

# Create a profile first (returns profile id)
PROF=$(curl -s -X POST http://localhost:9867/profiles \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"work"}' | jq -r '.id')

# Start an instance for that profile (returns instance id)
INST=$(curl -s -X POST http://localhost:9867/instances/start \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"profileId\":\"$PROF\",\"mode\":\"headless\"}" | jq -r '.id')

# Open a tab in that instance
TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://pinchtab.com"}' | jq -r '.tabId')

# Get snapshot
curl -H "Authorization: Bearer $PINCHTAB_TOKEN" "http://localhost:9867/tabs/$TAB/snapshot?filter=interactive"

# Click element
curl -X POST "http://localhost:9867/tabs/$TAB/action" \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"click","ref":"e5"}'

---

核心概念

服务 — PinchTab 的主进程。它管理配置文件、实例、路由和仪表板。

实例 — 正在运行的 Chrome 进程。每个实例可以关联一个配置文件。

配置文件 — 浏览器状态（Cookie、历史记录、本地存储）。登录一次，重启后仍保持登录状态。

标签页 — 单个网页。每个实例可以有多个标签页。

Bridge — 托管实例背后的单实例运行时。通常由服务启动，无需手动启动。

请阅读核心概念指南，了解更多信息。

---

为什么选择 PinchTab？

方面	PinchTab
令牌性能	✅
无头和有头模式	✅
配置文件	✅
高级 CDP 控制	✅
持久会话	✅
二进制文件大小	✅
多实例	✅
连接外部 Chrome	✅

基准测试：PinchTab 与 agent-browser 对比

测量 Agent 循环端到端的令牌成本（Anthropic API），百分比 表示“在此指标上，PinchTab 比 agent-browser 便宜 N%”：

范围	成本更低	请求更少	令牌更少
基础 Haiku（10 步）	9.5%	23.0%	17.9%
扩展 Haiku（24 步）	19.6%	31.1%	26.2%
扩展 Sonnet（24 步）	20.3%	29.4%	25.3%

随着工作负载时长增加，成本差距会扩大（点击→快照的往返开销 会不断累积），且在扩展范围内基本不受模型影响。

请参阅基准测试摘要了解概览，或参阅 基准测试深入分析了解完整的 方法、各次运行的表格和原始日志。

---

隐私

PinchTab 是一款完全开源、本地优先的工具。它不包含遥测或分析功能，也不依赖任何必需的外部服务。该二进制文件默认绑定到 127.0.0.1。持久配置文件会在本地计算机上存储浏览器会话，这与人们重复使用自己的浏览器类似。远程和分布式部署适用于高级用例，但需要由运维人员明确管理，并非默认配置。这个单一的 Go 二进制文件（约 30 MB）完全可验证：可从源代码构建，源代码位于 github.com/pinchtab/pinchtab。

---

文档

完整文档请访问 pinchtab.com/docs

示例

AI Agent 自动化

# Your AI agent can:
pinchtab nav https://pinchtab.com
pinchtab snap -i  # Get clickable elements
pinchtab click e5 # Click by ref
pinchtab fill e3 "[email protected]"  # Fill input
pinchtab press e7 Enter              # Submit form

数据提取

# Extract text (token-efficient)
pinchtab nav https://pinchtab.com/article
pinchtab text  # ~800 tokens instead of 10,000

多实例工作流

# Run multiple instances in parallel (profiles "alice" and "bob" must already exist — see POST /profiles above)
curl -s -X POST http://localhost:9867/instances/start \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profileId":"alice","mode":"headless"}'

curl -s -X POST http://localhost:9867/instances/start \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profileId":"bob","mode":"headless"}'

# Each instance is isolated
curl -H "Authorization: Bearer $PINCHTAB_TOKEN" http://localhost:9867/instances

请参阅 chrome-files.md，了解 PinchTab 如何管理 Chrome 用户数据目录并确保并行实例之间相互隔离的技术细节。

---

开发

想要参与贡献？请从 CONTRIBUTING.md 开始。 完整的配置与工作流指南请参阅 docs/guides/contributing.md。

快速开始：

git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
./dev doctor                # Verifies environment, offers hooks/deps setup
./dev --help                # Shows the developer toolkit commands
go build ./cmd/pinchtab     # Build pinchtab binary

如需诊断已安装的 PinchTab 和浏览器配置（检查配置文件是否加载、是否找到浏览器且版本符合要求、无头启动是否会暴露 CDP、请求格式是否得到处理；CloakBrowser 还会检查指纹标记和字体），请使用：

pinchtab doctor             # human-readable report
pinchtab doctor --json      # machine-readable
pinchtab doctor --check <name>    # run a single check by name
pinchtab doctor browser <name>    # scope to one browser.targets entry

---

许可证

MIT — 免费开源。

---

开始使用： pinchtab.com/docs