適用日期：2026-05-19

適用對(duì)象：Hermes Agent 的 Windows、WSL2、macOS、Linux、Termux 用戶。

使用方式：先看“快速排障流程”，再按錯(cuò)誤現(xiàn)象查對(duì)應(yīng)章節(jié)。

重要提醒：Hermes Agent 更新較快，命令和平臺(tái)能力可能變化。遇到不一致時(shí)，以官方文檔和 hermes --help、hermes doctor 輸出為準(zhǔn)。

1. 快速排障流程

遇到問題時(shí)，不要一開始就重裝。建議按這個(gè)順序排查：

hermes --version
hermes doctor
hermes config show
hermes dump

如果是網(wǎng)關(guān)、消息平臺(tái)或后臺(tái)服務(wù)問題，再加：

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

如果是模型/API 問題：

hermes model
hermes chat -q "hello"

如果是 Windows/WSL2 問題，先確認(rèn)自己在哪個(gè)系統(tǒng)里：

uname -a
pwd
which hermes

PowerShell 中：

wsl --list --verbose
where hermes

2. 常用診斷命令

3. 安裝階段常見錯(cuò)誤

3.1hermes: command not found

現(xiàn)象

安裝完成后執(zhí)行 hermes，提示命令不存在。

常見原因

• 當(dāng)前 shell 還沒有重新加載 PATH；
• ~/.local/bin 沒有加入 PATH；
• Windows 原生安裝后沒有重新打開 PowerShell；
• 服務(wù)用戶的 PATH 極簡(jiǎn)，不包含 Hermes launcher；
• 誤執(zhí)行了源碼目錄里的 hermes 文件，而不是虛擬環(huán)境里的 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

如果剛安裝完，關(guān)閉所有 PowerShell/Windows Terminal 窗口后重新打開。

3.2 安裝腳本下載失敗

現(xiàn)象

curl -fsSL ... | bash 報(bào)網(wǎng)絡(luò)錯(cuò)誤、DNS 錯(cuò)誤、TLS 錯(cuò)誤、連接超時(shí)。

常見原因

• 當(dāng)前網(wǎng)絡(luò)無(wú)法訪問 GitHub raw 域名；
• 代理沒有配置到 shell；
• 公司/校園網(wǎng)絡(luò)攔截；
• 系統(tǒng)證書過舊。

解決方案

先驗(yàn)證訪問：

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

如果失敗：

• 換網(wǎng)絡(luò)或配置代理；
• 確認(rèn)系統(tǒng)時(shí)間正確；
• 更新證書包：

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

macOS 可先確認(rèn) curl 和 Git 可用：

git --version
curl --version

3.3git: command not found

現(xiàn)象

安裝腳本提示找不到 Git。

解決方案

Ubuntu/Debian/WSL2：

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

macOS：

xcode-select --install

或：

brew install git

Windows 原生安裝器通常會(huì)優(yōu)先使用已有 Git；沒有時(shí)會(huì)下載 PortableGit。若 PortableGit 下載失敗，優(yōu)先排查網(wǎng)絡(luò)。

3.4Permission denied

現(xiàn)象

安裝或運(yùn)行時(shí)出現(xiàn)權(quán)限不足。

常見原因

• 把 Hermes 安裝在系統(tǒng)目錄；
• 對(duì) ~/.hermes 或 ~/.local/bin 沒有寫權(quán)限；
• WSL2 項(xiàng)目放在 /mnt/c/...，權(quán)限位不正常；
• 用 root 安裝后又用普通用戶運(yùn)行。

解決方案

普通個(gè)人使用建議安裝在普通用戶目錄，不要默認(rèn) sudo 安裝。

檢查權(quán)限：

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

修復(fù)當(dāng)前用戶目錄權(quán)限：

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

WSL2 中盡量把項(xiàng)目放在 Linux 文件系統(tǒng)，例如：

mkdir -p ~/projects
cd ~/projects

