sidebar_position: 2 title: “Environment Variables” description: “Complete reference of all environment variables used by Hermes Agent”

环境变量参考

Hermes 会从进程环境读取环境变量，而对于用户管理的机密信息，则从 ~/.hermes/.env 文件中获取。请将 API 密钥、机器人令牌、OAuth 密钥以及其他凭证存储在 .env 文件中；如果存在配置键，建议优先使用 config.yaml 来设置非机密性的行为参数。以下部分变量仅为进程级覆盖项或内部桥接变量，即便此处有相关说明，也不应将其加入 .env 文件中。

大语言模型提供方| 变量名 | 描述 |

|––––|——| | OPENROUTER_API_KEY | OpenRouter API密钥（为提升灵活性推荐使用） | | OPENROUTER_BASE_URL | 覆盖与OpenRouter兼容的基URL | | HERMES_OPENROUTER_CACHE | 启用OpenRouter响应缓存（值为1/true/yes/on）。会覆盖config.yaml中的openrouter.response_cache设置。详情请参阅响应缓存。 | | HERMES_OPENROUTER_CACHE_TTL | 缓存有效期，以秒为单位（范围：1-86400）。会覆盖config.yaml中的openrouter.response_cache_ttl设置。 | | NOUS_BASE_URL | 覆盖Nous Portal的基URL（极少需要，仅用于开发/测试） | | NOUS_INFERENCE_BASE_URL | 直接覆盖Nous推理接口的地址 | | OPENAI_API_KEY | 用于自定义OpenAI兼容接口的API密钥（需与OPENAI_BASE_URL一起使用） | | OPENAI_BASE_URL | 自定义接口的基URL（适用于VLLM、SGLang等框架） | | LM_API_KEY | LM Studio（lmstudio提供者）的API密钥。通常用于本地服务器场景 | | LM_BASE_URL | LM Studio的基URL（默认值：http://localhost:1234/v1） | | 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 | | COPILOT_API_BASE_URL | 覆盖Copilot API的基URL（对应copilot提供者） | | 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的基URL（默认值：https://api.z.ai/api/paas/v4） | | KIMI_API_KEY | Kimi / Moonshot AI API密钥（平台地址：moonshot.ai） | | KIMI_CODING_API_KEY | kimi-coding提供者对应的别名密钥，可与KIMI_API_KEY同时使用 | | 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） | | GMI_API_KEY | GMI Cloud API密钥（平台地址：gmicloud.ai） | | GMI_BASE_URL | 覆盖GMI Cloud的基URL（默认值：https://api.gmi-serving.com/v1） | | MINIMAX_API_KEY | MiniMax API密钥——全球通用接口（平台地址：minimax.io）。minimax-oauth模式不会使用该密钥（该模式通过浏览器登录即可） | | MINIMAX_BASE_URL | 覆盖Minimax的基URL（默认值：https://api.minimax.io/anthropic——Hermes使用的是Minimax兼容Anthropic Messages格式的接口）。minimax-oauth模式也不会使用该值 | | MINIMAX_CN_API_KEY | MiniMax API密钥——中国区接口（平台地址：minimaxi.com）。minimax-oauth模式不会使用该密钥（该模式通过浏览器登录即可） | | MINIMAX_CN_BASE_URL | 覆盖Minimax中国区的基URL（默认值：https://api.minimaxi.com/anthropic）。minimax-oauth模式不会使用该值 | | 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） | | TOKENHUB_API_KEY | 腾讯TokenHub API密钥（平台地址：tokenhub.tencentmaas.com） | | TOKENHUB_BASE_URL | 覆盖腾讯TokenHub的基URL（默认值：https://tokenhub.tencentmaas.com/v1） | | AZURE_FOUNDRY_API_KEY | Microsoft Foundry / Azure OpenAI API密钥（平台地址：ai.azure.com）。当model.auth_mode: entra_id时无需此密钥 | | AZURE_FOUNDRY_BASE_URL | Microsoft Foundry接口地址（例如，OpenAI风格接口为https://<resource>.openai.azure.com/openai/v1，Anthropic风格接口为https://<resource>.services.ai.azure.com/anthropic） | | AZURE_ANTHROPIC_KEY | 用于provider: anthropic场景的Azure Anthropic API密钥，且其对应的base_url需指向Microsoft Foundry部署的Claude服务——当同时配置了Anthropic和Azure Anthropic时，该密钥可作为ANTHROPIC_API_KEY的替代方案 | | AZURE_TENANT_ID | Entra ID租户ID（用于服务主体流程；当model.auth_mode: entra_id时，azure-identity会自动识别该值） | | AZURE_CLIENT_ID | Entra ID客户端ID（可为服务主体、工作负载身份或用户分配的托管身份） | | AZURE_CLIENT_SECRET | EnvironmentCredential所使用的服务主体密钥 | | AZURE_CLIENT_CERTIFICATE_PATH | 服务主体证书文件路径（可作为AZURE_CLIENT_SECRET的替代方案） | | AZURE_FEDERATED_TOKEN_FILE | AKS工作负载身份/OIDC流程所使用的联合令牌文件路径 | | AZURE_AUTHORITY_HOST | 主权云授权服务器地址的覆盖值（例如，Azure政府版为https://login.microsoftonline.us）。详情请参阅Azure Foundry指南 | | IDENTITY_ENDPOINT / MSI_ENDPOINT | App Service、Functions及Container Apps所使用的托管身份接口地址；虚拟机通常使用IMDS机制，无需设置这些参数 | | 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 | | ANTHROPIC_API_KEY | Anthropic控制台API密钥（平台地址：console.anthropic.com） | | ANTHROPIC_BASE_URL | 覆盖Anthropic API的基URL | | ANTHROPIC_TOKEN | 手动设置的或旧版的Anthropic OAuth/设置令牌覆盖值 | | DASHSCOPE_API_KEY | 阿里云Qwen模型对应的Qwen Cloud（Alibaba 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） | | ALIBABA_CODING_PLAN_API_KEY | Qwen编程计划API密钥（对应alibaba-coding-plan提供者） | | ALIBABA_CODING_PLAN_BASE_URL | 覆盖Qwen编程计划的基URL | | DEEPSEEK_API_KEY | 直接访问DeepSeek模型所需的API密钥（平台地址：platform.deepseek.com/api_keys） | | DEEPSEEK_BASE_URL | 自定义的DeepSeek API基URL | | NOVITA_API_KEY | NovitaAI API密钥——专为模型API、Agent Sandbox及GPU云服务设计的原生AI云平台（密钥管理地址：novita.ai/settings/key-management） | | NOVITA_BASE_URL | 覆盖NovitaAI的基URL（默认值：https://api.novita.ai/openai/v1） | | 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） | | STEPFUN_API_KEY | StepFun API密钥——用于Step系列模型的接口（平台地址：platform.stepfun.com） | | STEPFUN_BASE_URL | 覆盖StepFun的基URL（默认值：https://api.stepfun.com/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）API密钥，支持聊天、文本转语音及网络搜索功能（控制台地址：console.x.ai） | | XAI_BASE_URL | 覆盖xAI的基URL（默认值：https://api.x.ai/v1） | | MISTRAL_API_KEY | Mistral API密钥，用于Voxtral文本转语音及语音转文本功能（控制台地址：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 API密钥 | | 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服务名称，便于多实例同时运行 | | HERMES_GIT_BASH_PATH | 仅适用于Windows系统。用于指定终端工具所使用的bash.exe路径。可指向任何版本的bash——包括完整版的Git-for-Windows、通过符号链接连接的WSL bash、MSYS2或Cygwin。安装程序会自动将此路径设置为它所配置的PortableGit版本。详情请参阅Windows（原生）指南 | | HERMES_DISABLE_WINDOWS_UTF8 | 仅适用于Windows系统。将其设置为1可禁用UTF-8标准输入输出模拟层（configure_windows_stdio()函数），转而使用控制台的本地代码页。该设置有助于排查编码相关问题；在正常运行时很少需要使用 | | HERMES_KANBAN_HOME | 覆盖用于存储看板数据（数据库、工作空间及 worker日志）的共享Hermes根目录。如未指定该值，则会回退到get_default_hermes_root()函数确定的路径（即所有活跃配置文件的父目录）。该设置适用于测试或特殊部署场景 | | HERMES_KANBAN_BOARD | 固定当前进程所使用的看板名称。该设置优先级高于~/.hermes/kanban/current；调度器会将此值注入worker子进程的环境变量中，从而确保worker无法查看其他看板上的任务。默认值为default。有效值格式：小写字母、数字、连字符及下划线组合，长度为1-64个字符 | | HERMES_KANBAN_DB | 直接指定看板数据库文件的路径——优先级最高，可覆盖HERMES_KANBAN_BOARD和HERMES_KANBAN_HOME的设置。调度器会将此值注入worker子进程的环境变量中，确保所有profile worker都使用同一数据库 | | HERMES_KANBAN_WORKSPACES_ROOT | 直接指定看板工作空间的根目录——针对工作空间而言优先级最高，可覆盖HERMES_KANBAN_HOME的设置。调度器会将此值注入worker子进程的环境变量中 | | HERMES_KANBAN_DISPATCH_IN_GATEWAY | 对kanban.dispatch_in_gateway参数的运行时覆盖值。将其设置为0、false、no或off可阻止网关启动内置的Kanban调度器；任何非空字符串值都会启用该调度器。当有独立的调度器进程负责管理看板时，可使用此设置 |## 提供商认证（OAuth）

