ACP（Agent Client Protocol）是一个让 AI Agent 在编辑器里作为原生组件运行的协议。Hermes 支持 ACP，安装后 VS Code、Zed、JetBrains 编辑器的 Agent 面板里会出现 Hermes，任务结果（文件 diff、终端输出）直接在编辑器里展示，不需要切换到终端。

Hermes Agent ACP 集成：在 VS Code 和 Zed 编辑器里使用 Hermes 的完整配置指南

ACP 是什么，和 CLI 有什么区别

ACP（Agent Client Protocol）是一个开放协议（由 Anysphere 制定），定义了 IDE 和 AI Agent 之间的通信格式。支持 ACP 的编辑器能把 Agent 作为原生面板集成，任务结果直接在 IDE 里显示。

维度	CLI 模式	ACP 模式
界面	终端对话框	编辑器原生 Agent 面板
文件 diff	输出文本 diff	编辑器内可接受/拒绝的 diff
终端命令	直接在终端执行	编辑器集成终端，可配置审批
配置	~/.hermes/config.yaml	共用同一套配置
工具集	完整工具集	hermes-acp 精简工具集（去掉消息推送、音频等）

两种模式共用同一套 Skills、记忆和会话数据。ACP 模式下跑的 /code-review 等 Skill，和 CLI 里跑的完全一样。

前提条件

• Hermes Agent 已安装并配置好（hermes setup 完成）
• ~/.hermes/.env 里有有效的 LLM Provider Key
• Python 3.11+

安装 ACP 扩展包：

source venv/bin/activate
pip install -e ".[acp]"

VS Code 配置

第一步：安装 ACP Client 扩展

按 Ctrl+Shift+X（macOS 是 Cmd+Shift+X），搜索 ACP Client，点击安装。

或者命令行安装：

code --install-extension anysphere.acp-client

第二步：配置 settings.json

打开 VS Code 设置（Ctrl+,），点击右上角 {} 图标切换到 JSON 视图，添加：

{
  "acpClient.agents": [
    {
      "name": "hermes-agent",
      "registryDir": "/path/to/hermes-agent/acp_registry"
    }
  ]
}

把 /path/to/hermes-agent 替换为你的 Hermes 安装路径（比如 ~/.hermes/hermes-agent）。

第三步：重启 VS Code

重启后，编辑器的 Agent 面板里会出现 Hermes Agent 选项。

Zed 配置

Zed 内置 ACP 支持，配置更简单。

打开 Zed 设置

按 Cmd+,（macOS）或 Ctrl+,（Linux），在 settings.json 里添加：

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

要求 hermes 在 PATH 里可访问。如果用了 virtualenv，需要先 activate 或者写 hermes 的绝对路径。

重启 Zed

Hermes 会出现在 Agent 面板选项里。

JetBrains 配置

适用于 IntelliJ IDEA、PyCharm、WebStorm 等。

1. Settings → Plugins → Marketplace，搜索 ACP 或 Agent Client Protocol，安装后重启
2. Settings → Tools → ACP Agents，点 + 添加新 Agent
3. Registry 目录设为 acp_registry/ 的绝对路径（如 /home/user/hermes-agent/acp_registry）
4. 点 OK，ACP 面板（通常在右侧边栏）里出现 Hermes

ACP 模式下的工作流

文件编辑

Hermes 修改文件时，编辑器显示标准 diff：

• Accept：接受这处修改
• Reject：拒绝，保留原内容
• Review diff：查看完整变更再决定

终端命令

需要运行 shell 命令时（构建、测试、安装依赖），在编辑器集成终端里显示，并根据配置决定是自动执行还是需要手动批准。

审批流程

危险操作（删除文件、git 操作、重构）会暂停并弹出审批对话框，和 Gateway 模式 的审批逻辑一致，只是界面变成了编辑器原生 UI。

共享配置

ACP 模式使用和 CLI 完全相同的配置：

• API Keys / Provider：~/.hermes/.env
• 模型设置：~/.hermes/config.yaml
• Skills：~/.hermes/skills/
• 会话历史：~/.hermes/state.db

修改模型：

# ~/.hermes/config.yaml
model:
  default: anthropic/claude-sonnet-4.6

常见问题排查

Agent 不出现在编辑器里

1. 检查 acp_registry/ 目录路径是否正确，目录里是否有 agent.json
2. 确认 hermes 在 PATH 里：which hermes（找不到的话需要 activate virtualenv）
3. 改配置后重启编辑器

启动后立即报错

hermes doctor  # 检查配置完整性
hermes status  # 验证 API Key 是否有效
hermes acp     # 在终端直接跑，看报错输出

开启详细日志

HERMES_LOG_LEVEL=DEBUG hermes acp

VS Code 的日志：Output 面板 → 选择 ACP Client 或 Hermes Agent。

FAQ

Q: ACP 模式和直接用 Claude Code 有什么区别？

Claude Code 有独立的 IDE 扩展（VS Code / JetBrains），和 Anthropic 模型深度集成。Hermes ACP 是通用 ACP 协议实现，可以在任意 ACP 兼容的编辑器里运行，且支持切换 Provider。两者的功能在 IDE 集成层面相近，主要区别是模型灵活性和生态。

Q: ACP 工具集为什么比 CLI 精简？

ACP 场景是编辑器内的代码任务，不需要消息平台推送（send_message）、Home Assistant 控制、TTS 等功能。精简工具集减少 token 消耗，专注编程场景。如果需要完整工具集，在 config.yaml 里覆盖 acp_toolset 配置。

Q: ACP 模式下能用 Skills 吗？

可以，/skill-name 触发方式和 CLI 完全一样。Skills 目录和配置共享，CLI 里装的 Skill 在 ACP 模式里立即可用。