跳到主要內容

常見問題與故障排除

快速解答最常見的問題和解決方法。

常見問題​

Hermes 支持哪些大語言模型（LLM）提供商？​

Hermes Agent 支持任何兼容 OpenAI API 的提供商。已支持的提供商包括：

  • OpenRouter — 通過一個 API 密鑰訪問數百種模型（推薦用於靈活性）
  • Nous Portal — Nous Research 自有的推理端點
  • OpenAI — GPT-4o、o1、o3 等模型
  • Anthropic — Claude 模型（通過 OpenRouter 或兼容代理）
  • Google — Gemini 模型（通過 OpenRouter 或兼容代理）
  • z.ai / ZhipuAI — GLM 模型
  • Kimi / Moonshot AI — Kimi 模型
  • MiniMax — 全球及中國端點
  • 本地模型 — 通過 Ollama、vLLM、llama.cpp、SGLang 或任何兼容 OpenAI 的服務器運行

可通過 hermes model 命令設置提供商，或編輯 ~/.hermes/.env 文件。所有提供商密鑰的詳細信息請參見 環境變量 參考文檔。

它能在 Windows 上運行嗎？​

可以，而且當前頁面提供的是 Hermes Agent 中文社區維護的鏡像安裝入口，優先走國內可直連鏈路。Windows 用戶有兩條不同的安裝路徑：

  1. WSL2（推薦） —— 最接近官方類 Unix 工作流，兼容性最好：
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash
  1. 原生 PowerShell —— 適合想直接在 Windows 本機快速跑起來的用戶：
irm https://res1.hermesagent.org.cn/install.ps1 | iex

鏡像版安裝器默認會先完成核心安裝，並精簡掉部分國人不常用、或容易受外網影響的可選組件，以提高安裝速度和成功率。後續hermes agent配置完畢可以要求他進行補裝。如果你要長期使用終端工具、瀏覽器自動化、消息網關和各種 shell 工作流，仍然建議優先使用 WSL2。詳見 Windows 安裝指南。

它能在 Android / Termux 上運行嗎？​

可以 — Hermes 現已提供經過測試的 Termux 安裝路徑，適用於 Android 手機。

快速安裝方式：

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

如需完整手動步驟、支持的附加功能及當前限制，請參見 Termux 指南。

重要提示：目前 Android 上無法使用完整的 .[all] 附加功能，因為 voice 附加功能依賴於 faster-whisper → ctranslate2，而 ctranslate2 未發佈 Android 輪子（wheels）。請改用經過測試的 .[termux] 附加功能。

我的數據會被髮送到哪裡？​

API 調用僅發送至您配置的 LLM 提供商（例如 OpenRouter、您的本地 Ollama 實例）。Hermes Agent 不收集遙測數據、使用數據或分析信息。您的對話記錄、記憶和技能均本地存儲在 ~/.hermes/ 目錄中。

我可以離線使用或使用本地模型嗎？​

可以。運行 hermes model，選擇 自定義端點，並輸入您服務器的 URL：

hermes model
# 選擇：自定義端點（手動輸入URL）
# API 基本 URL：`http://localhost:11434/v1`
# API 密鑰：ollama
# 模型名稱：`qwen3.5:27b`
# Context 長度：32768 ← 設置它以匹配您服務器的實際 context window

或直接在 config.yaml 中配置：

model:
  default: qwen3.5:27b
  provider: custom
  base_url: http://localhost:11434/v1

Hermes 會將端點、提供商和基礎 URL 持久化保存在 config.yaml 中，因此重啟後仍有效。如果您的本地服務器僅加載了一個模型，/model custom 會自動檢測該模型。您也可以在 config.yaml 中設置 provider: custom —— 這是一個獨立的提供商，而非其他任何提供者的別名。

該功能支持 Ollama、vLLM、llama.cpp 服務器、SGLang、LocalAI 等。詳情請參見 配置指南。

Ollama 用戶

如果您在 Ollama 中設置了自定義 num_ctx（例如 ollama run --num_ctx 16384），請確保在 Hermes 中設置相同的上下文長度。Ollama 的 /api/show 接口報告的是模型的 最大 上下文長度，而非您配置的有效 num_ctx。

本地模型超時問題

Hermes 會自動檢測本地端點，並放寬流式傳輸超時時間（讀取超時從 120 秒提升至 1800 秒，禁用過期流檢測）。如果在處理超大上下文時仍遇到超時，請在 .env 文件中設置 HERMES_STREAM_READ_TIMEOUT=1800。詳情請參見 本地 LLM 指南。

