HermesAgent如何正确配置环境变量文件

一、在 ~/.hermes/.env 中定义 API 密钥

这是最标准、最推荐的方式。Hermes Agent 启动时会默认去这个路径寻找环境变量文件。所以，你得确保文件不仅存在，而且里面的变量名写得“对得上号”。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

首先，检查一下这个目录是否存在。如果还没有，手动创建它：

mkdir -p ~/.hermes

接着，用你顺手的编辑器（比如 nano 或 vim）创建或打开那个关键的 .env 文件：

nano ~/.hermes/.env

然后，就是填入密钥的环节了。这里有个关键细节：变量名必须和模型提供商的要求严格匹配。通常，你只需要保留你正在使用的那个模型配置，其他的可以注释掉，避免干扰。格式大致如下：

# OpenAI
OPENAI_API_KEY=sk-xxxxx
# Anthropic
ANTHROPIC_API_KEY=sk-ant-xxxxx
# MiniMax（这个需要两组密钥）
MINIMAX_API_KEY=xxxxx
MINIMAX_GROUP_ID=xxxxx
# OpenRouter
OPENROUTER_API_KEY=sk-or-xxxxx

文件保存好后，顺手给它设置一下权限，保证只有当前用户能读取，这样更安全：

chmod 600 ~/.hermes/.env

完成这几步，再重启 Hermes Agent，问题通常就解决了。

二、通过 Docker 环境变量注入 .env 内容

如果你是用 Docker 跑的 Hermes Agent，那么完全可以绕过本地文件，直接在启动容器时把密钥“喂”进去。这种方式对于临时测试或者基于容器编排的场景特别有用。

具体操作就是在 docker run 命令里通过 -e 参数来设置环境变量。比如，你想用 OpenAI 的模型：

docker run -d \
  --name hermes-agent \
  -v ~/.hermes:/root/.hermes \
  -p 3000:3000 \
  -e HERMES_MODEL_PROVIDER=openai \
  -e OPENAI_API_KEY=sk-xxxxx \
  nousresearch/hermes-agent:latest

跑起来之后，怎么确认密钥真的生效了呢？可以执行下面这个命令，检查容器内部的环境变量：

docker exec hermes-agent env | grep -i api_key

这里有个需要警惕的细节：HERMES_MODEL_PROVIDER 这个变量的值，必须和你后面传入的 API 密钥变量前缀保持一致。比如说，如果你把 provider 设成了 deepseek，那么传入的密钥变量名就应该是 DEEPSEEK_API_KEY。对不上号，调用肯定会失败。

三、使用 docker-compose.yml + 外部 .env 文件联动

对于生产环境或者更复杂的部署，docker-compose 配合外部 .env 文件是更优雅的方案。它的好处很明显：把敏感的密钥从编排文件（docker-compose.yml）里剥离出来，既安全，又便于管理不同环境的配置。

具体怎么做呢？首先，在你的 docker-compose.yml 文件同级目录下，创建一个名为 .env 的文件，并把密钥写进去：

echo "OPENAI_API_KEY=sk-xxxxx" > .env

然后，确保 docker-compose.yml 中引用的是这个变量名，而不是直接把密钥明文写死：

environment:
  - OPENAI_API_KEY=${OPENAI_API_KEY}

在启动之前，建议先检查一下配置是否被正确解析，执行：

docker-compose config | grep -A2 "environment"

如果一切正常，你会看到解析后的完整环境变量。确认无误后，再启动服务：

docker-compose up -d

这样一来，密钥管理就清晰多了，要修改或轮换密钥时，只需要动那个外部的 .env 文件即可。

所以，下次遇到 Hermes Agent 模型调用失败，先别慌。绝大多数情况下，问题就出在环境变量配置这个环节。你可以按照上面这三种方式逐一核对：检查默认路径下的文件、确认 Docker 启动参数，或者梳理 docker-compose 的变量引用。通常，症结就在这里，解决了它，模型就能顺畅调用了。