AI 程式設計教程中文版
官方教程中文版使用手冊

使用手冊

Hermes Agent 配置、工具系統、記憶、技能和訊息閘道器的中文使用入口，按問題定位能力邊界。

Hermes 的使用手冊可以先壓成五個入口：配置、工具、記憶、技能、訊息閘道器。它們分別回答「在哪裡配置」「能做什麼」「記住什麼」「如何複用流程」「從哪裡遠端接入」。

先給結論：排障從 provider（推理服務商）、session（會話）、配置開始，不從 Gateway（訊息閘道器）、cron（定時任務）、MCP（模型上下文協議）或 skill（技能）開始。基礎閉環穩定後，再逐層啟用工具、記憶、技能和遠端入口——能力越多，錯位越容易擴散。

官方手冊覆蓋什麼

Hermes 官方 llms.txt 把 user guide（使用指南）拆成約 30 個子頁，可以分成五大類（先看下面的總覽，每項細節會在後續文章展開，不必現在記）：

  • 基礎對話與配置：CLI（命令列）、TUI（終端 UI）、configuration（配置）、models（模型）、sessions（會話）、profiles（配置檔）、git worktrees（git 工作區）、Docker backend（Docker 後端）、security（安全）、checkpoints（檢查點）。
  • 能力擴充套件：tools（工具）、skills（技能）、memory（記憶）、context files（上下文檔案）、SOUL.md（人格檔案）、context references（上下文引用）、plugins（外掛）。
  • 自動化：cron（定時任務）、delegation（子代理委派）、kanban（看板）、goals（持久目標）、code execution（程式碼執行）、hooks（生命週期鉤子）、batch processing（批次處理）。
  • 多模態：voice（語音）、browser（瀏覽器）、vision（視覺）、image generation（影像生成）、TTS（語音合成）。
  • 訊息平臺：15+ 平臺的接入指南。

中文教程不把這些頁面平鋪成選單，而是按真實排障順序壓成 5 組：

組包含頁面先解決的問題
基礎執行CLI、TUI、configuration、models、sessions、profilesHermes 能不能穩定說話、恢復對話和切換模型
執行環境tools、toolsets、terminal backends、Docker、SSH、worktrees工具和命令在哪裡執行，是否可回復
長期上下文memory、memory providers、context files、SOUL.md、context references哪些事實進長期 prompt（系統提示），哪些按需引用
可複用能力skills、curator、plugins、MCP、ACP（代理上下文協議）、API server如何擴充套件能力且不汙染基礎環境
遠端與自動化messaging、cron、delegation、kanban、goals、hooks、batch遠端入口和後臺任務如何授權、審計和停止

這樣讀的好處是遇到問題能快速定位責任層，不會把「模型回答差」「命令執行錯」「訊息平臺沒授權」「memory 寫錯」混成一個含糊問題——四個問題的修復路徑完全不同。

五個入口

配置 Hermes Agent

讀懂 ~/.hermes/ 下 config.yaml、.env、auth.json、SOUL.md 各自管什麼，以及 provider 和 terminal backend 怎麼切換。

工具系統與終端後端

判斷要開哪些 toolsets（工具集），以及命令應該在本機、容器、遠端還是雲端執行——兩件事必須分開決策。

記憶系統

MEMORY.md、USER.md、凍結快照、session_search 和外部 memory provider 各自解決不同時間尺度的記憶問題——跨 session、跨任務、跨次對話。

技能系統

判斷什麼任務值得做成 skill，以及安裝外部 skill 前必須審查的金鑰與指令碼風險。

訊息閘道器與平臺接入

把 Hermes 接到 Telegram / Discord / Slack / Email 前，先理解 allowlist（允許名單）、DM pairing（私聊配對）和 chat session（聊天會話）。

按問題定位

不同症狀對應不同的「先去哪查」。把症狀和入口對上號，比從頭翻文件省時間得多：

flowchart LR
    S1["啟動失敗 / 模型不回<br/>key 不生效"] --> E1["📁 配置"]
    S2["命令不知道在哪跑<br/>工具許可權不清"] --> E2["🔧 工具系統"]
    S3["希望記住偏好<br/>專案規則 / 歷史任務"] --> E3["🧠 記憶系統"]
    S4["同一流程反覆做<br/>想做成可呼叫能力"] --> E4["📚 技能系統"]
    S5["接聊天平臺<br/>遠端入口 / 後臺"] --> E5["💬 訊息閘道器"]
    S6["MCP / ACP / API server<br/>provider routing"] --> CHK1{"基礎會話<br/>和 toolsets<br/>已穩定?"}
    S7["voice / browser<br/>vision / TTS"] --> CHK2{"當前工作流<br/>真需要媒體?"}
    CHK1 -- 否 --> E1
    CHK1 -- 是 --> EXT["✅ 擴充套件入口"]
    CHK2 -- 否 --> SKIP["⛔ 先不開"]
    CHK2 -- 是 --> EXT
    style EXT fill:#fde7c2,stroke:#d4761a
    style SKIP fill:#fde2e2,stroke:#c43d3d

文字版（圖載入失敗時看這個）：

  • 啟動失敗、模型不回、key 不生效 → 先查配置。
  • 命令不知道在哪裡執行、工具許可權不清楚 → 先查工具系統。
  • 希望 Hermes 記住偏好、專案規則或歷史任務 → 先查記憶系統。
  • 同一套流程反覆做，想變成可呼叫能力 → 先查技能系統。
  • 想把 Hermes 接到聊天平臺、遠端入口或後臺任務 → 先查訊息閘道器。
  • 需要 MCP、ACP、API server（API 伺服器）或 provider routing（推理服務商路由） → 先確認基礎會話和 toolsets 已經穩定。它們是擴充套件入口，不是排障入口——基礎不穩就開擴充套件，等於在裂縫上加壓。
  • 需要 voice（語音）、browser（瀏覽器）、vision（視覺）、image generation（影像生成）或 TTS（語音合成） → 先確認這些媒體能力真的屬於當前工作流。多數編碼任務並不需要一開始啟用媒體工具。