使用成本是多少？​

Hermes Agent 本身是免費且開源的（MIT 許可證）。您只需為所選提供商的 LLM API 使用量付費。本地模型的運行完全免費。

多人可以共用一個實例嗎？​

可以。消息網關 支持多個用戶通過 Telegram、Discord、Slack、WhatsApp 或 Home Assistant 與同一個 Hermes Agent 實例交互。訪問權限通過白名單（特定用戶 ID）和私信配對（第一個發消息的用戶獲得訪問權）進行控制。

記憶和技能有什麼區別？​

  • 記憶 存儲的是 事實 —— Agent 關於您、您的項目和偏好的信息。記憶會根據相關性自動檢索。
  • 技能 存儲的是 操作流程 —— 完成某項任務的分步說明。當 Agent 遇到類似任務時會調用這些技能。

兩者均在會話間持久化。詳情請參見 記憶 和 技能。

我可以在自己的 Python 項目中使用它嗎？​

可以。導入 AIAgent 類，即可在程序中使用 Hermes：

from run_agent import AIAgent

agent = AIAgent(model="openrouter/nous/hermes-3-llama-3.1-70b")
response = agent.chat("Explain quantum computing briefly")

完整 API 使用方法請參見 Python 庫指南。

故障排除​

安裝問題​

安裝後出現 hermes: command not found​

原因： 您的 shell 未重新加載更新後的 PATH。

解決方案：

# 重新加載你的shell profile
source ~/.bashrc    # bash
source ~/.zshrc     # zsh

# 或者啟動一個新終端 session

如果仍無效，請驗證安裝路徑：

which hermes
ls ~/.local/bin/hermes
提示

安裝程序會將 ~/.local/bin 添加到你的 PATH 中。如果你使用的是非標準的 shell 配置，請手動添加 export PATH="$HOME/.local/bin:$PATH"。

Python 版本過舊​

原因： Hermes 要求使用 Python 3.11 或更高版本。

解決方案：

python3 --version   # 檢查當前版本

# 安裝更新的 Python
sudo apt install python3.12   # Ubuntu/Debian
brew install python@3.12      # macOS

安裝程序會自動處理此問題——如果在手動安裝過程中看到此錯誤，請先升級 Python。

uv: command not found​

原因： uv 包管理器未安裝或不在 PATH 中。

解決方案：

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

安裝過程中出現權限拒絕錯誤​

原因： 對安裝目錄寫入權限不足。

解決方案：

# 不要在安裝程序中使用 sudo — 它會安裝到 ~/.local/bin
# 如果您之前使用 sudo 安裝，請清理：
sudo rm /usr/local/bin/hermes
# 然後重新運行標準安裝程序
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

提供商與模型問題​

API 密鑰無效​

原因： 密鑰缺失、已過期、設置錯誤或與提供方不匹配。

解決方案：

# 檢查您的配置
hermes config show

# 重新配置您的 provider
hermes model

# 或者直接設置
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx
注意

請確保密鑰與提供方匹配。OpenAI 的密鑰無法用於 OpenRouter，反之亦然。請檢查 ~/.hermes/.env 中是否存在衝突的條目。

模型不可用 / 找不到模型​

原因： 模型標識符錯誤，或該模型在你的提供方上不可用。

解決方案：

# 列出適用於您的 provider 的可用 models
hermes model

# 設置有效的model
hermes config set HERMES_MODEL openrouter/nous/hermes-3-llama-3.1-70b

# 或者指定 per-session
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct

速率限制（429 錯誤）​

原因： 已超過提供方的速率限制。

解決方案： 稍等片刻後重試。對於持續使用場景，可考慮：

  • 升級提供方套餐
  • 切換到其他模型或提供方
  • 使用 hermes chat --provider <alternative> 將請求路由至其他後端

上下文長度超出限制​

原因： 對話內容過長，超出模型的上下文窗口；或 Hermes 檢測到的上下文長度與實際不符。

解決方案：

# 壓縮當前session
/compress

# 或者開始一個新的session
hermes chat

# 將 model 與更大的 context window 一起使用
hermes chat --model openrouter/google/gemini-3-flash-preview

如果在首次進行長對話時出現此問題，可能是 Hermes 對你的模型上下文長度檢測錯誤。請檢查其檢測結果：

查看 CLI 啟動行——會顯示檢測到的上下文長度（例如：📊 上下文限制：128000 個 token）。你也可以在會話中使用 /usage 命令查看。

