Hermes Agent — Self-Improving AI Assistant + Complete Setup Guide

What is it?

In one sentence: an AI worker that improves itself

Hermes Agent is an open-source AI Agent framework from Nous Research. The biggest difference from other agents: it learns automatically from your usage experience. After a task is done once, Hermes can create a Skill for next time. You do not have to manually teach every workflow.

🔄 Self-improvement loop

Do work → remember → create skills → improve skills → do better work

Traditional AI Agent: teach it A, and it only does A.
Hermes Agent: teach it A; it learns A, notices B can use a similar method, and creates a skill for B.

Six core capabilities

Not just a tool — a system that grows

🧠

Self-learning

Automatically creates Skills from experience, making repeated work faster and better. Remembers preferences and work patterns across conversations.

🌐

Five-platform integration

Telegram, Discord, Slack, WhatsApp, Signal + terminal. One Agent can show up across platforms.

🤖

200+ model support

Access 200+ models through OpenRouter. Also supports OpenAI, Anthropic and self-hosted models. Switch with one command.

☁️

Flexible deployment

Run locally, via Docker, SSH, or serverless (Daytona / Modal). Serverless mode does not bill while idle.

⏰

Scheduled automation

Built-in Cron scheduler. Reports, backups and checks can be scheduled in natural language.

🔧

40+ tools + MCP

Includes 40+ tools and supports MCP extensions. Open-source MIT License for community contribution.

⚡ 跟其他Tool Comparison

Hermes Agent vs OpenClaw vs Claude Code + Telegram

	🧠 Hermes Agent	🦞 OpenClaw	⌨️ Claude Code + Telegram
Self-learning	✓ Auto-create Skills	△ Manual setup needed	△ MEMORY.md + brain 系統
Model support	200+（OpenRouter）	Multiple providers	Anthropic only
Messaging platforms	5 platforms incl. WhatsApp	4 platforms incl. LINE	✓ Telegram channel (remote control anytime)
Deployment	Local / Docker / Serverless	Local	Local CLI + Telegram relay
Scheduling	✓ Built-in Cron	✓ Cron + Heartbeat	✓ Remote Trigger / launchd
Multi-agent	Single Agent (enhanced)	✓ Multi-agent 編排	✓ Subagents / Skills
License	MIT（fully open source）	商業License	商業License
Learning curve	Moderate	Steeper	Moderate（會用 CLI + Telegram 設定）
Ecosystem maturity	New (early 2026)	Mature	Mature（officially maintained）

Want the full comparison?→ Three-way comparison page

1. Before installation

Three things you can prepare in five minutes

Operating system and hardware

macOS（Intel 或 Apple Silicon 都可）或 Linux（Ubuntu / Debian 主流發行版）
Memory 8 GB 起跳；想跑語音Mode或Local模型建議 16 GB+
Storage 約 2-3 GB（含 91 個 bundled skills 與快取目錄）
Network: access to GitHub, OpenRouter / OpenAI and Telegram API

The installer automatically handles uv、Python 3.11、Node.js、ripgrep、ffmpeg 等依賴——no need to pre-install them。

LLM provider key（choose one）

OpenRouter（recommended）：openrouter.ai sign up → 開一支 API key → 一個 key 通 200+ 家模型（Claude / GPT / Gemini / Llama / DeepSeek 等）
OpenAI：platform.openai.com create an API key
Anthropic：console.anthropic.com create an API key
You can mix providers（Hermes 支援多 provider 並存，按任務切換）

💡 808AI suggestion

For a first install, use OpenRouter——免綁定特定家、可以試免費模型（如 Llama 3.3、Gemini Flash）跑通流程，確定要長期用再考慮直接綁 Anthropic / OpenAI。

Telegram bot token (optional but strongly recommended)

用 Telegram 搜尋 @BotFather，點 Start
傳 /newbot，依提示輸入 bot 名稱與 username（必須以 bot 結尾，例如 my_hermes_bot）
BotFather 回你一串 token，類似 1234567890:ABCdefGHIjklMNO...——複製保存
傳 /setprivacy → 選你的 bot → 選 Disable（讓 bot 能讀群組訊息，必要時可用）

You can use Hermes without Telegram, but connecting it lets you command it from your phone anywhere — a major difference from the ChatGPT app.

2. One-line install

Official install.sh — runs automatically in about five minutes

# macOS / Linux 通用

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

This command will:

檢查並安裝 uv（Python 套件管理器）
下載 Hermes Agent 源碼到 ~/.hermes/hermes-agent/
建立 Python 3.11 虛擬環境 + 安裝 ~80 個 Python 依賴
安裝系統工具：Node.js、ripgrep、ffmpeg（如果還沒裝）
下載並掛載 91 個 bundled skills（humanizer、p5js、architecture-diagram、sketch、highlighter 等）
建立空 config.yaml、cron 目錄、logs 目錄
把 hermes Commandadd to ~/.local/bin/（記得Confirm在 $PATH 裡）