3.5ModuleNotFoundError: No module named 'dotenv'

現(xiàn)象

執(zhí)行 hermes 后出現(xiàn) Python 模塊缺失，例如 dotenv。

常見原因

官方文檔指出，這通常是調(diào)用了源碼目錄里的 ~/.hermes/hermes-agent/hermes，而不是虛擬環(huán)境里的 Hermes launcher。

解決方案

檢查當(dāng)前命令路徑：

which hermes

優(yōu)先使用：

~/.local/bin/hermes

或虛擬環(huán)境 launcher：

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

如果是服務(wù)用戶，確保 PATH 包含 ~/.local/bin。

3.6 Playwright/Chromium 安裝失敗

現(xiàn)象

安裝時(shí)瀏覽器依賴失敗，或 browser tool 無(wú)法啟動(dòng)。

常見原因

• Linux 缺少 Chromium 系統(tǒng)庫(kù)；
• 用戶沒有 sudo；
• Playwright 瀏覽器下載被網(wǎng)絡(luò)攔截；
• 服務(wù)器是 headless 環(huán)境，但沒有相關(guān)依賴。

解決方案

有 sudo 的 Debian/Ubuntu：

sudo npx playwright install-deps chromium

無(wú) sudo 的服務(wù)用戶：讓管理員先執(zhí)行上面的系統(tǒng)庫(kù)安裝，再用服務(wù)用戶安裝 Hermes。

如果暫時(shí)不需要瀏覽器能力，可以跳過：

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

3.7 Windows 原生安裝后功能異常

現(xiàn)象

PowerShell 可以運(yùn)行 hermes，但 terminal tool、browser tool、編碼、路徑或 dashboard chat terminal 異常。

說明

官方文檔將 Windows 原生支持標(biāo)注為 early beta。多數(shù) CLI、gateway、cron、browser tool、MCP 能力可原生運(yùn)行，但 dashboard 的 /chat 終端面板依賴 POSIX PTY，仍需要 WSL2。

解決方案

優(yōu)先判斷是否應(yīng)該改用 WSL2：

• 要做 POSIX/Linux 開發(fā)：推薦 WSL2；
• 要使用 dashboard 內(nèi)嵌終端：推薦 WSL2；
• 只是 PowerShell 里聊天、跑 gateway、跑 MCP：原生 Windows 可以嘗試。

編碼問題可臨時(shí)嘗試：

$env:HERMES_DISABLE_WINDOWS_UTF8="1"
hermes doctor

4. Windows/WSL2 常見錯(cuò)誤

4.1 在 WSL1 中安裝導(dǎo)致不穩(wěn)定

現(xiàn)象

命令能跑但經(jīng)常出現(xiàn)信號(hào)、網(wǎng)絡(luò)、進(jìn)程、文件權(quán)限異常。

原因

Hermes 更適合 WSL2。WSL1 的 Linux syscall、網(wǎng)絡(luò)和 procfs 行為與真實(shí) Linux 有差異。

解決方案

PowerShell：

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

4.2 WSL2 中hermes找不到

現(xiàn)象

在 Windows PowerShell 中能運(yùn)行，進(jìn)入 WSL2 后找不到；或反過來(lái)。

原因

Windows 原生 Hermes 和 WSL2 Hermes 是兩套安裝，數(shù)據(jù)目錄也不同：

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

解決方案

在你真正要使用的環(huán)境中單獨(dú)安裝和配置。不要假設(shè) Windows 的 hermes 會(huì)自動(dòng)出現(xiàn)在 WSL2。

WSL2 內(nèi)安裝：

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

4.3 WSL2 下運(yùn)行很慢

現(xiàn)象

git status、rg、Hermes 搜索文件、讀寫項(xiàng)目都很慢。

常見原因

項(xiàng)目放在 /mnt/c/Users/...。WSL2 訪問 Windows 文件系統(tǒng)會(huì)經(jīng)過跨邊界協(xié)議，I/O、權(quán)限和文件監(jiān)聽都更容易出問題。

