字
字节笔记本
2026年6月22日
hermes教程-环境变量
API中转
¥120
环境变量参考
所有变量均位于 ~/.hermes/.env 中。你也可以使用 hermes config set VAR value 进行设置。
LLM 提供商
| 变量 | 描述 |
|---|---|
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 | 缓存 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 / 智谱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_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 使用（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 使用（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 端点 URL（例如 OpenAI 风格：https://<resource>.openai.azure.com/openai/v1，或 Anthropic 风格：https://<resource>.services.ai.azure.com/anthropic） |
AZURE_ANTHROPIC_KEY | 用于 provider: anthropic + base_url 指向 Microsoft Foundry Claude 部署的 Azure Anthropic API 密钥（当同时配置了 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 Government 使用 https://login.microsoftonline.us）。参见 Azure Foundry 指南 |
IDENTITY_ENDPOINT / MSI_ENDPOINT | 用于应用服务、函数和容器应用的托管标识端点；VM 通常使用 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 |
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 Console API 密钥（console.anthropic.com） |
ANTHROPIC_BASE_URL | 覆盖 Anthropic API 基础 URL |
ANTHROPIC_TOKEN | 手动或旧版 Anthropic OAuth/设置令牌覆盖 |
DASHSCOPE_API_KEY | 通义千问（阿里云 DashScope）API 密钥，用于 Qwen 模型（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 | 通义千问 Coding Plan API 密钥（alibaba-coding-plan 提供商） |
ALIBABA_CODING_PLAN_BASE_URL | 覆盖通义千问 Coding Plan 基础 URL |
DEEPSEEK_API_KEY | DeepSeek API 密钥，用于直接访问 DeepSeek（platform.deepseek.com） |
DEEPSEEK_BASE_URL | 自定义 DeepSeek API 基础 URL |
NOVITA_API_KEY | NovitaAI API 密钥——AI 原生云，提供模型 API、Agent 沙箱和 GPU 云（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 密钥——托管 Ollama 目录，无需本地 GPU（ollama.com/settings/keys） |
OLLAMA_BASE_URL | 覆盖 Ollama Cloud 基础 URL（默认：https://ollama.com/v1） |
XAI_API_KEY | xAI (Grok) API 密钥，用于聊天 + TTS + 网络搜索（console.x.ai） |
XAI_BASE_URL | 覆盖 xAI 基础 URL（默认：https://api.x.ai/v1） |
MISTRAL_API_KEY | Mistral API 密钥，用于 Voxtral TTS 和 Voxtral STT（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 | 通义千问 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 服务名称，因此多个安装可以并发运行 |
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 stdio 垫片（configure_windows_stdio()）并回退到控制台的区域设置代码页。用于定位编码错误；正常操作中很少需要设置。 |
HERMES_KANBAN_HOME | 覆盖锚定看板（数据库 + 工作区 + 工作日志）的共享 Hermes 根目录。回退到 get_default_hermes_root()（任何活动配置文件的父目录）。用于测试和特殊部署。 |
HERMES_KANBAN_BOARD | 为此进程固定活动看板。优先级高于 ~/.hermes/kanban/current；调度器将其注入工作子进程环境，因此工作进程物理上无法看到其他看板上的任务。默认为 default。Slug 验证：小写字母数字 + 连字符 + 下划线，1-64 个字符。 |
HERMES_KANBAN_DB | 直接固定看板数据库文件路径（最高优先级；覆盖 HERMES_KANBAN_BOARD 和 HERMES_KANBAN_HOME）。调度器将其注入工作子进程环境，因此配置文件工作进程会收敛到调度器的看板。 |
HERMES_KANBAN_WORKSPACES_ROOT | 直接固定看板工作区根目录（工作区的最高优先级；覆盖 HERMES_KANBAN_HOME）。调度器将其注入工作子进程环境。 |
HERMES_KANBAN_DISPATCH_IN_GATEWAY | kanban.dispatch_in_gateway 的运行时覆盖。设置为 0、false、no 或 off 以防止网关启动嵌入式看板调度器；任何其他非空值则启用。当单独的调度器进程拥有看板时有用。 |
提供商认证（OAuth）
对于原生 Anthropic 认证，Hermes 优先使用 Claude Code 自身的凭证文件（如果存在），因为这些凭证可以自动刷新。针对 Anthropic 的 OAuth 需要 Claude Max 计划并购买额外使用额度——Hermes 以 Claude Code 身份路由，仅从 Max 计划的额外/超额额度中扣除，而非基础 Max 配额，且不适用于 Claude Pro。如果没有 Max + 额外额度，请改用 API 密钥。诸如 ANTHROPIC_TOKEN 之类的环境变量仍可作为手动覆盖使用，但不再是 Claude Max 登录的首选路径。
| 变量 | 描述 |
|---|---|
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） |
SEARXNG_URL | SearXNG 实例 URL，用于免费自托管网络搜索——无需 API 密钥（searxng.github.io） |
TAVILY_BASE_URL | 覆盖 Tavily API 端点。用于企业代理和自托管 Tavily 兼容搜索后端。模式与 GROQ_BASE_URL 相同。 |
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 浏览器会话 TTL（秒，默认：300） |
BROWSER_CDP_URL | 本地浏览器的 Chrome DevTools 协议 URL（通过 /browser connect 设置，例如 ws://localhost:9222） |
CAMOFOX_URL | Camofox 本地反检测浏览器 URL（默认：http://localhost:9377） |
CAMOFOX_USER_ID | 可选的外部管理 Camofox 用户 ID，用于共享可见会话 |
CAMOFOX_SESSION_KEY | 可选的 Camofox 会话密钥，用于为 CAMOFOX_USER_ID 创建标签页时使用 |
CAMOFOX_ADOPT_EXISTING_TAB | 设置为 true 以在创建新标签页前重用现有 Camofox 标签页 |
BROWSER_INACTIVITY_TIMEOUT | 浏览器会话不活动超时（秒） |
AGENT_BROWSER_ARGS | 额外的 Chromium 启动标志（逗号或换行分隔）。当以 root 身份运行或在 AppArmor 限制的非特权用户命名空间（Ubuntu 23.10+、DGX Spark、许多容器镜像）中运行时，Hermes 会自动注入 --no-sandbox,--disable-dev-shm-usage；仅当需要覆盖或添加其他标志时手动设置。 |
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 | 用于 Skills Hub 的 GitHub 令牌（更高的 API 速率限制、技能发布） |
HONCHO_API_KEY | 跨会话用户建模（honcho.dev） |
HONCHO_BASE_URL | 自托管 Honcho 实例的基础 URL（默认：Honcho 云）。本地实例无需 API 密钥。 |
HINDSIGHT_TIMEOUT | Hindsight 记忆提供者 API 调用的超时时间（秒，默认：60）。如果您的 Hindsight 实例在 /sync 或 on_session_switch 期间响应缓慢，并且在 errors.log 中看到超时，请增加此值。 |
SUPERMEMORY_API_KEY | 语义长期记忆，支持配置文件召回和会话摄取（supermemory.ai） |
DAYTONA_API_KEY | Daytona 云沙箱（daytona.io） |
Langfuse 可观测性
用于捆绑的 observability/langfuse 插件的环境变量。在 ~/.hermes/.env 中设置。插件也必须启用（hermes plugins enable observability/langfuse，或在 hermes plugins 中勾选），这些变量才会生效。
| 变量 | 描述 |
|---|---|
HERMES_LANGFUSE_PUBLIC_KEY | Langfuse 项目公钥（pk-lf-...）。必需。 |
HERMES_LANGFUSE_SECRET_KEY | Langfuse 项目密钥（sk-lf-...）。必需。 |
HERMES_LANGFUSE_BASE_URL | Langfuse 服务器 URL（默认：https://cloud.langfuse.com）。自托管时设置。 |
HERMES_LANGFUSE_ENV | 追踪的环境标签（production、staging 等） |
HERMES_LANGFUSE_RELEASE | 追踪的发布/版本标签 |
HERMES_LANGFUSE_SAMPLE_RATE | SDK 采样率 0.0–1.0（默认：1.0） |
HERMES_LANGFUSE_MAX_CHARS | 序列化负载的每字段截断长度（默认：12000） |
HERMES_LANGFUSE_DEBUG | true 启用详细插件日志记录到 agent.log |
LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_BASE_URL | 标准 Langfuse SDK 名称。当 HERMES_LANGFUSE_* 等效变量未设置时作为回退接受。 |
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 |
HERMES_DOCKER_BINARY | 覆盖 Hermes 调用的容器二进制文件（例如 podman、/usr/local/bin/docker）。未设置时，Hermes 自动发现 PATH 上的 docker 或 podman。当两者都安装且您想要非默认项，或二进制文件位于 PATH 之外时需要。 |
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 | 高级选择加入：将启动 cwd 挂载到 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 | 已弃用的网关/cron 终端会话直接覆盖。优先使用 config.yaml 中的 terminal.cwd；CLI 仍使用启动目录。 |
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_GROUP_ALLOWED_USERS | 仅在群组/论坛中授权的发送者用户 ID 列表（逗号分隔，不授予私聊访问权限）。以 - 开头的聊天 ID 格式值仍作为聊天 ID 被接受，以向后兼容 #17686 之前的配置，并附带弃用警告。 |
TELEGRAM_GROUP_ALLOWED_CHATS | 允许的群组/论坛聊天 ID 列表（逗号分隔）；任何成员均被授权 |
TELEGRAM_HOME_CHANNEL | 用于 cron 投递的默认 Telegram 聊天/频道 |
TELEGRAM_HOME_CHANNEL_NAME | Telegram 主频道的显示名称 |
TELEGRAM_CRON_THREAD_ID | 接收 cron 投递的论坛主题 ID；仅针对 cron 覆盖 TELEGRAM_HOME_CHANNEL_THREAD_ID。在主题模式下使用，以便对 cron 消息的回复打开新会话，而不是进入系统大厅（#24409）。 |
TELEGRAM_WEBHOOK_URL | Webhook 模式的公共 HTTPS URL（启用 webhook 而非轮询） |
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 | JSON 数组、换行分隔列表或逗号分隔列表，包含启用 Telegram 群组提及门控时接受的唤醒词正则表达式模式。等同于 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 为或关系）。自动启用 Members intent。当管理团队变动时很有用——角色授权会自动传播。 |
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_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 MiB）。设置为 0 表示无上限（附件在写入时保存在内存中）。 |
DISCORD_REACTIONS | 在处理过程中启用消息上的表情反应（默认：true） |
DISCORD_IGNORED_CHANNELS | 机器人永不响应的频道 ID 列表（逗号分隔） |
DISCORD_NO_THREAD_CHANNELS | 机器人响应时不自动创建线程的频道 ID 列表（逗号分隔） |
DISCORD_REPLY_TO_MODE | 回复引用行为：off、first（默认）或 all |
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 | 用于 cron 投递的默认 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 | 用于 cron 投递的默认空间（例如 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 MiB） |
GOOGLE_CHAT_BOOTSTRAP_SPACES | 启动时探测的额外空间 ID 列表（逗号分隔），用于解析机器人自身的 users/{id} |
GOOGLE_CHAT_DEBUG_RAW | 设置为任意值以在 DEBUG 级别记录经过编辑的 Pub/Sub 信封（仅调试用） |
WHATSAPP_ENABLED | 启用 WhatsApp 桥接（true/false） |
WHATSAPP_MODE | bot（独立号码）或 self-chat（给自己发消息） |
WHATSAPP_ALLOWED_USERS | 允许的电话号码列表（逗号分隔，含国家代码，无 +），或 * 允许所有发送者 |
WHATSAPP_ALLOW_ALL_USERS | 允许所有 WhatsApp 发送者，无需白名单（true/false） |
WHATSAPP_DEBUG | 在桥接中记录原始消息事件以进行故障排除（true/false） |
WHATSAPP_CLOUD_PHONE_NUMBER_ID | 来自 WhatsApp Business Cloud API 的 Meta 电话号码 ID（15-17 位数字；不是电话号码本身） |
WHATSAPP_CLOUD_ACCESS_TOKEN | Meta 访问令牌（以 EAA 开头）；临时令牌 24 小时后过期，系统用户令牌永久有效 |
WHATSAPP_CLOUD_APP_SECRET | 用于验证入站 webhook 签名的 32 字符十六进制应用密钥 |
WHATSAPP_CLOUD_VERIFY_TOKEN | 用于 Meta webhook 验证握手的共享密钥（由设置向导自动生成） |
WHATSAPP_CLOUD_ALLOWED_USERS | 允许向机器人发送消息的 wa_id 列表（逗号分隔，含国家代码的电话号码，无 +） |
WHATSAPP_CLOUD_ALLOW_ALL_USERS | 允许所有 WhatsApp Cloud 发送者，无需白名单（true/false） |
WHATSAPP_CLOUD_APP_ID | 可选的 Meta 应用 ID（用于未来分析集成） |
WHATSAPP_CLOUD_WABA_ID | 可选的 WhatsApp Business 账户 ID（用于未来分析集成） |
WHATSAPP_CLOUD_WEBHOOK_HOST | 入站 webhook 服务器绑定的接口（默认 0.0.0.0） |
WHATSAPP_CLOUD_WEBHOOK_PORT | 入站 webhook 服务器绑定的端口（默认 8090） |
WHATSAPP_CLOUD_WEBHOOK_PATH | Meta 发布入站消息的 URL 路径（默认 /whatsapp/webhook） |
WHATSAPP_CLOUD_API_VERSION | 调用的 Meta Graph API 版本（默认 v20.0） |
WHATSAPP_CLOUD_HOME_CHANNEL | 用作机器人主频道的 wa_id（用于 cron 作业等） |
WHATSAPP_CLOUD_DM_POLICY | Cloud 适配器的私聊门控（open/allowlist/disabled）；未设置时回退到 WHATSAPP_DM_POLICY |
WHATSAPP_CLOUD_ALLOW_FROM | 当 dm_policy: allowlist 时允许的发送者列表（逗号分隔，裸 wa_id；Baileys 风格的 JID 会被规范化） |
WHATSAPP_CLOUD_GROUP_POLICY | Cloud 适配器的群组门控（open/allowlist/disabled）；未设置时回退到 WHATSAPP_GROUP_POLICY |
WHATSAPP_CLOUD_GROUP_ALLOW_FROM | 当 group_policy: allowlist 时允许的群组聊天 ID 列表（逗号分隔） |
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_ALLOW_BOTS | none（默认）/ mentions / all——接受来自其他机器人的入站消息。参见机器人间消息 |
FEISHU_REQUIRE_MENTION | true（默认）/ false——群组消息是否需要 @提及机器人。可通过 group_rules.<chat_id>.require_mention 按聊天覆盖。 |
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 | 自建应用的 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（非成员用户 ID）列表（逗号分隔）。变量名是遗留的——它期望群组 ID。仅当 iLink 实际传递群组事件时生效；二维码登录的 iLink 机器人身份（[email protected]）通常不接收普通微信群消息。 |
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_PORTAL_HOST | 覆盖 QQ 门户主机（设置为 sandbox.q.qq.com 以通过沙箱网关路由；默认：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_ALLOWED_ROOMS | 允许触发机器人响应的 Matrix 房间 ID 列表（逗号分隔） |
MATRIX_HOME_ROOM | 用于主动消息投递的房间 ID（例如 !abc123:matrix.org） |
MATRIX_ENCRYPTION | 启用端到端加密（true/false，默认：false） |
MATRIX_E2EE_MODE | Matrix E2EE 行为：off、optional 或 required。设置时覆盖 MATRIX_ENCRYPTION。 |
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_IGNORE_USER_PATTERNS | 用于忽略 Matrix 桥接/应用服务幽灵用户 ID 的正则表达式列表（逗号分隔） |
MATRIX_PROCESS_NOTICES | 处理入站 Matrix m.notice 事件（默认：false） |
MATRIX_SESSION_SCOPE | 项目房间的 Matrix 会话范围：auto、room 或 thread（默认：auto） |
MATRIX_TOOLS_ALLOW_CROSS_ROOM | 允许 Matrix 工具定位当前房间以外的显式房间（默认：false） |
MATRIX_TOOLS_ALLOW_CROSS_ROOM_DESTRUCTIVE | 允许跨房间的 Matrix 编辑/邀请类工具；需要 MATRIX_TOOLS_ALLOW_CROSS_ROOM=true（默认：false） |
MATRIX_TOOLS_ALLOW_REDACTION | 允许执行 Matrix 消息编辑工具（默认：false） |
MATRIX_TOOLS_ALLOW_INVITES | 允许执行 Matrix 邀请工具（默认：false） |
MATRIX_TOOLS_ALLOW_ROOM_CREATE | 允许执行 Matrix 房间创建工具（默认：false） |
MATRIX_ALLOW_ROOM_MENTIONS | 允许出站 @room 提及以通知所有房间成员（默认：false） |
MATRIX_AUTO_THREAD | 为房间消息自动创建线程（默认：true） |
MATRIX_DM_MENTION_THREADS | 当机器人在私聊中被 @mentioned 时创建线程（默认：false） |
MATRIX_APPROVAL_REQUIRE_SENDER | 要求批准/模型选择器反应来自已知的原始请求者（默认：true） |
MATRIX_APPROVAL_TIMEOUT_SECONDS | Matrix 反应批准/模型选择器提示的超时时间（默认：300） |
MATRIX_ALLOW_PUBLIC_ROOMS | 允许 Matrix 房间创建工具创建公共房间（默认：false） |
MATRIX_MAX_MEDIA_BYTES | Matrix 媒体上传/下载的最大字节数（默认：104857600） |
MATRIX_RECOVERY_KEY | 设备密钥轮换后用于交叉签名验证的恢复密钥。建议用于启用了交叉签名的 E2EE 设置。 |
MATRIX_RECOVERY_KEY_OUTPUT_FILE | 可选的一次性路径，用于生成的 Matrix 恢复密钥。以 0600 模式创建，且从不覆盖。 |
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 服务器启用就必须设置。 |
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）。回环地址上仍需要 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 | 已弃用的网关工作目录兼容性回退。优先使用 config.yaml 中的 terminal.cwd。 |
GATEWAY_ALLOWED_USERS | 跨所有平台允许的用户 ID 列表（逗号分隔） |
GATEWAY_ALLOW_ALL_USERS | 允许所有用户，无需白名单（true/false，默认：false） |
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_*）是受信任 LAN 或 VPN 后端的快速选项，但不适合直接暴露于公共互联网。要使用您自己的身份提供商进行认证，请使用自托管 OIDC 提供商（HERMES_DASHBOARD_OIDC_*）。无论哪种方式，非回环绑定（hermes dashboard --host 0.0.0.0）都会启用认证门控。完整说明请参见 Web 仪表盘 → 认证。
| 变量 | 描述 |
|---|---|
HERMES_DASHBOARD_BASIC_AUTH_USERNAME | 捆绑的用户名/密码仪表盘认证提供商（plugins/dashboard_auth/basic）的用户名。与密码一起设置时激活该提供商。覆盖 dashboard.basic_auth.username。 |
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD | 基本提供商的明文密码（加载时在内存中哈希）。优先于配置中的 password_hash，因此您可以通过环境变量轮换。覆盖 dashboard.basic_auth.password。 |
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH | 基本提供商的 scrypt 密码哈希（推荐——静态时不存储明文）。使用 python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('PW'))" 计算。覆盖 dashboard.basic_auth.password_hash。 |
HERMES_DASHBOARD_BASIC_AUTH_SECRET | 签署基本提供商无状态会话令牌的 HMAC 密钥（32+ 字节，base64/hex/raw）。显式设置以便会话在重启后持续存在/跨多个工作进程；留空则随机生成（每次重启都会注销）。覆盖 dashboard.basic_auth.secret。 |
HERMES_DASHBOARD_BASIC_AUTH_TTL_SECONDS | 基本提供商的访问令牌生命周期（默认 12 小时）。覆盖 dashboard.basic_auth.session_ttl_seconds。 |
HERMES_DASHBOARD_OAUTH_CLIENT_ID | 用于门控/公共仪表盘的 OAuth 客户端 ID（agent:{instance_id}），激活 Nous（plugins/dashboard_auth/nous）提供商。覆盖 dashboard.oauth.client_id。使用 hermes dashboard register 配置。 |
HERMES_DASHBOARD_PUBLIC_URL | 仪表盘可访问的完整公共 URL，用于反向代理后的 OAuth 回调构建。覆盖 dashboard.public_url。 |
HERMES_DASHBOARD_OIDC_ISSUER | 捆绑的自托管 OIDC 提供商（plugins/dashboard_auth/self_hosted）的 OIDC 颁发者 URL。激活它需要此项。覆盖 dashboard.oauth.self_hosted.issuer。 |
HERMES_DASHBOARD_OIDC_CLIENT_ID | 自托管 OIDC 提供商的公共 OIDC 客户端 ID（授权码 + PKCE）。激活它需要此项。覆盖 dashboard.oauth.self_hosted.client_id。 |
HERMES_DASHBOARD_OIDC_SCOPES | 自托管 OIDC 提供商请求的 OIDC 范围（默认 openid profile email）。覆盖 dashboard.oauth.self_hosted.scopes。 |
HERMES_DESKTOP_REMOTE_URL | （桌面端）远程后端的基础 URL，例如 http://host:9119。设置后，覆盖应用内网关 URL；您仍需从网关设置面板登录（OAuth 重定向或用户名/密码，取决于后端公布的方式）。 |
Microsoft Graph（Teams 会议）
用于即将推出的 Teams 会议摘要管道的 Microsoft Graph REST 客户端的仅应用凭证。请参阅注册 Microsoft Graph 应用程序了解 Azure 门户操作步骤和所需的确切 API 权限。
| 变量 | 描述 |
|---|---|
MSGRAPH_TENANT_ID | Graph 应用注册的 Azure AD 租户 ID（目录 GUID）。 |
MSGRAPH_CLIENT_ID | Azure 应用注册的应用程序（客户端）ID。 |
MSGRAPH_CLIENT_SECRET | 应用注册的客户端密钥值。存储在 ~/.hermes/.env 中，权限为 chmod 600；通过 Azure 门户定期轮换。 |
MSGRAPH_SCOPE | 客户端凭证令牌请求的 OAuth2 范围（默认：https://graph.microsoft.com/.default）。 |
MSGRAPH_AUTHORITY_URL | Microsoft 标识平台授权机构（默认：https://login.microsoftonline.com）。仅针对国家/主权云覆盖（例如 GCC High 使用 https://login.microsoftonline.us）。 |
Microsoft Graph Webhook 监听器
用于 Graph 事件（Teams 会议、日历、聊天等）的入站变更通知监听器。请参阅 Microsoft Graph Webhook 监听器了解设置和安全加固。
| 变量 | 描述 |
|---|---|
MSGRAPH_WEBHOOK_ENABLED | 启用 msgraph_webhook 网关平台（true/1/yes）。 |
MSGRAPH_WEBHOOK_PORT | 监听器绑定的端口（默认：8646）。 |
MSGRAPH_WEBHOOK_CLIENT_STATE | Graph 在每个通知中回显的共享密钥；与 hmac.compare_digest 比较。使用 openssl rand -hex 32 生成。 |
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES | 允许的 Graph 资源路径/模式白名单（逗号分隔，例如 communications/onlineMeetings,chats/*/messages）。尾部 * 表示前缀匹配。空 = 接受所有。 |
MSGRAPH_WEBHOOK_ALLOWED_SOURCE_CIDRS | 允许向监听器发送 POST 的 CIDR 范围列表（逗号分隔，例如 52.96.0.0/14,52.104.0.0/14）。空 = 允许所有（默认）。生产环境中应限制为 Microsoft Graph 公布的出口范围。 |
Teams 会议摘要投递
仅在启用 teams_pipeline 插件时使用。设置也可在 config.yaml 的 platforms.teams.extra 下配置——两者都设置时环境变量优先。请参阅 Microsoft Teams → 会议摘要投递。
| 变量 | 描述 |
|---|---|
TEAMS_DELIVERY_MODE | graph 或 incoming_webhook。 |
TEAMS_INCOMING_WEBHOOK_URL | Teams 生成的 webhook URL；当 TEAMS_DELIVERY_MODE=incoming_webhook 时必需。 |
TEAMS_GRAPH_ACCESS_TOKEN | 预获取的用于 Graph 投递的委托访问令牌。很少需要——写入器在未设置时会回退到 MSGRAPH_* 应用凭证。 |
TEAMS_TEAM_ID | 频道投递的目标团队 ID（graph 模式）。 |
TEAMS_CHANNEL_ID | 目标频道 ID（与 TEAMS_TEAM_ID 配对）。 |
TEAMS_CHAT_ID | 目标 1:1 或群聊 ID（graph 模式下团队+频道的替代方案）。 |
LINE Messaging API
由捆绑的 LINE 平台插件（plugins/platforms/line/）使用。完整设置请参阅消息网关 → LINE。
| 变量 | 描述 |
|---|---|
LINE_CHANNEL_ACCESS_TOKEN | 来自 LINE Developers Console（Messaging API 标签页）的长期频道访问令牌。必需。 |
LINE_CHANNEL_SECRET | 频道密钥（基本设置标签页）；用于 HMAC-SHA256 webhook 签名验证。必需。 |
LINE_HOST | Webhook 绑定主机（默认：0.0.0.0）。 |
LINE_PORT | Webhook 绑定端口（默认：8646）。 |
LINE_PUBLIC_URL | 公共 HTTPS 基础 URL（例如 https://my-tunnel.example.com）。发送图片/音频/视频时必需——LINE 只接受 HTTPS 可访问的 URL。 |
LINE_ALLOWED_USERS | 允许向机器人发送私聊的用户 ID 列表（逗号分隔，以 U 开头）。 |
LINE_ALLOWED_GROUPS | 机器人将响应的群组 ID 列表（逗号分隔，以 C 开头）。 |
LINE_ALLOWED_ROOMS | 机器人将响应的房间 ID 列表（逗号分隔，以 R 开头）。 |
LINE_ALLOW_ALL_USERS | 仅开发用的逃生口——接受任何来源。默认：false。 |
LINE_HOME_CHANNEL | 使用 deliver: line 的 cron 作业的默认投递目标。 |
LINE_SLOW_RESPONSE_THRESHOLD | 慢 LLM 模板按钮回发触发前的秒数（默认：45）。设置为 0 以禁用并始终使用 Push 回退。 |
LINE_PENDING_TEXT | 回发按钮旁显示的泡泡文本。 |
LINE_BUTTON_LABEL | 回发按钮标签（默认：Get answer）。 |
LINE_DELIVERED_TEXT | 当已投递的回发被再次点击时的回复（默认：Already replied ✅）。 |
LINE_INTERRUPTED_TEXT | 当 /stop 孤立的回发按钮被点击时的回复（默认：Run was interrupted before completion.）。 |
ntfy（推送通知）
ntfy 是一个轻量级基于 HTTP 的推送通知服务。从 ntfy 移动应用 订阅一个主题，向该主题发布消息即可与代理对话。
| 变量 | 描述 |
|---|---|
NTFY_TOPIC | 要订阅的主题（入站消息）。必需。 |
NTFY_SERVER_URL | 服务器 URL（默认：https://ntfy.sh）。指向自托管 ntfy 以保护隐私。 |
NTFY_TOKEN | 可选的认证令牌。Bearer 令牌（例如 tk_xyz）或用于 Basic 认证的 user:pass。 |
NTFY_PUBLISH_TOPIC | 出站回复的主题（默认为 NTFY_TOPIC）。 |
NTFY_MARKDOWN | 设置为 true 以发送带有 X-Markdown: true 头的回复。默认：false。 |
NTFY_ALLOWED_USERS | 白名单（视为用户 ID；在 ntfy 上这些是主题名称）。通常设置为与 NTFY_TOPIC 相同的值。 |
NTFY_ALLOW_ALL_USERS | 仅开发用的逃生口——仅在访问控制的私有主题上安全。默认：false。 |
NTFY_HOME_CHANNEL | 使用 deliver: ntfy 的 cron 作业的默认投递目标。 |
NTFY_HOME_CHANNEL_NAME | 主频道的人类可读标签（默认为主题名称）。 |
在部署到不受信任的主题之前，请参阅 ntfy 消息指南——特别是身份模型部分。
高级消息调优
用于限制出站消息批处理器的每个平台高级旋钮。大多数用户无需触碰这些；默认值已设置为尊重每个平台的速率限制，同时不显得迟钝。
| 变量 | 描述 |
|---|---|
HERMES_TELEGRAM_TEXT_BATCH_DELAY_SECONDS | 刷新排队中的 Telegram 文本块之前的宽限窗口（默认：0.6）。 |
HERMES_TELEGRAM_TEXT_BATCH_SPLIT_DELAY_SECONDS | 当单条 Telegram 消息超过长度限制时，分割块之间的延迟（默认：2.0）。 |
HERMES_TELEGRAM_MEDIA_BATCH_DELAY_SECONDS | 刷新排队中的 Telegram 媒体之前的宽限窗口（默认：0.6）。 |
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS | 代理完成后发送后续消息之前的延迟，以避免与最后一个流块竞争。 |
HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT / _READ_TIMEOUT / _WRITE_TIMEOUT / _POOL_TIMEOUT | 覆盖底层 python-telegram-bot HTTP 超时（秒）。 |
HERMES_TELEGRAM_HTTP_POOL_SIZE | 到 Telegram API 的最大并发 HTTP 连接数。 |
HERMES_TELEGRAM_DISABLE_FALLBACK_IPS | 禁用 DNS 失败时使用的硬编码 Cloudflare 回退 IP（true/false）。 |
HERMES_DISCORD_TEXT_BATCH_DELAY_SECONDS | 刷新排队中的 Discord 文本块之前的宽限窗口（默认：0.6）。 |
HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS | 当 Discord 消息超过长度限制时，分割块之间的延迟（默认：2.0）。 |
HERMES_MATRIX_TEXT_BATCH_DELAY_SECONDS / _SPLIT_DELAY_SECONDS | Matrix 版本的 Telegram 批处理旋钮。 |
HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS / _SPLIT_DELAY_SECONDS / _MAX_CHARS / _MAX_MESSAGES | 飞书批处理调优——延迟、分割延迟、每条消息最大字符数、每批最大消息数。 |
HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS | 飞书媒体刷新延迟。 |
HERMES_FEISHU_DEDUP_CACHE_SIZE | 飞书 webhook 去重缓存大小（默认：1024）。 |
HERMES_WECOM_TEXT_BATCH_DELAY_SECONDS / _SPLIT_DELAY_SECONDS | 企业微信批处理调优。 |
HERMES_VISION_DOWNLOAD_TIMEOUT | 在将图像交给视觉模型之前下载图像的超时时间（秒，默认：30）。 |
HERMES_RESTART_DRAIN_TIMEOUT | 网关：在 /restart 时等待正在运行的运行排空后强制重启的秒数（默认：900）。 |
HERMES_GATEWAY_PLATFORM_CONNECT_TIMEOUT | 网关启动期间每个平台的连接超时（秒）。 |
HERMES_GATEWAY_BUSY_INPUT_MODE | 默认网关忙碌输入行为：queue、steer 或 interrupt。可通过 /busy 按聊天覆盖。 |
HERMES_GATEWAY_BUSY_ACK_ENABLED | 当用户在代理忙碌时发送输入时，网关是否发送确认消息（⚡/⏳/⏩）（默认：true）。设置为 false 以完全抑制这些消息——输入仍会正常排队/引导/中断，只是聊天回复被静音。从 config.yaml 中的 display.busy_ack_enabled 桥接而来。 |
HERMES_GATEWAY_NO_SUPERVISE | 在 s6-overlay Docker 镜像内部，选择退出自动监督，使用 pre-s6 前台语义（无自动重启，网关是容器的主进程）。真值：1、true、yes。等同于 --no-supervise CLI 标志。在 s6 镜像外部无效。 |
HERMES_GATEWAY_BOOTSTRAP_STATE | 在 s6-overlay Docker 镜像内部，声明网关在全新卷上的初始监督状态。在空白卷上没有持久化的 gateway_state.json，因此启动协调器会注册 gateway-default 槽位但将其保持关闭（仅当最后记录的状态为 running 时才会自动启动）。将此设置为 running，首次启动设置钩子会在协调器运行之前种子化 gateway_state.json，从而使网关在首次启动时启动。仅接受字面值 running。仅首次启动：现有的 gateway_state.json 永远不会被覆盖，因此故意停止的网关会在重启后保持停止。在 s6 镜像外部无效。 |
HERMES_FILE_MUTATION_VERIFIER | 启用每轮文件变异验证器页脚（默认：true）。启用后，Hermes 会附加一个建议列表，列出在该轮中失败且未被成功写入覆盖的 write_file / patch 调用。设置为 0、false、no 或 off 以抑制。镜像 config.yaml 中的 display.file_mutation_verifier；设置时环境变量优先。 |
HERMES_CRON_TIMEOUT | cron 作业代理运行的不活动超时（秒，默认：600）。代理在积极调用工具或接收流令牌时可以无限运行——此超时仅在空闲时触发。设置为 0 表示无限制。 |
HERMES_CRON_SCRIPT_TIMEOUT | 附加到 cron 作业的预运行脚本的超时时间（秒，默认：120）。对于需要更长执行时间的脚本（例如用于反机器人计时的随机延迟）进行覆盖。也可通过 config.yaml 中的 cron.script_timeout_seconds 配置。 |
HERMES_CRON_MAX_PARALLEL | 每个 tick 并行运行的最大 cron 作业数（默认：4）。 |
代理行为
| 变量 | 描述 |
|---|---|
HERMES_MAX_ITERATIONS | 每次对话的最大工具调用迭代次数（默认：90） |
HERMES_INFERENCE_MODEL | 在进程级别覆盖模型名称（会话中优先于 config.yaml）。也可通过 -m/--model 标志设置。 |
HERMES_YOLO_MODE | 设置为 1 以绕过危险命令批准提示。等同于 --yolo。 |
HERMES_ACCEPT_HOOKS | 自动批准 config.yaml 中任何未见过的 shell 钩子，无需 TTY 提示。等同于 --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 | 非流式陈旧调用超时（秒，默认：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_STREAM_RETRIES | 在临时网络错误时进行流中重连尝试的次数（默认：3）。 |
HERMES_AGENT_TIMEOUT | 运行中代理的网关不活动超时（秒，默认：900）。每次工具调用和流令牌都会重置。设置为 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/ 自动发现仓库本地插件，适用于代理加载器和仪表盘 Web 服务器。接受标准真值集：1 / true / yes / on（不区分大小写）。其他所有值——包括 0、false、no、off 和空字符串——均视为禁用（默认）。注意：自 GHSA-5qr3-c538-wm9j (#29156) 起，即使启用了此变量，仪表盘 Web 服务器也拒绝自动导入项目插件的 Python api 文件——项目插件可以通过静态 JS/CSS 扩展 UI，但其后端路由仅在移动到 ~/.hermes/plugins/ 下时才会加载。 |
HERMES_PLUGINS_DEBUG | 1/true 以在 stderr 上显示详细的插件发现日志——扫描的目录、解析的清单、跳过原因以及解析或 register() 失败时的完整回溯。面向插件作者。 |
HERMES_BACKGROUND_NOTIFICATIONS | 网关中的后台进程通知模式：all（默认）、result、error、off |
HERMES_EPHEMERAL_SYSTEM_PROMPT | 在 API 调用时注入的临时系统提示（从不持久化到会话） |
HERMES_PREFILL_MESSAGES_FILE | 在 API 调用时注入的临时预填充消息的 JSON 文件路径。 |
HERMES_ALLOW_PRIVATE_URLS | true/false——允许工具获取 localhost/私有网络 URL。网关模式下默认关闭。 |
HERMES_REDACT_SECRETS | true/false——控制工具输出、日志和聊天响应中的密钥编辑（默认：true）。 |
HERMES_WRITE_SAFE_ROOT | 可选的目录前缀，限制 write_file/patch 写入；路径在外需要批准。 |
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 请求负载转储到 stdout 而不是日志文件。 |
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 配置——配置值优先。 |
界面
| 变量 | 描述 |
|---|---|
HERMES_TUI | 设置为 1 时启动 TUI 而非经典 CLI。等同于传递 --tui。 |
HERMES_TUI_DIR | 预构建的 ui-tui/ 目录路径（必须包含 dist/entry.js 和填充的 node_modules）。由发行版和 Nix 使用，以跳过首次启动的 npm install。 |
HERMES_TUI_RESUME | 启动时按 ID 恢复特定的 TUI 会话。设置后，hermes --tui 会跳过创建新会话，而是拾取指定的会话——适用于断开连接或终端崩溃后重新连接。 |
HERMES_TUI_THEME | 强制 TUI 颜色主题：light、dark 或原始 6 字符背景十六进制（例如 ffffff 或 1a1a2e）。未设置时，Hermes 使用 COLORFGBG 和终端背景查询自动检测；此变量覆盖那些不设置 COLORFGBG 的终端（Ghostty、Warp、iTerm2 等）上的检测。 |
HERMES_INFERENCE_MODEL | 为 hermes -z / hermes chat 强制模型，而不修改 config.yaml。与 --provider 标志配对。对于需要每次运行覆盖默认模型的脚本调用者（扫描器、CI、批处理运行器）很有用。 |
会话设置
| 变量 | 描述 |
|---|---|
SESSION_IDLE_MINUTES | 不活动 N 分钟后重置会话（默认：1440） |
SESSION_RESET_HOUR | 每日重置小时（24 小时制，默认：4 = 凌晨 4 点） |
HERMES_SESSION_ID | 自动导出到 Hermes 生成的每个工具子进程（terminal、execute_code、持久 shell、Docker/Singularity 后端、委托子代理运行）。由代理设置为当前会话 ID；从工具调用的用户脚本可以读取它以将其输出、遥测或副作用与原始 Hermes 会话关联。您不应手动设置此变量——从父 shell 覆盖它仅在代理运行之外生效，并且一旦代理启动会话就会被覆盖。 |
上下文压缩（仅 config.yaml）
上下文压缩完全通过 config.yaml 配置——没有对应的环境变量。阈值设置位于 compression: 块中，而摘要模型/提供商位于 auxiliary.compression: 下。
yaml
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 配置——没有对应的环境变量。添加一个顶级 fallback_providers 列表，包含 provider 和 model 键，以在主模型遇到错误时启用自动故障转移。提供商为 auto 的辅助任务在 Hermes 内置辅助发现链之前也会查询此链。
yaml
fallback_providers:
- provider: openrouter
model: anthropic/claude-sonnet-4旧版顶级 fallback_model 单提供商形式仍会读取以向后兼容，但新配置应使用 fallback_providers。对于任务特定的辅助策略，请使用 config.yaml 中的 auxiliary.<task>.fallback_chain；没有对应的环境变量。
完整详情请参阅回退提供商。
提供商路由（仅 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）。
分享: