Hermes Agent

安裝總覽（macOS 版）

Hermes Agent 安裝與自定義 API 設定指南 — macOS 版

本指南目標：在 macOS 安裝 Hermes Agent（Nous Research 出品的本機 AI agent），並接上自己的 MYAI168 API，使用 Claude Opus 4.8。

涵蓋兩種情境：

  • 路線 A：第一次安裝（從沒裝過 OpenClaw／龍蝦）。
  • 路線 B：已經裝過 OpenClaw，想把設定遷移過來。

Hermes 與 OpenClaw（龍蝦）的差別：OpenClaw 底層是 Node／npm；Hermes 底層是 Python，安裝腳本會自動裝 uv 與 Python 3.11，不需要 sudo，也不會遇到 npm 全域目錄的權限問題。

開始之前：安全須知與前置準備

重要安全須知（務必先看）

  • Hermes 是有實際系統權限的 agent，可讀寫檔案、執行終端機指令、控制瀏覽器、甚至背景控制 macOS 桌面。不建議裝在同步了大量敏感資料的主力機；有條件的話用獨立機器或乾淨帳號。
  • 初期 token 消耗可能偏高，記得到 MYAI168 後台設用量上限。

設定檔位置

  • 設定檔：~/.hermes/config.yaml
  • 金鑰：~/.hermes/.env
  • 資料：~/.hermes/（sessions、logs、cron 等）
  • 程式碼：~/.hermes/hermes-agent

前置：準備好你的 MYAI168 API Key

安裝前先把金鑰準備好。MYAI168 有兩個端點：

OpenAI 相容端點    https://www.myai168.com/nou/api/openai/v1
Anthropic 原生端點 https://www.myai168.com/nou/api/anthropic

要用 Claude Opus 4.8，走 Anthropic 原生端點。

一、安裝 Hermes（兩種路線共通）

執行官方一行安裝腳本：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

這會自動安裝 uv、Python 3.11、clone 專案、完成設定，不需要 sudo。

安裝完成後，讓 hermes 指令在當前視窗生效：

source ~/.zshrc
二、設定供應商（路線 A：第一次安裝）

安裝完會進入設定精靈。路線 A 適用「沒裝過 OpenClaw」的情況。

精靈不會跳出任何 OpenClaw 遷移畫面（因為偵測不到 ~/.openclaw），會直接進入設定。依序這樣選：

  • How would you like to set up Hermes? → 選 Full setup（自己設定每個供應商，用自己的 key）。不要選 Quick Setup（Nous Portal），那是 Nous 自家訂閱服務。
  • Select provider：捲到清單最底下，選 custom (direct API) 或 Custom endpoint (enter URL manually)。接著依序輸入：
    • Base URL：https://www.myai168.com/nou/api/anthropic
    • API Key：你的 MYAI168 金鑰
    • Model：claude-opus-4-8
    • api_mode：選 anthropic_messages（Anthropic 協定）
  • 通訊平台（Telegram／Slack／Discord…） → 全部不選，直接 Enter。
  • 工具（Tools） → 可直接接受預設；若想保守，用 SPACE 關掉 Computer Use (macOS)、Browser Automation、Code Execution 這幾個高權限工具，核心對話不受影響。
  • 後續各種 Choose a provider（瀏覽器、圖片、TTS、視覺、搜尋）→ 一律選 Skip，之後想用再設。

設定完成後，建議仍做「手動確認／修正設定」一節再驗證。

二、設定供應商（路線 B：從 OpenClaw 遷移）

如果機器上裝過 OpenClaw 並設定過 MYAI168，精靈會自動偵測並詢問遷移。

  • OpenClaw Installation Detected：Would you like to see what can be imported? → 按 Y。
  • Migration Preview（會列出 provider-keys、custom_providers[myai168] 等項目）→ 確認金鑰與供應商在「會匯入」清單裡 → 按 y 繼續。
  • How would you like to set up Hermes? → 選 Full setup（不要選 Nous Portal）。
  • 接著精靈會逐段顯示「已從 OpenClaw 匯入」並問要不要重設：大原則——全部按 N（保持），把精靈跑完。通訊平台全不選、各種工具 provider 一律 Skip。

