Hermes API Key 透传指南：让工具容器也能用上你的密钥

问题的起源

Hermes 的终端工具默认运行在 Docker 容器里。这带来一个常见的困惑：宿主机配置的 API Key（比如 NOTION_API_KEY、WEREAD_API_KEY、DEEPSEEK_API_KEY）默认不会传到工具容器中。

你会发现 echo $NOTION_API_KEY 在容器里是空值，所有依赖这些环境变量的 API 调用都会报 401。

两步解决

第一步：确保宿主机 `.env` 里有 Key

Hermes 网关容器通过 env_file 加载宿主机 .env，这是 Key 的源头。

提示：.env 是 Hermes 的受保护文件，write_file 工具无权写入。用 shell 的 echo 追加即可。

第二步：配置 `docker_forward_env`

在 config.yaml 的 terminal 段落下，找到 docker_forward_env：

注意缩进：docker_forward_env 与 docker_image、backend 同级，列表项用 - 缩进两个空格。

如果这一项原来是空的 []，改成上面的列表即可。已经在列表里的 Key 无需重复添加。

最后：重启

重启后新会话就能拿到透传的 Key 了。验证方式：

原理

网关容器通过 env_file 加载 .env 但自己不使用；通过 docker_forward_env 白名单，在启动工具容器时将这些变量注入进去。

踩过的坑

write_file 被拒：.env 是受保护路径，只能用 shell echo 写入

改了 config 不重启：config.yaml 的变更必须重启网关才能生效

只加 .env 不加 forward：Key 到了网关容器但传不到工具容器，白忙活

docker_forward_env 缩进错误：YAML 对缩进敏感，确保和同级字段对齐

一次配置，到处使用

一旦配好，所有通过 Hermes 连接的外部服务——微信读书、Notion、DeepSeek 等——都能在同一个会话里无缝使用各自的 API Key，无需反复手动 export。

本文基于 Hermes Docker 部署的实战经验整理。如果你的 Hermes 部署方式不同（比如直接在宿主机运行），这个配置可能不适用。