常见问题与故障排除（FAQ & Troubleshooting）

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

常见问题（Frequently Asked Questions）

Hermes 支持哪些 LLM 提供商？

Hermes Agent 兼容任何 OpenAI 兼容的 API。支持的提供商包括：

OpenRouter — 通过一个 API 密钥访问数百个模型（推荐，灵活性最佳）
Nous Portal — Nous Research 自有推理端点
OpenAI — GPT-5.4、GPT-5-codex、GPT-4.1、GPT-4o 等
Anthropic — Claude 模型（直接 API、通过 hermes login anthropic 的 OAuth、OpenRouter 或任何兼容代理）
Google — Gemini 模型（通过 gemini 提供商的直接 API、google-gemini-cli OAuth 提供商、OpenRouter 或兼容代理）
z.ai / 智谱AI（ZhipuAI） — GLM 模型
Kimi / 月之暗面（Moonshot AI） — Kimi 模型
MiniMax — 全球和中国端点
本地模型（Local models） — 通过 Ollama、vLLM、llama.cpp、SGLang 或任何兼容 OpenAI 的服务器

通过 hermes model 或编辑 ~/.hermes/.env 设置提供商。所有提供商密钥请参阅环境变量（Environment Variables）参考。

可以在 Windows 上运行吗？

不能原生运行。 Hermes Agent 需要类 Unix 环境。在 Windows 上，请安装 WSL2 并在其中运行 Hermes。标准安装命令在 WSL2 中完美运行：

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

我在 WSL2 中运行 Hermes。控制 Windows 原生 Chrome 的最佳方式是什么？

推荐使用 MCP 桥接而非 /browser connect。

推荐模式：

在 WSL2 中运行 Hermes
继续在 Windows 上使用您已登录的 Chrome
通过 cmd.exe 或 powershell.exe 添加 chrome-devtools-mcp 作为 MCP 服务器
让 Hermes 使用生成的 MCP 浏览器工具

这比尝试强制 Hermes 核心浏览器传输直接跨 WSL2/Windows 边界连接更可靠。

参见：

可以在 Android / Termux 上运行吗？

可以——Hermes 现在有经过测试的 Termux 安装路径，适用于 Android 手机。

快速安装：

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，选择自定义端点（Custom endpoint），然后输入您服务器的 URL：

hermes model
# 选择：Custom endpoint（手动输入 URL）
# API base URL: http://localhost:11434/v1
# API key: ollama
# 模型名称：qwen3.5:27b
# 上下文长度：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 服务器、SGLang、LocalAI 等。详情请参阅配置指南（Configuration guide）。

:::tip Ollama 用户提示如果您在 Ollama 中设置了自定义 num_ctx（例如 ollama run --num_ctx 16384），请确保在 Hermes 中设置匹配的上下文长度——Ollama 的 /api/show 报告的是模型的最大上下文，而非您配置的有效 num_ctx。 :::

:::tip 本地模型超时提示 Hermes 自动检测本地端点并放宽流式超时（读取超时从 120 秒提高到 1800 秒，禁用陈旧流检测）。如果您在处理非常大的上下文时仍然遇到超时，请在 .env 中设置 HERMES_STREAM_READ_TIMEOUT=1800。详情请参阅本地 LLM 指南。 :::

费用是多少？

Hermes Agent 本身是免费且开源的（MIT 许可证）。您只需为您选择的提供商产生的 LLM API 使用费用付费。本地模型完全免费运行。

多个人可以使用同一个实例吗？

可以。消息网关（messaging gateway）允许多个用户通过 Telegram、Discord、Slack、WhatsApp 或 Home Assistant 与同一个 Hermes Agent 实例交互。访问控制通过白名单（特定用户 ID）和 DM 配对（第一个发送消息的用户声明访问权限）进行管理。

记忆和技能有什么区别？

记忆（Memory） 存储事实——智能体了解的关于您、您的项目和偏好的信息。记忆根据相关性自动检索。
技能（Skills） 存储过程——如何做事的分步说明。当智能体遇到类似任务时会调用技能。