推薦排障順序

不要從最複雜的入口開始排查。穩定順序是：

  1. Provider 能不能完成普通對話。
  2. Session 能不能恢復。
  3. 配置檔案和金鑰是否分開。
  4. Toolset 是否只開了當前任務需要的能力。
  5. Terminal backend 是否符合風險邊界。
  6. Memory 是否只存穩定事實。
  7. Skill 是否來自可信來源並已 hermes skills inspect（檢查命令）透過審查。
  8. Gateway、cron、background（後臺會話）、MCP 再逐項啟用。

Hermes 的複雜問題大多會退回三個基礎點：provider 是否穩定、session 是否可恢復、工具是否越權。先把這三點修對，再回頭看上層報錯——很多上層故障會自己消失。

啟用順序

把 Hermes 放進真實專案時，推薦按下面的順序做，每一步都要有可觀察結果（不只是"配完了"，而是"配完後我能看到什麼變化、出錯怎麼知道"）：

  1. Provider（推理服務商）：普通對話、模型切換和 token 計費路徑都能解釋清楚。
  2. Session（會話）：新建、繼續、搜尋、命名和清理 session 都能工作。
  3. Config（配置）：config.yaml、.env、auth.json、profile（配置檔）與專案 context 檔案（如 AGENTS.md、SOUL.md）分工清楚。
  4. Tools（工具）：只開當前任務需要的 toolset，並記錄高風險命令的批准方式（哪些命令需要按 Y 才執行，哪些走自動放行）。
  5. Backend（後端）：local、Docker、SSH、Daytona、Modal、Singularity、Vercel Sandbox 共 7 個選項只選一個主路徑先跑通；想加第二個之前先確認第一個穩定。
  6. Memory（記憶）：只儲存偏好、環境、約定和已驗證結論，不存日誌、金鑰或臨時細節——記憶是越用越髒的，寫入門檻要高。
  7. Skills（技能）：先使用內建或自建小 skill，跑穩了再考慮 Skills Hub 和外部 skill；任何外部 skill 安裝前都跑 hermes skills inspect 看指令碼和金鑰需求。
  8. Gateway（訊息閘道器）：從一個平臺開始（例如 Telegram 或 Slack），先用 allowlist 限定使用者；跑穩一個再加第二個。
  9. Automation（自動化）：cron、delegation、hooks、kanban、goals 最後啟用，並保留暫停入口——後臺任務必須能被一條命令停掉。

這不是保守，而是減少排障變數。Hermes 的優勢在組合能力，組合能力只有在基礎層穩定後才有價值；基礎不穩就堆功能，等於把噪聲放大。

最小健康狀態

一個可繼續擴充套件的 Hermes 設定應該滿足下面 8 條。可以用來對照自己當前裝機：

  • hermes --help 正常輸出。
  • hermes model 能列出和切換 provider。
  • hermes 能完成一次普通對話（輸入問題、收到合理回覆）。
  • hermes --continue 能恢復上一次 session。
  • ~/.hermes/.env（金鑰）和 config.yaml（配置）分工清楚，互不混寫。
  • terminal.backend 明確指定（local / docker / ssh / ...），不是預設值矇混。
  • toolsets 是按任務最小開啟——比如做編碼任務不開 browser 工具集。
  • Gateway 沒有在未配置 allowlist 的情況下上線（這條最容易踩坑：先開 Gateway 再設 allowlist = 在裸跑期間任何人都能命令你的機器）。

驗收清單

完成本節後，你應該能做一次最小驗收。把下面 10 條逐項確認（任何一項說不清，就別繼續疊加 MCP、cron、delegation 或多平臺閘道器）：

 1. hermes 能进入 CLI 或 TUI
 2. provider 能完成一次普通对话
 3. hermes --continue 能恢复上一轮
 4. 配置文件和密钥文件没有混写（密钥不出现在 config.yaml 里）
 5. 能解释当前 toolset 清单（开了哪几组工具集、为什么）
 6. 能解释 backend 的实际执行位置（命令到底在本机/容器/远端跑）
 7. memory 里没有临时日志、token 或敏感信息
 8. 能解释每个已安装 skill 的来源和作用范围
 9. messaging 入口有 allowlist 或等效访问限制
10. 自动化任务（cron / hooks / goals）有暂停命令、日志和失败告警

下一步

配置優先

新手先從配置頁開始，確認本機閉環能穩定執行——這是後面所有功能的地基。

回到原理篇

如果你還分不清這些能力之間的關係，先回到原理篇建立心智模型——花 30 分鐘比直接開幹省一整天排障。

官方資料

規劃 Hermes Agent 學習路徑

按經驗等級和使用場景選擇 Hermes Agent 文件閱讀順序，先跑通基礎閉環，再進入工具、記憶、訊息閘道器和自動化。

配置 Hermes Agent

理解 Hermes 的 ~/.hermes 目錄、config.yaml、.env、OAuth、配置優先順序、環境變數替換和七類 terminal backend。

本頁目錄

官方手冊覆蓋什麼五個入口按問題定位推薦排障順序啟用順序最小健康狀態驗收清單下一步官方資料