Hermes Agent 完整使用指南

適用情境：macOS／Linux／WSL2，並包含 Gemini API、Telegram Gateway、Skills、Memory、Cron、Google Workspace、Google Calendar、Fallback Provider 與安全設定。
更新基準：2026-06-28。不同版本的指令可能略有差異，請以本機 hermes --help 與官方文件為準。

Hermes Agent 是什麼
安裝與環境確認
首次設定
模型與 Provider
CLI 與 TUI 基本操作
Session 管理
Slash Commands
Tools 與 Toolsets
Skills
Memory 與 Session Search
SOUL.md 與 AGENTS.md
Telegram Gateway
Cron 自動化
Google Workspace 與 Google Calendar
Fallback Provider 與 Gemini 額度
Context Compression 與 Token 控制
Profiles
安全設定
更新、備份與解除安裝
常見問題排查
推薦日常工作流
指令速查表
官方參考資料

1. Hermes Agent 是什麼

Hermes Agent 是 Nous Research 開發的自主型 AI Agent。它除了聊天，也能：

執行 Terminal 指令。
搜尋、讀取與修改檔案。
搜尋網頁與進行瀏覽器操作。
建立可重複使用的 Skills。
保存跨 Session 的長期記憶。
透過 Telegram、Discord、Slack 等平台遠端操作。
建立 Cron 排程與監控任務。
使用不同模型供應商，並在主模型失敗時自動切換備援。
透過 Google Workspace OAuth 操作 Calendar、Gmail、Drive、Docs、Sheets 等服務。

Hermes 的使用者資料通常位於：

~/.hermes/
├── config.yaml
├── .env
├── SOUL.md
├── state.db
├── memories/
├── skills/
├── cron/
├── logs/
├── checkpoints/
├── google_token.json
└── google_client_secret.json

主要用途：

路徑	用途
`~/.hermes/config.yaml`	一般設定
`~/.hermes/.env`	API Key、Bot Token 等機密
`~/.hermes/SOUL.md`	Agent 的穩定人格與語氣
`~/.hermes/state.db`	CLI、TUI、Telegram 等 Session
`~/.hermes/memories/`	長期記憶
`~/.hermes/skills/`	自訂與安裝的 Skills
`~/.hermes/cron/`	排程資料
`~/.hermes/logs/`	執行紀錄

2. 安裝與環境確認

2.1 macOS、Linux、WSL2

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安裝完成後重新載入 Shell：

source ~/.zshrc

或：

source ~/.bashrc

確認：

hermes --version

2.2 Windows PowerShell

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

2.3 不需要 Browser Automation 的輕量安裝

curl -fsSL https://hermes-agent.nousresearch.com/install.sh \
  | bash -s -- --skip-browser

2.4 一般安裝路徑

程式碼：
~/.hermes/hermes-agent/

CLI：
~/.local/bin/hermes

資料與設定：
~/.hermes/

2.5 `hermes: command not found`

先執行：

export PATH="$HOME/.local/bin:$PATH"

永久加入 zsh：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

確認：

which hermes
hermes --version

2.6 Intel Mac 注意事項

官方安裝器會處理 Hermes 所需的主要依賴，例如 Python、Node.js、ripgrep 與 ffmpeg。舊款 Intel Mac 建議先確認：

git --version
uname -m

若使用公司代理、VPN 或嚴格防火牆，安裝套件與模型 API 連線可能需要另外設定 Proxy。

3. 首次設定

3.1 完整設定精靈

hermes setup

快速使用 Nous Portal：

hermes setup --portal

重新設定特定區塊：

hermes setup model
hermes setup terminal
hermes setup gateway
hermes setup tools
hermes setup agent

3.2 健康檢查

hermes doctor

查看整體狀態：

hermes status

深入檢查：

hermes status --deep

輸出可供除錯的設定摘要：

hermes dump

3.3 設定檔

機密：
~/.hermes/.env

一般設定：
~/.hermes/config.yaml

CLI 設定範例：

hermes config set terminal.backend local
hermes config set agent.max_turns 90
hermes config set agent.api_max_retries 0

檢查舊設定：

hermes config check
hermes config migrate

4. 模型與 Provider

4.1 新增或變更 Provider

在一般 Terminal 執行：

hermes model

設定精靈可處理：

Provider 選擇。
API Key。
OAuth。
模型名稱。
自架 OpenAI-compatible Endpoint。
預設模型。

