Hermes Agent 安装、运行、使用常见错误总结与解决方案

适用日期：2026-05-19
适用对象：Hermes Agent 的 Windows、WSL2、macOS、Linux、Termux 用户。
使用方式：先看“快速排障流程”，再按错误现象查对应章节。
重要提醒：Hermes Agent 更新较快，命令和平台能力可能变化。遇到不一致时，以官方文档和 hermes --help、hermes doctor 输出为准。

1. 快速排障流程

遇到问题时，不要一开始就重装。建议按这个顺序排查：

hermes --version
hermes doctor
hermes config show
hermes dump

如果是网关、消息平台或后台服务问题，再加：

hermes gateway status
cat ~/.hermes/logs/gateway.log | tail -50

如果是模型/API 问题：

hermes model
hermes chat -q "hello"

如果是 Windows/WSL2 问题，先确认自己在哪个系统里：

uname -a
pwd
which hermes

PowerShell 中：

wsl --list --verbose
where hermes

2. 常用诊断命令

目的	命令
查看版本	`hermes --version`
环境诊断	`hermes doctor`
尝试自动修复	`hermes doctor --fix`
查看配置	`hermes config show`
重新配置模型	`hermes model`
进入完整配置向导	`hermes setup`
查看可分享诊断摘要	`hermes dump`
查看 key 状态摘要	`hermes dump --show-keys`
启动聊天	`hermes` 或 `hermes chat`
快速测试一次模型	`hermes chat -q "hello"`
恢复最近会话	`hermes --continue` 或 `hermes chat --continue`
查看 gateway 状态	`hermes gateway status`
启动 gateway	`hermes gateway start`
前台运行 gateway	`hermes gateway run`
重新配置 gateway	`hermes gateway setup`
更新 Hermes	`hermes update`

3. 安装阶段常见错误

3.1 `hermes: command not found`

现象

安装完成后执行 hermes，提示命令不存在。

常见原因

当前 shell 还没有重新加载 PATH；
~/.local/bin 没有加入 PATH；
Windows 原生安装后没有重新打开 PowerShell；
服务用户的 PATH 极简，不包含 Hermes launcher；
误执行了源码目录里的 hermes 文件，而不是虚拟环境里的 launcher。

解决方案

Linux/macOS/WSL2：

source ~/.bashrc
# 或
source ~/.zshrc

检查：

echo $PATH
ls -l ~/.local/bin/hermes
which hermes

如果 PATH 没有 ~/.local/bin：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows 原生：

where hermes

如果刚安装完，关闭所有 PowerShell/Windows Terminal 窗口后重新打开。

3.2 安装脚本下载失败

现象

curl -fsSL ... | bash 报网络错误、DNS 错误、TLS 错误、连接超时。

常见原因

当前网络无法访问 GitHub raw 域名；
代理没有配置到 shell；
公司/校园网络拦截；
系统证书过旧。

解决方案

先验证访问：

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

如果失败：

换网络或配置代理；
确认系统时间正确；
更新证书包：

sudo apt update
sudo apt install -y ca-certificates curl git

macOS 可先确认 curl 和 Git 可用：

git --version
curl --version

3.3 `git: command not found`

现象

安装脚本提示找不到 Git。

解决方案

Ubuntu/Debian/WSL2：

sudo apt update
sudo apt install -y git curl ca-certificates

macOS：

xcode-select --install

或：

brew install git

Windows 原生安装器通常会优先使用已有 Git；没有时会下载 PortableGit。若 PortableGit 下载失败，优先排查网络。

3.4 `Permission denied`

现象

安装或运行时出现权限不足。

常见原因

把 Hermes 安装在系统目录；
对 ~/.hermes 或 ~/.local/bin 没有写权限；
WSL2 项目放在 /mnt/c/...，权限位不正常；
用 root 安装后又用普通用户运行。

解决方案

普通个人使用建议安装在普通用户目录，不要默认 sudo 安装。

检查权限：

