词元广场TOKPUB.COM - 欢迎您，支持一个 Key 调用近 600+ 海内外模型，限时特价模型低至 1 折，欢迎上岸！
"常见问题与故障排查"
常见问题与故障排查
常见问题
Hermes 支持哪些 LLM 提供商？
hermes auth add anthropic 进行 OAuth、OpenRouter 或任何兼容代理）gemini 提供商直接调用 API、google-gemini-cli OAuth 提供商、OpenRouter 或兼容代理）hermes model 设置提供商，或直接编辑 ~/.hermes/.env。所有提供商 key 请参阅环境变量参考文档。支持 Windows 吗？
我在 WSL2 中运行 Hermes，如何控制 Windows 上的普通 Chrome？
/browser connect。cmd.exe 或 powershell.exe 将 chrome-devtools-mcp 添加为 MCP 服务器支持 Android / Termux 吗？
.[all] 扩展目前在 Android 上不可用，因为 voice 扩展依赖 faster-whisper → ctranslate2，而 ctranslate2 未发布 Android wheel 包。请改用经过测试的 .[termux] 扩展。我的数据会被发送到哪里？
~/.hermes/ 目录中。可以离线使用 / 使用本地模型吗？
hermes model，选择自定义端点，然后输入您服务器的 URL：config.yaml 中配置：config.yaml，重启后仍然有效。如果您的本地服务器只加载了一个模型，/model custom 会自动检测到它。您也可以在 config.yaml 中设置 provider: custom — 这是一个一等提供商，不是其他任何东西的别名。Ollama 用户
num_ctx（例如 ollama run --num_ctx 16384），请确保在 Hermes 中设置匹配的上下文长度 — Ollama 的 /api/show 报告的是模型的最大上下文，而非您配置的实际 num_ctx。本地模型超时问题
.env 中设置 HERMES_STREAM_READ_TIMEOUT=1800。详情请参阅本地 LLM 指南。费用是多少？
多人可以使用同一个实例吗？
记忆（memory）和技能（skills）有什么区别？
可以在我自己的 Python 项目中使用吗？
AIAgent 类，以编程方式使用 Hermes：故障排查
安装问题
安装后出现 hermes: command not found
提示
~/.local/bin 添加到您的 PATH。如果您使用非标准 shell 配置，请手动添加 export PATH="$HOME/.local/bin:$PATH"。Python 版本过旧
终端命令提示 node: command not found（或 nvm、pyenv、asdf 等）
bash -l 构建每个会话的环境快照。bash 登录 shell 会读取 /etc/profile、~/.bash_profile 和 ~/.profile，但不会 source ~/.bashrc — 因此在 ~/.bashrc 中安装自身的工具（nvm、asdf、pyenv、cargo、自定义 PATH 导出）对快照不可见。当 Hermes 在 systemd 下运行或在未预加载交互式 shell 配置的最小 shell 中运行时，此问题最为常见。~/.bashrc。如果这还不够 — 例如您是 zsh 用户，PATH 在 ~/.zshrc 中，或者您从独立文件初始化 nvm — 请在 ~/.hermes/config.yaml 中列出需要额外 source 的文件：nvm.sh），而非整个 rc 文件。uv: command not found
uv 包管理器未安装或不在 PATH 中。安装时出现权限拒绝错误
提供商与模型问题
/model 只显示一个提供商 / 无法切换提供商
/model 只能在您已配置的提供商之间切换。如果您只设置了 OpenRouter，/model 就只会显示 OpenRouter。hermes model 添加新提供商：hermes model 添加新提供商后，启动新的聊天会话 — /model 将显示所有已配置的提供商。快速参考
| 目标 | 使用方式 |
|---|---|
| 添加新提供商 | hermes model（从终端） |
| 输入/更改 API key | hermes model（从终端） |
| 会话中途切换模型 | /model <name>（会话内） |
| 切换到其他已配置的提供商 | /model provider:model（会话内） |
API key 不起作用
警告
~/.hermes/.env 中是否有冲突条目。模型不可用 / 找不到模型
速率限制（429 错误）
hermes chat --provider <alternative> 路由到其他后端上下文长度超限
📊 Context limit: 128000 tokens）。您也可以在会话中使用 /usage 查看。终端问题
命令被标记为危险而阻止
rm -rf、DROP TABLE）。这是一项安全功能。y 批准执行。您也可以：提示
通过消息网关时 sudo 不起作用
sudo 无法提示输入密码。sudo — 请智能体寻找替代方案sudo，在 /etc/sudoers 中为特定命令配置免密 sudohermes chatDocker 后端无法连接
消息问题
Bot 不响应消息
消息未送达
hermes gateway setup 验证您的 bot token 是否有效cat ~/.hermes/logs/gateway.log | tail -50白名单混淆 — 谁可以与 bot 交互？
| 模式 | 工作方式 |
|---|---|
| 白名单 | 只有配置中列出的用户 ID 可以交互 |
| 私信配对 | 第一个在私信中发消息的用户获得独占访问权 |
| 开放 | 任何人都可以交互（不建议用于生产环境） |
~/.hermes/config.yaml 中您的网关设置下进行配置。请参阅消息文档。网关无法启动
WSL：网关持续断开连接或 hermes gateway start 失败
1.
/etc/wsl.conf（不存在则创建）2.
3.
wsl --shutdown4.
5.
systemctl is-system-running 应显示 "running" 或 "degraded"Windows 开机自启
1.
wsl -d Ubuntu -- bash -lc 'hermes gateway run'2.
macOS：网关找不到 Node.js / ffmpeg / 其他工具
/usr/bin:/bin:/usr/sbin:/sbin），不包含 Homebrew、nvm、cargo 或其他用户安装的工具目录。这通常会导致 WhatsApp bridge（node not found）或语音转录（ffmpeg not found）失败。hermes gateway install 时会捕获您的 shell PATH。如果您在设置网关后安装了新工具，请重新运行 install 以捕获更新后的 PATH：性能问题
响应缓慢
hermes chat --model openrouter/meta-llama/llama-3.1-8b-instructhermes chat -t "terminal"token 用量过高
提示
/compress。它会对对话历史进行摘要，在保留上下文的同时显著减少 token 用量。会话过长
MCP 问题
MCP 服务器无法连接
~/.hermes/config.yaml 中的 MCP 配置：MCP 服务器的工具未显示
tools/list RPC 方法tools.include、tools.exclude、tools.resources、tools.prompts 或 enabled 设置/reload-mcpMCP 超时错误
警告
Profiles（配置文件）
Profiles 与直接设置 HERMES_HOME 有何不同？
HERMES_HOME 之上的托管层。您可以在每次命令前手动设置 HERMES_HOME=/some/path，但 profiles 会为您处理所有底层工作：创建目录结构、生成 shell 别名（hermes-work）、在 ~/.hermes/active_profile 中跟踪活动 profile，以及自动跨所有 profiles 同步技能更新。它们还与 tab 补全集成，让您无需记忆路径。两个 profiles 可以共享同一个 bot token 吗？
Profiles 共享记忆或会话吗？
hermes profile create newname --clone-all 从当前 profile 复制所有内容。运行 hermes update 时会发生什么？
hermes update 拉取最新代码并重新安装依赖项一次（不是每个 profile 各一次）。然后自动将更新的技能同步到 所有 profiles。您只需运行一次 hermes update — 它覆盖机器上的每个 profile。可以运行多少个 profiles？
~/.hermes/profiles/ 下的一个目录。实际限制取决于您的磁盘空间以及系统能处理多少个并发网关（每个网关是一个轻量级 Python 进程）。运行数十个 profiles 完全没问题；每个空闲的 profile 不占用任何资源。工作流与模式
针对不同任务使用不同模型（多模型工作流）
~/.hermes/config.yaml 中设置：delegate_task 子智能体时，该子智能体将在 Gemini 上运行，而非您的主模型。您的主对话仍在 GPT-5.4 上进行。delegate_task，它会自动读取委托配置。/model：在一个 WhatsApp 号码上运行多个智能体（按聊天绑定）
1.
AGENTS.md 上下文文件或使用 /personality 命令按聊天更改行为。智能体能感知当前 所在的聊天并进行适应。2.
3.
4.
控制 Telegram 中显示的内容（隐藏日志和推理过程）
config.yaml 中的 display.tool_progress 设置控制显示多少工具活动：off — 仅显示最终响应。无工具调用、无推理过程、无日志。new — 实时显示新的工具调用（简短单行）。all — 显示所有工具活动，包括结果。verbose — 完整详情，包括工具参数和输出。off 或 new。编辑 config.yaml 后，重启网关使更改生效。/verbose 命令按会话切换（如果已启用）：在 Telegram 上管理技能（slash 命令限制）
hermes skills config 设置似乎没有生效。hermes skills config 按平台禁用技能。这会写入 config.yaml：hermes gateway restart 或终止并重新启动）。Telegram bot 命令菜单在启动时重建。提示
共享线程会话（多用户，一个对话）
1.
2.
3.
将 Hermes 迁移到另一台机器
1.
2.
~/.hermes/ 目录（配置、API key、记忆、技能、会话和 profiles）打包为 zip 文件，保存到主目录 ~/hermes-backup-<timestamp>.zip。3.
4.
hermes setup 以验证 API key 和提供商配置是否正常工作。将单个 profile 迁移到另一台机器
hermes backup 与 hermes profile export 的对比
| 功能 | hermes backup | hermes profile export |
|---|---|---|
| 使用场景 | 整机迁移 | 移植/共享特定 profile |
| 范围 | 全局（整个 ~/.hermes 目录） | 局部（单个 profile 目录） |
| 包含内容 | 所有 profiles、全局配置、API key、会话 | 单个 profile：SOUL.md、记忆、会话、技能 |
| 凭据 | 包含（.env 和 auth.json） | 排除（为安全共享而剥离） |
| 格式 | .zip | .tar.gz |
提示
hermes backup 即使在 Hermes 正在运行时也能生成一致的快照。还原的归档文件不包含机器本地的运行时文件，如 gateway.pid 和 cron.pid。安装后重新加载 shell 时出现权限拒绝
source ~/.zshrc 提示权限拒绝错误。~/.zshrc（或 ~/.bashrc）文件权限不正确，或安装程序无法干净写入时。这不是 Hermes 特有的问题 — 而是 shell 配置权限问题。首次运行智能体时出现 400 错误
仍然遇到问题？
1.
2.
3.
python3 --version）、Hermes 版本（hermes --version）以及完整的错误信息