跳到主要内容

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 wheels。请改用经过测试的 .[termux] 可选组件。

我的数据会被发送到任何地方吗？​

API 调用仅发送到你配置的 LLM 提供商（例如 OpenRouter、你本地的 Ollama 实例）。Hermes Agent 不收集遥测、使用数据或分析。你的对话、记忆和技能存储在本地 ~/.hermes/ 中。

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

可以。运行 hermes model，选择自定义端点，然后输入你服务器的 URL：

hermes model
# 选择：自定义端点（手动输入 URL）
# API 基础 URL：http://localhost:11434/v1
# API 密钥：ollama
# 模型名称：qwen3.5:27b
# 上下文长度：32768   ← 设置为与你服务器的实际上下文窗口匹配

或在 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 server、SGLang、LocalAI 等。请参阅配置指南了解详情。

Ollama 用户

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

本地模型超时

Hermes 自动检测本地端点并放宽流式传输超时（读取超时从 120s 提高到 1800s，禁用陈旧流检测）。如果你在非常大的上下文上仍然遇到超时，请在 .env 中设置 HERMES_STREAM_READ_TIMEOUT=1800。有关详细信息，请参阅本地 LLM 指南。

它要花多少钱？​

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="openrouter/nous/hermes-3-llama-3.1-70b")
response = agent.chat("Briefly explain quantum computing")

请参阅 Python 库指南 了解完整的 API 使用方法。

故障排除​

安装问题​

安装后 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 [email protected]      # 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

提供商和模型问题​

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 openrouter/nous/hermes-3-llama-3.1-70b

# 或指定每个会话
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct

速率限制（429 错误）​

原因： 你已超过提供商的速率限制。

解决方案： 等待片刻后重试。对于持续使用，请考虑：

  • 升级你的提供商计划
  • 切换到不同的模型或提供商
  • 使用 hermes chat --provider <alternative> 路由到不同的后端

超出上下文长度​

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

消息问题​

Bot 不响应消息​

原因： Bot 未运行、未授权，或者你的用户不在允许列表中。

解决方案：

# 检查网关是否在运行
hermes gateway status

# 启动网关
hermes gateway start

# 检查日志中的错误
cat ~/.hermes/logs/gateway.log | tail -50

消息未送达​

原因： 网络问题、bot 令牌过期或平台 webhook 配置错误。

解决方案：

  • 用 hermes gateway setup 验证你的 bot 令牌是否有效
  • 检查网关日志：cat ~/.hermes/logs/gateway.log | tail -50
  • 对于基于 webhook 的平台（Slack、WhatsApp），确保你的服务器可以公开访问

允许列表混乱 —— 谁可以与 bot 交谈？​

原因： 授权模式决定谁获得访问权限。

解决方案：

模式如何工作
允许列表仅允许列表中列出的用户 ID 交互
DM 配对第一个在 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，请确保已启用：

  1. 打开 /etc/wsl.conf（如果不存在则创建）
  2. 添加： 
    [boot]
    systemd=true
  3. 从 PowerShell：wsl --shutdown
  4. 重新打开你的 WSL 终端
  5. 验证：systemctl is-system-running 应显示"running"或"degraded"
Windows 启动时自动运行

要获得可靠的自动启动，请使用 Windows 任务计划程序在登录时启动 WSL + 网关：

  1. 创建一个运行 wsl -d Ubuntu -- bash -lc 'hermes gateway run' 的任务
  2. 设置它在用户登录时触发

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

原因： launchd 服务继承了一个最小 PATH（/usr/bin:/bin:/usr/sbin:/sbin），不包括 Homebrew、nvm、cargo 或其他用户安装的工具目录。这通常会破坏 WhatsApp 桥接（找不到 node）或语音转录（找不到 ffmpeg）。

解决方案： 网关在运行 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

性能问题​

响应慢​

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

解决方案：

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

高 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 服务器的工具未显示​

原因： 服务器已启动但工具发现失败、工具被配置过滤掉，或者服务器不支持你期望的 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 日志）以诊断根本原因。

配置文件​

配置文件与设置 HERMES_HOME 有什么区别？​

配置文件是 HERMES_HOME 之上的托管层。你可以在每个命令前手动设置 HERMES_HOME=/some/path，但配置文件为你处理所有管道：创建目录结构、生成 shell 别名（hermes-work）、在 ~/.hermes/active_profile 中跟踪活动配置，以及自动跨配置文件同步技能更新。它们还与标签补全集成，因此你无需记住路径。

两个配置文件可以共享同一个 bot 令牌吗？​

不能。每个消息平台（Telegram、Discord 等）都需要对 bot 令牌的独占访问权限。如果两个配置文件尝试同时使用同一个令牌，第二个网关将无法连接。为每个配置文件创建一个单独的 bot —— 对于 Telegram，请联系 @BotFather 制作额外的 bot。

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

不。每个配置文件都有自己的记忆存储、会话数据库和技能目录。它们完全隔离。如果你想用现有的记忆和会话启动一个新的配置文件，请使用 hermes profile create newname --clone-all 从当前配置文件复制所有内容。

当我运行 hermes update 时会发生什么？​

hermes update 拉取最新代码并重新安装依赖项一次（不是每个配置文件）。然后自动将更新的技能同步到所有配置文件。你只需要运行 hermes update 一次 —— 它涵盖机器上的每个配置文件。

