跳到主要内容

常见问题与故障排除

快速解答最常见的问题和解决方法。


常见问题

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 — 全球及中国端点
  • 本地模型 — 通过 OllamavLLMllama.cppSGLang 或任何兼容 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-whisperctranslate2,而 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 用户

如果您在 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 -rfDROP 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/list RPC 方法
  • 检查该服务器下的任何 tools.includetools.excludetools.resourcestools.promptsenabled 设置
  • 请注意,资源/提示工具仅在会话实际支持相应能力时才会注册
  • 修改配置后使用 /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)每个号码仅支持一个已认证的会话。

替代方案:

  1. 使用单个配置文件配合人格切换。 创建不同的 AGENTS.md 上下文文件,或使用 /personality 命令来按聊天切换行为。代理会识别自己所在的聊天并相应调整。

  2. 使用定时任务(cron job)处理专项任务。 例如,为购物清单追踪器设置一个 cron 任务,监控特定聊天并管理清单——无需额外的代理。

  3. 使用独立号码。 如果你需要真正独立的代理,可为每个配置文件配对一个独立的 WhatsApp 号码。Google Voice 等虚拟号码服务可满足此需求。

  4. 改用 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 — 完整细节,包括工具参数和输出。

对于消息平台,通常建议使用 offnew。修改 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 键控会话,因此每个人都有自己的对话上下文。这是出于隐私和上下文隔离的设计考虑。

替代方案:

  1. 使用 Slack。 Slack 会话按线程键控,而非用户。同一线程中的多个用户共享一个对话——这正是你所描述的行为。这是最自然的解决方案。

  2. 使用群聊并指定单一用户作为“操作员”。 由一人负责转达问题,会话保持统一。其他人可阅读并参与。

  3. 使用 Discord 频道。 Discord 会话按频道键控,因此同一频道中的所有用户共享上下文。为共享对话创建专用频道即可。

将 Hermes 导出到另一台机器

场景: 你在一台机器上已构建了技能、定时任务和记忆数据,现在希望将所有内容迁移到新的专用 Linux 服务器上。

解决方案:

  1. 在新机器上安装 Hermes Agent:

    curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
  2. 将整个 ~/.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
  3. 在新机器上运行 hermes setup,以验证 API 密钥和提供者配置是否正常工作。重新认证任何消息平台(尤其是 WhatsApp,它使用二维码配对)。

~/.hermes/ 目录包含所有内容:config.yaml.envSOUL.mdmemories/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 存在拼写错误。


仍然遇到问题?

如果您的问题未在此处涵盖:

  1. 搜索现有问题: GitHub Issues
  2. 向社区提问: Nous Research Discord
  3. 提交错误报告: 请附上您的操作系统信息、Python 版本(python3 --version)、Hermes 版本(hermes --version)以及完整的错误信息