📍 Directory structure after install

Everything is under ~/.hermes/，跟你既有的 Claude Code（~/.claude/）或 OpenClaw（~/.openclaw/）fully isolated——可以放心並行安裝。

~/.hermes/
├── hermes-agent/      # 源碼
├── config.yaml        # 設定檔（key、model、gateway 全在這）
├── audio_cache/       # 語音Mode快取
├── image_cache/       # 圖像快取
├── cron/              # Scheduling job 設定
├── hooks/             # 觸發事件腳本
└── logs/              # 執行紀錄

⚠️ Possible install blockers

Python 版本：若你 macOS 系統 Python instead of 3.11，uv 會自動下載；無需手動切換。
網路：GitHub raw 內容若被擋（極少數企業內網），先用 VPN 或改下載 release ZIP 解壓再跑 install.sh。
權限：腳本只寫到你的家目錄；不需要 sudo。如果跳出 sudo 詢問——立刻取消，回頭檢查腳本來源。

3. First setup with hermes setup wizard

Interactive wizard, three questions

# Run this right after install

hermes setup

The wizard asks three groups of questions:

Choose an LLM provider

列表會列出已偵測到的 provider（OpenRouter / OpenAI / Anthropic / Local Ollama）。選一個你準備好 key 的——OpenRouter 是 808AI suggestion的第一選擇。

Paste the API key

把上一步準備好的 key 貼進去；wizard 會直接寫進 ~/.hermes/config.yaml 並加密儲存（OS keychain 整合）。不需要手動編輯 config 檔。

Choose the default model

從 provider 的 model list 挑一個當預設。不確定就選列表第一個——之後可以用 hermes model 隨時切換。

結束後 wizard 會跑一次自我測試（呼叫 model 一次驗證 key 可用），看到 ✓ Setup complete 就代表 OK。

4. Configure LLM provider 細節

Switch models, add providers, tune settings anytime

Useful model commands

hermes model

List all available models and mark the current default

hermes model use <name>

Switch the default model，如 hermes model use anthropic/claude-3.5-sonnet

hermes model add <provider>

Add provider（再跑一次 setup wizard 的 model 段）

hermes model test

Call the current model once to test the key and billing path

model picking three principles

Daily chat / brainstorming：用便宜快的（GPT-4o-mini、Claude Haiku、Gemini Flash）
Important decisions / long-form writing：用最頂的（Claude Opus 4.7、GPT-5、Gemini 2.5 Pro）
Large data / long context：選 1M context 的（Gemini 2.5 Pro、Claude 1M context）

/think 與 /fast dynamic switching

v0.13.0 新增的功能：在聊天中直接打 /think default 切到「深度思考」Mode，/fast default 切回「快速回應」——不必離開 session 重設模型。

5. Connect Telegram gateway

Talk to Hermes from your phone anywhere

# Open gateway setup

hermes gateway add telegram

It asks two questions:

Bot token：貼上從 @BotFather 拿到的 token
Allowed chat_id：你自己的 Telegram user ID（傳 /start 給你的 bot，Hermes 會偵測並 prompt 你「是否信任這個 chat」）。strongly recommended: whitelist only yourself，避免被路人騷擾。

After setup, run:

# Start gateway daemon

hermes gateway

看到 Listening for messages... means it worked——打開你 Telegram bot 對話視窗，傳一句「Hi」，Hermes 應該幾秒內回覆。

🌐 17 個 Messaging Gateway overview

Hermes v0.13.0 supports these platforms（替換 telegram 即可）：

Telegram · Discord · Slack · WhatsApp · Signal · Email · SMS · iMessage · 飛書 Lark · 釘釘 DingTalk · WeCom 企業微信 · WeChat · Microsoft Teams · Matrix · Mattermost · Twilio Voice · Google Meet（Twilio 橋接）

6. Three run modes

Pick one, or run several together

Mode	Command	Use case
Interactive TUI	`hermes`	Chat directly in the terminal; good for debugging, trying skills and writing long pieces
Gateway daemon	`hermes gateway`	Runs in the background and receives Telegram / Discord / Slack messages — the main phone-control mode
Cron Scheduling	`hermes cron list`	Triggers scheduled tasks (daily briefs, weekly reports, checks) without interaction

Persistent background service：launchd（macOS） / systemd（Linux）

If you want Hermes to run 24/7 on a Mac mini, wrap the gateway as a launchd / systemd service:

# macOS — Hermes 內建幫你產生 plist

hermes service install --launchd

跑完會在 ~/Library/LaunchAgents/ 產生 com.nous.hermes.gateway.plist，並自動 load。要停掉用 hermes service uninstall。

7. Run alongside Claude Code / OpenClaw

The three stacks can coexist with separate bots and processes