ls -ld ~/.hermes ~/.local ~/.local/bin

修复当前用户目录权限：

sudo chown -R "$USER:$USER" ~/.hermes ~/.local

WSL2 中尽量把项目放在 Linux 文件系统，例如：

mkdir -p ~/projects
cd ~/projects

3.5 `ModuleNotFoundError: No module named 'dotenv'`

现象

执行 hermes 后出现 Python 模块缺失，例如 dotenv。

常见原因

官方文档指出，这通常是调用了源码目录里的 ~/.hermes/hermes-agent/hermes，而不是虚拟环境里的 Hermes launcher。

解决方案

检查当前命令路径：

which hermes

优先使用：

~/.local/bin/hermes

或虚拟环境 launcher：

~/.hermes/hermes-agent/venv/bin/hermes

如果是服务用户，确保 PATH 包含 ~/.local/bin。

3.6 Playwright/Chromium 安装失败

现象

安装时浏览器依赖失败，或 browser tool 无法启动。

常见原因

Linux 缺少 Chromium 系统库；
用户没有 sudo；
Playwright 浏览器下载被网络拦截；
服务器是 headless 环境，但没有相关依赖。

解决方案

有 sudo 的 Debian/Ubuntu：

sudo npx playwright install-deps chromium

无 sudo 的服务用户：让管理员先执行上面的系统库安装，再用服务用户安装 Hermes。

如果暂时不需要浏览器能力，可以跳过：

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

3.7 Windows 原生安装后功能异常

现象

PowerShell 可以运行 hermes，但 terminal tool、browser tool、编码、路径或 dashboard chat terminal 异常。

说明

官方文档将 Windows 原生支持标注为 early beta。多数 CLI、gateway、cron、browser tool、MCP 能力可原生运行，但 dashboard 的 /chat 终端面板依赖 POSIX PTY，仍需要 WSL2。

解决方案

优先判断是否应该改用 WSL2：

要做 POSIX/Linux 开发：推荐 WSL2；
要使用 dashboard 内嵌终端：推荐 WSL2；
只是 PowerShell 里聊天、跑 gateway、跑 MCP：原生 Windows 可以尝试。

编码问题可临时尝试：

$env:HERMES_DISABLE_WINDOWS_UTF8="1"
hermes doctor

4. Windows/WSL2 常见错误

4.1 在 WSL1 中安装导致不稳定

现象

命令能跑但经常出现信号、网络、进程、文件权限异常。

原因

Hermes 更适合 WSL2。WSL1 的 Linux syscall、网络和 procfs 行为与真实 Linux 有差异。

解决方案

PowerShell：

wsl --list --verbose
wsl --set-version Ubuntu 2
wsl --set-default-version 2

4.2 WSL2 中 `hermes` 找不到

现象

在 Windows PowerShell 中能运行，进入 WSL2 后找不到；或反过来。

原因

Windows 原生 Hermes 和 WSL2 Hermes 是两套安装，数据目录也不同：

Windows 原生：%LOCALAPPDATA%\hermes
WSL2/Linux：~/.hermes

解决方案

在你真正要使用的环境中单独安装和配置。不要假设 Windows 的 hermes 会自动出现在 WSL2。

WSL2 内安装：

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

4.3 WSL2 下运行很慢

现象

git status、rg、Hermes 搜索文件、读写项目都很慢。

常见原因

项目放在 /mnt/c/Users/...。WSL2 访问 Windows 文件系统会经过跨边界协议，I/O、权限和文件监听都更容易出问题。

解决方案

把 Linux 侧开发项目放到 WSL2 文件系统：

mkdir -p ~/projects
cd ~/projects
git clone <your-repo-url>

只有确实需要 Windows GUI 程序直接访问时，才把文件放到 /mnt/c/...。

4.4 `bad interpreter: /bin/bash^M`

现象

脚本在 WSL2/Linux 中运行时报：

bad interpreter: /bin/bash^M

原因

文件是 Windows CRLF 行尾。

解决方案