4.2 Session 內切換模型

進入 Hermes 後：

/model

切換已設定模型：

/model MODEL_NAME

切換並保存為全域預設：

/model MODEL_NAME --global

差異：

操作	用途
`hermes model`	新增 Provider、API Key、OAuth、Endpoint
`/model`	在已設定模型中切換
`/model ... --global`	保存新預設

4.3 Gemini API

Hermes 支援 Google AI Studio API Key，環境變數常用：

GOOGLE_API_KEY=YOUR_API_KEY

部分版本也支援：

GEMINI_API_KEY=YOUR_API_KEY

建議透過：

hermes model

設定，避免手動修改錯誤欄位。

4.4 單次覆寫模型

hermes chat \
  --provider gemini \
  --model YOUR_GEMINI_MODEL \
  -q "Summarize this repository"

這只影響本次執行，不修改全域預設。

4.5 模型選擇原則

Hermes 需要能穩定進行 Tool Calling 的模型。建議：

Context Window 至少約 64K。
支援 Structured Tool Call。
對程式碼與多步驟推理表現穩定。
主模型搭配不同供應商的 Fallback。

5. CLI 與 TUI 基本操作

5.1 啟動

hermes

或：

hermes chat

啟動 TUI：

hermes --tui

強制使用傳統 CLI：

hermes --cli

5.2 單次查詢

hermes chat -q "Summarize this project"

只輸出最終結果，適合 Shell Script：

hermes -z "Summarize the input"

搭配 stdin：

cat report.md | hermes -z "Summarize this report"

存入變數：

answer=$(hermes -z "What is 2 + 2?")
echo "$answer"

5.3 指定 Toolsets

hermes chat --toolsets web,terminal,file

只開啟必要工具可降低：

System Prompt Token。
誤操作風險。
模型選錯工具的機率。

5.4 多行輸入

依 Terminal 支援情況，可使用：

Alt + Enter
Ctrl + J
Shift + Enter

5.5 中斷工作

Ctrl + C

部分介面也支援：

/stop

6. Session 管理

6.1 繼續上一個 Session

hermes --continue

縮寫：

hermes -c

依名稱或 ID：

hermes -r "SESSION_ID_OR_TITLE"

6.2 查看 Session

hermes sessions list

依來源：

hermes sessions list --source telegram

顯示更多：

hermes sessions list --limit 50

6.3 重新命名

hermes sessions rename SESSION_ID "auth debugging"

6.4 匯出

hermes sessions export backup.jsonl

只匯出 Telegram：

hermes sessions export telegram.jsonl --source telegram

單一 Session：

hermes sessions export session.jsonl --session-id SESSION_ID

6.5 刪除與清理

hermes sessions delete SESSION_ID

不詢問：

hermes sessions delete SESSION_ID --yes

清理舊 Session：

hermes sessions prune --older-than 30

6.6 `/new`

/new

用途：

開始乾淨的 Context。
切換到不同主題。
降低舊對話對模型的干擾。

它不會刪除：

Persistent Memory。
Skills。
歷史 Session。
Google OAuth Token。
Telegram 設定。

建立有名稱的新 Session：

/new nextjs-refactor

6.7 `/compress`

/compress

用途：

摘要較舊對話。
保留近期訊息。
降低目前 Context 使用量。

它不是刪除歷史，原 Session 仍保存在：

~/.hermes/state.db

7. Slash Commands

實際可用命令依版本與平台而異，先查看：

/help

常見命令：

Command	用途
`/help`	查看命令
`/new [title]`	建立新 Session
`/reset`	重設目前對話
`/compress`	壓縮 Context
`/usage`	查看 Token 使用量
`/status`	查看狀態
`/model`	切換模型
`/tools`	管理工具
`/skills`	查看 Skills
`/cron`	管理排程
`/personality`	暫時切換人格
`/title`	查看或修改標題
`/retry`	重試上一個請求
`/undo`	回復上一個操作
`/stop`	停止目前工作
`/save`	保存快照
`/whoami`	查看平台 User ID
`/approve`	核准待批准操作
`/deny`	拒絕待批准操作
`/yolo`	切換略過 Approval 的危險模式
`/quit`	離開

8. Tools 與 Toolsets

8.1 管理工具

hermes tools

工具可依平台分開啟用，例如：

CLI：
Terminal、File、Web、Skills、Memory

Telegram：
Web、File、Skills、Memory、Cron