要修復上下文長度檢測，可手動顯式設置：

# 在“0”中
model:
  default: your-model-name
  context_length: 131072  # 您的 model 的實際 context window

對於自定義端點，可按模型單獨添加：

custom_providers:
  - name: "My Server"
    base_url: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 32768

有關自動檢測機制及所有覆蓋選項的詳情，請參閱 上下文長度檢測。

終端問題​

命令被阻止為危險操作​

原因： Hermes 檢測到潛在破壞性命令（如 rm -rf、DROP TABLE）。這是安全防護機制。

解決方案： 當提示時，審查命令並輸入 y 確認執行。你也可以：

  • 要求 Agent 使用更安全的替代方案
  • 參閱 安全文檔 中的完整危險模式列表
提示

此行為符合預期——Hermes 永遠不會靜默執行破壞性命令。確認提示會明確展示即將執行的內容。

通過消息網關無法使用 sudo​

原因： 消息網關在無交互式終端的環境下運行，因此 sudo 無法提示輸入密碼。

解決方案：

  • 避免在消息中使用 sudo——請讓 Agent 尋找替代方案
  • 若必須使用 sudo，請在 /etc/sudoers 中為特定命令配置免密 sudo
  • 或切換到終端界面執行管理任務：hermes chat

Docker 後端無法連接​

原因： Docker 守護進程未運行，或用戶權限不足。

解決方案：

# 確認 Docker 正在運行
docker info

# 將您的用戶添加到 docker 組
sudo usermod -aG docker $USER
newgrp docker

# 驗證
docker run hello-world

消息通信問題​

機器人不響應消息​

原因： 機器人未運行、未授權，或你的用戶不在允許列表中。

解決方案：

# 檢查 Gateway 是否正在運行
hermes gateway status

# 啟動gateway
hermes gateway start

# 檢查日誌中的錯誤
cat ~/.hermes/logs/gateway.log | tail -50

消息無法送達​

原因： 網絡問題、機器人令牌過期，或平臺 Webhook 配置錯誤。

解決方案：

  • 使用 hermes gateway setup 驗證機器人令牌是否有效
  • 檢查網關日誌：cat ~/.hermes/logs/gateway.log | tail -50
  • 對基於 Webhook 的平臺（如 Slack、WhatsApp），請確保你的服務器可公開訪問

允許列表混淆——誰可以與機器人對話？​

原因： 授權模式決定了誰可獲得訪問權限。

解決方案：

模式工作方式
允許列表僅配置中列出的用戶 ID 可以交互
私信配對第一個在私信中發送消息的用戶將獲得獨佔訪問權
公開任何人都可交互（不推薦用於生產環境）

在 ~/.hermes/config.yaml 中對應網關設置下進行配置。詳見 消息通信文檔。

網關無法啟動​

原因： 缺少依賴項、端口衝突或令牌配置錯誤。

解決方案：

# 安裝消息依賴項
pip install "hermes-agent[telegram]"   # 或 [discord]、[slack]、[whatsapp]

# 檢查端口衝突
lsof -i :8080

# 驗證配置
hermes config show

macOS：Node.js / ffmpeg / 其他工具在網關中找不到​

原因： launchd 服務繼承的 PATH 極其精簡（/usr/bin:/bin:/usr/sbin:/sbin），不包含 Homebrew、nvm、cargo 或其他用戶安裝的工具目錄。這通常會導致 WhatsApp 橋接失敗（node not found）或語音轉錄失敗（ffmpeg not found）。

解決方案： 網關在運行 hermes gateway install 時會捕獲你的 shell PATH。如果你在設置網關後安裝了新工具，請重新運行安裝以捕獲更新後的 PATH：

hermes gateway install    # 重新快照您當前的 PATH
hermes gateway start      # 檢測更新的 plist 並重新加載

您可以驗證 plist 文件是否具有正確的 PATH：

/usr/libexec/PlistBuddy -c "Print :EnvironmentVariables:PATH" \
  ~/Library/LaunchAgents/ai.hermes.gateway.plist

性能問題​

響應緩慢​

原因： 模型過大、API 服務器距離較遠，或系統提示中包含大量工具導致負載過重。

解決方案：

  • 嘗試使用更快或更小的模型：hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct
  • 減少激活的工具集：hermes chat -t "terminal"
  • 檢查您與服務提供商之間的網絡延遲
  • 對於本地模型，請確保 GPU VRAM 足夠

Token 使用量過高​

