环境变量参考
本页汇总了 Hermes Agent 支持的主要环境变量。大多数变量应写入 ~/.hermes/.env，你也可以通过 hermes config set VAR value 来设置。
大语言模型（LLM）提供商
| 变量 | 描述 |
|---|---|
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 令牌，用于 Copilot API，优先级最高（支持 OAuth gho_* 或细粒度 PAT github_pat_*；不支持经典 PAT ghp_*） |
GH_TOKEN | GitHub 令牌，Copilot 第二优先级（也供 gh CLI 使用） |
GITHUB_TOKEN | GitHub 令牌，Copilot 第三优先级 |
HERMES_COPILOT_ACP_COMMAND | 覆盖 Copilot ACP 可执行文件路径（默认：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） |
KIMI_CN_API_KEY | Kimi / Moonshot 中国区 API 密钥 (moonshot.cn) |
ARCEEAI_API_KEY | Arcee AI API 密钥 (chat.arcee.ai) |
ARCEE_BASE_URL | 覆盖 Arcee 基地址（默认：https://api.arcee.ai/api/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） |
XIAOMI_API_KEY | 小米 MiMo API 密钥 (platform.xiaomimimo.com) |
XIAOMI_BASE_URL | 覆盖小米 MiMo 基地址（默认：https://api.xiaomimimo.com/v1） |
HF_TOKEN | Hugging Face 令牌，用于推理提供商 (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 控制台 API 密钥 (console.anthropic.com) |
ANTHROPIC_TOKEN | 手动或旧版 Anthropic OAuth/设置令牌覆盖 |
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 OAuth 令牌，可用它显式覆盖默认值 |
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 认证，Hermes 会优先使用 Claude Code 自己的凭证文件，因为这些凭证可以自动刷新。像 ANTHROPIC_TOKEN 这样的环境变量仍可作为手动覆盖，但已经不是 Claude Pro/Max 登录的首选方式。
| 变量 | 描述 |
|---|---|
HERMES_INFERENCE_PROVIDER | 覆盖提供商标识：auto、openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、huggingface、zai、kimi-coding、kimi-coding-cn、minimax、minimax-cn、kilocode、xiaomi、arcee、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 | 最小代理密钥存活时间（秒），超过后重新生成（默认：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 URL（通过 /browser connect 设置，例如 ws://localhost:9222） |
CAMOFOX_URL | Camofox 本地反检测浏览器 URL（默认：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 令牌，用于 Skills Hub（更高的 API 速率限制、技能发布） |
HONCHO_API_KEY | 跨会话用户建模 (honcho.dev) |
HONCHO_BASE_URL | 自托管 Honcho 实例的基础 URL（默认：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，默认：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 认证令牌（与语音技能共享；也用于 webhook 签名验证） |
TWILIO_PHONE_NUMBER | Twilio 电话号码（E.164 格式，与语音技能共享） |
SMS_WEBHOOK_URL | Twilio 签名验证的公共 URL — 必须与 Twilio 控制台中的 webhook URL 匹配（必需） |
SMS_WEBHOOK_PORT | 接收短信的 webhook 监听端口（默认：8080） |
SMS_WEBHOOK_HOST | Webhook 绑定地址（默认：0.0.0.0） |
SMS_INSECURE_NO_SIGNATURE | 设置为 true 以禁用 Twilio 签名验证（仅限本地开发，不适用于生产环境） |
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 | 来自 open.feishu.cn 的飞书/Lark 机器人 App ID |
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 |
WECOM_CALLBACK_CORP_ID | 企业微信企业 Corp ID（用于回调自建应用） |
WECOM_CALLBACK_CORP_SECRET | 自建应用的 Corp Secret |
WECOM_CALLBACK_AGENT_ID | 自建应用的 Agent ID |
WECOM_CALLBACK_TOKEN | 回调验证令牌 |
WECOM_CALLBACK_ENCODING_AES_KEY | 回调加密的 AES 密钥 |
WECOM_CALLBACK_HOST | 回调服务器绑定地址（默认：0.0.0.0） |
WECOM_CALLBACK_PORT | 回调服务器端口（默认：8645） |
WECOM_CALLBACK_ALLOWED_USERS | 逗号分隔的允许用户 ID 列表 |
WECOM_CALLBACK_ALLOW_ALL_USERS | 设置 true 以允许所有用户而无需白名单 |
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） |
QQ_APP_ID | 来自 q.qq.com 的 QQ 机器人 App ID |
QQ_CLIENT_SECRET | 来自 q.qq.com 的 QQ 机器人 App Secret |
QQ_STT_API_KEY | 外部 STT 备用提供商的 API 密钥（可选，当 QQ 内置 ASR 没有返回文本时使用） |
QQ_STT_BASE_URL | 外部 STT 提供商的基础 URL（可选） |
QQ_STT_MODEL | 外部 STT 提供商的模型名称（可选） |
QQ_ALLOWED_USERS | 允许向机器人发消息的逗号分隔 QQ 用户 openID 列表 |
QQ_GROUP_ALLOWED_USERS | 用于群 @ 消息访问的逗号分隔 QQ 群 ID 列表 |
QQ_ALLOW_ALL_USERS | 允许所有用户（true/false，覆盖 QQ_ALLOWED_USERS） |
QQ_HOME_CHANNEL | 用于定时任务和通知的 QQ 用户/群 openID |
MATTERMOST_URL | Mattermost 服务器 URL（如 https://mm.example.com） |
MATTERMOST_TOKEN | Mattermost 机器人令牌或个人访问令牌 |
MATTERMOST_ALLOWED_USERS | 允许向机器人发消息的逗号分隔 Mattermost 用户 ID 列表 |
MATTERMOST_HOME_CHANNEL | 主动消息投递（定时任务、通知）的频道 ID |
MATTERMOST_REQUIRE_MENTION | 是否要求在频道中包含 @mention（默认：需包含）。设置为 false 以对所有消息作出响应。 |
MATTERMOST_FREE_RESPONSE_CHANNELS | 机器人响应但无需 @mention 的逗号分隔频道 ID 列表 |
MATTERMOST_REPLY_MODE | 回复风格：thread（线程回复）或 off（扁平消息，默认） |
MATRIX_HOMESERVER | Matrix homeserver 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（默认：需包含）。设置为 false 以对所有消息作出响应。 |
MATRIX_FREE_RESPONSE_ROOMS | 机器人响应但无需 @mention 的逗号分隔房间 ID 列表 |
MATRIX_AUTO_THREAD | 自动为房间消息创建线程（默认：true） |
MATRIX_DM_MENTION_THREADS | 当机器人在 DM 中被 @mentioned 时自动创建线程（默认：false） |
MATRIX_RECOVERY_KEY | 设备密钥轮换后用于交叉签名验证的恢复密钥。建议在启用交叉签名的 E2EE 设置中使用。 |
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 | 流式传输 socket 读取超时时间（秒），默认值为 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: 配置块，而摘要模型与提供商配置位于 auxiliary.compression: 下。
compression:
enabled: true
threshold: 0.50
target_ratio: 0.20 # fraction of threshold to preserve as recent tail
protect_last_n: 20 # minimum recent messages to keep uncompressed
旧版迁移
包含 compression.summary_model、compression.summary_provider 和 compression.summary_base_url 的旧版配置将在首次加载时自动迁移到 auxiliary.compression.*。
辅助任务覆盖
| 变量 | 描述 |
|---|---|
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 配置 —— 无环境变量支持。在配置文件中添加一个 fallback_model 块，并包含 provider 和 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"，用于排除会存储数据的提供商 |
tip
使用 hermes config set 设置环境变量 —— 它会自动将变量保存到正确文件中（.env 用于密钥，config.yaml 用于其他所有内容）。