Cron：
只啟用該 Job 需要的工具

8.2 常見工具類型

類別	用途
Web	搜尋與擷取網頁
Terminal	執行 Shell
File	讀寫、修改、搜尋檔案
Browser	Browser Automation
Vision	圖片分析
Image	生成圖片
Memory	讀寫長期記憶
Skills	載入與維護流程
Cron	建立與維護排程
Delegation	啟動子 Agent
Code Execution	以 Python 組合工具操作

8.3 單次指定

hermes chat --toolsets web,terminal

hermes chat --toolsets file,skills,memory

8.4 全域停用

在 ~/.hermes/config.yaml：

agent:
  disabled_toolsets:
    - browser
    - image

8.5 最小權限原則

Telegram Bot 不建議預設擁有完整 Terminal 權限，尤其 Bot 可能加入群組時。

9. Skills

9.1 Skill 是什麼

Skill 是可按需載入的 SKILL.md 工作流程，適合：

Kubernetes 部署。
GitHub PR 流程。
Obsidian Digital Garden 發布。
資料庫 Migration。
公司內部 SOP。
固定 Debugging 流程。

Skill 不會在每次請求中完整載入，比把所有操作寫進 AGENTS.md 更節省 Token。

9.2 路徑與結構

~/.hermes/skills/
└── productivity/
    └── my-workflow/
        ├── SKILL.md
        ├── references/
        ├── scripts/
        ├── templates/
        └── assets/

9.3 查看與搜尋

hermes skills list
hermes skills browse
hermes skills search kubernetes

9.4 安裝

hermes skills inspect openai/skills/k8s
hermes skills install openai/skills/k8s

官方 Optional Skill：

hermes skills install official/security/1password

URL：

hermes skills install https://example.com/SKILL.md --name my-skill

9.5 使用

Skill 通常可作為 Slash Command：

/github-pr-workflow create a PR for the auth refactor

/plan design a migration rollout

9.6 從流程學成 Skill

/learn how I just deployed the staging server

/learn the REST API under ~/projects/acme-sdk

/learn https://docs.example.com/api

9.7 更新與移除

hermes skills check
hermes skills update
hermes skills audit
hermes skills uninstall SKILL_NAME

恢復 Bundled Skill：

hermes skills reset google-workspace --restore

9.8 Skill 寫入審核

skills:
  write_approval: true

管理：

/skills pending
/skills diff ID
/skills approve ID
/skills reject ID

9.9 Memory、AGENTS 與 Skill 的分工

簡單偏好／環境事實 → Memory
專案規則 → AGENTS.md
穩定人格 → SOUL.md
可重複、超過數個步驟的流程 → Skill
一次性工作 → 普通 Prompt

10. Memory 與 Session Search

10.1 內建記憶

Hermes 的精簡長期記憶通常包含：

檔案	用途	約略限制
`MEMORY.md`	環境、長期事實、工作方式	2,200 字元
`USER.md`	使用者偏好與溝通風格	1,375 字元

通常位於：

~/.hermes/memories/

10.2 適合存放

使用繁體中文。
時區是 Asia/Taipei。
Node.js 專案預設使用 pnpm。
Vault 路徑。
固定 Repository 名稱。
不允許自動刪除 Production 資料。

不適合：

長篇技術文件。
完整部署腳本。
每日變動狀態。
一次性任務細節。

10.3 Session Search

歷史 Session 存在：

~/.hermes/state.db

Hermes 可利用全文搜尋找回以前對話，因此「未進入 Memory」不代表完全消失。

10.4 Memory 與 Skill 差異

Memory：
是什麼、在哪裡、偏好什麼

Skill：
如何做、有哪些步驟、怎麼驗證

例子：

Memory：
Obsidian Vault 在 /Users/miketsai/Documents/obsidian-vault

Skill：
如何標記、發布、驗證 Digital Garden

11. SOUL.md 與 AGENTS.md

11.1 SOUL.md

位置：

~/.hermes/SOUL.md

適合設定：

回覆語言。
語氣。
是否直接。
如何處理不確定性。
是否主動質疑危險方案。

範例：

# Personality

You are a pragmatic senior software engineer.

## Style

- Respond in Traditional Chinese unless asked otherwise.
- Be direct and technically precise.
- Prefer actionable commands over abstract explanations.
- Challenge unsafe or fragile approaches.
- State uncertainty clearly.
- Avoid unnecessary filler.

修改後建議：