两者都跨会话持久保存。详情请参阅记忆（Memory）和技能（Skills）。

可以在自己的 Python 项目中使用吗？

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

from run_agent import AIAgent
 
agent = AIAgent(model="anthropic/claude-opus-4.7")
response = agent.chat("简要解释量子计算")

完整的 API 使用请参阅Python 库指南（Python Library guide）。

故障排除（Troubleshooting）

安装问题（Installation Issues）

安装后出现 `hermes: command not found`

原因： 您的 shell 尚未重新加载更新后的 PATH。

解决方案：

# 重新加载 shell 配置文件
source ~/.bashrc    # bash
source ~/.zshrc     # zsh
 
# 或者启动新的终端会话

如果仍然不行，请验证安装位置：

which hermes
ls ~/.local/bin/hermes

:::tip 安装程序将 ~/.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。

终端命令报 `node: command not found`（或 `nvm`、`pyenv`、`asdf` 等）

原因： Hermes 启动时通过运行 bash -l 构建会话级环境快照。bash 登录 shell 会读取 /etc/profile、~/.bash_profile 和 ~/.profile，但不会加载 ~/.bashrc——因此安装在那里的工具（nvm、asdf、pyenv、cargo、自定义 PATH 导出）对快照不可见。这在 Hermes 运行于 systemd 下或在没有任何预加载交互式 shell 配置的最小 shell 中最常见。

解决方案： Hermes 默认自动加载 ~/.bashrc。如果这还不够——例如您是 zsh 用户，PATH 在 ~/.zshrc 中，或者您从独立文件中初始化 nvm——请在 ~/.hermes/config.yaml 中列出要加载的额外文件：

terminal:
  shell_init_files:
    - ~/.zshrc                     # zsh 用户：将 zsh 管理的 PATH 拉入 bash 快照
    - ~/.nvm/nvm.sh                # 直接初始化 nvm（不依赖于 shell）
    - /etc/profile.d/cargo.sh      # 系统级 rc 文件
  # 设置了此列表后，默认的 ~/.bashrc 自动加载将不会添加——
  # 如果两者都需要，请显式包含：
  #   - ~/.bashrc
  #   - ~/.zshrc

缺失的文件会被静默跳过。加载在 bash 中进行，因此依赖 zsh 特有语法的文件可能会报错——如果担心这个问题，请只加载设置 PATH 的部分（例如直接加载 nvm 的 nvm.sh）而不是整个 rc 文件。

要禁用自动加载行为（仅严格登录 shell 语义）：

terminal:
  auto_source_bashrc: false