注意：精靈跑完後，model 區塊有可能被預設值（OpenRouter／官方 Anthropic）覆蓋，且遷移的金鑰也可能沒留下。所以遷移路線「跑完一定要做下一節的手動確認」。

手動確認／修正設定（兩條路線都建議做）

不論哪條路線，設定精靈都可能沒把模型指到正確的自定義端點。最確定的做法是直接檢查並編輯設定檔。

先檢查金鑰在不在

cat ~/.hermes/.env

裡面應該要有（沒有就用下面兩行補上，換成真正的金鑰）：

echo 'MYAI168_CLAUDE_API_KEY=你的-key' >> ~/.hermes/.env
echo 'MYAI168_API_KEY=你的-key' >> ~/.hermes/.env

（OpenAI 與 Anthropic 端點若共用一把 key，兩行填一樣即可。）

再編輯設定檔

hermes config edit

把最上面的 model 區塊改成下面這樣（YAML 用空格縮排，不要用 Tab；下方原本的 fallback_providers、toolsets、agent 等區塊保持不動）：

model:
  provider: custom:myai168_claude
  default: claude-opus-4-8
  context_length: 200000

custom_providers:
  - name: myai168_claude
    base_url: https://www.myai168.com/nou/api/anthropic
    key_env: MYAI168_CLAUDE_API_KEY
    api_mode: anthropic_messages
  - name: myai168
    base_url: https://www.myai168.com/nou/api/openai/v1
    key_env: MYAI168_API_KEY
    api_mode: chat_completions

providers: {}

說明

  • provider 寫成 custom:myai168_claude，對應下方 name 為 myai168_claude 的那筆，走 Anthropic 協定。
  • key_env 指向 .env 裡的變數名稱，不是金鑰本身。
  • Anthropic 端點的 base_url 結尾用 .../anthropic（不含 /v1），Hermes 在 anthropic_messages 模式會自己接上 /v1/messages。
  • context_length 明確填 200000；Hermes 要求 agent 至少 64,000 token。

存檔方式（看 hermes config edit 開的是哪個編輯器）

  • nano → Ctrl + O 再 Enter，然後 Ctrl + X 離開。
  • vim → 先 Esc，輸入 :wq 再 Enter。
  • 圖形編輯器 → Cmd + S 存檔後關閉。
三、驗證與啟動

檢查設定：

hermes doctor

（若它只提醒「Run hermes setup to configure missing API keys for full tool access」，那是指你 Skip 掉的工具還沒設 key，與模型無關，可忽略。不要因此重跑 hermes setup，以免又覆蓋設定。）

開始聊天——直接打 hermes 進入互動介面最省事：

hermes

進到聊天畫面後直接打字、按 Enter 送出。（若想用單行測試，注意要用半形引號：hermes chat "你好"。）

成功的樣子：模型正常回話，畫面底部狀態列顯示 claude-opus-4-8、context 上限 200K。這代表 MYAI168 + Claude Opus 4.8 已接通。

四、常見問題速查
  • hermes 指令找不到（command not found） → 執行 source ~/.zshrc，或重開終端機視窗。
  • hermes chat 回話報 404／not found → 端點路徑問題。把 myai168_claude 的 base_url 從 .../anthropic 改成 .../anthropic/v1 再試。
  • 回話報 401／unauthorized → .env 裡的 MYAI168_CLAUDE_API_KEY 沒填或填錯，檢查金鑰。
  • 想切換模型 → 對話中用 /model 切換已設定好的模型；要新增供應商則離開 session 後跑 hermes model。
  • 想之後接通訊軟體 → hermes gateway setup。
五、維護

更新到最新版：

hermes update

兩個模型管理指令的差別

  • hermes model：在終端機（session 外）跑，完整供應商設定精靈。
  • /model：在對話中跑，只能切換已設定好的供應商／模型。

官方文件：https://hermes-agent.nousresearch.com/docs

其他常見問題頁面