对于原生 Anthropic 认证方式，若存在 Claude Code 自带的凭据文件，Hermes 会优先使用这些文件，因为其凭据可以自动刷新。通过 OAuth 连接 Anthropic 需要购买额外使用额度的 Claude Max 套餐——Hermes 会以 Claude Code 的身份发起请求，仅能消耗 Max 套餐的额外/超额额度，无法使用基础 Max 配额，且不支持 Claude Pro。若没有 Max 套餐及额外额度，则应使用 API 密钥。虽然 ANTHROPIC_TOKEN 等环境变量仍可用于手动覆盖设置，但已不再是 Claude Max 登录的首选方式。

工具 API

Langfuse 可观测性功能

用于内置插件 observability/langfuse 的环境变量。需在 ~/.hermes/.env 文件中设置这些变量。在它们生效之前，还需先启用该插件（执行 hermes plugins enable observability/langfuse，或通过 hermes plugins 界面勾选对应选项）。

Nous 工具网关

这些变量用于配置付费 Nous 用户或自托管网关部署所使用的工具网关。大多数用户无需设置这些参数——网关会通过 hermes model 或 hermes tools 自动配置。

终端后端

对于云沙箱后端，数据持久化依赖于文件系统。TERMINAL_LIFETIME_SECONDS 参数用于控制 Hermes 在何时清理空闲的终端会话，后续重新启动时可能会创建新的沙箱环境，而非继续运行原有的进程。

