Hermes + PinchTab 浏览器引擎手册 🦎

🦎 Hermes + PinchTab 浏览器引擎手册

版本: 3.2 | 更新日期: 2026-05-18 | 维护人: Hermes Agent

📑 目录

Agent 安装
安装（参考）
配置
MCP 集成
基本使用
已知坑位
安全策略
FAQ
浏览器引擎性能对比
运行时架构
故障排查清单
附录：绕弯方式对比

1. ✅ Agent 安装

1.1 用户发给 Agent 的对话

用户只需发一条消息，Agent 会自动完成全部安装：

安装 pinchtab 到默认路径，注册 MCP，放行所有域名，
禁用原生浏览器，使用已有的 Chromium 引擎

这条消息覆盖了官方推荐的 Agent 安装方式的全部要点：

默认路径 → $HOME/pinchtab/（volume 内）
注册 MCP → args: ["mcp"]，无 wrapper、无 --server
放行所有域名 → pinchtab config set security.allowedDomains '["*"]'
禁用原生浏览器 → disabled_toolsets: [browser, web]
使用已有 Chromium → 复用 Playwright headless shell，不重复下载

1.2 Agent 收到对话后的实际执行

# ── Step 1: 安装 pinchtab ─────────────────────────────────────
cd /opt/data/home
npm init -y
npm install pinchtab

# ── Step 2: 配置安全策略 + 浏览器引擎 ─────────────────────────
pinchtab config set security.allowedDomains '["*"]'
pinchtab config set browser.binary \
  /opt/hermes/.playwright/chromium_headless_shell-1217/chrome-linux/headless_shell

# ── Step 3: 注册 MCP + 禁用原生浏览器 ─────────────────────────
# 修改 config.yaml：
#   mcp_servers:
#     pinchtab:
#       command: /opt/data/home/pinchtab/node_modules/.bin/pinchtab
#       args: ["mcp"]                         # ← 官方推荐，无 --server
#       timeout: 120
#   disabled_toolsets: [browser, web]

# ── Step 4: CLI 验证 ───────────────────────────────────────────
pinchtab nav https://example.com --json
# 返回 { url, title, tabId } 即代表浏览器引擎可用

# ── Step 5: 重启 Gateway ───────────────────────────────────────
fuser -k 9867/tcp 2>/dev/null
systemctl --user restart hermes-gateway

# ── Step 6: 最终验证 ───────────────────────────────────────────
# 确认 mcp_pinchtab_navigate 工具可用

1.3 红线速查

红线	正确做法	错误后果
安装路径	`$HOME/pinchtab/`（volume 内）	换环境文件丢失
安全策略	`pinchtab config set ...`（CLI 持久化）	无法访问外部网站
MCP 参数	`args: ["mcp"]`，无额外参数	stdout 污染，MCP 断开
运行模式	MCP stdio 直调，不用 server daemon	实例卡在 stopping
浏览器引擎	复用已有 Chromium	多下载 300MB

1.4 验证清单

#	检查项	通过标准
1	`pinchtab --version`	0.12.0+
2	`pinchtab nav https://example.com --json`	返回页面 title/url
3	Gateway 重启成功	无异常日志
4	MCP 工具可用	"打开 example.com" 正常
5	无需手动创建 config.json	自动生成
6	无需 security down	config set 持久化
7	无需手动管理进程	Hermes MCP 自动管理

2. 📦 安装（参考）

2.1 官方一键安装

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

（可能需 sudo。Docker 内推荐 npm 方式）

2.2 二进制安装（当前环境使用）

# 当前环境使用从 GitHub releases 下载的独立二进制
# 路径: /opt/data/mcp/pinchtab/pinchtab
# 版本: v0.13.0
# 来源: GitHub releases → pinchtab-linux-amd64

2.3 npm 安装（Docker 环境推荐）

cd $HOME && npm init -y && npm install pinchtab

路径：永远用 $HOME/pinchtab/（Docker 中为 /opt/data/home/pinchtab/）。不要用 /www/。

2.4 验证安装

./node_modules/.bin/pinchtab --version

