ACP 编辑器集成

Hermes Agent 可以作为 ACP 服务器运行，让兼容 ACP 的编辑器通过 stdio 与 Hermes 通信，并展示：

• 聊天消息
• 工具调用活动
• 文件差异
• 终端命令
• 审批提示
• 流式思考/响应片段

ACP 适合当你希望 Hermes 表现得像编辑器原生编码代理，而非独立 CLI 或消息机器人时使用。

Hermes 在 ACP 模式下提供的内容

Hermes 使用专为编辑器工作流设计的 hermes-acp 工具集运行，包括：

• 文件工具：read_file、write_file、patch、search_files
• 终端工具：terminal、process
• 网页/浏览器工具
• 记忆、待办事项、会话搜索
• 技能
• execute_code 和 delegate_task
• 视觉能力

它有意排除了不适合典型编辑器用户体验的功能，例如消息投递和定时任务管理。

安装

正常安装 Hermes，然后添加 ACP 扩展：

pip install -e '.[acp]'

这会安装 agent-client-protocol 依赖并启用以下命令：

• hermes acp
• hermes-acp
• python -m acp_adapter

对于 Zed 注册表安装，Zed 通过官方 ACP 注册表条目启动 Hermes。该条目使用 uvx 分发，运行命令如下：

uvx --from 'hermes-agent[acp]==<version>' hermes-acp

确保在使用注册表安装路径前，uv 已在 PATH 中可用。

启动 ACP 服务器

以下任一命令均可启动 Hermes 的 ACP 模式：

hermes acp

hermes-acp

python -m acp_adapter

Hermes 将日志输出到 stderr，因此 stdout 保留给 ACP JSON-RPC 流量。

非交互式检查：

hermes acp --version
hermes acp --check

浏览器工具（可选）

浏览器工具（browser_navigate、browser_click 等）依赖于 agent-browser npm 包和 Chromium，它们不属于 Python wheel 的一部分。使用以下命令安装：

hermes acp --setup-browser           # 交互式（约 400 MB 下载前会提示）
hermes acp --setup-browser --yes     # 非交互式接受下载

这是独立命令。Zed 注册表的终端认证流程（hermes acp --setup）也会在模型选择后提供浏览器引导作为后续问题，因此大多数用户无需直接运行 --setup-browser。

具体操作：

• 如果缺失，安装 Node.js 22 LTS 到 ~/.hermes/node/
• 在该前缀下执行 npm install -g agent-browser @askjo/camofox-browser（无需 sudo——npm 的 --prefix 指向用户可写的 Hermes 管理的 Node）
• 安装 Playwright Chromium，或在可用时使用检测到的系统 Chrome/Chromium

引导过程是幂等的——重新运行速度很快，会跳过已完成的工作。

编辑器设置

VS Code

安装 ACP Client 扩展。

连接方式：

1. 从活动栏打开 ACP Client 面板。
2. 从内置代理列表中选择 Hermes Agent。
3. 连接并开始聊天。

如果你想手动定义 Hermes，通过 VS Code 设置的 acp.agents 添加：

