Hermes Agent 指令集完整指南
Hermes Agent 是一套可在本機、WSL、Linux 或伺服器環境中執行的 AI Agent 工具。它支援模型切換、工具呼叫、Skills、記憶、Session 管理、Telegram/Discord/WhatsApp Gateway、排程任務與多種開發輔助能力。
本文整理一份實用指令集，適合用來完成 Hermes Agent 的日常操作、重設、模型設定、Skills 管理、Telegram 綁定與故障排查。
一、進入 WSL 環境
如果 Hermes 安裝在 WSL 的 HermesAgent 發行版中，請先從 Windows PowerShell 進入 WSL：
wsl -d HermesAgent進入後可以確認目前使用者與系統資訊：
whoami
pwd
uname -a確認 Hermes 指令是否存在：
command -v hermes
hermes --version二、啟動與基本使用
啟動互動式聊天：
hermes使用單次問答模式：
hermes chat -q "你好，請確認目前模型設定"繼續上一個 Session：
hermes -c指定回復某個 Session：
hermes --resume SESSION_ID啟動時預載 Skills：
hermes -s codebase-inspection,systematic-debugging,test-driven-development在 Git 專案中使用隔離 worktree 執行：
hermes -w略過危險命令確認提示，僅建議在完全信任環境使用：
hermes --yolo三、查看狀態與診斷
查看 Hermes 狀態：
hermes status執行環境診斷：
hermes doctor輸出除錯摘要，方便貼給技術支援：
hermes dump查看版本資訊：
hermes version
hermes --version四、模型與 Provider 設定
進入互動式模型選擇器：
hermes model查看目前設定：
hermes config show查看設定檔位置：
hermes config path
hermes config env-path編輯主設定檔：
hermes config edit設定 Google Gemini Provider：
hermes config set model.provider gemini設定 Gemma 4 31B 模型：
hermes config set model.default gemma-4-31b-it設定 Google OpenAI-compatible endpoint：
hermes config set model.base_url https://generativelanguage.googleapis.com/v1beta/openai查看模型設定片段：
grep -A4 '^model:' ~/.hermes/config.yaml五、API Key 與環境變數
Hermes 的 API key 通常放在：
~/.hermes/.env編輯環境變數檔案：
nano ~/.hermes/.envGoogle AI Studio / Gemini 常用設定：
GOOGLE_API_KEY=你的_google_api_key
GEMINI_API_KEY=你的_google_api_key
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai設定檔權限建議改成只有目前使用者可讀寫：
chmod 600 ~/.hermes/.env測試 Google 模型清單是否可讀取：
set -a
. ~/.hermes/.env
set +a
curl -sS -H "x-goog-api-key: ${GOOGLE_API_KEY}" https://generativelanguage.googleapis.com/v1beta/models | head測試 Gemma 4 31B 是否能完成聊天請求：
set -a
. ~/.hermes/.env
set +a
curl -sS \
-H "Authorization: Bearer ${GOOGLE_API_KEY}" \
-H "Content-Type: application/json" \
https://generativelanguage.googleapis.com/v1beta/openai/chat/completions \
-d '{"model":"gemma-4-31b-it","messages":[{"role":"user","content":"Reply OK only."}],"max_tokens":8}'六、Skills 管理指令
Hermes Skills 是一種任務專長模組，可讓 Agent 在特定工作上套用專門流程，例如程式碼檢查、GitHub 工作流、研究論文、PDF、Notion、Google Workspace、MLOps 等。
列出已安裝 Skills：
hermes skills list互動式開關 Skills：
hermes skills config搜尋 Skills Hub：
hermes skills search github
hermes skills search pdf
hermes skills search research
hermes skills search notion預覽 Skill：
hermes skills inspect IDENTIFIER安裝 Skill：
hermes skills install IDENTIFIER強制安裝 Skill：
hermes skills install IDENTIFIER --force跳過確認安裝：
hermes skills install IDENTIFIER --yes檢查 Skills 更新：
hermes skills check更新 Skills：
hermes skills update移除 hub-installed Skill：
hermes skills uninstall IDENTIFIER常用開發組合：
hermes -s codebase-inspection,systematic-debugging,test-driven-development常用 GitHub 組合：
hermes -s github-auth,github-pr-workflow,github-code-review,github-issues常用研究組合：
hermes -s arxiv,research-paper-writing,llm-wiki七、工具 Toolsets 管理
Hermes 的 Tools 控制 Agent 能使用哪些能力，例如終端機、檔案、瀏覽器、記憶、TTS、排程、圖片分析等。
查看工具清單：
hermes tools list互動式設定工具：
hermes tools啟用常用工具：
hermes tools enable web browser terminal file memory skills todo啟用開發常用工具：
hermes tools enable terminal file code_execution browser skills memory session_search停用暫時不用或較敏感工具：
hermes tools disable rl moa homeassistant不同平台可以使用不同工具組。CLI、Telegram、Discord、WhatsApp 等平台可各自套用預設工具集或自訂工具。
八、Session 管理
列出歷史 Session：
hermes sessions list用互動式選單瀏覽 Session：
hermes sessions browse重新命名 Session：
hermes sessions rename SESSION_ID "新的標題"匯出 Session：
hermes sessions export SESSION_ID刪除 Session：
hermes sessions delete SESSION_ID清理舊 Session：
hermes sessions prune九、Memory 記憶功能
查看 Memory 設定：
hermes memoryHermes 預設可使用內建記憶系統。記憶相關資料通常位於：
~/.hermes/memories/查看記憶資料夾：
ls -la ~/.hermes/memories如果尚未產生 MEMORY.md 或 USER.md，通常代表 Agent 還沒有寫入記憶，這是正常狀態。
十、Telegram 綁定流程
Hermes 可透過 Gateway 連接 Telegram。建議先用前台模式測試，確認可用後再安裝背景服務。
1. 建立 Telegram Bot
在 Telegram 找 BotFather：
@BotFather建立新 bot：
/newbot完成後 BotFather 會給你一組 bot token，格式通常類似：
1234567890:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxx2. 取得自己的 Telegram User ID
在 Telegram 找：
@userinfobot傳任意訊息後，它會回覆你的 numeric user ID，例如：
1234567893. 使用 Hermes 互動式設定
hermes setup gateway設定時填入：
TELEGRAM_BOT_TOKEN：BotFather 給的 token
TELEGRAM_ALLOWED_USERS：你的 Telegram numeric user ID
TELEGRAM_HOME_CHANNEL：你的 Telegram numeric user ID4. 手動設定方式
也可以直接編輯 .env：
nano ~/.hermes/.env加入：
TELEGRAM_BOT_TOKEN=你的_bot_token
TELEGRAM_ALLOWED_USERS=你的_telegram_user_id
TELEGRAM_HOME_CHANNEL=你的_telegram_user_id安全提醒：TELEGRAM_ALLOWED_USERS 不建議留空，否則任何找到 bot 的人都有機會使用你的 Hermes 與 API 額度。
5. 前台測試 Gateway
hermes gateway run接著到 Telegram 對 bot 傳：
/start再測試：
你好，請告訴我目前使用的模型6. 安裝背景服務
確認前台模式可用後，再安裝背景服務：
hermes gateway install啟動背景服務：
hermes gateway start查看 Gateway 狀態：
hermes gateway status重啟 Gateway：
hermes gateway restart停止 Gateway：
hermes gateway stop移除 Gateway 背景服務：
hermes gateway uninstall十一、Pairing 使用者授權
Hermes 提供 pairing 管理，用於核准或撤銷使用者存取權。
查看 pending 與 approved users：
hermes pairing list核准 pairing code：
hermes pairing approve CODE撤銷使用者：
hermes pairing revoke USER_ID清除 pending codes：
hermes pairing clear-pending十二、Cron 排程任務
Hermes 支援 cron job，可以用來定時執行任務、產出報告或透過 Telegram 傳送通知。
查看 cron 指令：
hermes cron --help查看目前排程：
hermes cron list建立或管理排程時，可依照 CLI 提示輸入任務內容、執行時間與輸出平台。
十三、MCP 與外部工具整合
MCP 可讓 Hermes 與其他工具或服務互通。
查看 MCP 指令：
hermes mcp --help查看 MCP 伺服器設定：
hermes mcp list執行 Hermes 作為 MCP server：
hermes mcp serve十四、Plugins 管理
Hermes 支援 plugins，可安裝、更新、移除或列出外掛。
查看 plugin 指令：
hermes plugins --help列出 plugins：
hermes plugins list安裝 plugin：
hermes plugins install PLUGIN_IDENTIFIER更新 plugin：
hermes plugins update PLUGIN_IDENTIFIER移除 plugin：
hermes plugins remove PLUGIN_IDENTIFIER十五、Logs 與故障排查
查看最近 logs：
hermes logs即時追蹤 logs：
hermes logs -f查看錯誤 logs：
hermes logs errors查看最近一小時 logs：
hermes logs --since 1h如果 Telegram gateway 沒反應，建議依序檢查：
hermes gateway status
hermes logs -f
grep -E 'TELEGRAM_BOT_TOKEN|TELEGRAM_ALLOWED_USERS|TELEGRAM_HOME_CHANNEL' ~/.hermes/.env如果 Gemini API 回 403，常見原因包括 billing 未啟用、project 被拒絕存取、API key 權限限制錯誤、尚未接受 Gemini API 條款，或使用了不支援的 project。
如果模型清單可讀但生成失敗，可用 curl 測試：
set -a
. ~/.hermes/.env
set +a
curl -sS \
-H "Authorization: Bearer ${GOOGLE_API_KEY}" \
-H "Content-Type: application/json" \
https://generativelanguage.googleapis.com/v1beta/openai/chat/completions \
-d '{"model":"gemma-4-31b-it","messages":[{"role":"user","content":"Reply OK only."}],"max_tokens":8}'十六、備份與重設
備份 Hermes 設定與資料：
mkdir -p ~/hermes-backups
backup=~/hermes-backups/hermes-backup-$(date +%Y%m%d-%H%M%S).tar.gz
tar -czf "$backup" --ignore-failed-read ~/.hermes ~/.local/bin/hermes
ls -lh "$backup"停止 Gateway：
hermes gateway stop 2>/dev/null || true
systemctl --user disable --now hermes-gateway 2>/dev/null || true
pkill -f "hermes.*gateway" 2>/dev/null || true刪除 Hermes，重設前請務必確認已備份：
rm -f ~/.local/bin/hermes
rm -rf ~/.hermes重新安裝 Hermes：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash跳過互動式 setup 安裝：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup重新載入 shell：
source ~/.bashrc十七、更新與解除安裝
更新 Hermes：
hermes update檢查更新後狀態：
hermes version
hermes doctor解除安裝 Hermes：
hermes uninstall如果要手動刪除完整資料，請先備份再執行：
rm -f ~/.local/bin/hermes
rm -rf ~/.hermes十八、建議日常工作流
一般使用者可以每天這樣啟動：
wsl -d HermesAgent
hermes開發工作建議：
wsl -d HermesAgent
cd /path/to/project
hermes -s codebase-inspection,systematic-debugging,test-driven-developmentGitHub 工作建議：
hermes -s github-auth,github-pr-workflow,github-code-review,github-issues研究寫作建議：
hermes -s arxiv,research-paper-writing,llm-wikiTelegram 常駐建議：
hermes gateway status
hermes logs --since 1h十九、安全建議
API key 不應公開貼在聊天、文件或 GitHub repo 中。建議只存放於 ~/.hermes/.env，並將權限設為 600。
chmod 600 ~/.hermes/.env如果 API key 曾經公開，建議立即到 Google AI Studio 或 Google Cloud Console 重新產生 key，並撤銷舊 key。
Telegram Bot Token 也等同密碼，應避免公開。若曾曝光，請到 BotFather 重新產生 token。
二十、總結
Hermes Agent 的核心操作可以分為五類：模型設定、工具權限、Skills、Gateway、維護診斷。日常使用只需要掌握 hermes、hermes doctor、hermes config、hermes skills、hermes tools、hermes gateway 這幾組指令，就能完成大多數工作。
若要穩定長期使用，建議先確認模型 API 可正常生成，再設定 Telegram allowlist，最後才啟用 gateway 背景服務。這樣可以避免 API 額度外洩、bot 被陌生人使用，或服務背景化後不易排查問題。