/new

讓新 Session 重新載入。

11.2 AGENTS.md

放在專案根目錄：

project/
├── AGENTS.md
├── package.json
└── src/

範例：

# Project Context

This is a Next.js application using pnpm.

## Commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`

## Rules

- Use TypeScript strict mode.
- Do not use npm or yarn.
- Never edit generated migration files manually.
- Run tests before committing.

11.3 Context 檔案優先順序

Hermes 會依優先順序選取專案規則：

.hermes.md
→ AGENTS.md
→ CLAUDE.md
→ .cursorrules

SOUL.md 是獨立的人格設定，不參與上述互斥順序。

11.4 Monorepo

project/
├── AGENTS.md
├── frontend/
│   └── AGENTS.md
└── backend/
    └── AGENTS.md

子目錄規則可延後載入，避免初始 Prompt 過大。

12. Telegram Gateway

12.1 建立 Bot

在 Telegram 找：

@BotFather

建立：

/newbot

取得 Bot Token。

取得自己的 User ID，可透過：

@userinfobot

或 Hermes 中：

/whoami

12.2 設定精靈

hermes gateway setup

選擇 Telegram，輸入：

Bot Token。
Allowed User IDs。

12.3 手動設定

nano ~/.hermes/.env

加入：

TELEGRAM_BOT_TOKEN=123456789:YOUR_BOT_TOKEN
TELEGRAM_ALLOWED_USERS=123456789

多個使用者：

TELEGRAM_ALLOWED_USERS=123456789,987654321

12.4 啟動

前景：

hermes gateway run

安裝為 Service：

hermes gateway install
hermes gateway start

狀態：

hermes gateway status

重啟：

hermes gateway restart

停止：

hermes gateway stop

12.5 發送測試訊息

hermes send --list telegram

hermes send --to telegram "Hermes gateway test"

指定 Chat：

hermes send --to telegram:123456789 "Test message"

發送檔案：

hermes send --to telegram "MEDIA:/tmp/report.pdf"

圖片以文件傳送：

hermes send --to telegram \
  "[[as_document]] MEDIA:/tmp/screenshot.png"

12.6 群組設定

TELEGRAM_GROUP_ALLOWED_USERS=987654321
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890

注意：

TELEGRAM_ALLOWED_USERS 可授權 DM 與群組。
TELEGRAM_GROUP_ALLOWED_USERS 只控制群組。
BotFather Privacy Mode 可能影響 Bot 是否能讀取群組訊息。

12.7 安全原則

務必設定 Allowlist：

TELEGRAM_ALLOWED_USERS=YOUR_USER_ID

不建議：

TELEGRAM_ALLOWED_USERS=*

特別是在 Telegram Toolset 包含 Terminal 時。

13. Cron 自動化

13.1 前提

Cron 由 Gateway Scheduler 執行，因此 Gateway 必須持續運作：

hermes gateway install
hermes gateway start

13.2 自然語言建立

對 Hermes 說：

每天上午 9 點整理 AI 新聞並傳到 Telegram。

13.3 Slash Command

/cron add 30m "Remind me to check the build"

/cron add "every 2h" "Check server status"

13.4 Shell CLI

hermes cron create "every 2h" "Check server status"

每天 09:00：

hermes cron create "0 9 * * *" \
  "Summarize today's priorities" \
  --name "Morning Brief"

指定工作目錄：

hermes cron create "every 1d at 09:00" \
  "Audit open PRs and summarize CI health" \
  --workdir /Users/miketsai/projects/my-project

13.5 管理

hermes cron list
hermes cron status
hermes cron pause JOB_ID
hermes cron resume JOB_ID
hermes cron run JOB_ID
hermes cron edit JOB_ID --schedule "every 4h"
hermes cron remove JOB_ID

13.6 Schedule 範例

30m                 一次性，30 分鐘後
2h                  一次性，2 小時後
every 30m           每 30 分鐘
every 2h            每 2 小時
0 9 * * *           每天 09:00
0 9 * * 1-5         平日 09:00
0 */6 * * *         每 6 小時

13.7 Telegram Delivery

telegram
telegram:123456789
telegram:-1001234567890
telegram:-1001234567890:THREAD_ID

13.8 靜默監控

Prompt：

檢查 nginx 是否運作。
如果正常，只回覆 [SILENT]。
如果異常，說明問題。

13.9 Script-only Cron

適合不需要 LLM 的固定監控：