2.5 浏览器引擎

PinchTab 需要 Chromium。Hermes Docker 环境可复用 Playwright 头壳：

/opt/hermes/.playwright/chromium_headless_shell-1217/chrome-linux/headless_shell

当前环境实际 Chromium 路径：

/opt/data/home/.local/share/playwright/chromium-1217/chrome-linux64/chrome

Chromium 版本：144.0.7559.133（Playwright 捆绑版）
如无 Playwright，PinchTab 会自动下载。

3. ⚙️ 配置

3.1 PinchTab 自身配置

配置文件 ~/.pinchtab/config.json 首次运行自动生成。

pinchtab config set security.allowedDomains '["*"]'        # 放行所有域名
pinchtab config set browser.binary /path/to/chromium       # 指定浏览器
pinchtab config set server.port 9868                       # 换端口
pinchtab config list                                       # 查看配置

3.2 Hermes MCP 配置

mcp_servers:
  pinchtab:
    command: /opt/data/mcp/pinchtab/pinchtab
    args: ["mcp"]                # ← 只能写 mcp
    timeout: 120
disabled_toolsets: [browser, web]

4. 🔌 MCP 集成

4.1 启动方式

Hermes 通过 stdio 直调 pinchtab mcp，无 wrapper、无 --server。这是官方推荐的 Agent MCP 模式。

4.2 MCP 工具清单

mcp_pinchtab_navigate — 导航到 URL
mcp_pinchtab_click — 点击页面元素
mcp_pinchtab_screenshot — 页面截图
mcp_pinchtab_snap — 获取页面结构
mcp_pinchtab_back / forward — 前进后退
mcp_pinchtab_console — 控制台日志
mcp_pinchtab_cookies — Cookies 管理
mcp_pinchtab_download / pdf — 文件导出

共计约 38 个工具（导航、交互、键盘、内容、标签管理、等待、网络、对话框）

5. 🛠️ 基本使用

pinchtab nav https://example.com --json     # 导航
pinchtab snap                                # 页面结构
pinchtab screenshot -o page.png              # 截图
pinchtab tabs                                # 列出标签页
pinchtab instances --json                    # 实例状态

6. 🕳️ 已知坑位

#	坑	现象	原因	解决
1	security 锁死	外部网站空或 503	默认 localhost only	`pinchtab config set security.allowedDomains '["*"]'`
2	--server 污染 stdout	MCP 连接后断开	stdout 出非 JSON 行	args 只写 `["mcp"]`
3	daemon 实例卡死	实例永远 stopping	daemon 状态管理 bug	不用 daemon，MCP stdio
4	端口 9867 冲突	重启后连不上	旧进程未退出	`fuser -k 9867/tcp`
5	首次 503	第一个 nav 报错	初始化需 3-5 秒	等待重试
6	装到 /www/	换环境丢失	不在 volume 内	用 `$HOME/pinchtab/`

7. 🔒 安全策略

# ✅ 持久化修改
pinchtab config set security.allowedDomains '["*"]'

# ❌ 不要用 security down（重启后失效）

保持 loopback 绑定 server.bind = 127.0.0.1。

8. ❓ FAQ

Q: 官方有 Agent 安装文档吗？

GitHub 仓库有 skills/pinchtab/SKILL.md + docs/guides/mcp-agents.md。网站 pinchtab.com/docs 有 Humans/Agents 模式切换。

Q: 503 和 security 什么关系？

两个原因：① allowedDomains 没配（永久）；② 实例初始化延迟（3-5 秒瞬态）。先查 security。

Q: 需要手动管理 server 进程吗？

不需要。Hermes MCP 自动管理 stdio 子进程。

Q: MCP 报 Connection closed？

① args 有没有 --server；② 端口 9867 是否被占。然后重启 Gateway。

Q: 总占多少空间？

npm ~50MB + Go 二进制 ~70MB + Chromium ~279MB ≈ 400MB。

Q: PinchTab vs Playwright vs Agent-Browser 性能如何？

详见下方 #9 浏览器引擎性能对比

9. 📊 浏览器引擎性能对比

