pinchtab

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PinchTab — Browser Automation for AI Agents

PinchTab — 面向AI Agent的浏览器自动化

Control Chrome browsers via PinchTab's CLI and HTTP API. Token-efficient (~800 tokens/page), fast startup, stable element references, built-in stealth.

通过PinchTab的CLI和HTTP API控制Chrome浏览器。Token利用率高（每页约800个Token）、启动速度快、元素引用稳定、内置隐身模式。

Prerequisites

前置条件

bash

undefined

bash

undefined

Install (pick one)

安装（选择一种方式）

curl -fsSL https://pinchtab.com/install.sh | bash brew install pinchtab/tap/pinchtab npm install -g pinchtab

Start server (skip if already running)

启动服务器（若已运行可跳过）

pinchtab server & curl -s http://localhost:9867/health

undefined

pinchtab server & curl -s http://localhost:9867/health

undefined

Core Concepts

核心概念

Server → Profile (prof_XXX) → Instance (inst_XXX) → Tab (tab_XXX) → Element Refs (e0, e1, e5)

Profile — Persistent browser data (cookies, storage). Reuse profiles to keep login sessions alive.
Instance — Running Chrome process (max 1 per profile).
Element Ref — Stable IDs from snapshots for clicking/filling. Re-snapshot after page changes because refs become stale.

Server → Profile (prof_XXX) → Instance (inst_XXX) → Tab (tab_XXX) → Element Refs (e0, e1, e5)

Profile — 持久化浏览器数据（Cookie、存储）。复用配置文件可保持登录会话。
Instance — 运行中的Chrome进程（每个配置文件最多1个）。
Element Ref — 快照生成的稳定ID，用于点击/填写操作。页面变更后需重新生成快照，因为旧引用会失效。

Choosing the Right Approach

选择合适的实现方式

Situation	Approach	Why
Hầu hết tasks	CLI	Đơn giản, không cần parse JSON, 1 lệnh = 1 hành động
Cần batch actions hoặc tích hợp script	HTTP API	Batch/macro endpoint giảm request overhead
Chỉ cần đọc nội dung trang	`pinchtab text`	Token-efficient nhất (~800 tokens)
Cần tương tác (click, fill)	`pinchtab snap -ic` → action	Compact interactive snapshot cho refs, rồi act
Sau khi thực hiện action	`pinchtab snap -d`	Diff snapshot — chỉ lấy thay đổi, tiết kiệm token
Cần debug visual	`pinchtab screenshot`	Token cost cao — chỉ dùng khi text/snap không đủ
Site có bot detection	Bật stealth trước	`pinchtab config set chrome.stealth light`

场景	方法	原因
大多数任务	CLI	简单易用，无需解析JSON，一条命令对应一个操作
需要批量操作或脚本集成	HTTP API	批量/宏端点减少请求开销
仅需读取页面内容	`pinchtab text`	最节省Token（约800个Token）
需要交互（点击、填写）	`pinchtab snap -ic` → 执行操作	生成紧凑的交互式快照获取元素引用，再执行操作
执行操作后	`pinchtab snap -d`	差异快照——仅获取变化内容，节省Token
需要可视化调试	`pinchtab screenshot`	Token成本高——仅在文本/快照不足以排查问题时使用
网站存在机器人检测	提前开启隐身模式	`pinchtab config set chrome.stealth light`

CLI Workflow (Default)

CLI工作流（默认）

bash

undefined

bash

undefined

1. Navigate

1. 导航

pinchtab nav https://example.com

2. Read content (chọn 1)

2. 读取内容（选择一种）

pinchtab text # plain text — most efficient pinchtab snap -ic # interactive elements only — for interaction pinchtab quick <url> # navigate + snapshot in one command

pinchtab text # 纯文本——效率最高 pinchtab snap -ic # 仅交互式元素——用于交互操作 pinchtab quick <url> # 一步完成导航+快照

3. Interact

3. 交互操作

pinchtab fill e3 "value" # fill field (clears first) pinchtab click e5 # click element pinchtab press Enter # keyboard key

pinchtab fill e3 "value" # 填写字段（先清空原有内容） pinchtab click e5 # 点击元素 pinchtab press Enter # 触发键盘按键

4. Verify result

4. 验证结果

sleep 1 # wait for page update pinchtab snap -d # diff snapshot — only changes

undefined

sleep 1 # 等待页面更新 pinchtab snap -d # 差异快照——仅获取变化内容

undefined

Multi-Tab

多标签页操作

bash

pinchtab tab new https://source.com    # open new tab
pinchtab tab                           # list tabs with IDs
pinchtab tab tab_XXX                   # switch to tab
pinchtab tab close tab_XXX             # close tab

bash