SSH 后端

容器资源（Docker、Singularity、Modal、Daytona）

持久化 Shell

消息传递功能| 变量名 | 描述 |

|––––|——| | TELEGRAM_BOT_TOKEN | Telegram机器人令牌（从@BotFather获取） | | TELEGRAM_ALLOWED_USERS | 允许使用该机器人的用户ID，以逗号分隔（适用于私信、群组及论坛） | | TELEGRAM_GROUP_ALLOWED_USERS | 仅在群组/论坛中授权的发送者用户ID，以逗号分隔（不授予私信访问权限）。为兼容旧版配置（#17686之前），以“-”开头的聊天ID值仍会被视为有效聊天ID，但会发出弃用警告 | | TELEGRAM_GROUP_ALLOWED_CHATS | 允许发送消息的群组/论坛聊天ID，以逗号分隔；该群组的任何成员均有权发送消息 | | TELEGRAM_HOME_CHANNEL | 用于定时任务消息推送的默认Telegram聊天频道/频道名称 | | TELEGRAM_HOME_CHANNEL_NAME | Telegram首页频道的显示名称 | | TELEGRAM_CRON_THREAD_ID | 用于接收定时任务消息的论坛主题ID；仅针对定时任务，会覆盖TELEGRAM_HOME_CHANNEL_THREAD_ID设置。建议在主题模式下使用此参数，这样对定时消息的回复会打开新会话，而不会进入系统大厅（#24409） | | TELEGRAM_WEBHOOK_URL | Webhook模式的公共HTTPS地址（可替代轮询方式发送消息） | | TELEGRAM_WEBHOOK_PORT | Webhook服务器的本地监听端口（默认值为8443） | | TELEGRAM_WEBHOOK_SECRET | Telegram在每次消息更新时返回的密钥，用于验证消息真实性。一旦设置了TELEGRAM_WEBHOOK_URL，此参数为必填项——否则网关将无法启动（GHSA-3vpc-7q5r-276h）。可通过openssl rand -hex 32命令生成该密钥 | | TELEGRAM_REACTIONS | 在处理消息时启用表情符号反应功能（默认值为false） | | TELEGRAM_REQUIRE_MENTION | 在Telegram群组中回复消息前，要求必须明确@提及机器人。相当于config.yaml中的telegram.require_mention设置 | | TELEGRAM_MENTION_PATTERNS | 当启用Telegram群组@提及过滤功能时，允许的正则表达式触发词列表，格式可为JSON数组、换行分隔列表或逗号分隔列表。相当于telegram.mention_patterns设置 | | TELEGRAM_EXCLUSIVE_BOT_MENTIONS | 启用后，在Telegram群组中，明确的@...bot提及会先被路由到对应的机器人用户名，之后才会执行回复或触发词处理逻辑。默认值为true。相当于telegram.exclusive_bot_mentions设置 | | 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同时使用）。此设置会自动启用“成员”意图。当审核团队人员变动时非常有用，因为角色权限变更会自动生效 | | DISCORD_ALLOWED_CHANNELS | 允许机器人发送消息的Discord频道ID，以逗号分隔。一旦设置，机器人将仅在这些频道（以及允许的私信）中回复消息，会覆盖config.yaml中的discord.allowed_channels设置 | | DISCORD_PROXY | 用于连接Discord的代理URL，可覆盖HTTPS_PROXY设置。支持http://、https://、socks5://格式 | | DISCORD_HOME_CHANNEL | 用于定时任务消息推送的默认Discord频道 | | DISCORD_HOME_CHANNEL_NAME | Discord首页频道的显示名称 | | DISCORD_COMMAND_SYNC_POLICY | Discord斜杠命令启动同步策略：safe（差异对比后再同步）、bulk（使用旧版的tree.sync()方式）或off（关闭同步） | | DISCORD_REQUIRE_MENTION | 在服务器频道中回复消息前，要求必须进行@提及 | | DISCORD_FREE_RESPONSE_CHANNELS | 不要求必须@提及即可发送回复的频道ID，以逗号分隔 | | DISCORD_AUTO_THREAD | 当支持时，自动为长回复创建线程 | | DISCORD_ALLOW_ANY_ATTACHMENT | 设置为true时，允许接收所有类型的附件（不仅限于默认支持的PDF、文本、ZIP、Office文档格式）。未知类型的附件会被缓存，并以本地路径的形式呈现给机器人，以便其通过terminal、read_file、ffprobe等功能进行查看。默认值为false | | DISCORD_MAX_ATTACHMENT_BYTES | 网关缓存的单个附件的最大字节数。默认值为33554432（32兆字节）。设置为0则表示不设置上限（附件会在写入过程中保留在内存中） | | DISCORD_REACTIONS | 在处理消息时启用表情符号反应功能（默认值为true） | | DISCORD_IGNORED_CHANNELS | 机器人永远不会回复的Discord频道ID，以逗号分隔 | | DISCORD_NO_THREAD_CHANNELS | 机器人发送回复时不会自动创建线程的频道ID，以逗号分隔 | | DISCORD_REPLY_TO_MODE | 回复时的引用方式：off、first（默认）或all，与Discord规则一致 | | DISCORD_ALLOW_MENTION_EVERYONE | 允许机器人向@everyone/@here发送消息（默认值为false）。详情请参阅提及控制 | | DISCORD_ALLOW_MENTION_ROLES | 允许机器人接收@role格式的提及（默认值为false） | | DISCORD_ALLOW_MENTION_USERS | 允许机器人接收单个@user格式的提及（默认值为true） | | DISCORD_ALLOW_MENTION_REPLIED_USER | 回复用户消息时，也向该用户发送回复（默认值为true） | | SLACK_BOT_TOKEN | Slack机器人令牌（格式为xoxb-...） | | SLACK_APP_TOKEN | Slack应用级令牌（格式为xapp-...，在Socket模式下为必填项） | | SLACK_ALLOWED_USERS | 允许使用该机器人的Slack用户ID，以逗号分隔 | | SLACK_HOME_CHANNEL | 用于定时任务消息推送的默认Slack频道 | | SLACK_HOME_CHANNEL_NAME | Slack首页频道的显示名称 | | GOOGLE_CHAT_PROJECT_ID | 托管Pub/Sub主题的GCP项目编号（如需备用，可使用GOOGLE_CLOUD_PROJECT） | | GOOGLE_CHAT_SUBSCRIPTION_NAME | 完整的Pub/Sub订阅路径，格式为projects/{proj}/subscriptions/{sub}（旧版别名為GOOGLE_CHAT_SUBSCRIPTION） | | GOOGLE_CHAT_SERVICE_ACCOUNT_JSON | 服务账户JSON文件的路径，或直接在此处填写JSON内容（如需备用，可使用GOOGLE_APPLICATION_CREDENTIALS） | | GOOGLE_CHAT_ALLOWED_USERS | 允许与机器人聊天的用户邮箱地址，以逗号分隔 | | GOOGLE_CHAT_ALLOW_ALL_USERS | 允许所有Google Chat用户触发机器人功能（仅开发人员可用） | | GOOGLE_CHAT_HOME_CHANNEL | 用于定时任务消息推送的默认Google Chat空间编号（例如spaces/AAAA...） | | GOOGLE_CHAT_HOME_CHANNEL_NAME | Google Chat首页空间的显示名称 | | GOOGLE_CHAT_MAX_MESSAGES | Pub/Sub FlowControl机制允许的正在处理中的最大消息数（默认值为1） | | GOOGLE_CHAT_MAX_BYTES | Pub/Sub FlowControl机制允许的正在处理中的最大字节数（默认值为16777216，即16兆字节） | | GOOGLE_CHAT_BOOTSTRAP_SPACES | 启动时用于探测的额外空间编号，以便确定机器人自身的users/{id}信息 |### Web控制台与Hermes Desktop

