Hermes Agent 提供四种经验证的程序化接入方式：一、启用内置 REST API 服务；二、直连 Gateway WebSocket 实时通信；三、调用 ACP Unix Socket 高性能本地协议；四、通过 hermes-cli 子进程同步调用。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试调用 Hermes Agent 的 API 接口，但收到连接拒绝、空响应或 401 错误，则可能是由于服务未启动、认证密钥缺失、端点地址错误或请求格式不符合 OpenAI 兼容规范。以下是四种独立、可互换的程序化接入方式，均已在 2026 年主流部署环境中验证通过：
一、启用并调用内置 REST API 服务
该方式启动一个轻量级 HTTP 服务器，暴露与 OpenAI v1/chat/completions 兼容的接口，适用于脚本集成、CI/CD 流水线及简单 Web 后端调用。服务默认不启用，需显式启动且绑定明确地址。
1、确认 Hermes Agent 已完成安装并处于激活虚拟环境状态，执行 hermes --version 验证版本不低于 v0.13.0。
2、运行命令启动 API 服务：hermes api serve --host 0.0.0.0 --port 8000 --api-key sk-xxx，其中 sk-xxx 必须与 cli-config.yaml 中配置的 api_key 完全一致。
3、检查终端输出是否包含 "API server started on http://0.0.0.0:8000" 字样；若无，请确认端口未被占用，或添加 --debug 参数查看详细日志。
4、使用 curl 发起标准请求：curl -X POST "http://localhost:8000/v1/chat/completions" -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" -d '{"model":"qwen3-max","messages":[{"role":"user","content":"列出当前目录"}]}'。
二、直连 Gateway WebSocket 服务
该方式绕过 HTTP 协议栈，建立长连接以实现低延迟双向通信，适用于构建实时聊天界面、事件驱动工作流或需要接收流式响应（如 token 级 chunk）的前端应用。
1、先启动网关进程：hermes gateway run --host 127.0.0.1 --port 8080。
2、从日志中提取 WebSocket 地址，典型格式为 ws://127.0.0.1:8080/ws；注意该地址不含路径参数，不可拼接 /v1。
3、使用 Python websockets 库连接并发送消息帧：{"type": "message", "session_id": "sess-abc123", "content": "截图当前屏幕", "tools": ["screenshot"]}。
4、接收响应时需持续监听，识别 "event": "response_chunk" 类型消息以拼接流式输出，并在收到 "event": "response_complete" 后终止读取。
三、调用 ACP Unix Socket 本地控制协议
ACP 是 Hermes Agent 提供的高性能本地 IPC 协议，基于 Unix Domain Socket 实现零序列化开销的二进制通信，适用于 Shell 脚本、Ansible Playbook 或嵌入式自动化工具链。
1、确认系统支持 Unix socket 且 Hermes 进程以非 root 用户运行，socket 文件路径默认为 /tmp/hermes-acp.sock。
2、使用 socat 工具发送原始字节帧：echo -ne '\x00\x01\x00\x00\x00\x00\x00\x00{"cmd":"start_session","id":"cli-20260515"}' | socat - UNIX:/tmp/hermes-acp.sock。
3、响应为紧凑二进制结构，首字节标识状态码（0x00 表示成功），后续为 JSON 内容长度与 UTF-8 编码体；解析时需严格按长度字段截取。
4、会话生命周期由客户端主动管理，结束前必须发送 {"cmd":"end_session","id":"cli-20260515"} 帧，否则资源将滞留。
四、通过 hermes-cli 子进程同步调用
该方式以阻塞式子进程形式执行 CLI 命令，无需网络配置与协议解析，适合快速原型开发、临时调试或无法引入外部依赖的受限环境。
1、确保 hermes 命令全局可执行，运行 which hermes 返回有效路径。
2、构造带 session 上下文的调用命令：hermes chat --session-id temp-001 --model qwen3-max --message "压缩当前文件夹为zip"。
3、CLI 默认输出纯文本响应体，如需结构化结果，添加 --output json 参数，输出将包含 "status"、"content" 和 "tool_calls" 字段。
4、捕获子进程退出码：0 表示成功，1 表示输入错误，2 表示模型调用失败，3 表示工具执行异常；响应内容仅在退出码为 0 时保证完整可用。
