Hermes Agent API 启动完全指南：本地调试到生产常驻部署

前面我们聊完了 Hermes Agent 命令行实操，解决了终端手动交互的问题。但在实际开发中，我们更多需要把 Hermes 能力封装成 HTTP 接口，对接前端、机器人、自动化脚本、第三方系统。

Hermes 内置了完整的 API Server 网关服务，无需额外部署 Nginx、Node 服务，开箱即用。本文带你从零搞定 Hermes Agent API 启动、配置、鉴权、调用、常驻生产，一套流程直接落地。

一、先搞懂：Hermes API Server 是什么？

Hermes Agent 自带轻量 HTTP 网关，开启后可以：

• 通过 HTTP 请求调用 Agent 智能体能力（对话、工具调用、任务执行）
• 对接任意编程语言、前端页面、机器人、工作流平台
• 支持 流式响应（打字机效果）与完整会话上下文
• 支持跨域配置、接口鉴权、后台常驻运行

核心本质：hermes gateway 就是 Hermes 的 API 服务入口，所有接口能力均由网关承载。

二、前置准备：开启 API 服务总开关

API 服务默认关闭，需要手动在环境配置中启用，这是启动 API 的第一步。

1. 编辑环境配置文件

Hermes 核心配置目录默认在 ~/.hermes/，编辑 .env 配置文件：

# 打开环境配置文件
nano ~/.hermes/.env

2. 开启 API 核心配置（必加）

粘贴以下基础配置，启用服务并设置接口密钥，防止未授权访问：

# 开启 API Server 服务
API_SERVER_ENABLED=true

# 接口鉴权密钥（生产环境务必修改为复杂密钥）
API_SERVER_KEY=Hermes@2026API

# 可选：允许前端跨域调用（适配 Vue/React 本地调试）
API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

配置说明：

• API_SERVER_ENABLED：总开关，true 启用 / false 关闭
• API_SERVER_KEY：全局接口 Token，所有 API 请求必须携带鉴权
• API_SERVER_CORS_ORIGINS：白名单域名，解决浏览器跨域报错

保存退出后，配置即刻生效，无需重启客户端。

三、Hermes API 启停核心命令（全覆盖）

所有 API 服务操作均通过 hermes gateway 系列命令完成，区分前台调试和后台生产常驻两种模式。

1. 前台启动（本地调试推荐）

前台运行会直接在终端打印日志，方便排查接口报错、查看请求详情，适合开发调试：

# 快速启动 API 网关服务
hermes gateway run

启动成功标识：终端输出 API Server started on http://127.0.0.1:xxxx，默认端口由 Hermes 自动分配，也可自定义端口。

2. 后台常驻（生产服务器推荐）

服务器部署必须使用后台服务模式，关闭终端不中断服务，支持开机自启：

# 1. 安装系统服务（单次执行）
hermes gateway install

# 2. 后台启动服务
hermes gateway start

# 3. 查看运行状态
hermes gateway status

# 4. 查看实时日志（排查问题必备）
hermes gateway logs

# 5. 重启 / 停止服务
hermes gateway restart
hermes gateway stop

3. 系统级全局服务（云端生产首选）

如果需要所有用户生效、开机自启、系统托管，使用全局安装：

sudo hermes gateway install --system
sudo hermes gateway start --system

四、自定义 API 端口与高级参数

默认端口随机，多服务部署时容易冲突，可手动指定端口和监听地址。