sudo apt install -y dos2unix
dos2unix path/to/script.sh

建议在 WSL2 内设置 Git：

git config --global core.autocrlf input
git config --global core.eol lf

4.5 WSL2 访问 Windows 上的 Ollama/LM Studio 失败

现象

Hermes 配置本地模型后，连接 Windows 上的 Ollama、LM Studio、llama-server 报 Connection refused。

常见原因

WSL2 里的 localhost 不一定等于 Windows 的 localhost；
Windows 上的模型服务只绑定 127.0.0.1；
Windows 防火墙阻挡端口；
没有启用 mirrored networking。

解决方案

Windows 11 22H2+ 可考虑开启 WSL mirrored networking。旧环境通常需要让 Windows 模型服务监听 0.0.0.0，并放行端口。

以 Ollama 为例，确保服务绑定到可被 WSL 访问的地址，例如设置：

OLLAMA_HOST=0.0.0.0

然后在 WSL2 里使用 Windows host IP 或 mirrored 模式下的 localhost。

4.6 WSL2 睡眠后 HTTPS/OAuth 报错

现象

电脑睡眠/休眠后，Hermes 调 API、OAuth 或 HTTPS 证书相关请求失败。

原因

WSL2 时钟可能漂移。

解决方案

sudo hwclock -s

或安装时间同步工具，在 WSL2 登录时同步时间。

5. 配置和模型常见错误

5.1 `API key not set`

现象

Hermes 启动聊天时报 API key 没配置。

解决方案

推荐用向导：

hermes model

或检查配置：

hermes config show

直接设置示例：

hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx

注意：OpenAI、OpenRouter、Anthropic、DashScope、Kimi、GLM 等 key 名不同，不能混用。

5.2 API key 有但仍不可用

现象

明明设置了 key，仍然 401、403、invalid key、provider authentication failed。

常见原因

key 属于另一个 provider；
key 已过期或额度不足；
.env 中有旧 key 覆盖新配置；
使用了代理平台，但 base URL/model name 写错；
provider 账号没有对应模型权限。

解决方案

hermes config show
hermes model

检查本地环境文件是否有冲突：

cat ~/.hermes/.env

如果是 OpenRouter，确认账户余额、模型 ID、模型权限和 API key。

5.3 首次运行 HTTP 400

现象

安装、配置都成功，但第一次聊天返回 HTTP 400。

常见原因

官方 FAQ 中说明，这通常是模型名不匹配、模型不存在、API key 没权限访问该模型，或 OpenRouter 模型 ID 写错。

解决方案

查看当前 provider/model：

hermes config show | head -20

重新选择模型：

hermes model

用一个已知可用模型测试：

hermes chat -q "hello"

如果通过 OpenRouter，确认 key 有额度，并且模型 ID 没有拼写错误。

5.4 本地模型连接不上

现象

使用 Ollama、LM Studio、vLLM、SGLang、本地 OpenAI-compatible 服务时连接失败。

常见原因

base URL 不符合 OpenAI-compatible 格式；
服务没启动；
WSL2/Windows 网络边界没处理；
模型服务只监听 127.0.0.1；
API key 占位不符合服务要求；
context length 配置过大。

解决方案

先用 curl 测服务：

curl http://localhost:11434/v1/models

配置 Hermes：

hermes model
# 选择 Custom endpoint
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: 实际模型名

如果 Hermes 在 WSL2、本地模型在 Windows，请参考 WSL2 网络问题章节。

5.5 切换 profile 后配置“丢失”

现象

之前能用的模型、session、gateway 配置突然找不到。

常见原因

切换了 Hermes profile；
设置了不同的 HERMES_HOME；
Windows 原生和 WSL2 各有独立数据目录；
用 root 运行后写到了 /root/.hermes。

解决方案

检查：

hermes dump
echo $HERMES_HOME

不要混用普通用户和 root。确认当前 shell、用户、profile 都是预期的。

5.6 更新后配置缺失或格式不兼容

