這一篇不是教程。這是一本工具書。 你裝 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 --installUbuntu / Debian / WSL2 用戶：sudo apt updatesudo apt install -y gitCentOS / 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-certificatesUbuntu 用戶：sudo apt install -y ca-certificatessudo 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.11Ubuntu 用戶：sudo apt updatesudo 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/binecho $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 ~/.hermescurl -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搜索工具沒裝Mac: brew install ripgrep / Ubuntu: sudo apt install ripgrepffmpeg not found音視頻工具沒裝Mac: brew install ffmpeg / Ubuntu: sudo apt install ffmpegNo provider configured沒配模型hermes model 進嚮導Python version too lowPython 太舊裝 Python 3.11+PATH issue detectedPATH 有問題回到坑 010-011【坑 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-getsudo rm /var/lib/dpkg/lock-frontendsudo rm /var/lib/dpkg/locksudo 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 -ysudo apt updatesudo apt install -y python3.11 python3.11-venvMac 用戶（已裝 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 裝（能裝多個版本，隨時切）：# 裝 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash# 重載終端source ~/.bashrc # 或 ~/.zshrc# 裝 Node 22（Hermes 推薦）nvm install 22# 用 22nvm use 22【坑 018】uv: command not founduv 是 Hermes 用的新式 Python 包管理器。# 手動裝 uvcurl -LsSf https://astral.sh/uv/install.sh | shsource ~/.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 cleansudo apt autoremove # 清理 brew 緩存（Mac）brew cleanup -s【坑 020】WSL2 裏裝 Hermes，C 盤空間暴漲症狀：WSL2 裏裝完 Hermes，你 Windows C 盤少了 10GB。原因：WSL2 的 Ubuntu 子系統默認放在 C 盤，裏面裝什麼都算 C 盤。解決：把 WSL2 移到 D 盤。在 PowerShell（管理員）裏：# 1. 先停掉 WSLwsl --shutdown# 2. 導出當前 Ubuntuwsl --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 startsystemctl --user enable hermes-gatewayenable 這個命令的意思是"開機自啓"。【坑 024】Ubuntu 22.04 裝完之後路徑裏有 snap 導致衝突症狀：跑 hermes 報奇怪的 Python 錯誤，仔細一看 Python 用的是 /snap/bin/python 裏的。解決：# 調整 PATH，把 ~/.hermes/bin 放到 snap 前面echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.bashrcsource ~/.bashrc關鍵是把 Hermes 路徑放最前面。shell 找命令按 PATH 從左到右找，第一個找到的贏。【坑 025】CentOS / AlmaLinux / Rocky：yum 提示 package not found這幾個發行版默認源太保守，很多包找不到。開 EPEL 源：sudo dnf install -y epel-releasesudo dnf updatesudo dnf install -y git curl ripgrep ffmpegEPEL 全稱是 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 對話CronTelegram GatewayMCPHoncho memoryACP不支持：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】不知道選哪個 ProviderHermes 支持的主流 Provider 一覽：Provider特點中國用戶友好度最低起步費DeepSeek國產、便宜、支持長上下文⭐⭐⭐⭐⭐10 元通義千問 / 阿里雲國產大廠、合規⭐⭐⭐⭐看套餐智譜 GLM / z.ai國產閉源強⭐⭐⭐⭐看套餐Kimi / Moonshot超長上下文⭐⭐⭐⭐看套餐MiniMax有國內節點⭐⭐⭐⭐看套餐OpenRouter一個 Key 接幾百個海外模型⭐⭐⭐（需境外支付）$5Nous PortalHermes 官方自營⭐⭐⭐（需境外支付）免費 $0.10 額度/月推薦：首選 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-xxxxKimi 註冊送一些免費額度，足夠新手玩很久。【坑 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-xxxDEEPSEEK_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 名當成模型名填了。錯。各家正確的模型名：Provider常用模型名（原樣複製）DeepSeekdeepseek-chat、deepseek-reasonerKimimoonshot-v1-8k、moonshot-v1-32k、moonshot-v1-128k通義qwen-max、qwen-plus、qwen-turbo智譜glm-4-plus、glm-4-flashOpenRouteranthropic/claude-sonnet-4、openai/gpt-4o 等OpenAIgpt-4o、o1、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-8export LC_ALL=en_US.UTF-8 # 然後：source ~/.bashrc # 或 ~/.zshrcWSL2 / 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-qwenBase URL: 填 Provider 給的兼容端點API Key: 你的 KeyDefault model: 填這個 Provider 下某個具體模型名常用 Base URL 速查：ProviderBase 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，那會清空歷史。恢復歷史：# 看所有歷史 sessionhermes 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# 重新啓動hermesDocker 版：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 雲 APIAPI 配置階段的 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 --installUbuntu / Debian / WSL2 用戶：sudo apt updatesudo apt install -y gitCentOS / 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-certificatesUbuntu 用戶：sudo apt install -y ca-certificatessudo 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.11Ubuntu 用戶：sudo apt updatesudo 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/binecho $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 ~/.hermescurl -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搜索工具沒裝Mac: brew install ripgrep / Ubuntu: sudo apt install ripgrepffmpeg not found音視頻工具沒裝Mac: brew install ffmpeg / Ubuntu: sudo apt install ffmpegNo provider configured沒配模型hermes model 進嚮導Python version too lowPython 太舊裝 Python 3.11+PATH issue detectedPATH 有問題回到坑 010-011【坑 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-getsudo rm /var/lib/dpkg/lock-frontendsudo rm /var/lib/dpkg/locksudo 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 -ysudo apt updatesudo apt install -y python3.11 python3.11-venvMac 用戶（已裝 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 裝（能裝多個版本，隨時切）：# 裝 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash# 重載終端source ~/.bashrc # 或 ~/.zshrc# 裝 Node 22（Hermes 推薦）nvm install 22# 用 22nvm use 22【坑 018】uv: command not founduv 是 Hermes 用的新式 Python 包管理器。# 手動裝 uvcurl -LsSf https://astral.sh/uv/install.sh | shsource ~/.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 cleansudo apt autoremove # 清理 brew 緩存（Mac）brew cleanup -s【坑 020】WSL2 裏裝 Hermes，C 盤空間暴漲症狀：WSL2 裏裝完 Hermes，你 Windows C 盤少了 10GB。原因：WSL2 的 Ubuntu 子系統默認放在 C 盤，裏面裝什麼都算 C 盤。解決：把 WSL2 移到 D 盤。在 PowerShell（管理員）裏：# 1. 先停掉 WSLwsl --shutdown# 2. 導出當前 Ubuntuwsl --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 startsystemctl --user enable hermes-gatewayenable 這個命令的意思是"開機自啓"。【坑 024】Ubuntu 22.04 裝完之後路徑裏有 snap 導致衝突症狀：跑 hermes 報奇怪的 Python 錯誤，仔細一看 Python 用的是 /snap/bin/python 裏的。解決：# 調整 PATH，把 ~/.hermes/bin 放到 snap 前面echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.bashrcsource ~/.bashrc關鍵是把 Hermes 路徑放最前面。shell 找命令按 PATH 從左到右找，第一個找到的贏。【坑 025】CentOS / AlmaLinux / Rocky：yum 提示 package not found這幾個發行版默認源太保守，很多包找不到。開 EPEL 源：sudo dnf install -y epel-releasesudo dnf updatesudo dnf install -y git curl ripgrep ffmpegEPEL 全稱是 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 對話CronTelegram GatewayMCPHoncho memoryACP不支持：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】不知道選哪個 ProviderHermes 支持的主流 Provider 一覽：Provider特點中國用戶友好度最低起步費DeepSeek國產、便宜、支持長上下文⭐⭐⭐⭐⭐10 元通義千問 / 阿里雲國產大廠、合規⭐⭐⭐⭐看套餐智譜 GLM / z.ai國產閉源強⭐⭐⭐⭐看套餐Kimi / Moonshot超長上下文⭐⭐⭐⭐看套餐MiniMax有國內節點⭐⭐⭐⭐看套餐OpenRouter一個 Key 接幾百個海外模型⭐⭐⭐（需境外支付）$5Nous PortalHermes 官方自營⭐⭐⭐（需境外支付）免費 $0.10 額度/月小白推薦：首選 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-xxxxKimi 註冊送一些免費額度，足夠新手玩很久。【坑 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-xxxDEEPSEEK_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 名當成模型名填了。錯。各家正確的模型名：Provider常用模型名（原樣複製）DeepSeekdeepseek-chat、deepseek-reasonerKimimoonshot-v1-8k、moonshot-v1-32k、moonshot-v1-128k通義qwen-max、qwen-plus、qwen-turbo智譜glm-4-plus、glm-4-flashOpenRouteranthropic/claude-sonnet-4、openai/gpt-4o 等OpenAIgpt-4o、o1、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-8export LC_ALL=en_US.UTF-8 # 然後：source ~/.bashrc # 或 ~/.zshrcWSL2 / 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-qwenBase URL: 填 Provider 給的兼容端點API Key: 你的 KeyDefault model: 填這個 Provider 下某個具體模型名常用 Base URL 速查：ProviderBase 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，那會清空歷史。恢復歷史：# 看所有歷史 sessionhermes 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# 重新啓動hermesDocker 版：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 雲 APIAPI 配置階段的 25 個坑講完了。接下來是最後一塊——接入聊天軟件。💬 第三部分 · 接入聊天軟件的 25 個坑先理解：Gateway 是什麼很多人搞不懂為什麼接入聊天軟件要那麼多步驟。先理解概念：┌──────────────────────────────────────────────────────────┐│ 你在手機上發消息 ││ ↓ ││ 聊天軟件的服務器（飛書/企業微信/Telegram） ││ ↓ ││ Hermes Gateway（後台進程，負責接收和轉發） ││ ↓ ││ Hermes Agent（真正幹活的大腦） ││ ↓ ││ 調用 AI 模型 → 得到回覆 ││ ↓ ││ 沿原路返回到你的手機 │└──────────────────────────────────────────────────────────┘關鍵點：Gateway 是一個必須 7×24 小時跑的後台進程。它一停，所有接入的聊天機器人全都"死"。【坑 061】hermes gateway setup 找不到想接的平台跑：hermes gateway setup看到列表裏沒有你要的（比如沒看到微信相關選項）。原因：個人微信（wxwork 以外）不是 Hermes 官方支持的平台要接個人微信只能走第三方工具轉發（不在本文範圍）Hermes 官方支持的主流聊天平台（按推薦度）：平台難度對小白友好度飛書 / Lark⭐⭐⭐⭐⭐⭐⭐企業微信（WeCom Bot 模式）⭐⭐⭐⭐⭐⭐Telegram⭐⭐⭐⭐⭐（國內網絡問題）Discord⭐⭐⭐⭐⭐⭐釘釘⭐⭐⭐⭐⭐⭐⭐騰訊元寶⭐⭐⭐⭐⭐⭐Slack⭐⭐⭐⭐⭐（國內不常用）【坑 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_xxxxxxxxxxxxxxxxApp 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. 你的賬號不是企業管理員 → 讓管理員掃碼，或讓管理員提前創建好 BotB. 你的企業微信賬號不是"企業版" → 純個人企業微信賬號無法創建 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 不響應 @mentionSymptom: 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.logDocker 版：docker logs -f hermes【兜底 2】怎麼把問題發給朋友幫忙看新手問人前，先收集四樣東西：1. 你的操作系統（Mac / Windows+WSL2 / Ubuntu 等）2. Hermes 版本 hermes --version3. 完整報錯信息（從紅字開始到結束）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 發一條消息給你的 Botv0.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 | bashsource ~/.bashrc # 或 ~/.zshrc # 4. 重新配hermes setup # 5. 如果原來的記憶和 skill 重要，選擇性恢復tar -xzf hermes-backup.tar.gzcp -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 & TroubleshootingHermes Agent 官方 QuickstartHermes Agent 官方 InstallationHermes Agent 官方 GitHub IssuesHermes Agent 飛書接入文檔Hermes Agent 企業微信接入文檔Hermes Agent 釘釘接入文檔Hermes Agent 中文完整排錯指南（博客園）Hermes Agent 避坑完全指南（博客園）Hermes Agent 報錯完全排查手冊（博客園）Hermes Agent DeepSeek 接入完整指南（博客園）Troubleshooting Hermes Agent · meshworld.inFix Hermes Agent Installation Errors · markaicode.comHermes Agent Troubleshooting 8 Errors · bswen.com以上內容基於 Hermes Agent v0.13.0（2026 年 5 月）核對。項目更新非常快，命令和界面有版本差異時，以你實際裝到的 hermes --help 為準。

• Hermes 全網問題百寶箱：從裝不上到接不通，80 個坑我替你踩完…
• Hermes 全網問題百寶箱：從裝不上到接不通，80 個坑我替你踩完…
• Hermes 全網問題百寶箱：從裝不上到接不通，80 個坑我替你踩完…
• Hermes 全網問題百寶箱：從裝不上到接不通，80 個坑我替你踩完…
• Hermes 全網問題百寶箱：從裝不上到接不通，80 個坑我替你踩完…