Hermes Agent 本地部署指南

从零开始在你的开发环境中部署 Hermes AI Agent，涵盖环境搭建、LLM 接入、工具配置与生产部署的完整流程

环境准备

Hermes Agent 需要 Python 3.10+ 和 Git。推荐使用 Linux 或 macOS，Windows 用户建议使用 WSL2 以获得最佳体验。

最低要求： Python ≥ 3.10，pip ≥ 23.0，8 GB+ 内存（本地运行 LLM 则需要 16 GB+），20 GB+ 可用磁盘空间。

检查现有环境：

python3 --version
# 输出应为 Python 3.10.x 或更高

pip --version
# 建议 23.0+

git --version
# 用于克隆项目

推荐使用 pyenv 管理 Python 版本：

# 安装 pyenv（如果尚未安装）
# macOS
brew install pyenv

# Linux
curl https://pyenv.run | bash

# 安装并使用 Python 3.11（推荐版本）
pyenv install 3.11.9
pyenv local 3.11.9
python --version

创建项目专用虚拟环境：

# 创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate    # macOS / Linux
# .venv\Scripts\activate     # Windows

# 确认虚拟环境已激活
which python
# 应显示 .venv 下的路径

获取项目

从 GitHub 克隆 Hermes Agent 项目，建议使用稳定版本而非最新开发分支。

# 克隆主仓库
git clone https://github.com/your-org/hermes-agent.git
cd hermes-agent

# 查看可用版本标签
git tag -l

# 切换到最新稳定版
git checkout v1.2.0   # 替换为最新稳定版本号

# 确认版本
git describe --tags

项目目录结构概览：

hermes-agent/
├── hermes/
│   ├── core/           # 核心引擎
│   ├── agents/         # Agent 实现
│   ├── tools/          # 内置工具集
│   ├── memory/         # 记忆管理
│   └── llm/            # LLM 后端适配器
├── config/
│   └── config.yaml     # 主配置文件
├── skills/             # 自定义技能目录
├── docker-compose.yml  # Docker 部署文件
├── requirements.txt
├── setup.py
└── README.md

建议： 生产环境请始终使用带版本标签的稳定版本。开发测试可使用 main 分支体验最新功能，但不保证完全稳定。

安装依赖

安装 Python 依赖，包括核心库和可选的 LLM 后端支持包。

# 确保虚拟环境已激活
source .venv/bin/activate

# 安装核心依赖
pip install -r requirements.txt

# 以开发模式安装项目（推荐，方便调试）
pip install -e .

# 安装可选依赖（根据需要选择）
pip install -e ".[openai]"      # OpenAI / Claude API 支持
pip install -e ".[local]"       # 本地模型支持（ollama / llama.cpp）
pip install -e ".[dev]"         # 开发工具（linter / pytest）
pip install -e ".[all]"         # 安装所有可选依赖

网络问题： 如果 pip 安装缓慢，使用国内镜像源： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

配置 LLM 后端

Hermes Agent 支持多种 LLM 后端。根据你的需要选择一种方式，并配置对应的 API 密钥。

方式一：使用 Anthropic Claude API（推荐）

# 在 .env 文件中设置 API Key
echo 'ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx' >> .env

# config/config.yaml 中设置：
# llm:
#   provider: anthropic
#   model: claude-sonnet-4-6
#   max_tokens: 4096

方式二：使用 OpenAI API

# 在 .env 文件中设置 API Key
echo 'OPENAI_API_KEY=sk-xxxxxxxxxxxxx' >> .env

# config/config.yaml 中设置：
# llm:
#   provider: openai
#   model: gpt-4o
#   max_tokens: 4096

方式三：使用本地模型（通过 Ollama）

# 安装 Ollama
# macOS: brew install ollama
# Linux: curl -fsSL https://ollama.com/install.sh | sh

# 拉取模型
ollama pull llama3.1:8b
ollama pull qwen2.5:14b    # 中文场景推荐

# config/config.yaml 中设置：
# llm:
#   provider: ollama
#   model: qwen2.5:14b
#   base_url: http://localhost:11434

LLM 配置参数对照表：

