跳到主要内容

FAQ 与故障排查

这里汇总了最常见问题的快速答案与修复方法。

常见问题​

Hermes 支持哪些 LLM provider？​

Hermes Agent 可以接入任何兼容 OpenAI 的 API。常见可用 provider 包括：

  • OpenRouter —— 一个 API key 访问数百个模型（灵活性最高，推荐）
  • 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 配置 provider，也可以直接编辑 ~/.hermes/.env。所有 provider 相关 key 请参阅 Environment Variables。

能在 Windows 上运行吗？​

不能原生运行。 Hermes Agent 需要类 Unix 环境。在 Windows 上请安装 WSL2，然后在 WSL 内运行 Hermes。标准安装命令在 WSL2 中可以直接使用：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

能在 Android / Termux 上运行吗？​

可以。Hermes 现在已有经过验证的 Termux 安装路径。

快速安装：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

如果你想看完整手动步骤、支持的额外依赖和当前限制，请参阅 Termux guide。

需要注意：Android 当前不支持完整的 .[all] extra，因为 voice extra 依赖 faster-whisper -> ctranslate2，而 ctranslate2 没有提供 Android wheel。请使用已验证的 .[termux] extra。

我的数据会被发送到哪里？​

API 调用只会发送给你自己配置的 LLM provider（例如 OpenRouter 或你本地的 Ollama 实例）。Hermes Agent 不收集遥测、使用统计或分析数据。你的对话、记忆和技能都保存在本地 ~/.hermes/ 下。

可以离线使用 / 接本地模型吗？​

可以。运行 hermes model，选择 Custom endpoint，然后输入你本地服务的 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 会把 endpoint、provider 和 base URL 持久化到 config.yaml，所以重启后依然有效。如果你的本地服务只加载了一个模型，/model custom 还可以自动识别它。你也可以直接在 config.yaml 中写 provider: custom，它是正式 provider，不是别名。

这适用于 Ollama、vLLM、llama.cpp server、SGLang、LocalAI 等。更多细节请见 Configuration guide。

Ollama users

如果你在 Ollama 里自定义了 num_ctx（例如 ollama run --num_ctx 16384），请务必在 Hermes 里填入匹配的 context length。因为 Ollama 的 /api/show 返回的是模型理论最大上下文，不一定是你当前实际设置的 num_ctx。

Timeouts with local models

Hermes 会自动识别本地 endpoint，并放宽流式超时（read timeout 从 120s 提高到 1800s，同时关闭 stale stream detection）。如果你在超大上下文下仍然遇到超时，请在 .env 中设置 HERMES_STREAM_READ_TIMEOUT=1800。详见 Local LLM guide。

使用成本是多少？​

Hermes Agent 本身是免费开源的（MIT 许可证）。你只需要支付所选 provider 的 LLM API 使用成本。本地模型则完全免费。

多个人能共用一个实例吗？​

可以。messaging gateway 允许多位用户通过 Telegram、Discord、Slack、WhatsApp 或 Home Assistant 访问同一个 Hermes Agent 实例。访问控制通过 allowlist（指定用户 ID）和 DM pairing（第一个私信用户获取访问权）完成。

memory 和 skills 的区别是什么？​

  • Memory 保存的是事实 —— agent 知道的关于你、你的项目和偏好的信息。记忆会根据相关性自动检索
  • Skills 保存的是过程 —— 如何完成某件事的步骤说明。遇到相似任务时，agent 会调出对应技能

二者都会跨会话持久存在。详见 Memory 和 Skills。

可以在自己的 Python 项目里调用 Hermes 吗？​

可以。你可以导入 AIAgent 类，以编程方式使用 Hermes：

from run_agent import AIAgent

agent = AIAgent(model="anthropic/claude-opus-4.7")
response = agent.chat("Explain quantum computing briefly")

完整 API 用法请参阅 Python Library guide。

故障排查​

安装问题​

安装后提示 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

如果你是用官方安装脚本安装，脚本会自动处理；只有在手动安装时才常见碰到这个错误。

终端里提示 node: command not found（或 nvm、pyenv、asdf 等）​

原因： Hermes 会在启动时运行一次 bash -l 来构建每个会话的环境快照。bash login shell 会读取 /etc/profile、~/.bash_profile 和 ~/.profile，但不会自动 source ~/.bashrc。因此，那些把自己安装到 ~/.bashrc 里的工具（如 nvm、asdf、pyenv、cargo，或自定义 PATH）就不会进入快照。这在 systemd 或极简 shell 环境下尤其常见。

