深度解析 Hermes Browser Extension：如何让浏览器与本地大模型运行时无缝对话

在将大语言模型接入日常工作的过程中，很多人会遇到一个痛点：我们在浏览器里看到的网页内容，很难直接、安全地传递给本地运行的 AI 智能体。市面上大多数浏览器插件本质上是套壳的网页聊天机器人，它们要求你把数据上传到云端，或者只能提供非常有限的上下文抓取能力。

Hermes Browser Extension 的出现解决了一个特定且高阶的需求：它不是聊天机器人，而是一个原生的浏览器侧边栏，专门用来将你当前正在浏览的网页上下文，精准地桥接到你本地或远程运行的 Hermes Agent 运行时中。

这篇文章将带你全面了解这个工具的核心逻辑、安装配置细节、安全架构设计以及在实际开发中可能遇到的各类问题。

Hermes Browser Extension 到底是什么？

要准确理解这个工具，首先需要明确它的定位。Hermes Browser Extension 是由 Jon Komet 开发的社区级扩展，服务于 Nous Research 开源的下发任务智能体项目。它运行在 Chrome、Edge 或其他基于 Chromium 内核的浏览器中，采用 Manifest V3 (MV3) 标准的侧边栏 API 构建。

它的工作原理非常直接：这个侧边栏本身不包含任何大模型，它只是一个“通道”。默认情况下，它会与本地 http://127.0.0.1:8642 的 Hermes 网关或 API 服务器进行通信。当你配置了一个可访问的远程 URL 时，它也能连接到远程服务器。

通过这个通道，扩展可以直接调用你在 Hermes 中已经配置好的模型、工具、技能、会话、记忆以及 MCP 服务器。这意味着，你在 Hermes 生态里搭建的所有复杂能力，都可以直接在浏览器的侧边栏里被触发和使用。

界面与功能导览

在深入技术细节之前，我们先通过它的界面来直观感受它的设计理念。

功能模块	视觉呈现	实际作用
侧边栏主界面		提供对话交互界面，支持 Mono 等多种极客主题，呈现纯粹的终端感。
主题与外观设置		包含亮色/暗色/跟随系统模式，以及 Nous、Midnight、Ember、Mono、Cyberpunk 和 Slate 六种独立主题。
本地代理选择		允许在受信任的本地 Hermes API 网关端口之间进行切换。
浏览器行为控制		控制自动命名、提示词上下文范围，以及侧边栏是依附于当前标签页还是全局悬浮。
上下文作用域		核心控制区：仅聊天、跟随活动标签页、仅当前页面，以及选择哪些打开的标签页参与提示词构建。
兼容性面板		当连接的网关版本较旧时，提供明确的降级或手动模式，而不是直接抛出路由错误。

核心特性深度剖析

从实际使用的角度来看，这个扩展的几个核心特性决定了它与其他同类工具的本质区别。

1. 精细化的上下文捕获与隔离

很多插件抓取网页是粗暴的，但 Hermes 扩展在捕获上下文时表现得极其克制和精准。它可以捕获活动标签页的标题、URL、打开的标签页列表、你选中的文本、可读的页面正文、元数据、标题层级、表单、链接以及按钮。

更重要的是它的作用域控制：

• 仅聊天模式：当你不需要任何浏览器上下文时，它就是一个纯粹的客户端。
• 跟随活动标签页：你切换标签，它抓取的上下文就自动切换。
• 固定标签页与多标签页选择：你可以钉住某一个特定标签页，或者在提示词中自由勾选当前打开的多个标签页内容。

为了保持对话的整洁，被固定标签页的对话历史是隔离的，拥有独立的本地历史记录和 Hermes 会话绑定。

2. 透明的“上下文回执”机制

这是我在使用中认为非常有价值的一个设计。每次你发送带有网页上下文的请求后，扩展会折叠显示一个名为“What Hermes saw”的回执。这就像是快递的签收单，你可以清楚地看到 Hermes 到底接收到了哪些网页数据。这对于调试提示词、确认是否抓取到了正确的正文内容非常有帮助。

3. 智能语音听写双引擎

语音输入在浏览器扩展中经常因为权限问题翻车。Hermes 扩展采用了一种非常务实的双引擎策略：

• 优先使用连接的 Hermes 运行时提供的音频转录能力。
• 如果运行时不支持，自动降级使用浏览器的原生 Web Speech API。
• 如果 Chromium 的侧边栏直接屏蔽了麦克风权限弹窗（这是一个已知的浏览器机制），扩展会智能地打开一个独立的“Hermes Voice Dictation”标签页。在这个标签页里点击“开始听写”来满足浏览器的权限手势要求，转录完成后再自动回传给侧边栏。