解決方案

把 Linux 側(cè)開發(fā)項(xiàng)目放到 WSL2 文件系統(tǒng)：

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

只有確實(shí)需要 Windows GUI 程序直接訪問時(shí)，才把文件放到 /mnt/c/...。

4.4bad interpreter: /bin/bash^M

現(xiàn)象

腳本在 WSL2/Linux 中運(yùn)行時(shí)報(bào)：

bad interpreter: /bin/bash^M

原因

文件是 Windows CRLF 行尾。

解決方案

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

建議在 WSL2 內(nèi)設(shè)置 Git：

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

4.5 WSL2 訪問 Windows 上的 Ollama/LM Studio 失敗

現(xiàn)象

Hermes 配置本地模型后，連接 Windows 上的 Ollama、LM Studio、llama-server 報(bào) Connection refused。

常見原因

• WSL2 里的 localhost 不一定等于 Windows 的 localhost；
• Windows 上的模型服務(wù)只綁定 127.0.0.1；
• Windows 防火墻阻擋端口；
• 沒有啟用 mirrored networking。

解決方案

Windows 11 22H2+ 可考慮開啟 WSL mirrored networking。舊環(huán)境通常需要讓 Windows 模型服務(wù)監(jiān)聽 0.0.0.0，并放行端口。

以 Ollama 為例，確保服務(wù)綁定到可被 WSL 訪問的地址，例如設(shè)置：

OLLAMA_HOST=0.0.0.0

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

4.6 WSL2 睡眠后 HTTPS/OAuth 報(bào)錯(cuò)

現(xiàn)象

電腦睡眠/休眠后，Hermes 調(diào) API、OAuth 或 HTTPS 證書相關(guān)請(qǐng)求失敗。

原因

WSL2 時(shí)鐘可能漂移。

解決方案

sudo hwclock -s

或安裝時(shí)間同步工具，在 WSL2 登錄時(shí)同步時(shí)間。

5. 配置和模型常見錯(cuò)誤

5.1API key not set

現(xiàn)象

Hermes 啟動(dòng)聊天時(shí)報(bào) API key 沒配置。

解決方案

推薦用向?qū)В?/p>

hermes model

或檢查配置：

hermes config show

直接設(shè)置示例：

hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx

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

5.2 API key 有但仍不可用

現(xiàn)象

明明設(shè)置了 key，仍然 401、403、invalid key、provider authentication failed。

常見原因

• key 屬于另一個(gè) provider；
• key 已過期或額度不足；
• .env 中有舊 key 覆蓋新配置；
• 使用了代理平臺(tái)，但 base URL/model name 寫錯(cuò)；
• provider 賬號(hào)沒有對(duì)應(yīng)模型權(quán)限。

解決方案

hermes config show
hermes model

檢查本地環(huán)境文件是否有沖突：

cat ~/.hermes/.env

如果是 OpenRouter，確認(rèn)賬戶余額、模型 ID、模型權(quán)限和 API key。

5.3 首次運(yùn)行 HTTP 400

現(xiàn)象

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

常見原因

官方 FAQ 中說明，這通常是模型名不匹配、模型不存在、API key 沒權(quán)限訪問該模型，或 OpenRouter 模型 ID 寫錯(cuò)。

解決方案

查看當(dāng)前 provider/model：

hermes config show | head -20

重新選擇模型：

hermes model

用一個(gè)已知可用模型測(cè)試：

hermes chat -q "hello"

如果通過 OpenRouter，確認(rèn) key 有額度，并且模型 ID 沒有拼寫錯(cuò)誤。

5.4 本地模型連接不上

現(xiàn)象

使用 Ollama、LM Studio、vLLM、SGLang、本地 OpenAI-compatible 服務(wù)時(shí)連接失敗。

常見原因

