这里写目录标题Agent 使用agent-browser卡死问题排查与修复一、问题描述二、什么是 agent-browser三、问题排查过程3.1 第一反应检查 agent-browser 是否安装正确3.2 深入分析agent-browser 和 Hermes 的关系3.3 真相大白四、解决方案4.1 核心思路4.2 具体步骤4.3 便捷启动脚本五、问题原因与原理深度解析5.1 为什么 Hermes 浏览器工具会卡死5.2 什么是 CDP5.3 架构对比5.4 所以 agent-browser 到底用在哪5.5 一张图总结六、经验教训七、相关资源Agent 使用agent-browser卡死问题排查与修复当你给 AI 装上了手它却僵在半空中——记一次 Hermes CN Desktop 浏览器工具卡死的完整排查过程一、问题描述Windows 电脑上使用Hermes CN Desktop一个开源的Hermes AI Agent 第三方桌面端。为了让它能操控浏览器我安装了agent-browser这个工具。但是只要 Agent 调用浏览器相关的功能比如打开网页、截图、点击等终端就会卡死——没有错误提示、没有超时退出就那样一直挂着不动。二、什么是 agent-browseragent-browser是一个Node.js 命令行工具专门为 AI Agent 设计的浏览器自动化工具。它由 GoPlay 团队开发通过 npm 全局安装npminstall-gagent-browser它的核心能力能力说明 网页导航用open命令打开任意 URL️ 页面交互click、type、fill、scroll等模拟人工操作 内容获取snapshot获取无障碍树AI 可读、screenshot截图 AI 集成专门为 LLM/AI Agent 优化的输出格式ref 编号等 持久会话浏览器以守护进程运行可跨命令复用它底层使用的是 Google 的Puppeteer库来操控 Chrome 浏览器。三、问题排查过程3.1 第一反应检查 agent-browser 是否安装正确$npmlist-gagent-browser ├── agent-browser0.27.1# ✅ 已安装$ agent-browser doctor# 输出显示# ✅ CLI version 0.27.1# ✅ Chrome 已安装 (148.0.7778.217)# ✅ Headless launch 测试通过 (0.70s)# ✅ 守护进程运行中 (pid 436)一切正常那为什么 Hermes 用它还是会卡死3.2 深入分析agent-browser 和 Hermes 的关系这里有一个关键认知偏差我以为安装了agent-browserHermes 就会自动使用它。但实际并非如此。Hermes CN Desktop 是一个Python 应用程序用 Nuitka 编译成了 Windows 独立可执行文件它有自己的浏览器工具系统Hermes 浏览器系统结构 ├── browser_navigate() ← Python 实现的工具函数 ├── browser_click() ← Python 实现的工具函数 ├── browser_type() ← Python 实现的工具函数 ├── browser_snapshot() ← Python 实现的工具函数 │ ├── 浏览器后端引擎 (engine) │ ├── browser-use (Cloud) ❌ 损坏缺少 __init__.py │ ├── browserbase (Cloud) ❌ 损坏缺少 __init__.py │ └── firecrawl (Cloud) ❌ 损坏缺少 __init__.py │ └── 本地连接方式 └── CDP (Chrome DevTools Protocol) ← 这才是关键3.3 真相大白agent-browsernpm 包和 Hermes 的浏览器工具Python 内置是两个独立的系统。Hermes 并不知道也不使用 npm 的agent-browser。Hermes 的浏览器工作方式是通过CDPChrome DevTools Protocol连接到一个正在运行的 Chrome 浏览器通过 WebSocket 发送指令导航、点击、截图等通过 WebSocket 接收结果而配置文件中的cdp_url是空的browser:cdp_url:# ← 空的Hermes 不知道连谁engine:auto# 自动检测当cdp_url为空时Hermes 尝试自动启动浏览器——但在 Windows 编译版中这个启动过程挂起了导致终端工具卡死。四、解决方案4.1 核心思路启动 Chrome 浏览器并启用 CDP远程调试端口然后在 Hermes 配置中指定这个连接地址。4.2 具体步骤第一步以 headless 模式启动 Chrome不弹窗口/c/Program Files/Google/Chrome/Application/chrome.exe\--remote-debugging-port9222\--headless\--no-first-run\--no-default-browser-check\--user-data-dir$HOME/.agent-browser/profiles/hermes\--disable-gpu\about:blank参数说明--remote-debugging-port9222— 开启 CDP 端口--headless— 无界面模式不弹窗口--user-data-dir— 独立的 Chrome 用户数据目录不影响日常浏览第二步验证 CDP 是否正常curlhttp://127.0.0.1:9222/json/version返回示例{Browser:Chrome/148.0.7778.217,webSocketDebuggerUrl:ws://127.0.0.1:9222/devtools/browser/...}第三步修改 Hermes 配置编辑config.yaml路径见下方将browser.cdp_url设置为 Chrome 的 CDP 地址browser:cdp_url:http://127.0.0.1:9222# ← 告诉 Hermes 浏览器在哪command_timeout:60# ← 操作超时从30秒增加到60秒inactivity_timeout:300# ← 闲置超时增加到5分钟engine:auto配置文件位置C:\Users\用户名\AppData\Roaming\cn.org.hermesagent.desktop\runtime\hermes-home\config.yaml第四步重启 Hermes 会话在 Hermes 中输入/reset或退出重开配置即可生效。4.3 便捷启动脚本创建一个批处理文件start-chrome-cdp.bat双击即可启动echo off start /b C:\Program Files\Google\Chrome\Application\chrome.exe ^ --remote-debugging-port9222 ^ --headless ^ --no-first-run ^ --no-default-browser-check ^ --user-data-dir%USERPROFILE%\.agent-browser\profiles\hermes ^ --disable-gpu ^ about:blank echo Chrome headless started with CDP on port 9222五、问题原因与原理深度解析5.1 为什么 Hermes 浏览器工具会卡死正常流程 Hermes 调用 browser_navigate() → 检查 cdp_url有值 → 连接 Chrome CDP → 发送命令 → 获取结果 → ✅ 正常返回 卡死流程 Hermes 调用 browser_navigate() → 检查 cdp_url为空 → 尝试自动启动浏览器子进程 → 子进程启动失败/挂起Windows 编译版问题 → terminal 工具一直等待子进程返回 → 无限卡死 5.2 什么是 CDPCDP Chrome DevTools ProtocolChrome 开发者工具协议它是 Chrome 浏览器暴露的一个底层控制接口。你在 Chrome 中按 F12 打开开发者工具时实际上就在使用 CDP——只不过 DevTools 是图形界面版的 CDP 客户端。CDP 能做的事情你的程序 → [HTTP/WebSocket] → ChromeCDP 端口 9222 ├── Page.navigate() 打开网页 ├── Runtime.evaluate() 执行 JS ├── DOM.getDocument() 获取 DOM 树 ├── Input.dispatchMouseEvent 模拟鼠标点击 ├── Input.dispatchKeyEvent 模拟键盘输入 ├── Page.captureScreenshot() 截图 └── ...CDP 暴露了超过 200 个不同的命令覆盖了浏览器能力的方方面面。5.3 架构对比❌ 我以为的工作方式 我安装 agent-browser (npm) → Hermes (Python) 自动使用它 → 操控浏览器 ✗ 实际Hermes 根本不知道 agent-browser 的存在 ✅ 实际的工作方式 我启动 Chrome (带 --remote-debugging-port9222) → Chrome 在 9222 端口开放 CDP 接口 → Hermes 通过 WebSocket 连接 CDP → 直接操控浏览器 ✓ Hermes 内置工具本来就用 CDP不需要 agent-browser5.4 所以 agent-browser 到底用在哪agent-browser作为一个备选方案当 Hermes 内置的浏览器工具遇到反爬检测、验证码等问题时可以通过terminal工具直接调用agent-browser命令来绕过# 通过 Hermes 的 terminal 工具调用 agent-browseragent-browseropenhttps://example.com agent-browser snapshot-i5.5 一张图总结┌─────────────────────────────────────────────────────┐ │ 你的 Windows 电脑 │ │ │ │ ┌─────────────────┐ ┌─────────────────────────┐ │ │ │ Hermes Agent │ │ Chrome 浏览器 │ │ │ │ (Python 编译版) │ │ │ │ │ │ │ │ --remote-debugging- │ │ │ │ browser_ │────→│ port9222 │ │ │ │ navigate() 等 │ CDP │ (Headless 后台运行) │ │ │ │ │ │ │ │ │ └─────────────────┘ └─────────────────────────┘ │ │ │ │ ┌─────────────────┐ │ │ │ agent-browser │ (备选方案通过 terminal 调用) │ │ │ npm 包 v0.27.1 │ │ │ └─────────────────┘ │ └─────────────────────────────────────────────────────┘六、经验教训不要假设——安装了 A 工具不代表 B 工具会自动使用它。理解组件之间的关系很重要。查日志——Hermes 的agent.log和errors.log揭示了浏览器插件加载失败的信息早看能早定位问题。理解协议——CDP 是浏览器自动化的基石。不管是 Selenium、Puppeteer、Playwright 还是agent-browser底层都是 CDP。编译版软件的限制——Hermes CN Desktop 是编译后的二进制文件不能像源码版那样直接 pip install 包来修复问题需要通过配置绕行。七、相关资源资源链接Hermes Agent 官方文档https://hermes-agent.nousresearch.com/docsagent-browser 项目npm install -g agent-browserChrome DevTools Protocolhttps://chromedevtools.github.io/devtools-protocol/本文对应的 Hermes 技能skill_view(nameagent-browser-setup)文章写完于 2026-06-07。如果你也遇到同样的问题希望这篇文章能帮你省下几个小时。
Agent 使用agent-browser卡死问题排查与修复
发布时间：2026/6/8 6:39:37
这里写目录标题Agent 使用agent-browser卡死问题排查与修复一、问题描述二、什么是 agent-browser三、问题排查过程3.1 第一反应检查 agent-browser 是否安装正确3.2 深入分析agent-browser 和 Hermes 的关系3.3 真相大白四、解决方案4.1 核心思路4.2 具体步骤4.3 便捷启动脚本五、问题原因与原理深度解析5.1 为什么 Hermes 浏览器工具会卡死5.2 什么是 CDP5.3 架构对比5.4 所以 agent-browser 到底用在哪5.5 一张图总结六、经验教训七、相关资源Agent 使用agent-browser卡死问题排查与修复当你给 AI 装上了手它却僵在半空中——记一次 Hermes CN Desktop 浏览器工具卡死的完整排查过程一、问题描述Windows 电脑上使用Hermes CN Desktop一个开源的Hermes AI Agent 第三方桌面端。为了让它能操控浏览器我安装了agent-browser这个工具。但是只要 Agent 调用浏览器相关的功能比如打开网页、截图、点击等终端就会卡死——没有错误提示、没有超时退出就那样一直挂着不动。二、什么是 agent-browseragent-browser是一个Node.js 命令行工具专门为 AI Agent 设计的浏览器自动化工具。它由 GoPlay 团队开发通过 npm 全局安装npminstall-gagent-browser它的核心能力能力说明 网页导航用open命令打开任意 URL️ 页面交互click、type、fill、scroll等模拟人工操作 内容获取snapshot获取无障碍树AI 可读、screenshot截图 AI 集成专门为 LLM/AI Agent 优化的输出格式ref 编号等 持久会话浏览器以守护进程运行可跨命令复用它底层使用的是 Google 的Puppeteer库来操控 Chrome 浏览器。三、问题排查过程3.1 第一反应检查 agent-browser 是否安装正确$npmlist-gagent-browser ├── agent-browser0.27.1# ✅ 已安装$ agent-browser doctor# 输出显示# ✅ CLI version 0.27.1# ✅ Chrome 已安装 (148.0.7778.217)# ✅ Headless launch 测试通过 (0.70s)# ✅ 守护进程运行中 (pid 436)一切正常那为什么 Hermes 用它还是会卡死3.2 深入分析agent-browser 和 Hermes 的关系这里有一个关键认知偏差我以为安装了agent-browserHermes 就会自动使用它。但实际并非如此。Hermes CN Desktop 是一个Python 应用程序用 Nuitka 编译成了 Windows 独立可执行文件它有自己的浏览器工具系统Hermes 浏览器系统结构 ├── browser_navigate() ← Python 实现的工具函数 ├── browser_click() ← Python 实现的工具函数 ├── browser_type() ← Python 实现的工具函数 ├── browser_snapshot() ← Python 实现的工具函数 │ ├── 浏览器后端引擎 (engine) │ ├── browser-use (Cloud) ❌ 损坏缺少 __init__.py │ ├── browserbase (Cloud) ❌ 损坏缺少 __init__.py │ └── firecrawl (Cloud) ❌ 损坏缺少 __init__.py │ └── 本地连接方式 └── CDP (Chrome DevTools Protocol) ← 这才是关键3.3 真相大白agent-browsernpm 包和 Hermes 的浏览器工具Python 内置是两个独立的系统。Hermes 并不知道也不使用 npm 的agent-browser。Hermes 的浏览器工作方式是通过CDPChrome DevTools Protocol连接到一个正在运行的 Chrome 浏览器通过 WebSocket 发送指令导航、点击、截图等通过 WebSocket 接收结果而配置文件中的cdp_url是空的browser:cdp_url:# ← 空的Hermes 不知道连谁engine:auto# 自动检测当cdp_url为空时Hermes 尝试自动启动浏览器——但在 Windows 编译版中这个启动过程挂起了导致终端工具卡死。四、解决方案4.1 核心思路启动 Chrome 浏览器并启用 CDP远程调试端口然后在 Hermes 配置中指定这个连接地址。4.2 具体步骤第一步以 headless 模式启动 Chrome不弹窗口/c/Program Files/Google/Chrome/Application/chrome.exe\--remote-debugging-port9222\--headless\--no-first-run\--no-default-browser-check\--user-data-dir$HOME/.agent-browser/profiles/hermes\--disable-gpu\about:blank参数说明--remote-debugging-port9222— 开启 CDP 端口--headless— 无界面模式不弹窗口--user-data-dir— 独立的 Chrome 用户数据目录不影响日常浏览第二步验证 CDP 是否正常curlhttp://127.0.0.1:9222/json/version返回示例{Browser:Chrome/148.0.7778.217,webSocketDebuggerUrl:ws://127.0.0.1:9222/devtools/browser/...}第三步修改 Hermes 配置编辑config.yaml路径见下方将browser.cdp_url设置为 Chrome 的 CDP 地址browser:cdp_url:http://127.0.0.1:9222# ← 告诉 Hermes 浏览器在哪command_timeout:60# ← 操作超时从30秒增加到60秒inactivity_timeout:300# ← 闲置超时增加到5分钟engine:auto配置文件位置C:\Users\用户名\AppData\Roaming\cn.org.hermesagent.desktop\runtime\hermes-home\config.yaml第四步重启 Hermes 会话在 Hermes 中输入/reset或退出重开配置即可生效。4.3 便捷启动脚本创建一个批处理文件start-chrome-cdp.bat双击即可启动echo off start /b C:\Program Files\Google\Chrome\Application\chrome.exe ^ --remote-debugging-port9222 ^ --headless ^ --no-first-run ^ --no-default-browser-check ^ --user-data-dir%USERPROFILE%\.agent-browser\profiles\hermes ^ --disable-gpu ^ about:blank echo Chrome headless started with CDP on port 9222五、问题原因与原理深度解析5.1 为什么 Hermes 浏览器工具会卡死正常流程 Hermes 调用 browser_navigate() → 检查 cdp_url有值 → 连接 Chrome CDP → 发送命令 → 获取结果 → ✅ 正常返回 卡死流程 Hermes 调用 browser_navigate() → 检查 cdp_url为空 → 尝试自动启动浏览器子进程 → 子进程启动失败/挂起Windows 编译版问题 → terminal 工具一直等待子进程返回 → 无限卡死 5.2 什么是 CDPCDP Chrome DevTools ProtocolChrome 开发者工具协议它是 Chrome 浏览器暴露的一个底层控制接口。你在 Chrome 中按 F12 打开开发者工具时实际上就在使用 CDP——只不过 DevTools 是图形界面版的 CDP 客户端。CDP 能做的事情你的程序 → [HTTP/WebSocket] → ChromeCDP 端口 9222 ├── Page.navigate() 打开网页 ├── Runtime.evaluate() 执行 JS ├── DOM.getDocument() 获取 DOM 树 ├── Input.dispatchMouseEvent 模拟鼠标点击 ├── Input.dispatchKeyEvent 模拟键盘输入 ├── Page.captureScreenshot() 截图 └── ...CDP 暴露了超过 200 个不同的命令覆盖了浏览器能力的方方面面。5.3 架构对比❌ 我以为的工作方式 我安装 agent-browser (npm) → Hermes (Python) 自动使用它 → 操控浏览器 ✗ 实际Hermes 根本不知道 agent-browser 的存在 ✅ 实际的工作方式 我启动 Chrome (带 --remote-debugging-port9222) → Chrome 在 9222 端口开放 CDP 接口 → Hermes 通过 WebSocket 连接 CDP → 直接操控浏览器 ✓ Hermes 内置工具本来就用 CDP不需要 agent-browser5.4 所以 agent-browser 到底用在哪agent-browser作为一个备选方案当 Hermes 内置的浏览器工具遇到反爬检测、验证码等问题时可以通过terminal工具直接调用agent-browser命令来绕过# 通过 Hermes 的 terminal 工具调用 agent-browseragent-browseropenhttps://example.com agent-browser snapshot-i5.5 一张图总结┌─────────────────────────────────────────────────────┐ │ 你的 Windows 电脑 │ │ │ │ ┌─────────────────┐ ┌─────────────────────────┐ │ │ │ Hermes Agent │ │ Chrome 浏览器 │ │ │ │ (Python 编译版) │ │ │ │ │ │ │ │ --remote-debugging- │ │ │ │ browser_ │────→│ port9222 │ │ │ │ navigate() 等 │ CDP │ (Headless 后台运行) │ │ │ │ │ │ │ │ │ └─────────────────┘ └─────────────────────────┘ │ │ │ │ ┌─────────────────┐ │ │ │ agent-browser │ (备选方案通过 terminal 调用) │ │ │ npm 包 v0.27.1 │ │ │ └─────────────────┘ │ └─────────────────────────────────────────────────────┘六、经验教训不要假设——安装了 A 工具不代表 B 工具会自动使用它。理解组件之间的关系很重要。查日志——Hermes 的agent.log和errors.log揭示了浏览器插件加载失败的信息早看能早定位问题。理解协议——CDP 是浏览器自动化的基石。不管是 Selenium、Puppeteer、Playwright 还是agent-browser底层都是 CDP。编译版软件的限制——Hermes CN Desktop 是编译后的二进制文件不能像源码版那样直接 pip install 包来修复问题需要通过配置绕行。七、相关资源资源链接Hermes Agent 官方文档https://hermes-agent.nousresearch.com/docsagent-browser 项目npm install -g agent-browserChrome DevTools Protocolhttps://chromedevtools.github.io/devtools-protocol/本文对应的 Hermes 技能skill_view(nameagent-browser-setup)文章写完于 2026-06-07。如果你也遇到同样的问题希望这篇文章能帮你省下几个小时。