4. 快捷命令与不信任包装

扩展内置了 /summarize（总结）、/explain（解释）、/rewrite（重写）、/tabs（标签页）和 /action-items（行动项）等快捷命令。

在安全层面，它在将网页文本发送给 Hermes 之前，会明确将其包装为“不受信任的上下文”。这是一种防御性设计，防止恶意网页通过注入隐藏文本的方式来“越狱”或操纵你的本地智能体。

环境准备与安装步骤

在开始安装之前，请确保你的环境满足以下基本要求：

• Hermes Agent 已经安装并且能够正常运行。
• Hermes 网关/API 服务器已经在本地或远程可访问的机器上启用。
• Node.js 版本在 20 或以上。
• 浏览器版本为 Chrome 114 及以上、Edge、Brave 或 Comet 等支持侧边栏 API 的 Chromium 内核浏览器。

第一步：获取并构建源码

由于目前该扩展处于公共 Alpha 阶段，尚未上架 Chrome Web Store，因此需要通过“加载已解压的扩展程序”的方式手动安装。

打开终端，执行以下命令将代码克隆到本地并安装依赖：

git clone https://github.com/abundantbeing/hermes-browser-extension.git
cd hermes-browser-extension
npm install
npm run build

构建完成后，所有可加载的扩展文件都会生成在项目根目录下的 dist/ 文件夹中。请务必记住这个路径，这是后续安装的关键。

第二步：在浏览器中加载扩展

1. 在 Chrome 或 Edge 浏览器的地址栏中输入 chrome://extensions 或 edge://extensions 并回车。
2. 在页面右上角找到并开启“开发者模式”开关。
3. 点击页面左上角出现的“加载已解压的扩展程序”按钮。
4. 关键操作：在弹出的文件选择器中，必须选择刚刚构建生成的 dist/ 文件夹。千万不要选择项目根目录，也不要选择 extension/ 文件夹。选错的直接后果就是扩展无法正常工作。
5. 加载成功后，点击浏览器工具栏上的拼图图标，将 Hermes 扩展固定，然后点击图标即可打开侧边栏。

日常更新注意：如果你拉取了最新的代码并重新运行了 npm run build，需要回到 chrome://extensions 页面，在 Hermes Browser Extension 的卡片上点击“刷新”按钮才能生效。

连接到 Hermes 运行时的三种模式

扩展安装好后，接下来的核心任务是让它与你的 Hermes 网关建立通信。根据你的部署方式，有三种不同的连接配置方法。

模式一：本地 API 服务器（最安全推荐）

这是默认且最安全的连接方式，数据不离开你的本机。

首先，在运行 Hermes 的机器上，找到 ~/.hermes/.env 配置文件，添加或修改以下环境变量：

API_SERVER_ENABLED=true
API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8642
API_SERVER_KEY=<你需要设置一个强密码作为API服务器密钥>
API_SERVER_CORS_ORIGINS=chrome-extension://<你的扩展ID>

保存后，启动或重启网关：

hermes gateway run

在终端中，你可以通过 curl 命令来验证 API 服务器是否正常响应：

HERMES_GATEWAY_URL=http://127.0.0.1:8642
HERMES_API_TOKEN='<你刚才设置的密钥>'
curl "$HERMES_GATEWAY_URL/health"
curl -H "Authorization: Bearer $HERMES_API_TOKEN" "$HERMES_GATEWAY_URL/v1/models"

如果终端返回了健康状态和模型列表，说明后端没问题。现在回到浏览器的扩展侧边栏：

1. 点击“Connect to Hermes”。如果你的 Hermes Desktop 支持本地审批流，直接批准即可。
2. 如果不支持，点击“Manual setup”。
3. 选择“Local gateway”。
4. 网关 URL 填入 http://127.0.0.1:8642。
5. 粘贴你刚才设置的 API 密钥。
6. 点击“Test connection”，成功后点击“Save settings”。
7. 随便打开一个正常的 https:// 网页，输入“用一句话总结这个页面”进行测试。

模式二：远程 API 服务器

当你把 Hermes 部署在局域网的其他机器或云服务器上时，需要使用此模式。

在远程机器的 .env 文件中，你需要将主机绑定到可访问的接口，并严格限制 CORS：