pinchtab tab new https://source.com    # 打开新标签页
pinchtab tab                           # 列出所有标签页及ID
pinchtab tab tab_XXX                   # 切换到指定标签页
pinchtab tab close tab_XXX             # 关闭指定标签页

Security Gates

安全权限

5 tính năng nhạy cảm bị tắt mặc định. Nếu dùng upload, download, eval, macro, hoặc screencast mà bị lỗi, bật gate tương ứng:

bash

pinchtab config set security.allowUpload true      # cho pinchtab upload
pinchtab config set security.allowDownload true     # cho pinchtab download
pinchtab config set security.allowEvaluate true     # cho pinchtab eval
pinchtab config set security.allowMacro true        # cho POST /macro
pinchtab config set security.allowScreencast true   # cho pinchtab screencast

Upload limits mặc định: 5 MB/file, 8 file/request, 10 MB tổng.

Lưu ý PinchTab 0.10+:

GET /api/config

trả config dạng nested (

config.security.allowUpload

) thay vì flat (

security.allowUpload

). Script cần hỗ trợ cả hai format khi kiểm tra permission. Setting áp dụng ngay sau

pinchtab config set

, không cần restart server.

5个敏感功能默认关闭。如果使用上传、下载、eval、宏或录屏功能时出现错误，请开启对应的安全权限：

bash

pinchtab config set security.allowUpload true      # 允许PinchTab上传文件
pinchtab config set security.allowDownload true     # 允许PinchTab下载文件
pinchtab config set security.allowEvaluate true     # 允许PinchTab执行eval
pinchtab config set security.allowMacro true        # 允许调用POST /macro接口
pinchtab config set security.allowScreencast true   # 允许PinchTab录屏

默认上传限制：单文件5MB，单次请求最多8个文件，总大小10MB。

注意 PinchTab 0.10+版本：

GET /api/config

返回嵌套格式的配置（

config.security.allowUpload

）而非扁平格式（

security.allowUpload

）。脚本在检查权限时需同时支持两种格式。配置在执行

pinchtab config set

后立即生效，无需重启服务器。

Error Recovery

错误恢复

Lỗi phổ biến nhất: stale element refs (action fail vì trang đã thay đổi).

Action fail → re-snapshot (pinchtab snap -ic) → retry với ref mới

Lỗi	Xử lý
Element ref not found	Re-snapshot, dùng ref mới
Upload/Download/Eval fail	Bật security gate tương ứng (xem mục trên)
Server not running	`pinchtab server &`
Instance won't start	Kiểm tra `pinchtab instances` , stop instance cũ nếu cần
Bot detection	`pinchtab config set chrome.stealth light` + `--humanize` flag

最常见的错误：元素引用过期（因页面已变更导致操作失败）。

操作失败 → 重新生成快照（pinchtab snap -ic） → 使用新引用重试

错误	处理方式
找不到元素引用	重新生成快照，使用新的元素引用
上传/下载/Eval操作失败	开启对应的安全权限（见上文）
服务器未运行	执行 `pinchtab server &` 启动服务器
实例无法启动	检查 `pinchtab instances` ，如有需要停止旧实例
触发机器人检测	执行 `pinchtab config set chrome.stealth light` 并添加 `--humanize` 参数

Environment Variables

环境变量

Variable	Purpose	Default
`PINCHTAB_PORT`	Server port	9867
`PINCHTAB_TOKEN`	API auth token (thêm `-H "Authorization: Bearer $TOKEN"` nếu set)	(none)
`PINCHTAB_HEADLESS`	Headless mode	true

环境变量	用途	默认值
`PINCHTAB_PORT`	服务器端口	9867
`PINCHTAB_TOKEN`	API认证令牌（设置后需添加 `-H "Authorization: Bearer $TOKEN"` 请求头）	无
`PINCHTAB_HEADLESS`	无头模式	true

Reference

参考资料

Chi tiết tra cứu khi cần:

HTTP API — Endpoints, payloads, response formats, error codes. Đọc khi cần gọi HTTP API trực tiếp.
CLI commands — Tất cả CLI commands + flags. Đọc khi cần tìm lệnh cụ thể hoặc flags nâng cao.
Workflow patterns — 12 patterns phổ biến (scraping, login, pagination, stealth, multi-tab...). Đọc khi gặp scenario phức tạp cần tham khảo.

需要时可查阅以下详细资料：

HTTP API — 端点、请求体、响应格式、错误码。直接调用HTTP API时阅读。
CLI命令 — 所有CLI命令及参数。查找特定命令或高级参数时阅读。
工作流模式 — 12种常见模式（数据爬取、登录、分页、隐身模式、多标签页等）。遇到复杂场景需要参考时阅读。