原因： 對話過長、系統提示過於冗長，或大量工具調用累積了過多上下文。

解決方案：

# 壓縮對話以減少tokens
/compress

# 檢查 session token 的使用情況
/usage
提示

在長時間會話中定期使用 /compress。它會總結對話歷史，顯著降低 Token 使用量，同時保留上下文信息。

會話過長​

原因： 長時間對話累積了大量消息和工具輸出，接近上下文限制。

解決方案：

# 壓縮當前session（保留密鑰context）
/compress

# 參考舊的開始一個新的 session
hermes chat

# 如果需要，稍後恢復特定的 session
hermes chat --continue

MCP 問題​

MCP 服務器無法連接​

原因： 服務器二進制文件未找到、命令路徑錯誤，或缺少運行時環境。

解決方案：

# 確保安裝了 MCP 依賴項（已包含在標準安裝中）
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

# 對於基於 npm 的服務器，確保 Node.js 可用
node --version
npx --version

# 手動測試服務器
npx -y @modelcontextprotocol/server-filesystem /tmp

驗證您的 ~/.hermes/config.yaml 中的 MCP 配置：

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]

MCP 服務器未顯示工具​

原因： 服務器已啟動但工具發現失敗，工具被配置過濾掉，或服務器不支持您期望的 MCP 能力。

解決方案：

  • 檢查網關/代理日誌中是否存在 MCP 連接錯誤
  • 確保服務器能夠響應 tools/list RPC 方法
  • 檢查該服務器下的任何 tools.include、tools.exclude、tools.resources、tools.prompts 或 enabled 設置
  • 請注意，資源/提示工具僅在會話實際支持相應能力時才會註冊
  • 修改配置後使用 /reload-mcp
# 驗證 MCP 服務器是否已配置
hermes config show | grep -A 12 mcp_servers

# 配置更改後重新啟動 Hermes 或重新加載 MCP
hermes chat

另請參閱：

MCP 超時錯誤​

原因： MCP 服務器響應時間過長，或在執行過程中崩潰。

解決方案：

  • 如果支持，可在 MCP 服務器配置中增加超時時間
  • 檢查 MCP 服務器進程是否仍在運行
  • 對於遠程 HTTP MCP 服務器，檢查網絡連接
注意

如果 MCP 服務器在請求過程中崩潰，Hermes 將報告超時。請檢查服務器自身的日誌（而不僅僅是 Hermes 日誌），以診斷根本原因。

配置文件（Profiles）​

配置文件與直接設置 HERMES_HOME 有何不同？​

配置文件是在 HERMES_HOME 之上的一個管理層。您當然可以手動在每次命令前設置 HERMES_HOME=/some/path，但配置文件會為您處理所有底層工作：創建目錄結構、生成 shell 別名（hermes-work）、在 ~/.hermes/active_profile 中跟蹤當前激活的配置文件，並自動在所有配置文件之間同步技能更新。它們還與 Tab 補全集成，您無需記住路徑。

兩個配置文件可以共享同一個機器人令牌嗎？​

不可以。每個消息平臺（Telegram、Discord 等）都需要對機器人令牌的獨佔訪問權限。如果兩個配置文件同時嘗試使用相同的令牌，第二個網關將無法連接。請為每個配置文件創建獨立的機器人——對於 Telegram，可聯繫 @BotFather 創建額外的機器人。

配置文件之間是否共享記憶或會話？​

不共享。每個配置文件都有自己的記憶存儲、會話數據庫和技能目錄。它們完全隔離。如果您希望創建一個帶有現有記憶和會話的新配置文件，可以使用 hermes profile create newname --clone-all 從當前配置文件複製所有內容。

運行 hermes update 會發生什麼？​

hermes update 會拉取最新代碼並重新安裝依賴項 一次（不是每個配置文件都執行一次）。然後它會自動將更新的技能同步到所有配置文件。您只需運行一次 hermes update —— 它將覆蓋機器上所有配置文件。

我可以將配置文件移動到另一臺機器上嗎？​

可以。將配置文件導出為可移植的歸檔文件，並在另一臺機器上導入：

# 在源機器上
hermes profile export work ./work-backup.tar.gz

# 將文件複製到目標機器，然後：
hermes profile import ./work-backup.tar.gz work

導入的配置文件將包含導出時的所有配置、記憶、會話和技能。如果新機器的設置不同，您可能需要更新路徑或重新認證與服務提供商的連接。

我可以運行多少個配置文件？​