API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642
API_SERVER_KEY=<强密码>
API_SERVER_CORS_ORIGINS=chrome-extension://<你的扩展ID>

安全警示：绝对不要将 Hermes API 服务器毫无防护地裸露在公共互联网上。因为它直接关联着你真实的 Hermes 运行时和工具集。正确的做法是：在局域网内使用 HTTP，或者通过 Tailscale/VPN 通信；如果必须面向公网，必须将其置于受信任的 HTTPS 反向代理之后。

远程访问的地址示例可能是：

• http://192.168.1.50:8642 (局域网)
• http://hermes-desktop.local:8642 (本地域名)
• https://hermes.example.com (反向代理)

在扩展侧边栏中：

1. 选择“Remote gateway”。
2. 粘贴包含 http:// 或 https:// 的完整远程 URL。
3. 粘入 API 密钥并测试连接。

逻辑细节：当填入了 API Key 时，“Remote”代表连接的是远程 REST API 服务器，不强制要求 HTTPS。如果留空 API Key，“Remote”则会自动切换为连接远程仪表板的 WebSocket 模式（下文详述），此时强制要求 https://。

模式三：远程仪表板模式（无 API 服务器）

如果你在远程运行了 Hermes，但只暴露了带有 OAuth 登录保护的 Web 仪表板，而没有开放 API 端口，扩展依然可以工作。

在侧边栏选择“Remote”，输入仪表板的 https:// URL，将 API Key 留空。

此时，扩展会通过仪表板的 /api/ws 接口建立 WebSocket 连接，而不是走 REST API。它的认证机制非常巧妙：利用你已经在浏览器普通标签页中登录的仪表板会话，生成一个一次性的 WebSocket 票据。

操作流程：

1. 在浏览器的一个普通标签页打开仪表板 URL 并登录，保持该标签页不关闭。
2. 扩展会从该标签页以第一方身份获取票据，然后建立 Socket 连接。
3. 点击“Test connection”，如果能成功加载模型列表，说明整条链路畅通。

此模式的局限性：由于没有 REST 接口，图片附件只能以内联方式发送；技能列表和个人资料列表也无法获取，因为这些数据仅通过 REST 接口暴露，而仪表板的 REST 接口受限于跨域策略无法被扩展直接读取。

连接成功后发生了什么？

当侧边栏显示连接成功后，它会立刻从网关拉取一系列数据来初始化界面：

• 模型列表：调用 /v1/models 获取所有可用的提供商和模型，包括带有提供商前缀的完整 ID。
• 会话历史：调用 /api/sessions 按来源分组获取最近的对话记录。
• 技能建议：调用 /v1/skills 获取可以在输入框中使用的斜杠命令。
• 配置文件：如果网关暴露了元数据，会调用 /v1/profiles 填充配置选择器。
• 能力探测：调用 /v1/capabilities 获取特性标志，例如当前运行时是否支持音频转录或浏览器上传。

此时，如果你打开一个正常的网页，侧边栏顶部的 DOM/上下文芯片应该会显示一个非零的页面上下文字符数。如果你打开的是 chrome://extensions 这类浏览器内部页面，字符数会显示为 0，这是出于安全考虑的刻意限制。

极致保守的安全模型设计

在当前的这个版本中，Hermes Browser Extension 采取了一种极度保守的安全策略。作为经常接触各类浏览器扩展的开发者，我认为这种“宁可牺牲部分便利性，也要守住安全底线”的设计思路非常值得借鉴。

1. 权限最小化：扩展明确拒绝申请 debugger、nativeMessaging、点击/输入/表单提交、Cookies、历史记录、书签、下载等高危权限。它对浏览器没有任何控制权。
2. 纯粹的只读上下文：它只能“看”网页，不能替你点击购买按钮，不能替你填写注册表单，不能下载文件。
3. 不受信任上下文隔离：正如前文所述，网页文本在发送前会被打上“不受信任”的标签，防止 Prompt 注入。
4. 敏感页面黑名单：银行、加密货币、密码管理、支付、健康医疗以及政府税务等类别的网页，会被自动纳入受限范围，防止敏感数据泄露到本地模型中。
5. 严格的跨域与密钥控制：远程连接必须明确配置 URL、Token 和 CORS 白名单，拒绝任何模糊的匹配规则。

常见问题诊断与故障排除

在实际部署和使用中，你可能会遇到一些问题。以下是基于底层逻辑的排查指南。

加载了扩展但完全没反应

