Hermes Agent环境变量设置教程

想让 Hermes Agent 顺利连接模型却总提示“API 密钥无效”或“模型未连接”？问题很可能出在环境变量配置上！本文详解五种精准、可靠且适配不同场景的环境变量设置方法：从轻量便捷的 `.env` 文件持久化配置，到 shell 全局生效、终端临时调试、Windows PowerShell 用户级注册表写入，再到 WSL2 无缝同步 Windows 变量——无论你是 Linux/macOS 用户、Windows 原生开发者，还是跨平台 WSL2 玩家，都能找到最适合你工作流的一键解决方案，快速排除连接故障，即刻开启高效 AI 协作。

如果您尝试运行 Hermes Agent，但系统提示模型未连接或 API 密钥无效，则很可能是环境变量未正确写入或未被加载。以下是设置 Hermes Agent 环境变量的具体操作说明：

一、通过 .env 文件配置 API 密钥

该方法将密钥持久化写入专用配置文件，由 Hermes Agent 启动时自动读取，适用于所有支持的模型服务商，且无需修改系统级环境变量。

1、使用文本编辑器打开 Hermes Agent 的环境变量配置文件：nano ~/.hermes/.env

2、在文件中添加对应服务商的密钥行（仅填写其中一行即可）：OPENAI_API_KEY=sk-xxx 或 OPENROUTER_API_KEY=sk-or-xxx 或 KIMI_API_KEY=xxx

3、按 Ctrl+O 保存文件，回车确认；再按 Ctrl+X 退出编辑器。

4、重启 Hermes Agent 以加载新密钥：hermes

二、通过 shell 配置文件全局设置

该方法将密钥注入用户级 shell 环境，确保所有终端会话均可访问，适合需频繁切换上下文或集成到其他脚本的场景。

1、编辑当前 shell 的配置文件：nano ~/.bashrc（Linux/macOS）或 nano ~/.zshrc（macOS Zsh 用户）

2、在文件末尾新增一行，格式为：export OPENROUTER_API_KEY="sk-or-xxx"（注意引号不可省略）

3、保存并退出编辑器后，立即生效配置：source ~/.bashrc 或 source ~/.zshrc

4、验证变量是否已加载：echo $OPENROUTER_API_KEY，应显示完整密钥值

三、临时设置环境变量（单次会话有效）

该方法不写入任何文件，仅在当前终端窗口中生效，适用于快速测试密钥有效性或调试多密钥切换场景，关闭终端即失效。

1、在终端中直接执行导出命令：export OPENAI_API_KEY=sk-xxx

2、启动 Hermes Agent 并验证：hermes doctor

3、观察输出中是否出现 Model: connected，若未出现，说明密钥未被识别或网络不通

四、Windows PowerShell 下设置用户级环境变量

该方法适配原生 Windows PowerShell 环境，通过注册表持久化存储，避免每次启动都需重复设置，尤其适用于管理员权限安装后的首次配置。

1、以普通用户身份打开 PowerShell，执行以下命令写入用户级环境变量：[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-xxx", "User")

2、重启 PowerShell 窗口，使变更生效

3、验证变量是否已设置：echo $env:OPENROUTER_API_KEY

4、运行诊断命令确认连通性：hermes doctor

五、WSL2 中同步 Windows 环境变量

该方法用于在 WSL2 子系统中复用 Windows 主机已配置的密钥，避免重复维护两套变量，特别适合跨平台开发流程。

1、编辑 WSL2 的 bash 配置文件：nano ~/.bashrc

2、在文件末尾添加同步语句：export OPENROUTER_API_KEY="$(cmd.exe /c 'echo %OPENROUTER_API_KEY%')"

3、保存退出后执行：source ~/.bashrc

4、检查变量内容是否正确转换：echo $OPENROUTER_API_KEY（注意 cmd 输出末尾可能含回车符，必要时用 tr 命令清理）

今天关于《Hermes Agent环境变量设置教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！