`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

提供商与模型问题（Provider & Model Issues）

`/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 <name>`（会话内部）
切换到不同的已配置提供商	`/model provider:model`（会话内部）
:::

API 密钥不工作

原因： 密钥缺失、过期、设置错误或针对错误的提供商。

解决方案：

# 检查您的配置
hermes config show
 
# 重新配置您的提供商
hermes model
 
# 或直接设置
hermes config set OPENROUTER_API_KEY sk-or-...xxxx

:::warning 确保密钥与提供商匹配。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 <alternative> 路由到不同的后端

超出上下文长度（Context length exceeded）

原因： 对话对于模型的上下文窗口来说变得过长，或者 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

有关自动检测的工作原理和所有覆盖选项，请参阅上下文长度检测（Context Length Detection）。

终端问题（Terminal Issues）

命令被拦截为危险操作

原因： Hermes 检测到可能具有破坏性的命令（例如 rm -rf、DROP TABLE）。这是一项安全功能。

解决方案： 在提示时，检查命令并输入 y 批准。您也可以：

要求智能体使用更安全的替代方案
查看安全文档（Security docs）中的完整危险模式列表

:::tip 这是设计使然——Hermes 永远不会静默运行破坏性命令。批准提示会准确显示将要执行的内容。 :::

通过消息网关时 `sudo` 不工作

原因： 消息网关在没有交互式终端的情况下运行，因此 sudo 无法提示输入密码。

解决方案：

避免在消息中使用 sudo——要求智能体寻找替代方案
如果必须使用 sudo，在 /etc/sudoers 中为特定命令配置无密码 sudo
或者切换到终端界面进行管理任务：hermes chat

Docker 后端无法连接

原因： Docker 守护进程未运行或用户缺少权限。

解决方案：

# 检查 Docker 是否运行
docker info
 
# 将您的用户添加到 docker 组
sudo usermod -aG docker $USER
newgrp docker
 
# 验证
docker run hello-world

消息问题（Messaging Issues）

机器人不响应消息

原因： 机器人未运行、未经授权或您的用户不在白名单中。

解决方案：

# 检查网关是否运行
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），确保您的服务器可公开访问

白名单混淆——谁可以和机器人对话？

原因： 授权模式决定了谁可以访问。

解决方案：

模式	工作原理
白名单（Allowlist）	只有配置中列出的用户 ID 可以交互
DM 配对（DM pairing）	第一个发送 DM 消息的用户声明独占访问
开放（Open）	任何人都可以交互（不建议用于生产环境）

在 ~/.hermes/config.yaml 的网关设置中配置。请参阅消息文档（Messaging docs）。

网关无法启动

原因： 缺少依赖、端口冲突或令牌配置错误。

解决方案：

# 安装核心消息网关依赖
pip install "hermes-agent[messaging]"  # Telegram、Discord、Slack 和共享网关依赖
 
# 检查端口冲突
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”

:::tip 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

性能问题（Performance Issues）

响应慢

原因： 模型较大、API 服务器距离较远，或带有许多工具的系统提示较重。

解决方案：

尝试更快/更小的模型：hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct
减少活动的工具集：hermes chat -t "terminal"
检查到提供商的网络延迟
对于本地模型，确保有足够的 GPU VRAM

高 Token 消耗

原因： 长对话、冗长的系统提示或多次工具调用累积上下文。

解决方案：

# 压缩对话以减少 token
/compress
 
# 检查会话 token 使用情况
/usage

:::tip 在长对话期间定期使用 /compress。它会总结对话历史，显著减少 token 消耗，同时保留上下文。 :::

会话过长

原因： 长时间对话积累消息和工具输出，接近上下文限制。

解决方案：

# 压缩当前会话（保留关键上下文）
/compress
 
# 引用旧会话启动新会话
hermes chat
 
# 稍后如果需要，恢复特定会话
hermes chat --continue

MCP 问题（MCP Issues）

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 能力。

解决方案：

检查网关/智能体日志中的 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 服务器，检查网络连接

:::warning 如果 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 一次——它覆盖机器上的每个配置文件。

我可以运行多少个配置文件？

没有硬性限制。每个配置文件只是 ~/.hermes/profiles/ 下的一个目录。实际限制取决于您的磁盘空间以及您的系统可以处理多少个并发网关（每个网关是一个轻量级 Python 进程）。运行几十个配置文件完全没问题；每个空闲配置文件不消耗任何资源。

工作流与模式（Workflows & Patterns）

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

场景： 您使用 GPT-5.4 作为日常驱动模型，但 Gemini 或 Grok 能写更好的社交媒体内容。每次都手动切换模型很麻烦。

解决方案：委托配置（Delegation config）。 Hermes 可以自动将子智能体路由到不同的模型。在 ~/.hermes/config.yaml 中设置：

delegation:
  model: "google/gemini-3-flash-preview"   # 子智能体使用此模型
  provider: "openrouter"                    # 子智能体的提供商

现在当您告诉 Hermes “写一条关于 X 的 Twitter 帖子” 并且它生成一个 delegate_task 子智能体时，该子智能体将在 Gemini 上运行而不是您的主模型。您的主对话仍然在 GPT-5.4 上。

您也可以在提示中显式指出：“委托一个任务来写关于我们产品发布的社交媒体帖子。让您的子智能体实际写作。” 智能体将使用 delegate_task，它自动拾取委托配置。

对于不使用委托的临时模型切换，在 CLI 中使用 /model：

/model google/gemini-3-flash-preview    # 为此会话切换
# ... 写您的内容 ...
/model openai/gpt-5.4                   # 切换回来

更多关于委托工作原理的信息，请参阅子智能体委托（Subagent Delegation）。

在一个 WhatsApp 号码上运行多个智能体（按聊天绑定）

场景： 在 OpenClaw 中，您有多个独立智能体绑定到特定的 WhatsApp 聊天——一个用于家庭购物清单群组，另一个用于您的私人聊天。Hermes 能做到吗？

当前限制： Hermes 的每个配置文件都需要自己的 WhatsApp 号码/会话。您无法将多个配置文件绑定到同一个 WhatsApp 号码的不同聊天上——WhatsApp 桥接（Baileys）每个号码使用一个经过身份验证的会话。

变通方案：

使用单一配置文件配合个性切换。 创建不同的 AGENTS.md 上下文文件或使用 /personality 命令按聊天更改行为。智能体会识别它所在的聊天并相应调整。
使用 cron 任务处理专用任务。 对于购物清单跟踪器，设置一个监控特定聊天并管理清单的 cron 任务——不需要单独的智能体。
使用不同的号码。 如果您需要真正独立的智能体，将每个配置文件与自己的 WhatsApp 号码配对。来自 Google Voice 等服务的虚拟号码可以用于此。
改用 Telegram 或 Discord。 这些平台更自然地支持按聊天绑定——每个 Telegram 群组或 Discord 频道获得自己的会话，您可以在同一个账户上运行多个机器人令牌（每个配置文件一个）。

更多详情请参阅配置文件（Profiles）和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 机器人命令菜单在启动时重建。

:::tip 描述过长的技能在 Telegram 菜单中会被截断为 40 个字符，以保持在负载大小限制内。如果技能未显示，可能是总负载大小问题而非 100 个命令计数限制——禁用不用的技能对两者都有帮助。 :::

共享线程会话（多个用户，一个对话）

场景： 您有一个 Telegram 或 Discord 线程，其中多人提及机器人。您希望该线程中的所有提及都是同一个共享对话的一部分，而不是每个用户单独的会话。

当前行为： 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 backup
```
这会创建您整个 ~/.hermes/ 目录的 zip 包——配置、API 密钥、记忆、技能、会话和配置文件——保存到您的主目录为 ~/hermes-backup-<timestamp>.zip。