测试日期：2026-05-18 | 环境：Hermes Agent v2026.5.16, aarch64 Linux (Docker), 4-Core, 22GB RAM

Chromium：Playwright 捆绑版 headless_shell (Chrome 144) — 三引擎复用同一二进制

方法：每个 URL 连续测试 3 次（warm），取均值；等待策略 DOMContentLoaded；跳过冷启动首次

9.1 导航性能（毫秒，越低越好）

引擎	Simple example.com	Medium httpbin/html	Complex Wikipedia	平均	相对
🏆 Pinchtab 0.12.0 Go + Chrome CDP	224ms	528ms	560ms	437ms	1.0x
Playwright 1.59.0 Python + Chrome CDP	517ms	1,477ms	1,307ms	1,100ms	2.5x
Agent-Browser 0.27.0 Node.js + Hermes Native	999ms	1,293ms	1,617ms	1,303ms	3.0x

9.2 冷启动性能

引擎	冷启动（首次导航）	说明
Pinchtab	961ms	Go server 启动 + Chrome CDP 连接 + 导航；后续导航复用实例仅 ~224ms
Playwright	517ms*	*每个测试固有包含了 Python 启动 + 浏览器进程启动，无法避免每次往返
Agent-Browser	1,048ms	npx 命中缓存后 Node.js 启动 + Agent-Browser 初始化 + Chrome 启动 + 导航

9.3 内容提取性能

引擎	Snap 耗时	输出量	说明
Pinchtab snap	2,804ms	~49KB DOM 树	aria 可访问性树提取，包含元素 ref 定位信息
Playwright content()	即时	~617KB（Wikipedia）	全量 HTML，无结构摘要
Agent-Browser	N/A	N/A	需要 snap 命令，测试时未安装浏览器（ARM64 不兼容）

9.4 资源占用

引擎	二进制/包体积	+ Chromium	进程模型	说明
Pinchtab	19MB (Go 单文件)	279MB	常驻 daemon	Go 静态编译，零依赖；二进制最小
Playwright	133MB (Python)	279MB	每次启动新进程	Python 含完整浏览器驱动
Agent-Browser	162MB (npm + Node.js)	279MB	每次启动新进程	需要 Node.js 运行时；npx 缓存需另计

9.5 分析

为什么 Pinchtab 快这么多？

Go 静态编译 — 单二进制，无解释器/VM 开销，启动即毫秒级
常驻 daemon 架构 — Server + Bridge + Chrome 持续运行，后续导航只需 HTTP API 调用（~224ms），非每次重新启动整个浏览器
简洁的 MCP 桥接 — MCP stdio → Bridge HTTP → Chrome CDP，链路最短

Playwright 的优劣

优：Python API 功能最全，内容提取（content()/text()）无需额外调用
劣：每次调用的 Python 进程启动 + 浏览器 launch 开销约 300-500ms，即使只是简单导航
劣：variance 大（如 medium 页面 983-1989ms），受 Python GC 影响

Agent-Browser（Hermes 原生）的优劣

劣：Node.js 启动 + npx 解析 + Agent-Browser JS 初始化，三项叠加约 500ms 固定开销
劣：v2026.5.16 在 ARM64 上无法自动下载 Chrome（Chrome for Testing 不提供 ARM64 构建），需手动 --executable-path
优：内容提取使用 aria 可访问性树（带元素 ref），比完整 HTML 更友好
优：variance 最小 — 所有 URL 的导航时间接近（99%+ vs 864ms），说明瓶颈在初始化层而非网络

9.6 结论

Pinchtab 在导航性能上是 Playwright 的 2.5 倍、Agent-Browser 的 3 倍。

如果你的 Hermes Agent 需要频繁进行浏览器操作（导航、点击、数据提取），推荐使用 Pinchtab 作为 MCP 浏览器引擎，禁用原生 browser 工具集，并在 MCP 中配置 Pinchtab。

Playwright 适合需要完整 Python 控制能力的场景；Agent-Browser（原生 browser 工具）适合临时轻量浏览。

10. 🏗️ 运行时架构