症状：点击图标没反应，或者侧边栏一片空白。
根本原因：99% 的概率是加载路径错误。
解决步骤：确认你在“加载已解压的扩展程序”时选择的文件夹是 dist/。这个文件夹的直接子目录中必须包含 manifest.json。如果你选了项目根目录或 extension/ 源码目录，浏览器无法解析。

浏览器显示的仍然是旧版本

症状：明明拉取了新代码并构建了，但功能没变，版本号还是旧的。
根本原因：浏览器缓存了旧的解压目录，或者你只是重新加载了但没有指向新的构建产物。
解决步骤：

1. 确认本地确实执行了 npm run build，且 dist/ 文件夹的时间戳是最新的。
2. 进入 chrome://extensions，先点击卡片上的“移除”。
3. 重新点击“加载已解压的扩展程序”，选择最新的 dist/ 文件夹。
4. 不要通过点击“Service Worker”或“Inspect views”来试图刷新版本，那些只用于代码调试，不是版本控制源。

侧边栏提示无法连接到网关

症状：一直报错，显示连接失败。
排查逻辑：

1. 确认网关进程是否真的在运行。
2. 在终端运行 curl http://127.0.0.1:8642/health（本地）或对应的远程地址。如果 curl 都不通，说明是网络或防火墙问题，与扩展无关。
3. 如果 /health 通了，但 /v1/models 失败，问题一定出在认证或跨域上。检查 .env 中的 API_SERVER_KEY 是否与扩展中填写的完全一致，检查 API_SERVER_CORS_ORIGINS 是否准确填写了 chrome-extension://<你的扩展ID>（这个 ID 在移除重装后会改变，需要同步更新配置）。

原生 Hermes 计算机控制无法工作

症状：希望 Hermes 能像人一样操作电脑，但没反应。
概念澄清：这是一个非常常见的误解。Hermes Browser Extension 故意不包含浏览器控制权限，它无法驱动页面。原生的桌面控制能力是由 Hermes Agent 核心的 computer_use 工具集通过 cua-driver 提供的，与浏览器扩展无关。
排查步骤：在运行 Hermes 的机器终端上直接排查：

hermes tools list
hermes computer-use status
hermes computer-use doctor

如果提示驱动缺失，执行 hermes computer-use install。
系统级限制须知：

• Windows：通过 SSH 运行会处于 Session 0，无法看到交互式桌面，必须使用控制台/RDP 会话。管理员权限的窗口无法被普通权限的 Hermes 进程控制。
• macOS：需要在系统设置中授予“辅助功能”和“屏幕录制”权限。
• Linux：需要可访问的 X11/Wayland 显示环境以及 AT-SPI。

DOM 芯片显示 0 chars

症状：侧边栏顶部上下文字符数始终为 0。
原因：你当前正处于浏览器内部页面（如 chrome://、edge://、扩展管理页、开发者工具等）。出于安全沙箱机制，扩展被禁止读取这些页面的 DOM。切换到一个普通的 https:// 网站并刷新上下文即可恢复。

麦克风被阻止或语音听写无法启动

症状：点击麦克风没反应，或提示被阻止。
原因：Chromium 内核的侧边栏环境经常会抑制麦克风权限的弹窗请求。
解决流程：

1. 点击侧边栏麦克风，如果无反应，扩展会自动打开一个“Hermes Voice Dictation”标签页。
2. 在该标签页点击“Start dictation”，这个点击动作满足了浏览器要求用户主动交互的权限手势。
3. 说话后点击停止，文本会自动传回。
4. 如果依然被阻止，点击该标签页内的“Open microphone settings”，在浏览器弹出的设置中将该扩展的麦克风权限设为“允许”。

首次运行的连接向导不可用

原因：目前处于 Alpha 阶段，原生的桌面审批流还在迭代中。
解决方法：直接跳过向导，使用“Manual setup”，手动填入网关 URL 和 API Key 即可。

高阶玩法：利用 GitHub PR/Issue 自动审查

这个项目仓库中不仅包含浏览器扩展，还内置了两个针对 Hermes 的审查运行器，这对于开源项目维护者来说是一个极具启发性的应用场景。

本地轮询审查模式

你可以在本地运行一个监听器，让它自动检查 GitHub 上的开放 PR 和 Issue，并调用 Hermes 进行代码审查。

npm run review:watch

它的工作机制很严谨：它会计算 PR 头部 SHA 或 Issue 标题/正文的稳定签名，只对发生变化的目标进行审查。它会在每个 PR/Issue 下以稳定的标记符更新一条机器人评论，并且将 PR 差异和 Issue 内容视为“不受信任的输入”以保障安全。

