Hermes Docker 里读不到 GITHUB_TOKEN？~/.hermes/.env 环境变量转发排错指南

如果你在 Hermes Agent 里执行过：

hermes config set GITHUB_TOKEN github_xxxx

然后在交互式对话里问：

can you access GITHUB_TOKEN env variable?

Agent 却回答“不能”，或者 GitHub skill / GitHub auth 相关能力在 Docker terminal 里拿不到 token，那么问题可能不是 token 写错，而是 Hermes Docker 执行环境没有把 ~/.hermes/.env 里的变量转发进容器。

这篇文章基于 NousResearch/hermes-agent issue #1436，整理一个很常见的 Docker 环境变量问题：

GITHUB_TOKEN environment variable has been set in ~/.hermes/.env file, but not available in terminal that provide by Docker

适合搜索关键词：Hermes Docker GITHUB_TOKEN not available、hermes config set env not in Docker、~/.hermes/.env not forwarded to container、Hermes GitHub token Docker terminal、docker_forward_env Hermes。

先给结论：hermes config set 写入了本机配置，不等于 Docker 容器能读到

Hermes 的 hermes config set GITHUB_TOKEN ... 会把 secret 保存到 Hermes 的配置或 .env 体系中，例如：

~/.hermes/.env

但如果你使用的是 Docker-based terminal，命令实际运行在容器里。容器能看到哪些环境变量，取决于 Hermes 启动 Docker exec 时有没有把这些变量传进去。

issue #1436 的根因正是：Docker exec 只转发了当前 shell session 里的 os.getenv() 变量，却忽略了 ~/.hermes/.env 里由 hermes config set 保存的 secret。

结果就是：

• 宿主机 Hermes 配置里有 GITHUB_TOKEN；
• 但容器 shell 里没有；
• Agent 在 Docker terminal 中执行 GitHub 相关命令时读不到 token。

典型现象

你可能看到：

hermes config set GITHUB_TOKEN github_xxxx

看起来设置成功。

但进入 Hermes 对话后，让它检查：

echo $GITHUB_TOKEN

或者让它访问私有 repo，结果发现：

• $GITHUB_TOKEN 是空的；
• GitHub CLI 未认证；
• GitHub skill 说没有 token；
• 私有 repo 访问失败；
• Agent 回答“我不能访问 GITHUB_TOKEN 环境变量”。

如果你使用 Docker terminal，这就很符合 #1436 的场景。

为什么宿主机有变量，容器里没有？

Docker 容器不是宿主机 shell 的透明复制。

环境变量通常有几个来源：

1. 你当前 shell 里 export 的变量； 2. .env 文件； 3. Docker run / exec 时显式传入的 -e； 4. compose 配置； 5. 应用自己加载后再注入的变量。

问题版本里，Hermes Docker exec 只看当前进程环境变量，例如：

os.getenv("GITHUB_TOKEN")

但 hermes config set 保存到 ~/.hermes/.env 的变量，并不一定已经存在于当前 shell process env。

所以 Docker exec 没有把它带进容器。

修复方向：加载 ~/.hermes/.env 作为 fallback

issue 评论里提到 PR #1439 的修复思路：

• Docker exec command 不只读取当前 shell session 的 os.getenv()；
• 还要通过已有的 load_env() helper 加载 ~/.hermes/.env；
• 如果 shell env 没有，就用 .env 里的值作为 fallback；
• 这样通过 hermes config set 保存的 secret 也能进入 Docker container。

后续维护者还提到 docker_forward_env 显式 allowlist 是更合适的方向，对应 PR #1449；issue 最终由 commit 556e0f4b4326cf7e04e7095e7946583bce8b4296 closed。

这说明官方方向不是“把所有宿主机环境变量都无脑塞进容器”，而是更可控地转发需要的变量。

临时排查：确认变量到底在哪一层丢了

可以按三层检查。

1. 检查 Hermes 配置层

确认你确实设置过：

hermes config get GITHUB_TOKEN

如果不能直接显示 secret，也可以检查 ~/.hermes/.env 是否有对应 key，但不要把 token 内容粘贴到聊天或 issue 里。

2. 检查宿主机 shell 层

运行：

echo $GITHUB_TOKEN

如果这里为空，但 ~/.hermes/.env 有值，就说明它只存在于 Hermes 配置文件中，不在当前 shell env。

3. 检查 Docker terminal 层

让 Hermes Docker terminal 执行：

printenv GITHUB_TOKEN

如果这里为空，就说明变量没有被转发进容器。

Workaround：显式导出或配置 docker_forward_env

如果你使用的 Hermes 版本还没有修复，可以临时用几种方式绕过。

方式一：当前 shell 显式 export