我可以将配置文件移动到另一台机器吗？​

可以。将配置文件导出到可移植存档，然后在另一台机器上导入：

# 在源机器上
hermes profile export work ./work-backup.tar.gz

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

导入的配置文件将包含导出中的所有配置、记忆、会话和技能。如果新机器设置不同，你可能需要更新路径或重新向提供商进行身份验证。

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

没有硬性限制。每个配置文件只是 ~/.hermes/profiles/ 下的一个目录。实际限制取决于你的磁盘空间和系统可以处理的并发网关数量（每个网关是一个轻量级 Python 进程）。运行数十个配置文件没有问题；每个空闲的配置文件不使用资源。

工作流与模式​

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

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

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

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

现在当你告诉 Hermes"写一个关于 X 的 Twitter 主题"并它生成一个 delegate_task 子 agent 时，该子 agent 在 Gemini 上运行而不是你的主模型。你的主要对话保留在 GPT-5.4 上。

你也可以在提示中明确表达："委托一个任务来撰写关于我们产品发布会的社交媒体帖子。使用你的子 agent 进行实际写作。" Agent 将使用 delegate_task，它会自动拾取委托配置。

有关一次性的模型切换而不是委托，请在 CLI 中使用 /model：

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

请参阅子代理委托了解更多关于委托如何工作。

在一个 WhatsApp 号码上运行多个 agent（按聊天绑定）​

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

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

变通方案：

  1. 使用具有人格切换的单一配置文件。 创建不同的 AGENTS.md 上下文文件或使用 /personality 命令来更改每个聊天的行为。Agent 知道它在哪个聊天中，可以适应。

  2. 使用 cron 作业进行专业任务。 对于购物清单跟踪器，设置一个监视特定聊天并管理列表的 cron 作业 —— 不需要单独的 agent。

  3. 使用单独的号码。 如果你需要真正独立的 agent，请将每个配置文件与自己的 WhatsApp 号码配对。Google Voice 等服务的虚拟号码适用于此。

  4. 改用 Telegram 或 Discord。 这些平台更自然地支持按聊天绑定 —— 每个 Telegram 群组或 Discord 频道获得自己的会话，你可以运行多个 bot 令牌（每个配置文件一个）在同一个帐户上。

请参阅配置文件和 WhatsApp 设置了解更多详情。

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

场景： 你在 Telegram 中看到网关 exec 日志、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 bot 命令菜单在启动时重建。

提示

具有非常长描述的技能在 Telegram 菜单中被截断为 40 个字符以保持在有效载荷大小限制内。如果技能没有出现，可能是总有效载荷大小问题而不是 100 个命令计数限制 —— 禁用未使用的技能有助于解决两者。

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

场景： 你有一个 Telegram 或 Discord 线程，多个人提到 bot。你希望该线程中的所有提到都是一个共享对话的一部分，而不是单独的用户会话。

当前行为： Hermes 在大多数平台上创建按用户 ID 键控的会话，因此每个人获得自己的对话上下文。这是为隐私和上下文隔离而设计的。

变通方案：

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

  2. 使用带有单一用户的群聊。 如果一个人是被指定的"操作员"中继问题，会话保持统一。其他人可以阅读。

  3. 使用 Discord 频道。 Discord 会话按频道键控，因此同一频道中的所有用户共享上下文。使用专用频道进行共享对话。

导出 Hermes 到另一台机器​

场景： 你在一台机器上构建了技能、cron 作业和记忆，想将所有内容移动到新的专用 Linux 机器。

解决方案：

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

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

  2. 复制你整个 ~/.hermes/ 目录除了 hermes-agent 子目录（那是代码仓库 —— 新安装有自己的）：

    # 在源机器上
    rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/

    或者使用配置文件导出/导入：

    # 在源机器上
    hermes profile export default ./hermes-backup.tar.gz

    # 在目标机器上
    hermes profile import ./hermes-backup.tar.gz default

  3. 在新机器上，运行 hermes setup 验证 API 密钥和提供商配置是否正常工作。重新向消息平台进行身份验证（尤其是 WhatsApp，它使用 QR 配对）。

~/.hermes/ 目录包含所有内容：config.yaml、.env、SOUL.md、memories/、skills/、state.db（会话）、cron/ 和任何自定义插件。代码本身位于 ~/.hermes/hermes-agent/ 中，是全新安装的。

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

第一次 agent 运行时出现错误 400​

场景： 设置完成良好，但第一次聊天尝试失败，HTTP 400。

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

解决方案：

# 检查配置了什么模型和提供商
hermes config show | head -20

# 重新运行模型选择
hermes model

# 或用已知良好的模型测试
hermes chat -q "hello" --model anthropic/claude-sonnet-4.6

如果使用 OpenRouter，请确保你的 API 密钥有信用额度。来自 OpenRouter 的 400 通常意味着模型需要付费计划或模型 ID 有拼写错误。

仍然卡住了？​

如果你的问题不在此处：

  1. 搜索现有问题： GitHub Issues
  2. 询问社区： Nous Research Discord
  3. 提交错误报告： 包含你的 OS、Python 版本（python3 --version）、Hermes 版本（hermes --version）和完整错误消息