如果你需要覆盖默认配置，可以使用以下环境变量：

HERMES_REVIEW_REPO=abundantbeing/hermes-browser-extension
HERMES_REVIEW_GATEWAY_URL=http://127.0.0.1:8642
HERMES_REVIEW_API_KEY=<你的密钥>
HERMES_REVIEW_MAX_TARGETS=3
HERMES_REVIEW_STATE_FILE=~/.hermes/hermes-browser-review-state.json

GitHub Actions 事件运行器

项目还提供了 npm run review:event 用于未来的 GitHub Actions 或 Webhook 接入。它需要接收 GITHUB_EVENT_NAME、GITHUB_EVENT_PATH 和 GITHUB_REPOSITORY 等环境变量。

架构注意事项：如果你打算在 GitHub 托管的 runner 上运行此工作流，必须意识到 runner 是无法访问你本地电脑的 127.0.0.1:8642 的。你必须部署一个远程的 Hermes API 服务器（通过 Tailscale/VPN/HTTPS 暴露），或者使用与你 Hermes 机器在同一网络下的自托管 GitHub Runner。此外，推送包含 workflow 的文件还需要具有 workflow 范围的 GitHub Token。

在调试这些审查脚本时，建议先使用干运行模式：

npm run review:watch:dry-run

项目结构解析与二次开发

如果你希望基于这个扩展进行二次开发或贡献代码，理解其项目布局是第一步。

extension/
  manifest.json       # MV3 扩展的核心配置文件
  background.js       # 控制侧边栏行为的后台脚本
  content.js          # 注入到网页中的上下文收集器
  sidepanel.html      # 侧边栏的 HTML 结构
  sidepanel.css       # 侧边栏的样式表
  sidepanel.js        # 核心逻辑：Hermes API 客户端与 UI 状态管理
  voice-dictation.*   # 解决侧边栏麦克风被屏蔽的独立录音页面
  request-permissions.* # 可见的扩展麦克风权限辅助页面
  sidepanel-preview.html # 静态视觉测试预览页
  assets/             # 本地 Hermes 字体、图标和图像资源
  lib/common.mjs      # 共享的提示词、上下文和安全处理工具库
scripts/
  build.mjs           # 构建脚本，将 extension/ 编译打包到 dist/
  check-manifest.mjs  # 校验 manifest 中声明的资源/权限是否完整
  hermes-review-github-event.mjs # GitHub 事件审查运行器
  hermes-review-watch.mjs        # 本地 PR/Issue 审查轮询器
  package.mjs         # 打包生成 artifacts/hermes-browser-extension.tar.gz
tests/
  common.test.mjs     # 针对工具库行为的单元测试

开发过程中，你可以利用内置的 npm 脚本来保证代码质量：

• npm test：执行测试用例。
• npm run check:js：检查 JavaScript 代码规范。
• npm run check:manifest：验证 manifest 文件的合法性。
• npm run verify：运行全套校验流程。
• npm run package：将构建好的扩展打包成压缩包用于分发。

利用 Hermes 自身完成安装部署

作为一款智能体工具，最极客的安装方式莫过于让智能体自己来完成部署。如果你已经有一套运行良好的 Hermes 环境，你可以直接向它输入以下提示词，利用它的 Computer Use 能力自动完成整个过程：

Install Hermes Browser Extension from https://github.com/abundantbeing/hermes-browser-extension. Clone it, run npm install, run npm run build, then use computer use to open chrome://extensions, enable Developer mode, load the dist folder unpacked, and help me connect it to my local or remote Hermes Gateway API server. Do not reveal, print, screenshot, or commit my API key.

注意提示词的最后一句非常关键：明确禁止智能体在控制台打印、截图或提交你的 API 密钥，这是在使用自动化工具处理敏感凭证时必须养成的好习惯。

总结与生态定位

Hermes Browser Extension 在整个 Nous Research 的 Hermes 生态中扮演着“边缘触角”的角色。它不试图在浏览器里重新造一个轮子，也不试图取代 Hermes Agent 的核心功能。它的核心价值在于：以最小的权限代价，将浏览器中最有价值的上下文信息，安全、透明地输送到你精心搭建的本地 AI 管道中。

对于注重数据隐私、希望将大模型深度融入信息检索与阅读工作流的用户来说，这种“本地运行时 + 纯只读浏览器桥接”的架构，代表了浏览器 AI 助手未来一种非常理性且可持续的发展方向。