Skip to main content

常见问题与故障排查

这里汇总了最常见的问题，以及对应的解决思路和处理办法。

常见问题​

Hermes 支持哪些大模型提供商？​

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 — 全球及中国区服务端点
  • 本地模型 — 通过 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 现已提供经过测试的 Termux 安装路径，适用于安卓手机。

快速安装方式：

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

如需完整手动步骤、支持的附加功能以及当前限制，请参阅 Termux 使用指南。

重要提示：目前 Android 上无法使用完整的 .[all] 功能，因为 voice 依赖于 faster-whisper` → `ctranslate2，而 ctranslate2 并未发布 Android 版本。请改用经过验证的 .[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 报告的是模型的最大上下文长度，而非你实际配置的有效上下文长度。

本地模型超时问题

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
tip

安装程序会将 ~/.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
warning

请确认密钥与提供商一致。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 启动行，显示了检测到的上下文长度（例如 📊 Context limit: 128000 tokens）。也可在会话中使用 /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 -rf、DROP TABLE）。这是安全防护机制。

解决方案： 当提示出现时，审查命令并输入 y 确认执行。你还可以：

  • 要求 agent 使用更安全的替代方案
  • 在 安全文档 中查看所有危险模式列表
tip

此行为符合预期——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

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

原因： WSL 的 systemd 支持不可靠。许多 WSL2 安装未启用 systemd，即使启用，服务也可能在 WSL 重启或 Windows 空闲休眠后无法存活。

解决方案： 改用前台模式而非 systemd 服务：

# Option 1: Direct foreground (simplest)
hermes gateway run

# Option 2: Persistent via tmux (survives terminal close)
tmux new -s hermes 'hermes gateway run'
# Reattach later: tmux attach -t hermes

# Option 3: Background via 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 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
tip

在长时间会话中定期使用 /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.include、tools.exclude、tools.resources、tools.prompts 或 enabled 设置
  • 请注意，资源/提示工具仅在会话实际支持这些功能时才会注册
  • 修改配置后使用 /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 服务器，检查网络连通性
warning

如果 MCP 服务器在请求中途崩溃，Hermes 会报告超时。请检查服务器自身的日志（而不仅仅是 Hermes 日志），以诊断根本原因。

配置文件（Profiles）​

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

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

两个配置文件能否共享同一个机器人令牌？​

不能。每个消息平台（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 写社交媒体内容更出色。每次手动切换模型非常繁琐。

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

delegation:
  model: "google/gemini-3-flash-preview"   # subagents use this model
  provider: "openrouter"                    # provider for subagents

现在当你对 Hermes 说“写一篇关于 X 的推文系列”时，它会启动一个 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 jobs）处理专项任务。 例如为购物清单追踪设置一个 cron 任务，监控特定聊天并管理列表——无需额外代理。

  3. 使用独立号码。 若需真正独立的代理，可为每个配置文件分配一个独立的 WhatsApp 号码。虚拟号码服务（如 Google Voice）可满足此需求。

  4. 改用 Telegram 或 Discord。 这两个平台天然支持按聊天绑定：每个 Telegram 群组或 Discord 频道都有独立会话，你可以在同一账户下运行多个机器人令牌（每个配置文件对应一个）。

详细信息请见 配置文件 和 WhatsApp 设置。

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

场景： 你在 Telegram 中看到网关执行日志、Hermes 推理过程和工具调用细节，而不仅仅是最终输出。

解决方案： display.tool_progress 设置（位于 config.yaml 中）控制工具活动的可见程度：

display:
  tool_progress: "off"   # options: off, new, all, verbose
  • off — 仅显示最终回复。不展示工具调用、推理过程或日志。
  • new — 显示工具调用的实时简短提示（一行字）。
  • all — 显示所有工具活动，包括结果。
  • verbose — 完整详情，包含工具参数和输出。

对于消息平台，通常建议使用 off 或 new。修改 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 机器人的命令菜单会在启动时重建。

tip

在 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、.env、SOUL.md、memories/、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. 提交 bug 报告： 请附上你的操作系统、Python 版本（python3 --version）、Hermes 版本（hermes --version）及完整错误信息