沒有硬性限制。每個配置文件只是 ~/.hermes/profiles/ 下的一個目錄。實際限制取決於您的磁盤空間以及系統能處理的併發網關數量（每個網關是一個輕量級 Python 進程）。運行數十個配置文件是完全可行的；每個空閒配置文件不消耗任何資源。

工作流與模式​

為不同任務使用不同模型（多模型工作流）​

場景： 您日常使用 GPT-5.4，但 Gemini 或 Grok 在撰寫社交媒體內容方面表現更佳。每次手動切換模型非常繁瑣。

解決方案：委託配置（Delegation config）。Hermes 可以自動將子 Agent 路由到不同的模型。您可以在 ~/.hermes/config.yaml 中進行設置：

delegation:
  model: "google/gemini-3-flash-preview"   # 子代理使用此 model
  provider: "openrouter"                    # provider 用於子代理

現在當你告訴 Hermes “幫我寫一篇關於 X 的 Twitter 帖子”時，它會啟動一個 delegate_task 子 Agent，該子 Agent 在 Gemini 上運行，而不是在你的主模型上。你的主要對話仍保留在 GPT-5.4 上。

你也可以在提示中明確表達：“將任務委託給撰寫關於我們產品發佈社交媒體帖子。使用你的子 Agent 來實際撰寫。” 該 Agent 會使用 delegate_task，它會自動加載委託配置。

對於無需委託的一次性模型切換，可在 CLI 中使用 /model 命令：

/model google/gemini-3-flash-preview    # session 的開關
# ...寫下您的內容...
/model openai/gpt-5.4                   # 切換回來

有關委託機制的更多詳情，請參閱 子 Agent 委託。

在一個 WhatsApp 號碼上運行多個 Agent（按聊天綁定）​

場景： 在 OpenClaw 中，你可以將多個獨立的 Agent 綁定到特定的 WhatsApp 聊天——一個用於家庭購物清單群組，另一個用於你的私人聊天。Hermes 能否做到這一點？

當前限制： Hermes 的每個配置文件都需要獨立的 WhatsApp 號碼/會話。你無法將多個配置文件綁定到同一 WhatsApp 號碼的不同聊天——WhatsApp 橋接器（Baileys）每個號碼僅支持一個已認證的會話。

替代方案：

  1. 使用單個配置文件配合人格切換。 創建不同的 AGENTS.md 上下文文件，或使用 /personality 命令來按聊天切換行為。Agent 會識別自己所在的聊天並相應調整。

  2. 使用定時任務（cron job）處理專項任務。 例如，為購物清單追蹤器設置一個 cron 任務，監控特定聊天並管理清單——無需額外的 Agent。

  3. 使用獨立號碼。 如果你需要真正獨立的 Agent，可為每個配置文件配對一個獨立的 WhatsApp 號碼。Google Voice 等虛擬號碼服務可滿足此需求。

  4. 改用 Telegram 或 Discord。 這些平臺更自然地支持按聊天綁定——每個 Telegram 群組或 Discord 頻道都有獨立會話，你可以在同一賬戶上運行多個機器人令牌（每個配置文件一個）。

更多詳情請參閱 配置文件 和 WhatsApp 設置。

控制 Telegram 中顯示的內容（隱藏日誌和推理過程）​

場景： 你在 Telegram 中看到網關執行日誌、Hermes 的推理過程以及工具調用詳情，而不僅僅是最終輸出。

解決方案： config.yaml 中的 display.tool_progress 設置控制顯示多少工具活動：

display:
  tool_progress: "off"   # 選項：關閉、新建、全部、詳細
  • off — 僅顯示最終響應。不顯示工具調用、推理過程或日誌。
  • new — 在工具調用發生時顯示新調用（簡短的一行）。
  • all — 顯示所有工具活動，包括結果。
  • verbose — 完整細節，包括工具參數和輸出。

對於消息平臺，通常建議使用 off 或 new。修改 config.yaml 後，需重啟網關以使更改生效。

你也可以通過 /verbose 命令（若已啟用）在會話級別切換此設置：

display:
  tool_progress_command: true   # 在網關中啟用“0”

在 Telegram 上管理技能（斜槓命令數量限制）​

場景： Telegram 的斜槓命令數量限制為 100 個，而你的技能數量已接近或超過該限制。你希望在 Telegram 上禁用不需要的技能，但 hermes skills config 的設置似乎未生效。

解決方案： 使用 hermes skills config 按平臺禁用技能。這會寫入 config.yaml：