参数	说明	推荐值
provider	LLM 提供商	anthropic / openai / ollama
model	模型名称	claude-sonnet-4-6 / gpt-4o
max_tokens	最大输出 token 数	4096
temperature	生成温度（0-1）	0.7（创意任务）/ 0.2（精确任务）
timeout	请求超时秒数	120

配置工具与技能

为 Agent 配置可调用的工具和自定义技能，赋予它读写文件、执行命令、搜索网页等能力。

工具目录配置：

# config/config.yaml 中启用工具
# tools:
#   enabled:
#     - file_read        # 读取文件
#     - file_write       # 写入文件
#     - bash_exec        # 执行 shell 命令
#     - web_search       # 网页搜索
#     - web_fetch        # 抓取网页内容
#     - python_repl      # Python 交互式解释器
#     - memory           # 记忆管理
#
#   disabled:
#     - file_delete      # 默认禁用危险操作
#     - system_config    # 默认禁用系统配置修改

编写自定义技能：

# skills/my_custom_skill.py
from hermes.core import Skill, register_skill

@register_skill(
    name="我的自定义技能",
    description="读取指定目录下的所有日志文件并汇总错误信息",
    triggers=["分析日志", "查看错误日志"]
)
class MyCustomSkill(Skill):
    def execute(self, log_dir: str = "/var/log"):
        import os
        errors = []
        for f in os.listdir(log_dir):
            if f.endswith(".log"):
                with open(os.path.join(log_dir, f)) as fp:
                    for line in fp:
                        if "ERROR" in line:
                            errors.append(line.strip())
        return {
            "total_errors": len(errors),
            "errors": errors[:50]  # 最多返回前 50 条
        }

安全原则： 危险操作（删除文件、修改系统配置、网络请求）建议默认禁用，仅在需要时通过白名单逐项启用。

启动与调试

完成配置后启动 Hermes Agent，验证 LLM 连接和工具调用是否正常。

启动交互式会话：

# 启动命令行交互式 Agent
hermes chat

# 指定配置文件
hermes chat --config config/my_config.yaml

# 启动时加载特定技能目录
hermes chat --skills-dir ./my-skills

一次性任务模式：

# 直接执行任务并返回结果
hermes run "分析当前目录的代码结构，列出所有 .py 文件"

# 指定 LLM 模型
hermes run --model claude-sonnet-4-6 "重构 src/utils.py 中的 helper 函数"

# JSON 格式输出
hermes run --output json "列出所有 TODO 注释"

调试模式：

# 启用详细日志
hermes chat --log-level DEBUG

# 查看工具调用详情
hermes chat --trace-tools

# 以 API 服务模式启动（便于调试）
hermes serve --host 127.0.0.1 --port 8000 --reload

验证清单： 启动后先让 Agent 执行一个简单任务（如 "列出当前目录文件"），确认 LLM 响应正常、工具调用成功，再处理复杂任务。

生产部署

将 Hermes Agent 部署为长期运行的服务，并提供 API 供其他应用调用。

方式一：使用 Docker 部署（推荐）

# 构建镜像
docker build -t hermes-agent:latest .

# 启动服务
docker run -d \
  --name hermes-agent \
  -p 8000:8000 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/skills:/app/skills \
  --env-file .env \
  --restart unless-stopped \
  hermes-agent:latest

方式二：使用 systemd 管理进程

# /etc/systemd/system/hermes-agent.service
[Unit]
Description=Hermes AI Agent Service
After=network.target

[Service]
Type=simple
User=hermes
WorkingDirectory=/opt/hermes-agent
EnvironmentFile=/opt/hermes-agent/.env
ExecStart=/opt/hermes-agent/.venv/bin/hermes serve --host 0.0.0.0 --port 8000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

API 调用示例：

# 健康检查
curl http://localhost:8000/health
# → {"status":"ok","version":"1.2.0","llm":"anthropic:claude-sonnet-4-6"}

# 发送任务请求
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "帮我检查服务器磁盘使用情况",
    "tools": ["bash_exec"],
    "stream": false
  }'

# 获取会话历史
curl http://localhost:8000/api/sessions

生产建议： 配置 Nginx 反向代理 + HTTPS；设置日志轮转（logrotate）；使用 Prometheus + Grafana 监控 API 延迟和 token 消耗；配置 API 认证（JWT / API Key）；设置资源限制防止单次请求占用过多资源。