用于Web控制台的认证，以及实现Hermes Desktop与远程后端连接。遵循“仅使用密钥”的原则，凭证应存储在~/.hermes/.env文件中；而OAuth的client_id则建议设置在config.yaml的dashboard.oauth字段下（若同时设置，环境变量优先生效）。

系统预置了三种控制台认证提供程序。对于远程Hermes Desktop连接或任何面向互联网的控制台，推荐的提供程序是OAuth（Nous Portal）——需设置HERMES_DASHBOARD_OAUTH_CLIENT_ID（可通过hermes dashboard register命令进行配置）。内置的用户名/密码提供程序（HERMES_DASHBOARD_BASIC_AUTH_*）适用于位于可信局域网或VPN后的后端，是最快的解决方案，但不适合直接暴露在公共互联网上。若要使用自建的身份验证服务，可使用自托管OIDC提供程序（HERMES_DASHBOARD_OIDC_*）。无论采用哪种方式，只要设置非回环绑定地址（如hermes dashboard --host 0.0.0.0），就会启用认证网关。详情请参阅Web控制台 → 认证。

Microsoft Graph（Teams会议）

用于即将推出的Teams会议摘要处理流程中Microsoft Graph REST客户端的仅应用专用凭证。有关Azure门户的操作指南及所需的精确API权限，请参阅注册Microsoft Graph应用。