{
  "acp.agents": {
    "Hermes Agent": {
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

Zed

Zed v0.221.x 及更新版本通过官方 ACP 注册表安装外部代理。

1. 打开 Agent 面板。
2. 点击 Add Agent，或运行 zed: acp registry 命令。
3. 搜索 Hermes Agent。
4. 安装并启动一个新的 Hermes 外部代理线程。

前置条件：

• 首先使用 hermes model 配置 Hermes 提供商凭证，或在 ~/.hermes/.env / ~/.hermes/config.yaml 中设置。
• 安装 uv，以便注册表启动器可以运行 uvx --from 'hermes-agent[acp]==<version>' hermes-acp。

在注册表条目可用之前进行本地开发时，在 Zed 设置中使用自定义代理服务器：

{
  "agent_servers": {
    "hermes-agent": {
      "type": "custom",
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

JetBrains

使用兼容 ACP 的插件，并将其指向：

/path/to/hermes-agent/acp_registry

注册表清单

Hermes 官方 ACP 注册表元数据的源文件位于：

acp_registry/agent.json
acp_registry/icon.svg

上游注册表的 PR 会将这些文件复制到 agentclientprotocol/registry 的顶层 hermes-agent/ 目录中。

注册表条目使用直接指向 hermes-agent PyPI 发布的 uvx 分发：

uvx --from 'hermes-agent[acp]==<version>' hermes-acp

注册表 CI 会验证固定版本在 PyPI 上存在，因此清单的 version 和 uvx package 固定必须始终与 pyproject.toml 一致。scripts/release.py 会自动保持它们同步。

配置和凭证

ACP 模式使用与 CLI 相同的 Hermes 配置：

• ~/.hermes/.env
• ~/.hermes/config.yaml
• ~/.hermes/skills/
• ~/.hermes/state.db

提供商解析使用 Hermes 正常的运行时解析器，因此 ACP 继承当前配置的提供商和凭证。Hermes 还为首次运行的注册表客户端提供终端认证方法（--setup）；这会打开 Hermes 的交互式模型/提供商设置。

会话行为

ACP 会话由 ACP 适配器的内存会话管理器在服务器运行时跟踪。

每个会话存储：

• 会话 ID
• 工作目录
• 选定的模型
• 当前对话历史
• 取消事件

底层的 AIAgent 仍然使用 Hermes 正常的持久化/日志路径，但 ACP 的 list/load/resume/fork 限定在当前运行的 ACP 服务器进程范围内。

工作目录行为

ACP 会话将编辑器的 cwd 绑定到 Hermes 的任务 ID，因此文件和终端工具相对于编辑器工作区运行，而非服务器进程的 cwd。

审批

危险的终端命令可以路由回编辑器作为审批提示。ACP 审批选项比 CLI 流程更简单：

• 允许一次
• 始终允许
• 拒绝

在超时或出错时，审批桥会拒绝该请求。

会话级别的编辑自动审批

ACP 提供了一个介于允许一次和始终允许之间的第三层级：允许本次会话。从编辑器的权限提示中选择此选项，会将审批记录在当前 ACP 会话内——此后该会话中每个匹配的命令都会直接通过而无需提示，但新的 ACP 会话（或重启编辑器）会重置状态并在首次使用时重新提示。

选项	编辑器标签	范围	重启后是否持久化
allow_once	允许一次	本次工具调用	否
allow_session	允许本次会话	此 ACP 会话中的所有匹配调用	否——会话结束时清除
allow_always	始终允许	所有未来会话	是（写入 Hermes 永久允许列表）
deny	拒绝	本次工具调用	否

allow_session 是编辑器工作流的合理默认选择——你信任代理在当前任务期间的行为，但不想授予长期有效的允许列表条目。安全权衡是直接的：范围越广，编辑器中断你的次数越少，但行为异常的代理（或提示注入）在你注意到之前可能造成的损害也越大。对于不熟悉的命令，从 allow_once 开始；在看到代理正确运行相同模式几次后，提升为 allow_session；将 allow_always 保留给你永远信任的幂等命令（例如 git status）。

ACP 桥将这些选项映射到 Hermes 的内部审批语义——allow_always 写入永久允许列表条目，与 CLI 相同，而 allow_session 仅影响当前 ACP 会话的进程内审批缓存。

故障排除

ACP 代理未在编辑器中出现

检查：

• 在 Zed 中，使用 zed: acp registry 打开 ACP 注册表并搜索 Hermes Agent。
• 对于手动/本地开发，验证自定义 agent_servers 命令指向 hermes acp。
• Hermes 已安装并在 PATH 中。
• 已安装 ACP 扩展（pip install -e '.[acp]'）。
• 如果从官方 Zed 注册表条目启动，已安装 uv。

ACP 启动但立即报错

尝试以下检查：

hermes acp --version
hermes acp --check
hermes doctor
hermes status

缺少凭证

ACP 模式使用 Hermes 现有的提供商设置。使用以下命令配置凭证：

hermes model

或编辑 ~/.hermes/.env。注册表客户端也可以触发 Hermes 的终端认证流程，该流程运行相同的交互式提供商/模型设置。

Zed 注册表启动器找不到 uv

从官方 uv 安装文档安装 uv，然后从 Zed 重试 Hermes Agent 线程。

参见

• ACP 内部机制
• 提供商运行时解析
• 工具运行时