将 zip 复制到新机器并导入：

# 在源机器上
scp ~/hermes-backup-<timestamp>.zip newmachine:~/
 
# 在新机器上
hermes import ~/hermes-backup-<timestamp>.zip

在新机器上运行 hermes setup 验证 API 密钥和提供商配置是否正常工作。

将单个配置文件移动到另一台机器

场景： 您想移动或分享一个特定的配置文件——不是整个安装。

# 在源机器上
hermes profile export work ./work-backup.tar.gz
 
# 将文件复制到目标机器，然后：
hermes profile import ./work-backup.tar.gz work

导入的配置文件将拥有导出时的所有配置、记忆、会话和技能。如果新机器有不同的设置，您可能需要更新路径或重新认证提供商。

`hermes backup` 与 `hermes profile export` 比较

特性	`hermes backup`	`hermes profile export`
使用场景	完整机器迁移	移植/分享特定配置文件
范围	全局（整个 `~/.hermes` 目录）	本地（单个配置文件目录）
包含	所有配置文件、全局配置、API 密钥、会话	单个配置文件：SOUL.md、记忆、会话、技能
凭据	包含（`.env` 和 `auth.json`）	排除（为安全分享已剥离）
格式	`.zip`	`.tar.gz`

手动备用方案（rsync）： 如果您更喜欢直接复制文件，请排除代码仓库：

rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/

:::tip 即使在 Hermes 主动运行时，hermes backup 也能生成一致的快照。恢复后的存档排除了机器本地的运行时文件，如 gateway.pid 和 cron.pid。 :::