解决方法： Hermes 默认会自动 source ~/.bashrc。如果这还不够，比如你是 zsh 用户、PATH 写在 ~/.zshrc，或者你把 nvm 单独放在其它脚本里，可以在 ~/.hermes/config.yaml 中显式声明额外初始化文件：

terminal:
  shell_init_files:
    - ~/.zshrc
    - ~/.nvm/nvm.sh
    - /etc/profile.d/cargo.sh
  # When this list is set, the default ~/.bashrc auto-source is NOT added —
  # include it explicitly if you want both:
  #   - ~/.bashrc
  #   - ~/.zshrc

不存在的文件会被静默跳过。注意这些文件是在 bash 中执行的，所以如果某个文件依赖 zsh 专属语法，可能会报错。遇到这种情况，建议只 source 设置 PATH 的那部分脚本，而不是整份 rc 文件。

如果你想彻底关闭自动 source ~/.bashrc 的行为：

terminal:
  auto_source_bashrc: false

uv: command not found​

原因： uv 没安装，或者不在 PATH 中。

解决方法：

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

安装时出现 permission denied​

原因： 当前用户对安装目录没有写权限。

解决方法：

# 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

Provider 与模型问题​

/model 里只显示一个 provider / 无法切换 provider​

原因： 会话里的 /model 只能切换你已经配置过的 provider。如果你只配过 OpenRouter，那它就只会显示 OpenRouter。

解决方法： 退出当前会话，然后在终端里运行 hermes model 添加新 provider：

# Exit the Hermes chat session first (Ctrl+C or /quit)

# Run the full provider setup wizard
hermes model

通过 hermes model 添加完新的 provider 后，再开启新会话，/model 就会显示所有已配置 provider。

API key 不工作​

原因： key 缺失、过期、配置错误，或者和 provider 不匹配。

解决方法：

# 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
注意

请确认 key 和 provider 一一对应。OpenAI 的 key 不能拿去接 OpenRouter，反过来也不行。还要检查 ~/.hermes/.env 里是否有互相冲突的配置项。

Model not available / model not found​

原因： 模型标识符写错，或者该模型在你的 provider 上不可用。

解决方法：

# List available models for your provider
hermes model

# Set a valid model
hermes config set HERMES_MODEL anthropic/claude-opus-4.7

# Or specify per-session
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct

429 限流错误​

原因： 你超过了 provider 的速率限制。

解决方法： 稍等片刻后重试。长期来看可以考虑：

  • 升级 provider 套餐
  • 切换到其它模型或 provider
  • 使用 hermes chat --provider <alternative> 路由到不同后端

Context length exceeded​

原因： 对话太长，超过了模型上下文窗口；或者 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 启动行会显示当前识别出的上下文上限，你也可以在会话中用 /usage 查看。

要显式修正它，可以在 config.yaml 里写：

model:
  default: your-model-name
  context_length: 131072

对于自定义 endpoint，也可以按模型单独设置：

custom_providers:
  - name: "My Server"
    base_url: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 32768

自动检测机制及更多覆盖方式请参阅 Context Length Detection。

终端问题​

命令被判定为危险并被拦截​

原因： Hermes 识别到了潜在破坏性命令（例如 rm -rf、DROP TABLE）。这是安全机制的一部分。

解决方法： 在提示时仔细核对命令内容，确认无误后输入 y 批准。你也可以：

  • 让 agent 改用更安全的替代方案
  • 在 Security docs 中查看危险模式列表
提示

这是正常行为。Hermes 不会悄悄执行高破坏性命令。审批提示会明确告诉你它打算执行什么。

通过 messaging gateway 使用 sudo 不生效​

原因： messaging gateway 没有交互式终端，因此 sudo 无法弹密码提示。

解决方法：

  • 在消息平台里尽量避免 sudo，让 agent 先找替代办法
  • 如果必须用 sudo，就在 /etc/sudoers 中只对白名单命令启用 passwordless sudo
  • 或直接改用终端界面执行管理类任务：hermes chat

Docker backend 无法连接​

原因： Docker daemon 没启动，或者当前用户没有权限。

解决方法：

docker info
sudo usermod -aG docker $USER
newgrp docker
docker run hello-world

消息平台问题​

机器人不回复消息​

原因： 机器人没运行、未授权，或者你的用户不在 allowlist 中。

解决方法：

hermes gateway status
hermes gateway start

消息没有成功投递​

原因： 网络问题、bot token 失效，或者平台 webhook 配置错误。