Microsoft Graph Webhook监听器

用于接收Graph事件（如Teams会议、日历事件、聊天消息等）的入站变更通知。有关设置及安全强化措施，请参阅Microsoft Graph Webhook监听器。

Teams会议摘要发送

仅当启用了teams_pipeline插件时才会使用该功能。相关设置也可通过config.yaml文件中的platforms.teams.extra字段进行配置——若同时设置了环境变量，则环境变量优先生效。详情请参阅Microsoft Teams → 会议摘要发送。

LINE消息API

由内置的LINE平台插件（plugins/platforms/line/）所使用。有关完整设置流程，请参阅消息网关 → LINE。

ntfy（推送通知）

ntfy是一款轻量级的基于HTTP的推送通知服务。可通过ntfy移动应用订阅某个主题，向该主题发送消息即可与智能体进行交互。

在将不受信任的主题用于生产环境之前，请先仔细阅读ntfy消息指南，尤其是身份模型相关章节。

高级消息配置调优用于调控外出消息批量处理功能的各平台高级参数。大多数用户无需调整这些设置；系统默认已针对各平台的速率限制进行了优化，从而确保运行流畅。

智能体行为| 参数名 | 描述 |

|––––|——| | HERMES_MAX_ITERATIONS | 每次对话中调用工具的最大迭代次数（默认值：90） | | HERMES_INFERENCE_MODEL | 在进程层面指定模型名称（该设置会优先于会话中的 config.yaml 配置）。也可通过 -m/--model 参数进行设置。 | | HERMES_YOLO_MODE | 设定为 1 可绕过危险命令的审批提示。功能等同于 --yolo。 | | HERMES_ACCEPT_HOOKS | 在无终端提示的情况下，自动批准 config.yaml 中声明的所有未见过的全局 shell hook。功能等同于 --accept-hooks 或 hooks_auto_accept: true。 | | HERMES_IGNORE_USER_CONFIG | 跳过 ~/.hermes/config.yaml 文件，使用内置默认配置（但 .env 文件中的凭证仍会被加载）。功能等同于 --ignore-user-config。 | | HERMES_IGNORE_RULES | 跳过自动注入的 AGENTS.md、SOUL.md、.cursorrules 文件、内存内容以及预加载的技能。功能等同于 --ignore-rules。 | | HERMES_SAFE_MODE | 故障排查模式：禁用所有自定义配置——跳过插件发现和 MCP 服务器加载流程。该模式会由 --safe-mode 参数自动启用（同时也会设置上述两个参数）。 | | HERMES_MD_NAMES | 以逗号分隔的规则文件名列表，系统会自动注入这些文件（默认值：AGENTS.md,CLAUDE.md,.cursorrules,SOUL.md）。 | | 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） | | CODEX_HOME | 当启用 Codex 应用服务器运行时环境 时，用于指定 Codex CLI 读取配置及认证信息的目录路径（默认值：~/.codex）。Hermes 的迁移机制会将相关配置写入 <CODEX_HOME>/config.toml 文件中。 | | HERMES_KANBAN_TASK | 由看板调度器在启动工作进程时设置的任务 UUID。各个工作进程以及由此生成的 hermes-tools MCP 子进程都会继承该值，以便看板工具能够正确进行权限控制。请勿手动设置此参数。 | | HERMES_API_TIMEOUT | LLM API 调用的超时时间（单位：秒）（默认值：1800） | | HERMES_API_CALL_STALE_TIMEOUT | 非流式请求的超时时间（单位：秒）（默认值：90）。若未设置该参数，本地提供商的此功能将自动关闭；对于上下文规模极大的场景，该超时时间也可能会相应增加。同样可在 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_STREAM_RETRIES | 遇到短暂网络故障时，在流式连接过程中尝试重新连接的次数（默认值：3） | | HERMES_AGENT_TIMEOUT | 运行中的智能体处于非活跃状态时的超时时间（单位：秒）（默认值：1800，即 30 分钟）。每次调用工具或发送流式 token 后，该计时器都会重置。将其设置为 0 即可禁用此功能。 | | HERMES_AGENT_TIMEOUT_WARNING | 当智能体处于非活跃状态达到指定时间后，网关会发送警告信息（默认值：HERMES_AGENT_TIMEOUT 的 75%）。 | | HERMES_AGENT_NOTIFY_INTERVAL | 对于长时间运行的智能体轮次，网关在发送进度通知之间的间隔时间（单位：秒）。 | | HERMES_CHECKPOINT_TIMEOUT | 创建文件系统检查点的超时时间（单位：秒）（默认值：30） | | HERMES_EXEC_ASK | 在网关模式下是否启用执行操作前的审批提示（true/false） | | HERMES_ENABLE_PROJECT_PLUGINS | 是否允许智能体加载器及控制台网页服务器自动发现位于 ./.hermes/plugins/ 目录中的项目级插件。该参数接受所有表示“真”的值：1 / true / yes / on（不区分大小写）。其余所有值——包括 0、false、no、off 以及空字符串——均被视为禁用状态（默认值）。注意：从 GHSA-5qr3-c538-wm9j (#29156) 版本开始，即使启用了此参数，控制台网页服务器仍不会自动导入项目插件的 Python api 文件——项目插件虽然可以通过静态 JS/CSS 扩展界面功能，但其后台路由仅当被放置在 ~/.hermes/plugins/ 目录下时才会被加载。 | | HERMES_PLUGINS_DEBUG | 设定为 1/true 时，会在标准错误流中输出详细的插件发现过程日志——包括扫描的目录、解析的清单文件、跳过某些文件的理由，以及解析或 register() 操作失败时的完整堆栈跟踪信息。该功能主要面向插件开发者。 | | HERMES_BACKGROUND_NOTIFICATIONS | 网关模式下的后台进程通知方式：all（默认值）、result、error、off | | HERMES_EPHEMERAL_SYSTEM_PROMPT | 在调用 API 时注入的临时系统提示语——此类提示语不会被保存到会话中。 | | HERMES_PREFILL_MESSAGES_FILE | 包含临时预填提示语的 JSON 文件路径，这些提示语会在调用 API 时被注入。 | | HERMES_ALLOW_PRIVATE_URLS | true/false——决定是否允许工具访问本地主机或私有网络中的 URL。在网关模式下默认为关闭状态。 | | HERMES_REDACT_SECRETS | true/false——控制是否在工具输出、日志及聊天回复中隐藏敏感信息（默认值：true）。 | | HERMES_WRITE_SAFE_ROOT | 用于限制 write_file/patch 操作的目录前缀；位于该前缀之外的路径将需要额外审批。支持使用 os.pathsep 符号分隔多个目录（Unix 系统用 :，Windows 系统用 ;）。 | | HERMES_DISABLE_LAZY_INSTALLS | 官方 Docker 镜像中会自动设置此内部桥接参数，以防止在不可修改的 /opt/hermes 目录树下运行时安装依赖项。在用户配置文件 config.yaml 中，对应的参数为 security.allow_lazy_installs: false；请勿在 .env 文件中设置该参数。 | | HERMES_DISABLE_FILE_STATE_GUARD | 设定为 1 可关闭 patch/write_file 操作中的“自上次读取后文件已被修改”检测机制。 | | HERMES_CORE_TOOLS | 用于以逗号分隔的形式覆盖默认的核心工具列表（高级功能，通常无需使用）。 | | HERMES_BUNDLED_SKILLS | 用于以逗号分隔的形式覆盖启动时自动加载的预装技能列表。 | | HERMES_OPTIONAL_SKILLS | 以逗号分隔的可选技能名称列表，系统会在首次运行时自动安装这些技能。 | | HERMES_DEBUG_INTERRUPT | 设定为 1 时，会将详细的中断/取消操作流程记录到 agent.log 文件中。 | | HERMES_DUMP_REQUESTS | 是否将 API 请求的完整内容输出到日志文件中（true/false）。 | | HERMES_dump_REQUEST_STDOUT | 将 API 请求的完整内容直接输出到标准输出流，而非日志文件。 | | HERMES_OAUTH_TRACE | 设定为 1 时，会记录 OAuth 令牌的交换及刷新操作过程，同时还会包含经过脱敏处理的操作时间信息。 | | HERMES_OAUTH_FILE | 用于指定存储 OAuth 凭证文件的路径（默认值：~/.hermes/auth.json）。 | | HERMES_AGENT_HELP_GUIDANCE | 为自定义部署场景的系统提示语添加额外的指导文本。 | | HERMES_AGENT_LOGO | 用于在 CLI 启动时替换默认的 ASCII 标识徽标。 | | DELEGATION_MAX_CONCURRENT_CHILDREN | 每批 delegate_task 请求允许的最大并行子智能体数量（默认值：3，下限为 1，无上限）。同样可在 config.yaml 中通过 delegation.max_concurrent_children 参数进行设置——配置文件中的值具有优先级。 |

界面相关参数

会话设置参数

上下文压缩功能（仅通过 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

:::info 旧配置迁移 包含 compression.summary_model、compression.summary_provider 以及 compression.summary_base_url 的旧版配置，在首次加载时会被自动迁移为 auxiliary.compression.* 格式。

::

辅助任务覆盖参数

对于特定任务所需的直接接口，Hermes 会使用该任务配置的 API 密钥或 OPENAI_API_KEY，而不会重复使用 OPENROUTER_API_KEY。

备用提供商（仅适用于 config.yaml）

主模型的备用链配置完全通过 config.yaml 完成——不存在相应的环境变量。只需在文件顶部添加一个包含 provider 和 model 键的 fallback_providers 列表，即可在主模型出现故障时实现自动切换。那些提供商设置为 auto 的辅助任务，在触发 Hermes 内置的辅助任务发现机制之前，也会先查询此备用链。

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4

为保持向后兼容性，系统仍会读取旧版的单提供者格式的 fallback_model 设置，但新配置应使用 fallback_providers。对于特定任务的辅助策略，请在 config.yaml 中使用 auxiliary.<task>.fallback_chain 选项；目前暂无对应的环境变量。

详情请参阅 Fallback Providers 文档。

提供者路由设置（仅适用于 config.yaml）

这些设置需放在 ~/.hermes/config.yaml 文件的 provider_routing 部分中：

:::tip 建议使用 hermes config set 命令来设置环境变量——该命令会自动将它们保存到相应的文件中（敏感信息存入 .env 文件，其他内容则存入 config.yaml）。

::