Hermes Agent 中文站 Logo

Hermes Agent 中文站

导航

reference

⚙️ 05-环境变量参考LCP

⚙️ 05-环境变量参考 是 Hermes Agent 中文站「reference、environment-variables」路径下的中文说明页，帮助你理解适用场景、关键步骤、常见坑和下一步入口，并和快速上手、现成方案、Packs、问题排查及参考手册形成完整学习链路。

最后更新：2026-04-28查看 GitHub 原文

这页查的是 Hermes 的环境变量、API Key、token 与 base URL。 如果你要排查 key 为什么不通过，请看 05-遇到问题 / 03-模型 Provider 与自定义 endpoint 问题。

🎯 1. 页面用途

这一页用来查 Hermes 的环境变量参考，而不是排障。

它适合用来查：

  • API Key 应该放哪里
  • provider 的变量名怎么写
  • BASE_URL、token、OAuth 相关变量怎么理解
  • 哪些配置应该放 .env，哪些更适合放 config.yaml
  • 中国环境下自定义兼容层要特别注意什么

这页不负责：

  • API Key 无效排障
  • endpoint 404 / timeout 排障
  • tools / system role 不兼容排障
  • provider 选型推荐

🔹 2. 官方来源

中文站这一页会保留官方变量名，但把它们按用途重新分组，减少“表太长看不下去”的阅读压力。

🧭 3. 什么时候查这页

你在下面这些场景里，应该优先查这页：

  • 你要接一个新的 provider，但不知道变量名
  • 你要确认 API Key 放 .env 还是放 config.yaml
  • 你要接 OpenAI-compatible endpoint，想确认 BASE_URL 怎么覆盖
  • 你要查中国模型 / 国内中转常见变量名
  • 你要分清“配置值”和“敏感 secrets”分别放哪

如果你要解决的是：

  • 为什么 401 / 403
  • 为什么 model 不存在
  • 为什么 endpoint 超时

那是排障，不是这页。

🧠 4. 核心概念中文解释

4.1 先记住这一条：secrets 放 .env

官方核心规则非常明确：

~/.hermes/.env

也就是说：

  • API Key
  • token
  • provider secret
  • 一些敏感 base_url / auth 变量

优先放在：

~/.hermes/.env

4.2 hermes config set VAR value 也能写进去

官方同时支持：

hermes config set VAR value

它会根据变量类型，自动写进正确位置：

  • secrets 更适合写进 .env
  • 一般配置更适合写进 config.yaml

4.3 不是所有东西都该放环境变量

中文站这里要特别帮你拆开：

  • secrets / token / key：优先 .env
  • 一些功能配置：更适合 config.yaml

比如官方也明确提到，有些功能更应该在 config.yaml 里配：

  • context compression
  • fallback model
  • provider routing
  • 一些 display / advanced provider settings

4.4 环境变量页是“查名字”，不是“教你选模型”

这页真正回答的是：

  • 这个 provider 变量叫什么
  • 默认 base URL 是什么
  • 我该放哪

它不负责回答：

  • 这个 provider 值不值得用
  • 你应该选哪一个国内模型
  • 为什么现在接了却报错

⚡ 5. 常用项速查

5.1 最常记住的路径与设置方式

项目你先记住什么
secrets / tokens / API Key~/.hermes/.env
命令行设置变量hermes config set VAR value
普通配置主文件~/.hermes/config.yaml

5.2 常见 provider 变量分组

说明：下面是“先记最常见的一层”的中文速查，不是官方全量变量表的逐字复制。完整变量名和最新变更，以官方原文为准。

OpenRouter / OpenAI-compatible / 聚合入口

变量中文说明
OPENROUTER_API_KEYOpenRouter API Key
OPENROUTER_BASE_URLOpenRouter-compatible base URL 覆盖
OPENAI_API_KEY自定义 OpenAI-compatible endpoint 的 key
OPENAI_BASE_URL自定义 OpenAI-compatible endpoint 的 base URL
AI_GATEWAY_API_KEYVercel AI Gateway 的 key
AI_GATEWAY_BASE_URLAI Gateway base URL

Anthropic / Gemini / 常见国际主流 provider

