常见问题与故障排除
快速解答最常见的问题和解决方法。
常见问题
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 / ZhipuAI — GLM 模型
- Kimi / Moonshot AI — 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 现已提供经过测试的 Termux 安装路径,适用于 Android 手机。
快速安装方式:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
如需完整手动步骤、支持的附加功能及当前限制,请参见 Termux 指南。
重要提示:目前 Android 上无法使用完整的 .[all] 附加功能,因为 voice 附加功能依赖于 faster-whisper → ctranslate2,而 ctranslate2 未发布 Android 轮子(wheels)。请改用经过测试的 .[termux] 附加功能。
我的数据会被发送到哪里?
API 调用仅发送至您配置的 LLM 提供商(例如 OpenRouter、您的本地 Ollama 实例)。Hermes Agent 不收集遥测数据、使用数据或分析信息。您的对话记录、记忆和技能均本地存储在 ~/.hermes/ 目录中。
我可以离线使用或使用本地模型吗?
可以。运行 hermes model,选择 自定义端点,并输入您服务器的 URL:
hermes model
# Select: Custom endpoint (enter URL manually)
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen3.5:27b
# Context length: 32768 ← set this to match your server's actual context window
或直接在 config.yaml 中配置:
model:
default: qwen3.5:27b
provider: custom
base_url: http://localhost:11434/v1
Hermes 会将端点、提供商和基础 URL 持久化保存在 config.yaml 中,因此重启后仍有效。如果您的本地服务器仅加载了一个模型,/model custom 会自动检测该模型。您也可以在 config.yaml 中设置 provider: custom —— 这是一个独立的提供商,而非其他任何提供者的别名。
该功能支持 Ollama、vLLM、llama.cpp 服务器、SGLang、LocalAI 等。详情请参见 配置指南。
如果您在 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)和私信配对(第一个发消息的用户获得访问权)进行控制。
记忆和技能有什么区别?
- 记忆 存储的是 事实 —— 代理关于您、您的项目和偏好的信息。记忆会根据相关性自动检索。
- 技能 存储的是 操作流程 —— 完成某项任务的分步说明。当代理遇到类似任务时会调用这些技能。
我可以在自己的 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。
解决方案:
# Reload your shell profile
source ~/.bashrc # bash
source ~/.zshrc # zsh
# Or start a new terminal session
如果仍无效,请验证安装路径:
which hermes
ls ~/.local/bin/hermes
安装程序会将 ~/.local/bin 添加到你的 PATH 中。如果你使用的是非标准的 shell 配置,请手动添加 export PATH="$HOME/.local/bin:$PATH"。
Python 版本过旧
原因: Hermes 要求使用 Python 3.11 或更高版本。
解决方案:
python3 --version # Check current version
# Install a newer 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
安装过程中出现权限拒绝错误
原因: 对安装目录写入权限不足。
解决方案:
# Don't use sudo with the installer — it installs to ~/.local/bin
# If you previously installed with sudo, clean up:
sudo rm /usr/local/bin/hermes
# Then re-run the standard installer
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
提供商与模型问题
API 密钥无效
原因: 密钥缺失、已过期、设置错误或与提供方不匹配。
解决方案:
# Check your configuration
hermes config show
# Re-configure your provider
hermes model
# Or set directly
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx
请确保密钥与提供方匹配。OpenAI 的密钥无法用于 OpenRouter,反之亦然。请检查 ~/.hermes/.env 中是否存在冲突的条目。
模型不可用 / 找不到模型
原因: 模型标识符错误,或该模型在你的提供方上不可用。
解决方案:
# List available models for your provider
hermes model
# Set a valid model
hermes config set HERMES_MODEL openrouter/nous/hermes-3-llama-3.1-70b
# Or specify per-session
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct
速率限制(429 错误)
原因: 已超过提供方的速率限制。
解决方案: 稍等片刻后重试。对于持续使用场景,可考虑:
- 升级提供方套餐
- 切换到其他模型或提供方
- 使用
hermes chat --provider <alternative>将请求路由至其他后端
上下文长度超出限制
原因: 对话内容过长,超出模型的上下文窗口;或 Hermes 检测到的上下文长度与实际不符。
解决方案:
# Compress the current session
/compress
# Or start a fresh session
hermes chat
# Use a model with a larger context window
hermes chat --model openrouter/google/gemini-3-flash-preview
如果在首次进行长对话时出现此问题,可能是 Hermes 对你的模型上下文长度检测错误。请检查其检测结果:
查看 CLI 启动行——会显示检测到的上下文长度(例如:📊 上下文限制:128000 个 token)。你也可以在会话中使用 /usage 命令查看。
要修复上下文长度检测,可手动显式设置:
# In ~/.hermes/config.yaml
model:
default: your-model-name
context_length: 131072 # your model's actual context window
对于自定义端点,可按模型单独添加:
custom_providers:
- name: "My Server"
base_url: "http://localhost:11434/v1"
models:
qwen3.5:27b:
context_length: 32768
有关自动检测机制及所有覆盖选项的详情,请参阅 上下文长度检测。
终端问题
命令被阻止为危险操作
原因: Hermes 检测到潜在破坏性命令(如 rm -rf、DROP TABLE)。这是安全防护机制。
解决方案: 当提示时,审查命令并输入 y 确认执行。你也可以:
- 要求代理使用更安全的替代方案
- 参阅 安全文档 中的完整危险模式列表
此行为符合预期——Hermes 永远不会静默执行破坏性命令。确认提示会明确展示即将执行的内容。
通过消息网关无法使用 sudo
原因: 消息网关在无交互式终端的环境下运行,因此 sudo 无法提示输入密码。
解决方案:
- 避免在消息中使用
sudo——请让代理寻找替代方案 - 若必须使用
sudo,请在/etc/sudoers中为特定命令配置免密 sudo - 或切换到终端界面执行管理任务:
hermes chat
Docker 后端无法连接
原因: Docker 守护进程未运行,或用户权限不足。
解决方案:
# Check Docker is running
docker info
# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker
# Verify
docker run hello-world
消息通信问题
机器人不响应消息
原因: 机器人未运行、未授权,或你的用户不在允许列表中。
解决方案:
# Check if the gateway is running
hermes gateway status
# Start the gateway
hermes gateway start
# Check logs for errors
cat ~/.hermes/logs/gateway.log | tail -50
消息无法送达
原因: 网络问题、机器人令牌过期,或平台 Webhook 配置错误。
解决方案:
- 使用
hermes gateway setup验证机器人令牌是否有效 - 检查网关日志:
cat ~/.hermes/logs/gateway.log | tail -50 - 对基于 Webhook 的平台(如 Slack、WhatsApp),请确保你的服务器可公开访问
允许列表混淆——谁可以与机器人对话?
原因: 授权模式决定了谁可获得访问权限。
解决方案:
| 模式 | 工作方式 |
|---|---|
| 允许列表 | 仅配置中列出的用户 ID 可以交互 |
| 私信配对 | 第一个在私信中发送消息的用户将获得独占访问权 |
| 公开 | 任何人都可交互(不推荐用于生产环境) |
在 ~/.hermes/config.yaml 中对应网关设置下进行配置。详见 消息通信文档。
网关无法启动
原因: 缺少依赖项、端口冲突或令牌配置错误。
解决方案:
# Install messaging dependencies
pip install "hermes-agent[telegram]" # or [discord], [slack], [whatsapp]
# Check for port conflicts
lsof -i :8080
# Verify configuration
hermes config show
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 # Re-snapshots your current PATH
hermes gateway start # Detects the updated plist and reloads
您可以验证 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 使用量过高
原因: 对话过长、系统提示过于冗长,或大量工具调用累积了过多上下文。
解决方案:
# Compress the conversation to reduce tokens
/compress
# Check session token usage
/usage
在长时间会话中定期使用 /compress。它会总结对话历史,显著降低 Token 使用量,同时保留上下文信息。
会话过长
原因: 长时间对话累积了大量消息和工具输出,接近上下文限制。
解决方案:
# Compress current session (preserves key context)
/compress
# Start a new session with a reference to the old one
hermes chat
# Resume a specific session later if needed
hermes chat --continue
MCP 问题
MCP 服务器无法连接
原因: 服务器二进制文件未找到、命令路径错误,或缺少运行时环境。
解决方案:
# Ensure MCP dependencies are installed (already included in standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
# For npm-based servers, ensure Node.js is available
node --version
npx --version
# Test the server manually
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 能力。
解决方案:
- 检查网关/代理日志中是否存在 MCP 连接错误
- 确保服务器能够响应
tools/listRPC 方法 - 检查该服务器下的任何
tools.include、tools.exclude、tools.resources、tools.prompts或enabled设置 - 请注意,资源/提示工具仅在会话实际支持相应能力时才会注册
- 修改配置后使用
/reload-mcp
# Verify MCP servers are configured
hermes config show | grep -A 12 mcp_servers
# Restart Hermes or reload MCP after config changes
hermes chat
另请参阅:
MCP 超时错误
原因: MCP 服务器响应时间过长,或在执行过程中崩溃。
解决方案:
- 如果支持,可在 MCP 服务器配置中增加超时时间
- 检查 MCP 服务器进程是否仍在运行
- 对于远程 HTTP MCP 服务器,检查网络连接
如果 MCP 服务器在请求过程中崩溃,Hermes 将报告超时。请检查服务器自身的日志(而不仅仅是 Hermes 日志),以诊断根本原因。
配置文件(Profiles)
配置文件与直接设置 HERMES_HOME 有何不同?
配置文件是在 HERMES_HOME 之上的一个管理层。您当然可以手动在每次命令前设置 HERMES_HOME=/some/path,但配置文件会为您处理所有底层工作:创建目录结构、生成 shell 别名(hermes-work)、在 ~/.hermes/active_profile 中跟踪当前激活的配置文件,并自动在所有配置文件之间同步技能更新。它们还与 Tab 补全集成,您无需记住路径。
两个配置文件可以共享同一个机器人令牌吗?
不可以。每个消息平台(Telegram、Discord 等)都需要对机器人令牌的独占访问权限。如果两个配置文件同时尝试使用相同的令牌,第二个网关将无法连接。请为每个配置文件创建独立的机器人——对于 Telegram,可联系 @BotFather 创建额外的机器人。
配置文件之间是否共享内存或会话?
不共享。每个配置文件都有自己的内存存储、会话数据库和技能目录。它们完全隔离。如果您希望创建一个带有现有记忆和会话的新配置文件,可以使用 hermes profile create newname --clone-all 从当前配置文件复制所有内容。
运行 hermes update 会发生什么?
hermes update 会拉取最新代码并重新安装依赖项 一次(不是每个配置文件都执行一次)。然后它会自动将更新的技能同步到所有配置文件。您只需运行一次 hermes update —— 它将覆盖机器上所有配置文件。
我可以将配置文件移动到另一台机器上吗?
可以。将配置文件导出为可移植的归档文件,并在另一台机器上导入:
# On the source machine
hermes profile export work ./work-backup.tar.gz
# Copy the file to the target machine, then:
hermes profile import ./work-backup.tar.gz work
导入的配置文件将包含导出时的所有配置、记忆、会话和技能。如果新机器的设置不同,您可能需要更新路径或重新认证与服务提供商的连接。
我可以运行多少个配置文件?
没有硬性限制。每个配置文件只是 ~/.hermes/profiles/ 下的一个目录。实际限制取决于您的磁盘空间以及系统能处理的并发网关数量(每个网关是一个轻量级 Python 进程)。运行数十个配置文件是完全可行的;每个空闲配置文件不消耗任何资源。
工作流与模式
为不同任务使用不同模型(多模型工作流)
场景: 您日常使用 GPT-5.4,但 Gemini 或 Grok 在撰写社交媒体内容方面表现更佳。每次手动切换模型非常繁琐。
解决方案:委托配置(Delegation config)。Hermes 可以自动将子代理路由到不同的模型。您可以在 ~/.hermes/config.yaml 中进行设置:
delegation:
model: "google/gemini-3-flash-preview" # subagents use this model
provider: "openrouter" # provider for subagents
现在当你告诉 Hermes “帮我写一篇关于 X 的 Twitter 帖子”时,它会启动一个 delegate_task 子代理,该子代理在 Gemini 上运行,而不是在你的主模型上。你的主要对话仍保留在 GPT-5.4 上。
你也可以在提示中明确表达:“将任务委托给撰写关于我们产品发布社交媒体帖子。使用你的子代理来实际撰写。” 该代理会使用 delegate_task,它会自动加载委托配置。
对于无需委托的一次性模型切换,可在 CLI 中使用 /model 命令:
/model google/gemini-3-flash-preview # switch for this session
# ... write your content ...
/model openai/gpt-5.4 # switch back
有关委托机制的更多详情,请参阅 子代理委托。
在一个 WhatsApp 号码上运行多个代理(按聊天绑定)
场景: 在 OpenClaw 中,你可以将多个独立的代理绑定到特定的 WhatsApp 聊天——一个用于家庭购物清单群组,另一个用于你的私人聊天。Hermes 能否做到这一点?
当前限制: Hermes 的每个配置文件都需要独立的 WhatsApp 号码/会话。你无法将多个配置文件绑定到同一 WhatsApp 号码的不同聊天——WhatsApp 桥接器(Baileys)每个号码仅支持一个已认证的会话。
替代方案:
-
使用单个配置文件配合人格切换。 创建不同的
AGENTS.md上下文文件,或使用/personality命令来按聊天切换行为。代理会识别自己所在的聊天并相应调整。 -
使用定时任务(cron job)处理专项任务。 例如,为购物清单追踪器设置一个 cron 任务,监控特定聊天并管理清单——无需额外的代理。
-
使用独立号码。 如果你需要真正独立的代理,可为每个配置文件配对一个独立的 WhatsApp 号码。Google Voice 等虚拟号码服务可满足此需求。
-
改用 Telegram 或 Discord。 这些平台更自然地支持按聊天绑定——每个 Telegram 群组或 Discord 频道都有独立会话,你可以在同一账户上运行多个机器人令牌(每个配置文件一个)。
更多详情请参阅 配置文件 和 WhatsApp 设置。
控制 Telegram 中显示的内容(隐藏日志和推理过程)
场景: 你在 Telegram 中看到网关执行日志、Hermes 的推理过程以及工具调用详情,而不仅仅是最终输出。
解决方案: config.yaml 中的 display.tool_progress 设置控制显示多少工具活动:
display:
tool_progress: "off" # options: off, new, all, verbose
off— 仅显示最终响应。不显示工具调用、推理过程或日志。new— 在工具调用发生时显示新调用(简短的一行)。all— 显示所有工具活动,包括结果。verbose— 完整细节,包括工具参数和输出。
对于消息平台,通常建议使用 off 或 new。修改 config.yaml 后,需重启网关以使更改生效。
你也可以通过 /verbose 命令(若已启用)在会话级别切换此设置:
display:
tool_progress_command: true # enables /verbose in the gateway
在 Telegram 上管理技能(斜杠命令数量限制)
场景: Telegram 的斜杠命令数量限制为 100 个,而你的技能数量已接近或超过该限制。你希望在 Telegram 上禁用不需要的技能,但 hermes skills config 的设置似乎未生效。
解决方案: 使用 hermes skills config 按平台禁用技能。这会写入 config.yaml:
skills:
disabled: [] # globally disabled skills
platform_disabled:
telegram: [skill-a, skill-b] # disabled only on telegram
更改后,必须重启网关(运行 hermes gateway restart 或终止并重新启动)。Telegram 机器人的命令菜单会在启动时重建。
在 Telegram 菜单中,描述过长的技能会被截断为 40 个字符,以符合负载大小限制。如果技能未显示,可能并非因为达到 100 条命令的限制,而是总负载大小超限——禁用未使用的技能可同时解决此问题。
共享线程会话(多人共用一个对话)
场景: 你在 Telegram 或 Discord 的一个线程中,多人提及机器人。你希望所有提及都属于同一个共享对话,而不是为每个用户创建独立会话。
当前行为: 在大多数平台上,Hermes 会根据用户 ID 键控会话,因此每个人都有自己的对话上下文。这是出于隐私和上下文隔离的设计考虑。
替代方案:
-
使用 Slack。 Slack 会话按线程键控,而非用户。同一线程中的多个用户共享一个对话——这正是你所描述的行为。这是最自然的解决方案。
-
使用群聊并指定单一用户作为“操作员”。 由一人负责转达问题,会话保持统一。其他人可阅读并参与。
-
使用 Discord 频道。 Discord 会话按频道键控,因此同一频道中的所有用户共享上下文。为共享对话创建专用频道即可。
将 Hermes 导出到另一台机器
场景: 你在一台机器上已构建了技能、定时任务和记忆数据,现在希望将所有内容迁移到新的专用 Linux 服务器上。
解决方案:
-
在新机器上安装 Hermes Agent:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -
将整个
~/.hermes/目录复制到新机器上,但不包括hermes-agent子目录(该目录是代码仓库——新安装会自带自己的版本):# On the source machine
rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/或使用配置文件导出/导入功能:
# On source machine
hermes profile export default ./hermes-backup.tar.gz
# On target machine
hermes profile import ./hermes-backup.tar.gz default -
在新机器上运行
hermes setup,以验证 API 密钥和提供者配置是否正常工作。重新认证任何消息平台(尤其是 WhatsApp,它使用二维码配对)。
~/.hermes/ 目录包含所有内容:config.yaml、.env、SOUL.md、memories/、skills/、state.db(会话数据)、cron/ 以及任何自定义插件。代码本身位于 ~/.hermes/hermes-agent/,并会进行全新安装。
安装后重新加载 shell 时出现权限被拒绝
场景: 运行 Hermes 安装程序后,执行 source ~/.zshrc 时出现权限被拒绝错误。
原因: 这通常是因为 ~/.zshrc(或 ~/.bashrc)文件权限设置不正确,或者安装程序无法干净地写入该文件。这不是 Hermes 特有的问题——而是 shell 配置文件权限问题。
解决方案:
# Check permissions
ls -la ~/.zshrc
# Fix if needed (should be -rw-r--r-- or 644)
chmod 644 ~/.zshrc
# Then reload
source ~/.zshrc
# Or just open a new terminal window — it picks up PATH changes automatically
如果安装程序已添加 PATH 行但权限错误,可以手动添加:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
首次运行代理时出现 400 错误
场景: 设置过程顺利完成,但首次聊天尝试失败,返回 HTTP 400 错误。
原因: 通常是模型名称不匹配——配置的模型在你的提供者处不存在,或 API 密钥无权访问该模型。
解决方案:
# Check what model and provider are configured
hermes config show | head -20
# Re-run model selection
hermes model
# Or test with a known-good model
hermes chat -q "hello" --model anthropic/claude-sonnet-4.6
如果使用 OpenRouter,请确保你的 API 密钥有余额。OpenRouter 返回 400 错误通常意味着该模型需要付费计划,或模型 ID 存在拼写错误。
仍然遇到问题?
如果您的问题未在此处涵盖:
- 搜索现有问题: GitHub Issues
- 向社区提问: Nous Research Discord
- 提交错误报告: 请附上您的操作系统信息、Python 版本(
python3 --version)、Hermes 版本(hermes --version)以及完整的错误信息