FAQ 与故障排除
常见问题的快速解答和修复方案。
常见问题
哪些 LLM 提供商可与 Hermes 配合使用？
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 / 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 现在拥有针对 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 wheel。请改用已验证的 .[termux] 扩展包。
我的数据会被发送到别处吗？
API 调用只会发送到你配置的 LLM 提供商（例如 OpenRouter、你的本地 Ollama 实例）。Hermes Agent 不收集遥测、使用数据或分析信息。你的对话、记忆和技能都存储在本地 ~/.hermes/ 中。
可以离线使用 / 配合本地模型吗？
可以。运行 hermes model，选择自定义端点，然后输入你的服务器 URL：
hermes model
# 选择：Custom endpoint (enter URL manually)
# 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 会将端点、提供商和基础 URL 持久化到 config.yaml，重启后依然有效。这适用于 Ollama、vLLM、llama.cpp server、SGLang、LocalAI 等。详情请参阅配置指南。
:::tip Ollama 用户
如果你在 Ollama 中设置了自定义 num_ctx（例如 ollama run --num_ctx 16384），请确保在 Hermes 中设置匹配的上下文长度——Ollama 的 /api/show 报告的是模型最大上下文，不是你配置的 num_ctx。
:::tip 本地模型超时
Hermes 会自动检测本地端点并放宽流式超时（读取超时从 120s 提升到 1800s，过期流检测关闭）。如果在极大上下文下仍遇到超时，请在
.env 中设置
HERMES_STREAM_READ_TIMEOUT=1800。
使用成本是多少？
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="anthropic/claude-opus-4.7")
response = agent.chat("简要解释量子计算")
完整 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，那 /model 就只会显示 OpenRouter。
解决： 先退出会话，在终端中使用 hermes model 添加新提供商：
# 先退出 Hermes 聊天会话（Ctrl+C 或 /quit）
# 运行完整提供商设置向导
hermes model
# 这会允许你：添加提供商、运行 OAuth、输入 API 密钥、配置端点
通过 hermes model 添加新提供商后，开始新的聊天会话——/model 现在会显示所有已配置的提供商。
:::tip 快速参考
| 想要…… | 使用 |
|-----------|-----|
| 添加新提供商 | hermes model（从终端运行） |
| 输入/更改 API 密钥 | hermes model（从终端运行） |
| 会话中切换模型 | /model <名称>（在会话内） |
| 切换到不同的已配置提供商 | /model provider:model（在会话内） |
API 密钥无效
原因： 密钥缺失、过期、设置错误或属于错误提供商。
解决：
# 检查配置
hermes config show
# 重新配置提供商
hermes model
# 或直接设置
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx
确保密钥与提供商匹配。OpenAI 密钥无法在 OpenRouter 上使用，反之亦然。检查 `~/.hermes/.env` 中是否有冲突的条目。
模型不可用 / 找不到模型
原因： 模型标识符错误，或你的提供商上没有该模型。
解决：
# 列出提供商的可用模型
hermes model
# 设置有效模型
hermes config set HERMES_MODEL anthropic/claude-opus-4.7
# 或按会话指定
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
消息网关问题
机器人不回复消息
原因： 机器人未运行、未授权，或你的用户不在白名单中。
解决：
# 检查网关是否运行
hermes gateway status
# 启动网关
hermes gateway start
# 检查日志中的错误
cat ~/.hermes/logs/gateway.log | tail -50
消息无法送达
原因： 网络问题、机器人令牌过期或平台 webhook 配置错误。
解决：
- 使用 hermes gateway setup 验证机器人令牌是否有效
- 检查网关日志：cat ~/.hermes/logs/gateway.log | tail -50
- 对于基于 webhook 的平台（Slack、WhatsApp），确保服务器可公开访问
白名单困惑——谁可以和机器人对话？
原因： 授权模式决定了谁能获得访问权限。
解决：
| 模式 |
工作原理 |
| 白名单 |
只有配置中列出的用户 ID 可以交互 |
| DM 配对 |
第一个在私信中发消息的用户获得独占访问权 |
| 开放 |
任何人都可以交互（生产环境不推荐） |
在 ~/.hermes/config.yaml 中配置网关设置。请参阅消息文档。
网关无法启动
原因： 缺少依赖、端口冲突或令牌配置错误。
解决：
# 安装消息依赖
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（不存在则创建）
- 添加：
ini
[boot]
systemd=true
- 从 PowerShell 执行：
wsl --shutdown
- 重新打开 WSL 终端
- 验证：
systemctl is-system-running 应显示 "running" 或 "degraded"
:::tip Windows 开机自动启动
如需可靠的自动启动，使用 Windows 任务计划程序在登录时启动 WSL + 网关：
1. 创建任务，运行 wsl -d Ubuntu -- bash -lc 'hermes gateway run'
2. 设置为在用户登录时触发
性能问题
响应慢
原因： 模型大、API 服务器远或系统提示词重、工具多。
解决：
- 尝试更快/更小的模型：hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct
- 减少活跃工具集：hermes chat -t "terminal"
- 检查到提供商的网络延迟
- 本地模型请确保 GPU 显存充足
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 工具未显示
原因： 服务器已启动但工具发现失败、工具被配置过滤掉，或服务器不支持你期望的功能。
解决：
- 检查网关/Agent 日志中的 MCP 连接错误
- 确保服务器响应 tools/list RPC 方法
- 检查该服务器下的 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 日志）来诊断根本原因。
仍有问题？
如果你的问题未在此处涵盖：
- 搜索现有 issue： GitHub Issues
- 询问社区： Nous Research Discord
- 提交 bug 报告： 包含你的操作系统、Python 版本（
python3 --version）、Hermes 版本（hermes --version）和完整错误信息