变量中文说明
ANTHROPIC_API_KEYAnthropic API Key
ANTHROPIC_TOKEN手动 / legacy Anthropic token override
GOOGLE_API_KEYGoogle / Gemini API Key
GEMINI_API_KEYGOOGLE_API_KEY 的别名
GEMINI_BASE_URLGemini base URL override

国内与中国用户常见 provider

变量中文说明
GLM_API_KEYz.ai / GLM key
GLM_BASE_URLz.ai / GLM base URL
KIMI_API_KEYKimi / Moonshot key
KIMI_BASE_URLKimi / Moonshot base URL
MINIMAX_API_KEYMiniMax global key
MINIMAX_BASE_URLMiniMax global base URL
MINIMAX_CN_API_KEYMiniMax 中国区 key
MINIMAX_CN_BASE_URLMiniMax 中国区 base URL
DASHSCOPE_API_KEY阿里云 DashScope / Qwen key
DASHSCOPE_BASE_URLDashScope 兼容层地址
DEEPSEEK_API_KEYDeepSeek key
DEEPSEEK_BASE_URLDeepSeek base URL
XIAOMI_API_KEY小米模型 key
XIAOMI_BASE_URL小米模型 base URL
TENCENT_TOKENHUB_API_KEY腾讯 TokenHub key
TENCENT_TOKENHUB_BASE_URL腾讯 TokenHub base URL
STEPFUN_API_KEY阶跃星辰 StepFun key
NVIDIA_API_KEYNVIDIA NIM key
NVIDIA_BASE_URLNVIDIA NIM base URL
ARCEE_API_KEYArcee AI key
GMI_API_KEYGMI Cloud key
NOVITA_API_KEYNovita AI key

GitHub Copilot / OAuth / 特殊鉴权

变量中文说明
COPILOT_GITHUB_TOKENGitHub Copilot 首选 token
GH_TOKENGitHub token 的次优先入口
GITHUB_TOKEN另一个 GitHub token 入口
HERMES_COPILOT_ACP_COMMANDCopilot ACP 命令覆盖
HERMES_COPILOT_ACP_ARGSCopilot ACP 参数覆盖

5.3 最容易混淆的一组点

你看到的项实际含义不要误解成什么
.envsecrets 主存放处不是所有配置都该放这里
config.yaml功能 / 行为 / 高级配置不是 API Key 主存放处
*_BASE_URLprovider endpoint 覆盖不是 model 名称
API_KEY鉴权凭据不是 provider 开关
alias 变量同一 provider 的兼容别名不是新 provider

🗂️ 6. 完整参考结构

6.1 官方基础规则

官方最重要的两条是：

~/.hermes/.env

hermes config set VAR value

可以把它记成：

  • 手工管理 secrets：改 .env
  • 想通过命令设置：用 hermes config set

6.2 LLM provider 变量

官方原文覆盖很多 provider，这里按中文阅读习惯重组成 4 类：

A. 默认聚合 / OpenAI-compatible 类

适合你：

  • 想先接一个通用入口
  • 想挂兼容 OpenAI API 的自建或第三方接口

常见变量：

  • OPENROUTER_API_KEY
  • OPENROUTER_BASE_URL
  • OPENAI_API_KEY
  • OPENAI_BASE_URL
  • AI_GATEWAY_API_KEY
  • AI_GATEWAY_BASE_URL

B. 国际主流官方 provider 类

常见变量：

  • ANTHROPIC_API_KEY
  • ANTHROPIC_TOKEN
  • GOOGLE_API_KEY
  • GEMINI_API_KEY
  • GEMINI_BASE_URL
  • AWS_REGION
  • AWS_PROFILE

这类通常更偏“官方原生接入”。

C. 国内与中国用户常见 provider 类

常见变量：

  • GLM_API_KEY
  • GLM_BASE_URL
  • KIMI_API_KEY
  • KIMI_BASE_URL
  • MINIMAX_API_KEY
  • MINIMAX_BASE_URL
  • MINIMAX_CN_API_KEY
  • MINIMAX_CN_BASE_URL
  • DASHSCOPE_API_KEY
  • DASHSCOPE_BASE_URL
  • DEEPSEEK_API_KEY
  • DEEPSEEK_BASE_URL
  • XIAOMI_API_KEY
  • XIAOMI_BASE_URL
  • TENCENT_TOKENHUB_API_KEY
  • TENCENT_TOKENHUB_BASE_URL
  • STEPFUN_API_KEY
  • NVIDIA_API_KEY
  • NVIDIA_BASE_URL
  • ARCEE_API_KEY
  • GMI_API_KEY
  • NOVITA_API_KEY