10.1 进程拓扑

Hermes Agent (MCP Client)
    │  stdio (JSON-RPC)
    ▼
PinchTab MCP Server (`pinchtab mcp`)
    │  HTTP API (localhost:9867)
    ▼
PinchTab Bridge Process
    │  CDP (Chrome DevTools Protocol)
    ▼
Chromium Browser (headless, PID 83+)

PinchTab 以 server --background-child 模式运行，自动管理子进程生命周期。Bridge 进程负责 MCP stdio 与 Chrome CDP 之间的桥接。

10.2 进程层级详解

PID	进程	用途	端口
62	`pinchtab server --background-child`	主服务进程（HTTP API + Dashboard）	9867
71	`pinchtab bridge`	Bridge 进程，连接 MCP 与 Chrome	—
83	`chrome` (main)	Chromium 主进程	9869 (CDP)
89, 91	`chrome --type=zygote`	Zygote 沙箱进程	—
121	`chrome --type=utility (network)`	网络服务	—
123	`chrome --type=utility (storage)`	存储服务	—
155+	`chrome --type=renderer`	渲染进程（每个标签页一个）	9869 (CDP)

10.3 安装与版本

二进制路径	`/opt/data/mcp/pinchtab/pinchtab`
版本	v0.13.0
来源	GitHub releases（pinchtab-linux-amd64）
配置目录	`/opt/data/home/.pinchtab/`
Profile 目录	`/opt/data/home/.pinchtab/profiles/default`
Extensions	`/opt/data/home/.pinchtab/extensions`

10.4 浏览器配置

Chromium 路径	`/opt/data/home/.local/share/playwright/chromium-1217/chrome-linux64/chrome`
Chromium 版本	144.0.7559.133（Playwright 捆绑版）
运行模式	headless=new
窗口尺寸	1280×800（虚拟），800×600（ozone-override）
语言	en-US
User-Agent	`Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.7559.133 Safari/537.36`
隐身级别	light
沙箱	`--no-sandbox`（容器/无 root 环境必需）

10.5 关键配置项

来源：/opt/data/home/.pinchtab/config.json

Server

server.port	9867
server.bind	127.0.0.1
server.token	自动生成的认证 token
server.stateDir	/opt/data/home/.pinchtab

Security

security.allowedDomains	["*"]（已放开，默认仅 localhost）
security.idpi.enabled	true（内容检测）
security.idpi.strictMode	true
trustedProxyCIDRs	["192.168.1.120/32"]
trustedResolveCIDRs	["192.168.0.0/16", "10.0.0.0/8", "172.16.0.0/12"]
allowEvaluate / Macro / Screencast / Download / Cookies / NetworkIntercept / Upload / Clipboard / StateExport	全部 false

Multi-Instance

strategy	always-on
allocationPolicy	fcfs（先到先得）
端口范围	9868–9968
重启策略	max 20 次，初始退避 2s，最大 60s

超时

actionSec	30s
navigateSec	60s
shutdownSec	10s

10.6 关键文件与路径

路径	用途	重要性
`/opt/data/home/.pinchtab/config.json`	Server 实际使用的配置	⭐⭐⭐ 最高优先级
`/opt/data/home/.pinchtab/server.pid`	Server PID 和 token 文件	⭐⭐⭐ 运行时读取
`/opt/data/home/.pinchtab/server.log`	Server 日志	⭐⭐ 调试用
`/opt/data/.pinchtab/config.json`	MCP 工具读取的配置	⭐⭐⭐ 必须同步
`/opt/data/.pinchtab/instances/`	实例状态目录	⭐⭐ 清理 error 实例
`/opt/data/.pinchtab/profiles/default/`	用户数据目录	⭐⭐ 浏览器 profile
`/opt/data/mcp/pinchtab/pinchtab`	PinchTab 二进制	⭐⭐⭐ v0.13.0
`~/.hermes/config.yaml`	Hermes 的 MCP 配置	⭐⭐ MCP 连接配置

10.7 Token 鉴权链路

1. Server 启动时生成 token (或从 config 读取)
   ↓
