常见问题与故障排除
> 📖 本文档翻译自 Hermes Agent 官方文档 > 最后更新：2026-04-16
常见问题与故障排除
常见问题和疑问的快速解答与修复方法。
常见问题
Hermes 支持哪些 LLM 提供商？
Hermes Agent 兼容任何 OpenAI 兼容的 API。支持的提供商包括：
- OpenRouter——通过一个 API 密钥访问数百个模型（推荐，灵活性最高）
- Nous Portal——Nous Research 自有的推理端点
- OpenAI——GPT-4o、o1、o3 等
- Anthropic——Claude 模型（通过 OpenRouter 或兼容代理）
- Google——Gemini 模型（通过 OpenRouter 或兼容代理）
- z.ai / 智谱AI——GLM 模型
- Kimi / 月之暗面——Kimi 模型
- MiniMax——全球和中国端点
- 本地模型——通过 Ollama、vLLM、llama.cpp、SGLang 或任何 OpenAI 兼容服务器
通过 hermes model 或编辑 ~/.hermes/.env 设置你的提供商。所有提供商密钥参见环境变量参考。
在 Windows 上能用吗？
不能原生运行。 Hermes Agent 需要 Unix 类环境。在 Windows 上，安装 WSL2 并在其中运行 Hermes。标准安装命令在 WSL2 中运行完美：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
在 Android / Termux 上能用吗？
可以——Hermes 现在有经过测试的 Android Termux 安装路径。
快速安装：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
完整的手动步骤、支持的附加组件和当前限制，参见 Termux 指南。
重要提示：完整的 .[all] 附加组件目前在 Android 上不可用，因为 voice 附加组件依赖 faster-whisper → ctranslate2，而 ctranslate2 不发布 Android wheels。请使用经过测试的 .[termux] 附加组件。
我的数据会发送到别处吗？
API 调用只发送到你配置的 LLM 提供商（例如 OpenRouter、你的本地 Ollama 实例）。Hermes Agent 不收集遥测数据、使用数据或分析数据。你的对话、记忆和技能存储在本地 ~/.hermes/ 中。
可以离线 / 使用本地模型吗？
可以。运行 hermes model，选择自定义端点，输入你的服务器 URL：
hermes model
选择：Custom endpoint（手动输入 URL）
API base URL: http://localhost:11434/v1
API key: ollama
Model name: qwen3.5:27b
Context length: 32768 ← 设置为与服务器实际上下文窗口匹配的值
或者直接在 config.yaml 中配置：
model: default: qwen3.5:27b provider: custom base_url: http://localhost:11434/v1
Hermes 将端点、提供商和 base URL 持久化到 config.yaml，重启后依然有效。如果你的本地服务器只加载了一个模型，/model custom 会自动检测。你也可以在 config.yaml 中设置 provider: custom——它是一等公民提供商，不是任何其他选项的别名。
这适用于 Ollama、vLLM、llama.cpp server、SGLang、LocalAI 等。详见配置指南。
💡 Ollama 用户注意
如果你在 Ollama 中设置了自定义 num_ctx（例如 ollama run --num_ctx 16384），确保在 Hermes 中设置匹配的上下文长度——Ollama 的 /api/show 报告的是模型的最大上下文，而不是你配置的有效 num_ctx。
⏱️ 本地模型超时
Hermes 自动检测本地端点并放宽流式超时（读取超时从 120 秒提高到 1800 秒，禁用过时流检测）。如果在超大上下文上仍然遇到超时，在 .env 中设置 HERMES_STREAM_READ_TIMEOUT=1800。详见本地 LLM 指南。
费用是多少？
Hermes Agent 本身免费且开源（MIT 许可证）。你只需为你选择的提供商的 LLM API 使用付费。本地模型完全免费运行。
多人可以使用同一个实例吗？
可以。消息网关允许多个用户通过 Telegram、Discord、Slack、WhatsApp 或 Home Assistant 与同一个 Hermes Agent 实例交互。访问通过允许列表（特定用户 ID）和 DM 配对（第一个发送消息的用户获得访问权）控制。
记忆和技能有什么区别？
- 记忆存储事实——Agent 了解的关于你、你的项目和偏好的信息。记忆根据相关性自动检索。
- 技能存储过程——关于如何做事的分步指令。当 Agent 遇到类似任务时，会调用相关技能。
可以在自己的 Python 项目中使用吗？
可以。导入 AIAgent 类并以编程方式使用 Hermes：
from run_agent import AIAgent
agent = AIAgent(model="openrouter/nous/hermes-3-llama-3.1-70b") response = agent.chat("Explain quantum computing briefly")
完整 API 用法参见 Python 库指南。
故障排除
安装问题
安装后 hermes: command not found
原因： 你的 Shell 尚未重新加载更新后的 PATH。
解决方案：
重新加载 Shell 配置
source ~/.bashrc # bash source ~/.zshrc # zsh
或者开启一个新的终端会话
如果仍然不行，检查安装位置：
which hermes ls ~/.local/bin/hermes
💡 提示
安装程序将 ~/.local/bin 添加到你的 PATH。如果你使用非标准 Shell 配置，手动添加 export PATH="$HOME/.local/bin:$PATH"。
Python 版本太旧
原因： Hermes 需要 Python 3.11 或更新版本。
解决方案：
python3 --version # 检查当前版本
安装更新的 Python
sudo apt install python3.12 # Ubuntu/Debian brew install python@3.12 # macOS
安装程序会自动处理此问题——如果在手动安装时看到此错误，请先升级 Python。
uv: command not found
原因： uv 包管理器未安装或不在 PATH 中。
解决方案：
curl -LsSf https://astral.sh/uv/install.sh | sh source ~/.bashrc
安装时权限被拒绝
原因： 没有足够的权限写入安装目录。
解决方案：
不要使用 sudo 运行安装程序——它安装到 ~/.local/bin
如果你之前用 sudo 安装过，清理：
sudo rm /usr/local/bin/hermes
然后重新运行标准安装程序
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
提供商与模型问题
/model 只显示一个提供商 / 无法切换提供商
原因： /model（在聊天会话内）只能在已配置的提供商之间切换。如果你只设置了 OpenRouter，那就只有 OpenRouter 会显示。
解决方案： 退出会话并从终端使用 hermes model 添加新提供商：
先退出 Hermes 聊天会话（Ctrl+C 或 /quit）
运行完整的提供商设置向导
hermes model
这让你：添加提供商、运行 OAuth、输入 API 密钥、配置端点
通过 hermes model 添加新提供商后，开始新的聊天会话——/model 现在会显示所有已配置的提供商。
快速参考
| 想要... | 使用 |
|---|---|
| 添加新提供商 | hermes model（从终端） |
| 输入/更改 API 密钥 | hermes model（从终端） |
| 会话中切换模型 | /model <名称>（在会话内） |
| 切换到不同已配置提供商 | /model provider:model（在会话内） |
API 密钥不工作
原因： 密钥缺失、过期、设置错误或属于错误的提供商。
解决方案：
检查你的配置
hermes config show
重新配置提供商
hermes model
或直接设置
hermes config set OPENROUTER_API_KEY sk-or-...xxxx
⚠️ 警告
确保密钥与提供商匹配。OpenAI 密钥不能用于 OpenRouter，反之亦然。检查 ~/.hermes/.env 中是否有冲突的条目。
模型不可用 / 模型未找到
原因： 模型标识符不正确或你的提供商上不可用。
解决方案：
列出提供商的可用模型
hermes model
设置有效模型
hermes config set HERMES_MODEL openrouter/nous/hermes-3-llama-3.1-70b
或按会话指定
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct
速率限制（429 错误）
原因： 你已超出提供商的速率限制。
解决方案： 等待一会儿再重试。对于持续使用，考虑：
- 升级你的提供商计划
- 切换到不同的模型或提供商
- 使用
hermes chat --provider <备选>路由到不同的后端
上下文长度超出
原因： 对话已超过模型的上下文窗口长度，或者 Hermes 为你的模型检测到了错误的上下文长度。
解决方案：
压缩当前会话
/compress
或开始新会话
hermes chat
使用更大上下文窗口的模型
hermes chat --model openrouter/google/gemini-3-flash-preview
如果这在第一个长对话中就发生了，Hermes 可能为你的模型检测到了错误的上下文长度。检查它检测到的值：
查看 CLI 启动行——它显示检测到的上下文长度（例如 📊 Context limit: 128000 tokens）。你也可以在会话中使用 /usage 检查。
要修复上下文检测，显式设置：
在 ~/.hermes/config.yaml 中
model: default: your-model-name context_length: 131072 # 你的模型实际上下文窗口
对于自定义端点，按模型添加：
custom_providers:
- name: "My Server" base_url: "http://localhost:11434/v1" models: qwen3.5:27b: context_length: 32768
参见上下文长度检测了解自动检测的工作原理和所有覆盖选项。
终端问题
命令被阻止为危险命令
原因： Hermes 检测到潜在破坏性命令（例如 rm -rf、DROP TABLE）。这是安全功能。
解决方案： 当提示时，审查命令并输入 y 批准。你也可以：
- 让 Agent 使用更安全的替代方案
- 查看安全文档中的完整危险模式列表
💡 提示
这是按设计工作的——Hermes 绝不会静默运行破坏性命令。审批提示会准确显示将要执行的内容。
通过消息网关 sudo 不工作
原因： 消息网关在没有交互式终端的情况下运行，所以 sudo 无法提示输入密码。
解决方案：
- 避免在消息中使用
sudo——让 Agent 寻找替代方案 - 如果必须使用
sudo，在/etc/sudoers中为特定命令配置免密 sudo - 或切换到终端界面执行管理任务：
hermes chat
Docker 后端无法连接
原因： Docker 守护进程未运行或用户缺少权限。
解决方案：
检查 Docker 是否运行
docker info
将用户添加到 docker 组
sudo usermod -aG docker $USER newgrp docker
验证
docker run hello-world
消息问题
Bot 不响应消息
原因： Bot 未运行、未授权或你的用户不在允许列表中。
解决方案：
检查网关是否运行
hermes gateway status
启动网关
hermes gateway start
检查日志中的错误
cat ~/.hermes/logs/gateway.log | tail -50
消息不送达
原因： 网络问题、Bot Token 过期或平台 Webhook 配置错误。
解决方案：
- 使用
hermes gateway setup验证你的 Bot Token 有效 - 检查网关日志：
cat ~/.hermes/logs/gateway.log | tail -50 - 对于基于 Webhook 的平台（Slack、WhatsApp），确保你的服务器可公开访问
允许列表混淆——谁能与 Bot 对话？
原因： 授权模式决定谁获得访问权限。
解决方案：
| 模式 | 工作方式 |
|---|---|
| 允许列表 | 仅配置中列出的用户 ID 可以交互 |
| DM 配对 | 第一个在 DM 中发送消息的用户获得独占访问权 |
| 开放 | 任何人都可以交互（不建议用于生产环境） |
在 ~/.hermes/config.yaml 的网关设置下配置。参见消息文档。
网关无法启动
原因： 缺少依赖、端口冲突或 Token 配置错误。
解决方案：
安装消息依赖
pip install "hermes-agent[telegram]" # 或 [discord]、[slack]、[whatsapp]
检查端口冲突
lsof -i :8080
验证配置
hermes config show
WSL：网关不断断开或 hermes gateway start 失败
原因： WSL 的 systemd 支持不可靠。许多 WSL2 安装未启用 systemd，即使启用了，服务也可能在 WSL 重启或 Windows 空闲关闭后不存活。
解决方案： 使用前台模式而非 systemd 服务：
方式 1：直接前台运行（最简单）
hermes gateway run
方式 2：通过 tmux 持久化（关闭终端后仍运行）
tmux new -s hermes 'hermes gateway run'
稍后重新连接：tmux attach -t hermes
方式 3：通过 nohup 后台运行
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &
如果你仍想尝试 systemd，确保它已启用：
-
打开
/etc/wsl.conf（不存在则创建） -
添加：
[boot] systemd=true
-
从 PowerShell 运行：
wsl --shutdown -
重新打开 WSL 终端
-
验证：
systemctl is-system-running应该显示 "running" 或 "degraded"
💡 Windows 启动时自动启动
要实现可靠的自动启动，使用 Windows 任务计划程序在登录时启动 WSL + 网关：
- 创建一个运行
wsl -d Ubuntu -- bash -lc 'hermes gateway run'的任务 - 设置为用户登录时触发
macOS：网关找不到 Node.js / ffmpeg / 其他工具
原因： launchd 服务继承最小 PATH（/usr/bin:/bin:/usr/sbin:/sbin），不包含 Homebrew、nvm、cargo 或其他用户安装的工具目录。这通常导致 WhatsApp 桥接（node not found）或语音转录（ffmpeg not found）失败。
解决方案： 网关在你运行 hermes gateway install 时捕获你的 Shell PATH。如果你在设置网关后安装了工具，重新运行安装以捕获更新的 PATH：
hermes gateway install # 重新快照你当前的 PATH hermes gateway start # 检测到更新的 plist 并重新加载
你可以验证 plist 是否有正确的 PATH：
/usr/libexec/PlistBuddy -c "Print :EnvironmentVariables:PATH"
~/Library/LaunchAgents/ai.hermes.gateway.plist
性能问题
响应缓慢
原因： 大型模型、远程 API 服务器或包含大量工具的繁重系统提示。
解决方案：
- 尝试更快/更小的模型：
hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct - 减少活跃工具集：
hermes chat -t "terminal" - 检查到提供商的网络延迟
- 对于本地模型，确保你有足够的 GPU VRAM
Token 使用量高
原因： 长对话、冗长的系统提示或大量工具调用累积了上下文。
解决方案：
压缩对话以减少 Token
/compress
检查会话 Token 使用量
/usage
💡 提示
在长会话中定期使用 /compress。它会总结对话历史并显著减少 Token 使用量，同时保留上下文。
会话变得太长
原因： 持续的对话累积了消息和工具输出，接近上下文限制。
解决方案：
压缩当前会话（保留关键上下文）
/compress
开始新会话并引用旧会话
hermes chat
稍后恢复特定会话
hermes chat --continue
MCP 问题
MCP 服务器无法连接
原因： 服务器二进制文件未找到、命令路径错误或缺少运行时。
解决方案：
确保 MCP 依赖已安装（标准安装中已包含）
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
对于基于 npm 的服务器，确保 Node.js 可用
node --version npx --version
手动测试服务器
npx -y @modelcontextprotocol/server-filesystem /tmp
验证你的 ~/.hermes/config.yaml MCP 配置：
mcp_servers: filesystem: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
MCP 服务器的工具未显示
原因： 服务器已启动但工具发现失败、工具被配置过滤或服务器不支持你期望的 MCP 功能。
解决方案：
-
检查网关/Agent 日志中的 MCP 连接错误
-
确保服务器响应
tools/listRPC 方法 -
审查该服务器下的
tools.include、tools.exclude、tools.resources、tools.prompts或enabled设置 -
请注意，资源/提示工具仅在会话实际支持这些功能时才注册
-
更改配置后使用
/reload-mcp验证 MCP 服务器已配置
hermes config show | grep -A 12 mcp_servers
配置更改后重启 Hermes 或重新加载 MCP
hermes chat
另请参阅：
MCP 超时错误
原因： MCP 服务器响应时间过长或在执行过程中崩溃。
解决方案：
- 如果支持，在 MCP 服务器配置中增加超时
- 检查 MCP 服务器进程是否仍在运行
- 对于远程 HTTP MCP 服务器，检查网络连接
⚠️ 警告
如果 MCP 服务器在请求中途崩溃，Hermes 会报告超时。检查服务器自己的日志（不仅仅是 Hermes 日志）来诊断根本原因。
配置文件
配置文件与设置 HERMES_HOME 有什么区别？
配置文件是在 HERMES_HOME 之上的管理层。你_可以_在每次命令前手动设置 HERMES_HOME=/some/path，但配置文件会为你处理所有细节：创建目录结构、生成 Shell 别名（hermes-work）、在 ~/.hermes/active_profile 中跟踪活跃配置文件、以及自动在所有配置文件之间同步技能更新。它们还集成了 Tab 补全，这样你不必记住路径。
两个配置文件可以共享同一个 Bot Token 吗？
不可以。每个消息平台（Telegram、Discord 等）需要对 Bot Token 的独占访问。如果两个配置文件同时尝试使用同一个 Token，第二个网关将无法连接。为每个配置文件创建单独的 Bot——对于 Telegram，找 @BotFather 创建额外的 Bot。
配置文件之间共享记忆或会话吗？
不共享。每个配置文件有自己的记忆存储、会话数据库和技能目录。它们完全隔离。如果你想用现有的记忆和会话创建新配置文件，使用 hermes profile create newname --clone-all 从当前配置文件复制所有内容。
运行 hermes update 时会发生什么？
hermes update 拉取最新代码并一次性重新安装依赖（不是按配置文件）。然后自动将更新的技能同步到所有配置文件。你只需运行一次 hermes update——它覆盖机器上的每个配置文件。
可以将配置文件移到另一台机器吗？
可以。将配置文件导出为可移植归档并在另一台机器上导入：
在源机器上
hermes profile export work ./work-backup.tar.gz
将文件复制到目标机器，然后：
hermes profile import ./work-backup.tar.gz work
导入的配置文件将包含导出时的所有配置、记忆、会话和技能。如果新机器有不同的设置，你可能需要更新路径或重新认证提供商。
可以运行多少个配置文件？
没有硬性限制。每个配置文件只是 ~/.hermes/profiles/ 下的一个目录。实际限制取决于你的磁盘空间和系统可以处理多少并发网关（每个网关是一个轻量级 Python 进程）。运行几十个配置文件没问题；每个空闲的配置文件不使用资源。
工作流与模式
为不同任务使用不同模型（多模型工作流）
场景： 你使用 GPT-5.4 作为日常驱动，但 Gemini 或 Grok 更擅长写社交媒体内容。每次手动切换模型很繁琐。
解决方案：委派配置。 Hermes 可以自动将子 Agent 路由到不同的模型。在 ~/.hermes/config.yaml 中设置：
delegation: model: "google/gemini-3-flash-preview" # 子 Agent 使用此模型 provider: "openrouter" # 子 Agent 的提供商
现在当你告诉 Hermes "写一个关于 X 的 Twitter 主题帖"并产生 delegate_task 子 Agent 时，该子 Agent 会在 Gemini 上运行而不是你的主模型。你的主要对话仍在 GPT-5.4 上。
你也可以在提示中明确指定："委派一个任务来写关于我们产品发布的社交媒体帖子。用你的子 Agent 来实际撰写。" Agent 会使用 delegate_task，自动使用委派配置。
对于不使用委派的一次性模型切换，在 CLI 中使用 /model：
/model google/gemini-3-flash-preview # 为此会话切换
... 写你的内容 ...
/model openai/gpt-5.4 # 切回
详见子 Agent 委派。
在一个 WhatsApp 号码上运行多个 Agent（按聊天绑定）
场景： 在 OpenClaw 中，你有多个独立 Agent 绑定到特定的 WhatsApp 聊天——一个用于家庭购物清单群，另一个用于你的私聊。Hermes 能做到吗？
当前限制： Hermes 配置文件每个需要自己的 WhatsApp 号码/会话。你不能将多个配置文件绑定到同一 WhatsApp 号码的不同聊天——WhatsApp 桥接（Baileys）每个号码使用一个认证会话。
替代方案：
-
使用单个配置文件配合人格切换。 创建不同的
AGENTS.md上下文文件或使用/personality命令按聊天更改行为。Agent 看到它在哪个聊天中并可以适应。 -
使用 Cron 任务处理专门任务。 对于购物清单跟踪器，设置一个监控特定聊天并管理列表的 Cron 任务——不需要单独的 Agent。
-
使用单独的号码。 如果你需要真正独立的 Agent，将每个配置文件与自己的 WhatsApp 号码配对。来自 Google Voice 等服务的虚拟号码适用于此。
-
改用 Telegram 或 Discord。 这些平台更自然地支持按聊天绑定——每个 Telegram 群组或 Discord 频道都有自己的会话，你可以在同一账号上运行多个 Bot Token（每个配置文件一个）。
详见配置文件和 WhatsApp 设置。
控制 Telegram 中显示的内容（隐藏日志和推理）
场景： 你在 Telegram 中看到网关执行日志、Hermes 推理和工具调用详情，而不仅仅是最终输出。
解决方案： config.yaml 中的 display.tool_progress 设置控制显示多少工具活动：
display: tool_progress: "off" # 选项：off、new、all、verbose
off——仅最终响应。无工具调用、无推理、无日志。new——显示新发生的工具调用（简要一行）。all——显示所有工具活动包括结果。verbose——完整详情包括工具参数和输出。
对于消息平台，off 或 new 通常是你想要的。编辑 config.yaml 后，重启网关使更改生效。
你也可以使用 /verbose 命令按会话切换（如果启用）：
display: tool_progress_command: true # 在网关中启用 /verbose
在 Telegram 上管理技能（斜杠命令限制）
场景： Telegram 有 100 个斜杠命令的限制，你的技能快超出了。你想禁用 Telegram 上不需要的技能，但 hermes skills config 设置似乎不生效。
解决方案： 使用 hermes skills config 按平台禁用技能。这会写入 config.yaml：
skills: disabled: [] # 全局禁用的技能 platform_disabled: telegram: [skill-a, skill-b] # 仅在 telegram 上禁用
更改后，重启网关（hermes gateway restart 或杀掉并重新启动）。Telegram Bot 命令菜单在启动时重建。
💡 提示
描述很长的技能在 Telegram 菜单中会被截断到 40 个字符，以保持在载荷大小限制内。如果技能没有出现，可能是总载荷大小问题而不是 100 个命令计数限制——禁用未使用的技能对两者都有帮助。
共享话题会话（多用户，一个对话）
场景： 你有一个 Telegram 或 Discord 话题，多个人在其中提及 Bot。你希望该话题中的所有提及属于一个共享对话，而不是分开的按用户会话。
当前行为： Hermes 在大多数平台上按用户 ID 创建会话，所以每个人都获得自己的对话上下文。这是为隐私和上下文隔离而设计的。
替代方案：
-
使用 Slack。 Slack 会话按话题而不是按用户索引。同一话题中的多个用户共享一个对话——正好是你描述的行为。这是最自然的选择。
-
使用带单一用户的群聊。 如果一个人是指定的"操作员"来转达问题，会话保持统一。其他人可以旁观。
-
使用 Discord 频道。 Discord 会话按频道索引，所以同一频道中的所有用户共享上下文。为共享对话使用专用频道。
将 Hermes 导出到另一台机器
场景： 你在一台机器上积累了技能、Cron 任务和记忆，想将所有内容迁移到新的专用 Linux 服务器。
解决方案：
-
在新机器上安装 Hermes Agent：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
-
复制整个
~/.hermes/目录但不包括hermes-agent子目录（那是代码仓库——新安装有自己的）：在源机器上
rsync -av --exclude='hermes-agent'
/.hermes/ newmachine:/.hermes/
或者使用配置文件导出/导入：
在源机器上
hermes profile export default ./hermes-backup.tar.gz
在目标机器上
hermes profile import ./hermes-backup.tar.gz default
- 在新机器上，运行
hermes setup验证 API 密钥和提供商配置正常工作。重新认证任何消息平台（特别是 WhatsApp，使用 QR 配对）。
~/.hermes/ 目录包含所有内容：config.yaml、.env、SOUL.md、memories/、skills/、state.db（会话）、cron/ 和任何自定义插件。代码本身位于 ~/.hermes/hermes-agent/ 并全新安装。
安装后重新加载 Shell 时权限被拒绝
场景： 运行 Hermes 安装程序后，source ~/.zshrc 出现权限被拒绝错误。
原因： 这通常发生在 ~/.zshrc（或 ~/.bashrc）文件权限不正确，或安装程序无法干净地写入时。这不是 Hermes 特定的问题——是 Shell 配置权限问题。
解决方案：
检查权限
ls -la ~/.zshrc
如需修复（应为 -rw-r--r-- 或 644）
chmod 644 ~/.zshrc
然后重新加载
source ~/.zshrc
或者直接打开新的终端窗口——它会自动获取 PATH 更改
如果安装程序添加了 PATH 行但权限不对，你可以手动添加：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
首次 Agent 运行时出现 400 错误
场景： 设置完成正常，但第一次聊天尝试失败，HTTP 400。
原因： 通常是模型名称不匹配——配置的模型在你的提供商上不存在，或 API 密钥没有访问权限。
解决方案：
检查配置了什么模型和提供商
hermes config show | head -20
重新运行模型选择
hermes model
或使用已知良好的模型测试
hermes chat -q "hello" --model anthropic/claude-sonnet-4.6
如果使用 OpenRouter，确保你的 API 密钥有余额。来自 OpenRouter 的 400 错误通常意味着模型需要付费计划或模型 ID 有拼写错误。
仍然卡住？
如果你的问题未在此处涵盖：
- 搜索已有问题： GitHub Issues
- 向社区提问： Nous Research Discord
- 提交 Bug 报告： 包含你的操作系统、Python 版本（
python3 --version）、Hermes 版本（hermes --version）和完整错误消息