export GITHUB_TOKEN=github_xxxx
hermes

这样 Docker exec 通过 os.getenv() 有机会读到它。

注意：不要把真实 token 写进 shell history、截图或聊天记录。

方式二：升级 Hermes

升级到包含 .env fallback / docker_forward_env 相关修复的版本。

方式三：使用显式 allowlist

如果你的版本支持类似 docker_forward_env 的配置，建议只转发必要变量，例如：

docker_forward_env:
  - GITHUB_TOKEN
  - GIT_AUTHOR_NAME
  - GIT_AUTHOR_EMAIL
  - GIT_COMMITTER_NAME
  - GIT_COMMITTER_EMAIL

不要把整个宿主机环境都转发进去，避免泄露无关 secret。

Git username/email 和 GITHUB_TOKEN 不是一回事

issue 评论里还讨论了 Git config。

很多人以为 Git username/email 也是环境变量，但通常它们保存在：

~/.gitconfig

而不是 $GIT_AUTHOR_NAME 这种环境变量。

所以即使 GITHUB_TOKEN 转发进容器，Git commit 的用户名和邮箱仍可能不对。

可选方案有两个：

方案 A：设置 Git 环境变量

hermes config set GIT_AUTHOR_NAME "Your Name"
hermes config set GIT_AUTHOR_EMAIL "you@example.com"
hermes config set GIT_COMMITTER_NAME "Your Name"
hermes config set GIT_COMMITTER_EMAIL "you@example.com"

然后确保这些变量也被转发进 Docker。

方案 B：只读挂载 ~/.gitconfig

如果支持 docker volumes，可以挂载：

docker_volumes:
  - ~/.gitconfig:/root/.gitconfig:ro

评论里也提到后续修复支持 ~ expansion，并可以把 ~/.gitconfig 只读挂载到容器中。

安全注意：不要盲目转发所有 secret

这个问题看起来像“变量转发越多越好”，但生产环境里不建议这么做。

更安全的原则是：

• 只转发当前任务需要的 token；
• 使用 allowlist，而不是全量 env dump；
• 不把 token 写进文章、日志、截图或 issue；
• 能用短期 token 就不用长期 token；
• 私有 repo 权限只给最小范围。

尤其是 GITHUB_TOKEN，如果具备 repo 写权限，泄露风险很高。

和 DeepAI API 中转站的关系

这个问题本身不是 DeepAI API 中转站的问题。它发生在 Hermes Docker terminal 的环境变量转发层。

DeepAI API 中转站适合统一 OpenAI-compatible 模型接入，例如：

• Base URL；
• API Key；
• 模型选择；
• Cherry Studio、Cline、Dify、Open WebUI 等工具里的统一配置。

但如果你的 Agent 在 Docker 容器里运行，任何 API Key——无论是 GitHub、OpenAI、DeepAI 还是其他 provider——都需要正确进入容器环境或配置文件。

所以更通用的经验是：

> API Key 配对了，不代表容器里能读到；Docker 环境变量转发必须单独验证。

FAQ

hermes config set GITHUB_TOKEN 成功了，为什么 Docker 里还是空？

因为它可能写入了 ~/.hermes/.env，但 Docker exec 只转发了当前 shell env，没有加载 .env 文件。

直接 export GITHUB_TOKEN 可以吗？

可以作为临时 workaround，但注意 shell history 和泄露风险。更推荐升级到支持 .env fallback 或 docker_forward_env 的版本。

Git 用户名和邮箱为什么也不对？

Git username/email 通常在 ~/.gitconfig，不是环境变量。需要挂载 .gitconfig，或设置 GIT_AUTHOR_* / GIT_COMMITTER_* 环境变量。

能不能把所有环境变量都转发进容器？

不建议。这样可能把无关 secret 暴露给容器和 Agent。最好用 allowlist。

DeepAI API Key 也会遇到同样问题吗？

会。如果 DeepAI Key 只存在宿主机 .env，但 Docker 容器没拿到，容器内调用也会失败。检查方式和 GITHUB_TOKEN 类似。

总结

Hermes Docker terminal 里读不到 GITHUB_TOKEN，不一定是 token 配错，而可能是：

hermes config set → 写入 ~/.hermes/.env
Docker exec → 没加载 ~/.hermes/.env
容器内 → GITHUB_TOKEN 为空

排查时要分清三层：Hermes 配置、本机 shell、Docker 容器。

最稳的处理方式是升级到支持 .env fallback / docker_forward_env 的版本，并只把必要变量显式转发进容器。

一句话总结：在 Docker 模式下，secret 写进 Hermes 配置不等于容器能读到；一定要验证容器内的 printenv。