Hermes Agent — 搭建 · 部署

📋环境要求

🐍

Python

≥ 3.10

核心运行时，推荐 3.11+ 以获得更好性能

📦

包管理器

uv（推荐）或 pip

uv 安装更快，依赖解析更准确

🔑

LLM API Key

至少一个 Provider

OpenAI / Anthropic / Google Gemini / Bedrock 任选

🐳

Docker（可选）

20.10+

仅 Docker 部署模式或容器化工具环境需要

⬇安装方法

bash

# 基础安装（仅 CLI）
pip install hermes-agent

# 含 Gateway 平台依赖（Telegram / Discord / Slack 等）
pip install "hermes-agent[messaging]"

# 含全部可选依赖
pip install "hermes-agent[full]"

bash

# 安装 uv（如未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 用 uv 安装 hermes（推荐方式，速度更快）
uv tool install hermes-agent

# 含 messaging 插件
uv tool install "hermes-agent[messaging]"

1

克隆仓库

bash
git clone https://github.com/block/hermes-agent
cd hermes-agent

2

创建虚拟环境并安装

bash
uv sync                    # 安装所有依赖
uv sync --extra messaging  # 含 Gateway 平台

3

运行

bash
uv run hermes
# 或
uv run python -m hermes

bash

# pipx 将 hermes 安装到独立环境，全局可调用
pipx install hermes-agent

# 注入额外依赖（如需 Telegram 支持）
pipx inject hermes-agent python-telegram-bot

⚙配置

ℹ️

Hermes 使用分层配置：~/.hermes/config.yaml 为全局配置，./.hermes/config.yaml 为项目级覆盖。环境变量优先级最高。

~/.hermes/config.yaml
# LLM Provider — 至少配置一个
provider:
  default: "openai"            # 默认使用的 provider
  openai:
    api_key: "sk-..."          # 或设置 OPENAI_API_KEY 环境变量
    model: "gpt-4o"
  anthropic:
    api_key: "sk-ant-..."      # 或 ANTHROPIC_API_KEY
    model: "claude-sonnet-4-6"
  gemini:
    api_key: "AIza..."          # 或 GEMINI_API_KEY
    model: "gemini-2.5-flash"

# Agent 行为
agent:
  max_iterations: 50           # 最大工具调用轮次
  context_budget: 100000      # 最大 token 预算
  auto_compress: true         # 自动触发上下文压缩
  memory_enabled: true        # 启用跨会话记忆

# 工具环境
tools:
  environment: "local"         # local | docker | ssh | modal | daytona
  allow_shell: true
  allow_browser: false
  docker_image: "hermes-sandbox:latest"

也可直接通过环境变量配置（优先级最高）：

bash (.env 或 shell)

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
AWS_ACCESS_KEY_ID=...           # Bedrock 用
AWS_SECRET_ACCESS_KEY=...
HERMES_MODEL=claude-sonnet-4-6  # 覆盖默认模型
HERMES_MAX_TOKENS=100000

关键配置参数说明

参数	类型	必填	说明
provider.default	string	必填	默认 LLM provider 名称
provider.*.api_key	string	必填	对应 provider 的 API Key
agent.max_iterations	int	可选	单次对话最大工具调用轮次，默认 50
agent.context_budget	int	可选	触发自动压缩的 token 阈值
tools.environment	enum	可选	工具执行环境：local / docker / ssh / modal / daytona
tools.allow_shell	bool	可选	是否允许 Shell 命令执行，默认 true

▶运行模式

💻

交互式 CLI

最常用模式。带 TUI 的交互式对话，支持历史、自动补全、Slash 命令。

hermes

🌐

Gateway 多平台

监听 22 个消息平台（Telegram、Discord、Slack 等），将消息路由至 AIAgent。

hermes gateway

🔌

ACP Server

暴露 Agent Control Protocol HTTP 接口，供外部系统程序化调用 Agent。

hermes serve

bash — 启动命令汇总

# === 交互式 CLI ===
hermes                                   # 进入交互界面
hermes --model claude-sonnet-4-6       # 指定模型
hermes --profile work                  # 使用指定 profile
hermes --no-tools                      # 禁用工具调用（纯对话）

# === 非交互式（管道 / 脚本）===
echo "分析这个文件" | hermes --no-interactive
hermes --task "给 README.md 添加使用说明"

# === Gateway 模式 ===
hermes gateway                           # 启动所有已配置平台
hermes gateway --platform telegram     # 仅启动 Telegram
hermes gateway --platform discord,slack

# === ACP Server ===
hermes serve                             # 默认 8080 端口
hermes serve --port 9000 --host 0.0.0.0

💬CLI 交互使用

terminal — 典型会话示例
$ hermes
╔══════════════════════════════════════╗
║         Hermes Agent v0.12.0         ║
║   Model: gpt-4o  ·  Profile: default ║
╚══════════════════════════════════════╝

> 帮我分析当前目录的项目结构

◉ Running tool: terminal(ls -la)
◉ Running tool: file_read(README.md)

这是一个 Python 项目，包含以下结构...

> /model claude-sonnet-4-6        # 切换模型
> /skill coding                   # 加载编码 skill
> /memory show                    # 查看已记忆内容

🌐Gateway 模式配置

⚠️

Gateway 模式需要额外安装 messaging 依赖：pip install "hermes-agent[messaging]"

~/.hermes/config.yaml — gateway 配置段
gateway:
  telegram:
    enabled: true
    bot_token: "1234567890:AAF..."
    allowed_users: [123456789]     # Telegram user ID 白名单

  discord:
    enabled: true
    bot_token: "MTI3..."
    guild_ids: [987654321]

  slack:
    enabled: false
    bot_token: "xoxb-..."
    app_token: "xapp-..."

  whatsapp:
    enabled: false
    phone_number_id: "..."
    access_token: "..."

🐳Docker 部署

docker-compose.yml

version: "3.9"
services:
  hermes:
    image: ghcr.io/block/hermes-agent:latest
    restart: unless-stopped
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ~/.hermes:/root/.hermes       # 持久化配置和会话
      - ./workspace:/workspace         # 工作目录
    ports:
      - "8080:8080"                    # ACP Server 端口
    command: hermes gateway           # 以 gateway 模式运行

bash

docker compose up -d        # 后台启动
docker compose logs -f     # 查看日志

/Slash 命令参考

/model <name>

切换当前会话使用的 LLM 模型

/skill <name>

加载指定 Skill 文件注入 system prompt

/memory show

显示当前跨会话记忆内容

/memory clear

清除所有跨会话记忆

/tools list

列出当前可用的所有工具

/tools disable <name>

在当前会话禁用指定工具

/context show

显示当前 token 使用量和压缩状态

/context compress

手动触发上下文压缩

/history

浏览历史会话列表

/profile <name>

切换 profile（配置集合）

/delegate <prompt>

派发子 Agent 执行独立任务

/exit

退出 CLI（也可 Ctrl+D）

👤Profile 系统

Profile 是一组配置的集合，允许在不同场景（工作/个人/项目）之间快速切换。每个 profile 有独立的会话历史、记忆、配置覆盖。

~/.hermes/profiles/default/

默认 profile，未指定时使用

~/.hermes/profiles/work/

工作场景，可覆盖 provider、工具权限等

~/.hermes/sessions/

SQLite 会话存储目录（FTS5 全文索引）

~/.hermes/memory/

跨会话记忆文件存储

~/.hermes/skills/

自定义 SKILL.md 文件目录

./.hermes/config.yaml

项目级配置，覆盖全局配置

搭建 · 部署 · 使用