• base URL 不符合 OpenAI-compatible 格式；
• 服務(wù)沒啟動(dòng)；
• WSL2/Windows 網(wǎng)絡(luò)邊界沒處理；
• 模型服務(wù)只監(jiān)聽 127.0.0.1；
• API key 占位不符合服務(wù)要求；
• context length 配置過大。

解決方案

先用 curl 測(cè)服務(wù)：

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

配置 Hermes：

hermes model
# 選擇 Custom endpoint
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: 實(shí)際模型名

如果 Hermes 在 WSL2、本地模型在 Windows，請(qǐng)參考 WSL2 網(wǎng)絡(luò)問題章節(jié)。

5.5 切換 profile 后配置“丟失”

現(xiàn)象

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

常見原因

• 切換了 Hermes profile；
• 設(shè)置了不同的 HERMES_HOME；
• Windows 原生和 WSL2 各有獨(dú)立數(shù)據(jù)目錄；
• 用 root 運(yùn)行后寫到了 /root/.hermes。

解決方案

檢查：

hermes dump
echo $HERMES_HOME

不要混用普通用戶和 root。確認(rèn)當(dāng)前 shell、用戶、profile 都是預(yù)期的。

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

現(xiàn)象

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

解決方案

hermes config check
hermes config migrate
hermes doctor

更新前建議備份：

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

6. 運(yùn)行階段常見錯(cuò)誤

6.1 Hermes 啟動(dòng)慢或回答慢

常見原因

• 選擇了大模型或遠(yuǎn)端 provider 延遲高；
• 會(huì)話太長(zhǎng)；
• 啟用了太多工具、MCP、skills；
• 本地模型顯存不足；
• 項(xiàng)目在 WSL2 的 /mnt/c 下。

解決方案

壓縮會(huì)話：

/compress

查看 token 使用：

/usage

減少工具：

hermes chat -t "terminal"

換更快模型：

hermes chat --model <provider/model>

WSL2 項(xiàng)目移到：

~/projects

6.2 會(huì)話太長(zhǎng)、上下文溢出

現(xiàn)象

長(zhǎng)時(shí)間使用后，模型開始遺忘、變慢或報(bào) context length 相關(guān)錯(cuò)誤。

解決方案

在 Hermes 聊天中執(zhí)行：

/compress

必要時(shí)開啟新會(huì)話：

hermes chat

恢復(fù)最近會(huì)話：

hermes chat --continue

6.3hermes --continue找不到舊會(huì)話

常見原因

• 當(dāng)前 profile 變了；
• HERMES_HOME 變了；
• Windows 原生和 WSL2 安裝混用；
• 會(huì)話沒有成功保存。

解決方案

hermes sessions list
hermes dump
echo $HERMES_HOME

確認(rèn)你在同一個(gè)用戶、同一個(gè)系統(tǒng)、同一個(gè) profile 下。

6.4 Terminal tool 不能執(zhí)行命令

常見原因

• 終端工具未啟用；
• Windows 原生 Git Bash/PortableGit 異常；
• Docker/SSH backend 未配置好；
• 當(dāng)前目錄權(quán)限不足；
• gateway 環(huán)境沒有交互式 shell。

解決方案

重新配置工具：

hermes tools

本地 shell 檢查：

pwd
whoami
which bash

Windows 原生檢查：

where bash
where git
where hermes

如果是 Docker backend：

docker info
docker run hello-world

6.5sudo在消息平臺(tái)里不可用

現(xiàn)象

Telegram/Discord/Slack gateway 中讓 Hermes 執(zhí)行 sudo，命令卡住或失敗。

原因

消息 gateway 沒有交互式終端，無(wú)法輸入 sudo 密碼。

解決方案

• 盡量不要在 messaging gateway 中執(zhí)行 sudo；
• 改用本地 hermes chat 做管理員任務(wù)；
• 如果必須自動(dòng)化，給極少數(shù)明確命令配置 passwordless sudo，不要開放全量 sudo。

