02 · 先跑通第一個穩定閉環 · AI 程式設計教程中文版

第一次使用 Hermes，不要急著接 Telegram、開 cron（定時）、裝 skills（技能）、配置外部 memory provider（記憶外掛）或接 MCP（模型上下文協議）。穩定閉環只有幾件事：命令能啟動，provider 能用，普通對話能完成，剛才的 session（會話）能恢復，低風險工具動作能被你看懂。

官方資料：Quickstart、Installation、Configuration。

先給結論：新手第一天目標不是"全配置完"，而是**"確認最小鏈路可靠"**。閉環不穩定，所有高階功能都會變成排障噪音——同一個錯誤既可能在模型層、也可能在工具層、也可能在 backend 層，一次開 5 個變數等於在沼澤裡找鑰匙。

為什麼先跑閉環

Hermes 是一個能力可以不斷往上疊的系統——toolsets（工具集）、terminal backend（終端後端）、memory（記憶）、skills（技能）、Gateway（訊息閘道器）、cron（定時）、background session（後臺會話）、delegation（委派子代理）、MCP（模型上下文協議）、plugins（外掛）都能繼續接。

但所有複雜能力都依賴底層閉環：

flowchart LR
    Install["安裝與 PATH"] --> Provider["provider/model"]
    Provider --> Chat["普通對話"]
    Chat --> Session["session 恢復"]
    Session --> Tool["低風險工具"]
    Tool --> Advanced["Gateway / skills / memory / cron"]

如果 provider 不穩定、session 儲存不了、CLI 都跑不通，後面接再多功能只會讓問題更難定位。

閉環五步

命令可用

shell 能找到 hermes，幫助命令能輸出。

Provider 可用

key、OAuth、網路、model 和 context size 都能支撐普通對話。

對話可完成

一次小任務能正常回復，不出現 provider 或 context 報錯。

Session 可恢復

用 --continue 或 -c 能接回上一輪上下文。

工具可控

只做只讀、低風險工具驗證，確認 tool output 可理解。

安裝後檢查

先確認命令：

hermes --help

再進入 provider 配置：

hermes model

如果 shell 找不到命令，先 source ~/.bashrc 或 source ~/.zshrc。不要立刻重灌，也不要開始改複雜配置。

Provider 驗證

第一次只配置一個 provider。驗證時看四點：

憑據有效：API key 或 OAuth 沒過期；如果是 OAuth，確認登入流程跑完沒卡在瀏覽器回撥。
網路可用：請求能穩定返回，不是斷斷續續超時。國際 provider 沒梯子時考慮切到中國區直連（Z.AI / Kimi / DeepSeek / Qwen 等）。
模型符合任務：官方 quickstart 強制要求至少 64K tokens 上下文——上下文不夠時 Hermes 在啟動時就會拒絕模型載入，不是執行後才報錯。
成本可控：不會因為一次試跑觸發意外費用。訂閱型 provider（如 Claude Max）按月計費，按 token 計費的（OpenRouter / 直連 API key）需要心裡有數。

多 provider、fallback（備用切換）、routing（路由）都放到基礎閉環之後。否則出錯時你不知道是哪條鏈路壞了——你看到的是"模型回覆超時"，但實際上可能是 fallback 一直在切，每次切都重新建立連線。

第一次任務

第一次任務要小、明確、可驗證。

恢復 session

完成第一次對話後馬上驗證：

hermes --continue

短引數：

hermes -c

如果剛完成的對話不能恢復，先修 session。Gateway、多平臺對話、memory、skills 和 background tasks 都依賴 session 能被正確儲存和恢復。

低風險工具驗證

基礎對話穩定後，再驗證一個低風險工具動作：

只读列出当前目录文件，并说明你不会修改任何文件。

合格標準：

只執行只讀命令。
能展示或總結 tool output。
命令執行位置符合當前 backend。
沒有訪問敏感目錄。

不要在這一步讓 Hermes 修改檔案、執行未知指令碼、接外部平臺或後臺執行命令。

失敗時怎麼定位

對症下藥——下面五種症狀對應的常見根因，一次只改一層：

症狀	最可能的原因	先做什麼
`hermes: command not found`	PATH 或 shell 配置問題（最常見：用 zsh 但只改了 .bashrc）	`echo $SHELL` 看用哪個 shell；`source` 對應的 rc 檔案；檢查 `~/.local/bin` 在 `$PATH` 裡
Provider 報錯（401 / 403 / 拒絕呼叫）	key 錯、OAuth 過期、網路、模型名拼寫、context size 不夠、provider 限流	`hermes model` 重新互動配置；本地模型確認 `--ctx-size 65536`
對話中斷 / 卡住不響應	模型上下文超限、網路、工具呼叫掛起、timeout	看是不是任務太複雜；用 Ctrl+C 中斷後重試小任務
`--continue` 失敗	session 儲存被清、profile 切換、啟動目錄或檔案許可權	`hermes sessions list` 看是否真有上一個 session；確認從同一目錄啟動
工具執行異常	toolset 沒開、terminal backend 不對、cwd（當前目錄）問題、許可權或 sandbox 配置	看是哪個工具報錯；臨時把 toolset 降到最小；確認 backend 是不是預期

不要在一個失敗狀態裡同時改五個變數。一次只改一層——改完跑一次最小驗收命令，確認這一層 OK 再繼續下一層。

官方資料

Quickstart（第一次安裝到對話）
Installation（PATH / 目錄 / Termux / 原生 Windows）
Configuration（~/.hermes/ 檔案分工）
Sessions（session 管理與恢復機制）

02 · 先跑通第一個穩定閉環