hermes cron create "every 5m" \
  --no-agent \
  --script memory-watchdog.sh \
  --deliver telegram \
  --name "memory-watchdog"

用途：

Disk usage。
RAM threshold。
Heartbeat。
檔案異動。
CI status。

14. Google Workspace 與 Google Calendar

Hermes Bundled Skill：

skills/productivity/google-workspace/

支援：

Gmail。
Calendar。
Drive。
Contacts。
Sheets。
Docs。

14.1 確認 Skill

hermes skills list | grep google-workspace

若缺少或被修改：

hermes skills reset google-workspace --restore

14.2 Google Cloud 設定

建立或選擇 Google Cloud Project。
啟用所需 API。
設定 OAuth Consent Screen。
External + Testing 時，把自己的 Google 帳號加入 Test Users。
建立 OAuth Client。
Application Type 選 Desktop app。
下載 Client Secret JSON。

Calendar 至少啟用：

Google Calendar API

14.3 OAuth Setup

建立捷徑：

GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"

安裝依賴：

$GSETUP --install-deps

檢查：

$GSETUP --check

保存 Client Secret：

$GSETUP --client-secret \
  "$HOME/Downloads/client_secret_xxx.json"

產生 OAuth URL：

$GSETUP --auth-url

開啟 URL 並授權。

瀏覽器最後可能跳到：

http://localhost:1/...

即使頁面顯示連線失敗，也請複製地址列中的完整 URL。

交換 Token：

$GSETUP --auth-code \
  'http://localhost:1/?code=...&scope=...&state=...'

驗證：

$GSETUP --check
$GSETUP --check-live

14.4 現行 `setup.py` 實際支援參數

目前程式碼支援：

--check
--check-live
--client-secret
--auth-url
--auth-code
--revoke
--install-deps

部分文件曾出現：

--services
--format

但現行 setup.py 沒有這兩個參數。若遇到：

unrecognized arguments: --services ... --format json

請移除它們。

14.5 Token 路徑

~/.hermes/google_token.json
~/.hermes/google_client_secret.json
~/.hermes/google_oauth_pending.json

撤銷：

$GSETUP --revoke

14.6 Google API 指令

GAPI="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/google_api.py"

列出 Calendar：

$GAPI calendar list

指定日期：

$GAPI calendar list \
  --start 2026-06-28T00:00:00+08:00 \
  --end 2026-07-05T23:59:59+08:00

建立活動：

$GAPI calendar create \
  --summary "Hermes 測試行程" \
  --start 2026-06-30T15:00:00+08:00 \
  --end 2026-06-30T16:00:00+08:00

加入地點：

$GAPI calendar create \
  --summary "午餐" \
  --start 2026-06-30T12:00:00+08:00 \
  --end 2026-06-30T13:00:00+08:00 \
  --location "Taipei"

邀請參與者：

$GAPI calendar create \
  --summary "Project Review" \
  --start 2026-06-30T14:00:00+08:00 \
  --end 2026-06-30T15:00:00+08:00 \
  --attendees "alice@example.com,bob@example.com"

刪除：

$GAPI calendar delete EVENT_ID

14.7 時區

時間應包含 Offset 或 Z：

2026-06-30T15:00:00+08:00
2026-06-30T07:00:00Z

避免：

2026-06-30T15:00:00

沒有時區的時間可能被當作 UTC。

14.8 自然語言

列出我未來七天的 Google Calendar 行程。

幫我在 2026 年 6 月 30 日下午 3 點到 4 點建立「Hermes 測試行程」，時區使用 Asia/Taipei。

找出明天下午有哪些空檔。

涉及新增、修改、刪除時，建議先讓 Hermes 顯示即將執行的內容。

15. Fallback Provider 與 Gemini 額度

15.1 觸發情況

HTTP 429。
500／502／503。
401／403。
Connection Error。
空白或無效 Response。
Provider 暫時不可用。

15.2 設定

hermes fallback

新增：

hermes fallback add

查看：

hermes fallback list

移除：

hermes fallback remove

清除：

hermes fallback clear

15.3 YAML 範例

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
  - provider: nous
    model: nous-hermes-3

自架：

fallback_providers:
  - provider: custom
    model: my-local-model
    base_url: http://localhost:8000/v1
    key_env: LOCAL_API_KEY

15.4 Gemini 429 建議處理