安装后重新加载 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

首次运行智能体时出现错误 400

场景： 设置顺利完成，但第一次聊天尝试失败并返回 HTTP 400。

原因： 通常是模型名称不匹配——配置的模型在您的提供商上不存在，或者 API 密钥没有权限访问它。

解决方案：

# 检查配置的模型和提供商
hermes config show | head -20
 
# 重新运行模型选择
hermes model
 
# 或使用已知有效的模型测试
hermes chat -q "hello" --model anthropic/claude-opus-4.7

如果使用 OpenRouter，请确保您的 API 密钥有余额。OpenRouter 返回 400 通常意味着模型需要付费方案，或者模型 ID 有拼写错误。

仍有问题？

如果您的问题未在这里涵盖：

搜索已有问题： GitHub Issues
向社区提问： Nous Research Discord
提交错误报告： 包括您的操作系统、Python 版本（python3 --version）、Hermes 版本（hermes --version）以及完整的错误信息

好奇心花园🪴

探索

最近的笔记

note-template

getMoon.js

getWeather.js

常见问题与故障排除

常见问题与故障排除（FAQ & Troubleshooting）

常见问题（Frequently Asked Questions）

Hermes 支持哪些 LLM 提供商？

可以在 Windows 上运行吗？

我在 WSL2 中运行 Hermes。控制 Windows 原生 Chrome 的最佳方式是什么？

可以在 Android / Termux 上运行吗？

我的数据会被发送到其他地方吗？

可以在离线环境/使用本地模型吗？

费用是多少？

多个人可以使用同一个实例吗？

记忆和技能有什么区别？

可以在自己的 Python 项目中使用吗？

故障排除（Troubleshooting）

安装问题（Installation Issues）

安装后出现 hermes: command not found

Python 版本过旧

终端命令报 node: command not found（或 nvm、pyenv、asdf 等）

uv: command not found

安装过程中权限被拒绝

提供商与模型问题（Provider & Model Issues）

/model 只显示一个提供商 / 无法切换提供商

API 密钥不工作

模型不可用 / 找不到模型

速率限制（429 错误）

超出上下文长度（Context length exceeded）

终端问题（Terminal Issues）

命令被拦截为危险操作

通过消息网关时 sudo 不工作

Docker 后端无法连接

消息问题（Messaging Issues）

机器人不响应消息

消息无法投递

白名单混淆——谁可以和机器人对话？

网关无法启动

WSL：网关不断断开连接或 hermes gateway start 失败

macOS：Node.js / ffmpeg / 其他工具在网关中找不到

性能问题（Performance Issues）

响应慢

高 Token 消耗

会话过长

MCP 问题（MCP Issues）

MCP 服务器无法连接

MCP 服务器的工具未显示

MCP 超时错误

配置文件（Profiles）

配置文件与直接设置 HERMES_HOME 有何不同？

两个配置文件可以共享同一个机器人令牌吗？

配置文件共享记忆或会话吗？

运行 hermes update 会发生什么？

我可以运行多少个配置文件？

工作流与模式（Workflows & Patterns）

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

在一个 WhatsApp 号码上运行多个智能体（按聊天绑定）

控制 Telegram 中显示的内容（隐藏日志和推理过程）

在 Telegram 上管理技能（斜杠命令限制）

共享线程会话（多个用户，一个对话）

将 Hermes 导出到另一台机器

将单个配置文件移动到另一台机器

hermes backup 与 hermes profile export 比较

安装后重新加载 shell 时权限被拒绝

首次运行智能体时出现错误 400

仍有问题？

关系图谱

目录

反向链接

安装后出现 `hermes: command not found`

终端命令报 `node: command not found`（或 `nvm`、`pyenv`、`asdf` 等）

`uv: command not found`

`/model` 只显示一个提供商 / 无法切换提供商

通过消息网关时 `sudo` 不工作

WSL：网关不断断开连接或 `hermes gateway start` 失败

运行 `hermes update` 会发生什么？

`hermes backup` 与 `hermes profile export` 比较