7. Gateway 和消息平臺(tái)常見錯(cuò)誤

7.1 Bot 不回復(fù)消息

常見原因

• gateway 沒啟動(dòng)；
• bot token 錯(cuò)誤或過期；
• 用戶不在 allowlist；
• 平臺(tái)權(quán)限沒開；
• gateway 日志中有異常；
• WSL2 后臺(tái)服務(wù)隨 Windows 休眠/關(guān)閉而停止。

解決方案

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

重新配置：

hermes gateway setup

檢查 allowlist、bot token、平臺(tái)權(quán)限。

7.2 Gateway 啟動(dòng)失敗

常見原因

• 缺少 messaging 依賴；
• 端口沖突；
• token 配置錯(cuò)誤；
• systemd/launchd/PowerShell 后臺(tái)環(huán)境 PATH 不完整。

解決方案

檢查配置：

hermes config show

檢查端口：

lsof -i :8080

必要時(shí)安裝 messaging extra：

pip install "hermes-agent[messaging]"

如果是 macOS launchd 服務(wù)找不到 Node.js、ffmpeg 等工具，重新安裝 gateway 以刷新 PATH：

hermes gateway install
hermes gateway start

7.3 WSL2 中 gateway 老是斷開

常見原因

• WSL2 沒啟用 systemd；
• Windows 空閑后關(guān)閉 WSL；
• systemd user service 沒有隨 WSL 啟動(dòng)；
• 網(wǎng)絡(luò)/NAT 變化。

解決方案

前臺(tái)運(yùn)行：

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 后驗(yàn)證：

systemctl is-system-running

7.4 消息發(fā)不出去或 webhook 不通

常見原因

• token 過期；
• webhook 地址外網(wǎng)不可達(dá)；
• 本地端口沒有映射到公網(wǎng)；
• Slack/WhatsApp/Telegram 平臺(tái)側(cè)權(quán)限或回調(diào)配置錯(cuò)誤；
• 防火墻阻擋。

解決方案

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

如果平臺(tái)需要從公網(wǎng)訪問本機(jī)，優(yōu)先使用 cloudflared/ngrok 這類隧道，而不是直接暴露本機(jī)端口。

7.5 Telegram 里顯示過多工具日志和推理過程

現(xiàn)象

Telegram/消息平臺(tái)中出現(xiàn)大量工具調(diào)用、日志、過程信息，不只顯示最終答案。

解決方案

在 ~/.hermes/config.yaml 中調(diào)整：

display:
  tool_progress: "off"

常用選項(xiàng)：

off      只顯示最終回復(fù)
new      顯示新工具調(diào)用摘要
all      顯示所有工具活動(dòng)
verbose  顯示完整細(xì)節(jié)

修改后重啟 gateway。

7.6 Telegram slash command 太多

現(xiàn)象

技能太多，Telegram 命令菜單異?；虿糠置畈伙@示。

原因

Telegram slash command 有數(shù)量和 payload 限制。

解決方案

禁用不需要的技能，尤其是平臺(tái)級(jí)禁用：

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

修改后：

hermes gateway restart

或停止后重新運(yùn)行 gateway。

8. MCP 常見錯(cuò)誤

8.1 MCP server not connecting

常見原因

• MCP server 二進(jìn)制不存在；
• command 路徑錯(cuò)；
• Node.js/npx/Python 不在 PATH；
• 環(huán)境變量缺失；
• MCP server 自身啟動(dòng)失敗；
• 修改配置后沒有 reload。

解決方案

檢查 Node：

node --version
npx --version

手動(dòng)測(cè)試 MCP server：

npx -y @modelcontextprotocol/server-filesystem /tmp

檢查配置：

hermes config show | grep -A 12 mcp_servers

在 Hermes 會(huì)話中重新加載：

/reload-mcp

必要時(shí)安裝 MCP extra：

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

8.2 MCP 工具不顯示

常見原因