稍後重試。
/new 建立新 Session。
/compress 降低 Context。
關閉不需要的 Toolsets。
設定不同 Provider 的 Fallback。
降低主 Provider Retry 次數。

hermes config set agent.api_max_retries 0

15.5 同一 Project 多把 API Key

Gemini 額度通常以 Project 為單位計算，因此同一 Google Cloud Project 的另一把 API Key 不一定能繞過限制。

較可靠的方式：

不同 Provider。
不同計費 Project。
升級額度。
減少 Prompt 與 Tool Schema Token。

15.6 Fallback 通常是 Turn-scoped

本次訊息主模型失敗後可切到備援；下一則訊息仍會重新嘗試主模型，不會自動永久改掉整個 Session。

16. Context Compression 與 Token 控制

16.1 設定範例

compression:
  enabled: true
  threshold: 0.50
  target_ratio: 0.20
  protect_last_n: 20
  protect_first_n: 3

含義：

Context 使用達 50% 時開始壓縮。
將舊訊息摘要。
保護最近 20 則訊息。
保護最前面 3 則重要訊息。

16.2 指定壓縮模型

auxiliary:
  compression:
    provider: gemini
    model: YOUR_FAST_GEMINI_MODEL

壓縮模型的 Context Window 不應小於主模型需要處理的內容。

16.3 Gemini Free Tier 較積極設定

compression:
  enabled: true
  threshold: 0.25
  target_ratio: 0.10
  protect_last_n: 10
  protect_first_n: 0

優點：

較早壓縮。
減少輸入 Token。

代價：

舊細節更容易只剩摘要。

16.4 手動操作

/usage
/compress
/new

判斷原則：

同一任務仍在持續 → /compress
已切換到另一個主題 → /new
要找以前內容 → Session Search

16.5 檢查 Prompt 大小

hermes prompt-size

只啟用必要工具：

hermes chat --toolsets file,terminal

17. Profiles

17.1 Profile 隔離內容

每個 Profile 可有自己的：

Config。
API Keys。
SOUL。
Memory。
Sessions。
Skills。
Cron。
Gateway。
state.db。

17.2 建立

hermes profile create coder
coder setup
coder chat

17.3 Clone

hermes profile create work --clone

通常會複製：

Config。
.env。
SOUL。
Skills。

但建立新的 Session 與 Memory。

完整複製：

hermes profile create backup --clone-all

17.4 指定與切換

hermes -p coder chat

設定預設：

hermes profile use coder

切回：

hermes profile use default

17.5 Profile Gateway

coder gateway install
coder gateway start
coder gateway status

不同 Profile 建議使用不同 Telegram Bot Token。

17.6 Profile 不是 Sandbox

Profile 只隔離 Hermes 資料，不能限制 Agent 存取檔案。

需要真正隔離時：

hermes config set terminal.backend docker

也可以限制工作目錄：

coder config set terminal.cwd /absolute/project/path

18. 安全設定

18.1 Approval Mode

approvals:
  mode: manual
  timeout: 60
  cron_mode: deny

模式：

Mode	行為
`manual`	危險操作要求人工批准
`smart`	由輔助模型判斷風險
`off`	不要求批准，接近 YOLO

18.2 YOLO

hermes --yolo

或：

/yolo

會略過多數 Approval，不建議在真實工作環境使用。

適合的有限情境：

Disposable Docker。
可重建 CI。
無重要資料的測試環境。
已驗證的固定腳本。

18.3 Container Backend

hermes config set terminal.backend docker

或：

hermes setup terminal

18.4 Telegram Allowlist

TELEGRAM_ALLOWED_USERS=YOUR_ID

不要在有 Terminal 權限時使用：

TELEGRAM_ALLOWED_USERS=*

18.5 Security Audit

hermes security audit

CI 中：

hermes security audit --fail-on high

JSON：

hermes security audit --json

18.6 Checkpoints

hermes chat --checkpoints

查看：

hermes checkpoints

回復：

/rollback

19. 更新、備份與解除安裝

19.1 更新

hermes update --check

hermes update

更新前備份：

hermes update --backup

更新後：

hermes doctor
hermes gateway restart

多 Profile：

hermes gateway restart --all

19.2 備份

hermes backup

匯入：

hermes import BACKUP_FILE.zip

Profile：

hermes profile export coder

19.3 建議備份

~/.hermes/config.yaml
~/.hermes/.env
~/.hermes/SOUL.md
~/.hermes/memories/
~/.hermes/skills/
~/.hermes/cron/
~/.hermes/state.db

