环境变量参考
所有变量均位于 ~/.hermes/.env 文件中。你也可以使用 hermes config set VAR value 来设置它们。
大语言模型（LLM）提供商
| 变量 | 说明 |
|---|---|
OPENROUTER_API_KEY | OpenRouter API 密钥（推荐，灵活性高） |
OPENROUTER_BASE_URL | 覆盖兼容 OpenRouter 的基础 URL |
NOUS_BASE_URL | 覆盖 Nous Portal 基础 URL（很少需要；仅限开发/测试） |
NOUS_INFERENCE_BASE_URL | 直接覆盖 Nous 推理端点 |
AI_GATEWAY_API_KEY | Vercel AI Gateway API 密钥（ai-gateway.vercel.sh） |
AI_GATEWAY_BASE_URL | 覆盖 AI Gateway 基础 URL（默认值：https://ai-gateway.vercel.sh/v1） |
OPENAI_API_KEY | 自定义兼容 OpenAI 端点的 API 密钥（与 OPENAI_BASE_URL 配合使用） |
OPENAI_BASE_URL | 自定义端点的基础 URL（如 VLLM、SGLang 等） |
COPILOT_GITHUB_TOKEN | 用于 Copilot API 的 GitHub 令牌 — 优先级最高（OAuth gho_* 或细粒度 PAT github_pat_*；经典 PAT ghp_* 不支持） |
GH_TOKEN | GitHub 令牌 — Copilot 的第二优先级（也被 gh CLI 使用） |
GITHUB_TOKEN | GitHub 令牌 — 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 基础 URL |
GLM_API_KEY | z.ai / 智谱 AI GLM API 密钥（z.ai） |
ZAI_API_KEY | GLM_API_KEY 的别名 |
Z_AI_API_KEY | GLM_API_KEY 的别名 |
GLM_BASE_URL | 覆盖 z.ai 基础 URL（默认值：https://api.z.ai/api/paas/v4） |
KIMI_API_KEY | Kimi / Moonshot AI API 密钥（moonshot.ai） |
KIMI_BASE_URL | 覆盖 Kimi 基础 URL（默认值：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 基础 URL（默认值：https://api.arcee.ai/api/v1） |
MINIMAX_API_KEY | MiniMax API 密钥 — 全球端点（minimax.io） |
MINIMAX_BASE_URL | 覆盖 MiniMax 基础 URL（默认值：https://api.minimax.io/anthropic — Hermes 使用 MiniMax 兼容 Anthropic Messages 的端点） |
MINIMAX_CN_API_KEY | MiniMax API 密钥 — 中国端点（minimaxi.com） |
MINIMAX_CN_BASE_URL | 覆盖 MiniMax 中国基础 URL（默认值：https://api.minimaxi.com/anthropic） |
KILOCODE_API_KEY | Kilo Code API 密钥（kilo.ai） |
KILOCODE_BASE_URL | 覆盖 Kilo Code 基础 URL（默认值：https://api.kilo.ai/api/gateway） |
XIAOMI_API_KEY | 小米 MiMo API 密钥（platform.xiaomimimo.com） |
XIAOMI_BASE_URL | 覆盖小米 MiMo 基础 URL（默认值：https://api.xiaomimimo.com/v1） |
HF_TOKEN | 用于推理提供商的 Hugging Face 令牌（huggingface.co/settings/tokens） |
HF_BASE_URL | 覆盖 Hugging Face 基础 URL（默认值：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 基础 URL |
HERMES_GEMINI_CLIENT_ID | 用于 google-gemini-cli PKCE 登录的 OAuth 客户端 ID（可选；默认为 Google 公开的 gemini-cli 客户端） |
HERMES_GEMINI_CLIENT_SECRET | 用于 google-gemini-cli 的 OAuth 客户端密钥（可选） |
HERMES_GEMINI_PROJECT_ID | 付费 Gemini 层级的 GCP 项目 ID（免费层级自动配置） |
ANTHROPIC_API_KEY | Anthropic 控制台 API 密钥（console.anthropic.com） |
ANTHROPIC_TOKEN | 手动或旧版 Anthropic OAuth/setup-token 覆盖 |
DASHSCOPE_API_KEY | 用于 Qwen 模型的阿里云 DashScope API 密钥（modelstudio.console.alibabacloud.com） |
DASHSCOPE_BASE_URL | 自定义 DashScope 基础 URL（默认值：https://dashscope-intl.aliyuncs.com/compatible-mode/v1；中国大陆区域请使用 https://dashscope.aliyuncs.com/compatible-mode/v1） |
DEEPSEEK_API_KEY | 直接访问 DeepSeek 的 API 密钥（platform.deepseek.com） |
DEEPSEEK_BASE_URL | 自定义 DeepSeek API 基础 URL |
NVIDIA_API_KEY | NVIDIA NIM API 密钥 — Nemotron 和开源模型（build.nvidia.com） |
NVIDIA_BASE_URL | 覆盖 NVIDIA 基础 URL（默认值：https://integrate.api.nvidia.com/v1；本地 NIM 端点请设为 http://localhost:8000/v1） |
OLLAMA_API_KEY | Ollama Cloud API 密钥 — 无需本地 GPU 的托管 Ollama 目录（ollama.com/settings/keys） |
OLLAMA_BASE_URL | 覆盖 Ollama Cloud 基础 URL（默认值：https://ollama.com/v1） |
XAI_API_KEY | xAI（Grok）聊天 + TTS 的 API 密钥（console.x.ai） |
XAI_BASE_URL | 覆盖 xAI 基础 URL（默认值：https://api.x.ai/v1） |
MISTRAL_API_KEY | Mistral Voxtral TTS 和 Voxtral STT 的 API 密钥（console.mistral.ai） |
AWS_REGION | 用于 Bedrock 推理的 AWS 区域（例如 us-east-1、eu-central-1）。由 boto3 读取。 |
AWS_PROFILE | 用于 Bedrock 身份验证的 AWS 命名配置文件（读取 ~/.aws/credentials）。留空则使用默认 boto3 凭证链。 |
BEDROCK_BASE_URL | 覆盖 Bedrock 运行时基础 URL（默认值：https://bedrock-runtime.us-east-1.amazonaws.com；通常留空并使用 AWS_REGION 替代） |
HERMES_QWEN_BASE_URL | Qwen Portal 基础 URL 覆盖（默认值：https://portal.qwen.ai/v1） |
OPENCODE_ZEN_API_KEY | OpenCode Zen API 密钥 — 按需付费访问精选模型（opencode.ai） |
OPENCODE_ZEN_BASE_URL | 覆盖 OpenCode Zen 基础 URL |
OPENCODE_GO_API_KEY | OpenCode Go API 密钥 — 开源模型每月 $10 订阅（opencode.ai） |
OPENCODE_GO_BASE_URL | 覆盖 OpenCode Go 基础 URL |
CLAUDE_CODE_OAUTH_TOKEN | 如果你手动导出了一个 Claude Code 令牌，则显式覆盖 |
HERMES_MODEL | 在进程级别覆盖模型名称（由 cron 调度器使用；正常情况请优先使用 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、kimi-coding-cn、minimax、minimax-cn、kilocode、xiaomi、arcee、alibaba、deepseek、nvidia、ollama-cloud、xai（别名 grok）、google-gemini-cli、qwen-oauth、bedrock、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 | 在 API 调用时注入的临时预填充消息 JSON 文件路径 |
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 | 用于 AI 原生网络搜索、提取和爬取的 Tavily API 密钥（app.tavily.com） |
EXA_API_KEY | 用于 AI 原生网络搜索和内容的 Exa API 密钥（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 浏览器会话 TTL（秒）（默认值：300） |
BROWSER_CDP_URL | 本地浏览器的 Chrome DevTools 协议 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 | 覆盖兼容 OpenAI 的 Groq STT 端点 |
STT_OPENAI_MODEL | 覆盖 OpenAI STT 模型（默认值：whisper-1） |
STT_OPENAI_BASE_URL | 覆盖兼容 OpenAI 的 STT 端点 |
GITHUB_TOKEN | 用于 Skills Hub 的 GitHub 令牌（更高的 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） |
Nous 工具网关
这些变量用于为付费 Nous 订阅者或自托管网关部署配置工具网关。大多数用户无需设置这些变量 — 网关会通过 hermes model 或 hermes tools 自动配置。
| 变量 | 说明 |
|---|---|
TOOL_GATEWAY_DOMAIN | 工具网关路由的基础域名（默认值：nousresearch.com） |
TOOL_GATEWAY_SCHEME | 网关 URL 的 HTTP 或 HTTPS 方案（默认值：https） |
TOOL_GATEWAY_USER_TOKEN | 工具网关的身份验证令牌（通常从 Nous 身份验证自动填充） |
FIRECRAWL_GATEWAY_URL | 专门覆盖 Firecrawl 网关端点的 URL |
终端后端
| 变量 | 说明 |
|---|---|
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 卷挂载（逗号分隔的 主机路径:容器路径 对） |
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 | cron 投递的默认 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） |
TELEGRAM_REPLY_TO_MODE | 回复引用行为：off、first（默认值）或 all。与 Discord 模式一致。 |
TELEGRAM_IGNORED_THREADS | 机器人从不响应的逗号分隔 Telegram 论坛主题/线程 ID 列表 |
TELEGRAM_PROXY | 用于 Telegram 连接的代理 URL — 覆盖 HTTPS_PROXY。支持 http://、https://、socks5:// |
DISCORD_BOT_TOKEN | Discord 机器人令牌 |
DISCORD_ALLOWED_USERS | 允许使用机器人的逗号分隔 Discord 用户 ID 列表 |
DISCORD_ALLOWED_ROLES | 允许使用机器人的逗号分隔 Discord 角色 ID 列表（与 DISCORD_ALLOWED_USERS 为 OR 关系）。自动启用 Members 意图。当管理团队变动时非常有用 — 角色权限会自动传播。 |
DISCORD_ALLOWED_CHANNELS | 逗号分隔的 Discord 频道 ID 列表。设置后，机器人仅在这些频道中响应（如果允许，还包括私信）。覆盖 config.yaml 中的 discord.allowed_channels。 |
DISCORD_PROXY | 用于 Discord 连接的代理 URL — 覆盖 HTTPS_PROXY。支持 http://、https://、socks5:// |
DISCORD_HOME_CHANNEL | cron 投递的默认 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 |
DISCORD_ALLOW_MENTION_EVERYONE | 允许机器人 ping @everyone/@here（默认值：false）。参见提及控制。 |
DISCORD_ALLOW_MENTION_ROLES | 允许机器人 ping @role 提及（默认值：false）。 |
DISCORD_ALLOW_MENTION_USERS | 允许机器人 ping 个别 @user 提及（默认值：true）。 |
DISCORD_ALLOW_MENTION_REPLIED_USER | 回复用户消息时 ping 该作者（默认值：true）。 |
SLACK_BOT_TOKEN | Slack 机器人令牌（xoxb-...） |
SLACK_APP_TOKEN | Slack 应用级令牌（xapp-...，Socket 模式必需） |
SLACK_ALLOWED_USERS | 逗号分隔的 Slack 用户 ID 列表 |
SLACK_HOME_CHANNEL | cron 投递的默认 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 | 入站 SMS 的 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 | cron 作业 / 通知投递的电话号码 |
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 | cron 投递和通知的飞书聊天 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 | cron 投递和通知的企业微信聊天 ID |
WECOM_CALLBACK_CORP_ID | 回调自建应用的企业微信企业 Corp ID |
WECOM_CALLBACK_CORP_SECRET | 自建应用的企业密钥 |
WECOM_CALLBACK_AGENT_ID | 自建应用的智能体 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 机器人 API 扫码登录获得的微信账户 ID |
WEIXIN_TOKEN | 通过 iLink 机器人 API 扫码登录获得的微信身份验证令牌 |
WEIXIN_BASE_URL | 覆盖微信 iLink 机器人 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 | cron 投递和通知的微信聊天 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 | cron/通知投递的电话/电子邮件 |
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） |
QQBOT_HOME_CHANNEL | cron 投递和通知的 QQ 用户/群组 openID |
QQBOT_HOME_CHANNEL_NAME | QQ 主频道的显示名称 |
QQ_SANDBOX | 将 QQ 机器人路由到沙箱网关以进行开发测试（true/false）。请使用来自 q.qq.com 的沙箱应用凭证。 |
MATTERMOST_URL | Mattermost 服务器 URL（例如 https://mm.example.com） |
MATTERMOST_TOKEN | Mattermost 的机器人令牌或个人访问令牌 |
MATTERMOST_ALLOWED_USERS | 允许向机器人发送消息的逗号分隔 Mattermost 用户 ID 列表 |
MATTERMOST_HOME_CHANNEL | 主动消息投递（cron、通知）的频道 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_DEVICE_ID | 跨重启保持 E2EE 持久性的稳定 Matrix 设备 ID（例如 HERMES_BOT）。若无此设置，E2EE 密钥每次启动都会轮换，导致历史房间解密失败。 |
MATRIX_REACTIONS | 对入站消息启用处理生命周期表情符号反应（默认值：true）。设为 false 可禁用。 |
MATRIX_REQUIRE_MENTION | 在房间中需要 @mention（默认值：true）。设为 false 可响应所有消息。 |
MATRIX_FREE_RESPONSE_ROOMS | 机器人无需 @mention 即可响应的逗号分隔房间 ID 列表 |
MATRIX_AUTO_THREAD | 为房间消息自动创建线程（默认值：true） |
MATRIX_DM_MENTION_THREADS | 当机器人在私信中被 @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 | 用于 webhook 签名验证的全局 HMAC 密钥（当路由未指定自身密钥时作为回退） |
API_SERVER_ENABLED | 启用兼容 OpenAI 的 API 服务器（true/false）。与其他平台并行运行。 |
API_SERVER_KEY | API 服务器身份验证的 Bearer 令牌。对非环回绑定强制执行。 |
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）需要每个连接具有不同的模型名称。 |
GATEWAY_PROXY_URL | 要转发消息的远程 Hermes API 服务器 URL（代理模式）。设置后，网关仅处理平台 I/O — 所有智能体工作均委托给远程服务器。也可通过 config.yaml 中的 gateway.proxy_url 配置。 |
GATEWAY_PROXY_KEY | 代理模式下用于对远程 API 服务器进行身份验证的 Bearer 令牌。必须与远程主机上的 API_SERVER_KEY 匹配。 |
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_API_CALL_STALE_TIMEOUT | 非流式陈旧调用超时时间（秒）（默认值：300）。本地提供商留空时自动禁用。也可通过 config.yaml 中的 providers.<id>.stale_timeout_seconds 或 providers.<id>.models.<model>.stale_timeout_seconds 配置。 |
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 调用时注入的临时系统提示（从不持久化到会话中） |
DELEGATION_MAX_CONCURRENT_CHILDREN | 每个 delegate_task 批次的最大并行子智能体数量（默认值：3，下限为 1，无上限）。也可通过 config.yaml 中的 delegation.max_concurrent_children 配置 — 配置文件中的值优先级更高。 |
界面
| 变量 | 说明 |
|---|---|
HERMES_TUI | 设为 1 时启动 TUI 而非经典 CLI。等效于传递 --tui。 |
HERMES_TUI_DIR | 预构建的 ui-tui/ 目录路径（必须包含 dist/entry.js 和已填充的 node_modules）。由发行版和 Nix 使用，以跳过首次启动时的 npm install。 |
Cron 调度器
| 变量 | 说明 |
|---|---|
HERMES_CRON_TIMEOUT | cron 作业智能体运行的无活动超时时间（秒）（默认值：600）。智能体在 actively 调用工具或接收流令牌时可以无限期运行 — 此设置仅在空闲时触发。设为 0 表示无限制。 |
HERMES_CRON_SCRIPT_TIMEOUT | 附加到 cron 作业的预运行脚本超时时间（秒）（默认值：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 # 保留为最近尾部的阈值比例
protect_last_n: 20 # 保持未压缩的最小最近消息数
旧版迁移
包含 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 配置 — 没有相关的环境变量。添加一个包含 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 | 允许的提供商 slug 列表（例如 ["anthropic", "google"]） |
ignore | 跳过的提供商 slug 列表 |
order | 按顺序尝试的提供商 slug 列表 |
require_parameters | 仅使用支持所有请求参数的提供商（true/false） |
data_collection | "allow"（默认值）或 "deny" 以排除数据存储提供商 |
提示
使用 hermes config set 设置环境变量 — 它会自动将它们保存到正确的文件中（.env 用于机密，config.yaml 用于其他所有内容）。