现象

hermes update 后模型、工具或 gateway 配置异常。

解决方案

hermes config check
hermes config migrate
hermes doctor

更新前建议备份：

cp -a ~/.hermes ~/.hermes.backup.$(date +%Y%m%d)

6. 运行阶段常见错误

6.1 Hermes 启动慢或回答慢

常见原因

选择了大模型或远端 provider 延迟高；
会话太长；
启用了太多工具、MCP、skills；
本地模型显存不足；
项目在 WSL2 的 /mnt/c 下。

解决方案

压缩会话：

/compress

查看 token 使用：

/usage

减少工具：

hermes chat -t "terminal"

换更快模型：

hermes chat --model <provider/model>

WSL2 项目移到：

~/projects

6.2 会话太长、上下文溢出

现象

长时间使用后，模型开始遗忘、变慢或报 context length 相关错误。

解决方案

在 Hermes 聊天中执行：

/compress

必要时开启新会话：

hermes chat

恢复最近会话：

hermes chat --continue

6.3 `hermes --continue` 找不到旧会话

常见原因

当前 profile 变了；
HERMES_HOME 变了；
Windows 原生和 WSL2 安装混用；
会话没有成功保存。

解决方案

hermes sessions list
hermes dump
echo $HERMES_HOME

确认你在同一个用户、同一个系统、同一个 profile 下。

6.4 Terminal tool 不能执行命令

常见原因

终端工具未启用；
Windows 原生 Git Bash/PortableGit 异常；
Docker/SSH backend 未配置好；
当前目录权限不足；
gateway 环境没有交互式 shell。

解决方案

重新配置工具：

hermes tools

本地 shell 检查：

pwd
whoami
which bash

Windows 原生检查：

where bash
where git
where hermes

如果是 Docker backend：

docker info
docker run hello-world

6.5 `sudo` 在消息平台里不可用

现象

Telegram/Discord/Slack gateway 中让 Hermes 执行 sudo，命令卡住或失败。

原因

消息 gateway 没有交互式终端，无法输入 sudo 密码。

解决方案

尽量不要在 messaging gateway 中执行 sudo；
改用本地 hermes chat 做管理员任务；
如果必须自动化，给极少数明确命令配置 passwordless sudo，不要开放全量 sudo。

7. Gateway 和消息平台常见错误

7.1 Bot 不回复消息

常见原因

gateway 没启动；
bot token 错误或过期；
用户不在 allowlist；
平台权限没开；
gateway 日志中有异常；
WSL2 后台服务随 Windows 休眠/关闭而停止。

解决方案

hermes gateway status
hermes gateway start
cat ~/.hermes/logs/gateway.log | tail -50

重新配置：

hermes gateway setup

检查 allowlist、bot token、平台权限。

7.2 Gateway 启动失败

常见原因

缺少 messaging 依赖；
端口冲突；
token 配置错误；
systemd/launchd/PowerShell 后台环境 PATH 不完整。

解决方案

检查配置：

hermes config show

检查端口：

lsof -i :8080

必要时安装 messaging extra：

pip install "hermes-agent[messaging]"

如果是 macOS launchd 服务找不到 Node.js、ffmpeg 等工具，重新安装 gateway 以刷新 PATH：

hermes gateway install
hermes gateway start

7.3 WSL2 中 gateway 老是断开

常见原因

WSL2 没启用 systemd；
Windows 空闲后关闭 WSL；
systemd user service 没有随 WSL 启动；
网络/NAT 变化。

解决方案

前台运行：

hermes gateway run

用 tmux 保持：

tmux new -s hermes 'hermes gateway run'
tmux attach -t hermes

用 nohup：

nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &

启用 WSL2 systemd：

sudo nano /etc/wsl.conf

写入：

[boot]
systemd=true

PowerShell：

wsl --shutdown

重新打开 WSL 后验证：

systemctl is-system-running

7.4 消息发不出去或 webhook 不通

常见原因

