Hermes開源實戰指南：Nous Research開源AI智能體完全手冊（上、下冊）

第一部分 入門與基礎
第 1 章 認識 Hermes Agent ············································································.002
1.1 Hermes Agent 是什麼：起源與設計哲學 ··················································.002
1.2 核心架構與技術棧概覽 ·······································································.005
1.3 與其他 AI 智能體的對比分析 ·······························································.014
1.4 Hermes Agent 的核心優勢與適用場景 ·····················································.020
1.5 快速上手：體驗 Hermes Agent ······························································.027
第 2 章 安裝與環境配置 ················································································.033
2.1 Linux/macOS 安裝詳解 ·······································································.033
2.2 Windows WSL2 安裝指南 ····································································.041
2.3 Android Termux 安裝與配置 ·································································.044
2.4 Hermes 更新與卸載 ············································································.049
2.5 Hermes 看板：任務管理與自動化調度 ····················································.056
第 3 章 核心概念深度解析 ·············································································.061
3.1 配置文件詳解：config.yaml ·································································.061
3.2 LLM 提供商配置 ··········································································.068
3.3 模型選擇策略：按任務選模型 ······························································.073
3.3.1 模型選擇的三維框架 ··································································.073
3.3.2 七類任務的參考模型選型 ····························································.074
3.3.3 如何快速切換模型 ·····································································.075
3.3.4 雙模型策略（推薦日常使用） ·····················································.075
3.3.5 成本優化策略 ···········································································.076
3.3.6 如何自己評估模型效果？ ····························································.076
3.3.7 註意事項 ·················································································.077
3.3.8 小結 ·······················································································.077
3.4 API 密鑰管理與安全最佳實踐 ······························································.077
3.4.1 三道防線，能擋住絕大多數常見泄露 ············································.078
3.4.2 第一步：基礎安全—把密鑰放在受保護的文件裏 ··························.078
3.4.3 第二步：Git 防泄露—最後的防線 ··············································.079
3.4.4 進階：專用密鑰管理工具（可選） ···············································.080
3.4.5 密鑰輪換（按企業策略定期執行，常見 90 天/3–6 個月） ·················.080
3.4.6 泄露應急響應 ···········································································.080
3.4.7 安全審計腳本 ···········································································.081
3.4.8 關鍵原則 ·················································································.082
3.4.9 小結 ·······················································································.082
3.5 配置管理通用實踐 ·············································································.082
3.5.1 為什麼需要多環境思維？ ····························································.082
3.5.2 核心原則 ·················································································.083
3.5.3 用環境變量區分環境 ··································································.083
3.5.4 用 direnv 按目錄自動加載（僅限開發環境，不建議自動加載生產密鑰） ····.084
3.5.5 配置作為代碼（Config as Code）
—保留變量引用，不要把明文 key 寫入 config.yaml ····················.085
目錄 XIII
3.5.6 容器部署場景 ···········································································.085
3.5.7 配置變更的審批與回滾 ·······························································.086
3.5.8 註意事項 ·················································································.086
3.5.9 小結 ·······················································································.086
第二部分 日常使用與配置
第 4 章 命令行界面（CLI）完全指南 ··························································.089
4.1 TUI 功能與界面 ················································································.089
4.1.1 啟動界面：你的第一印象 ····························································.089
4.1.2 頂部狀態欄：儀表盤而非裝飾 ·····················································.090
4.1.3 對話歷史區域：不只是聊天記錄 ··················································.090
4.1.4 輸入區域：日常操作的“主戰場” ···············································.092
4.1.5 流式輸出：實時看到 AI 在“打字” ··············································.092
4.1.6 顯示配置：按你的口味調整·························································.093
4.1.7 終端兼容性：你的終端行不行 ·····················································.093
4.1.8 最佳終端設置 ···········································································.093
4.1.9 小結 ·······················································································.094
4.2 斜杠命令 ····················································································.094
4.2.1 會話控制命令 ···········································································.095
4.2.2 配置管理命令 ···········································································.098
4.2.3 工具和技能管理命令 ··································································.100
4.2.4 信息與幫助命令 ········································································.102
4.2.5 小結：命令的“三三制” ····························································.103
4.3 會話管理 ·························································································.104
4.3.1 會話存儲：你的對話去哪兒了 ·····················································.104
4.3.2 啟動與恢復：從“從哪開始”到“接著聊” ···································.105
4.3.3 會話內管理（斜杠命令速查） ·····················································.105
4.3.4 CLI 子命令：批量管理會話 ·························································.105
4.3.5 備份與恢復：別讓你的對話資產丟失 ············································.107
4.3.6 全文搜索：三周前說的那句話在哪？ ············································.108
4.3.7 會話生命周期與最佳實踐 ····························································.108
4.3.8 註意事項 ·················································································.109
4.3.9 小結 ·······················································································.110
4.4 快捷鍵與操作技巧 ·············································································.110
4.4.1 必須記住的快捷鍵 ·····································································.110
4.4.2 命令行啟動技巧：更聰明的入口 ···················································.111
4.4.3 提示詞技巧（讓一次問答更值錢） ···············································.112
4.4.4 Shell 別名：把復雜命令變成習慣 ··················································.113
4.4.5 批處理：讓 Hermes 替你批量幹活 ·················································.115
4.4.6 提示詞模板管理 ········································································.116
4.4.7 學習路線建議（按需推進，不是 KPI） ··········································.117
4.4.8 註意事項 ·················································································.117
4.4.9 小結 ·······················································································.117
4.5 Personality 與 SOUL.md ·······························································.118
4.5.1 快速入門：從內置預設中選一個 ··················································.118
4.5.2 深度定制：SOUL.md 定義 AI 的“靈魂” ·······································.119
4.5.3 專業場景定制：三個實戰模板 ·····················································.120
4.5.4 自定義個性預設 ········································································.121
4.5.5 會話中隨時切換 ········································································.122
4.5.6 Personality + Memory：協同工作 ··················································.122
4.5.7 管理多個 SOUL.md ···································································.123
4.5.8 註意事項＆最佳實踐 ··································································.123
4.5.9 小結 ·······················································································.123
第 5 章 模型配置與提供商管理 ·······································································.124
5.1 記憶架構 ·························································································.124
5.1.1 記憶系統：兩個文件，一個目標 ··················································.124
5.1.2 MEMORY.md：智能體的技術筆記 ················································.125
5.1.3 USER.md：你的“使用說明書” ··················································.127
5.1.4 雙文件協同：一個實際例子·························································.128
5.1.5 記憶文件管理 ···········································································.128
5.1.6 小結 ·······················································································.129
5.2 記憶工具操作 ···················································································.130
5.2.1 三種操作的核心理念 ··································································.130
5.2.2 add：追加新知識（最常用） ·······················································.130
5.2.3 replace：精準替換（修正過時信息） ·············································.131
5.2.4 remove：清理過期內容（維護記憶新鮮度） ···································.132
5.2.5 完整工作流：一個實際案例·························································.132
5.2.6 操作失敗怎麼辦 ········································································.133
5.2.7 自動化更新策略（建議性，以配置為準） ······································.133
5.2.8 容量管理速查 ···········································································.134
5.2.9 小結 ·······················································································.134
5.3 會話搜索 ·························································································.134
5.3.1 怎麼用：在對話中自然提問·························································.134
5.3.2 FTS5 是什麼（你只需要知道這麼多） ···········································.135
5.3.3 搜索語法（給需要精確搜索的高級用戶） ······································.135
5.3.4 會話摘要：快速了解搜索結果 ·····················································.135
5.3.5 跨會話召回的工作流程 ·······························································.136
5.3.6 搜索技巧：搜得更準 ··································································.137
5.3.7 會話索引的維護 ········································································.137
5.3.8 隱私與安全 ··············································································.137
5.3.9 小結 ·······················································································.138
5.4 外部記憶提供商 ···········································································.138
5.4.1 快速決策：我該選哪個？ ····························································.139
5.4.2 體系結構：插件式設計（以源碼為準） ·········································.139
5.4.3 快速配置 ·················································································.139
5.4.4 幾類 provider 的代表性對比 ·························································.140
5.4.5 跨設備同步：能力與風險並存 ·····················································.141
5.4.6 安全最佳實踐 ···········································································.141
5.4.7 小結 ·······················································································.142
5.5 記憶最佳實踐 ···················································································.142
5.5.1 五大核心原則 ···········································································.142
5.5.2 六大常見誤區 ···········································································.145
5.5.3 記憶系統健康度評估 ··································································.145
5.5.4 記憶備份策略 ···········································································.146
5.5.5 小結 ·······················································································.147
第 6 章 工具系統深度配置 ···································································.148
6.1 技能系統原理 ··············································································.148
6.1.1 核心設計：三層漸進式披露·························································.148
6.1.2 四種激活方式 ···········································································.149
6.1.3 技能的生命周期 ········································································.150
6.1.4 技能 vs 記憶：兩個系統的分工 ····················································.150
6.1.5 技能隔離與安全（邊界與註意事項） ············································.151
6.1.6 小結 ·······················································································.151
6.2 內置工具集與技能目錄 ·······································································.151
6.2.1 第一部分：內置工具集（“肌肉”） ···············································.152
6.2.2 第二部分：內置技能（“知識”） ··················································.153
6.2.3 技能管理命令速查 ·····································································.155
6.2.4 小結 ·······················································································.155
6.3 從 Skills Hub 安裝技能 ········································································.155
6.3.1 第一步：搜索和瀏覽 ··································································.156
6.3.2 第二步：評估技能質量和安全性 ··················································.156
6.3.3 第三步：安裝與配置 ··································································.157
6.3.4 企業部署：私有 Hub 與白名單 ·····················································.158
6.3.5 故障排除 ·················································································.160
6.3.6 小結 ·······················································································.160
6.4 創建自定義技能 ················································································.160
6.4.1 技能目錄結構 ···········································································.160
6.4.2 SKILL.md 的基本形態 ································································.161
6.4.3 關鍵字段詳解 ···········································································.161
6.4.4 條件顯示：技能自動隱藏/顯示 ·····················································.162
6.4.5 環境變量聲明 ···········································································.162
6.4.6 技能配置項 ··············································································.163
6.4.7 正文寫作：給 AI 看的操作手冊 ····················································.163
6.4.8 實踐建議 ·················································································.164
6.4.9 小結 ·······················································································.164
6.5 AI 自動創建技能 ···············································································.164
6.5.1 一個示例場景 ···········································································.165
6.5.2 skill_manage 工具：6 種動作························································.165
6.5.3 Agent 什麼情況下可能自動創建技能（產品設想） ···························.166
6.5.4 自動創建的技能長什麼樣 ····························································.167
6.5.5 為什麼這類技能能長期復用·························································.167
6.5.6 實踐建議 ·················································································.167
6.5.7 一個更貼近工程實踐的理解框架 ··················································.168
6.5.8 小結 ·······················································································.168
第 7 章 記憶與個性化 ··········································································.169
7.1 內置工具全景圖：Hermes 的“瑞士軍刀架” ···········································.169
7.1.1 從一個真實場景開始 ··································································.169
7.1.2 Toolset 是什麼 ·········································································.169
7.1.3 Core Toolsets（核心工具集） ·······················································.169
7.1.4 Composite Toolsets（組合工具集） ················································.170
7.1.5 其他可用 Toolset（插件/場景專屬） ··············································.171
7.1.6 從用戶視角看：最重要的幾組能力 ···············································.171
7.1.7 Platform Toolset 與運行場景 ·························································.172
7.1.8 動態工具：MCP 與插件 ·····························································.172
7.1.9 常用命令入口 ···········································································.173
7.1.10 工具與安全邊界 ······································································.173
7.1.11 如何理解 Hermes 的工具體系 ·····················································.174
7.1.12 小結 ·····················································································.174
7.2 終端工具實戰：命令執行與系統操作 ·····················································.174
7.2.1 terminal：執行命令 ····································································.175
7.2.2 process：後臺進程管理 ·······························································.175
7.2.3 execute_code：把工具串成程序 ····················································.175
7.2.4 終端後端決定命令在哪裏執行 ·····················································.176
7.2.5 與終端能力最相關的幾項配置 ·····················································.177
7.2.6 審批機制：終端工具的安全邊界 ··················································.177
7.2.7 關於“命令以誰的權限執行” ·····················································.178
7.2.8 為什麼容器/雲後端很重要 ···························································.178
7.2.9 終端工具的典型工作流：以“查日誌修 Bug”為例 ···························.179
7.2.10 與文件、技能、消息系統的聯動 ·················································.179
7.2.11 恢復機制（適用於生產環境） ····················································.180
7.2.12 實戰建議 ···············································································.180
7.2.13 小結 ·····················································································.180
7.3 Web 工具集：搜索、提取與瀏覽器自動化 ···············································.181
7.3.1 一個場景錨定認知 ·····································································.181
7.3.2 兩層架構 ·················································································.181
7.3.3 web：搜索與內容提取 ································································.181
7.3.4 browser：真正與網頁交互 ···························································.182
7.3.5 瀏覽器後端選型速查 ··································································.183
7.3.6 本地瀏覽器與雲瀏覽器如何理解 ··················································.183
7.3.7 /browser connect 與 CDP ·························································.183
7.3.8 配置裏的關鍵點 ········································································.184
7.3.9 web 與 browser 怎麼配合··························································.185
7.3.10 和 execute_code 的關系 ·························································.185
7.3.11 使用建議 ···············································································.186
7.3.12 小結 ·····················································································.186
7.4 文件與代碼工具：文件操作與程序化執行 ···············································.187
7.4.1 從一個痛點開始 ········································································.187
7.4.2 能力概覽 ·················································································.187
7.4.3 file toolset：四個核心能力 ·························································.187
7.4.4 execute_code：程序化工具調用 ··················································.188
7.4.5 什麼時候該用 execute_code ······················································.189
7.4.6 執行模式 ·················································································.189
7.4.7 資源限制與安全邊界 ··································································.190
7.4.8 技能與環境變量透傳 ··································································.191
7.4.9 file 與 execute_code 的典型配合方式 ·······································.191
7.4.10 與單純終端命令的區別 ·····························································.192
7.4.11 使用建議 ···············································································.192
7.4.12 小結 ·····················································································.192
7.5 終端後端選擇：本地·容器·遠程·雲沙箱 ············································.193
7.5.1 後端清單 ·················································································.193
7.5.2 統一配置 ·················································································.193
7.5.3 後端詳解 ·················································································.194
7.5.4 持久化邊界（重要） ··································································.197
7.5.5 安全配置配合 ···········································································.197
7.5.6 選擇速查 ·················································································.198
7.5.7 小結 ·······················································································.198
第三部分 技能生態
第 8 章 技能系統詳解 ···················································································.200
8.1 消息網關架構與工作原理 ····································································.200
8.1.1 先跑通一個場景 ········································································.200
8.1.2 網關到底是什麼 ········································································.200
8.1.3 架構設計哲學 ···········································································.201
8.1.4 核心組件詳解 ···········································································.201
8.1.5 網關生命周期管理 ·····································································.202
8.1.6 消息處理完整流程 ·····································································.203
8.1.7 配置與文件位置 ········································································.204
8.1.8 安全與鑒權（默認拒絕） ····························································.204
8.1.9 監控與告警 ··············································································.205
8.1.10 斜杠命令系統 ·········································································.205
8.1.11 最佳實踐 ···············································································.205
8.1.12 小結 ·····················································································.206
8.2 Telegram Bot 集成完全指南 ··································································.206
8.2.1 前置準備 ·················································································.206
8.2.2 Hermes Telegram 配置 ································································.207
8.2.3 訪問控制配置 ···········································································.208
8.2.4 群組使用的關鍵點：Privacy Mode（默認建議保持 ON） ···················.208
8.2.5 Webhook 模式（適合“會休眠的雲平臺”） ·····································.209
8.2.6 Proxy 支持（國內網絡環境常用） ·················································.209
8.2.7 Home Channel（Cron 輸出投遞位置） ············································.209
8.2.8 群聊觸發策略（建議：默認要求 mention） ·····································.210
8.2.9 Docker 終端與文件發送（容易踩坑） ············································.210
8.2.10 消息限制（企業必讀） ·····························································.211
8.2.11 安全最佳實踐 ·········································································.211
8.2.12 故障排查 ···············································································.211
8.2.13 小結 ·····················································································.212
8.3 Discord Bot 配置與高級功能 ································································.212
8.3.1 創建應用與邀請入群（Discord 側） ··············································.212
8.3.2 配置 Hermes（最小閉環） ··························································.213
8.3.3 行為與會話模型（官方默認） ·····················································.213
8.3.4 常用開關 ·················································································.214
8.3.5 故障排查（系統化檢查） ····························································.215
8.3.6 小結 ·······················································································.215
8.4 國內平臺集成：飛書、企業微信與微信 ··················································.216
8.4.1 飛書（Feishu / Lark） ·································································.217
8.4.2 企業微信（WeCom） ·································································.220
8.4.3 微信（WeChat） ·······································································.222
8.4.4 企業數據安全註意事項 ·······························································.224
8.4.5 小結 ·······················································································.224
8.5 多平臺統一管理與消息路由策略 ···························································.225
8.5.1 一個真實的“多平臺時刻”·························································.225
8.5.2 讀者最需要的不是“路由規則” ··················································.225
8.5.3 多平臺運行模式（兩種最常見） ··················································.226
8.5.4 配置分層：什麼時候編輯哪個文件 ···············································.226
8.5.5 會話隔離與用戶授權 ··································································.227
8.5.6 主動投遞：用 Cron 的 deliver，而不是“偽 API 推送” ·····················.228
8.5.7 統一運維：服務與診斷 ·······························································.229
8.5.8 可靠性與邊界說明（與 8.1 生命周期規則合並） ······························.230
8.5.9 監控與告警配置 ········································································.230
8.5.10 最佳實踐總結（六條核心原則） ·················································.231
8.5.11 小結 ·····················································································.231
第 9 章 Skills Hub 生態 ·················································································.232
9.1 MCP 協議概述 ··················································································.232
9.1.1 為什麼需要 MCP·······································································.232
9.1.2 Hermes 中的 MCP 架構 ·······························································.232
9.1.3 兩種傳輸模式 ···········································································.233
9.1.4 連接與錯誤處理 ········································································.234
9.1.5 常用 CLI 命令 ··········································································.234
9.1.6 配置字段完整參考 ·····································································.235
9.2 配置 MCP 服務器 ··············································································.236
9.2.1 配置結構 ·················································································.236
9.2.2 本地 STDIO 服務器配置 ·····························································.236
9.2.3 遠程 HTTP 服務器配置 ·······························································.237
9.2.4 工具過濾配置 ···········································································.238
9.2.5 啟用/禁用服務器 ·······································································.239
9.2.6 環境變量註入 ···········································································.240
9.2.7 OAuth 認證配置 ········································································.240
9.2.8 使用 hermes mcp configure 進行交互式配置 ·······························.241
9.3 使用 MCP 工具 ·················································································.241
9.3.1 自動工具發現 ···········································································.241
9.3.2 查看已配置的服務器 ··································································.241
9.3.3 測試服務器連接 ········································································.242
9.3.4 在對話中使用 MCP 工具 ·····························································.242
9.3.5 工具調用參數 ···········································································.243
9.3.6 通過 hermes mcp ＜name＞ call 手動調用工具 ·······························.244
9.3.7 常見使用場景 ···········································································.244
9.4 編寫自定義 MCP 服務器 ·····································································.245
9.4.1 MCP 服務器開發概述 ································································.246
9.4.2 使用 MCP Python SDK 開發 ·························································.246
9.4.3 定義工具 ·················································································.247
9.4.4 添加資源（Resources） ······························································.248
9.4.5 添加提示模板（Prompts） ···························································.249
9.4.6 錯誤處理與 SSRF 防護 ······························································.250
9.4.7 使用 FastMCP 快速開發 ······························································.251
9.4.8 調試自定義服務器 ·····································································.252
9.5 MCP 故障排除與安全 ·········································································.253
9.5.1 連接問題排查 ···········································································.254
9.5.2 常見錯誤信息 ···········································································.255
9.5.3 安全最佳實踐 ···········································································.255
9.5.4 OAuth 認證管理 ········································································.257
9.5.5 性能優化 ·················································································.257
9.5.6 更新 MCP 服務器（按依賴審查處理） ···········································.258
9.5.7 日誌與診斷 ··············································································.258
9.5.8 本章小結與安全優先級 ·······························································.259
第 10 章 技能開發實戰 ········································································.260
10.1 Cron 調度概述 ············································································.260
10.1.1 為什麼需要 Cron ·····································································.260
10.1.2 Cron 的工作原理 ·····································································.261
10.1.3 Cron CLI 命令 ·········································································.261
10.1.4 創建第一個 Cron 任務 ·······························································.262
10.1.5 Cron 表達式格式 ·····································································.262
10.1.6 交付目標（Deliver） ································································.263
10.2 Cron 任務類型 ·················································································.264
10.2.1 周期性重復任務 ······································································.264
10.2.2 單次執行 vs 有限次重復 ····························································.265
10.2.3 帶技能的任務 ·········································································.266
10.2.4 任務優先級與調度 ···································································.266
10.2.5 任務命名與 ID ········································································.267
10.3 Cron 任務管理與配置 ········································································.267
10.3.1 查看任務列表 ·········································································.268
10.3.2 暫停與恢復任務 ······································································.268
10.3.3 修改任務 ···············································································.268
10.3.4 立即執行任務 ·········································································.269
10.3.5 刪除