中文站补充理解：

  • 变量名能配对，不代表模型名也一定配对
  • BASE_URL 写对，不代表 endpoint 路径一定完整
  • 国内兼容层常常还要单独核验 tools / system role / model id 兼容性

D. 特殊入口与工具链相关变量

例如：

  • GitHub Copilot 相关 token
  • Hugging Face router
  • NVIDIA / Ollama Cloud
  • Mistral 语音相关
  • Gemini CLI 的 PKCE / project id 配置

这类通常不是新手第一步必查，但当你进入更深层接入时会很重要。

E. TUI、Desktop 与 Windows 环境变量

变量中文说明
HERMES_TUI设为 1 强制启用 TUI 界面
HERMES_TUI_THEMETUI 主题：light 或 dark
HERMES_TUI_DIR预构建 TUI 界面文件路径
HERMES_TUI_RESUMETUI 自动恢复行为
HERMES_DESKTOP_CWDDesktop App 启动工作目录
HERMES_DESKTOP_HERMES_ROOTDesktop App Hermes 根目录
HERMES_HOME自定义 Hermes 主目录
HERMES_GIT_BASH_PATHWindows: 指定 Portable Git 的 bash 路径
HERMES_DISABLE_WINDOWS_UTF8Windows: 设为 1 禁用 UTF-8 控制台处理

6.3 安全提示

这一组不是排障，但必须提醒：

  • 不要把 .env 提交到 GitHub
  • 不要截图完整 API Key
  • 不要把真实 token 直接贴进 issue
  • 分享配置时，用 YOUR_API_KEY 或脱敏写法代替

6.4 中国环境补充

对于国内用户，最容易踩的不是“变量名不会写”，而是这四类细节：

  1. BASE_URL 和服务商文档不一致
  2. /v1 重复或缺失
  3. model id 不是服务商真实支持的名称
  4. 虽然能聊天，但 tools / system role 不稳定

这四类不属于这页的排障正文，但你在查变量时必须心里有数。

⚠️ 7. 注意事项

7.1 这页只负责“查变量名和放置位置”

它不负责帮你判断：

  • 哪家模型更值得用
  • 哪个中转更稳定
  • 为什么你现在 401 / 404 / timeout

7.2 Anthropic 的 auth 路径比过去更复杂

官方说明里提到：

  • 原生 Anthropic auth 现在更偏向使用 Claude Code 的 credential files
  • 环境变量仍可作为手动 override

所以不要把历史旧经验机械套用到当前版本上。

7.3 BASE_URL 写了，不代表所有层都匹配

特别是国内兼容层，最常见的问题不是“变量没设”，而是：

  • endpoint 其实不兼容
  • model 名称不兼容
  • 工具调用协议不兼容

7.4 这页不是“兼容层排障页”

如果你已经走到 401 / 403 / 404 / timeout / model not found，那就该去故障模块，不要继续在 Reference 页兜圈子。

🚦 8. 出问题了去哪

你现在卡在哪先去哪里
API Key 无效 / 401 / 40305-遇到问题 / 03-模型 Provider 与自定义 endpoint 问题
endpoint 不通 / 404 / timeout05-遇到问题 / 03-模型 Provider 与自定义 endpoint 问题
配置改了像没生效05-遇到问题 / 07-配置 Profiles 与环境隔离问题
不知道该选哪个中国模型03-国内落地 / 02-国内模型 / 01-总览
不确定问题在哪05-遇到问题 / 01-总览

🌐 9. 官方原文链接

如果你需要查全量变量名、默认 base URL、别名或某个 provider 的最新字段，以官方原文为准。

📚 10. 相关中文站页面

➡️ 下一步

完成后进入：

如果你想先回到上一阶段入口重新确认位置：

🔗 Reference 相关入口

上一篇

👤 04-Profile 命令参考

这页查的是 hermes profile ... 这一组命令，用来管理不同的 Hermes profile。 如果你要查一般 CLI 命令，请看 02-CLI 命令参考。

下一篇

🧰 06-Built-in Tools 参考

这页查的是 Hermes 内置工具（built-in tools），以及它们和 toolsets、平台、凭据之间的关系。…