• server 沒響應(yīng) tools/list；
• 配置里 enabled、tools.include、tools.exclude 限制了工具；
• 當(dāng)前會(huì)話不支持資源/提示能力；
• 修改后未 reload；
• server 啟動(dòng)成功但鑒權(quán)失敗。

解決方案

檢查 Hermes 日志和 gateway/agent 日志；簡(jiǎn)化 MCP 配置，只保留一個(gè) server 和最小環(huán)境變量，確認(rèn)能正常列出工具后再逐步添加。

8.3 WSL2 調(diào) Windows Chrome MCP 報(bào) UNC 路徑問題

現(xiàn)象

Hermes 在 WSL2 中啟動(dòng) Windows 側(cè)二進(jìn)制，出現(xiàn) UNC path 不支持或 cwd 異常。

原因

Windows cmd.exe 不理解 WSL Linux 路徑作為當(dāng)前工作目錄。

解決方案

這類場(chǎng)景可從 /mnt/c/... 下啟動(dòng) Hermes，或?qū)?wrapper 先 cd 到 Windows 可識(shí)別路徑，再調(diào)用 Windows 程序。

9. Browser、文件和終端能力常見錯(cuò)誤

9.1 browser tool 無(wú)法打開頁(yè)面

常見原因

• Playwright/Chromium 安裝失??；
• headless 服務(wù)器缺系統(tǒng)庫(kù)；
• 網(wǎng)絡(luò)被代理/防火墻攔截；
• Windows 原生依賴 Git Bash/Node 路徑異常；
• WSL2 內(nèi)訪問 Windows localhost 地址不對(duì)。

解決方案

先運(yùn)行：

hermes doctor
node --version
npx --version

Linux 缺依賴：

sudo npx playwright install-deps chromium

WSL2 訪問 Windows 服務(wù)時(shí)，確認(rèn)網(wǎng)絡(luò)配置和綁定地址。

9.2 agent 改錯(cuò)文件或找不到文件

常見原因

• 當(dāng)前工作目錄不是項(xiàng)目目錄；
• Windows/WSL2 路徑混淆；
• 文件在 Windows，Hermes 在 WSL2；
• 使用相對(duì)路徑但當(dāng)前 cwd 不對(duì)；
• 多個(gè) profile/session 混淆。

解決方案

開始任務(wù)前讓 Hermes 確認(rèn)：

pwd
ls
git status

WSL2 下 注意路徑轉(zhuǎn)換：

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

9.3 Docker backend 不工作

現(xiàn)象

Hermes 設(shè)置 Docker terminal backend 后連接失敗。

常見原因

• Docker daemon 未啟動(dòng)；
• 當(dāng)前用戶不在 docker group；
• Docker Desktop 未運(yùn)行；
• WSL2 Docker 集成沒開；
• 鏡像/容器權(quán)限不足。

解決方案

docker info
docker run hello-world

Linux：

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

Windows/WSL2 用戶確認(rèn) Docker Desktop 已啟動(dòng)，并啟用了對(duì)應(yīng) WSL distro 集成。

10. 更新、卸載、重裝常見錯(cuò)誤

10.1hermes update失敗

常見原因

• GitHub 網(wǎng)絡(luò)不可達(dá)；
• 本地 Hermes 源碼目錄有未提交修改；
• 虛擬環(huán)境損壞；
• 權(quán)限被 root/普通用戶混用破壞。

解決方案

先備份：

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

再檢查：

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

如果你修改過源碼，先保存自己的改動(dòng)，不要直接覆蓋。

10.2 卸載后重裝仍然帶舊配置

原因

卸載程序可能只移除程序，不一定刪除所有數(shù)據(jù)。舊配置通常在：

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

解決方案

如果確認(rèn)要完全清空：

hermes uninstall --full

或手動(dòng)備份后刪除數(shù)據(jù)目錄。

10.3 root 安裝和普通用戶安裝混亂

現(xiàn)象

root 下能運(yùn)行，普通用戶不能；或配置寫到了 /root/.hermes。