token 过期；
webhook 地址外网不可达；
本地端口没有映射到公网；
Slack/WhatsApp/Telegram 平台侧权限或回调配置错误；
防火墙阻挡。

解决方案

hermes gateway setup
cat ~/.hermes/logs/gateway.log | tail -50

如果平台需要从公网访问本机，优先使用 cloudflared/ngrok 这类隧道，而不是直接暴露本机端口。

7.5 Telegram 里显示过多工具日志和推理过程

现象

Telegram/消息平台中出现大量工具调用、日志、过程信息，不只显示最终答案。

解决方案

在 ~/.hermes/config.yaml 中调整：

display:
  tool_progress: "off"

常用选项：

off      只显示最终回复
new      显示新工具调用摘要
all      显示所有工具活动
verbose  显示完整细节

修改后重启 gateway。

7.6 Telegram slash command 太多

现象

技能太多，Telegram 命令菜单异常或部分命令不显示。

原因

Telegram slash command 有数量和 payload 限制。

解决方案

禁用不需要的技能，尤其是平台级禁用：

skills:
  disabled: []
  platform_disabled:
    telegram: [skill-a, skill-b]

修改后：

hermes gateway restart

或停止后重新运行 gateway。

8. MCP 常见错误

8.1 MCP server not connecting

常见原因

MCP server 二进制不存在；
command 路径错；
Node.js/npx/Python 不在 PATH；
环境变量缺失；
MCP server 自身启动失败；
修改配置后没有 reload。

解决方案

检查 Node：

node --version
npx --version

手动测试 MCP server：

npx -y @modelcontextprotocol/server-filesystem /tmp

检查配置：

hermes config show | grep -A 12 mcp_servers

在 Hermes 会话中重新加载：

/reload-mcp

必要时安装 MCP extra：

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

8.2 MCP 工具不显示

常见原因

server 没响应 tools/list；
配置里 enabled、tools.include、tools.exclude 限制了工具；
当前会话不支持资源/提示能力；
修改后未 reload；
server 启动成功但鉴权失败。

解决方案

检查 Hermes 日志和 gateway/agent 日志；简化 MCP 配置，只保留一个 server 和最小环境变量，确认能正常列出工具后再逐步添加。

8.3 WSL2 调 Windows Chrome MCP 报 UNC 路径问题

现象

Hermes 在 WSL2 中启动 Windows 侧二进制，出现 UNC path 不支持或 cwd 异常。

原因

Windows cmd.exe 不理解 WSL Linux 路径作为当前工作目录。

解决方案

这类场景可从 /mnt/c/... 下启动 Hermes，或写 wrapper 先 cd 到 Windows 可识别路径，再调用 Windows 程序。

9. Browser、文件和终端能力常见错误

9.1 browser tool 无法打开页面

常见原因

Playwright/Chromium 安装失败；
headless 服务器缺系统库；
网络被代理/防火墙拦截；
Windows 原生依赖 Git Bash/Node 路径异常；
WSL2 内访问 Windows localhost 地址不对。

解决方案

先运行：

hermes doctor
node --version
npx --version

Linux 缺依赖：

sudo npx playwright install-deps chromium

WSL2 访问 Windows 服务时，确认网络配置和绑定地址。

9.2 agent 改错文件或找不到文件

常见原因

当前工作目录不是项目目录；
Windows/WSL2 路径混淆；
文件在 Windows，Hermes 在 WSL2；
使用相对路径但当前 cwd 不对；
多个 profile/session 混淆。

解决方案

开始任务前让 Hermes 确认：

pwd
ls
git status

WSL2 下注意路径转换：

wslpath -w ~/projects/myrepo
wslpath -u 'C:\Users\you\Documents'

9.3 Docker backend 不工作

现象

Hermes 设置 Docker terminal backend 后连接失败。

常见原因

Docker daemon 未启动；
当前用户不在 docker group；
Docker Desktop 未运行；
WSL2 Docker 集成没开；
镜像/容器权限不足。

解决方案