2. token 写入 /opt/data/home/.pinchtab/server.pid
   ↓
3. token 也写入 /opt/data/.pinchtab/config.json (需手动同步)
   ↓
4. MCP 工具从 /opt/data/.pinchtab/config.json 读取 token
   ↓
5. 所有 HTTP 请求携带 Authorization: Bearer <token>
   ↓
6. Server 验证 token → 转发到 bridge → 转发到 Chrome

⚠️ 关键坑点：两个 config.json 必须同步！

10.8 端口分配

端口	服务	用途
9867	Server	中央控制面（health, navigate, tabs）
9868	Bridge	实例代理（转发 CDP 命令）
9869	Chrome	远程调试端口（CDP）
9888	Profile Server	用户数据同步（通常不跑）

10.9 正常调用链路

导航：Hermes 调用 mcp_pinchtab_navigate(url) → MCP stdio → pinchtab bridge → HTTP API POST /api/browser/navigate → Chromium 导航到目标 URL
快照：Hermes 调用 mcp_pinchtab_snapshot(compact=true) → 获取页面 DOM 结构 + 元素 refs（e1, e2, ...）→ 支持 compact/text 两种输出格式
交互：Hermes 调用 mcp_pinchtab_click(selector="e5") 或 mcp_pinchtab_type(...) → 通过 CDP 协议操作页面元素
等待/验证：mcp_pinchtab_wait_for_selector / wait_for_text / network 等

10.10 健康检查

curl http://127.0.0.1:9867/health
# → {"status":"ok","mode":"dashboard","version":"0.13.0","authRequired":true}

11. 🔧 故障排查清单

11.1 401 missing_token / bad_token

症状：所有 API 返回 401

根因：两个 config.json 中 token 不一致

解决：手动同步 /opt/data/home/.pinchtab/config.json 中的 token 到 /opt/data/.pinchtab/config.json

11.2 MCP 导航失败

检查项：MCP 导航

命令：pinchtab nav https://example.com

预期结果：成功

失败排查：检查安全策略 → 检查端口 9867 是否在监听 → 检查 Chrome 二进制路径

11.3 MCP 快照失败

检查项：MCP 快照

命令：pinchtab snapshot

预期结果：返回页面节点

失败排查：先确认 nav 成功 → 检查 bridge (9868) 是否运行 → 检查 Chrome CDP 端口 (9869)

11.4 Token 同步检查

检查项：Token 同步

命令：对比两个 config

预期结果：token 一致

cat /opt/data/home/.pinchtab/config.json | grep token
cat /opt/data/.pinchtab/config.json | grep token

11.5 排查要点汇总

问题	排查方向
MCP 工具不可用	检查 Hermes 是否重新加载了 MCP 配置
连接失败	确认 pinchtab server 进程在运行（PID 62）
CDP 连接失败	检查 Chromium 主进程（PID 83）是否存活，端口 9869 是否监听
域名被拒	检查 security.allowedDomains 配置
Token 认证	HTTP API 调用需 `Authorization: Bearer <token>` 头
内存占用过高	每个渲染进程约 100-170MB，多标签页场景注意内存
无系统 Chrome	使用 Playwright 捆绑版，不要依赖 /usr/bin/chrome

12. 附录：绕弯方式对比

以下方式不推荐，仅供对照：

❌ 方式 A：装到 /www/kc-ai-hermes/pinchtab/

不在 volume 中，重建丢失。

❌ 方式 B：用 `pinchtab security down`

重启后失效。

❌ 方式 C：MCP args 加 `--server`

stdout 出 HINT: 非 JSON 行，MCP 断开。

❌ 方式 D：bash wrapper script

引入环境差异，更难排查。

❌ 方式 E：`pinchtab server` 守护进程

实例可能卡 stopping。官方说 daemon "not normal agent workflow"。

❌ 方式 F：手动创建 config.json

自动生成，所有修改用 pinchtab config set。

— 本文档由 Hermes Agent 维护于 Trilium | v3.2 新增浏览器引擎性能对比（Pinchtab vs Playwright vs Agent-Browser）