解决方法：

  • 用 hermes gateway setup 验证 bot token
  • 检查 gateway 日志
  • 对 webhook 模式平台（如 Slack、WhatsApp），确认你的服务具备公网可达性

Allowlist 让人困惑：到底谁能跟 bot 对话？​

原因： 访问权限取决于你启用的授权模式。

解决方法：

ModeHow it works
Allowlist只有配置中列出的用户 ID 可以交互
DM pairing第一个私聊 bot 的用户会获得独占访问权
Open任何人都能交互（生产环境不推荐）

相关配置位于 ~/.hermes/config.yaml 中 gateway 对应平台段。详见 Messaging docs。

Gateway 启动不了​

原因： 依赖缺失、端口冲突，或 token 配置错误。

解决方法：

pip install "hermes-agent[telegram]"   # or [discord], [slack], [whatsapp]
lsof -i :8080
hermes config show

WSL：gateway 经常断开，或 hermes gateway start 失败​

原因： WSL 的 systemd 支持并不稳定。很多 WSL2 环境根本没有开启 systemd，即使开启了，服务也未必能跨 WSL 重启或 Windows 空闲挂起保持存活。

解决方法： 优先用前台模式，而不是 systemd service：

hermes gateway run
tmux new -s hermes 'hermes gateway run'
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &

如果你坚持尝试 systemd，请确保它已开启，并通过 systemctl is-system-running 验证。

macOS：gateway 找不到 Node.js / ffmpeg / 其它工具​

原因： launchd 服务继承的是一个极简 PATH（/usr/bin:/bin:/usr/sbin:/sbin），其中没有 Homebrew、nvm、cargo 等用户安装路径，因此很容易导致 WhatsApp bridge 找不到 node，或语音转写找不到 ffmpeg。

解决方法： hermes gateway install 会在安装时捕获当前 shell 的 PATH。如果你是在安装 gateway 之后才安装这些工具，请重新执行：

hermes gateway install
hermes gateway start

性能问题​

回复很慢​

原因： 模型太大、API 服务距离太远，或系统提示过重、工具集太多。

解决方法：

  • 试试更快 / 更小的模型
  • 缩减启用工具集
  • 检查你到 provider 的网络延迟
  • 如果使用本地模型，确认 GPU / VRAM 足够

Token 用量太高​

原因： 长对话、过于冗长的系统提示，或者大量工具调用不断累积上下文。

解决方法：

/compress
/usage

会话越来越长​

原因： 长时间对话持续累积消息和工具输出，逐步逼近上下文上限。

解决方法：

/compress
hermes chat
hermes chat --continue

MCP 问题​

MCP server 连接不上​

原因： server 二进制不存在、命令路径错误，或缺少运行时。

解决方法：

cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
node --version
npx --version
npx -y @modelcontextprotocol/server-filesystem /tmp

并确认 ~/.hermes/config.yaml 中 MCP 配置正确。

来自 MCP server 的工具没有出现​

原因： server 启动了，但工具发现失败；工具被配置过滤掉了；或者 server 并不支持你以为它支持的 MCP capability。

解决方法：

  • 查看 gateway / agent 日志里的 MCP 连接错误
  • 确认 server 能响应 tools/list
  • 检查 tools.include、tools.exclude、tools.resources、tools.prompts、enabled 等配置
  • 修改配置后执行 /reload-mcp

MCP 超时错误​

原因： MCP server 响应太慢，或者执行中崩溃。

解决方法：

  • 如果配置支持，调大超时时间
  • 确认 MCP server 进程仍在运行
  • 如果是远端 HTTP MCP server，检查网络连通性
注意

如果 MCP server 在请求中途崩溃，Hermes 通常会报告 timeout。此时需要检查的是 MCP server 自己的日志，而不只是 Hermes 日志。

Profiles​

Profile 和手动设置 HERMES_HOME 有什么区别？​

Profile 是建立在 HERMES_HOME 之上的一层受管抽象。你当然可以在每次执行前手动设置 HERMES_HOME=/some/path，但 profile 会自动帮你处理目录结构、shell alias（如 hermes-work）、当前激活 profile 记录，以及跨 profile 的技能同步更新。

两个 profile 能共用同一个 bot token 吗？​

不能。每个消息平台（Telegram、Discord 等）都要求独占 bot token。如果两个 profile 同时尝试使用同一个 token，后启动的 gateway 会连接失败。应为每个 profile 单独创建机器人。

不同 profile 会共享 memory 或 session 吗？​

不会。每个 profile 都有自己的记忆存储、session 数据库和技能目录，彼此完全隔离。如果你想从已有 profile 复制全部记忆与会话，可以使用 hermes profile create newname --clone-all。