skills:
  disabled: []                    # 全局禁用 skills
  platform_disabled:
    telegram: [skill-a, skill-b]  # 僅在 telegram 上禁用

更改後，必須重啟網關（運行 hermes gateway restart 或終止並重新啟動）。Telegram 機器人的命令菜單會在啟動時重建。

提示

在 Telegram 菜單中，描述過長的技能會被截斷為 40 個字符，以符合負載大小限制。如果技能未顯示，可能並非因為達到 100 條命令的限制，而是總負載大小超限——禁用未使用的技能可同時解決此問題。

共享線程會話（多人共用一個對話）​

場景： 你在 Telegram 或 Discord 的一個線程中，多人提及機器人。你希望所有提及都屬於同一個共享對話，而不是為每個用戶創建獨立會話。

當前行為： 在大多數平臺上，Hermes 會根據用戶 ID 鍵控會話，因此每個人都有自己的對話上下文。這是出於隱私和上下文隔離的設計考慮。

替代方案：

  1. 使用 Slack。 Slack 會話按線程鍵控，而非用戶。同一線程中的多個用戶共享一個對話——這正是你所描述的行為。這是最自然的解決方案。

  2. 使用群聊並指定單一用戶作為“操作員”。 由一人負責轉達問題，會話保持統一。其他人可閱讀並參與。

  3. 使用 Discord 頻道。 Discord 會話按頻道鍵控，因此同一頻道中的所有用戶共享上下文。為共享對話創建專用頻道即可。

將 Hermes 導出到另一臺機器​

場景： 你在一臺機器上已構建了技能、定時任務和記憶數據，現在希望將所有內容遷移到新的專用 Linux 服務器上。

解決方案：

  1. 在新機器上安裝 Hermes Agent：

    curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

  2. 將整個 ~/.hermes/ 目錄複製到新機器上，但不包括 hermes-agent 子目錄（該目錄是代碼倉庫——新安裝會自帶自己的版本）：

    # On the source machine
    rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/

    或使用配置文件導出/導入功能：

    # On source machine
    hermes profile export default ./hermes-backup.tar.gz

    # On target machine
    hermes profile import ./hermes-backup.tar.gz default

  3. 在新機器上運行 hermes setup，以驗證 API 密鑰和提供者配置是否正常工作。重新認證任何消息平臺（尤其是 WhatsApp，它使用二維碼配對）。

~/.hermes/ 目錄包含所有內容：config.yaml、.env、SOUL.md、memories/、skills/、state.db（會話數據）、cron/ 以及任何自定義插件。代碼本身位於 ~/.hermes/hermes-agent/，並會進行全新安裝。

安裝後重新加載 shell 時出現權限被拒絕​

場景： 運行 Hermes 安裝程序後，執行 source ~/.zshrc 時出現權限被拒絕錯誤。

原因： 這通常是因為 ~/.zshrc（或 ~/.bashrc）文件權限設置不正確，或者安裝程序無法乾淨地寫入該文件。這不是 Hermes 特有的問題——而是 shell 配置文件權限問題。

解決方案：

# 檢查權限
ls -la ~/.zshrc

# 如果需要，請修復（應為 -rw-r--r-- 或 644）
chmod 644 ~/.zshrc

# 然後重新加載
source ~/.zshrc

# 或者只是打開一個新的終端窗口 - 它會自動獲取 PATH 更改

如果安裝程序已添加 PATH 行但權限錯誤，可以手動添加：

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

首次運行 Agent 時出現 400 錯誤​

場景： 設置過程順利完成，但首次聊天嘗試失敗，返回 HTTP 400 錯誤。

原因： 通常是模型名稱不匹配——配置的模型在你的提供者處不存在，或 API 密鑰無權訪問該模型。

解決方案：

# 檢查model和provider的配置
hermes config show | head -20

# 重新運行model選擇
hermes model

# 或者使用已知良好的 model 進行測試
hermes chat -q "hello" --model anthropic/claude-sonnet-4.6

如果使用 OpenRouter，請確保你的 API 密鑰有餘額。OpenRouter 返回 400 錯誤通常意味著該模型需要付費計劃，或模型 ID 存在拼寫錯誤。

仍然遇到問題？​

如果您的問題未在此處涵蓋：

  1. 搜索現有問題： GitHub Issues
  2. 向社區提問： Nous Research Discord
  3. 提交錯誤報告： 請附上您的操作系統信息、Python 版本（python3 --version）、Hermes 版本（hermes --version）以及完整的錯誤信息