Hermes Agent 浏览器工具的用户登录实现方案
Hermes Agent 的浏览器工具将身份验证统一纳入常规的页面交互流程，并配合不同后端的状态持久化能力来完成登录态的保持。本文基于 NousResearch/hermes-agent 源码的直接分析，梳理其在处理“需要登录才能访问的网站”时的五种具体操作方案。
注：以下分析基于仓库中的tools/browser_tool.py、tools/browser_camofox.py与tools/browser_camofox_state.py等核心文件。
一、交互式自动化登录（通用方案）
这是最基础的方案，适用于所有后端。Agent 通过标准的浏览器操作链模拟人类登录：
browser_navigate(url)— 打开登录页browser_type(ref, text)— 在用户名/密码输入框中填写内容browser_click(ref)或browser_press("Enter")— 点击登录按钮或提交表单browser_snapshot()— 确认登录是否成功（页面跳转、出现个人中心等）
在 tools/browser_tool.py 的实现中，browser_type 底层调用的是 fill 命令，会先清空输入框再键入文本，避免残留旧内容。这种方式零配置、通用性强，但面对 CAPTCHA、2FA、二维码或强反 bot 检测时容易失败。
二、持久化浏览器 Profile / Cookie
对于需要反复访问的登录网站，Hermes 提供了跨任务保留登录态的能力，核心载体是 Camofox 后端。
Camofox 的 Managed Persistence
当环境变量 CAMOFOX_URL 指向本地 Camofox 服务器，并在 config.yaml 中启用持久化：
browser:
camofox:
managed_persistence: truetools/browser_camofox_state.py 会根据当前 Hermes profile 生成一个确定性的 userId，并映射到固定本地目录（~/.hermes/browser_auth/camofox/）。Camofox 服务器收到相同 userId 时会复用同一浏览器 profile，因此 cookies、localStorage、IndexedDB 等登录状态可以跨任务保留。
在 tools/browser_tool.py 的清理逻辑中，当 managed persistence 启用时，Agent 会执行 soft cleanup——仅释放本地内存跟踪，不销毁服务端的浏览器上下文，从而确保 session cookies 得以保留。
三、JavaScript 注入（程序化身份验证）
Hermes 的 browser_console 工具支持传入 expression 参数，在页面上下文中执行任意 JavaScript（相当于 DevTools Console）。这允许 Agent 直接：
- 读取/设置 Cookie：
document.cookie = "session_id=xxx" - 操作 localStorage：
localStorage.setItem('token', 'xxx') - 注入 JWT 或 API Token
该能力在 tools/browser_tool.py 的 _browser_eval 中实现，Camofox 后端也提供了对应的 /tabs/{tabId}/eval REST 端点。适用于开发者已拥有用户 session token、需要跳过登录表单的场景。
四、人机协作登录
当遇到强反 bot、CAPTCHA、二维码登录或 SSO 时，Hermes 提供了两种人机协作路径，但二者的交互形态差异很大。
4.1 Camofox + VNC：实时可操作浏览器窗口
这是代码中唯一为人类用户提供了可直接点击、输入、扫码的浏览器界面的方案。
在 tools/browser_camofox.py 中，初始化时会探测 Camofox 服务器的 /health 端点。如果服务器返回 vncPort，Hermes 会将其缓存为 _vnc_url，并在每次 camofox_navigate() 调用后把该地址写入返回结果：
{
"vnc_url": "http://<host>:<vncPort>",
"vnc_hint": "Browser is visible via VNC. Share this link with the user so they can watch the browser live."
}人类用户看到的界面：在自己的浏览器中打开 vnc_url，通常是一个 noVNC Web 客户端，显示远程桌面级别的浏览器窗口。用户可以直接点击按钮、填写表单、扫描二维码、拖动滑块完成 CAPTCHA，也可以观看 Agent 的自动化操作并随时接管。
协作流程：Agent 检测到登录或验证受阻后，会将 vnc_url 发送给用户，随后停止发送浏览器操作指令，等待用户反馈“已完成登录/验证”，再继续后续自动化。如果同时启用了 managed_persistence，用户通过 VNC 登录一次后，后续任务可直接复用该登录态。
4.2 browser_vision：截图回传的静态辅助
这是所有后端都可使用的通用方案，但它是单向的。Agent 调用 browser_vision 后，会将当前页面截图保存到本地，并通过 MEDIA:<path> 以图片附件形式发到聊天对话中。
用户只能看、不能点。典型 workflow 是：
- Agent 操作到验证页，发现被拦截
- Agent 截图并回传，用户看到例如短信验证码输入框
- Agent 通过对话询问用户验证码
- 用户回复数字，Agent 继续用
browser_type填入
该方案对需要人类直接操作网页元素的场景（如点击“我不是机器人”复选框、拖动拼图、扫码登录）基本无效。
五、连接已登录的现有浏览器（CDP Override）
Hermes 支持通过 BROWSER_CDP_URL 环境变量连接到一个现有的 Chrome DevTools Protocol (CDP) 端点。用户可以：
- 在本地启动一个普通 Chrome（带
--remote-debugging-port） - 手动登录目标网站
- 将 Chrome 的 CDP websocket 地址交给 Hermes
- Agent 直接在该已登录的浏览器实例中执行操作
在 tools/browser_tool.py 中，_get_cdp_override() 会读取该环境变量，_get_session_info() 则会创建对应的 CDP session，完全绕过本地启动和云 provider。
六、安全与防护
在 browser_navigate 的实现中，有一道针对凭据外泄的安全检查。Agent 会解码 URL 并扫描其中是否包含 API key 或 token 前缀，一旦发现即阻断导航：
url_decoded = urllib.parse.unquote(url)
if _PREFIX_RE.search(url) or _PREFIX_RE.search(url_decoded):
return {
"success": False,
"error": "Blocked: URL contains what appears to be an API key or token."
}这防止了 prompt injection 攻击通过导航链接将用户的敏感凭证外泄。
总结
| 方案 | 实现方式 | 最佳适用场景 |
|---|---|---|
| 自动化表单登录 | navigate → type → click/press |
普通用户名密码登录，无强反 bot |
| 持久化 Profile/Cookie | Camofox managed_persistence |
需要长期、反复访问同一网站 |
| JS 注入 Token/Cookie | browser_console(expression=...) |
已有 session token，需快速跳过登录 |
| 人机协作（VNC 实时） | Camofox 后端 + vnc_url |
CAPTCHA、二维码、SSO 等复杂验证 |
| 人机协作（截图辅助） | browser_vision + 对话回传 |
验证码回传等轻协作 |
| 连接已登录浏览器 | BROWSER_CDP_URL |
用户已有登录环境，Agent 仅做后续操作 |
整体而言，Hermes 的登录策略 = 交互式表单填写 + 后端状态保持 + 人机协作兜底。在默认的本地 agent-browser CLI 后端和云端 Browserbase / Browser Use 后端中，代码层面并未为人类预留可直接操作的浏览器界面；若需真正的实时人机协作，Camofox + VNC 是目前代码中最完整的实现路径。
Member discussion