运行 hermes update 会发生什么？​

hermes update 会只更新一次代码和依赖（不是每个 profile 都单独更新），然后自动把更新后的技能同步到所有 profile。也就是说，一台机器上只需要执行一次。

可以把 profile 搬到另一台机器吗？​

可以。先导出成归档，再到另一台机器导入：

hermes profile export work ./work-backup.tar.gz
hermes profile import ./work-backup.tar.gz work

导入后会带上配置、记忆、会话和技能，但如果新机器环境不同，你可能仍需调整路径或重新认证 provider。

最多能跑多少个 profile？​

没有硬上限。每个 profile 本质上只是 ~/.hermes/profiles/ 下的一个目录。实际限制取决于磁盘空间，以及你的系统能同时承载多少 gateway 进程。

工作流与模式​

不同任务使用不同模型（多模型工作流）​

场景： 你平时主力使用 GPT-5.4，但 Gemini 或 Grok 在社交媒体文案上表现更好。每次手动切换模型很麻烦。

解决方案： 使用 delegation config，让子 agent 自动走另一个模型：

delegation:
  model: "google/gemini-3-flash-preview"
  provider: "openrouter"

这样，当 Hermes 为你启动 delegate_task 子 agent 时，它就会自动使用 Gemini，而主会话仍然留在 GPT-5.4 上。

一台 WhatsApp 号码上跑多个 agent​

当前限制： Hermes 的每个 profile 都需要自己独立的 WhatsApp 号码 / 会话。不能像 OpenClaw 那样在同一号码下把不同 profile 绑定到不同聊天。

替代方案：

  1. 用单一 profile，结合 AGENTS.md 或 /personality 按聊天切换风格
  2. 用 cron jobs 做专用任务
  3. 使用多个不同号码
  4. 改用 Telegram 或 Discord，这些平台更自然支持按聊天隔离

控制 Telegram 中显示的内容（隐藏日志与推理）​

场景： 你在 Telegram 中看到的是 gateway 执行日志、Hermes 推理和工具调用细节，而不是简洁的最终回复。

解决方案： 用 config.yaml 中的 display.tool_progress 控制显示粒度：

display:
  tool_progress: "off"
  • off：只显示最终回复
  • new：显示新工具调用的简短一行状态
  • all：显示所有工具活动及结果
  • verbose：显示工具参数与输出的完整细节

消息平台一般推荐 off 或 new。改完 config.yaml 后，需要重启 gateway。

在 Telegram 上管理技能（slash command 数量上限）​

场景： Telegram 只有 100 个 slash command 限额，而你的技能太多了。

解决方案： 用 hermes skills config 按平台禁用技能，它会把配置写入 config.yaml：

skills:
  disabled: []
  platform_disabled:
    telegram: [skill-a, skill-b]

修改后必须重启 gateway，Telegram 的命令菜单只会在启动时重建。

共享线程会话（多人同一上下文）​

当前行为： Hermes 在大多数平台上按用户 ID 划分 session，因此每个人都有自己的独立上下文。

替代方案：

  1. 使用 Slack，Slack 是按 thread 组织 session
  2. 在群聊里由一个“操作员”统一转述问题
  3. 使用 Discord channel，Discord 是按频道共享上下文

把 Hermes 整体迁移到另一台机器​

  1. 在新机器上安装 Hermes
  2. 复制整个 ~/.hermes/，但排除 hermes-agent 子目录
  3. 在新机器上运行 hermes setup 验证 API key 与 provider

你也可以直接用 profile export / import。

安装后 reload shell 出现 permission denied​

原因： 通常是 ~/.zshrc 或 ~/.bashrc 权限错误，不是 Hermes 特有问题。

解决方法：

ls -la ~/.zshrc
chmod 644 ~/.zshrc
source ~/.zshrc

首次运行 agent 报 400​

原因： 往往是模型名与 provider 不匹配，或者 API key 没有该模型权限。

解决方法：

hermes config show
hermes model
hermes chat -q "hello" --model anthropic/claude-opus-4.7

如果你使用 OpenRouter，也请确认账户有余额。有时 OpenRouter 返回 400，只是因为该模型需要付费套餐，或模型 ID 写错。

仍然没解决？​

如果你的问题不在这里：

  1. 搜索已有 issues： GitHub Issues
  2. 向社区提问： Nous Research Discord
  3. 提交 bug 报告： 请附上你的操作系统、Python 版本（python3 --version）、Hermes 版本（hermes --version）以及完整错误信息