Hermes 安裝在 ~/.hermes/，跟下面兩套fully isolated：

Claude Code → ~/.claude/
OpenClaw → ~/.openclaw/

Only these are shared:

System binaries：uv / Python / Node.js / ffmpeg / ripgrep（one copy is enough）
API keys（選用）：OpenRouter / OpenAI key can be shared across all three to reduce management overhead

💡 808AI Tony’s practical stack suggestion

戰略 + 寫 code → Claude Code（最穩，Subagents 拆任務最順）
自動化 daemon / cron → OpenClaw（多 agent 編排是強項）
想試語音 / Honcho 用戶建模 / 自我建立 Skill → Hermes
三個獨立 Telegram bot，手機收到不同訊息對應到不同 agent，分工清楚。

⚠️ One Telegram polling conflict trap

The same Telegram bot token cannot同時被兩個 process polling——會互踢。每套（Claude Code / OpenClaw / Hermes）必須用different bot tokens。BotFather 開新 bot 完全免費。

8. FAQ / Troubleshooting

安裝後找不到 hermes Command

把 ~/.local/bin add to $PATH：

# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# Zsh（macOS 預設）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

API key keeps being rejected

Check for extra spaces at the beginning of the key：跑 hermes model test 看 error
OpenRouter key 必須以 sk-or- 開頭；OpenAI 是 sk-；Anthropic 是 sk-ant-
OpenRouter account must have credits first $5 美金以上才能用付費模型；free models can still be used

Telegram bot does not respond

Confirm hermes gateway is still running（看終端機有沒有 Listening for messages...）
有沒有把這個 bot token 同時給別人 / 別的 process 用
Confirm你的 chat_id 已加入白名單（hermes gateway allowlist）

Want to fully uninstall

# 1. Stop the service (if installed)

hermes service uninstall

# 2. Delete the whole directory

trash ~/.hermes

Use trash instead of rm -rf——so accidental deletion can be recovered from macOS Trash。

9. Tony’s first-hand test

2026/05/09 notes from a successful run on Mac mini M4 32GB

🧪 From zero to first message in five minutes

安裝：一條 curl 命令搞定，~5 分鐘安裝完，自動處理 uv / Python 3.11 / Node.js / ripgrep / ffmpeg / 91 個 bundled skills。

位置：Everything is under ~/.hermes/，fully isolated不影響既有 Claude Code 或 OpenClaw。

啟動成本：只需一個 LLM provider key（OpenRouter 一個 key 通 200+ models 最方便）+ 獨立 Telegram bot token（BotFather 開新 bot）。

跑起來：hermes（Interactive TUI）/ hermes setup（初次設定 wizard）/ hermes gateway（啟 messaging gateway）。

Practical positioning

跟 Claude Code、OpenClaw 三套完全可以並行——各自獨立 bot、獨立 process、共享 OpenAI / OpenRouter key
Hermes 的 Active Memory + 自動 Skill 建立是真亮點，跟主 agent 互補（instead of取代）
Good fit當「第二意見」reviewer——主 agent 寫東西，丟給 Hermes review，會抓到不同視角
對「想試 Claude 以外模型」的人——OpenRouter 一個 key 通 200+ 家，瞬間打開模型選擇

Is it right for you?

	Good fit	Not yet
Beginner	有 CLI 基礎、敢自己 debug 的人	完全沒摸過終端機——先從 Claude Code + Telegram 入門
已有 AI Tools	想加「第二意見」reviewer / 試新模型	主 agent 還沒用熟——先深耕一個
Use case	單一強化 agent / 語音 / 多 messaging 平台	需要多 agent 編排（用 OpenClaw 更直接）

10. v0.13.0 — 2026/05 new features總覽

過去 1 個月 Hermes 重點往「語音 + realtime + 多平台」方向走（截至 2026/05/10）

🎙️

Discord 語音 STT/TTS

Discord voice channels 支援 realtime 語音轉文字 + 文字轉語音 + agent-proxy Mode。直接用語音跟 Hermes 對話，不必打字。

📞

Google Meet 語音橋

Google Meet + Twilio dial-in 整合 Gemini realtime 語音 bridge。會議中讓 Hermes 即時筆記、回答問題。

🧠

Active Memory 自訂工具名

Active Memory plugin 支援 concrete tool names — 自動觸發更精準，不會誤抓不相關的記憶。

⚙️

Chat overrides

新增 /think default + /fast default 在聊天中即時切換思考深度，不需重啟 session。

📱

iOS 配對 setup codes

iOS app 支援 setup codes 連到私人 LAN gateway。在家用 Mac mini 跑 Hermes，手機可直接配對。

💬

17 個 Messaging Gateway

Telegram / Discord / Slack / WhatsApp / Signal / Email / SMS / 飛書 / 釘釘 / WeCom / WeChat / iMessage 等全平台覆蓋。