环境变量
Hermes Agent 使用一系列环境变量来配置其行为、连接外部服务和管理安全设置。以下是所有可用环境变量的完整参考。
核心配置
| 环境变量 | 默认值 | 说明 |
|---|---|---|
HERMES_AGENT_NAME | hermes-agent | 代理的名称，用于标识实例 |
HERMES_AGENT_VERSION | latest | 代理版本号 |
HERMES_AGENT_PORT | 3000 | 代理监听的端口 |
HERMES_AGENT_HOST | 0.0.0.0 | 代理绑定的主机地址 |
安全与认证
| 环境变量 | 默认值 | 说明 |
|---|---|---|
HERMES_API_KEY | (无) | 用于 API 认证的密钥（建议使用 HERMES_API_KEYS 多密钥支持） |
HERMES_API_KEYS | (无) | 逗号分隔的 API 密钥列表，支持多密钥认证 |
HERMES_JWT_SECRET | hermes-jwt-secret | JWT 令牌签名密钥 |
HERMES_JWT_EXPIRES_IN | 1h | JWT 令牌过期时间（如 1h, 24h, 7d） |
HERMES_RATE_LIMIT | 100 | 每分钟最大请求次数 |
HERMES_RATE_LIMIT_WINDOW | 60s | 限流窗口时间（如 60s, 300s） |
外部服务集成
LLM 提供商
| 环境变量 | 默认值 | 说明 |
|---|---|---|
LLM_PROVIDER | openai | LLM 提供商：openai, openrouter, anthropic, google, mistral, nous, local |
OPENAI_API_KEY | (无) | OpenAI API 密钥 |
OPENROUTER_API_KEY | (无) | OpenRouter API 密钥 |
ANTHROPIC_API_KEY | (无) | Anthropic API 密钥 |
GOOGLE_API_KEY | (无) | Google API 密钥 |
MISTRAL_API_KEY | (无) | Mistral API 密钥 |
NOUS_API_KEY | (无) | Nous Research API 密钥 |
LOCAL_LLM_URL | http://localhost:11434 | 本地 LLM 服务 URL（如 Ollama） |
模型配置
| 环境变量 | 默认值 | 说明 |
|---|---|---|
DEFAULT_MODEL | gpt-4o | 默认使用的 LLM 模型 |
DEFAULT_TEMPERATURE | 0.7 | 默认生成温度 |
DEFAULT_MAX_TOKENS | 2048 | 默认最大 token 数量 |
DEFAULT_TOP_P | 0.9 | 默认 top-p 采样值 |
DEFAULT_FREQUENCY_PENALTY | 0.0 | 频率惩罚系数 |
DEFAULT_PRESENCE_PENALTY | 0.0 | 存在惩罚系数 |
通信与渠道集成
即时通讯平台
| 环境变量 | 默认值 | 说明 |
|---|---|---|
TELEGRAM_BOT_TOKEN | (无) | Telegram 机器人 token |
DISCORD_BOT_TOKEN | (无) | Discord 机器人 token |
SLACK_BOT_TOKEN | (无) | Slack 机器人 token |
WHATSAPP_API_KEY | (无) | WhatsApp Business API 密钥 |
SIGNAL_USERNAME | (无) | Signal 用户名（手机号） |
SIGNAL_PASSWORD | (无) | Signal 密码 |
MATRIX_HOMESERVER | (无) | Matrix 服务器地址 |
MATRIX_USERNAME | (无) | Matrix 用户名 |
MATRIX_PASSWORD | (无) | Matrix 密码 |
Webhook 与事件通知
| 环境变量 | 默认值 | 说明 |
|---|---|---|
WEBHOOK_URL | (无) | 接收事件通知的 webhook URL |
WEBHOOK_HEADERS | (无) | 自定义 webhook 请求头（JSON 格式） |
EVENT_LOGGING_ENABLED | true | 是否启用事件日志记录 |
数据存储与持久化
| 环境变量 | 默认值 | 说明 |
|---|---|---|
DATABASE_URL | sqlite:///hermes.db | 数据库连接字符串（支持 SQLite, PostgreSQL, MySQL） |
REDIS_URL | redis://localhost:6379 | Redis 缓存/消息队列 URL |
CACHE_TTL | 3600 | 缓存过期时间（秒） |
SESSION_STORAGE | memory | 会话存储方式：memory, redis, database |
调试与日志
| 环境变量 | 默认值 | 说明 |
|---|---|---|
LOG_LEVEL | info | 日志级别：debug, info, warn, error |
LOG_FORMAT | json | 日志格式：json, text |
DEBUG_MODE | false | 启用调试模式（显示详细错误信息） |
TRACE_ENABLED | false | 启用请求追踪（用于性能分析） |
高级功能与实验性选项
| 环境变量 | 默认值 | 说明 |
|---|---|---|
ENABLE_MCP | false | 启用 MCP（Model Control Protocol）支持 |
MCP_SERVER_URL | http://localhost:8080 | MCP 服务器地址 |
ENABLE_HONCHO | false | 启用 Honcho 任务调度器 |
HONCHO_WORKER_COUNT | 4 | Honcho 工作进程数量 |
SOUL_FILE_PATH | ./souls/SOUL.md | SOUL.md 文件路径 |
AGENTSKILLS_IO_API_KEY | (无) | agentskills.io API 密钥（用于技能注册） |
FEATURE_FLAGS | (无) | 特性开关（JSON 格式，如 {"experimental": true}） |
示例配置文件 (.env)
# 核心配置
HERMES_AGENT_NAME=hermes-prod
HERMES_AGENT_PORT=8080
HERMES_AGENT_HOST=0.0.0.0
# 安全配置
HERMES_API_KEYS=sk-abc123,sk-def456
HERMES_JWT_SECRET=super-secret-jwt-key
HERMES_RATE_LIMIT=500
HERMES_RATE_LIMIT_WINDOW=60s
# LLM 配置
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-openai-key
DEFAULT_MODEL=gpt-4o
DEFAULT_TEMPERATURE=0.5
# 通信集成
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx54321
DISCORD_BOT_TOKEN=MTIzNDU2OjFyQkMtREYxMjM0Z2hJa2wteHk1NDMyMQ==
SLACK_BOT_TOKEN=xoxb-1234567890-1234567890-abcdefghijklmnopqrstuvwxyz
# 数据存储
DATABASE_URL=postgresql://user:pass@localhost/hermes_db
REDIS_URL=redis://redis:6379/0
CACHE_TTL=1800
# 日志与调试
LOG_LEVEL=debug
LOG_FORMAT=text
DEBUG_MODE=true
# 实验性功能
ENABLE_MCP=true
MCP_SERVER_URL=http://mcp-server:8080
FEATURE_FLAGS={"experimental": true, "beta": false}
注意：所有环境变量均可通过
.env文件或系统环境变量设置。优先级为：命令行参数 > 系统环境变量 >.env文件。
如需了解更多，请参阅 Hermes Agent 官方文档 或访问 agentskills.io 获取技能集成指南。"
环境变量参考
所有变量均需配置在 ~/.hermes/.env 中。你也可以通过 hermes config set VAR value 设置它们。
大模型提供商
| 变量 | 说明 |
|---|---|
OPENROUTER_API_KEY | OpenRouter API 密钥（推荐用于灵活性） |
OPENROUTER_BASE_URL | 覆盖 OpenRouter 兼容的基地址 |
AI_GATEWAY_API_KEY | Vercel AI Gateway API 密钥 (ai-gateway.vercel.sh) |
AI_GATEWAY_BASE_URL | 覆盖 AI Gateway 基地址（默认：`https://ai-gateway.vercel.sh/v1``) |
OPENAI_API_KEY | 自定义 OpenAI 兼容端点的 API 密钥（与 OPENAI_BASE_URL 一起使用） |
OPENAI_BASE_URL | 自定义端点的基地址（如 VLLM、SGLang 等） |
COPILOT_GITHUB_TOKEN | GitHub token，用于 Copilot API —— 优先级最高（OAuth gho_* 或细粒度 PAT github_pat_*；经典 PAT ghp_* 不支持） |
GH_TOKEN | GitHub token —— Copilot 的第二优先级（也用于 gh CLI） |
GITHUB_TOKEN | GitHub token —— Copilot 的第三优先级 |
HERMES_COPILOT_ACP_COMMAND | 覆盖 Copilot ACP CLI 可执行文件路径（默认：copilot） |
COPILOT_CLI_PATH | HERMES_COPILOT_ACP_COMMAND 的别名 |
HERMES_COPILOT_ACP_ARGS | 覆盖 Copilot ACP 参数（默认：--acp --stdio） |
COPILOT_ACP_BASE_URL | 覆盖 Copilot ACP 基地址 |
GLM_API_KEY | z.ai / ZhipuAI GLM API 密钥 (z.ai) |
ZAI_API_KEY | GLM_API_KEY 的别名 |
Z_AI_API_KEY | GLM_API_KEY 的别名 |
GLM_BASE_URL | 覆盖 z.ai 基地址（默认：https://api.z.ai/api/paas/v4) |
KIMI_API_KEY | Kimi / Moonshot AI API 密钥 (moonshot.ai) |
KIMI_BASE_URL | 覆盖 Kimi 基地址（默认：https://api.moonshot.ai/v1) |
MINIMAX_API_KEY | MiniMax API 密钥 —— 全球端点 (minimax.io) |
MINIMAX_BASE_URL | 覆盖 MiniMax 基地址（默认：https://api.minimax.io/v1) |
MINIMAX_CN_API_KEY | MiniMax API 密钥 —— 中国端点 (minimaxi.com) |
MINIMAX_CN_BASE_URL | 覆盖 MiniMax 中国基地址（默认：https://api.minimaxi.com/v1) |
KILOCODE_API_KEY | Kilo Code API 密钥 (kilo.ai) |
KILOCODE_BASE_URL | 覆盖 Kilo Code 基地址（默认：https://api.kilo.ai/api/gateway) |
HF_TOKEN | Hugging Face Token，用于推理服务提供商 (huggingface.co/settings/tokens) |
HF_BASE_URL | 覆盖 Hugging Face 基地址（默认：https://router.huggingface.co/v1) |
GOOGLE_API_KEY | Google AI Studio API 密钥 (aistudio.google.com/app/apikey) |
GEMINI_API_KEY | GOOGLE_API_KEY 的别名 |
GEMINI_BASE_URL | 覆盖 Google AI Studio 基地址 |
ANTHROPIC_API_KEY | Anthropic Console API 密钥 (console.anthropic.com) |
ANTHROPIC_TOKEN | 手动或旧版 Anthropic OAuth/setup-token 覆盖 |
DASHSCOPE_API_KEY | 阿里云 DashScope API 密钥，用于 Qwen 模型 (modelstudio.console.alibabacloud.com) |
DASHSCOPE_BASE_URL | 自定义 DashScope 基地址（默认：https://coding-intl.dashscope.aliyuncs.com/v1) |
DEEPSEEK_API_KEY | DeepSeek API 密钥，用于直接访问 DeepSeek (platform.deepseek.com) |
DEEPSEEK_BASE_URL | 自定义 DeepSeek API 基地址 |
OPENCODE_ZEN_API_KEY | OpenCode Zen API 密钥 —— 按使用付费，可访问精选模型 (opencode.ai) |
OPENCODE_ZEN_BASE_URL | 覆盖 OpenCode Zen 基地址 |
OPENCODE_GO_API_KEY | OpenCode Go API 密钥 —— $10/月订阅，开放模型访问 (opencode.ai) |
OPENCODE_GO_BASE_URL | 覆盖 OpenCode Go 基地址 |
CLAUDE_CODE_OAUTH_TOKEN | 若手动导出，显式覆盖 Claude Code token |
HERMES_MODEL | 在进程级别覆盖模型名称（由定时任务调度器使用；正常情况下建议使用 config.yaml） |
VOICE_TOOLS_OPENAI_KEY | 用于 OpenAI 语音转文本和文本转语音服务的首选 OpenAI 密钥 |
HERMES_LOCAL_STT_COMMAND | 可选的本地语音转文本命令模板。支持 {input_path}、{output_dir}、{language} 和 {model} 占位符 |
HERMES_LOCAL_STT_LANGUAGE | 默认语言，传递给 HERMES_LOCAL_STT_COMMAND 或自动检测的本地 whisper CLI 回退（默认：en） |
HERMES_HOME | 覆盖 Hermes 配置目录（默认：~/.hermes）。同时影响网关 PID 文件和 systemd 服务名，允许多个安装实例并发运行 |
提供商认证（OAuth）
对于原生 Anthropic 认证，当存在 Claude Code 自身的凭证文件时，Hermes 会优先使用这些文件，因为它们可以自动刷新。尽管环境变量如 ANTHROPIC_TOKEN 仍可用作手动覆盖，但已不再是 Claude Pro/Max 登录的首选方式。
| 变量 | 说明 |
|---|---|
HERMES_INFERENCE_PROVIDER | 覆盖提供方选择：auto、openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、huggingface、zai、kimi-coding、minimax、minimax-cn、kilocode、alibaba、deepseek、opencode-zen、opencode-go、ai-gateway（默认：auto） |
HERMES_PORTAL_BASE_URL | 覆盖 Nous Portal URL（用于开发/测试） |
NOUS_INFERENCE_BASE_URL | 覆盖 Nous 推理 API URL |
HERMES_NOUS_MIN_KEY_TTL_SECONDS | 最小代理密钥 TTL，超过此时间将重新生成（默认：1800 = 30分钟） |
HERMES_NOUS_TIMEOUT_SECONDS | Nous 凭证/令牌流程的 HTTP 超时时间 |
HERMES_DUMP_REQUESTS | 将 API 请求负载转储到日志文件中（true/false） |
HERMES_PREFILL_MESSAGES_FILE | 一个 JSON 文件路径，其中包含在 API 调用时注入的临时预填充消息 |
HERMES_TIMEZONE | IANA 时区覆盖（例如 America/New_York） |
工具 API
| 变量 | 说明 |
|---|---|
PARALLEL_API_KEY | AI 原生网络搜索 (parallel.ai) |
FIRECRAWL_API_KEY | 网页抓取与云浏览器 (firecrawl.dev) |
FIRECRAWL_API_URL | 自定义 Firecrawl API 端点，适用于自托管实例（可选） |
TAVILY_API_KEY | Tavily API 密钥，用于 AI 原生网页搜索、提取与爬取 (app.tavily.com) |
EXA_API_KEY | Exa API 密钥，用于 AI 原生网页搜索与内容获取 (exa.ai) |
BROWSERBASE_API_KEY | 浏览器自动化 (browserbase.com) |
BROWSERBASE_PROJECT_ID | Browserbase 项目 ID |
BROWSER_USE_API_KEY | Browser Use 云浏览器 API 密钥 (browser-use.com) |
FIRECRAWL_BROWSER_TTL | Firecrawl 浏览器会话存活时间（秒），默认：300 |
BROWSER_CDP_URL | 本地浏览器的 Chrome DevTools Protocol 地址（通过 /browser connect 设置，例如 ws://localhost:9222） |
CAMOFOX_URL | Camofox 本地反检测浏览器地址（默认：http://localhost:9377) |
BROWSER_INACTIVITY_TIMEOUT | 浏览器会话空闲超时时间（秒） |
FAL_KEY | 图像生成 (fal.ai) |
GROQ_API_KEY | Groq Whisper STT API 密钥 (groq.com) |
ELEVENLABS_API_KEY | ElevenLabs 高级 TTS 音色 (elevenlabs.io) |
STT_GROQ_MODEL | 覆盖 Groq STT 模型（默认：whisper-large-v3-turbo） |
GROQ_BASE_URL | 覆盖 Groq OpenAI 兼容 STT 端点 |
STT_OPENAI_MODEL | 覆盖 OpenAI STT 模型（默认：whisper-1） |
STT_OPENAI_BASE_URL | 覆盖 OpenAI 兼容 STT 端点 |
GITHUB_TOKEN | GitHub token，用于 Skills Hub（更高的 API 速率限制，技能发布） |
HONCHO_API_KEY | 跨会话用户建模 (honcho.dev) |
HONCHO_BASE_URL | 自托管 Honcho 实例的基地址（默认：Honcho 云端）。本地实例无需 API 密钥 |
SUPERMEMORY_API_KEY | 带有个人资料回忆与会话摄入功能的语义长期记忆 (supermemory.ai) |
TINKER_API_KEY | 强化学习训练 (tinker-console.thinkingmachines.ai) |
WANDB_API_KEY | 强化学习训练指标 (wandb.ai) |
DAYTONA_API_KEY | Daytona 云沙箱 (daytona.io) |
终端后端| 变量 | 说明 |
|------|------|
| TERMINAL_ENV | 后端：local、docker、ssh、singularity、modal、daytona |
| TERMINAL_DOCKER_IMAGE | Docker 镜像（默认值：nikolaik/python-nodejs:python3.11-nodejs20） |
| TERMINAL_DOCKER_FORWARD_ENV | 要显式传递到 Docker 终端会话中的环境变量名称的 JSON 数组。注意：由技能声明的 required_environment_variables 会自动转发——您仅需在此处指定未被任何技能声明的变量。 |
| TERMINAL_DOCKER_VOLUMES | 额外的 Docker 卷挂载（以逗号分隔的 host:container 键值对） |
| TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE | 高级可选设置：将启动时的工作目录挂载到 Docker 中（/workspace/true，默认值：false） |
| TERMINAL_SINGULARITY_IMAGE | Singularity 镜像或 .sif 路径 |
| TERMINAL_MODAL_IMAGE | Modal 容器镜像 |
| TERMINAL_DAYTONA_IMAGE | Daytona沙箱镜像 |
| TERMINAL_TIMEOUT | 命令超时时间（秒） |
| TERMINAL_LIFETIME_SECONDS | 终端会话的最大持续时间（秒） |
| TERMINAL_CWD | 所有终端会话的工作目录 |
| SUDO_PASSWORD | 启用无需交互提示的 sudo |
对于云沙箱后端，持久化采用文件系统方式。TERMINAL_LIFETIME_SECONDS 控制 Hermes 清理空闲终端会话的时间，后续恢复时可能重新创建沙箱，而非保留原有运行中的进程。
SSH 后端
| 变量 | 说明 |
|---|---|
TERMINAL_SSH_HOST | 远程服务器主机名 |
TERMINAL_SSH_USER | SSH 用户名 |
TERMINAL_SSH_PORT | SSH 端口（默认值：22） |
TERMINAL_SSH_KEY | 私钥路径 |
TERMINAL_SSH_PERSISTENT | 覆盖 SSH 的持久化 shell（默认值：遵循 TERMINAL_PERSISTENT_SHELL） |
容器资源（Docker、Singularity、Modal、Daytona）
| 变量 | 说明 |
|---|---|
TERMINAL_CONTAINER_CPU | CPU 核心数（默认值：1） |
TERMINAL_CONTAINER_MEMORY | 内存大小（MB，默认值：5120） |
TERMINAL_CONTAINER_DISK | 磁盘空间（MB，默认值：51200） |
TERMINAL_CONTAINER_PERSISTENT | 在会话间持久化容器文件系统（默认值：true） |
TERMINAL_SANDBOX_DIR | 工作区和覆盖层的主机目录（默认值：~/.hermes/sandboxes/） |
持久化 Shell
| 变量 | 说明 |
|---|---|
TERMINAL_PERSISTENT_SHELL | 为非本地后端启用持久化 shell（默认值：true）。也可通过 config.yaml 中的 terminal.persistent_shell 设置 |
TERMINAL_LOCAL_PERSISTENT | 为本地后端启用持久化 shell（默认值：false） |
TERMINAL_SSH_PERSISTENT | 覆盖 SSH 后端的持久化 shell（默认值：遵循 TERMINAL_PERSISTENT_SHELL） |
消息通知| 变量 | 说明 |
|------|------|
| TELEGRAM_BOT_TOKEN | Telegram 机器人的令牌（来自 @BotFather） |
| TELEGRAM_ALLOWED_USERS | 允许使用该机器人的用户 ID 列表，以逗号分隔 |
| TELEGRAM_HOME_CHANNEL | 定时任务消息的默认 Telegram 聊天/频道 |
| TELEGRAM_HOME_CHANNEL_NAME | Telegram 主频道的显示名称 |
| TELEGRAM_WEBHOOK_URL | Webhook 模式所需的公共 HTTPS URL（启用 webhook 而非轮询模式） |
| TELEGRAM_WEBHOOK_PORT | Webhook 服务器的本地监听端口（默认：8443） |
| TELEGRAM_WEBHOOK_SECRET | 用于验证更新来源为 Telegram 的密钥令牌 |
| TELEGRAM_REACTIONS | 处理消息期间启用表情反应（默认：false） |
| DISCORD_BOT_TOKEN | Discord 机器人的令牌 |
| DISCORD_ALLOWED_USERS | 允许使用该机器人的 Discord 用户 ID 列表，以逗号分隔 |
| DISCORD_HOME_CHANNEL | 定时任务消息的默认 Discord 频道 |
| DISCORD_HOME_CHANNEL_NAME | Discord 主频道的显示名称 |
| DISCORD_REQUIRE_MENTION | 在服务器频道中响应前要求 @提及 |
| DISCORD_FREE_RESPONSE_CHANNELS | 不需要 @提及的频道 ID 列表，以逗号分隔 |
| DISCORD_AUTO_THREAD | 支持时自动创建长回复线程 |
| DISCORD_REACTIONS | 处理消息期间启用表情反应（默认：true） |
| DISCORD_IGNORED_CHANNELS | 机器人从不响应的频道 ID 列表，以逗号分隔 |
| DISCORD_NO_THREAD_CHANNELS | 机器人响应但不自动创建线程的频道 ID 列表，以逗号分隔 |
| DISCORD_REPLY_TO_MODE | 回复引用行为：off、first（默认）、或 all |
| SLACK_BOT_TOKEN | Slack 机器人令牌（xoxb-...） |
| SLACK_APP_TOKEN | Slack 应用级令牌（xapp-...，Socket Mode 所需） |
| SLACK_ALLOWED_USERS | 允许使用该机器人的 Slack 用户 ID 列表，以逗号分隔 |
| SLACK_HOME_CHANNEL | 定时任务消息的默认 Slack 频道 |
| SLACK_HOME_CHANNEL_NAME | Slack 主频道的显示名称 |
| WHATSAPP_ENABLED | 启用 WhatsApp 桥接（true/false） |
| WHATSAPP_MODE | bot（独立号码）或 self-chat（给自己发消息） |
| WHATSAPP_ALLOWED_USERS | 允许的电话号码列表（含国家代码，不含 +），或 * 表示允许所有发送者 |
| WHATSAPP_ALLOW_ALL_USERS | 允许所有 WhatsApp 发送者而无需白名单（true/false） |
| WHATSAPP_DEBUG | 在桥接中记录原始消息事件以供故障排查（true/false） |
| SIGNAL_HTTP_URL | signal-cli 守护进程 HTTP 端点（例如 http://127.0.0.1:8080） |
| SIGNAL_ACCOUNT | 机器人的电话号码，E.164 格式 |
| SIGNAL_ALLOWED_USERS | 允许的 E.164 电话号码或 UUID 列表，以逗号分隔 |
| SIGNAL_GROUP_ALLOWED_USERS | 允许的群组 ID 列表，或 * 表示所有群组 |
| SIGNAL_HOME_CHANNEL_NAME | Signal 主频道的显示名称 |
| SIGNAL_IGNORE_STORIES | 忽略 Signal 的动态/状态更新 |
| SIGNAL_ALLOW_ALL_USERS | 允许所有 Signal 用户而无需白名单 |
| TWILIO_ACCOUNT_SID | Twilio 账户 SID（与语音技能共享） |
| TWILIO_AUTH_TOKEN | Twilio 认证令牌（与语音技能共享） |
| TWILIO_PHONE_NUMBER | Twilio 电话号码，E.164 格式（与语音技能共享） |
| SMS_WEBHOOK_PORT | 接收短信的 Webhook 监听端口（默认：8080） |
| SMS_ALLOWED_USERS | 允许聊天的 E.164 电话号码列表，以逗号分隔 |
| SMS_ALLOW_ALL_USERS | 允许所有 SMS 发送者而无需白名单 |
| SMS_HOME_CHANNEL | 用于定时任务/通知投递的电话号码 |
| SMS_HOME_CHANNEL_NAME | SMS 主频道的显示名称 |
| EMAIL_ADDRESS | 邮件网关适配器的邮箱地址 |
| EMAIL_PASSWORD | 邮箱账户的密码或应用专用密码 |
| EMAIL_IMAP_HOST | 邮件适配器的 IMAP 主机名 |
| EMAIL_IMAP_PORT | IMAP 端口 |
| EMAIL_SMTP_HOST | 邮件适配器的 SMTP 主机名 |
| EMAIL_SMTP_PORT | SMTP 端口 |
| EMAIL_ALLOWED_USERS | 允许向机器人发送消息的邮箱地址列表，以逗号分隔 |
| EMAIL_HOME_ADDRESS | 主动邮件投递的默认收件人 |
| EMAIL_HOME_ADDRESS_NAME | 邮件主目标的显示名称 |
| EMAIL_POLL_INTERVAL | 邮件轮询间隔（秒） |
| EMAIL_ALLOW_ALL_USERS | 允许所有入站邮件发送者 |
| DINGTALK_CLIENT_ID | 来自开发者门户的钉钉机器人 AppKey（open.dingtalk.com） |
| DINGTALK_CLIENT_SECRET | 来自开发者门户的钉钉机器人 AppSecret |
| DINGTALK_ALLOWED_USERS | 允许向机器人发送消息的钉钉用户 ID 列表，以逗号分隔 |
| FEISHU_APP_ID | 飞书/Lark 机器人 App ID（来自 open.feishu.cn） |
| FEISHU_APP_SECRET | 飞书/Lark 机器人 App Secret |
| FEISHU_DOMAIN | feishu（中国区）或 lark（国际版）。默认：feishu |
| FEISHU_CONNECTION_MODE | websocket（推荐）或 webhook。默认：websocket |
| FEISHU_ENCRYPT_KEY | Webhook 模式可选加密密钥 |
| FEISHU_VERIFICATION_TOKEN | Webhook 模式可选验证令牌 |
| FEISHU_ALLOWED_USERS | 允许向机器人发送消息的飞书用户 ID 列表，以逗号分隔 |
| FEISHU_HOME_CHANNEL | 飞书定时任务和通知的聊天 ID |
| WECOM_BOT_ID | 企业微信 AI 机器人 ID（来自管理控制台） |
| WECOM_SECRET | 企业微信 AI 机器人密钥 |
| WECOM_WEBSOCKET_URL | 自定义 WebSocket URL（默认：wss://openws.work.weixin.qq.com） |
| WECOM_ALLOWED_USERS | 允许向机器人发送消息的企业微信用户 ID 列表，以逗号分隔 |
| WECOM_HOME_CHANNEL | 企业微信定时任务和通知的聊天 ID |
| WEIXIN_ACCOUNT_ID | 通过 iLink Bot API 的二维码登录获取的微信账号 ID |
| WEIXIN_TOKEN | 通过 iLink Bot API 的二维码登录获取的微信认证令牌 |
| WEIXIN_BASE_URL | 覆盖微信 iLink Bot API 基础 URL（默认：https://ilinkai.weixin.qq.com） |
| WEIXIN_CDN_BASE_URL | 覆盖微信 CDN 基础 URL 用于媒体传输（默认：https://novac2c.cdn.weixin.qq.com/c2c） |
| WEIXIN_DM_POLICY | 私信策略：open、allowlist、pairing、disabled（默认：open） |
| WEIXIN_GROUP_POLICY | 群聊消息策略：open、allowlist、disabled（默认：disabled） |
| WEIXIN_ALLOWED_USERS | 允许私信机器人的微信用户 ID 列表，以逗号分隔 |
| WEIXIN_GROUP_ALLOWED_USERS | 允许与机器人互动的微信群 ID 列表，以逗号分隔 |
| WEIXIN_HOME_CHANNEL | 微信定时任务和通知的聊天 ID |
| WEIXIN_HOME_CHANNEL_NAME | 微信主频道的显示名称 |
| WEIXIN_ALLOW_ALL_USERS | 允许所有微信用户而无需白名单（true/false） |
| BLUEBUBBLES_SERVER_URL | BlueBubbles 服务器 URL（如 http://192.168.1.10:1234） |
| BLUEBUBBLES_PASSWORD | BlueBubbles 服务器密码 |
| BLUEBUBBLES_WEBHOOK_HOST | Webhook 监听绑定地址（默认：127.0.0.1） |
| BLUEBUBBLES_WEBHOOK_PORT | Webhook 监听端口（默认：8645） |
| BLUEBUBBLES_HOME_CHANNEL | 用于定时任务/通知投递的电话/邮箱 |
| BLUEBUBBLES_ALLOWED_USERS | 已授权用户的列表，以逗号分隔 |
| BLUEBUBBLES_ALLOW_ALL_USERS | 允许所有用户（true/false） |
| MATTERMOST_URL | Mattermost 服务器 URL（如 https://mm.example.com） |
| MATTERMOST_TOKEN | Mattermost 机器人令牌或个人访问令牌 |
| MATTERMOST_ALLOWED_USERS | 允许向机器人发送消息的 Mattermost 用户 ID 列表，以逗号分隔 |
| MATTERMOST_HOME_CHANNEL | 主动消息投递（定时任务、通知）的频道 ID |
| MATTERMOST_REQUIRE_MENTION | 要求在频道中包含 @mention（默认：true）。设为 false 可对所有消息作出响应。 |
| MATTERMOST_FREE_RESPONSE_CHANNELS | 机器人在其中无需 @mention 即可响应的频道 ID 列表，以逗号分隔 |
| MATTERMOST_REPLY_MODE | 回复样式：thread（线程回复）或 off（扁平消息，默认） |
| MATRIX_HOMESERVER | Matrix 服务器 URL（如 https://matrix.org） |
| MATRIX_ACCESS_TOKEN | 机器人身份验证的 Matrix 访问令牌 |
| MATRIX_USER_ID | Matrix 用户 ID（如 @hermes:matrix.org）—— 密码登录时必需，使用访问令牌时可选 |
| MATRIX_PASSWORD | Matrix 密码（替代访问令牌） |
| MATRIX_ALLOWED_USERS | 允许向机器人发送消息的 Matrix 用户 ID 列表，以逗号分隔（如 @alice:matrix.org） |
| MATRIX_HOME_ROOM | 主动消息投递的房间 ID（如 !abc123:matrix.org） |
| MATRIX_ENCRYPTION | 启用端到端加密（true/false，默认：false） |
| MATRIX_REQUIRE_MENTION | 要求在房间中包含 @mention（默认：true）。设为 false 可对所有消息作出响应。 |
| MATRIX_FREE_RESPONSE_ROOMS | 机器人在其中无需 @mention 即可响应的房间 ID 列表，以逗号分隔 |
| MATRIX_AUTO_THREAD | 自动为房间消息创建线程（默认：true） |
| MATRIX_DM_MENTION_THREADS | 当机器人在 DM 中被 @mentioned 时创建线程（默认：false） |
| HASS_TOKEN | Home Assistant 长期访问令牌（启用 HA 平台 + 工具） |
| HASS_URL | Home Assistant URL（默认：http://homeassistant.local:8123） |
| WEBHOOK_ENABLED | 启用 Webhook 平台适配器（true/false） |
| WEBHOOK_PORT | 接收 Webhook 的 HTTP 服务器端口（默认：8644） |
| WEBHOOK_SECRET | 全局 HMAC 密钥，用于 Webhook 签名验证（当路由未指定自身密钥时作为备用） |
| API_SERVER_ENABLED | 启用 OpenAI 兼容 API 服务器（true/false）。与其它平台并行运行。 |
| API_SERVER_KEY | API 服务器认证的 Bearer Token。对非本地绑定强制启用。 |
| API_SERVER_CORS_ORIGINS | 允许直接调用 API 服务器的浏览器源列表，以逗号分隔（例如 http://localhost:3000,http://127.0.0.1:3000）。默认：禁用。 |
| API_SERVER_PORT | API 服务器端口（默认：8642） |
| API_SERVER_HOST | API 服务器的主机/绑定地址（默认：127.0.0.1）。使用 0.0.0.0 实现网络访问——需配合 API_SERVER_KEY 和窄范围的 API_SERVER_CORS_ORIGINS 白名单。 |
| API_SERVER_MODEL_NAME | 在 /v1/models 上公布的模型名称。默认为配置文件名（或 hermes-agent 为默认配置）。适用于多用户场景，前端如 Open WebUI 需要为每个连接指定不同的模型名称。 |
| MESSAGING_CWD | 消息模式下终端命令的工作目录（默认：~） |
| GATEWAY_ALLOWED_USERS | 跨所有平台允许的用户 ID 列表，以逗号分隔 |
| GATEWAY_ALLOW_ALL_USERS | 允许所有用户而无需白名单（true/false，默认：false） |## 代理行为
| 变量 | 描述 |
|---|---|
HERMES_MAX_ITERATIONS | 每次对话中最大工具调用迭代次数（默认：90） |
HERMES_TOOL_PROGRESS | 已弃用的兼容性变量，用于控制工具进度显示。建议在 config.yaml 中使用 display.tool_progress。 |
HERMES_TOOL_PROGRESS_MODE | 已弃用的兼容性变量，用于设置工具进度模式。建议在 config.yaml 中使用 display.tool_progress。 |
HERMES_HUMAN_DELAY_MODE | 响应节奏：off/natural/custom |
HERMES_HUMAN_DELAY_MIN_MS | 自定义延迟范围最小值（毫秒） |
HERMES_HUMAN_DELAY_MAX_MS | 自定义延迟范围最大值（毫秒） |
HERMES_QUIET | 抑制非必要输出（true/false） |
HERMES_API_TIMEOUT | LLM API 调用超时时间（秒，默认：1800） |
HERMES_STREAM_READ_TIMEOUT | 流式传输读取超时时间（秒，默认：120）。本地提供者会自动增加至 HERMES_API_TIMEOUT。若本地 LLM 在长时间代码生成时超时，请适当提高该值。 |
HERMES_STREAM_STALE_TIMEOUT | 静默流检测超时时间（秒，默认：180）。本地提供者会自动禁用。若在此时间段内未收到任何数据块，则触发连接终止。 |
HERMES_EXEC_ASK | 在网关模式下启用执行审批提示（true/false） |
HERMES_ENABLE_PROJECT_PLUGINS | 启用从 ./.hermes/plugins/ 自动发现仓库本地插件（true/false，默认：false） |
HERMES_BACKGROUND_NOTIFICATIONS | 网关模式下的后台进程通知模式：all（默认）、result、error、off |
HERMES_EPHEMERAL_SYSTEM_PROMPT | 在 API 调用时注入的临时系统提示（永不持久化到会话中） |
定时调度器
| 变量 | 描述 |
|---|---|
HERMES_CRON_TIMEOUT | 定时任务代理运行的空闲超时时间（秒，默认：600）。当代理正在持续调用工具或接收流式数据时，不会触发此超时；仅在完全空闲时生效。设为 0 可实现无限期运行。 |
HERMES_CRON_SCRIPT_TIMEOUT | 定时任务前运行脚本的超时时间（秒，默认：120）。对于需要更长执行时间的脚本（如反机器人定时的随机延迟），可进行覆盖。也可通过 config.yaml 中的 cron.script_timeout_seconds 进行配置。 |
会话设置
| 变量 | 描述 |
|---|---|
SESSION_IDLE_MINUTES | 会话在连续 N 分钟无操作后重置（默认：1440） |
SESSION_RESET_HOUR | 每日重置时间（24小时制，默认：4 = 凌晨4点） |
上下文压缩（仅 config.yaml）
上下文压缩仅通过 config.yaml 中的 compression 配置部分进行设置 —— 不存在相关环境变量。
compression:
enabled: true
threshold: 0.50
summary_model: "" # empty = use main configured model
summary_provider: auto
summary_base_url: null # Custom OpenAI-compatible endpoint for summaries
辅助任务覆盖
| 变量 | 描述 |
|---|---|
AUXILIARY_VISION_PROVIDER | 覆盖视觉任务的提供者 |
AUXILIARY_VISION_MODEL | 覆盖视觉任务的模型 |
AUXILIARY_VISION_BASE_URL | 视觉任务的直接 OpenAI 兼容端点 |
AUXILIARY_VISION_API_KEY | 与 AUXILIARY_VISION_BASE_URL 配对使用的 API 密钥 |
AUXILIARY_WEB_EXTRACT_PROVIDER | 覆盖网页提取/摘要任务的提供者 |
AUXILIARY_WEB_EXTRACT_MODEL | 覆盖网页提取/摘要任务的模型 |
AUXILIARY_WEB_EXTRACT_BASE_URL | 网页提取/摘要任务的直接 OpenAI 兼容端点 |
AUXILIARY_WEB_EXTRACT_API_KEY | 与 AUXILIARY_WEB_EXTRACT_BASE_URL 配对使用的 API 密钥 |
对于特定任务的直接端点，Hermes 会使用任务配置的 API 密钥或 OPENAI_API_KEY。它不会复用 OPENROUTER_API_KEY 来访问这些自定义端点。
备用模型（仅 config.yaml）
主模型的备用机制仅通过 config.yaml 配置 —— 无对应环境变量。在配置文件中添加一个包含 provider 和 model 键的 fallback_model 部分，可在主模型出现错误时启用自动故障转移。
fallback_model:
provider: openrouter
model: anthropic/claude-sonnet-4
详情请参见 备用提供者。
提供者路由（仅 config.yaml）
这些配置项需置于 ~/.hermes/config.yaml 的 provider_routing 部分中：
| 键 | 描述 |
|---|---|
sort | 提供者排序方式："price"（默认）、"throughput" 或 "latency" |
only | 允许使用的提供者别名列表（例如 ["anthropic", "google"]） |
ignore | 要跳过的提供者别名列表 |
order | 按顺序尝试的提供者别名列表 |
require_parameters | 仅使用支持所有请求参数的提供者（true/false） |
data_collection | "allow"（默认）或 "deny"，用于排除存储数据的提供者 |
使用 hermes config set 来设置环境变量 —— 它会自动将它们保存到正确文件中（.env 用于密钥，config.yaml 用于其他内容）。