不要把以下內容提交到公開 GitHub：

.env
API Keys
Telegram Bot Token
Google OAuth Client Secret
google_token.json
完整 Hermes Backup

19.4 解除安裝

hermes uninstall

20. 常見問題排查

20.1 `hermes` 找不到

source ~/.zshrc
which hermes
echo $PATH

加入：

export PATH="$HOME/.local/bin:$PATH"

20.2 API Key 或 Provider 錯誤

hermes model
hermes doctor
hermes status --deep

20.3 Telegram 無回應

hermes gateway status
hermes logs

前景除錯：

hermes gateway stop
hermes gateway run

確認：

TELEGRAM_BOT_TOKEN
TELEGRAM_ALLOWED_USERS

20.4 Session 找不到

hermes sessions list
hermes sessions repair

確認 Profile：

hermes profile

20.5 SOUL 修改沒生效

/new

20.6 Skill 沒出現

hermes skills list
hermes skills audit

檢查：

~/.hermes/skills/<category>/<skill>/SKILL.md

20.7 Google Calendar 未授權

GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"

$GSETUP --check
$GSETUP --auth-url

20.8 Google API 403

可能原因：

對應 API 未啟用。
OAuth App 是 Testing，但使用者不在 Test Users。
授權 Scope 不完整。
OAuth Client 被停用。

20.9 Token 使用過高

/usage
/compress
/new

再檢查：

hermes tools
hermes prompt-size

20.10 排除個人設定干擾

hermes chat \
  --ignore-user-config \
  --ignore-rules \
  -q "Test"

安全模式：

hermes chat --safe-mode -q "Test"

21. 推薦日常工作流

適合：

macOS
Gemini API
Telegram
Google Calendar
Obsidian Digital Garden

21.1 開機後

hermes gateway status

未啟動：

hermes gateway start

21.2 進入專案

cd ~/projects/PROJECT_NAME
hermes --tui

專案根目錄放置：

AGENTS.md

21.3 新主題

/new project-name

21.4 Context 變長

/usage
/compress

21.5 Gemini 不穩

hermes fallback list
hermes config set agent.api_max_retries 0

21.6 Telegram 遠端任務

列出我明天的 Google Calendar 行程。

檢查指定 GitHub Repository 的最新 CI 狀態。

發布所有標記為 dg-publish: true 的 Obsidian Digital Garden 文件。

21.7 每週維護

hermes update --backup
hermes doctor
hermes security audit
hermes skills check
hermes sessions prune --older-than 90

21.8 每月備份

hermes backup

22. 指令速查表

安裝與設定

hermes setup
hermes setup --portal
hermes model
hermes tools
hermes doctor
hermes status

Chat

hermes
hermes --tui
hermes -c
hermes -r "SESSION"
hermes chat -q "PROMPT"
hermes -z "PROMPT"

Tools

hermes tools
hermes chat --toolsets web,terminal,file
hermes prompt-size

Sessions

hermes sessions list
hermes sessions export backup.jsonl
hermes sessions rename ID "TITLE"
hermes sessions delete ID
hermes sessions prune --older-than 90

Skills

hermes skills list
hermes skills browse
hermes skills search QUERY
hermes skills inspect SLUG
hermes skills install SLUG
hermes skills check
hermes skills update
hermes skills audit
hermes skills uninstall NAME

Gateway

hermes gateway setup
hermes gateway install
hermes gateway start
hermes gateway status
hermes gateway restart
hermes gateway stop
hermes gateway run

hermes send --list telegram
hermes send --to telegram "MESSAGE"
hermes send --to telegram:CHAT_ID "MESSAGE"

Cron

hermes cron create "every 1h" "TASK"
hermes cron list
hermes cron status
hermes cron pause ID
hermes cron resume ID
hermes cron run ID
hermes cron edit ID --schedule "every 4h"
hermes cron remove ID

Fallback

hermes fallback
hermes fallback add
hermes fallback list
hermes fallback remove
hermes fallback clear

Profile

hermes profile create coder
coder setup
coder chat
hermes profile list
hermes profile use coder
hermes profile use default

維護

hermes update --check
hermes update --backup
hermes backup
hermes logs
hermes security audit
hermes uninstall

Slash Commands

/help
/new
/compress
/usage
/status
/model
/tools
/skills
/cron
/title
/retry
/undo
/stop
/save
/whoami
/quit