docker info
docker run hello-world

Linux：

sudo usermod -aG docker $USER
newgrp docker
docker run hello-world

Windows/WSL2 用户确认 Docker Desktop 已启动，并启用了对应 WSL distro 集成。

10. 更新、卸载、重装常见错误

10.1 `hermes update` 失败

常见原因

GitHub 网络不可达；
本地 Hermes 源码目录有未提交修改；
虚拟环境损坏；
权限被 root/普通用户混用破坏。

解决方案

先备份：

cp -a ~/.hermes ~/.hermes.backup.$(date +%Y%m%d)

再检查：

cd ~/.hermes/hermes-agent
git status
hermes doctor

如果你修改过源码，先保存自己的改动，不要直接覆盖。

10.2 卸载后重装仍然带旧配置

原因

卸载程序可能只移除程序，不一定删除所有数据。旧配置通常在：

Linux/macOS/WSL2：~/.hermes
Windows 原生：%LOCALAPPDATA%\hermes

解决方案

如果确认要完全清空：

hermes uninstall --full

或手动备份后删除数据目录。

10.3 root 安装和普通用户安装混乱

现象

root 下能运行，普通用户不能；或配置写到了 /root/.hermes。

解决方案

个人使用统一用普通用户运行。检查：

whoami
which hermes
echo $HERMES_HOME

不要一会儿 sudo hermes，一会儿普通用户 hermes。

11. Termux/Android 常见错误

11.1 安装 voice/all extra 失败

原因

官方 FAQ 提到 Android 上完整 .[all] extra 不适用，因为部分语音依赖没有 Android wheel。

解决方案

使用官方 Termux 路径，不要强行安装全量 desktop extras：

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

Termux 上先保证基础聊天可用，再考虑扩展能力。

11.2 手机端后台运行不稳定

原因

Android 电池优化、网络切换、后台限制会影响长期运行。

解决方案

关闭 Termux 的电池优化；
使用 tmux；
不建议把手机作为 24/7 gateway 生产环境；
长期在线建议使用 VPS、家用服务器或稳定桌面机器。

12. 安全相关常见错误

12.1 把 API key 提交到 Git

风险

API key 一旦进入公开仓库，通常应视为泄露。

解决方案

立即撤销旧 key；
生成新 key；
确认 .env、config.yaml、日志没有被提交；
给项目 .gitignore 添加敏感文件规则。

12.2 Gateway 开放给所有人

风险

如果 bot 是 open mode，任何人都可能调用你的模型额度和本机工具。

解决方案

生产环境使用 allowlist 或私有 DM pairing。不要在公网 bot 上开放 terminal、filesystem、browser 等高权限能力。

12.3 给 agent 过大权限

风险

Hermes 可以调用本机工具时，权限边界就是当前用户权限。当前用户能删什么、改什么，agent 理论上也可能触达。

建议

初次使用放在测试目录；
生产环境使用低权限用户；
重要任务前备份；
高风险操作使用 Docker/SSH 隔离 backend；
不要用 root 长期运行。

13. 一页式错误速查表

错误/现象	最可能原因	快速处理
`hermes: command not found`	PATH 未刷新	`source ~/.bashrc` 或重开终端
`API key not set`	未配置 provider	`hermes model`
HTTP 400	模型名/权限/额度错误	`hermes config show` 后重选模型
key 有但 401/403	key 与 provider 不匹配	检查 `~/.hermes/.env` 和 provider
browser tool 失败	Playwright/Chromium 依赖缺失	`sudo npx playwright install-deps chromium`
WSL2 很慢	项目在 `/mnt/c`	移到 `~/projects`
`bad interpreter: /bin/bash^M`	CRLF 行尾	`dos2unix script.sh`
gateway 不回复	未启动/token/allowlist	`hermes gateway status` + 看日志
WSL2 gateway 断开	systemd/WSL 生命周期	`hermes gateway run` 或 tmux/systemd
MCP server 不连	command/path/env 错	手动运行 server + `/reload-mcp`
`sudo` 在 Telegram 失败	无交互终端	改用本地 CLI 或配置最小 passwordless sudo
更新后配置异常	config schema 变化	`hermes config check && hermes config migrate`
卸载后旧配置还在	数据目录未删	`hermes uninstall --full`

