配置指南
HermesX 全部环境变量和配置项参考。
配置优先级
SaaS 部署应通过环境变量或 Secret 注入配置。遗留本地配置文件不属于受支持的公开运行时。
SaaS 服务配置
| 变量 |
必填 |
默认值 |
说明 |
DATABASE_URL |
是 |
- |
数据库连接字符串。PostgreSQL 使用 postgres://...；MySQL 使用 user:pass@tcp(host:3306)/dbname?parseTime=true&charset=utf8mb4&loc=UTC |
HERMES_ACP_TOKEN |
是 |
- |
静态管理员 Bearer Token，用于 admin 端点认证 |
HERMES_BOOTSTRAP_RATE_LIMIT_RPM |
否 |
5 |
POST /admin/v1/bootstrap 按来源 IP 的每分钟尝试次数 |
SAAS_API_PORT |
否 |
8080 |
SaaS API 服务端口 |
SAAS_ALLOWED_ORIGINS |
否 |
-（不启用 CORS） |
CORS 允许的来源，* 表示全部，或逗号分隔的域名列表 |
SAAS_STATIC_DIR |
否 |
-（不提供静态文件） |
静态文件目录路径；发布镜像使用 /static 提供内嵌 WebUI |
HERMES_API_PORT |
否 |
8081 |
OpenAI 兼容适配器端口 |
HERMES_API_KEY |
否 |
- |
OpenAI 兼容适配器的 Bearer Token |
HERMES_ACP_PORT |
否 |
- |
ACP 服务器端口（不设置则不启动 ACP） |
LLM 配置
| 变量 |
必填 |
默认值 |
说明 |
LLM_API_URL |
否 |
- |
LLM API 端点 URL |
LLM_API_KEY |
否 |
- |
LLM API 认证密钥 |
LLM_MODEL |
否 |
- |
默认 LLM 模型名称 |
HERMES_MODEL |
否 |
- |
SaaS Agent Runtime 默认模型 |
HERMES_PROVIDER |
否 |
- |
LLM 提供商（openai / anthropic / auto） |
HERMES_BASE_URL |
否 |
- |
SaaS Agent Runtime 的 LLM API Base URL |
HERMES_API_KEY_LLM |
否 |
- |
SaaS Agent Runtime 的 LLM API Key |
HERMES_API_MODE |
否 |
- |
API 协议模式（openai / anthropic） |
HERMES_MAX_ITERATIONS |
否 |
20 |
Agent 最大迭代次数 |
HERMES_MAX_TOKENS |
否 |
4096 |
单次响应最大 token 数 |
存储配置
数据库
| 变量 |
必填 |
默认值 |
说明 |
DATABASE_URL |
是（SaaS 模式） |
- |
PostgreSQL 或 MySQL 连接字符串 |
DATABASE_DRIVER |
否 |
postgres |
数据库驱动类型：postgres 或 mysql |
Redis
| 变量 |
必填 |
默认值 |
说明 |
REDIS_URL |
否 |
- |
Redis 连接字符串，用于分布式速率限制和 Cron Scheduler 分布式锁 |
Cron Scheduler
启用分布式定时任务调度需要 REDIS_URL 已配置。Scheduler 通过 Redis 分布式锁实现多 Pod 互斥执行。
| 变量 |
必填 |
默认值 |
说明 |
SCHEDULER_POLL_INTERVAL |
否 |
30s |
从 PG 同步定时任务的轮询间隔 |
SCHEDULER_EXEC_TIMEOUT |
否 |
5m |
单次任务执行超时时间 |
SCHEDULER_LOCK_TTL |
否 |
12m |
Redis 分布式锁 TTL（应大于最长任务执行时间） |
Scheduler 在 REDIS_URL 可用时自动启动。如果 Redis 不可用，scheduler 初始化失败但不阻塞主服务启动（non-fatal）。
MinIO / S3
| 变量 |
必填 |
默认值 |
说明 |
MINIO_ENDPOINT |
否 |
- |
MinIO 服务地址（如 localhost:9000） |
MINIO_ACCESS_KEY |
否 |
- |
MinIO 访问密钥 |
MINIO_SECRET_KEY |
否 |
- |
MinIO 密钥 |
MINIO_BUCKET |
否 |
hermes-skills |
MinIO 存储桶名称 |
MINIO_USE_SSL |
否 |
false |
是否使用 SSL 连接 MinIO |
BUNDLED_SKILLS_DIR |
否 |
skills |
内置技能目录路径，用于租户自动 Provisioning |
当配置了 MinIO 后，系统在以下时机自动同步技能：
- 创建租户时：异步将 BUNDLED_SKILLS_DIR 中的所有技能复制到租户 MinIO 前缀，并生成默认 SOUL.md
- 服务启动时：遍历所有租户执行增量同步（新增/更新内置技能，跳过用户修改过的技能）
可观测性配置
| 变量 |
必填 |
默认值 |
说明 |
OTEL_EXPORTER_OTLP_ENDPOINT |
否 |
-（不启用 tracing） |
OpenTelemetry OTLP gRPC 端点 |
OTEL_EXPORTER_OTLP_INSECURE |
否 |
false |
是否使用不安全连接 |
OTEL_SERVICE_NAME |
否 |
hermes-agent |
OTel 服务名 |
Agent 行为配置（v1.4.0+）
| 变量 |
必填 |
默认值 |
说明 |
HERMES_CONTEXT_COMPRESSION |
否 |
true |
启用上下文自动压缩 |
HERMES_COMPRESSION_THRESHOLD |
否 |
80000 |
触发压缩的 token 阈值 |
HERMES_MEMORY_CURATOR |
否 |
true |
启用自主记忆整理 |
HERMES_MAX_MEMORIES |
否 |
100 |
单租户最大记忆条数 |
HERMES_SELF_IMPROVE |
否 |
true |
启用自我改进循环 |
HERMES_REVIEW_INTERVAL |
否 |
10 |
自我评审触发间隔（对话轮次） |
HERMES_MAX_INSIGHTS |
否 |
50 |
最大改进洞察条数 |
调试与运行时
| 变量 |
必填 |
默认值 |
说明 |
HERMES_DEBUG |
否 |
false |
启用调试日志（LLM 请求/响应详情） |
HERMES_DEFAULT_MODEL |
否 |
- |
全局默认模型（config fallback） |
HERMES_FILE_STATE |
否 |
- |
为 SaaS Agent 执行启用文件状态跟踪 |
记忆系统
Hermes 支持多种外部记忆提供商，按需配置：
Honcho
| 变量 |
说明 |
HONCHO_API_KEY |
Honcho 记忆服务 API Key |
HONCHO_APP_ID |
Honcho 应用 ID |
HONCHO_BASE_URL |
Honcho 服务地址 |
HONCHO_USER_ID |
Honcho 用户标识 |
Mem0
| 变量 |
说明 |
MEM0_API_KEY |
Mem0 记忆服务 API Key |
MEM0_BASE_URL |
Mem0 服务地址 |
Supermemory
| 变量 |
说明 |
SUPERMEMORY_API_KEY |
Supermemory 服务 API Key |
SUPERMEMORY_BASE_URL |
Supermemory 服务地址 |
Channel 与消息平台集成
Channel 与消息平台集成通过 SaaS 服务配置。旧独立 gateway 子命令不再是受支持的公开运行时。
| 变量 |
说明 |
TELEGRAM_BOT_TOKEN |
Telegram Bot Token |
DISCORD_BOT_TOKEN |
Discord Bot Token |
SLACK_APP_TOKEN |
Slack App-Level Token |
SLACK_BOT_TOKEN |
Slack Bot Token |
DMWORK_API_URL |
DmWork API 端点 |
DMWORK_BOT_TOKEN |
DmWork Bot Token |
辅助视觉模型
用于图像识别等多模态场景：
| 变量 |
默认值 |
说明 |
AUXILIARY_VISION_API_KEY |
回退到 OPENROUTER_API_KEY |
Vision LLM API Key |
AUXILIARY_VISION_BASE_URL |
OpenRouter 端点 |
Vision LLM Base URL |
AUXILIARY_VISION_MODEL |
- |
Vision 模型名称 |
工具 API Key
各类工具集成所需的 API Key：
| 变量 |
说明 |
OPENROUTER_API_KEY |
OpenRouter API Key |
GEMINI_API_KEY |
Google Gemini API Key |
GOOGLE_API_KEY |
Google API Key（搜索等） |
EXA_API_KEY |
Exa 搜索 API Key |
FIRECRAWL_API_KEY |
Firecrawl 网页抓取 API Key |
FAL_KEY |
fal.ai 图像生成 API Key |
ELEVENLABS_API_KEY |
ElevenLabs TTS API Key |
OSV_ENDPOINT |
Open Source Vulnerabilities API 端点 |
邮件配置
| 变量 |
说明 |
EMAIL_FROM |
发件人地址 |
EMAIL_USERNAME |
邮箱账号 |
EMAIL_PASSWORD |
邮箱密码 |
EMAIL_SMTP_HOST |
SMTP 服务器地址 |
EMAIL_SMTP_PORT |
SMTP 端口 |
EMAIL_IMAP_HOST |
IMAP 服务器地址 |
浏览器工具
| 变量 |
默认值 |
说明 |
BROWSER_BACKEND |
local |
浏览器后端（local 或 browserbase） |
BROWSER_CDP_URL |
- |
Chrome DevTools Protocol 端点 |
HASS_URL |
- |
Home Assistant 地址 |
HASS_TOKEN |
- |
Home Assistant 长期访问令牌 |
沙箱执行模式
SANDBOX_MODE 控制 execute_code 工具的执行后端：
| 变量 |
必填 |
默认值 |
说明 |
SANDBOX_MODE |
启用 execute_code 时必填 |
- |
代码执行后端模式 |
可选值：
| 模式 |
说明 |
适用场景 |
local |
仅当 HERMESX_ALLOW_LOCAL_SANDBOX=true 且环境不是 production 时直接在宿主机执行 |
显式本地 SaaS 开发 |
docker |
通过 Docker 容器执行 |
容器隔离执行，需要 Docker 守护进程 |
k8s-job |
通过 Kubernetes Job 执行 |
生产环境、无需 DinD 或特权容器 |
如果未设置 SANDBOX_MODE，execute_code 会返回错误，不会回退到宿主机执行。当 HERMES_ENV、HERMESX_ENV、APP_ENV 或 GO_ENV 任一值为 production 时，local 模式会被拒绝。
K8s Job 模式配置
当 SANDBOX_MODE=k8s-job 时，以下变量可选配置：
| 变量 |
默认值 |
说明 |
K8S_JOB_NAMESPACE |
default |
Job 运行的命名空间 |
K8S_JOB_IMAGE |
ubuntu:latest |
Job 使用的容器镜像 |
K8S_JOB_CPU_LIMIT |
500m |
CPU 资源限制 |
K8S_JOB_MEMORY_LIMIT |
256Mi |
内存资源限制 |
K8S_JOB_SERVICE_ACCOUNT |
-（使用默认 SA） |
Job Pod 的 ServiceAccount |
注意：K8s Job 模式需要 kubectl 已配置且可访问目标集群。在集群内部署时，通常通过 in-cluster config 自动完成。
本地 SaaS 开发
本地开发仍应运行 SaaS 服务形态：
docker compose -f docker-compose.saas.yml up -d --build
# 或在已有外部依赖时：
SAAS_STATIC_DIR=./webui/dist ./hermesx saas-api
不要再记录或依赖旧本地助手、gateway 运行时或分离前端容器配置。
安全注意事项
HERMES_ACP_TOKEN 用于管理员认证，生产环境必须使用强密码POST /admin/v1/bootstrap 默认按来源 IP 限制为 5 RPM；公网入口仍建议在 Nginx/Ingress 层叠加限流DATABASE_URL 中的密码建议通过 Kubernetes Secret 或 Vault 注入- API Key 以 SHA-256 哈希存储，无法逆向获取原始值
- 设置
SAAS_ALLOWED_ORIGINS 为具体域名，避免在生产环境使用 *
- 生产环境基础设施镜像必须固定 release tag 或 digest，不要部署
:latest
- MinIO 凭证应与 PostgreSQL 凭证独立管理
相关文档