1. 為什么我最后把 Hermes Agent 留在了本地第一次接觸 Hermes Agent 的時候我其實沒抱太大期待。AI 智能體平臺這兩年冒出來太多裝完能跑、跑完能用的沒幾個。Hermes Agent 是 Nous Research 出的開源智能體框架簡單說就是你給它一個模型 API Key它就能在本地起一個帶 Web UI 的智能體平臺能聊天、能調(diào)工具、能掛消息網(wǎng)關、能跑定時任務。適合誰適合想在自己機器上快速驗證 Agent 能力、又不想被 Docker 編排和一堆環(huán)境變量折磨的開發(fā)者。我試過在 Windows WSL 里從零裝一遍整個過程最花時間的不是安裝本身而是搞清楚 Web UI 到底監(jiān)聽哪個端口、模型 Key 該填在哪一層。這篇就把這條路徑完整走一遍依賴清單、可復制的安裝命令、配置文件片段、啟動后訪問 Web UI、創(chuàng)建第一個智能體對話的驗證動作。目標很明確——10 分鐘內(nèi)確認平臺可用。需要提前說清楚一件事Hermes Agent 本身是框架它不綁定某一家模型服務。你可以接 Claude、OpenAI也可以接兼容 OpenAI 協(xié)議的國內(nèi)模型網(wǎng)關。我這次演示用的是 TaoToken 的 API 作為模型后端因為它同時提供 Claude Code 和 OpenAI 兼容兩種接入方式配置起來比較省事。下面所有命令和配置都可以直接抄。環(huán)境前提只有三條一臺能跑 Node.js 的機器Windows 用 WSL、macOS、Linux 都行Node.js 18 以上以及一個可用的模型 API Key。不需要 Docker不需要單獨裝數(shù)據(jù)庫Hermes 默認用本地 SQLite 存會話和記憶。2. 裝 Hermes Agent 前先把模型入口配好很多人卡在第一步不是因為 Hermes 裝不上而是裝完之后模型調(diào)不通。所以我把順序調(diào)一下先把模型入口準備好再裝 Hermes。這樣裝完直接就能對話不用來回改配置。我用的模型入口是 TaoToken。它的官網(wǎng)是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址后面不加任何參數(shù)直接就是根路徑。它兼容 OpenAI 的/v1/chat/completions和 Anthropic 的/v1/messages兩種協(xié)議所以 Hermes 里無論選 OpenAI 還是 Claude 類型都能接。先去控制臺拿 Key。打開 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登錄后在 API Keys 頁面創(chuàng)建一個新 Key。創(chuàng)建時建議給它起個能認出來的名字比如hermes-local方便以后區(qū)分。Key 只在創(chuàng)建時完整顯示一次復制下來存好。拿到 Key 之后先別急著裝 Hermes用 curl 驗證一下這個 Key 能不能正常調(diào)模型。這一步能省掉后面 80% 的排障時間curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-3-5-sonnet-20241022, messages: [{role: user, content: 只回復兩個字可用}], max_tokens: 16 }如果返回的 JSON 里choices[0].message.content是「可用」說明 Key 和網(wǎng)絡都沒問題。如果返回 401說明 Key 復制錯了或者被禁用如果返回 404檢查一下 URL 是不是寫成了/api/v1/chat/completions少一個v1就會 404。模型 ID 這塊要注意TaoToken 的模型列表在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 可以查到。Claude 系列用claude-3-5-sonnet-20241022這種帶日期的完整 IDOpenAI 系列用gpt-4o這種短 ID。Hermes 的配置向?qū)Ю飼屇闾钅Ｐ兔铄e的話啟動后對話會報model not found。如果你打算長期跑 Agent 任務比如定時任務、多輪工具調(diào)用可以考慮 TaoToken 的 Coding Plan它在長上下文和連續(xù)調(diào)用場景下更劃算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。不過第一次上手先用按量計費的 Key 就夠了跑通再說。3. 可復制的安裝與配置文件片段現(xiàn)在開始裝 Hermes Agent。官方安裝腳本是一行命令但國內(nèi)網(wǎng)絡直接跑容易卡在下載環(huán)節(jié)所以我建議先配好 npm 鏡像再裝。第一步確認 Node.js 版本node -v npm -v如果低于 18先升級。WSL 里可以用 nvm 裝curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20第二步配 npm 鏡像并安裝 Hermesnpm config set registry https://registry.npmmirror.com npm install -g hermes-agent裝完后跑健康檢查hermes doctor你會看到一串檢查項包括 Node 版本、配置文件、模型連通性。第一次跑的時候模型那項大概率是紅的因為還沒配 Key。第三步寫配置文件。Hermes 的配置默認在~/.hermes/config.toml你也可以用hermes setup走向?qū)У驅(qū)в袝r候會覆蓋已有配置所以我更推薦直接寫文件。下面這份是我實測能跑通的配置路徑和字段名都跟當前版本一致# ~/.hermes/config.toml [model] provider openai base_url https://taotoken.net/api/v1 api_key sk-你的Key model claude-3-5-sonnet-20241022 max_tokens 4096 temperature 0.7 [web] enabled true host 0.0.0.0 port 8648 [memory] enabled true backend sqlite path ~/.hermes/memory.db [gateway] enabled false幾個關鍵點解釋一下。provider填openai是因為 TaoToken 的/v1/chat/completions走 OpenAI 協(xié)議即使底層模型是 Claude 也這么填。base_url一定要帶/v1這是 OpenAI SDK 的約定少了會 404。model填你在 TaoToken 模型列表里看到的完整 ID。web.port默認就是 8648如果你機器上這個端口被占了改成 8649 之類的。如果你更習慣用 Claude 原生協(xié)議也可以把 provider 改成anthropicbase_url 改成https://taotoken.net/apimodel 不變。兩種方式我都試過OpenAI 協(xié)議在 Hermes 里兼容性更好工具調(diào)用更穩(wěn)。第四步裝 Web UI。Hermes 本體自帶命令行但 Web UI 是單獨一個包npm install -g hermes-web-ui hermes-web-ui start啟動成功會打印一行Web UI running at http://localhost:8648。如果你在 WSL 里跑Windows 瀏覽器直接訪問http://localhost:8648就能打開WSL2 會自動做端口轉(zhuǎn)發(fā)。4. 啟動后驗證 Web UI 與首個智能體對話Web UI 起來之后先別急著建 Agent按順序做三個驗證動作確認整條鏈路是通的。第一個動作打開http://localhost:8648你應該看到一個左側(cè)欄 中間對話區(qū)的面板。左側(cè)欄頂部有「Agents」「Sessions」「Skills」「Settings」幾個入口。如果頁面白屏按 F12 看 Console大概率是hermes-web-ui沒連上后端檢查hermes主進程有沒有在跑。第二個動作進 Settings確認模型配置讀到了。這里會顯示當前 provider、base_url、model。如果顯示的是空或者默認值說明~/.hermes/config.toml沒被讀到檢查文件路徑和 TOML 語法。TOML 對引號很敏感字符串必須用雙引號。第三個動作創(chuàng)建一個最小 Agent 并對話。點左側(cè)「Agents」→「New Agent」填三個字段字段填什么說明Nametest-agent隨便起后面能改Modelclaude-3-5-sonnet-20241022跟 config.toml 里一致System Prompt你是一個簡潔的助手回答不超過三句話。先簡單點保存后回到對話區(qū)選中test-agent輸入「你好介紹一下你自己」。正常的話你會看到 SSE 流式輸出字一個一個蹦出來。如果卡住不動看終端里hermes進程有沒有報錯。再做一個工具調(diào)用驗證。在對話里輸入「現(xiàn)在幾點用工具查一下」。Hermes 內(nèi)置了時間工具正常會觸發(fā)一次 tool call返回當前時間。這一步能驗證模型是否支持 function calling。如果模型返回的是純文本「我無法獲取時間」說明你用的模型 ID 不支持工具調(diào)用換gpt-4o或claude-3-5-sonnet再試。到這里平臺就算跑通了。整個過程如果網(wǎng)絡順利從裝 Node 到發(fā)出第一條消息10 分鐘是夠的。我實測下來最慢的一步是npm install -g hermes-agent配了鏡像之后大概 40 秒。5. 報錯排查401、local proxy failed 與 reading choices這一節(jié)把我踩過的坑列出來你遇到報錯直接對號入座。401 Unauthorized。這是最常見的。原因有三個Key 復制時帶了空格、Key 被禁用、或者base_url和provider不匹配。排查方法先用第 2 節(jié)那條 curl 命令單獨測 Keycurl 通了說明 Key 沒問題問題在 Hermes 配置。重點檢查config.toml里api_key那行有沒有多余引號嵌套比如api_key sk-xxx這種。local proxy failed / connection refused。這個報錯通常出現(xiàn)在你本地開了某個網(wǎng)絡工具Hermes 的請求被攔了。解決方法是檢查環(huán)境變量HTTP_PROXY和HTTPS_PROXY如果設了但代理沒開請求就會 refused。臨時清掉unset HTTP_PROXY unset HTTPS_PROXY hermes restartError reading choices / choices is undefined。這個報錯說明模型返回的 JSON 結(jié)構(gòu)跟 Hermes 預期的不一樣。常見原因是base_url少寫了/v1請求打到了根路徑返回的是 HTML 而不是 JSON。檢查base_url https://taotoken.net/api/v1這一行。另一個原因是模型 ID 寫錯了服務端返回了錯誤對象里面沒有choices字段。用 curl 單獨測一下你填的那個 model ID。OAuth token expired。如果你在 Hermes 里配了 Claude 的 OAuth 登錄而不是 API Key會碰到這個。OAuth token 有效期短過期后要重新授權。我的建議是本地開發(fā)直接用 API Key別用 OAuth省心。TaoToken 的 Key 是長期有效的不存在過期問題。Web UI 打不開端口 8648 被占用。先查誰占了lsof -i :8648如果是別的進程改config.toml里的web.port為 8649然后hermes restart和hermes-web-ui restart。注意兩個服務都要重啟只重啟一個不生效。Agent 回復到一半斷了?？唇K端有沒有max_tokens exceeded。Hermes 默認max_tokens可能偏小在config.toml里調(diào)到 4096 或 8192。另外 TaoToken 的 Claude 模型單次輸出上限跟模型本身有關claude-3-5-sonnet支持到 8192填大了也沒用。如果你用的是 Cline MCP 或者 Codex 的auth.json方式接入記住三件套必須同時對上Base URL 填https://taotoken.net/api/v1Key 填sk-開頭那串Model ID 填完整帶日期的版本號。這三個任何一個不對都會報上面那些錯。6. 跑通之后下一步可以做什么平臺跑通只是起點。Hermes 真正有意思的地方在于它的記憶系統(tǒng)和技能市場。你可以在 Web UI 的 Skills 頁面搜關鍵詞找到合適的技能直接裝比如網(wǎng)頁抓取、文件處理、定時總結(jié)。裝完的技能會出現(xiàn)在 Agent 的工具列表里對話時模型會自動調(diào)用。如果你想讓 Agent 常駐跑任務比如每天早上總結(jié)一次新聞可以在 Web UI 的 Cron 頁面配一個定時任務Cron 表達式寫0 9 * * *任務內(nèi)容寫你的 prompt。任務觸發(fā)時 Hermes 會自己調(diào)模型執(zhí)行結(jié)果存在會話歷史里。模型入口這塊如果你后面要跑大量 Agent 任務按量計費的 Key 可能會比預期貴。TaoToken 的 Coding Plan 在連續(xù)調(diào)用場景下有更劃算的計費方式入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各種協(xié)議的完整示例。API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 需要新建或吊銷 Key 的時候去那里。最后說一個我自己的習慣每次改完config.toml先跑hermes doctor再重啟服務。doctor 會告訴你哪一項配置沒生效比直接重啟然后對著報錯猜要快得多。這個習慣幫我省了不少來回折騰的時間。