Hermes 全網問題百寶箱：從裝不上到接不通，80 個坑我替你踩完了 | 保姆教程 03
整理版優先睇
本文係 Hermes 工具嘅全面排坑手冊，涵蓋安裝、配置模型同接入聊天軟件三大階段，提供遞進式解法，適合新手同升級用戶快速對照解決問題。
呢篇文章係 NousResearch 團隊為 Hermes 工具寫嘅第三篇保姆教程，但唔係一般教學，而係一本「問題百科」。作者親身踩過超過 80 個坑，按發生順序排好，每個坑都畀出遞進式解法——A 方法唔得就試 B，唔會塞死喺一條路。
文章覆蓋三大階段：安裝（30 個坑）、配置模型同 API（25 個坑）、接入聊天軟件（25 個坑），再加一個兜底篇教終極自查同睇日誌。無論你用 Mac、Windows WSL2 定 Linux，遇到咩報錯都可以喺度揾到對應解法。整體結論係：只要你肯逐個坑試，冇搞唔掂嘅問題。
建議做法：先快速睇一次目錄，記低邊啲部分同自己有關；遇到具體錯誤就 Ctrl+F 搜關鍵詞，唔使由頭讀到尾。標記好呢篇文，以後每次裝機或者升級都翻返嚟對照。
- 結論：Hermes 安裝配置過程最常見嘅 80 個坑已經有完整對應解法，唔使再周圍問人。
- 方法：遞進式解法——A 方案唔得就試 B，B 唔得就試 C，確保唔會走入死衚衕。
- 差異：香港用戶特別要注意網絡唔順同 WSL2 設定，尤其係 GitHub 連線同 Docker Hub 鏡像加速。
- 啟發：配置模型之前一定要搞清楚 Provider、API Key 同模型嘅關係，分清楚呢三個概念就唔會配錯。
- 可行動點：遇到任何報錯先用「終極自查五步法」，再睇日誌截圖攞去社羣求助，有效率嘅求助先有人幫。
內容片段
┌─────────────────────────────────────────────────┐│ WslRegisterDistribution failed with error: ││ 0x80370102 ││ Please enable the Virtual Machine Platform... │└─────────────────────────────────────────────────┘安裝階段最易中招嘅 30 個陷阱
安裝之前記得先檢查 Git 有冇裝好（git --version）。如果冇裝，Mac 用 xcode-select --install，Ubuntu 用 sudo apt install git。
常見網絡報錯有 curl: (6) Could not resolve host（DNS 問題）同 curl: (28) Connection timed out（握手超時）。前者可以換網絡或者用海外 VPS，後者可以重試幾次或者改 DNS 做 8.8.8.8。
如果係 Mac M 系列晶片，裝完可能遇到 bad CPU type in executable，因為裝錯 Intel 版本。解決方法係裝 Rosetta 2 或者直接剷咗重新安裝 arm64 版本。
Windows 用戶一定要用 WSL2，唔可以喺 CMD 或 PowerShell 直接裝。裝 WSL2 之後如果 Ubuntu 開唔到，試嚇 wsl --update 更新內核。另外 WSL2 默認放 C 盤，好易令 C 盤空間暴漲，建議移到 D 盤。
- 1 裝完之後 hermes --version 報 command not found：先 source ~/.bashrc 或 ~/.zshrc，再唔得就手動加 PATH 或者用 sudo ln -s 創建軟連結。
- 2 hermes doctor 報紅叉係正常體檢，跟住提示裝嘢就得。如果卡住就用 hermes doctor --offline。
- 3 Python 版本太低（<3.11）會報錯，Ubuntu 要用 deadsnakes PPA 裝新版本，Mac 用 brew install python@3.11。
- 4 Node.js 係可選，但建議用 nvm 裝 Node 22 以備不時之需。
模型配置同 API 整合嘅 25 個常見障礙
建議首選 DeepSeek，平、國內直連、模型質素好。去 platform.deepseek.com 註冊，喺「API Keys」度創建 key，記住要另外充值（聊天網頁嘅免費額度唔通用）。
其他 Provider 包括 阿里雲百鍊（用 custom provider + OpenAI 兼容端點）、智譜 GLM、Kimi Moonshot、OpenRouter（一個 key 接海外模型）。OpenRouter 需要境外支付。
跑 hermes model 會進入交互式嚮導，用方向鍵選擇 Provider，跟住輸入 API Key 同模型名。如果揀 Custom OpenAI-compatible endpoint，要填 Base URL。
- 如果 API Key 無效，檢查有冇充值夠錢，或者 Key 係咪複製漏咗字符。
- 模型名寫錯係常見錯誤，例如 deepseek-chat 寫成 deepseek-chat-v2。
- Token limit 超限時，試嚇用更長上下文嘅模型版本，或者改短啲系統提示詞。
- Ollama 本地模型要注意啟動咗服務先，而且模型名要同 ollama list 顯示嘅一致。
接入聊天軟件同最終排查
飛書接入有 8 個常見坑，包括 創建應用冇配權限、事件訂閲 URL 填錯、白名單 IP 冇加。企業微信要注意 掃碼綁定失敗 同 消息回調地址驗證。
Telegram Bot 要特別小心 Token 被複製多咗空格，同埋 webhook 模式需要裝依賴 Flask 之類。如果 Bot 唔回消息，先 睇日誌（hermes logs），睇下有冇報錯。
- 1 終極自查五步法：第一步 check Gateway 狀態；第二步 check API Key 同模型配置；第三步 check 聊天軟件後台白名單；第四步睇日誌；第五步重啟服務。
- 2 如果日誌都睇唔明，截圖去 Hermes 社羣求助，記得附上 hermes doctor 輸出同錯誤訊息。
- 3 升級到 v0.13 要留意舊 config.yaml 可能失效，建議重新用 hermes model 配一次，唔好直接抄舊配置。
這一篇不是教程。這是一本工具書。 你裝 Hermes 的時候、配模型的時候、接聊天軟件的時候——遇到任何報錯，Ctrl+F 搜關鍵詞就能找到解法。 建議先收藏，再慢慢看。
寫在最前面：這篇寫給誰看
先自我定位。如果你符合下面任何一條，這篇就是為你寫的：
點開了前兩篇，看懂了大概，但動手裝的時候就卡殼了 裝上了 Hermes，配模型的時候一直報錯，試了七八種方法都不行 模型配好了，接飛書 / 企業微信 / 其它聊天軟件一直連不上，Bot 在羣裏像死機 你壓根不懂什麼是終端，看到別人講命令行就頭皮發麻，但又確實想用上 AI 助手 你已經是老玩家，但最近升級到 v0.13 後舊配置突然全壞了
這篇把 Hermes 最全的坑按發生順序排了一遍，每一個坑都給出遞進式解法。
遞進式解法什麼意思？就是：A 方法不行試 B，B 不行試 C，C 不行還有 D——不會讓你走進死衚衕。
文章很長。建議做法：
先通讀一遍目錄，心裏有底 遇到具體報錯再回來 Ctrl+F 搜關鍵詞 收藏起來，以後每次翻就像翻字典
🗺️ 全文目錄（Ctrl+F 可跳轉）
第一部分 · 安裝階段的 30 個坑
準備篇：終端是什麼？怎麼打開？ 安裝前的必查項 安裝命令本身的報錯 裝完之後的 command not found依賴缺失與版本問題 Mac / Linux / WSL2 各自的平台坑
第二部分 · 配置模型與 API 的 25 個坑
先搞懂：Provider、API Key、模型 是什麼關係 去哪註冊 API Key（6 個主流 Provider 註冊路徑） hermes model/hermes setup嚮導踩坑API Key 無效、過期、充值未到賬 模型名寫錯的 5 種常見情況 Token limit 超限、上下文不足 連不上模型服務的 N 種情況 Ollama 本地模型的經典坑
第三部分 · 接入聊天軟件的 25 個坑
Gateway 基本原理 飛書：從創建應用到 Bot 上線的 8 個坑 企業微信：掃碼綁定失敗、消息不回、白名單問題 釘釘 Stream 模式的 4 個坑 Telegram：Token 被複制 8 遍、webhook 依賴缺失 接入後"Bot 不回消息"的 10 種排查路徑
第四部分 · 兜底篇
終極自查五步法 日誌怎麼看、怎麼截圖給別人看 哪裏能快速拿到幫助 升級到 v0.13 的小心事項
第五部分 · 下篇預告
🧰 第一部分 · 安裝階段的 30 個坑
準備篇 · 你得先會"打開終端"
Hermes 是一個命令行工具。不懂沒關係，先學會打開"終端"這個黑框框。
Mac 用戶怎麼打開終端
按住鍵盤上的 ⌘ + 空格鍵 → 彈出搜索框 → 輸入"終端"或"Terminal" → 回車。
屏幕上會彈出一個黑色（或白色）窗口，光標在閃。這就是終端。 你之後所有命令都在這裏敲。
Windows 用戶怎麼打開終端
先說結論：Hermes 官方明確表示不支持 Windows 原生安裝。Windows 用戶必須先裝 WSL2（一個住在 Windows 裏的 Linux 子系統），然後在 WSL2 裏操作。
裝 WSL2 的方法：
按 Win 鍵，搜"PowerShell"右鍵 PowerShell → "以管理員身份運行" 粘貼下面這行，回車：
wsl --install
等它跑完，重啓電腦 開機後會自動彈出 Ubuntu 窗口，讓你設用戶名和密碼（密碼不會顯示，盲打） 以後你的"終端"就是這個 Ubuntu 窗口
⚠️ 之後文章裏所有涉及終端的命令，Windows 用戶一律在 Ubuntu 窗口裏跑，不要跑在 CMD 或 PowerShell。
【坑 001】WSL2 裝不上，報 0x80370102
終端裏看到這樣的提示：
┌─────────────────────────────────────────────────┐
│ WslRegisterDistribution failed with error: │
│ 0x80370102 │
│ Please enable the Virtual Machine Platform... │
└─────────────────────────────────────────────────┘
原因：你電腦的 BIOS 裏虛擬化功能沒開。
解決：
重啓電腦，按 F2 / F10 / Delete（不同品牌鍵不同）進 BIOS 在 BIOS 裏找 "Virtualization" 或 "Intel VT-x" / "AMD-V"，改成 Enabled 保存退出，重啓 回到 Windows，重新執行 wsl --install
還是不行？ 有些老電腦 CPU 根本不支持虛擬化，這種情況換電腦或租個海外服務器。
【坑 002】WSL2 裝好了，但 Ubuntu 啓動不了
症狀：雙擊 Ubuntu 圖標，窗口一閃就沒了。
遞進式解法：
方法 A（先試）：
打開 PowerShell 管理員權限，跑：
wsl --update
更新 WSL 內核，再重試啓動 Ubuntu
方法 B（A 不行再試）：
PowerShell 裏跑：
wsl --shutdown
wsl -d Ubuntu
強制關閉並重新進入 Ubuntu
方法 C（B 還不行）：
徹底卸載重裝：
wsl --unregister Ubuntu
wsl --install -d Ubuntu
方法 D（C 還不行）：
Windows 版本太舊。升級到 Windows 11 或 Windows 10 最新版。
【坑 003】終端打開了，但看到一行紅字 Restricted
這是 zsh 在給你警告，不是報錯。
看到的內容大概這樣：
┌────────────────────────────────────────────────────────┐
│ [oh-my-zsh] Insecure completion-dependent directories │
│ detected: │
│ zsh compinit: insecure directories, run compaudit │
└────────────────────────────────────────────────────────┘
解決：敲一行：
compaudit | xargs chmod g-w
中文解釋：compaudit 檢查有安全風險的目錄，xargs chmod g-w 把這些目錄的"組可寫"權限去掉。
跑完關掉終端重新開一個，警告就沒了。
【坑 004】安裝前檢查 Git（很多人跳過這一步）
Hermes 安裝過程要用 Git 從 GitHub 拉代碼。先檢查本機有沒有：
git --version
中文解釋：顯示 Git 的版本號。
三種可能輸出：
情況 A： git version 2.xx.x→ 有，繼續下一步情況 B： command not found: git→ 沒裝，見下方情況 C：彈窗問"要不要安裝命令行工具" → Mac 用戶點"安裝"，等幾分鐘
情況 B 的解決：
Mac 用戶：
xcode-select --install
Ubuntu / Debian / WSL2 用戶：
sudo apt update
sudo apt install -y git
CentOS / AlmaLinux 用戶：
sudo dnf install -y git
【坑 005】終於開始裝 Hermes，但 curl 命令一跑就報錯
你跑了官方安裝命令：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
然後看到紅字：
┌──────────────────────────────────────────────────────┐
│ curl: (6) Could not resolve host: │
│ raw.githubusercontent.com │
└──────────────────────────────────────────────────────┘
原因：網絡連不上 GitHub。這和你的命令沒關係，是網絡問題。
遞進式解法：
方案 A（最穩）：
換一個能穩定連 GitHub 的網絡環境
如果在家裏用寬帶連不上，去咖啡店 / 公司 WiFi 試一下
方案 B（折騰派）：
用一台海外服務器裝（香港 / 新加坡 / 日本 / 美國節點）
Vultr / DigitalOcean / Hetzner / 騰訊雲海外 / 阿里雲海外均可
方案 C（有工具的）：
自己配代理後再跑：
export https_proxy=http://你的代理地址:端口
export http_proxy=http://你的代理地址:端口
之後再跑 curl 安裝命令
方案 D（最後的辦法）：
手動下載安裝腳本。先訪問：
https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh
把內容保存成 install.sh，再本地跑：
bash install.sh
【坑 006】curl: (28) Failed to connect, connection timed out
終端顯示：
┌──────────────────────────────────────────────────────┐
│ curl: (28) Failed to connect to │
│ raw.githubusercontent.com port 443: Connection │
│ timed out │
└──────────────────────────────────────────────────────┘
原因：網絡通，但握手超時。通常是間歇性網絡問題。
解決：
步驟 1：重試 2-3 次
curl -fsSL https://raw.githubusercontent.com/... | bash
步驟 2：換 DNS
Mac：系統設置 → 網絡 → 高級 → DNS → 改成 8.8.8.8 和 1.1.1.1
Linux：
sudo nano /etc/resolv.conf
改成：
nameserver 8.8.8.8
nameserver 1.1.1.1
步驟 3：如果公司網絡限制嚴，回到坑 005 的方案 B 或 C
【坑 007】curl: (35) SSL certificate problem
┌──────────────────────────────────────────────────────┐
│ curl: (35) SSL certificate problem: │
│ unable to get local issuer certificate │
└──────────────────────────────────────────────────────┘
原因：本機 SSL 證書庫太舊或被替換了（可能用過某些代理工具改過證書）。
解決：
Mac 用戶：
brew install ca-certificates
Ubuntu 用戶：
sudo apt install -y ca-certificates
sudo update-ca-certificates
還是不行？臨時跳過證書驗證（僅做應急用，不推薦長期這樣）：
curl -k -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
-k 參數的中文意思是"不校驗 SSL 證書"。
【坑 008】安裝腳本跑到一半卡死在下載 Python
終端裏一直顯示：
Downloading Python 3.11...
(卡住不動 5 分鐘以上)
原因：Python 安裝包下載慢，或被牆。
解決：
# 按 Ctrl+C 先中斷
# 然後手動裝 Python 3.11，再重跑安裝腳本
Mac 用戶先裝 Homebrew（如果沒裝過）：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
然後裝 Python：
brew install python@3.11
Ubuntu 用戶：
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3-pip
裝完再回來跑 Hermes 安裝腳本。
【坑 009】裝到一半報 Permission denied
┌──────────────────────────────────────────────────────┐
│ mkdir: cannot create directory '/opt/hermes': │
│ Permission denied │
└──────────────────────────────────────────────────────┘
原因：你在一個你沒權限寫入的目錄跑了安裝腳本。
解決：
不要用 sudo 跑 Hermes 安裝腳本。 Hermes 是用戶級工具，要裝在你自己的家目錄（~/.hermes/），不是系統目錄。
正確做法：
# 先回到家目錄
cd ~
# 再跑安裝命令
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
【坑 010】裝完之後，hermes --version 報 command not found
這是小白裝完之後最經典的恐慌瞬間。你以為裝失敗了，其實 99% 情況下只是——
終端還沒重新加載配置，不知道去哪找 hermes 命令。
遞進式解法（按順序試，成功一步就停）：
第 1 步：告訴終端重新加載配置
先看看你用的是 bash 還是 zsh：
echo $SHELL
結果是 /bin/bash → 跑：source ~/.bashrc
結果是 /bin/zsh → 跑：source ~/.zshrc
之後再試：hermes --version
第 2 步：關掉終端窗口，重新打開一個
這能解決一大半"重載不成功"的問題
第 3 步：檢查 hermes 二進制是否真的存在
ls ~/.hermes/bin/hermes
有 → 繼續第 4 步
沒有 → 安裝真的失敗了，去看坑 005-008 網絡/證書問題
第 4 步：手動把 hermes 加進 PATH
echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
（zsh 用戶把 .bashrc 改成 .zshrc）
第 5 步：上面全無效，重新跑一遍安裝腳本
curl -fsSL https://.../install.sh | bash
【坑 011】裝完 command not found + 手動加 PATH 也不行
你按坑 010 做了所有步驟，還是不行。
終極排查：
# 第一步：看 PATH 裏到底有沒有 ~/.hermes/bin
echo $PATH | tr ':' '\n'
中文解釋：顯示你當前 PATH 的所有目錄，每行一個。
如果輸出裏沒看到 ~/.hermes/bin 或 /Users/你名字/.hermes/bin：
# 直接給 hermes 建一個"快捷方式"到系統路徑
sudo ln -s ~/.hermes/bin/hermes /usr/local/bin/hermes
中文解釋：ln -s 是創建"軟連結"，把 ~/.hermes/bin/hermes 這個文件的一個入口放到 /usr/local/bin/hermes。
之後就能在任何終端裏直接敲 hermes 了。
【坑 012】Mac 用戶：M 系列芯片裝完報 bad CPU type
┌──────────────────────────────────────────────────────┐
│ bad CPU type in executable: hermes │
└──────────────────────────────────────────────────────┘
原因：你的 Mac 是 Apple Silicon（M1/M2/M3/M4）芯片，但裝到的是 Intel 版本的二進制。
解決：
# 先確認你的 Mac 架構
uname -m
輸出 arm64= Apple Silicon輸出 x86_64= Intel
如果是 arm64 但跑了 Intel 版：
# 裝 Rosetta 2（讓 Intel 程序也能跑）
softwareupdate --install-rosetta --agree-to-license
或者更乾淨的方法——卸載重裝，讓安裝腳本自動識別你的架構：
rm -rf ~/.hermes
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
【坑 013】裝完之後，hermes doctor 報一堆紅叉
這不是 bug，這是 Hermes 在幫你體檢。
跑：
hermes doctor
輸出可能長這樣：
┌─────────────────────────────────────────────────────┐
│ Running health check... │
│ │
│ ✓ Python 3.11.x detected │
│ ✓ Node.js 22.x detected │
│ ✗ ripgrep not found │
│ ✗ ffmpeg not found │
│ ✗ No provider configured │
│ │
│ Suggested fixes: │
│ brew install ripgrep ffmpeg │
│ hermes model │
└─────────────────────────────────────────────────────┘
每一條紅叉下面都會告訴你怎麼修。照着做就行。
常見紅叉一一對應：
ripgrep not found | brew install ripgrep / Ubuntu: sudo apt install ripgrep | |
ffmpeg not found | brew install ffmpeg / Ubuntu: sudo apt install ffmpeg | |
No provider configured | hermes model | |
Python version too low | ||
PATH issue detected |
【坑 014】hermes doctor 卡住不動
跑 hermes doctor，終端光標一直在閃，什麼也不輸出。
原因：它在聯網檢查更新，網絡不通所以卡住。
解決：
# 按 Ctrl+C 中斷，用 offline 模式
hermes doctor --offline
--offline 參數的意思是"不聯網檢查"，只做本地體檢。
如果這個版本里沒這個參數，直接跳過 hermes doctor，往後走。不檢查也能用。
【坑 015】Ubuntu 用戶：apt install 本身就報錯
┌──────────────────────────────────────────────────────┐
│ E: Could not get lock /var/lib/dpkg/lock-frontend │
│ Another process is using the Package Manager. │
└──────────────────────────────────────────────────────┘
原因：另一個程序正在用 apt（比如系統自動更新在後台跑）。
解決：
# 等 5 分鐘，讓它自己跑完
# 或者強制殺掉：
sudo killall apt apt-get
sudo rm /var/lib/dpkg/lock-frontend
sudo rm /var/lib/dpkg/lock
sudo dpkg --configure -a
之後再跑你想裝的東西。
【坑 016】Python 版本過低報錯
┌──────────────────────────────────────────────────────┐
│ ERROR: Hermes Agent requires Python 3.11 or higher │
│ Found: Python 3.8.10 │
└──────────────────────────────────────────────────────┘
解決路徑：
Ubuntu 用戶：
# 加一個能裝 Python 3.11 的源
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install -y python3.11 python3.11-venv
Mac 用戶（已裝 Homebrew）：
brew install python@3.11
裝完之後一定要讓系統認這個新版本：
# 看看 python3 現在指向哪個版本
python3 --version
如果還是老版本，在 ~/.bashrc 或 ~/.zshrc 末尾加一行：
alias python3="/usr/local/bin/python3.11"
然後：
source ~/.bashrc # 或 source ~/.zshrc
【坑 017】Node.js 沒裝或版本過低
┌──────────────────────────────────────────────────────┐
│ ERROR: Node.js 20+ required │
└──────────────────────────────────────────────────────┘
Node.js 在 Hermes 裏是可選的（只有用瀏覽器工具時才用到），但裝上更省心。
推薦用 nvm 裝（能裝多個版本，隨時切）：
# 裝 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 重載終端
source ~/.bashrc # 或 ~/.zshrc
# 裝 Node 22（Hermes 推薦）
nvm install 22
# 用 22
nvm use 22
【坑 018】uv: command not found
uv 是 Hermes 用的新式 Python 包管理器。
# 手動裝 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc # 或 ~/.zshrc
裝完驗證：
uv --version
【坑 019】磁盤空間不足
┌──────────────────────────────────────────────────────┐
│ No space left on device │
└──────────────────────────────────────────────────────┘
Hermes 本體 + 依賴大約 2-3 GB。
# 看看哪裏佔空間
df -h
中文解釋：df 是"disk free"的縮寫，-h 讓數字用人類可讀的方式顯示（GB/MB）。
空間不夠的話：
# 清理 apt 緩存（Ubuntu）
sudo apt clean
sudo apt autoremove
# 清理 brew 緩存（Mac）
brew cleanup -s
【坑 020】WSL2 裏裝 Hermes，C 盤空間暴漲
症狀：WSL2 裏裝完 Hermes，你 Windows C 盤少了 10GB。
原因：WSL2 的 Ubuntu 子系統默認放在 C 盤，裏面裝什麼都算 C 盤。
解決：把 WSL2 移到 D 盤。
在 PowerShell（管理員）裏：
# 1. 先停掉 WSL
wsl --shutdown
# 2. 導出當前 Ubuntu
wsl --export Ubuntu D:\wsl-backup\ubuntu.tar
# 3. 註銷
wsl --unregister Ubuntu
# 4. 在 D 盤重新導入
wsl --import Ubuntu D:\wsl-ubuntu D:\wsl-backup\ubuntu.tar
之後 Ubuntu 就住在 D 盤，C 盤空間馬上釋放。
【坑 021】Mac 用戶：launchd 自動啓動不繼承 PATH
這是所有 Mac Hermes 用戶遲早要踩的大坑。
你想開機自啓 Hermes，跑了 launchd，發現它啓動失敗，報 hermes: command not found——但你在終端裏能用。
原因：launchd 啓動的進程不繼承你終端裏的 PATH。
解決：在 launchd 的 plist 配置裏顯式寫出完整路徑。
例如：
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/Users/你的用戶名/.hermes/bin:/usr/local/bin:/usr/bin:/bin</string>
</dict>
不推薦新手碰 launchd。最省心的方案是用 Docker 跑 Hermes，Docker Desktop 在"開機自啓"裏勾選就行。
【坑 022】WSL2 用戶：systemd 不穩定
現象：在 WSL2 裏用 systemd 常駐 Hermes Gateway，過一段時間莫名其妙死掉。
原因：WSL2 的 systemd 支持不是默認開啓的，開起來也不太穩。
解決路徑：
方案 A（最推薦）：用 Docker Desktop
裝 Docker Desktop for Windows，後端自動用 WSL2
設置裏勾"開機自啓"和"登錄後啓動"
Hermes 全程跑在 Docker 裏，穩定到離譜
方案 B：用 tmux 代替 systemd
sudo apt install tmux
tmux new -s hermes
（進入 tmux 後）
hermes gateway
（按 Ctrl+B 再按 D 退出但不關閉）
方案 C：確實要用 systemd
編輯 /etc/wsl.conf，加：
[boot]
systemd=true
然後 wsl --shutdown 關掉所有 WSL，重新打開 Ubuntu
【坑 023】VPS 上裝完重啓後 Hermes 自己沒起來
症狀：VPS 重啓後登錄上去，Hermes 不工作了。
解決：配置開機自啓。
Docker 版（最省心）：
跑容器的時候加上 --restart unless-stopped：
docker run -d \
--name hermes \
--restart unless-stopped \
-v ~/.hermes:/opt/data \
-p 8642:8642 \
nousresearch/hermes-agent gateway run
裸機版（systemd 用戶服務）：
~/.hermes/scripts/hermes-gateway install
~/.hermes/scripts/hermes-gateway start
systemctl --user enable hermes-gateway
enable 這個命令的意思是"開機自啓"。
【坑 024】Ubuntu 22.04 裝完之後路徑裏有 snap 導致衝突
症狀：跑 hermes 報奇怪的 Python 錯誤，仔細一看 Python 用的是 /snap/bin/python 裏的。
解決：
# 調整 PATH，把 ~/.hermes/bin 放到 snap 前面
echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
關鍵是把 Hermes 路徑放最前面。shell 找命令按 PATH 從左到右找，第一個找到的贏。
【坑 025】CentOS / AlmaLinux / Rocky：yum 提示 package not found
這幾個發行版默認源太保守，很多包找不到。開 EPEL 源：
sudo dnf install -y epel-release
sudo dnf update
sudo dnf install -y git curl ripgrep ffmpeg
EPEL 全稱是 Extra Packages for Enterprise Linux，社區維護的補充軟件包源。
【坑 026】安裝腳本跑完但 ~/.hermes/ 目錄是空的
原因：腳本跑了一半就因為網絡問題中斷了，但你沒注意到。
排查：
ls -la ~/.hermes/
看到只有零星幾個文件，沒有完整的 bin/、scripts/、lib/ 等子目錄——說明裝不完整。
解決：
# 把殘留清乾淨
rm -rf ~/.hermes
# 解決網絡問題後（回到坑 005-008）重新跑安裝腳本
curl -fsSL https://raw.githubusercontent.com/.../install.sh | bash
【坑 027】Docker 版安裝：nousresearch/hermes-agent 鏡像拉不下來
┌──────────────────────────────────────────────────────┐
│ Unable to find image │
│ 'nousresearch/hermes-agent:latest' locally │
│ docker: Error response from daemon: │
│ Get "https://registry-1.docker.io/v2/": timeout │
└──────────────────────────────────────────────────────┘
原因：Docker Hub 在國內經常連不上。
解決：配 Docker 鏡像加速。
編輯 /etc/docker/daemon.json（沒有就新建）：
{
"registry-mirrors": [
"https://docker.m.daocloud.io",
"https://dockerproxy.com",
"https://docker.mirrors.ustc.edu.cn"
]
}
保存後重啓 Docker：
sudo systemctl restart docker
再重新拉鏡像。
【坑 028】Docker 版跑起來了，但容器裏找不到 ~/.hermes
症狀：Docker 跑 Hermes 可以，但改 ~/.hermes/config.yaml 之後沒生效。
原因：你改的是宿主機的文件，但容器裏讀的是容器內的文件（因為你沒掛載卷）。
解決：啓動容器時一定要掛載 -v ~/.hermes:/opt/data。
# 錯誤（沒掛載）：
docker run -d nousresearch/hermes-agent gateway run
# 正確（掛載宿主機目錄）：
docker run -d \
-v ~/.hermes:/opt/data \
nousresearch/hermes-agent gateway run
-v ~/.hermes:/opt/data 的意思是：把宿主機的 ~/.hermes 目錄，映射到容器裏的 /opt/data。兩邊是同一份文件。
【坑 029】Termux（安卓）裝完，語音 / 瀏覽器工具跑不了
現象：在安卓手機 Termux 上裝 Hermes，大部分功能能用，但 voice / browser 相關報錯。
原因：Termux 官方支持的是**"精簡版"**，不包含所有擴展。
解決：看官方 Termux 專用文檔。
Hermes 在 Termux 上經過測試支持的功能：
CLI 對話 Cron Telegram Gateway MCP Honcho memory ACP
不支持：WhatsApp bridge、瀏覽器工具。
在手機上玩 Hermes 就暫時繞開這些。
【坑 030】重裝後原來的記憶 / 歷史都沒了
預防：Hermes 所有數據都在 ~/.hermes/ 目錄。
卸載前一定先備份：
# 打包備份
tar -czf hermes-backup-$(date +%Y%m%d).tar.gz ~/.hermes/
這一行的含義：
tar= 歸檔工具-czf= 創建 gzip 壓縮包，指定文件名$(date +%Y%m%d)= 自動加上今天的日期
重裝之後恢復：
tar -xzf hermes-backup-20260512.tar.gz -C ~/
-xzf 表示"解壓 gzip 格式的歸檔"，-C ~/ 表示解壓到家目錄。
安裝階段的 30 個坑講完了。 準備進入配 API 階段。
🔑 第二部分 · 配置模型與 API 的 25 個坑
先搞懂三個名詞：Provider、API Key、模型
小白最容易混的三個概念，一次說清楚：
┌─────────────────────────────────────────────────────────┐
│ Provider = 模型供應商 │
│ 比如：DeepSeek 公司 / 阿里雲 / OpenAI / Anthropic │
│ │
│ API Key = 通行證 │
│ 你去 Provider 那裏註冊賬號，它給你發一把"鑰匙" │
│ 格式一般是 sk-xxxxxxxxx 這樣一串字符 │
│ │
│ 模型 = 具體用哪個大腦 │
│ 同一個 Provider 下可能有多個模型 │
│ 比如 DeepSeek 旗下有 deepseek-chat、deepseek-reasoner │
└─────────────────────────────────────────────────────────┘
Hermes 需要這三樣東西全部對得上，才能工作。
【坑 031】不知道選哪個 Provider
Hermes 支持的主流 Provider 一覽：
| DeepSeek | |||
| 通義千問 / 阿里雲 | |||
| 智譜 GLM / z.ai | |||
| Kimi / Moonshot | |||
| MiniMax | |||
| OpenRouter | |||
| Nous Portal |
推薦：首選 DeepSeek。便宜、國內直連、模型質量對得起這個價位。
第三方週轉商推薦更便宜(無廣)：https://www.vivaapi.cn/
【坑 032】DeepSeek 在哪註冊？怎麼拿 API Key？
完整流程：
第 1 步：打開 https://platform.deepseek.com
第 2 步：右上角"登錄/註冊"，用手機號註冊
第 3 步：登錄後左側菜單找"API Keys"
第 4 步：點"Create new API key"
第 5 步：給 Key 起個名字（比如 hermes-pc）
第 6 步：複製那一串 sk-xxxxx 的字符串，馬上找個安全的地方存好
（關掉這個彈窗之後就看不到完整內容了）
第 7 步：左側菜單"賬單充值"，充 10-20 元（夠用很久）
⚠️ 一個重要提醒：DeepSeek 的 API Key 和你平時用的 DeepSeek 聊天網頁的賬號是同一個賬號，但餘額是分開的。聊天網頁可能給你送了 token，但那是給聊天用的，API 調用要單獨充值。
【坑 033】通義千問 / 阿里雲百鍊怎麼拿 Key
第 1 步：打開 https://bailian.console.aliyun.com
第 2 步：用你的阿里雲賬號登錄（沒有就註冊一個）
第 3 步：左側菜單找"API-KEY"
第 4 步：點"創建"，確認
第 5 步：複製 Key（以 sk- 開頭）
通義千問系列在 Hermes 裏通常要用 custom provider + OpenAI 兼容端點的方式接入，Base URL 填：
https://dashscope.aliyuncs.com/compatible-mode/v1
【坑 034】智譜 GLM / z.ai 怎麼拿 Key
國內版：
打開 https://bigmodel.cn → 註冊 → API Keys → 創建
海外版：
打開 https://z.ai → 註冊 → 同上
默認送一些免費 token，用完再充。
【坑 035】Kimi / Moonshot 怎麼拿 Key
第 1 步：打開 https://platform.moonshot.cn
第 2 步：註冊登錄
第 3 步：左側"API Keys" → 創建
第 4 步：複製 sk-xxxx
Kimi 註冊送一些免費額度，足夠新手玩很久。
【坑 036】OpenRouter 怎麼拿 Key（需要境外支付能力）
第 1 步：打開 https://openrouter.ai
第 2 步：註冊（推薦用 GitHub/Google 賬號登錄）
第 3 步：右上角頭像 → Keys → Create Key
第 4 步：充值需要信用卡或 Crypto（至少 $5）
OpenRouter 的特點是 一個 Key 能接幾百種海外模型，包括 Claude、GPT、Gemini、Llama 等。
【坑 037】hermes model 嚮導進去之後不知道選什麼
跑：
hermes model
會進入交互式嚮導。大致界面：
┌─────────────────────────────────────────────────────┐
│ Select your provider: │
│ │
│ > OpenRouter │
│ Nous Portal │
│ OpenAI │
│ Anthropic │
│ DeepSeek │
│ Moonshot / Kimi │
│ z.ai / ZhipuAI │
│ MiniMax │
│ Ollama (local) │
│ Custom OpenAI-compatible endpoint │
└─────────────────────────────────────────────────────┘
用上下箭頭選，回車確認。
小白選擇指南：
新手第一次：選 DeepSeek 上面沒有你要的 Provider（比如通義、百度文心、MiniMax 等）：選 Custom OpenAI-compatible endpoint 想試玩 Hermes 官方模型：選 Nous Portal
【坑 038】嚮導裏提示 "API Key is invalid"
你填完 Key 後提示：
┌──────────────────────────────────────────────────────┐
│ Error: API Key authentication failed │
│ Provider returned: 401 Unauthorized │
└──────────────────────────────────────────────────────┘
排查順序：
第 1 步：檢查是否多複製了空格或換行
打開某個記事本，把 Key 粘進去，看開頭結尾是不是多一個空格
Key 的標準格式：sk-後面一串字符，不應該有任何空格
第 2 步：檢查 Key 是否完整
很多 Provider 生成 Key 時，彈窗關閉就看不到完整 Key
重新去 Provider 後台生成一個新的
第 3 步：檢查賬户是否已充值
有些 Provider（比如 DeepSeek）即使註冊了，但不充值 Key 也無法調用
登錄 Provider 後台確認有餘額
第 4 步：檢查 Provider 有沒有要求"實名認證"
阿里雲百鍊、騰訊雲等國內大廠需要先實名
【坑 039】嚮導裏填錯了，想改怎麼辦
最簡單做法：重新跑一次 hermes model，它會覆蓋之前的配置。
手動改：
API Key 保存在 ~/.hermes/.env 文件裏。
# 打開文件編輯
nano ~/.hermes/.env
裏面內容長這樣：
OPENROUTER_API_KEY=sk-xxx
DEEPSEEK_API_KEY=sk-yyy
找到對應行改成新的，Ctrl+O 保存，Ctrl+X 退出。
【坑 040】/model 和 hermes model 有什麼區別
這是 2026 年 4 月博客園高贊帖總結的小白必踩坑：
hermes model ← 在終端外面跑，改的是"默認模型"
影響所有新開的 session
/model ← 在 Hermes 對話內部打，只改"當前這輪對話"
下次新開對話又回到默認
小白場景建議：
想永久換模型 → 退出 Hermes，跑 hermes model只想這次換一下（比如臨時用 Claude 寫個文）→ 對話裏打 /model
【坑 041】模型名寫錯了
┌──────────────────────────────────────────────────────┐
│ Error: Model 'deepseek' not found │
│ Available models: deepseek-chat, deepseek-reasoner │
└──────────────────────────────────────────────────────┘
很多新手直接把 Provider 名當成模型名填了。錯。
各家正確的模型名：
deepseek-chatdeepseek-reasoner | |
moonshot-v1-8kmoonshot-v1-32k、moonshot-v1-128k | |
qwen-maxqwen-plus、qwen-turbo | |
glm-4-plusglm-4-flash | |
anthropic/claude-sonnet-4openai/gpt-4o 等 | |
gpt-4oo1、o3 |
最新的模型名可能有變化，以 Provider 官網為準。
【坑 042】"Token limit exceeded" / "context length exceeded"
┌──────────────────────────────────────────────────────┐
│ Error: Token limit exceeded │
│ Your request had 8192 tokens but the model's │
│ context window is only 4096. │
└──────────────────────────────────────────────────────┘
意思：你這一輪對話塞進去的內容，超過了模型能處理的上下文。
小白理解：模型就像一個短期記憶窗口，一次只能看 N 個字。超了就報錯。
解決路徑：
方案 A（最快）：換個長上下文的模型
deepseek-chat：64K
moonshot-v1-128k：128K
claude-sonnet-4：200K
換到其中一個，絕大多數場景夠用
方案 B：開新會話
不用 hermes --continue，直接敲 hermes 開乾淨會話
不讓老對話佔用上下文
方案 C：清理 MEMORY.md
~/.hermes/memories/MEMORY.md 文件塞太多內容也會佔上下文
打開看看，刪點沒用的
方案 D：改 Ollama 的 num_ctx（只有用 Ollama 本地模型時）
見坑 058
【坑 043】回覆全是英文，怎麼讓它說中文
原因：模型默認用英文。你沒明確告訴它用中文。
解決：編輯 ~/.hermes/SOUL.md（如果沒有就新建）：
# 身份
你是一箇中文 AI 助手，名叫 Hermes。
# 行為準則
- 默認使用簡體中文回覆。英文產品名、專有名詞保留英文。
- 不要主動翻譯中文為英文。
- 除非用戶明確要求英文回覆，否則一律中文。
保存。下次啓動 Hermes 自動加載。
驗證：進入 Hermes 跟它說"用中文自我介紹一下"，應該中文回你。
【坑 044】回覆是亂碼或者方塊字
你看到：
Hermes: ä½ å¥½ï¼Œæˆ‘æ˜¯...
原因：你的終端沒設 UTF-8。
Mac / Linux 解決：
# 在 ~/.bashrc 或 ~/.zshrc 末尾加：
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
# 然後：
source ~/.bashrc # 或 ~/.zshrc
WSL2 / Windows 終端解決：
Windows Terminal → 設置 → 默認值 → 高級 → 文字呈現下面勾"UTF-8 BOM"。
【坑 045】連接超時 / 連不上模型服務
┌──────────────────────────────────────────────────────┐
│ Error: Connection timed out │
│ Failed to reach api.deepseek.com │
└──────────────────────────────────────────────────────┘
排查：
# 第 1 步：看看能不能 ping 通
ping api.deepseek.com
按 Ctrl+C 停止。
看結果：
64 bytes from ...→ 能通，回到坑 038 檢查 KeyRequest timeout→ 網絡問題Unknown host→ DNS 問題（回到坑 006）
網絡問題的解決：
方案 A：換 DNS
Mac: 系統設置 → 網絡 → 高級 → DNS → 加 8.8.8.8
Linux: sudo nano /etc/resolv.conf
方案 B：換節點
有些 Provider 有國內/海外不同節點，用國內節點延遲低
方案 C：設代理
export https_proxy=http://代理地址:端口
再跑 hermes
【坑 046】"Rate limit exceeded"（調用頻率超限）
┌──────────────────────────────────────────────────────┐
│ Error 429: Too Many Requests │
│ You have exceeded the rate limit of 10 req/min │
└──────────────────────────────────────────────────────┘
原因：短時間請求太多，被 Provider 限流。
解決路徑：
方案 A：等 1 分鐘再試
大多數限流是按分鐘重置的
方案 B：升級賬户等級
DeepSeek 充值 50 元以上自動升級到更高的限流閾值
OpenRouter 有付費等級
方案 C：配 Fallback Provider（v0.12+ 功能）
hermes fallback
加一個備用 Provider，主 Provider 掛了自動切
【坑 047】Provider 服務器本身掛了
┌──────────────────────────────────────────────────────┐
│ Error 503: Service Unavailable │
│ The server is temporarily down for maintenance │
└──────────────────────────────────────────────────────┘
這不是你的問題。Provider 自己的服務器問題。
解決：
去 Provider 官網看"系統狀態"頁 如果他們在維護，換一個 Provider 臨時用 有配 Fallback 會自動切（見坑 046）
【坑 048】自定義 OpenAI 兼容端點怎麼填
很多國產 Provider（阿里雲百鍊、字節火山引擎、七牛雲等）支持"OpenAI 兼容端點"。
在 hermes model 嚮導裏選 Custom OpenAI-compatible endpoint，會問你：
Provider name: 隨便起，比如 my-qwen
Base URL: 填 Provider 給的兼容端點
API Key: 你的 Key
Default model: 填這個 Provider 下某個具體模型名
常用 Base URL 速查：
https://dashscope.aliyuncs.com/compatible-mode/v1 | |
https://ark.cn-beijing.volces.com/api/v3 | |
https://api.qnaigc.com/v1 | |
https://api.siliconflow.cn/v1 |
【坑 049】充了錢但還是報 "insufficient balance"
原因：大多數 Provider 充值有到賬延遲（幾秒到幾分鐘），或者你充到了另一個賬號。
排查：
第 1 步：回 Provider 後台看餘額
確實到賬了 → 等 5 分鐘重試
沒到賬 → 看訂單狀態
第 2 步：確認你充值用的是同一個賬號
有些 Provider 區分"個人賬號"和"企業賬號"
第 3 步：確認沒填錯 Key
每個賬號的 Key 不通用
【坑 050】配完模型，對話不回 / 一直轉圈
症狀：你問它問題，光標在閃，但永遠不出結果。
遞進式排查：
第 1 步：看終端有沒有紅字報錯
有紅字 → 按報錯信息對應坑找
第 2 步：運行體檢
hermes doctor
看哪一項紅叉，按建議修
第 3 步：看日誌
tail -f ~/.hermes/logs/*.log
會看到最新的幾行日誌
第 4 步：重啓 Hermes
Ctrl+C 中斷 → 重新 hermes
第 5 步：換個模型試
/model 切到另一個 Provider
如果新模型能回答，說明原 Provider 有問題
【坑 051】換模型的時候原來的會話丟了
預防：不要在對話裏用 /reset 或 /clear，那會清空歷史。
恢復歷史：
# 看所有歷史 session
hermes sessions
# 恢復某一個
hermes --resume <session-id>
【坑 052】返回消息特別慢
原因和解決：
情況 A：模型本身慢（比如 reasoner 類需要"深思熟慮"）
→ 耐心等，或換個 chat 類模型
情況 B：網絡抖動
→ 換 DNS 或用國內節點
情況 C：你用了 Ollama 本地模型，機器配置不夠
→ 換個小一點的模型，或上雲 API
【坑 053】"Model does not support tool calling"
┌──────────────────────────────────────────────────────┐
│ Error: The selected model does not support tool │
│ calling. Please choose a model with tool support. │
└──────────────────────────────────────────────────────┘
原因：Hermes 是個 Agent，很依賴"調用工具"這個能力。有些模型（尤其免費的小模型）不支持。
解決：換支持 tool calling 的模型。
確認支持的：
DeepSeek 系列全支持 Kimi Moonshot v1 系列支持 Claude 3.5+ 支持 GPT-4 系列支持 Qwen 2.5+ 支持 Llama 3.1+ 70B 以上版本支持
不支持的：
很多免費的 embedding 模型 一些小於 7B 的本地模型
【坑 054】Anthropic Claude 訂閲模式"out of extra usage"
這是 2026 年 4 月 GitHub issue #6475 報告的老 bug：
┌──────────────────────────────────────────────────────┐
│ You're out of extra usage. │
│ (即使你剛訂閲、剛重啓也可能出現這個) │
└──────────────────────────────────────────────────────┘
解決：
# 重新登錄 Claude 訂閲
hermes model
# 選 Anthropic → 用 OAuth 流程重新登錄
# 或者切換到 Claude API Key 模式
# 在 Anthropic 後台拿 API Key，填進去
【坑 055】配置文件改了但沒生效
症狀：你改了 ~/.hermes/config.yaml 或 .env，但 Hermes 行為沒變。
原因：Hermes 啓動時就把配置讀進內存，改文件不會自動重載。
解決：
# Ctrl+C 退出當前 Hermes
# 重新啓動
hermes
Docker 版：
docker restart hermes
【坑 056】hermes config show 看不到你改的字段
hermes config show
輸出只顯示默認值，看不到你剛改的。
原因：配置文件格式錯誤（YAML 很嚴格）。
檢查：
# 用 Python 檢查 YAML 是否合法
python3 -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))"
看到報錯說明格式錯了。常見錯誤：
縮進用了 tab 而不是空格 冒號後忘了加空格 字符串裏有特殊符號但沒加引號
【坑 057】Ollama 本地模型：上下文默認才 4096
這是本地模型最大的坑。
Ollama 默認 num_ctx 只有 2048 或 4096，但 Hermes 需要 至少 64000 才能正常工作（因為要塞系統提示、工具 schema、歷史消息等）。
解決：
編輯 ~/.hermes/config.yaml，在 providers 下面加：
providers:
ollama:
options:
num_ctx: 65536
保存後重啓 Hermes。
驗證：
# 讓它做一箇中等長度的任務
hermes -q "讀取當前目錄的 5 個 md 文件，總結每個文件的主題"
不報 "context length exceeded" 就是生效了。
【坑 058】Ollama 報 model not found
┌──────────────────────────────────────────────────────┐
│ Error: model 'qwen3:8b' not found, try pulling it │
└──────────────────────────────────────────────────────┘
解決：先讓 Ollama 下載這個模型。
# 拉模型（要下載，可能幾 GB）
ollama pull qwen3:8b
# 看本地有哪些模型
ollama list
然後讓 Hermes 用這個模型（名字要和 ollama list 裏完全一致）。
【坑 059】Ollama 連接被拒絕
┌──────────────────────────────────────────────────────┐
│ Error: Connection refused (127.0.0.1:11434) │
└──────────────────────────────────────────────────────┘
原因：Ollama 服務沒啓動。
解決：
# 啓動 Ollama 服務
ollama serve
# 或者在 Mac 上打開 Ollama 應用
Mac 裝了 Ollama 之後，要確保菜單欄右上角有 Ollama 的小圖標，沒有就去應用裏打開。
【坑 060】Ollama 工具調用不穩，偶爾亂回覆
原因：本地模型的 tool calling 能力不穩定，特別是 8B 以下的小模型。
解決：
建議 A：換更強的模型
Qwen 2.5 14B 起步
Llama 3.3 70B 更穩
Hermes 3 70B（和 Agent 同名同系列，最適配）
建議 B：減少同時啓用的工具
config.yaml 裏減少 toolsets，讓模型壓力小一點
建議 C：回去用雲 API
本地模型不是新手第一選擇
穩定優先的場景用 DeepSeek 雲 API
API 配置階段的 25 個坑講完了。接下來是最後一塊——接入聊天軟件。
Hermes 全網問題百寶箱：從裝不上到接不通，80 個坑我替你踩完了 | 保姆教程 03
這一篇不是教程。這是一本工具書。 你裝 Hermes 的時候、配模型的時候、接聊天軟件的時候——遇到任何報錯，Ctrl+F 搜關鍵詞就能找到解法。 建議先收藏，再慢慢看。
【封面配圖建議】 深色背景。畫面中央是一本翻開的"工具手冊"，封面寫着 "Hermes Troubleshooting"。手冊兩邊懸浮着三個發光標籤：安裝坑、API 坑、接入坑。背景有一堆"紅叉報錯"飄過，一道綠光把它們全部變成了"綠勾"。畫面下方一行字："80 個坑 · 每一個都給你挖了出口"。
寫在最前面：這篇寫給誰看
先自我定位。如果你符合下面任何一條，這篇就是為你寫的：
點開了前兩篇，看懂了大概，但動手裝的時候就卡殼了 裝上了 Hermes，配模型的時候一直報錯，試了七八種方法都不行 模型配好了，接飛書 / 企業微信 / 其它聊天軟件一直連不上，Bot 在羣裏像死機 你壓根不懂什麼是終端，看到別人講命令行就頭皮發麻，但又確實想用上 AI 助手 你已經是老玩家，但最近升級到 v0.13 後舊配置突然全壞了
這篇把 Hermes 最全的坑按發生順序排了一遍，每一個坑都給出遞進式解法。
遞進式解法什麼意思？就是：A 方法不行試 B，B 不行試 C，C 不行還有 D——不會讓你走進死衚衕。
文章很長。建議做法：
先通讀一遍目錄，心裏有底 遇到具體報錯再回來 Ctrl+F 搜關鍵詞 收藏起來，以後每次翻就像翻字典
🗺️ 全文目錄（Ctrl+F 可跳轉）
第一部分 · 安裝階段的 30 個坑
準備篇：終端是什麼？怎麼打開？ 安裝前的必查項 安裝命令本身的報錯 裝完之後的 command not found依賴缺失與版本問題 Mac / Linux / WSL2 各自的平台坑
第二部分 · 配置模型與 API 的 25 個坑
先搞懂：Provider、API Key、模型 是什麼關係 去哪註冊 API Key（6 個主流 Provider 註冊路徑） hermes model/hermes setup嚮導踩坑API Key 無效、過期、充值未到賬 模型名寫錯的 5 種常見情況 Token limit 超限、上下文不足 連不上模型服務的 N 種情況 Ollama 本地模型的經典坑
第三部分 · 接入聊天軟件的 25 個坑
Gateway 基本原理 飛書：從創建應用到 Bot 上線的 8 個坑 企業微信：掃碼綁定失敗、消息不回、白名單問題 釘釘 Stream 模式的 4 個坑 Telegram：Token 被複制 8 遍、webhook 依賴缺失 接入後"Bot 不回消息"的 10 種排查路徑
第四部分 · 兜底篇
終極自查五步法 日誌怎麼看、怎麼截圖給別人看 哪裏能快速拿到幫助 升級到 v0.13 的小心事項
第五部分 · 下篇預告
🧰 第一部分 · 安裝階段的 30 個坑
準備篇 · 你得先會"打開終端"
Hermes 是一個命令行工具。不懂沒關係，先學會打開"終端"這個黑框框。
Mac 用戶怎麼打開終端
按住鍵盤上的 ⌘ + 空格鍵 → 彈出搜索框 → 輸入"終端"或"Terminal" → 回車。
屏幕上會彈出一個黑色（或白色）窗口，光標在閃。這就是終端。 你之後所有命令都在這裏敲。
Windows 用戶怎麼打開終端
先說結論：Hermes 官方明確表示不支持 Windows 原生安裝。Windows 用戶必須先裝 WSL2（一個住在 Windows 裏的 Linux 子系統），然後在 WSL2 裏操作。
裝 WSL2 的方法：
按 Win 鍵，搜"PowerShell"右鍵 PowerShell → "以管理員身份運行" 粘貼下面這行，回車：
wsl --install
等它跑完，重啓電腦 開機後會自動彈出 Ubuntu 窗口，讓你設用戶名和密碼（密碼不會顯示，盲打） 以後你的"終端"就是這個 Ubuntu 窗口
⚠️ 之後文章裏所有涉及終端的命令，Windows 用戶一律在 Ubuntu 窗口裏跑，不要跑在 CMD 或 PowerShell。
【坑 001】WSL2 裝不上，報 0x80370102
終端裏看到這樣的提示：
┌─────────────────────────────────────────────────┐
│ WslRegisterDistribution failed with error: │
│ 0x80370102 │
│ Please enable the Virtual Machine Platform... │
└─────────────────────────────────────────────────┘
原因：你電腦的 BIOS 裏虛擬化功能沒開。
解決：
重啓電腦，按 F2 / F10 / Delete（不同品牌鍵不同）進 BIOS 在 BIOS 裏找 "Virtualization" 或 "Intel VT-x" / "AMD-V"，改成 Enabled 保存退出，重啓 回到 Windows，重新執行 wsl --install
還是不行？ 有些老電腦 CPU 根本不支持虛擬化，這種情況換電腦或租個海外服務器。
【坑 002】WSL2 裝好了，但 Ubuntu 啓動不了
症狀：雙擊 Ubuntu 圖標，窗口一閃就沒了。
遞進式解法：
方法 A（先試）：
打開 PowerShell 管理員權限，跑：
wsl --update
更新 WSL 內核，再重試啓動 Ubuntu
方法 B（A 不行再試）：
PowerShell 裏跑：
wsl --shutdown
wsl -d Ubuntu
強制關閉並重新進入 Ubuntu
方法 C（B 還不行）：
徹底卸載重裝：
wsl --unregister Ubuntu
wsl --install -d Ubuntu
方法 D（C 還不行）：
Windows 版本太舊。升級到 Windows 11 或 Windows 10 最新版。
【坑 003】終端打開了，但看到一行紅字 Restricted
這是 zsh 在給你警告，不是報錯。
看到的內容大概這樣：
┌────────────────────────────────────────────────────────┐
│ [oh-my-zsh] Insecure completion-dependent directories │
│ detected: │
│ zsh compinit: insecure directories, run compaudit │
└────────────────────────────────────────────────────────┘
解決：敲一行：
compaudit | xargs chmod g-w
中文解釋：compaudit 檢查有安全風險的目錄，xargs chmod g-w 把這些目錄的"組可寫"權限去掉。
跑完關掉終端重新開一個，警告就沒了。
【坑 004】安裝前檢查 Git（很多人跳過這一步）
Hermes 安裝過程要用 Git 從 GitHub 拉代碼。先檢查本機有沒有：
git --version
中文解釋：顯示 Git 的版本號。
三種可能輸出：
情況 A： git version 2.xx.x→ 有，繼續下一步情況 B： command not found: git→ 沒裝，見下方情況 C：彈窗問"要不要安裝命令行工具" → Mac 用戶點"安裝"，等幾分鐘
情況 B 的解決：
Mac 用戶：
xcode-select --install
Ubuntu / Debian / WSL2 用戶：
sudo apt update
sudo apt install -y git
CentOS / AlmaLinux 用戶：
sudo dnf install -y git
【坑 005】終於開始裝 Hermes，但 curl 命令一跑就報錯
你跑了官方安裝命令：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
然後看到紅字：
┌──────────────────────────────────────────────────────┐
│ curl: (6) Could not resolve host: │
│ raw.githubusercontent.com │
└──────────────────────────────────────────────────────┘
原因：網絡連不上 GitHub。這和你的命令沒關係，是網絡問題。
遞進式解法：
方案 A（最穩）：
換一個能穩定連 GitHub 的網絡環境
如果在家裏用寬帶連不上，去咖啡店 / 公司 WiFi 試一下
方案 B（折騰派）：
用一台海外服務器裝（香港 / 新加坡 / 日本 / 美國節點）
Vultr / DigitalOcean / Hetzner / 騰訊雲海外 / 阿里雲海外均可
方案 C（有工具的）：
自己配代理後再跑：
export https_proxy=http://你的代理地址:端口
export http_proxy=http://你的代理地址:端口
之後再跑 curl 安裝命令
方案 D（最後的辦法）：
手動下載安裝腳本。先訪問：
https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh
把內容保存成 install.sh，再本地跑：
bash install.sh
【坑 006】curl: (28) Failed to connect, connection timed out
終端顯示：
┌──────────────────────────────────────────────────────┐
│ curl: (28) Failed to connect to │
│ raw.githubusercontent.com port 443: Connection │
│ timed out │
└──────────────────────────────────────────────────────┘
原因：網絡通，但握手超時。通常是間歇性網絡問題。
解決：
步驟 1：重試 2-3 次
curl -fsSL https://raw.githubusercontent.com/... | bash
步驟 2：換 DNS
Mac：系統設置 → 網絡 → 高級 → DNS → 改成 8.8.8.8 和 1.1.1.1
Linux：
sudo nano /etc/resolv.conf
改成：
nameserver 8.8.8.8
nameserver 1.1.1.1
步驟 3：如果公司網絡限制嚴，回到坑 005 的方案 B 或 C
【坑 007】curl: (35) SSL certificate problem
┌──────────────────────────────────────────────────────┐
│ curl: (35) SSL certificate problem: │
│ unable to get local issuer certificate │
└──────────────────────────────────────────────────────┘
原因：本機 SSL 證書庫太舊或被替換了（可能用過某些代理工具改過證書）。
解決：
Mac 用戶：
brew install ca-certificates
Ubuntu 用戶：
sudo apt install -y ca-certificates
sudo update-ca-certificates
還是不行？臨時跳過證書驗證（僅做應急用，不推薦長期這樣）：
curl -k -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
-k 參數的中文意思是"不校驗 SSL 證書"。
【坑 008】安裝腳本跑到一半卡死在下載 Python
終端裏一直顯示：
Downloading Python 3.11...
(卡住不動 5 分鐘以上)
原因：Python 安裝包下載慢，或被牆。
解決：
# 按 Ctrl+C 先中斷
# 然後手動裝 Python 3.11，再重跑安裝腳本
Mac 用戶先裝 Homebrew（如果沒裝過）：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
然後裝 Python：
brew install python@3.11
Ubuntu 用戶：
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3-pip
裝完再回來跑 Hermes 安裝腳本。
【坑 009】裝到一半報 Permission denied
┌──────────────────────────────────────────────────────┐
│ mkdir: cannot create directory '/opt/hermes': │
│ Permission denied │
└──────────────────────────────────────────────────────┘
原因：你在一個你沒權限寫入的目錄跑了安裝腳本。
解決：
不要用 sudo 跑 Hermes 安裝腳本。 Hermes 是用戶級工具，要裝在你自己的家目錄（~/.hermes/），不是系統目錄。
正確做法：
# 先回到家目錄
cd ~
# 再跑安裝命令
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
【坑 010】裝完之後，hermes --version 報 command not found
這是小白裝完之後最經典的恐慌瞬間。你以為裝失敗了，其實 99% 情況下只是——
終端還沒重新加載配置，不知道去哪找 hermes 命令。
遞進式解法（按順序試，成功一步就停）：
第 1 步：告訴終端重新加載配置
先看看你用的是 bash 還是 zsh：
echo $SHELL
結果是 /bin/bash → 跑：source ~/.bashrc
結果是 /bin/zsh → 跑：source ~/.zshrc
之後再試：hermes --version
第 2 步：關掉終端窗口，重新打開一個
這能解決一大半"重載不成功"的問題
第 3 步：檢查 hermes 二進制是否真的存在
ls ~/.hermes/bin/hermes
有 → 繼續第 4 步
沒有 → 安裝真的失敗了，去看坑 005-008 網絡/證書問題
第 4 步：手動把 hermes 加進 PATH
echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
（zsh 用戶把 .bashrc 改成 .zshrc）
第 5 步：上面全無效，重新跑一遍安裝腳本
curl -fsSL https://.../install.sh | bash
【坑 011】裝完 command not found + 手動加 PATH 也不行
你按坑 010 做了所有步驟，還是不行。
終極排查：
# 第一步：看 PATH 裏到底有沒有 ~/.hermes/bin
echo $PATH | tr ':' '\n'
中文解釋：顯示你當前 PATH 的所有目錄，每行一個。
如果輸出裏沒看到 ~/.hermes/bin 或 /Users/你名字/.hermes/bin：
# 直接給 hermes 建一個"快捷方式"到系統路徑
sudo ln -s ~/.hermes/bin/hermes /usr/local/bin/hermes
中文解釋：ln -s 是創建"軟連結"，把 ~/.hermes/bin/hermes 這個文件的一個入口放到 /usr/local/bin/hermes。
之後就能在任何終端裏直接敲 hermes 了。
【坑 012】Mac 用戶：M 系列芯片裝完報 bad CPU type
┌──────────────────────────────────────────────────────┐
│ bad CPU type in executable: hermes │
└──────────────────────────────────────────────────────┘
原因：你的 Mac 是 Apple Silicon（M1/M2/M3/M4）芯片，但裝到的是 Intel 版本的二進制。
解決：
# 先確認你的 Mac 架構
uname -m
輸出 arm64= Apple Silicon輸出 x86_64= Intel
如果是 arm64 但跑了 Intel 版：
# 裝 Rosetta 2（讓 Intel 程序也能跑）
softwareupdate --install-rosetta --agree-to-license
或者更乾淨的方法——卸載重裝，讓安裝腳本自動識別你的架構：
rm -rf ~/.hermes
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
【坑 013】裝完之後，hermes doctor 報一堆紅叉
這不是 bug，這是 Hermes 在幫你體檢。
跑：
hermes doctor
輸出可能長這樣：
┌─────────────────────────────────────────────────────┐
│ Running health check... │
│ │
│ ✓ Python 3.11.x detected │
│ ✓ Node.js 22.x detected │
│ ✗ ripgrep not found │
│ ✗ ffmpeg not found │
│ ✗ No provider configured │
│ │
│ Suggested fixes: │
│ brew install ripgrep ffmpeg │
│ hermes model │
└─────────────────────────────────────────────────────┘
每一條紅叉下面都會告訴你怎麼修。照着做就行。
常見紅叉一一對應：
ripgrep not found | brew install ripgrep / Ubuntu: sudo apt install ripgrep | |
ffmpeg not found | brew install ffmpeg / Ubuntu: sudo apt install ffmpeg | |
No provider configured | hermes model | |
Python version too low | ||
PATH issue detected |
【坑 014】hermes doctor 卡住不動
跑 hermes doctor，終端光標一直在閃，什麼也不輸出。
原因：它在聯網檢查更新，網絡不通所以卡住。
解決：
# 按 Ctrl+C 中斷，用 offline 模式
hermes doctor --offline
--offline 參數的意思是"不聯網檢查"，只做本地體檢。
如果這個版本里沒這個參數，直接跳過 hermes doctor，往後走。不檢查也能用。
【坑 015】Ubuntu 用戶：apt install 本身就報錯
┌──────────────────────────────────────────────────────┐
│ E: Could not get lock /var/lib/dpkg/lock-frontend │
│ Another process is using the Package Manager. │
└──────────────────────────────────────────────────────┘
原因：另一個程序正在用 apt（比如系統自動更新在後台跑）。
解決：
# 等 5 分鐘，讓它自己跑完
# 或者強制殺掉：
sudo killall apt apt-get
sudo rm /var/lib/dpkg/lock-frontend
sudo rm /var/lib/dpkg/lock
sudo dpkg --configure -a
之後再跑你想裝的東西。
【坑 016】Python 版本過低報錯
┌──────────────────────────────────────────────────────┐
│ ERROR: Hermes Agent requires Python 3.11 or higher │
│ Found: Python 3.8.10 │
└──────────────────────────────────────────────────────┘
解決路徑：
Ubuntu 用戶：
# 加一個能裝 Python 3.11 的源
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install -y python3.11 python3.11-venv
Mac 用戶（已裝 Homebrew）：
brew install python@3.11
裝完之後一定要讓系統認這個新版本：
# 看看 python3 現在指向哪個版本
python3 --version
如果還是老版本，在 ~/.bashrc 或 ~/.zshrc 末尾加一行：
alias python3="/usr/local/bin/python3.11"
然後：
source ~/.bashrc # 或 source ~/.zshrc
【坑 017】Node.js 沒裝或版本過低
┌──────────────────────────────────────────────────────┐
│ ERROR: Node.js 20+ required │
└──────────────────────────────────────────────────────┘
Node.js 在 Hermes 裏是可選的（只有用瀏覽器工具時才用到），但裝上更省心。
推薦用 nvm 裝（能裝多個版本，隨時切）：
# 裝 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 重載終端
source ~/.bashrc # 或 ~/.zshrc
# 裝 Node 22（Hermes 推薦）
nvm install 22
# 用 22
nvm use 22
【坑 018】uv: command not found
uv 是 Hermes 用的新式 Python 包管理器。
# 手動裝 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc # 或 ~/.zshrc
裝完驗證：
uv --version
【坑 019】磁盤空間不足
┌──────────────────────────────────────────────────────┐
│ No space left on device │
└──────────────────────────────────────────────────────┘
Hermes 本體 + 依賴大約 2-3 GB。
# 看看哪裏佔空間
df -h
中文解釋：df 是"disk free"的縮寫，-h 讓數字用人類可讀的方式顯示（GB/MB）。
空間不夠的話：
# 清理 apt 緩存（Ubuntu）
sudo apt clean
sudo apt autoremove
# 清理 brew 緩存（Mac）
brew cleanup -s
【坑 020】WSL2 裏裝 Hermes，C 盤空間暴漲
症狀：WSL2 裏裝完 Hermes，你 Windows C 盤少了 10GB。
原因：WSL2 的 Ubuntu 子系統默認放在 C 盤，裏面裝什麼都算 C 盤。
解決：把 WSL2 移到 D 盤。
在 PowerShell（管理員）裏：
# 1. 先停掉 WSL
wsl --shutdown
# 2. 導出當前 Ubuntu
wsl --export Ubuntu D:\wsl-backup\ubuntu.tar
# 3. 註銷
wsl --unregister Ubuntu
# 4. 在 D 盤重新導入
wsl --import Ubuntu D:\wsl-ubuntu D:\wsl-backup\ubuntu.tar
之後 Ubuntu 就住在 D 盤，C 盤空間馬上釋放。
【坑 021】Mac 用戶：launchd 自動啓動不繼承 PATH
這是所有 Mac Hermes 用戶遲早要踩的大坑。
你想開機自啓 Hermes，跑了 launchd，發現它啓動失敗，報 hermes: command not found——但你在終端裏能用。
原因：launchd 啓動的進程不繼承你終端裏的 PATH。
解決：在 launchd 的 plist 配置裏顯式寫出完整路徑。
例如：
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/Users/你的用戶名/.hermes/bin:/usr/local/bin:/usr/bin:/bin</string>
</dict>
不推薦新手碰 launchd。最省心的方案是用 Docker 跑 Hermes，Docker Desktop 在"開機自啓"裏勾選就行。
【坑 022】WSL2 用戶：systemd 不穩定
現象：在 WSL2 裏用 systemd 常駐 Hermes Gateway，過一段時間莫名其妙死掉。
原因：WSL2 的 systemd 支持不是默認開啓的，開起來也不太穩。
解決路徑：
方案 A（最推薦）：用 Docker Desktop
裝 Docker Desktop for Windows，後端自動用 WSL2
設置裏勾"開機自啓"和"登錄後啓動"
Hermes 全程跑在 Docker 裏，穩定到離譜
方案 B：用 tmux 代替 systemd
sudo apt install tmux
tmux new -s hermes
（進入 tmux 後）
hermes gateway
（按 Ctrl+B 再按 D 退出但不關閉）
方案 C：確實要用 systemd
編輯 /etc/wsl.conf，加：
[boot]
systemd=true
然後 wsl --shutdown 關掉所有 WSL，重新打開 Ubuntu
【坑 023】VPS 上裝完重啓後 Hermes 自己沒起來
症狀：VPS 重啓後登錄上去，Hermes 不工作了。
解決：配置開機自啓。
Docker 版（最省心）：
跑容器的時候加上 --restart unless-stopped：
docker run -d \
--name hermes \
--restart unless-stopped \
-v ~/.hermes:/opt/data \
-p 8642:8642 \
nousresearch/hermes-agent gateway run
裸機版（systemd 用戶服務）：
~/.hermes/scripts/hermes-gateway install
~/.hermes/scripts/hermes-gateway start
systemctl --user enable hermes-gateway
enable 這個命令的意思是"開機自啓"。
【坑 024】Ubuntu 22.04 裝完之後路徑裏有 snap 導致衝突
症狀：跑 hermes 報奇怪的 Python 錯誤，仔細一看 Python 用的是 /snap/bin/python 裏的。
解決：
# 調整 PATH，把 ~/.hermes/bin 放到 snap 前面
echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
關鍵是把 Hermes 路徑放最前面。shell 找命令按 PATH 從左到右找，第一個找到的贏。
【坑 025】CentOS / AlmaLinux / Rocky：yum 提示 package not found
這幾個發行版默認源太保守，很多包找不到。開 EPEL 源：
sudo dnf install -y epel-release
sudo dnf update
sudo dnf install -y git curl ripgrep ffmpeg
EPEL 全稱是 Extra Packages for Enterprise Linux，社區維護的補充軟件包源。
【坑 026】安裝腳本跑完但 ~/.hermes/ 目錄是空的
原因：腳本跑了一半就因為網絡問題中斷了，但你沒注意到。
排查：
ls -la ~/.hermes/
看到只有零星幾個文件，沒有完整的 bin/、scripts/、lib/ 等子目錄——說明裝不完整。
解決：
# 把殘留清乾淨
rm -rf ~/.hermes
# 解決網絡問題後（回到坑 005-008）重新跑安裝腳本
curl -fsSL https://raw.githubusercontent.com/.../install.sh | bash
【坑 027】Docker 版安裝：nousresearch/hermes-agent 鏡像拉不下來
┌──────────────────────────────────────────────────────┐
│ Unable to find image │
│ 'nousresearch/hermes-agent:latest' locally │
│ docker: Error response from daemon: │
│ Get "https://registry-1.docker.io/v2/": timeout │
└──────────────────────────────────────────────────────┘
原因：Docker Hub 在國內經常連不上。
解決：配 Docker 鏡像加速。
編輯 /etc/docker/daemon.json（沒有就新建）：
{
"registry-mirrors": [
"https://docker.m.daocloud.io",
"https://dockerproxy.com",
"https://docker.mirrors.ustc.edu.cn"
]
}
保存後重啓 Docker：
sudo systemctl restart docker
再重新拉鏡像。
【坑 028】Docker 版跑起來了，但容器裏找不到 ~/.hermes
症狀：Docker 跑 Hermes 可以，但改 ~/.hermes/config.yaml 之後沒生效。
原因：你改的是宿主機的文件，但容器裏讀的是容器內的文件（因為你沒掛載卷）。
解決：啓動容器時一定要掛載 -v ~/.hermes:/opt/data。
# 錯誤（沒掛載）：
docker run -d nousresearch/hermes-agent gateway run
# 正確（掛載宿主機目錄）：
docker run -d \
-v ~/.hermes:/opt/data \
nousresearch/hermes-agent gateway run
-v ~/.hermes:/opt/data 的意思是：把宿主機的 ~/.hermes 目錄，映射到容器裏的 /opt/data。兩邊是同一份文件。
【坑 029】Termux（安卓）裝完，語音 / 瀏覽器工具跑不了
現象：在安卓手機 Termux 上裝 Hermes，大部分功能能用，但 voice / browser 相關報錯。
原因：Termux 官方支持的是**"精簡版"**，不包含所有擴展。
解決：看官方 Termux 專用文檔。
Hermes 在 Termux 上經過測試支持的功能：
CLI 對話 Cron Telegram Gateway MCP Honcho memory ACP
不支持：WhatsApp bridge、瀏覽器工具。
在手機上玩 Hermes 就暫時繞開這些。
【坑 030】重裝後原來的記憶 / 歷史都沒了
預防：Hermes 所有數據都在 ~/.hermes/ 目錄。
卸載前一定先備份：
# 打包備份
tar -czf hermes-backup-$(date +%Y%m%d).tar.gz ~/.hermes/
這一行的含義：
tar= 歸檔工具-czf= 創建 gzip 壓縮包，指定文件名$(date +%Y%m%d)= 自動加上今天的日期
重裝之後恢復：
tar -xzf hermes-backup-20260512.tar.gz -C ~/
-xzf 表示"解壓 gzip 格式的歸檔"，-C ~/ 表示解壓到家目錄。
安裝階段的 30 個坑講完了。 準備進入配 API 階段。
【中間配圖建議】 一張"排錯地圖"的等距插畫。地圖上有三座山峯：第一座標"安裝"（已經走過，插了一面紅旗）；第二座標"API 配置"（正在爬）；第三座標"接入聊天"（遠處雲裏）。山路上畫着散落的小圖標（報錯信息、API Key、Bot 頭像），一個小機器人拎着工具箱走在路上。
🔑 第二部分 · 配置模型與 API 的 25 個坑
先搞懂三個名詞：Provider、API Key、模型
小白最容易混的三個概念，一次說清楚：
┌─────────────────────────────────────────────────────────┐
│ Provider = 模型供應商 │
│ 比如：DeepSeek 公司 / 阿里雲 / OpenAI / Anthropic │
│ │
│ API Key = 通行證 │
│ 你去 Provider 那裏註冊賬號，它給你發一把"鑰匙" │
│ 格式一般是 sk-xxxxxxxxx 這樣一串字符 │
│ │
│ 模型 = 具體用哪個大腦 │
│ 同一個 Provider 下可能有多個模型 │
│ 比如 DeepSeek 旗下有 deepseek-chat、deepseek-reasoner │
└─────────────────────────────────────────────────────────┘
Hermes 需要這三樣東西全部對得上，才能工作。
【坑 031】不知道選哪個 Provider
Hermes 支持的主流 Provider 一覽：
| DeepSeek | |||
| 通義千問 / 阿里雲 | |||
| 智譜 GLM / z.ai | |||
| Kimi / Moonshot | |||
| MiniMax | |||
| OpenRouter | |||
| Nous Portal |
小白推薦：首選 DeepSeek。便宜、國內直連、模型質量對得起這個價位。
【坑 032】DeepSeek 在哪註冊？怎麼拿 API Key？
完整流程：
第 1 步：打開 https://platform.deepseek.com
第 2 步：右上角"登錄/註冊"，用手機號註冊
第 3 步：登錄後左側菜單找"API Keys"
第 4 步：點"Create new API key"
第 5 步：給 Key 起個名字（比如 hermes-pc）
第 6 步：複製那一串 sk-xxxxx 的字符串，馬上找個安全的地方存好
（關掉這個彈窗之後就看不到完整內容了）
第 7 步：左側菜單"賬單充值"，充 10-20 元（夠用很久）
⚠️ 一個重要提醒：DeepSeek 的 API Key 和你平時用的 DeepSeek 聊天網頁的賬號是同一個賬號，但餘額是分開的。聊天網頁可能給你送了 token，但那是給聊天用的，API 調用要單獨充值。
【坑 033】通義千問 / 阿里雲百鍊怎麼拿 Key
第 1 步：打開 https://bailian.console.aliyun.com
第 2 步：用你的阿里雲賬號登錄（沒有就註冊一個）
第 3 步：左側菜單找"API-KEY"
第 4 步：點"創建"，確認
第 5 步：複製 Key（以 sk- 開頭）
通義千問系列在 Hermes 裏通常要用 custom provider + OpenAI 兼容端點的方式接入，Base URL 填：
https://dashscope.aliyuncs.com/compatible-mode/v1
【坑 034】智譜 GLM / z.ai 怎麼拿 Key
國內版：
打開 https://bigmodel.cn → 註冊 → API Keys → 創建
海外版：
打開 https://z.ai → 註冊 → 同上
默認送一些免費 token，用完再充。
【坑 035】Kimi / Moonshot 怎麼拿 Key
第 1 步：打開 https://platform.moonshot.cn
第 2 步：註冊登錄
第 3 步：左側"API Keys" → 創建
第 4 步：複製 sk-xxxx
Kimi 註冊送一些免費額度，足夠新手玩很久。
【坑 036】OpenRouter 怎麼拿 Key（需要境外支付能力）
第 1 步：打開 https://openrouter.ai
第 2 步：註冊（推薦用 GitHub/Google 賬號登錄）
第 3 步：右上角頭像 → Keys → Create Key
第 4 步：充值需要信用卡或 Crypto（至少 $5）
OpenRouter 的特點是 一個 Key 能接幾百種海外模型，包括 Claude、GPT、Gemini、Llama 等。
【坑 037】hermes model 嚮導進去之後不知道選什麼
跑：
hermes model
會進入交互式嚮導。大致界面：
┌─────────────────────────────────────────────────────┐
│ Select your provider: │
│ │
│ > OpenRouter │
│ Nous Portal │
│ OpenAI │
│ Anthropic │
│ DeepSeek │
│ Moonshot / Kimi │
│ z.ai / ZhipuAI │
│ MiniMax │
│ Ollama (local) │
│ Custom OpenAI-compatible endpoint │
└─────────────────────────────────────────────────────┘
用上下箭頭選，回車確認。
小白選擇指南：
新手第一次：選 DeepSeek 上面沒有你要的 Provider（比如通義、百度文心、MiniMax 等）：選 Custom OpenAI-compatible endpoint 想試玩 Hermes 官方模型：選 Nous Portal
【坑 038】嚮導裏提示 "API Key is invalid"
你填完 Key 後提示：
┌──────────────────────────────────────────────────────┐
│ Error: API Key authentication failed │
│ Provider returned: 401 Unauthorized │
└──────────────────────────────────────────────────────┘
排查順序：
第 1 步：檢查是否多複製了空格或換行
打開某個記事本，把 Key 粘進去，看開頭結尾是不是多一個空格
Key 的標準格式：sk-後面一串字符，不應該有任何空格
第 2 步：檢查 Key 是否完整
很多 Provider 生成 Key 時，彈窗關閉就看不到完整 Key
重新去 Provider 後台生成一個新的
第 3 步：檢查賬户是否已充值
有些 Provider（比如 DeepSeek）即使註冊了，但不充值 Key 也無法調用
登錄 Provider 後台確認有餘額
第 4 步：檢查 Provider 有沒有要求"實名認證"
阿里雲百鍊、騰訊雲等國內大廠需要先實名
【坑 039】嚮導裏填錯了，想改怎麼辦
最簡單做法：重新跑一次 hermes model，它會覆蓋之前的配置。
手動改：
API Key 保存在 ~/.hermes/.env 文件裏。
# 打開文件編輯
nano ~/.hermes/.env
裏面內容長這樣：
OPENROUTER_API_KEY=sk-xxx
DEEPSEEK_API_KEY=sk-yyy
找到對應行改成新的，Ctrl+O 保存，Ctrl+X 退出。
【坑 040】/model 和 hermes model 有什麼區別
這是 2026 年 4 月博客園高贊帖總結的小白必踩坑：
hermes model ← 在終端外面跑，改的是"默認模型"
影響所有新開的 session
/model ← 在 Hermes 對話內部打，只改"當前這輪對話"
下次新開對話又回到默認
小白場景建議：
想永久換模型 → 退出 Hermes，跑 hermes model只想這次換一下（比如臨時用 Claude 寫個文）→ 對話裏打 /model
【坑 041】模型名寫錯了
┌──────────────────────────────────────────────────────┐
│ Error: Model 'deepseek' not found │
│ Available models: deepseek-chat, deepseek-reasoner │
└──────────────────────────────────────────────────────┘
很多新手直接把 Provider 名當成模型名填了。錯。
各家正確的模型名：
deepseek-chatdeepseek-reasoner | |
moonshot-v1-8kmoonshot-v1-32k、moonshot-v1-128k | |
qwen-maxqwen-plus、qwen-turbo | |
glm-4-plusglm-4-flash | |
anthropic/claude-sonnet-4openai/gpt-4o 等 | |
gpt-4oo1、o3 |
最新的模型名可能有變化，以 Provider 官網為準。
【坑 042】"Token limit exceeded" / "context length exceeded"
┌──────────────────────────────────────────────────────┐
│ Error: Token limit exceeded │
│ Your request had 8192 tokens but the model's │
│ context window is only 4096. │
└──────────────────────────────────────────────────────┘
意思：你這一輪對話塞進去的內容，超過了模型能處理的上下文。
小白理解：模型就像一個短期記憶窗口，一次只能看 N 個字。超了就報錯。
解決路徑：
方案 A（最快）：換個長上下文的模型
deepseek-chat：64K
moonshot-v1-128k：128K
claude-sonnet-4：200K
換到其中一個，絕大多數場景夠用
方案 B：開新會話
不用 hermes --continue，直接敲 hermes 開乾淨會話
不讓老對話佔用上下文
方案 C：清理 MEMORY.md
~/.hermes/memories/MEMORY.md 文件塞太多內容也會佔上下文
打開看看，刪點沒用的
方案 D：改 Ollama 的 num_ctx（只有用 Ollama 本地模型時）
見坑 058
【坑 043】回覆全是英文，怎麼讓它說中文
原因：模型默認用英文。你沒明確告訴它用中文。
解決：編輯 ~/.hermes/SOUL.md（如果沒有就新建）：
# 身份
你是一箇中文 AI 助手，名叫 Hermes。
# 行為準則
- 默認使用簡體中文回覆。英文產品名、專有名詞保留英文。
- 不要主動翻譯中文為英文。
- 除非用戶明確要求英文回覆，否則一律中文。
保存。下次啓動 Hermes 自動加載。
驗證：進入 Hermes 跟它說"用中文自我介紹一下"，應該中文回你。
【坑 044】回覆是亂碼或者方塊字
你看到：
Hermes: ä½ å¥½ï¼Œæˆ‘æ˜¯...
原因：你的終端沒設 UTF-8。
Mac / Linux 解決：
# 在 ~/.bashrc 或 ~/.zshrc 末尾加：
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
# 然後：
source ~/.bashrc # 或 ~/.zshrc
WSL2 / Windows 終端解決：
Windows Terminal → 設置 → 默認值 → 高級 → 文字呈現下面勾"UTF-8 BOM"。
【坑 045】連接超時 / 連不上模型服務
┌──────────────────────────────────────────────────────┐
│ Error: Connection timed out │
│ Failed to reach api.deepseek.com │
└──────────────────────────────────────────────────────┘
排查：
# 第 1 步：看看能不能 ping 通
ping api.deepseek.com
按 Ctrl+C 停止。
看結果：
64 bytes from ...→ 能通，回到坑 038 檢查 KeyRequest timeout→ 網絡問題Unknown host→ DNS 問題（回到坑 006）
網絡問題的解決：
方案 A：換 DNS
Mac: 系統設置 → 網絡 → 高級 → DNS → 加 8.8.8.8
Linux: sudo nano /etc/resolv.conf
方案 B：換節點
有些 Provider 有國內/海外不同節點，用國內節點延遲低
方案 C：設代理
export https_proxy=http://代理地址:端口
再跑 hermes
【坑 046】"Rate limit exceeded"（調用頻率超限）
┌──────────────────────────────────────────────────────┐
│ Error 429: Too Many Requests │
│ You have exceeded the rate limit of 10 req/min │
└──────────────────────────────────────────────────────┘
原因：短時間請求太多，被 Provider 限流。
解決路徑：
方案 A：等 1 分鐘再試
大多數限流是按分鐘重置的
方案 B：升級賬户等級
DeepSeek 充值 50 元以上自動升級到更高的限流閾值
OpenRouter 有付費等級
方案 C：配 Fallback Provider（v0.12+ 功能）
hermes fallback
加一個備用 Provider，主 Provider 掛了自動切
【坑 047】Provider 服務器本身掛了
┌──────────────────────────────────────────────────────┐
│ Error 503: Service Unavailable │
│ The server is temporarily down for maintenance │
└──────────────────────────────────────────────────────┘
這不是你的問題。Provider 自己的服務器問題。
解決：
去 Provider 官網看"系統狀態"頁 如果他們在維護，換一個 Provider 臨時用 有配 Fallback 會自動切（見坑 046）
【坑 048】自定義 OpenAI 兼容端點怎麼填
很多國產 Provider（阿里雲百鍊、字節火山引擎、七牛雲等）支持"OpenAI 兼容端點"。
在 hermes model 嚮導裏選 Custom OpenAI-compatible endpoint，會問你：
Provider name: 隨便起，比如 my-qwen
Base URL: 填 Provider 給的兼容端點
API Key: 你的 Key
Default model: 填這個 Provider 下某個具體模型名
常用 Base URL 速查：
https://dashscope.aliyuncs.com/compatible-mode/v1 | |
https://ark.cn-beijing.volces.com/api/v3 | |
https://api.qnaigc.com/v1 | |
https://api.siliconflow.cn/v1 |
【坑 049】充了錢但還是報 "insufficient balance"
原因：大多數 Provider 充值有到賬延遲（幾秒到幾分鐘），或者你充到了另一個賬號。
排查：
第 1 步：回 Provider 後台看餘額
確實到賬了 → 等 5 分鐘重試
沒到賬 → 看訂單狀態
第 2 步：確認你充值用的是同一個賬號
有些 Provider 區分"個人賬號"和"企業賬號"
第 3 步：確認沒填錯 Key
每個賬號的 Key 不通用
【坑 050】配完模型，對話不回 / 一直轉圈
症狀：你問它問題，光標在閃，但永遠不出結果。
遞進式排查：
第 1 步：看終端有沒有紅字報錯
有紅字 → 按報錯信息對應坑找
第 2 步：運行體檢
hermes doctor
看哪一項紅叉，按建議修
第 3 步：看日誌
tail -f ~/.hermes/logs/*.log
會看到最新的幾行日誌
第 4 步：重啓 Hermes
Ctrl+C 中斷 → 重新 hermes
第 5 步：換個模型試
/model 切到另一個 Provider
如果新模型能回答，說明原 Provider 有問題
【坑 051】換模型的時候原來的會話丟了
預防：不要在對話裏用 /reset 或 /clear，那會清空歷史。
恢復歷史：
# 看所有歷史 session
hermes sessions
# 恢復某一個
hermes --resume <session-id>
【坑 052】返回消息特別慢
原因和解決：
情況 A：模型本身慢（比如 reasoner 類需要"深思熟慮"）
→ 耐心等，或換個 chat 類模型
情況 B：網絡抖動
→ 換 DNS 或用國內節點
情況 C：你用了 Ollama 本地模型，機器配置不夠
→ 換個小一點的模型，或上雲 API
【坑 053】"Model does not support tool calling"
┌──────────────────────────────────────────────────────┐
│ Error: The selected model does not support tool │
│ calling. Please choose a model with tool support. │
└──────────────────────────────────────────────────────┘
原因：Hermes 是個 Agent，很依賴"調用工具"這個能力。有些模型（尤其免費的小模型）不支持。
解決：換支持 tool calling 的模型。
確認支持的：
DeepSeek 系列全支持 Kimi Moonshot v1 系列支持 Claude 3.5+ 支持 GPT-4 系列支持 Qwen 2.5+ 支持 Llama 3.1+ 70B 以上版本支持
不支持的：
很多免費的 embedding 模型 一些小於 7B 的本地模型
【坑 054】Anthropic Claude 訂閲模式"out of extra usage"
這是 2026 年 4 月 GitHub issue #6475 報告的老 bug：
┌──────────────────────────────────────────────────────┐
│ You're out of extra usage. │
│ (即使你剛訂閲、剛重啓也可能出現這個) │
└──────────────────────────────────────────────────────┘
解決：
# 重新登錄 Claude 訂閲
hermes model
# 選 Anthropic → 用 OAuth 流程重新登錄
# 或者切換到 Claude API Key 模式
# 在 Anthropic 後台拿 API Key，填進去
【坑 055】配置文件改了但沒生效
症狀：你改了 ~/.hermes/config.yaml 或 .env，但 Hermes 行為沒變。
原因：Hermes 啓動時就把配置讀進內存，改文件不會自動重載。
解決：
# Ctrl+C 退出當前 Hermes
# 重新啓動
hermes
Docker 版：
docker restart hermes
【坑 056】hermes config show 看不到你改的字段
hermes config show
輸出只顯示默認值，看不到你剛改的。
原因：配置文件格式錯誤（YAML 很嚴格）。
檢查：
# 用 Python 檢查 YAML 是否合法
python3 -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))"
看到報錯說明格式錯了。常見錯誤：
縮進用了 tab 而不是空格 冒號後忘了加空格 字符串裏有特殊符號但沒加引號
【坑 057】Ollama 本地模型：上下文默認才 4096
這是本地模型最大的坑。
Ollama 默認 num_ctx 只有 2048 或 4096，但 Hermes 需要 至少 64000 才能正常工作（因為要塞系統提示、工具 schema、歷史消息等）。
解決：
編輯 ~/.hermes/config.yaml，在 providers 下面加：
providers:
ollama:
options:
num_ctx: 65536
保存後重啓 Hermes。
驗證：
# 讓它做一箇中等長度的任務
hermes -q "讀取當前目錄的 5 個 md 文件，總結每個文件的主題"
不報 "context length exceeded" 就是生效了。
【坑 058】Ollama 報 model not found
┌──────────────────────────────────────────────────────┐
│ Error: model 'qwen3:8b' not found, try pulling it │
└──────────────────────────────────────────────────────┘
解決：先讓 Ollama 下載這個模型。
# 拉模型（要下載，可能幾 GB）
ollama pull qwen3:8b
# 看本地有哪些模型
ollama list
然後讓 Hermes 用這個模型（名字要和 ollama list 裏完全一致）。
【坑 059】Ollama 連接被拒絕
┌──────────────────────────────────────────────────────┐
│ Error: Connection refused (127.0.0.1:11434) │
└──────────────────────────────────────────────────────┘
原因：Ollama 服務沒啓動。
解決：
# 啓動 Ollama 服務
ollama serve
# 或者在 Mac 上打開 Ollama 應用
Mac 裝了 Ollama 之後，要確保菜單欄右上角有 Ollama 的小圖標，沒有就去應用裏打開。
【坑 060】Ollama 工具調用不穩，偶爾亂回覆
原因：本地模型的 tool calling 能力不穩定，特別是 8B 以下的小模型。
解決：
建議 A：換更強的模型
Qwen 2.5 14B 起步
Llama 3.3 70B 更穩
Hermes 3 70B（和 Agent 同名同系列，最適配）
建議 B：減少同時啓用的工具
config.yaml 裏減少 toolsets，讓模型壓力小一點
建議 C：回去用雲 API
本地模型不是新手第一選擇
穩定優先的場景用 DeepSeek 雲 API
API 配置階段的 25 個坑講完了。接下來是最後一塊——接入聊天軟件。
💬 第三部分 · 接入聊天軟件的 25 個坑
先理解：Gateway 是什麼
很多人搞不懂為什麼接入聊天軟件要那麼多步驟。先理解概念：
┌──────────────────────────────────────────────────────────┐
│ 你在手機上發消息 │
│ ↓ │
│ 聊天軟件的服務器（飛書/企業微信/Telegram） │
│ ↓ │
│ Hermes Gateway（後台進程，負責接收和轉發） │
│ ↓ │
│ Hermes Agent（真正幹活的大腦） │
│ ↓ │
│ 調用 AI 模型 → 得到回覆 │
│ ↓ │
│ 沿原路返回到你的手機 │
└──────────────────────────────────────────────────────────┘
關鍵點：Gateway 是一個必須 7×24 小時跑的後台進程。它一停，所有接入的聊天機器人全都"死"。
【坑 061】hermes gateway setup 找不到想接的平台
跑：
hermes gateway setup
看到列表裏沒有你要的（比如沒看到微信相關選項）。
原因：
個人微信（wxwork 以外）不是 Hermes 官方支持的平台 要接個人微信只能走第三方工具轉發（不在本文範圍）
Hermes 官方支持的主流聊天平台（按推薦度）：
【坑 062】飛書：創建自建應用時找不到入口
第 1 步：訪問 https://open.feishu.cn
第 2 步：右上角"登錄"（用你日常用的飛書賬號就行，不需要企業管理員）
第 3 步：登錄後右上角有"開發者後台"按鈕
第 4 步：進入開發者後台 → 左上角"創建企業自建應用"
有的人沒看到"開發者後台"按鈕，因為：
症狀 A：你登錄的是"Feishu"還是"Lark"？
中國大陸用的是 feishu.cn
國際版/海外是 larksuite.com
兩個後台入口獨立，選對應的
症狀 B：頁面加載慢/加載不全
換 Chrome 或 Edge 瀏覽器
清理緩存再重試
【坑 063】飛書：拿到 App ID 和 App Secret 後找不到在哪
創建完應用後，進入應用的詳情頁：
左側菜單 → "憑證與基礎信息"
會看到兩個關鍵字段：
App ID: cli_xxxxxxxxxxxxxxxx
App Secret: yyyyyyyyyyyyyyyyyyyy（點擊"顯示"或"查看"才能看到）
把這兩個複製好。
【坑 064】飛書：hermes gateway setup 填完之後報錯
┌──────────────────────────────────────────────────────┐
│ Error: Feishu authentication failed │
│ invalid app_id or app_secret │
└──────────────────────────────────────────────────────┘
排查：
第 1 步：App Secret 少複製了？
有些瀏覽器複製帶了換行符
把複製的內容粘到記事本，確認首尾無空格
第 2 步：App 還沒發佈？
飛書應用創建完還要"發佈"才能用
在應用後台 → "版本管理與發佈" → 創建新版本 → 發佈
第 3 步：選錯了 Feishu/Lark？
中國版和海外版 API 端點不同
確認嚮導裏選的和你賬號一致
【坑 065】飛書：Bot 權限不夠
症狀：Bot 發消息後，終端日誌顯示"權限不足"。
解決：去飛書開放平台應用後台：
左側 → "權限管理"
最少勾選這幾項：
□ im:message → 接收消息
□ im:message.send_as_bot → 以 Bot 身份發消息
□ im:chat → 獲取會話信息
□ im:resource → 接收圖片/文件（建議勾）
勾完之後點"保存"，然後一定要再次發佈應用新版本，否則權限不生效。
【坑 066】飛書：Bot 在單聊裏回應但羣裏不回
原因：飛書羣聊默認要 @ Bot 才會回應。
三種處理方式：
方案 A（推薦）：羣裏 @Bot 再說話
手動 @ 一下，Bot 才會收到
方案 B：在應用後台配置"接收所有羣消息"
需要企業管理員審批（公司應用）
方案 C：改 Hermes 配置，讓它響應羣裏所有消息
編輯 ~/.hermes/config.yaml，在 feishu 適配器下加：
respond_to_non_mentions: true
小白建議：A 方案最省事。
【坑 067】飛書：消息回覆了但連結點不動
Bot 回覆裏的連結點了沒反應。
原因：飛書有安全域名限制。
解決：回開放平台應用後台 → "安全設置" → "Web 應用消息卡片域名白名單" → 加上你要跳轉的域名。
【坑 068】飛書：審批卡片點了無反應
這是 GitHub Issue #11600 報告的已知問題（v0.9.0）。
v0.10+ 已修復。如果你還在用老版本：
hermes update
升到最新版。
【坑 069】企業微信：掃碼創建 Bot 失敗
按照官方推薦的掃碼創建方式：
hermes gateway setup
# 選擇 WeCom → Bot 模式
# 終端顯示一個二維碼
# 用企業微信手機 App 掃碼
掃完報錯：
┌──────────────────────────────────────────────────────┐
│ Failed to create bot: organization not found │
└──────────────────────────────────────────────────────┘
原因：
A. 你的賬號不是企業管理員
→ 讓管理員掃碼，或讓管理員提前創建好 Bot
B. 你的企業微信賬號不是"企業版"
→ 純個人企業微信賬號無法創建 AI Bot
→ 需要註冊企業（至少是個人創辦的企業），然後使用企業管理員身份
【坑 070】企業微信：掃碼成功，但 Bot 在對話裏不回消息
排查：
第 1 步：看 Hermes 日誌
tail -f ~/.hermes/logs/gateway.log
看發消息時有沒有收到來自企業微信的事件
第 2 步：確認 Bot 是"啓用"狀態
企業微信管理後台 → 應用管理 → 找到你的 Bot
狀態是否是"已啓用"
第 3 步：檢查可見範圍
默認只有創建者可見，需要加"全員可見"或指定人員
第 4 步：重啓 Gateway
docker restart hermes
或 systemctl --user restart hermes-gateway
【坑 071】企業微信 Callback 模式：回調 URL 驗證失敗
如果你選了更高級的 Callback 模式（不是 Bot 模式）：
┌──────────────────────────────────────────────────────┐
│ 驗證失敗：URL 無法訪問 │
└──────────────────────────────────────────────────────┘
原因：企業微信要從公網訪問你的服務器。
解決：
條件 1：你的 Hermes 必須跑在有公網 IP 的機器上
（家裏 NAT 內網不行）
條件 2：8642 端口對外開放
防火牆放行
雲服務器安全組放行
條件 3：推薦配 HTTPS
企業微信對 HTTP 回調有限制
用 Caddy 或 Nginx 配一個免費的 Let's Encrypt 證書
小白建議：先用 Bot 模式（WebSocket），不要碰 Callback 模式。
【坑 072】釘釘：Stream Mode 連接失敗
釘釘 Stream 模式也是長連接，不需要公網：
hermes gateway setup
# 選 DingTalk → Stream Mode
# 填 AppKey 和 AppSecret
連接失敗的原因：
A. AppKey/AppSecret 來源錯
需要在"釘釘開放平台"（open.dingtalk.com）創建應用
不是釘釘後台的普通機器人
B. 應用類型錯
要創建"企業內部開發" → "H5 微應用"或"Stream 模式機器人"
C. 沒開 Stream 模式權限
進入應用詳情 → 基礎信息 → 應用信息
開啓 Stream 模式開關
【坑 073】釘釘：消息收到了但回覆不了
┌──────────────────────────────────────────────────────┐
│ Error: session-webhook-url not configured │
└──────────────────────────────────────────────────────┘
原因：釘釘用 "session webhook" 送回回覆，需要單獨配。
解決：回開放平台應用後台 → 添加能力"機器人" → 開啓回調。
【坑 074】Telegram：Bot Token 被複制 8 遍
這是 GitHub Issue #8908 報的老 bug。
┌──────────────────────────────────────────────────────┐
│ InvalidToken: 8 concatenated tokens detected │
└──────────────────────────────────────────────────────┘
原因：.env 裏填 Token 時不小心粘了 8 次。
解決：
nano ~/.hermes/.env
找到 TELEGRAM_BOT_TOKEN= 這一行，把後面的值改成一個單獨的 Token（以 數字:xxx 的格式）。
【坑 075】Telegram：webhook 模式缺依賴
┌──────────────────────────────────────────────────────┐
│ ImportError: python-telegram-bot[webhooks] missing │
└──────────────────────────────────────────────────────┘
這是 GitHub Issue #4915 的老 bug。
解決：
pip install "python-telegram-bot[webhooks]"
或者乾脆不用 webhook 模式，用 polling 模式（默認就是 polling，不需要公網）。
【坑 076】Telegram：國內連不上 telegram.org
┌──────────────────────────────────────────────────────┐
│ Error: Connection to api.telegram.org failed │
└──────────────────────────────────────────────────────┘
原因：眾所周知。
解決：
方案 A（最穩）：Hermes 跑在海外服務器上
方案 B：給 Hermes 配代理
export https_proxy=http://代理地址:端口
再跑 hermes gateway
國內用戶建議放棄 Telegram，選飛書或企業微信。
【坑 077】Discord：Bot 不響應 @mention
Symptom: Bot 在服務器裏，但 @它 沒反應
排查：
第 1 步：看 hermes status
確認 Discord 連接狀態為 Connected
第 2 步：檢查 Bot 角色權限
服務器設置 → 角色 → hermes_bot
至少要有：Send Messages, Read Message History, Use Application Commands
第 3 步：檢查 Bot 是否被頻道屏蔽
頻道權限裏是否禁用了該 Bot
第 4 步：重啓 Gateway
docker restart hermes
【坑 078】通用：Bot 收到消息但"一直在輸入"再也不回
這是最難排查的症狀。
遞進式排查：
第 1 步：看日誌
tail -n 100 ~/.hermes/logs/gateway.log
找有沒有錯誤、warnings
第 2 步：測試 CLI 是否能用
docker exec -it hermes hermes
（如果是 Docker 版）
在 CLI 裏問一個簡單問題
能回 → 問題在 Gateway，不在 Agent
不能回 → 問題在 Agent，回去看 API 配置
第 3 步：檢查 API Key 是否過期
在 Provider 後台看 Key 是否還 active
看餘額還有沒有
第 4 步：強制清空並重啓
Ctrl+C 或 docker stop hermes
重新啓動
【坑 079】多 Profile 用同一個 Bot Token 打架
┌──────────────────────────────────────────────────────┐
│ Error: Another process is using this bot's webhook │
└──────────────────────────────────────────────────────┘
原因：一個 Bot Token 只能被一個 Gateway 進程佔用。
解決：
方案 A（推薦）：每個 profile 創建獨立的 Bot
飛書/Telegram/企業微信都支持你創建多個 Bot
每個 profile 分配一個，互不干擾
方案 B：關掉一個 profile 的 Gateway
如果不需要多 profile 同時在線
把不用的 profile 的 gateway 關掉
【坑 080】Cron 任務定時了但 Bot 不發消息
這是小白最常見的"最後一公里"失敗。
原因：Hermes 的 cron 任務只會在 Gateway 後台進程運行時觸發。
排查：
第 1 步：Gateway 還活着嗎？
docker ps | grep hermes
(STATUS 是 Up 多少天)
第 2 步：Cron 任務是否真的創建了？
docker exec hermes hermes cron list
第 3 步：任務的下次觸發時間是啥時候？
docker exec hermes hermes cron status
看下一次該跑的時間
第 4 步：cron 的 prompt 裏有沒有"調用 messaging 工具發到指定聊天平台"
新建的 cron 默認**不會**把結果發到飛書/Telegram
要在 prompt 裏明確說：
"生成完日報後，用 messaging 工具發送到我的飛書私聊"
🛠️ 第四部分 · 兜底篇
終極自查五步法（前面 80 個坑都沒對上時用）
如果你的問題不在上面 80 個坑裏，按這個順序來：
第 1 步：hermes doctor
看是不是基礎環境出問題
第 2 步：hermes config show
看配置有沒有寫錯
第 3 步：查 provider 後台
API Key 是否有效、餘額是否夠
第 4 步：查日誌
tail -f ~/.hermes/logs/*.log
看實時輸出，截最後幾十行
第 5 步：升級到最新版
hermes update
很多問題其實是老版本 bug，升上去自動消失
【兜底 1】日誌在哪？怎麼看？
所有日誌都在：
~/.hermes/logs/
常用命令：
# 看實時日誌（Ctrl+C 停止）
tail -f ~/.hermes/logs/gateway.log
# 看最後 100 行
tail -n 100 ~/.hermes/logs/gateway.log
# 搜關鍵詞（比如找 error）
grep -i "error" ~/.hermes/logs/gateway.log
Docker 版：
docker logs -f hermes
【兜底 2】怎麼把問題發給朋友幫忙看
新手問人前，先收集四樣東西：
1. 你的操作系統（Mac / Windows+WSL2 / Ubuntu 等）
2. Hermes 版本
hermes --version
3. 完整報錯信息（從紅字開始到結束）
4. 你做了什麼才觸發的
這四樣齊了，問人才不會被說"信息不全"。
【兜底 3】哪裏能快速拿到幫助
官方文檔： hermes-agent.nousresearch.com/docs/
官方 FAQ： hermes-agent.nousresearch.com/docs/reference/faq/
GitHub Issues：github.com/NousResearch/hermes-agent/issues
（搜你的關鍵詞，80% 你踩的坑別人都踩過）
搜 Issues 的姿勢：
搜關鍵詞，用英文
比如搜 "token limit" 而不是 "字數超限"
搜 error 後面帶具體報錯碼
【兜底 4】升級到 v0.13 的注意事項
如果你在用老版本（比如 v0.10 或 v0.11），升級到最新的 v0.13 時注意：
第 1 步：先備份
tar -czf hermes-backup-before-upgrade.tar.gz ~/.hermes/
第 2 步：升級
hermes update
第 3 步：遷移配置（很多老字段被重命名或拆分）
hermes config check → 看哪些字段過時
hermes config migrate → 交互式升級到新格式
第 4 步：重啓所有 Hermes 進程
docker restart hermes
或
systemctl --user restart hermes-gateway
第 5 步：驗證核心功能
hermes doctor
hermes model
發一條消息給你的 Bot
v0.13 的一些破壞性更新（非技術小白可跳過）：
Kanban 系統重構，老的任務記錄可能要手動遷移 /goal命令新增，老版本里的"全會話目標"改成了這個Checkpoints v2 重寫， /rollback的界面變了8 個 P0 安全修復，建議一定升
【兜底 5】實在搞不定，重裝
如果排查下來就是搞不定，最快的方式：重裝。
# 1. 備份
tar -czf hermes-backup.tar.gz ~/.hermes/
# 2. 清乾淨
rm -rf ~/.hermes
# 3. 重裝
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc # 或 ~/.zshrc
# 4. 重新配
hermes setup
# 5. 如果原來的記憶和 skill 重要，選擇性恢復
tar -xzf hermes-backup.tar.gz
cp -r backup/.hermes/memories ~/.hermes/
cp -r backup/.hermes/skills ~/.hermes/
重裝比繼續折騰經常更快。別怕這一步。
📮 第五部分 · 下篇預告
到這裏，Hermes 的裝機 + 配模型 + 接聊天軟件全部打通了。
前三篇回顧：
保姆教程 01：
從 0 到擁有第一個能聽懂中文的 AI 助手
保姆教程 02：
讓它搬進服務器，定時上班，有自己的目標
保姆教程 03（本篇）：
80 個坑 · 一本工具書 · 裝什麼都不怕
保姆教程 04（下一篇預告）：
讓 AI 替你畫圖
—— 把 Hermes 接上 ComfyUI / 即夢 / 可靈 / Midjourney
—— 它幫你優化 prompt、批量出圖、自動挑出最好的
—— 你睡覺時它在工作，早上起來有 50 張待你選
這才是我們系列真正的終局：把 Hermes 做成你"AI 繪圖工作台"的大腦。
📚 系列文章索引
保姆教程 01 · Hermes 新手教程：從 0 到第一次對話 保姆教程 02 · Hermes 進階：讓 AI 員工 24 小時替你上班 保姆教程 03 · 本篇（全網問題百寶箱，收藏向） 保姆教程 04 · 即將發佈（Hermes × 圖像生成工作流） 保姆教程 05 · 計劃中（Hermes × 視頻生成工作流）
回看前兩篇：公眾號回覆 "Hermes 01" 或 "Hermes 02" 獲取。
本篇的完整 Markdown 版 + 所有命令打包：公眾號回覆 "排錯手冊" 獲取。
🎁 寫在最後
這篇不是為了讓你一次讀完。
是為了讓你在某個深夜，裝 Hermes 裝到一半，終端全是紅字，想砸電腦的時候——
打開公眾號，翻到這篇，按着 Ctrl+F 搜一個關鍵詞，找到那個坑，照着做，問題解決。
每解決一個，就把它標個記號。標記號的坑越多，你就從"小白"熬成"半高手"了。
祝你明年這個時候，回來翻這篇，能笑着說："這 80 個坑我都踩過了。"
資料來源（均已交叉核對）
Hermes Agent 官方 FAQ & Troubleshooting Hermes Agent 官方 Quickstart Hermes Agent 官方 Installation Hermes Agent 官方 GitHub Issues Hermes Agent 飛書接入文檔 Hermes Agent 企業微信接入文檔 Hermes Agent 釘釘接入文檔 Hermes Agent 中文完整排錯指南（博客園） Hermes Agent 避坑完全指南（博客園） Hermes Agent 報錯完全排查手冊（博客園） Hermes Agent DeepSeek 接入完整指南（博客園） Troubleshooting Hermes Agent · meshworld.in Fix Hermes Agent Installation Errors · markaicode.com Hermes Agent Troubleshooting 8 Errors · bswen.com
以上內容基於 Hermes Agent v0.13.0（2026 年 5 月）核對。項目更新非常快，命令和界面有版本差異時，以你實際裝到的
hermes --help為準。