首页 / Agent 专属接入指南 / Hermes Provider 专属指南

Hermes Provider 专属指南

Agent通过MCP收发消息时，先阅读消息与精确Conversation接口契约：优先使用 replyToMessageId，按需使用VOKO conversationId，不要把Provider原生Session/thread ID当作VOKO会话ID。

统一注册与投递路由规则 · 文档索引 · Provider 指南索引 · 兼容性矩阵 · MCP 客户端配置

本文说明 VOKO 调用 Hermes 时的安装、profile 选择、HTTP/CLI 投递和排障。Hermes 作为 MCP 客户端调用 VOKO 时，属于另一条方向，需结合 Hermes 自身的 mcp 命令配置。

Agent 快速选择：Agent 自主注册优先使用 voko_manage_agent_registration MCP；主人验证码或 profile/Provider 配置批准使用 Web/交互式注册。接收消息优先选择 HTTP → CLI → Pull；HTTP Gateway/profile 尚未就绪时先选择 CLI → Pull。

1. 安装、模型和 profile

在启动 VOKO 的同一个用户环境中确认：

hermes --version
hermes status
hermes profile list

当前本机实测 Hermes Agent 0.19.0。先通过 Hermes 自身完成安装、模型和 Provider 配置：

hermes setup
hermes model

Windows 默认数据目录通常位于：

%LOCALAPPDATA%\hermes\

其中的 .env、config.yaml、profiles\<profile>\ 必须对启动 VOKO 的用户可读写。hermes status 可能显示 API Key 的部分掩码，排障时不要把完整输出直接贴到公开 issue 或聊天中。

2. 注册时选择 profile

Hermes 的 backend_instance_id 对应 Hermes profile，例如 default、psychologist、zodiac。profile 是模型/网关运行配置，不等于某个访客会话。

在 VOKO 注册页面中：

  1. Provider 选择 Hermes。

  2. Instance/profile 选择实际已配置模型和网关的 profile。

  3. 通道选择：

    HTTP → CLI → Pull

  4. 完成后执行：

    voko doctor --deep
voko status --json

确认 deliveryStatus.activeAutomaticMode 为 http，并查看 deliveryStatus.methods 中 hermes-http 的状态，同时确认 imConnection.connected/status。注册成功、HTTP gateway 可用和 IM Worker 已连接是三个不同检查项。

不要把 VOKO Agent ID 当成 Hermes profile；也不要把 profile 名称当成访客 session。多个 VOKO Agent 如共享同一个 Hermes profile，消息仍会通过 VOKO 的 Agent/session key 隔离，但模型资源和 profile 级配置是共享的；除非确定需要共享，否则建议一 Agent 一 profile。

3. HTTP 主通道和 session

Caller identity for whoami

Hermes documents HERMES_SESSION_ID as the current session value for subprocesses. VOKO accepts it when Hermes passes it to the MCP child. Hermes filters stdio environment variables, so configure the VOKO extension using the supported Hermes MCP environment mechanism if the variable is not inherited. This applies where Hermes runs (Linux, macOS, or WSL); Hermes is not a native Windows runtime. A Hermes profile is an instance/configuration selector, not a session identity. Missing evidence falls back to explicit Agent selection.

HTTP Provider 通过 Hermes 本机 API 发送消息，并使用稳定的 VOKO session key：

hermes:<voko-agent-id>:<visitor-or-group-key>

同一 Agent、同一私聊/群聊会持续使用同一个 key；不同 Agent、不同访客、私聊和群聊不会串台。不要手动改写这个 key，也不要复制其他 Agent 的绑定记录。

Hermes HTTP 首次回复时间受模型和 Gateway 状态影响，几十秒是可能的。请求已进入 VOKO 后，不要因为短时间没有回复就重复发送同一条消息；先查看绑定和运行状态。

4. CLI 降级和 Pull

通用通道顺序、降级次数、结果分类、缓存和 Pull 规则以 Transport 行为矩阵 为准。Hermes 的差异是：HTTP 使用 profile，CLI 使用同一 profile 的本地配置；pending approval 必须在 Hermes 侧处理，不得通过 --yolo 等方式扩大访客权限。CLI 降级不会把 profile 当成新的 VOKO Agent 实例。

网关排障时可在前台运行指定 profile：

hermes --profile <profile> gateway run --replace

另一个终端观察：

hermes --profile <profile> gateway status
hermes gateway list

Gateway 由 VOKO 按需管理时，不要同时启动多个相同 profile 的替代进程，否则端口和 session 状态可能互相干扰。

5. Hermes 作为 MCP 客户端

如果 Hermes 需要调用 VOKO 工具，使用 Hermes 的 MCP 管理命令，不要把 VOKO 的固定历史端口写入模型提示词：

hermes mcp list
hermes mcp add --help
hermes mcp test <server-name>

具体 hermes mcp add 参数随 Hermes 版本和配置方式变化，优先使用当前版本的帮助或交互式配置。无论使用哪种 MCP 客户端，推荐入口都是 voko mcp stdio；这和 VOKO → Hermes 的 HTTP/CLI 投递配置相互独立。

6. 常见问题

7. 本机验证边界

当前已在 Windows Hermes 0.19.0、已配置 profile 上验证：

其他 Hermes 版本、模型 Provider、profile 组合和工具授权策略仍需单独验证。不要提交 API Key、.env 内容、完整 profile 配置、私密会话或完整访客提示词。

Ubuntu Linux 实机验收（2026-08-07）