14. 建议的稳定使用方式

Windows 用户优先用 WSL2，除非明确只需要原生 PowerShell 使用。
WSL2 项目放在 ~/projects，不要长期在 /mnt/c/... 里做 Linux 开发。
先让 CLI + 一个模型稳定工作，再配置 gateway、MCP、skills、browser。
Gateway 生产使用必须设置 allowlist。
出问题先跑 hermes doctor 和 hermes dump，再考虑重装。
重装前备份 ~/.hermes 或 %LOCALAPPDATA%\hermes。
长会话定期 /compress。
不要长期用 root 跑 Hermes。

转载自CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/weixin_51035135/article/details/161212809

Hermes Agent 安装、运行、使用常见错误总结与解决方案

1. 快速排障流程

2. 常用诊断命令

3. 安装阶段常见错误

3.1 hermes: command not found

3.2 安装脚本下载失败

3.3 git: command not found

3.4 Permission denied

3.5 ModuleNotFoundError: No module named 'dotenv'

3.6 Playwright/Chromium 安装失败

3.7 Windows 原生安装后功能异常

4. Windows/WSL2 常见错误

4.1 在 WSL1 中安装导致不稳定

4.2 WSL2 中 hermes 找不到

4.3 WSL2 下运行很慢

4.4 bad interpreter: /bin/bash^M

4.5 WSL2 访问 Windows 上的 Ollama/LM Studio 失败

4.6 WSL2 睡眠后 HTTPS/OAuth 报错

5. 配置和模型常见错误

5.1 API key not set

5.2 API key 有但仍不可用

5.3 首次运行 HTTP 400

5.4 本地模型连接不上

5.5 切换 profile 后配置“丢失”

5.6 更新后配置缺失或格式不兼容

6. 运行阶段常见错误

6.1 Hermes 启动慢或回答慢

6.2 会话太长、上下文溢出

6.3 hermes --continue 找不到旧会话

6.4 Terminal tool 不能执行命令

6.5 sudo 在消息平台里不可用

7. Gateway 和消息平台常见错误

7.1 Bot 不回复消息

7.2 Gateway 启动失败

7.3 WSL2 中 gateway 老是断开

7.4 消息发不出去或 webhook 不通

7.5 Telegram 里显示过多工具日志和推理过程

7.6 Telegram slash command 太多

8. MCP 常见错误

8.1 MCP server not connecting

8.2 MCP 工具不显示

8.3 WSL2 调 Windows Chrome MCP 报 UNC 路径问题

9. Browser、文件和终端能力常见错误

9.1 browser tool 无法打开页面

9.2 agent 改错文件或找不到文件

9.3 Docker backend 不工作

10. 更新、卸载、重装常见错误

10.1 hermes update 失败

10.2 卸载后重装仍然带旧配置

10.3 root 安装和普通用户安装混乱

11. Termux/Android 常见错误

11.1 安装 voice/all extra 失败

11.2 手机端后台运行不稳定

12. 安全相关常见错误

12.1 把 API key 提交到 Git

12.2 Gateway 开放给所有人

12.3 给 agent 过大权限

13. 一页式错误速查表

14. 建议的稳定使用方式

评论

评论列表

微信小程序

QQ小程序

关于作者

3.1 `hermes: command not found`

3.3 `git: command not found`

3.4 `Permission denied`

3.5 `ModuleNotFoundError: No module named 'dotenv'`

4.2 WSL2 中 `hermes` 找不到

4.4 `bad interpreter: /bin/bash^M`

5.1 `API key not set`

6.3 `hermes --continue` 找不到旧会话

6.5 `sudo` 在消息平台里不可用

10.1 `hermes update` 失败