解決方案

個(gè)人使用統(tǒng)一用普通用戶運(yùn)行。檢查：

whoami
which hermes
echo $HERMES_HOME

不要一會(huì)兒 sudo hermes，一會(huì)兒普通用戶 hermes。

11. Termux/Android 常見錯(cuò)誤

11.1 安裝 voice/all extra 失敗

原因

官方 FAQ 提到 Android 上完整 .[all] extra 不適用，因?yàn)椴糠终Z(yǔ)音依賴沒有 Android wheel。

解決方案

使用官方 Termux 路徑，不要強(qiáng)行安裝全量 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 上先保證基礎(chǔ)聊天可用，再考慮擴(kuò)展能力。

11.2 手機(jī)端后臺(tái)運(yùn)行不穩(wěn)定

原因

Android 電池優(yōu)化、網(wǎng)絡(luò)切換、后臺(tái)限制會(huì)影響長(zhǎng)期運(yùn)行。

解決方案

• 關(guān)閉 Termux 的電池優(yōu)化；
• 使用 tmux；
• 不建議把手機(jī)作為 24/7 gateway 生產(chǎn)環(huán)境；
• 長(zhǎng)期在線建議使用 VPS、家用服務(wù)器或穩(wěn)定桌面機(jī)器。

12. 安全相關(guān)常見錯(cuò)誤

12.1 把 API key 提交到 Git

風(fēng)險(xiǎn)

API key 一旦進(jìn)入公開倉(cāng)庫(kù)，通常應(yīng)視為泄露。

解決方案

• 立即撤銷舊 key；
• 生成新 key；
• 確認(rèn) .env、config.yaml、日志沒有被提交；
• 給項(xiàng)目 .gitignore 添加敏感文件規(guī)則。

12.2 Gateway 開放給所有人

風(fēng)險(xiǎn)

如果 bot 是 open mode，任何人都可能調(diào)用你的模型額度和本機(jī)工具。

解決方案

生產(chǎn)環(huán)境使用 allowlist 或私有 DM pairing。不要在公網(wǎng) bot 上開放 terminal、filesystem、browser 等高權(quán)限能力。

12.3 給 agent 過大權(quán)限

風(fēng)險(xiǎn)

Hermes 可以調(diào)用本機(jī)工具時(shí)，權(quán)限邊界就是當(dāng)前用戶權(quán)限。當(dāng)前用戶能刪什么、改什么，agent 理論上也可能觸達(dá)。

建議

• 初次使用放在測(cè)試目錄；
• 生產(chǎn)環(huán)境使用低權(quán)限用戶；
• 重要任務(wù)前備份；
• 高風(fēng)險(xiǎn)操作使用 Docker/SSH 隔離 backend；
• 不要用 root 長(zhǎng)期運(yùn)行。

13. 一頁(yè)式錯(cuò)誤速查表

14. 建議的穩(wěn)定使用方式

1. Windows 用戶優(yōu)先用 WSL2，除非明確只需要原生 PowerShell 使用。
2. WSL2 項(xiàng)目放在 ~/projects，不要長(zhǎng)期在 /mnt/c/... 里做 Linux 開發(fā)。
3. 先讓 CLI + 一個(gè)模型穩(wěn)定工作，再配置 gateway、MCP、skills、browser。
4. Gateway 生產(chǎn)使用必須設(shè)置 allowlist。
5. 出問題先跑 hermes doctor 和 hermes dump，再考慮重裝。
6. 重裝前備份 ~/.hermes 或 %LOCALAPPDATA%\hermes。
7. 長(zhǎng)會(huì)話定期 /compress。
8. 不要長(zhǎng)期用 root 跑 Hermes。

到此這篇關(guān)于Hermes Agent安裝、運(yùn)行、使用常見錯(cuò)誤總結(jié)與解決方案的文章就介紹到這了,更多相關(guān)Hermes Agent安裝內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論