전체 문서 목록
ESSENTIALS

Hermes Agent 필수판 — 꼭 알아야 할 것만

완전 가이드에서 각 장의 “🚩 처음이라면 이것만” 소절만 모으고 🔧 개발자용 세부는 뺀 판입니다. 처음 쓰는 사람이 이해하고 바로 활용하는 데 필요한 범위입니다. 모르는 말은 용어표, 처음부터 따라 하려면 활용편, 모든 세부는 완전 가이드를 보세요.

CHAPTER 01

설치와 첫 대화

Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트)를 내 컴퓨터에 설치하고, 두뇌가 될 모델을 고르고, 첫 대화가 되는지 확인한 다음, 그 대화를 다시 이어 하는 데까지 갑니다. 공식 문서는 설치를 “2분 안에 끝난다”고 소개하고, 빠른 시작 문서는 “설치는 됐는데 아무것도 안 된다”는 상황을 피하는 순서를 알려 줍니다. 이 장은 그 순서를 그대로 따릅니다.

설치하기 — 두 가지 방법

Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 이하 Hermes)를 내 컴퓨터에 들이는 방법은 크게 둘입니다. Desktop 패키지를 내려받아 실행하거나, 터미널(글자로 명령을 입력하는 창)에 명령 한 줄을 붙여 넣습니다. 빠른 시작 문서는 macOS·Windows 라면 Desktop 설치 프로그램을 추천합니다. 명령줄 프로그램(CLI — 터미널에서 글자로 쓰는 프로그램)과 데스크톱 앱을 한 번에 쉽게 설치해 주기 때문입니다.

아주 쉽게 말하면 가구를 들이는 두 가지 방법과 비슷합니다. Desktop 패키지는 다 조립된 가구를 배달받는 것이라, 받아서 놓으면 끝입니다. 명령 한 줄은 조립 기사를 부르는 것입니다. 기사(설치 스크립트)가 부품을 가져와 내 집에서 조립해 줍니다. 어느 쪽이든 끝나면 hermes 라는 명령으로 대화를 시작합니다.
방법 A — Desktop 패키지 (추천) macOS · Windows — 내려받아 실행 데스크톱 앱 hermes 명령 CLI 에이전트·Python·필요한 부품이 한 꾸러미에 처음 켤 때 따로 조립(빌드)하지 않음 방법 B — 명령 한 줄 Linux · macOS · WSL2 · Windows — 터미널에 붙여 넣기 hermes 명령 CLI 만 설치 데스크톱 앱 원하면 나중에 설치 스크립트가 소스를 받아 내 컴퓨터에서 준비 나중에 hermes desktop 을 입력하면 데스크톱 앱도 설치·실행 터미널에서 hermes 입력 → 대화 시작
두 방법의 차이는 “누가 조립하느냐”입니다. A는 조립된 꾸러미를 받고, B는 스크립트가 내 컴퓨터에서 준비합니다.

내 환경에 맞는 탭을 골라 따라 합니다.

Hermes 웹사이트에서 내 플랫폼에 맞는 패키지를 내려받습니다.

플랫폼하는 일
macOSDMG(macOS 설치용 묶음 파일)를 열고 Hermes.app 을 Applications(응용 프로그램) 폴더로 복사합니다.
Windows내려받은 .appinstaller 파일을 Windows App Installer 로 엽니다. 서명된 MSIX 묶음이 설치되고, 업데이트를 받아 올 곳도 함께 기록됩니다.

패키지 안에 에이전트, Python, 지원되는 부품, 미리 만들어 둔 화면이 들어 있어서 처음 켤 때 따로 조립하지 않습니다. 다만 제공자에 접속하거나 선택 기능을 연결할 때는 인터넷이 필요할 수 있습니다.

Intel Mac 은 지원 대상이 아닙니다 macOS 설치 프로그램은 Apple Silicon 전용입니다. 원문은 x86(Intel) 프로세서의 macOS 를 지원 플랫폼이 아니라고 적습니다.

데스크톱 앱의 화면 구성은 받은 원문에 설명이 없습니다. 원문은 「Hermes Desktop」 쪽을 보라고만 적습니다(이 가이드는 다루지 않음).

Hermes Desktop 없이 명령줄만 설치하는 방법입니다. 터미널에 아래 한 줄을 붙여 넣고 Enter 를 누릅니다.

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

뜻: 설치 스크립트(해야 할 명령을 순서대로 적어 둔 파일)를 내려받아 바로 실행합니다. Linux, macOS, WSL2(Windows 안에서 Linux 를 돌리는 기능)에서 씁니다.

끝나면 셸(터미널 안에서 명령을 받아 실행하는 프로그램)이 설정을 다시 읽게 한 뒤 대화를 시작합니다.

source ~/.bashrc   # or: source ~/.zshrc
hermes             # Start chatting!

뜻: 첫 줄은 셸 설정을 다시 읽습니다(쓰는 셸에 따라 ~/.bashrc 나 ~/.zshrc 가운데 하나). 둘째 줄이 대화를 시작합니다. ~ 는 내 홈 폴더를 뜻합니다.

Windows 에서 WSL2 없이 바로 설치할 때는 PowerShell 에서 아래 명령을 실행합니다.

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

뜻: Windows 용 설치 스크립트를 내려받아 실행합니다.

받은 원문에 Windows 내용은 이 명령과 옵션 이름, 설치 위치 정도뿐입니다. 이 가이드는 macOS·Linux 터미널을 기준으로 설명합니다.

aarch64 Android 기기에서는 Termux APT 패키지를 씁니다. 서명된 저장소를 먼저 설정한 다음 pkg install hermes-agent 를 실행합니다.

위의 데스크톱·서버용 스크립트는 Termux 설치 방법이 아닙니다. 저장소를 설정하는 절차는 별도의 Termux APT 안내에 있는데, 받은 원문에는 들어 있지 않습니다(이 가이드는 다루지 않음).

명령 한 줄로 설치할 때 실제로 겪는 흐름은 다음과 같습니다.

① 설치 명령을 붙여 넣습니다

위 탭의 한 줄을 붙여 넣고 Enter 를 누릅니다. 스크립트가 소스를 받아 오고 필요한 프로그램을 준비하는 동안 단계마다 상태가 한 줄씩 보입니다. 자세한 기록은 Hermes 데이터 폴더 아래 logs/install.log 에 쌓이고, 어떤 단계가 실패하면 그 기록의 마지막 몇 줄과 파일 위치를 알려 줍니다.

② 이어지는 설정 질문에 답합니다

사람이 직접 실행한 경우, 스크립트는 실행 파일을 만들고 데이터 폴더를 준비한 뒤 설정(setup)과 게이트웨이(메신저와 Hermes 를 이어 주는 프로그램) 구성 단계까지 이어서 띄웁니다. 여기서 고르는 제공자는 다음 추천 소절에서 설명합니다.

③ 셸 설정을 다시 읽고 hermes 를 입력합니다

source ~/.bashrc(또는 source ~/.zshrc)를 실행한 뒤 hermes 를 입력합니다. hermes: command not found(그런 명령을 찾을 수 없다는 뜻)가 나오면 셸 설정을 다시 읽지 않았거나 PATH(명령을 찾아보는 폴더 목록)에 문제가 있는 것입니다.

설치가 끝난 뒤 설정을 하나씩 고칠 때는 전용 명령을 씁니다. hermes model(제공자(AI 모델을 빌려주는 서비스)와 모델 고르기), hermes tools(켤 도구 정하기), hermes gateway setup(메신저 플랫폼 연결), hermes config set·hermes config get(설정 값 하나를 넣기·보기), 그리고 전부를 한 번에 정하는 설정 마법사 hermes setup 입니다. 지금 외울 필요는 없습니다.

명령줄만 설치했더라도 나중에 hermes desktop 한 줄이면 Hermes Desktop 을 설치하고 실행합니다.

이미 다른 컴퓨터에서 Hermes 를 쓰고 있다면 설정을 처음부터 다시 만들 필요가 없습니다. hermes import 로 전체 백업을 되살리거나, hermes profile import 로 에이전트 하나만 옮겨 올 수 있습니다. 프로필 내보내기(profile export)는 일부러 인증 정보를 빼므로 전체 백업이 아닙니다. 절차는 공식 문서 참고(이 가이드는 다루지 않음).

제공자와 모델 고르기 — 가장 중요한 단계

원문이 “가장 중요한 설정 단계”라고 부르는 곳입니다. Hermes 는 도구(tool — 에이전트가 쓰는 기능 하나. 터미널 실행, 파일 읽기, 웹 검색 등)를 써서 일하는 손발이고, 무엇을 할지 생각하는 두뇌는 모델(에이전트의 두뇌 역할을 하는 AI — Claude, GPT, Gemini 등)입니다. 모델은 제공자(provider — AI 모델을 빌려주는 서비스)를 통해 빌려 씁니다. 제공자를 정하지 않으면 Hermes 는 답을 만들 두뇌가 없는 상태이므로, 어느 제공자의 어떤 모델을 쓸지 정해 주는 일이 먼저입니다.

생각은 모델이 하고, Hermes 는 그 답대로 움직입니다 Hermes 내 컴퓨터에서 돎 손발 — 도구를 써서 일함 제공자 provider — 모델을 빌려주는 서비스 Nous Portal · OpenRouter … 모델 두뇌 — 생각하고 답을 씀 Claude · GPT · Gemini … 질문 질문 답 답 hermes model 로 고릅니다 — 언제든 다시 바꿀 수 있습니다
제공자는 모델로 가는 창구입니다. 창구를 정하고 그 안에서 모델을 고릅니다.

고르는 명령은 하나입니다. 터미널(글자로 명령을 입력하는 창)에 입력하면 질문에 답하며 따라가는 방식으로 진행됩니다.

hermes model

뜻: 제공자와 모델을 고르는 화면을 엽니다.

어떤 길로 갈지는 내 사정에 따라 셋으로 나뉩니다.

새로 설치한 상태라면 아래 한 줄이 가장 빠릅니다.

hermes setup --portal

뜻: 로그인하고, Nous 를 제공자로 정하고, Tool Gateway 를 켜는 일을 명령 하나로 끝냅니다.

구독 하나에 들어 있는 것설명
300개가 넘는 모델구독 하나로 씁니다
Tool Gateway웹 검색, 이미지 생성, TTS(글을 음성으로 읽어 주는 기능), 클라우드 브라우저. 도구마다 키를 따로 챙길 필요가 없습니다

Tool Gateway 는 Nous Portal 구독에 딸린 도구 묶음입니다. 메신저를 잇는 “게이트웨이”와 다른 것이라 영어 이름 그대로 적습니다.

hermes model 을 실행해 그 제공자를 고르고, 아래 표의 방법대로 로그인하거나 API 키(제공자가 내주는 긴 비밀 문자열 — 내 계정임을 증명)를 넣습니다. 설정을 저장하면 바로 대화를 시작할 수 있습니다.

API 키를 발급받는 절차는 받은 원문에 없습니다.

새로 설치한 상태에서 hermes setup 을 실행하면 세 가지 방식 가운데 하나를 고르게 됩니다.

방식무엇을 하나이런 사람에게
Quick Setup
(Nous Portal)
OAuth(브라우저에서 로그인해 허락하는 방식)로 로그인하므로 관리할 API 키가 없습니다. 모델과 Tool Gateway 도구를 함께 설정하고, 요금은 Nous Portal 구독으로 청구됩니다.원문이 추천하는 빠른 길
Full Setup제공자, 도구, 옵션을 하나하나 직접 거칩니다. 내 키를 가져와 씁니다.쓸 제공자와 키가 이미 있는 사람
Blank Slate에이전트를 돌리는 데 꼭 필요한 최소한만 켜고 나머지는 모두 끈 채 시작합니다.필요한 것만 골라 켜서 전부 내 손으로 관리하려는 사람

OpenClaw, Claude Code, Codex CLI, Cursor 를 쓰다가 왔다면, 새로 실행한 hermes setup 이 내 컴퓨터에서 그것을 찾아내어 먼저 기존 설정을 가져올지 묻습니다(이를 위해 agent-importers 플러그인을 설치합니다 — 공식 문서 Import from Other Agents 쪽).

원문은 “처음 고르기 좋은 곳”을 긴 표로 싣습니다. 그 가운데 앞의 네 곳과, 직접 주소를 지정하는 방식을 옮깁니다.

제공자어떤 곳인가설정 방법
Nous Portal구독형. 따로 설정할 것이 없습니다hermes model 에서 OAuth 로그인
OpenAI CodexChatGPT 또는 Codex 구독으로 Codex 모델을 씁니다hermes model → ChatGPT or Codex Subscription 에서 기기 코드 인증
AnthropicClaude 모델을 직접 씁니다. Max 요금제 + 추가 사용 크레딧(OAuth), 또는 쓴 만큼 내는 API 키hermes model → OAuth 로그인(Max + 추가 크레딧 필요), 또는 Anthropic API 키
OpenRouter여러 제공자의 많은 모델로 이어 줍니다API 키 입력
Custom EndpointVLLM, SGLang, Ollama 등 OpenAI 호환 API 라면 무엇이든접속 주소(base URL) + API 키
모델의 최소 조건 — 컨텍스트 64K 토큰 Hermes 는 컨텍스트(문맥 창 — 모델이 한 번에 기억하며 볼 수 있는 글의 양)가 최소 64,000 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)인 모델이 필요합니다. 그보다 작은 모델은 여러 단계에 걸쳐 도구를 부르는 일에 필요한 작업 기억을 유지하지 못해 시작할 때 거부됩니다. 서비스로 제공되는 모델 대부분(Claude, GPT, Gemini, Qwen, DeepSeek)은 이 조건을 쉽게 넘습니다. 내 컴퓨터에서 직접 모델을 돌린다면 컨텍스트 크기를 64K 이상으로 맞춥니다(예: llama.cpp 는 --ctx-size 65536, Ollama 는 -c 65536).
처음이라면 제공자를 하나 고르고, 바꿔야 할 이유를 알기 전에는 기본값을 그대로 둡니다. 제공자는 hermes model 로 언제든 바꿀 수 있어 한곳에 묶이지 않습니다. 제공자 전체 목록과 환경 변수, 설정 절차는 공식 문서 Providers(AI Providers) 쪽에 있습니다(이 가이드는 다루지 않음).

첫 대화 — 되는지 확인하기

제공자(AI 모델을 빌려주는 서비스)를 정했으면 대화를 시작합니다. 터미널(글자로 명령을 입력하는 창)에 아래 둘 가운데 하나를 입력합니다.

hermes            # classic CLI
hermes --tui      # modern TUI (recommended)

뜻: 첫 줄은 기존 화면으로, 둘째 줄은 새 화면으로 대화를 엽니다. 원문은 둘째를 추천합니다.

명령열리는 화면
hermes클래식 CLI(터미널에서 글자로 쓰는 프로그램 화면) — prompt_toolkit 으로 만든 기존 화면
hermes --tui새 TUI(새 터미널 화면) — 겹쳐 뜨는 창, 마우스로 고르기, 일하는 중에도 막히지 않는 입력

두 화면은 세션(대화 한 묶음), 슬래시 명령(입력 칸에 / 로 시작해 넣는 명령), 설정을 함께 씁니다. 그러니 둘 다 열어 보고 편한 쪽을 쓰면 됩니다.

터미널 — hermes
❯ Check my current directory and tell me what looks like the main project file.

단순하게 흉내 낸 그림입니다. 원문은 “모델, 쓸 수 있는 도구, 스킬이 담긴 환영 배너가 보인다”고만 적습니다.

첫 질문은 구체적이고, 맞았는지 확인하기 쉬운 것으로 고릅니다. 원문의 예 세 가지입니다. 영어 그대로 입력해도 되고, 뜻을 참고해 내 상황에 맞게 바꿔도 됩니다.

입력할 글 (원문)뜻
Summarize this repo in 5 bullets and tell me what the main entrypoint is.이 저장소(repo — 프로젝트 파일이 담긴 폴더)를 다섯 줄로 요약하고, 프로그램이 시작되는 중심 파일이 무엇인지 알려 줘.
Check my current directory and tell me what looks like the main project file.지금 있는 폴더를 살펴보고, 중심이 되는 프로젝트 파일로 보이는 것을 알려 줘.
Help me set up a clean GitHub PR workflow for this codebase.이 코드 묶음에 맞는 깔끔한 GitHub PR(변경을 검토해 달라고 올리는 요청) 작업 흐름을 만들도록 도와줘.

답이 왔다면 아래 네 가지를 확인합니다. 원문이 적은 “성공한 모습”입니다.

첫 대화가 성공한 모습 — 네 가지 ✓ 배너에 모델 표시 내가 고른 모델·제공자가 배너에 보임 ✓ 오류 없이 답함 Hermes 가 오류 없이 답을 돌려줌 ✓ 필요하면 도구 사용 터미널 · 파일 읽기 · 웹 검색 ✓ 대화가 이어짐 한 번 넘게 주고받아도 정상으로 계속됨
네 개가 모두 맞으면, 원문 표현대로 “가장 어려운 부분은 지난 것”입니다.

하나라도 어긋나면 기능을 더 얹지 말고 먼저 고칩니다. 증상별로 볼 곳은 자주 겪는 실패에, 따라 하는 절차는 활용편 「시작 전 준비」에 있습니다.

이어 하기 — 세션이 남는지 확인

다음으로 넘어가기 전에 한 가지를 더 확인합니다. 방금 한 대화로 돌아올 수 있는지입니다. Hermes 는 대화를 세션(대화 한 묶음 — 시작부터 끝까지의 기록)으로 남겨 두고, 다음에 그 세션을 다시 열어 이어 갈 수 있습니다.

hermes --continue    # Resume the most recent session
hermes -c            # Short form

뜻: 가장 최근 세션을 이어서 엽니다. 둘째 줄은 같은 명령의 짧은 형태입니다.

첫 대화 세션이 시작됨 Hermes 를 닫음 대화를 마침 hermes --continue 방금 그 세션으로 돌아옴 저장된 세션 돌아오지 않으면 — 같은 프로필인지, 세션이 실제로 저장됐는지 확인
세션은 Hermes 를 닫아도 남고, hermes --continue 가 가장 최근 것을 다시 엽니다.

이 명령을 입력하면 방금 나눈 그 세션으로 돌아와야 합니다. 돌아오지 않는다면 원문이 일러 주는 두 가지를 확인합니다.

확인할 것설명
같은 프로필인가프로필(profile — 설정·기억·세션을 따로 쓰는 별도 Hermes 환경)을 바꾼 것이 원인일 수 있습니다.
세션이 실제로 저장됐는가hermes sessions list(세션 목록 보기)로 확인합니다.
왜 지금 확인하나요 원문은 이 확인이 나중에 설정을 여럿 쓰거나 컴퓨터를 여러 대 오갈 때 중요해진다고 적습니다. 세션을 더 다루는 법은 2장 「세션」과 「이어 하기」에서 다룹니다.
한눈에 정리
  • 순서는 설치 → 제공자 → 첫 대화 → 이어 하기. 대화 한 번이 되기 전에는 기능을 더 얹지 않습니다.
  • 설치는 Desktop 패키지(macOS·Windows, 추천)나 터미널 명령 한 줄 가운데 하나로 합니다. macOS 설치 프로그램은 Apple Silicon 전용입니다.
  • 제공자는 hermes model 로 고르고 언제든 바꿀 수 있습니다. 가장 쉬운 길은 hermes setup --portal 입니다. 모델은 컨텍스트가 최소 64K 토큰이어야 합니다.
  • 비밀 값은 ~/.hermes/.env, 그 밖의 설정은 ~/.hermes/config.yaml 에 있습니다. hermes config set 으로 넣으면 맞는 파일로 자동으로 갑니다.
  • hermes 나 hermes --tui 로 시작합니다. 성공 기준은 배너의 모델, 오류 없는 답, 도구 사용, 이어지는 대화입니다.
  • hermes --continue(hermes -c)로 방금 세션에 돌아오는지 확인합니다.
  • 막히면 증상 표를 보고, 모르겠으면 hermes doctor 부터 복구 순서 여섯 단계를 차례로 돌립니다.

이 장의 나머지 소절과 🔧 세부는 완전 가이드 1장에 있습니다.

CHAPTER 02

터미널에서 대화하기 — CLI 와 세션

Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트)와 가장 기본적으로 만나는 곳은 터미널(글자로 명령을 입력하는 창)입니다. 이 장에서는 대화 화면을 여는 법, 화면 읽는 법, 슬래시 명령(입력 칸에 / 로 시작해 넣는 명령)과 단축키, 일하는 도중에 방향을 바꾸는 법을 익히고, 대화가 세션(대화 한 묶음)으로 저장되어 다시 이어지고·찾아지고·정리되는 방식을 살펴봅니다.

CLI 실행하기 — hermes 한 줄로 시작

Hermes 의 CLI(터미널에서 글자로 쓰는 프로그램 화면)는 웹 페이지가 아니라 터미널 안에서 열리는 대화 화면입니다. 원문은 이 화면이 여러 줄 입력, 슬래시 명령 자동 완성, 대화 기록, 도중에 끼어들어 방향 바꾸기, 도구(tool — 에이전트가 쓰는 기능 하나. 터미널 실행·파일 읽기·웹 검색 등)가 내는 결과를 실시간으로 보여 주기를 갖췄다고 소개합니다. AI 에이전트(말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)에게 일을 시키는 창구인 셈입니다.

여는 방법은 터미널에 hermes 라고 입력하고 Enter 를 누르는 것이 전부입니다. 처음 쓰는 컴퓨터라면 먼저 hermes setup --portal 한 줄로 준비를 마쳐야 합니다 — 1장 설치와 제공자 고르기를 보세요.

아주 쉽게 말하면 메신저 대화방을 터미널 안에 연다고 생각하면 됩니다. 아래 칸에 글을 쓰고 Enter 를 누르면 Hermes 가 답합니다. 다만 상대가 말만 하는 것이 아니라, 내 컴퓨터에서 파일을 읽고 명령을 실행하며 일을 해 줍니다.
대화형 (기본) — hermes 나 Hermes 메시지 답 · 한 일 묻고 답하기를 계속 주고받습니다 앞에서 한 말을 기억한 채로 이어집니다 Ctrl+D 로 나갈 때까지 열려 있습니다 한 번 묻기 — hermes chat -q "…" 질문 Hermes 답 출력 답 하나를 받고 바로 끝납니다 대화 화면이 열리지 않습니다 (비대화형) 간단한 질문이나 자동화에 씁니다
CLI 를 쓰는 두 가지 방식. 처음에는 왼쪽(대화형)만 알아도 충분합니다.

시작할 때 뒤에 옵션을 붙이면 모델(에이전트의 두뇌 역할을 하는 AI)이나 제공자(provider — AI 모델을 빌려주는 서비스), 툴셋(toolset — 도구 꾸러미)을 골라서 열 수 있습니다. 자주 쓰는 것만 추리면 다음과 같습니다.

입력뜻
hermes대화형 세션을 시작합니다(기본).
hermes chat -q "Hello"한 번만 묻고 답을 받은 뒤 끝냅니다.
hermes chat --model "anthropic/claude-sonnet-4"쓸 모델을 정해서 엽니다.
hermes chat --provider nous제공자를 정해서 엽니다(nous = Nous Portal, openrouter = OpenRouter).
hermes chat --toolsets "web,terminal,skills"쓸 툴셋을 정해서 엽니다(4장).
hermes --continue가장 최근 세션(대화 한 묶음)을 이어 합니다(이어 하기).
시작 옵션은 그 세션에 고정됩니다 작업 폴더와 --model·--provider·--toolsets 같은 시작 옵션은 세션을 만들 때 그 세션에 고정됩니다. 이어 하기를 하면서 다른 값으로 바꿀 수는 없습니다. 대화 도중에 모델을 바꾸려면 슬래시 명령 /model 을 씁니다.
새 화면 TUI 도 있습니다 Hermes 에는 hermes --tui 로 여는 TUI(새 터미널 화면)도 들어 있습니다. 원문은 겹쳐 뜨는 창, 마우스로 고르기, 입력을 막지 않는 화면을 갖췄다고만 소개하고 공식 문서 TUI 쪽을 가리킵니다(이 가이드는 다루지 않음). 이 장은 hermes 로 여는 기본 화면(원문 표현으로 classic CLI)을 기준으로 설명합니다.

슬래시 명령 — / 로 시작하는 명령

슬래시 명령은 대화 입력 칸에 / 로 시작해 넣는 명령입니다. Hermes 에게 일을 시키는 말이 아니라 Hermes 프로그램 자체를 조작하는 버튼에 가깝습니다. 입력 칸에 / 만 쳐도 쓸 수 있는 명령이 자동 완성 목록으로 뜨고, Tab 으로 완성합니다. 대소문자는 가리지 않습니다(/HELP 와 /help 는 같습니다).

입력 칸에 / 를 쳤을 때 (흉내)
❯ /▍
   /help      Show command help
   /model     Show or change the current model
   /tools     List currently available tools
   /title     Name the current session
   …

자동 완성 목록의 실제 모양은 원문에 그림이 없어, 원문 표의 명령과 설명으로 흉내 낸 것입니다.

원문이 “자주 쓰는 예”로 꼽은 명령입니다. 처음에는 위의 다섯 개만 기억해도 됩니다.

명령하는 일
/help명령 도움말을 보여 줍니다.
/model지금 모델을 보여 주거나 바꿉니다.
/tools지금 쓸 수 있는 도구 목록.
/title My Session지금 세션에 이름을 붙입니다(이름 붙이기).
/sessions세션 고르기 화면을 엽니다. 글자를 쳐서 거르고, 화살표로 고르고, Enter 로 이어 합니다.
/status세션 정보(모델·프로필(설정·기억·세션을 따로 쓰는 별도 Hermes 환경)·토큰·시간)와 최근 요약(턴 수, 많이 쓴 도구, 손댄 파일, 마지막 질문과 답). 내 컴퓨터에서만 계산하며 모델을 부르지 않습니다.
/context [all]컨텍스트를 무엇이 얼마나 차지하는지 그림과 표로(시스템 프롬프트·도구·스킬·기억·대화·남은 공간). all 을 붙이면 스킬·툴셋별로도.
/bg <prompt>따로 떨어진 백그라운드 세션에서 일을 시킵니다(백그라운드 세션).
/btw <question>하던 일을 끊지 않고, 지금 대화에 대해 곁가지 질문을 합니다.
/skills browseSkills Hub 와 공식 선택 스킬을 둘러봅니다(6장).
/reasoning high생각을 더 깊이 하도록 올립니다.

슬래시 명령은 세 갈래에서 옵니다.

① 기본 명령

Hermes 에 처음부터 들어 있는 명령. 위 표가 그 일부입니다.

② 스킬 명령

~/.hermes/skills/(~ 는 내 홈 폴더)에 설치된 스킬(일하는 방법을 적은 설명서)은 모두 자동으로 슬래시 명령이 됩니다. 스킬 이름이 곧 명령 이름입니다(6장).

③ 빠른 명령

quick commands — 내가 설정 파일에 정해 두는 명령. 모델을 부르지 않고 정해 둔 셸 명령을 바로 실행합니다.

스킬 명령은 뒤에 시킬 일을 이어 적습니다. 이름만 넣으면 스킬을 불러온 뒤 Hermes 가 무엇이 필요한지 되묻습니다.

/excalidraw sketch the request flow for our API
/github-pr-workflow create a PR for the auth refactor
/excalidraw

뜻: “우리 API 의 요청 흐름을 스케치해 줘” / “인증 리팩터링의 PR 을 만들어 줘” / (이름만 — 무엇을 할지 Hermes 가 물어봄)

Unsupported gateway CLI command; use /help 가 나오면 원문의 한 절은 기본 CLI 가 받는 슬래시 명령을 /stop·/approve·/answer·/discard·/branch·/model·/compress·/yolo·/help·/quit 로만 적고, 다른 절의 표는 /title·/sessions·/bg 등도 CLI 명령으로 소개합니다. 명령이 거절되면 /help 로 지금 쓸 수 있는 목록을 확인하고, 모든 슬래시 명령이 필요하면 원문 안내대로 hermes --tui 를 쓰세요.

일하는 도중에 방향 바꾸기 · 멈추기

Hermes 가 한참 일하는 것을 보다가 “아, 그게 아닌데” 싶을 때가 있습니다. 끝날 때까지 기다릴 필요가 없습니다. 일하는 중에도 입력 칸은 살아 있어서, 새 메시지를 쓰고 Enter 를 누르면 새 턴(내 메시지 하나에 Hermes 가 일하고 답하는 한 차례)을 시작하지 않고 지금 하던 턴의 방향을 바꿉니다.

  • 이미 끝낸 도구 작업과 화면에 보인 생각은 컨텍스트에 그대로 남습니다 — 처음부터 다시 하지 않습니다.
  • 돌고 있던 도구는 안전하게 끊을 수 있는 지점까지 간 뒤에 내 말이 적용됩니다.
  • 아예 그만두게 하려면 빈 입력 칸에서 Ctrl+C 를 누르거나 /stop 을 입력합니다. /stop 은 그 턴과 앞에서 돌던 작업을 취소합니다.

modern 화면에서는 일하는 동안 입력 칸에 type to redirect this turn · Tab queues it for after(입력하면 이번 턴의 방향을 바꿉니다 · Tab 은 끝난 뒤로 줄 세웁니다)라는 안내가 보입니다.

일하는 중에 Enter 를 눌렀을 때 내 메시지를 어떻게 다룰지는 세 가지 방식 가운데 고를 수 있습니다. 기본은 interrupt 입니다.

내가 새 메시지 + Enter interrupt (기본)지금 방향을 바꿉니다 일하는 중 내 말을 반영해 다시 진행 queue끝난 뒤 다음 차례로 일하는 중… 끝까지 마침 줄 서서 기다림 다음 턴: 내 메시지 steer멈추지 않고 전달 일하는 중… 계속 진행 다음 도구 호출이 끝난 뒤 내 말이 전달됨
세로 점선이 내가 Enter 를 누른 순간입니다. 방식에 따라 내 메시지가 언제 Hermes 에게 닿는지가 달라집니다.
방식Enter 를 누르면바꾸는 명령
interrupt (기본)지금 턴이 내 말을 반영해 다시 진행합니다. 오래 걸리는 터미널 명령(빌드 등)이 돌고 있었다면 죽이지 않고 뒤로 보내고(끝나면 알림), 내 메시지를 바로 읽습니다. 다른 도구는 먼저 끝냅니다./busy interrupt
queueHermes 가 지금 일을 끝낸 뒤 다음 턴으로 실행합니다./busy queue
steer끊지도, 새 턴을 만들지도 않고 지금 실행에 끼워 넣습니다. 다음 도구 호출 뒤에 Hermes 에게 닿습니다./busy steer

지금 방식은 /busy status 로 확인합니다. 방식과 상관없이 /queue <prompt> 로 다음 턴을 직접 줄 세울 수도 있습니다. 일하는 중에 처음 Enter 를 누르면 이 설정을 알려 주는 한 줄 안내가 한 번 나옵니다.

멈추기와 나가기는 다릅니다. 헷갈리기 쉬워 표로 정리합니다.

하고 싶은 것방법결과
방향만 바꾸기새 메시지 + Enter지금 턴이 내 말을 반영합니다.
이번 일 그만두기빈 입력 칸에서 Ctrl+C, 또는 /stop하던 일을 멈춥니다. 대화 화면은 그대로입니다.
화면에서 나가기Ctrl+DHermes 화면을 닫습니다. 돌고 있던 턴은 취소되지 않고 끝까지 진행되며, 나중에 hermes --resume 으로 답을 볼 수 있습니다.
강제로 끝내기Ctrl+C 를 2초 안에 두 번강제 종료.

세션이란 — 자동으로 저장되는 대화 한 묶음

세션은 대화 한 묶음입니다. Hermes 는 모든 대화를 따로 저장 버튼을 누르지 않아도 자동으로 세션으로 저장합니다. 터미널에서 한 대화든 Telegram·Discord·Slack 같은 메신저에서 한 대화든 마찬가지이고, 주고받은 메시지 전체가 남습니다. 덕분에 세 가지가 가능해집니다 — 어제 하던 대화를 이어 하기, 지난 대화들 속에서 찾기, 쌓인 기록을 관리하기.

아주 쉽게 말하면 대화 하나가 공책 한 권입니다. Hermes 는 대화가 시작되면 새 공책을 꺼내 오간 말을 모두 적고, 책장 한 곳에 꽂아 둡니다. 공책에 제목을 붙여 두면 나중에 꺼내기 쉽고, 꺼낸 공책 뒤에 이어서 쓸 수도 있습니다.
CLI터미널에서 한 대화 메신저Telegram · Discord · Slack … 그 밖예약 작업 · API … state.db~/.hermes/state.db — 모든 세션이 여기에 📓 refactoring auth 📓 my project #3 📓 (제목 없는 세션) 이어 하기hermes -c 찾기목록 · 검색 관리이름 · 내보내기 · 정리
어디서 한 대화든 내 컴퓨터의 한 파일(~/.hermes/state.db, ~ 는 내 홈 폴더)에 세션으로 쌓입니다. 예약 작업은 정해 둔 시간에 Hermes 가 혼자 실행하는 일입니다(7장).

세션 하나에 저장되는 것은 다음과 같습니다.

저장되는 것설명
세션 ID · 출처 · 사용자 ID세션마다 붙는 고유 번호와, 어디서(CLI·Telegram 등) 누가 시작했는지
세션 제목사람이 읽을 수 있는 이름. 서로 겹치지 않습니다.
모델과 설정 · 시스템 프롬프트그 대화에 쓴 모델, 그리고 Hermes 에게 주어진 기본 지시문의 그때 모습
메시지 기록 전체내 말, Hermes 의 답, 도구 호출과 그 결과
토큰 수 · 시각입력/출력 토큰 수, 시작·종료 시각
부모 세션 ID대화가 길어져 압축되며 새 세션으로 이어졌을 때, 어느 세션에서 왔는지

세션을 다루는 기본 동작은 넷입니다. 새 대화를 시작하려면 /new(이름을 붙여 /new payments-refactor 처럼 써도 됩니다), 대화가 길어지면 /compress 로 요약해 줄이고, 나갔다가 돌아오면 hermes -c 로 이어 하고, 오래된 세션은 필요할 때만 hermes sessions prune 으로 지웁니다. 압축은 지금 쓰는 컨텍스트를 줄일 뿐, 기록을 지워 주는 기능이 아닙니다.

일이 끝나면 /new 로 끊어 주세요 원문은 일이나 주제가 끝날 때마다 /new 로 새 세션을 시작하라고 권합니다. ① 기억(memory — 세션이 끝나도 남는 메모)은 세션이 시작될 때 불러오고 끝날 때 정리해 저장하므로, 끝나지 않는 세션에서는 “스스로 배우는” 장치가 거의 돌지 않습니다(5장). ② 대화가 길수록 매 턴 실어 보내는 앞부분이 커져 비용이 늡니다. 끊기 전에 “기억해 둘 만한 것은 기억해 줘” 하고 말해 두면 도움이 됩니다. 컴퓨터나 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)를 다시 시작하는 것은 끊는 것이 아닙니다 — 같은 세션이 이어집니다.
저장된 기록이 전부 매번 모델에게 가는 것은 아닙니다 매 턴 모델이 보는 것은 시스템 프롬프트, 지금 대화 창, 그 턴에 Hermes 가 일부러 넣는 내용입니다. 컨텍스트를 빨리 채우는 것은 그림 파일이 아니라 장황한 글(통째로 붙인 로그, 큰 도구 출력, 긴 변경 내역)이니, 큰 자료는 요약·파일 경로·필요한 부분만 주는 편이 좋습니다.
한눈에 정리
  • 터미널에 hermes 를 입력하면 대화 화면이 열립니다. hermes chat -q "…" 는 한 번만 묻고 끝냅니다.
  • 화면은 환영 배너·대화 영역·입력 칸·상태 줄로 이루어지고, 상태 줄의 컨텍스트 막대가 빨강(95% 이상)이 되면 /compress 나 /new 를 생각합니다.
  • 입력 칸에 / 를 치면 슬래시 명령 목록이 뜹니다. /help·/model·/title·/sessions 부터 익히세요.
  • 줄바꿈은 Alt+Enter 나 Ctrl+J. 줄을 ! 로 시작하면 모델을 거치지 않고 내가 직접 셸 명령을 실행합니다.
  • 일하는 중에도 새 메시지 + Enter 로 방향을 바꿀 수 있습니다. 멈추려면 Ctrl+C 나 /stop, 나가려면 Ctrl+D(돌던 턴은 계속됨).
  • 모든 대화는 세션으로 ~/.hermes/state.db 에 자동 저장됩니다. hermes -c 로 가장 최근 대화를, hermes -c "제목" 으로 이름 붙인 대화를 이어 합니다.
  • 제목은 자동으로 붙고 /title 로 바꿉니다. hermes sessions list 로 내가 찾고, Hermes 는 session_search 도구로 지난 대화를 스스로 찾아봅니다.
  • /bg 는 지금 대화와 분리된 백그라운드 세션에서 일을 시키고, 끝나면 결과 상자를 보여 줍니다.
  • 일이 끝나면 /new 로 세션을 끊어 주세요. 자동 정리는 기본으로 꺼져 있고, 지우는 것은 끝난 세션뿐입니다.

이 장의 나머지 소절과 🔧 세부는 완전 가이드 2장에 있습니다.

CHAPTER 03

설정 — 파일 · 모델 · 한도

Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 도구를 써서 내 대신 일을 해 주는 AI 프로그램)의 설정은 모두 ~/.hermes/ 폴더 한곳에 모여 있습니다. 이 장은 설정이 어디에 저장되고, 어떻게 바꾸고, 값이 여러 곳에 있을 때 무엇이 이기는지를 먼저 설명한 뒤, 꼭 알아 둘 한도·압축·보조 모델·화면 표시·터미널 백엔드를 차례로 봅니다. 나머지 설정은 장 끝의 접힌 표에 한 줄씩 정리했습니다.

설정이 저장되는 곳 — ~/.hermes/ 폴더

Hermes 는 모든 설정을 ~/.hermes/ 폴더에 둡니다. 맨 앞의 ~(물결표 — 내 홈 폴더, 곧 내 계정의 개인 폴더)는 “내 홈 폴더”를 뜻하므로, 내 홈 폴더 안의 .hermes 라는 폴더입니다. 원문은 “쉽게 찾을 수 있도록” 한곳에 모았다고 설명합니다. 설정뿐 아니라 기억, 스킬, 예약 작업, 기록도 이 폴더에 함께 있습니다.

아주 쉽게 말하면 책상 서랍 하나에 수첩과 작은 금고가 들어 있다고 생각해 보세요. 수첩(config.yaml)에는 “어떤 모델을 쓸지, 화면에 얼마나 자세히 보여 줄지” 같은, 남이 봐도 괜찮은 선택을 적습니다. 금고(.env)에는 열쇠에 해당하는 비밀 값만 넣습니다. Hermes 는 일할 때마다 이 서랍을 열어 둘을 함께 봅니다.
~/.hermes/ — 내 홈 폴더 안의 Hermes 폴더 config.yaml 설정 수첩 — 모델·터미널·압축·화면 표시 등 비밀이 아닌 모든 설정 .env 금고 — API 키·토큰·비밀번호 비밀 값만 auth.json SOUL.md memories/ skills/ cron/ sessions/ logs/
깜빡이는 두 파일이 이 장의 주인공입니다. 아래 줄의 일곱 항목은 표에서 설명합니다.
파일·폴더들어 있는 것 (원문 설명)
config.yaml설정 — 모델(에이전트의 두뇌 역할을 하는 AI), 터미널, TTS(글을 소리로 읽어 주는 기능), 압축 등
.envAPI 키(AI 서비스를 쓸 자격을 증명하는 비밀 문자열)와 그 밖의 비밀 값
auth.jsonOAuth(브라우저에서 로그인해 사용 권한을 받는 방식)로 로그인한 제공자(provider — AI 모델을 빌려주는 서비스)의 인증 정보 (Nous Portal 등)
SOUL.md에이전트의 기본 정체성 — 모델에게 주는 기본 지시문(시스템 프롬프트)의 첫째 자리 (5장)
memories/기억(세션이 끝나도 남는 메모) — MEMORY.md, USER.md
skills/에이전트가 만든 스킬(특정 일을 하는 방법을 적은 설명서)
cron/예약 작업(cron — 정해 둔 시간에 자동 실행)
sessions/게이트웨이(메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)의 세션(대화 한 묶음)
logs/기록 — errors.log, gateway.log. 비밀 값은 자동으로 가려집니다

이 가운데 사람이 직접 신경 쓸 파일은 두 개이고, 원문의 규칙은 한 문장입니다 — 비밀 값(API 키·봇 토큰·비밀번호)은 .env 에, 그 밖의 모든 것은 config.yaml 에. 모델, 터미널 백엔드, 압축 설정, 기억 한도, 툴셋(toolset — 도구 꾸러미)이 모두 “그 밖의 것”입니다. .env 는 이름=값 을 한 줄에 하나씩 적고, config.yaml 은 YAML(야믈 — 들여쓰기로 묶음을 나타내는 설정 파일 형식)로 적습니다.

~/.hermes/config.yaml (일부)
terminal:
  backend: local    # 명령을 어디서 실행할지
  timeout: 180      # 명령 하나의 제한 시간(초)
compression:
  enabled: true     # 긴 대화 자동 압축
  threshold: 0.50   # 한도의 50% 에서 압축 시작

들여 쓴 줄은 바로 위 줄의 묶음에 속합니다. 그래서 위 파일의 첫 설정을 한 줄로 부를 때는 점으로 이어 terminal.backend 라고 씁니다 — “terminal 묶음 안의 backend”라는 뜻입니다. 이 장의 표에 나오는 display.language, agent.max_turns 같은 이름은 모두 이렇게 읽습니다. # 뒤의 글은 사람이 읽으라고 붙인 설명입니다.

직접 고치지 않는 가장 쉬운 길 원문은 가장 쉬운 길로 hermes setup --portal 을 듭니다. 로그인 한 번으로 모델 제공자와 Tool Gateway 의 도구 네 가지가 연결되어 YAML 을 손으로 고칠 필요가 없고, Nous Portal 구독자는 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위) 단위로 요금을 매기는 제공자에서 10% 할인도 받는다고 합니다. Nous Portal 자체는 공식 문서 Nous Portal 쪽 참고(이 가이드는 다루지 않음).
config.yaml 을 잘못 고쳐 깨뜨렸다면 Hermes 는 내장 기본값으로 돌아가지 않고 가장 최근의 멀쩡한 사본으로 대신 동작하며, YAML 을 고칠 때까지 시작할 때마다 경고합니다. 깨진 파일 자체는 건드리지 않으므로, 천천히 열어 고치면 됩니다.

설정 보고 바꾸기 — hermes config 명령

설정 파일을 직접 열어 고쳐도 되지만, 터미널(글자로 명령을 입력하는 창)에서 hermes config 명령을 쓰면 값이 알맞은 파일로 알아서 들어갑니다. 계열 명령은 일곱 가지입니다.

명령하는 일
hermes config지금 설정을 보여 줍니다
hermes config editconfig.yaml 을 편집기로 엽니다
hermes config get KEY그 설정이 실제로 어떤 값으로 쓰이는지 출력합니다
hermes config set KEY VAL설정 하나를 정합니다
hermes config unset KEY내가 정한 값을 지웁니다
hermes config check빠진 옵션과 오래되어 맞지 않는 저장된 선택을 점검합니다
hermes config migrate빠진 옵션을 하나씩 물어 가며 채웁니다

표의 KEY 는 설정 이름, VAL 은 넣을 값입니다. 값 하나를 바꾸는 흐름을 원문의 예시 그대로 따라가 봅니다.

1. 지금 값 보기

hermes config get model

뜻: “모델 설정이 지금 무엇으로 되어 있나?” 우선순위까지 따진 최종 값을 보여 줍니다.

2. 값 바꾸기

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker

뜻: “모델을 이것으로”, “터미널 백엔드를 docker 로”. 점으로 이은 이름은 config.yaml 에 저장됩니다.

3. 비밀 값 넣기

hermes config set OPENROUTER_API_KEY sk-or-...

뜻: “OpenRouter 의 API 키를 저장”. 같은 set 명령이지만 이름이 대문자·밑줄이라 .env 에 저장됩니다(sk-or-... 자리에 내 키를 넣습니다).

4. 원래대로 되돌리기 · 점검

hermes config unset terminal.backend
hermes config check

뜻: “내가 정한 터미널 백엔드 값을 지워라”, 그리고 “빠지거나 낡은 설정이 없는지 봐라”. 지운 설정은 우선순위의 아래 단계 값(다음 소절)을 따릅니다.

hermes config set 이름과 값을 넘김 이름의 모양을 봄 내가 파일을 고르지 않아도 됨 .env 대문자·밑줄 이름 (환경 변수) 예: OPENROUTER_API_KEY config.yaml 점으로 이은 이름 예: terminal.backend
set 명령 하나가 이름의 모양에 따라 두 파일 중 알맞은 곳에 저장합니다.

OPENROUTER_API_KEY, HERMES_TIMEZONE 처럼 대문자와 밑줄로 된 이름은 환경 변수(프로그램이 시작할 때 읽어 가는, 이름표가 붙은 값)로 보고 언제나 .env 에 저장하며, 점으로 이은 이름은 config.yaml 로 갑니다. 이름을 잘못 치면 “혹시 이것을 말했나요?”라는 안내가 나오므로, 그때는 철자를 다시 확인합니다.

파일을 직접 고칠 때 주의 YAML 은 같은 이름의 묶음을 한 파일에 두 번 쓰면 뒤의 것이 앞의 것을 아무 말 없이 덮어씁니다. 이미 있는 묶음(예: terminal:)에 항목을 더할 때는 새로 하나 더 만들지 말고 기존 묶음 안에 넣습니다.

hermes config 말고도 설정을 대신 써 주는 명령이 있습니다. 원문에 나오는 것만 모았습니다.

명령무엇을 정하나
hermes model주 모델과 제공자. 메뉴의 “Configure auxiliary models”(보조 모델 설정)로 보조 모델도 고릅니다
hermes tools도구(tool — 에이전트가 쓰는 기능 하나)와 툴셋 켜고 끄기, 웹 검색·브라우저 서비스 고르기 (4장)
hermes doctor바꾸지는 않고 진단만 합니다 — 잘못 적은 시간대, 연결되지 않는 보조 모델 설정 등
대화 중 슬래시 명령(대화 입력 칸에 / 로 시작해 넣는 명령)/reasoning high --global, /fast fast --global 처럼 --global 을 붙이면 config.yaml 에 저장되고, 붙이지 않으면 이번 세션에만 적용됩니다
한눈에 정리
  • Hermes 의 설정은 모두 ~/.hermes/ 폴더에 있습니다. 비밀 값은 .env, 그 밖의 모든 설정은 config.yaml 입니다.
  • hermes config get 으로 보고, set 으로 바꾸고, unset 으로 지웁니다. set 은 이름 모양을 보고 알맞은 파일에 저장합니다.
  • 값이 여러 곳에 있으면 명령에 붙인 옵션 → config.yaml → .env → 내장 기본값 순서로 이깁니다.
  • 파일 읽기(100000자), 터미널 출력(50000자), 명령 시간(180초) 같은 한도가 컨텍스트를 지킵니다.
  • 대화가 컨텍스트 한도의 50%에 닿으면 오래된 부분을 요약으로 바꾸는 압축이 자동으로 일어납니다. 압축 전 대화도 지워지지 않습니다.
  • 이미지 분석·제목 짓기·압축 요약 같은 곁가지 일은 보조 모델 자리가 맡습니다. 기본은 주 모델이며 hermes model 메뉴에서 바꿉니다.
  • 답 끝에 파일 수정 실패 경고가 붙으면 모델의 말보다 그 경고를 믿습니다.
  • 터미널 백엔드는 명령이 실행되는 곳입니다. 기본 local 은 격리가 없고, 헷갈리면 local 로 되돌려 확인합니다.

이 장의 나머지 소절과 🔧 세부는 완전 가이드 3장에 있습니다.

CHAPTER 04

도구 · 툴셋 · MCP

Hermes Agent 는 AI 에이전트(말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)입니다. 그 “일을 해 주는” 부분을 맡는 것이 도구입니다. 이 장에서는 Hermes 에 어떤 도구가 들어 있는지, 도구 꾸러미인 툴셋을 어떻게 켜고 끄는지, 에이전트의 명령이 실제로 어디에서 실행되는지, 그리고 MCP 로 바깥 서비스의 도구를 어떻게 꽂아 쓰는지 차례로 살펴봅니다.

도구란 무엇인가 — 에이전트의 손

도구(tool — 에이전트가 쓰는 기능 하나. 웹 검색, 터미널 명령 실행, 파일 읽기 같은 것)는 에이전트의 능력을 넓혀 주는 기능입니다. 모델(에이전트의 두뇌 역할을 하는 AI — Claude · GPT · Gemini 등)은 혼자서는 글을 읽고 쓸 수만 있습니다. 실제로 웹을 찾아보거나, 내 컴퓨터에서 명령을 실행하거나, 파일을 고치려면 그 일을 대신 해 줄 도구가 있어야 합니다. Hermes 는 이런 도구를 폭넓게 갖춘 채로 설치됩니다.

아주 쉽게 말하면 모델이 “두뇌”라면 도구는 “손”입니다. 두뇌는 “이 폴더에 무엇이 있는지 봐야겠다”고 생각만 할 수 있고, 실제로 폴더를 열어 보는 것은 손(파일을 읽는 도구)입니다. 손이 많을수록 맡길 수 있는 일이 늘어나고, 어떤 손을 쥐여 줄지는 내가 정할 수 있습니다.
🙂 나 부탁하는 말 Hermes 모델(두뇌)이 어떤 도구를 쓸지 고르고 결과를 읽고 답합니다 웹 검색web_search 터미널 명령 실행terminal 파일 읽기 · 고치기read_file · patch 기억 남기기memory 바깥 서비스의 도구MCP 서버 도구
움직이는 점은 부탁 하나가 도구를 거쳐 답으로 돌아오는 길입니다. 오른쪽은 도구의 일부입니다.

원문은 내장 도구를 아래처럼 큰 묶음으로 소개합니다. 도구 이름은 대화 기록에 그대로 나오므로, “이런 이름이 보이면 이런 일을 하는 중이구나” 정도로만 알아 두면 됩니다.

묶음도구 이름 예하는 일
웹 (Web)web_search, web_extract웹을 검색하고, 찾은 페이지의 내용을 뽑아 옵니다.
X 검색 (X Search)x_searchX(Twitter)의 글과 타래를 검색합니다. 기본은 꺼져 있고, 따로 켜야 합니다.
터미널 · 파일terminal, process, read_file, patch명령을 실행하고 파일을 다룹니다.
브라우저 (Browser)browser_exec, browser_cdp, browser_dialog, browser_vault웹 브라우저를 자동으로 조작합니다(화면 찍기 포함).
미디어 (Media)vision_analyze, image_generate, text_to_speech그림을 보고 분석하거나, 그림 · 음성을 만들어 냅니다.
에이전트 조율todo, clarify, execute_code, delegate_task계획 세우기, 나에게 되묻기, 코드 실행, 하위 에이전트(일을 나눠 받은 별도 에이전트)에게 위임 — 7장.
기억 · 되찾기memory, session_search세션이 끝나도 남는 기억과, 지난 세션 검색 — 5장.
자동화 (Automation)cronjob예약 작업(cron — 정해 둔 시간에 자동 실행)을 만들고 · 목록을 보고 · 고치고 · 멈추고 · 다시 켜고 · 바로 실행하고 · 지웁니다 — 7장.
연동 (Integrations)MCP 서버 도구, 플러그인 도구바깥 서비스와 잇습니다. 이 장 뒤쪽의 MCP 가 여기에 해당합니다.

내장 도구 말고도 플러그인(plugin — Hermes 에 덧붙여 설치하는 추가 기능)이 도구를 더해 줍니다. 원문이 드는 예는 집 안 기기를 다루는 Home Assistant 로, homeassistant 카탈로그 플러그인에서 옵니다.

API 키 없이 쓰는 길 — Nous Tool Gateway 유료 Nous Portal 구독자는 웹 검색 · 이미지 생성 · 음성 합성(TTS) · 브라우저 자동화를 Tool Gateway 로, 서비스마다 따로 API 키(그 서비스를 쓸 자격을 증명하는 비밀 문자열)를 마련하지 않고 쓸 수 있습니다. hermes model 로 켜거나 hermes tools 에서 도구별로 설정합니다. (8장의 메신저 “게이트웨이”와는 다른 것입니다.)

툴셋 — 도구 꾸러미를 켜고 끄기

도구는 하나하나 따로 관리하지 않고 툴셋(toolset — 도구 꾸러미)으로 묶여 있습니다. 툴셋은 이름 하나로 관련 도구를 한꺼번에 켜고 끄는 단위이고, 플랫폼(Hermes 를 쓰는 곳 — 터미널, Telegram 같은 메신저 등)마다 따로 켜고 끌 수 있습니다. 예를 들어 터미널에서는 명령 실행 도구를 쓰게 하고, 메신저에서는 꺼 두는 식입니다.

아주 쉽게 말하면 공구함에 “목공 세트”, “전기 세트”처럼 칸이 나뉘어 있다고 생각하면 됩니다. 일터에 따라 필요한 세트만 들고 가듯, 툴셋을 켜고 끄는 것으로 에이전트가 그 자리에서 할 수 있는 일의 범위를 내가 정합니다.

쓰는 명령은 두 가지입니다. 둘 다 터미널(글자로 명령을 입력하는 창)에 입력합니다.

하고 싶은 일명령뜻
쓸 수 있는 도구를 모두 보기 · 플랫폼별로 켜고 끄기hermes tools도구 목록을 보여 주고, 고르는 화면(대화형)에서 플랫폼마다 설정합니다. 원문은 두 용도에 같은 명령을 적어 둡니다.
이번 대화에서만 정한 툴셋으로 시작하기hermes chat --toolsets "web,terminal"쉼표로 이은 툴셋(여기서는 web 과 terminal)만 가지고 대화를 엽니다.

원문이 “흔히 쓰는 툴셋”으로 드는 이름입니다(원문은 이름만 나열합니다): web search terminal file browser vision image_gen skills tts todo memory session_search cronjob code_execution delegation clarify messaging discord discord_admin debugging safe.

미리 묶어 둔 툴셋도 있습니다 전체 목록에는 hermes-cli, hermes-telegram 같은 플랫폼용 기본 묶음(platform presets)과, MCP 서버를 연결하면 자동으로 생기는 mcp-<서버 이름> 툴셋도 들어 있습니다(연결된 뒤 일어나는 일). 툴셋별 도구 구성은 공식 문서 Toolsets Reference 쪽 참고(이 가이드는 다루지 않음).

MCP 란 — 바깥 도구를 꽂는 공통 규격

MCP(Model Context Protocol — 외부 서비스의 도구를 에이전트에 연결하는 공통 규격)는 Hermes 안에 들어 있지 않은 도구를 Hermes 가 쓸 수 있게 이어 주는 방법입니다. 도구를 내주는 쪽 프로그램을 MCP 서버(MCP 규격에 맞춰 도구를 내주는 프로그램)라고 부릅니다. GitHub, 데이터베이스, 파일 시스템, 브라우저, 회사 내부 API 등 이미 어딘가에 있는 도구를 MCP 서버를 통해 연결하면, 에이전트는 그 도구를 내장 도구와 똑같이 씁니다.

쓰고 싶은 서비스마다 Hermes 전용 도구를 새로 만들 수는 없습니다. 원문은 “이미 다른 곳에 있는 도구를 Hermes 가 쓰게 하고 싶다면, 대개 MCP 가 가장 깔끔한 길”이라고 적습니다.

아주 쉽게 말하면 MCP 는 멀티탭의 콘센트 모양 같은 것입니다. 콘센트 모양이 하나로 정해져 있으니, 어느 회사가 만든 기기든 플러그만 맞으면 꽂아 쓸 수 있습니다. MCP 서버는 “플러그가 달린 기기”, Hermes 는 “멀티탭”입니다. 꽂기만 하면 Hermes 가 그 기기에 어떤 기능이 있는지 알아서 살펴봅니다.
Hermes 내장 도구 + MCP 로 꽂은 도구 stdio 서버 내 컴퓨터에서 Hermes 가 함께 실행하는 프로그램 HTTP 서버 다른 곳에서 운영되는 주소(URL)에 바로 접속 바깥의 도구 · 자료 GitHub 데이터베이스 파일 시스템 브라우저 회사 내부 API … 그 밖에도
MCP 서버는 Hermes 와 바깥 서비스 사이의 연결 부품입니다. Hermes 는 시작할 때 서버에 어떤 도구가 있는지 알아보고 자기 도구 목록에 올립니다.

원문이 꼽는 MCP 의 좋은 점은 다섯 가지입니다.

좋은 점뜻
도구를 새로 만들지 않아도Hermes 전용 도구를 먼저 짜지 않고 바깥의 도구 생태계를 씁니다.
로컬과 원격을 한곳에내 컴퓨터의 stdio 서버와 원격 HTTP 서버를 같은 설정에 적습니다.
알아서 찾고 등록시작할 때 서버의 도구를 자동으로 찾아 등록합니다.
자료 · 프롬프트용 보조 도구서버가 지원하면 MCP 의 자료(resources)와 프롬프트(prompts)를 다루는 보조 도구도 붙습니다.
서버별 걸러 내기Hermes 에게 보여 줄 도구만 고릅니다 — 걸러 내기.

MCP 서버는 연결 방식에 따라 두 종류입니다. 어느 쪽인지는 내가 정하는 것이 아니라 그 서버의 안내 문서가 어떤 값을 주느냐로 갈립니다 — 명령(command)을 주면 stdio, 주소(url)를 주면 HTTP 입니다.

Hermes 가 내 컴퓨터에서 딸린 프로그램으로 직접 실행하고, 표준 입출력(stdin/stdout — 프로그램끼리 글자를 주고받는 기본 통로)으로 대화하는 서버입니다.

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"

뜻: github 라는 이름으로, npx … 명령을 실행해 서버를 띄우고, 그 서버에 접근 토큰(access token — 서비스가 내준 디지털 출입증. 글의 양을 세는 “토큰”과는 다른 말)을 환경 변수로 넘깁니다. *** 자리에는 실제 값을 넣습니다.

  • 서버가 내 컴퓨터에 설치되어 있을 때
  • 내 컴퓨터의 자료에 빠르게 접근하고 싶을 때
  • 따라 하는 MCP 서버 문서가 command, args, env 를 보여 줄 때

다른 곳에서 운영되는 서버에 Hermes 가 주소로 바로 접속합니다.

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

뜻: remote_api 라는 이름으로, 적힌 주소에 접속하고, 요청마다 인증 정보(headers)를 함께 보냅니다.

  • MCP 서버가 다른 곳에서 운영될 때
  • 회사가 내부용 MCP 주소를 열어 둘 때
  • 그 연동 때문에 Hermes 가 내 컴퓨터에 프로그램을 따로 띄우는 것이 싫을 때

많은 호스팅형 서버는 고정된 토큰 대신 브라우저 로그인(OAuth)을 요구합니다 — 로그인이 필요한 서버.

Claude Code 를 쓰다 왔다면 ~/.claude.json 의 mcpServers 묶음이 Hermes config.yaml 의 mcp_servers 에 대응합니다. hermes import-agent claude-code(agent-importers 플러그인에 들어 있음)가 스킬 · 지침과 함께 옮겨 줍니다. (공식 문서 Import from Other Agents 쪽 참고.)

MCP 서버 추가하기 — 카탈로그와 직접 설정

MCP 서버를 Hermes 에 붙이는 길은 크게 둘입니다. 하나는 Nous 직원이 검토해 받아들인 서버 목록인 카탈로그에서 고르는 것이고, 다른 하나는 설정 파일 ~/.hermes/config.yaml(~ 는 내 홈 폴더)에 직접 몇 줄 적는 것입니다. MCP 기능은 표준 설치에 들어 있어 따로 설치할 것은 없습니다. 처음이라면 카탈로그부터 보는 편이 쉽습니다.

카탈로그의 서버는 모두 기본으로 꺼져 있으므로 쓰고 싶은 것만 설치합니다.

명령하는 일
hermes mcp고르는 화면(대화형 선택기)을 엽니다. 기본 동작입니다.
hermes mcp catalog목록을 글자로만 출력합니다(스크립트에 쓰기 좋음).
hermes mcp install deepwiki이름으로 바로 설치합니다(여기서는 deepwiki).
hermes mcp — 원문의 예시 화면
deepwiki     available              Ask questions about public GitHub repositories
linear       enabled                Linear issue/project management (remote OAuth)
github       installed (disabled)   GitHub repo + PR tools

각 줄은 이름 · 지금 상태 · 설명이고, 상태는 available(설치할 수 있음) · enabled(켜져 있음) · installed (disabled)(설치됐지만 꺼 둠) 가운데 하나입니다. 줄에서 Enter 를 누르면 설치(필요한 자격 증명 입력까지 안내), 켜기, 끄기, 제거를 할 수 있습니다.

대화 중에 말로 부탁해도 됩니다. 원문의 예: add the Linear MCP (뜻: Linear MCP 를 추가해 줘). 그러면 에이전트가 연결 관리 도구를 부르고 설정 카드가 나타납니다. 카드는 데스크톱 앱에서는 대화 상자로, TUI(hermes --tui 로 여는 새 터미널 화면)에서는 입력 칸 위의 안내 상자로, 기존 CLI 에서는 패널로 뜨며 동작은 같습니다.

카드는 필요한 값을 한꺼번에 묻고(비밀 값은 가려짐) Connect 나 Cancel 을 고르게 합니다. 브라우저 로그인이 필요하면 인증 링크를 보여 주되 브라우저를 멋대로 열지는 않습니다 — 데스크톱에서는 Open in browser, 터미널에서는 Enter. 서버가 토큰을 받아들이고 첫 연결이 된 뒤에야 설정과 토큰을 저장하고, 거절되거나 취소하면 아무것도 남기지 않습니다.

메신저 앱에서는 카드가 없습니다. 그때는 에이전트가 ① 의 명령들을 대신 알려 줍니다.

카탈로그에 없는 서버는 그 서버의 안내 문서가 주는 값을 설정 파일의 mcp_servers 아래에 적습니다. 원문의 빠른 시작 예시는 내 폴더 하나를 읽게 해 주는 파일 시스템 서버입니다.

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

뜻: filesystem 이라는 이름으로 서버를 실행하고, 맨 끝에 적은 폴더(/home/user/projects)를 그 서버에 알려 줍니다. 폴더 경로는 내 것으로 바꿉니다. 줄 앞의 들여쓰기는 예시 그대로 지킵니다.

따라 하기 — 카탈로그에서 설치하는 흐름과 설정 파일로 추가하는 흐름을 한 번에 봅니다.

① 서버를 고르거나 적습니다

카탈로그: 터미널에 hermes mcp 를 입력하고 원하는 줄에서 Enter. 직접 설정: ~/.hermes/config.yaml 의 mcp_servers 아래에 서버 항목을 적습니다(설정 파일 여는 법은 3장).

② 필요한 값을 넣습니다 (카탈로그)

항목에 따라 요구하는 것이 다릅니다.

요구하는 것Hermes 가 하는 일
API 키설치할 때 물어보고 ~/.hermes/.env 에 적습니다. 비밀이 아닌 값(기본 주소 등)도 같은 파일에 들어갑니다.
OAuth (원격 MCP)설정에 auth: oauth 로 적히고, 처음 연결할 때 MCP 클라이언트가 브라우저를 엽니다.
OAuth (Google · GitHub 같은 다른 제공자)아직 인증하지 않았다면 hermes auth <provider> 를 하라고 안내합니다.

③ 쓸 도구를 고릅니다 (카탈로그)

자격 증명이 준비되면 Hermes 가 서버에 물어 도구 목록을 받아 와 체크리스트로 보여 줍니다. Space 로 켜고 끄고 Enter 로 확정합니다. 체크한 도구만 Hermes 에 드러납니다.

도구 고르기 — 원문의 예시 화면
Select tools for 'linear' (SPACE toggle, ENTER confirm)
  [x] find_issues       Find issues matching a query
  [x] get_issue         Get a single issue
  [x] create_issue      Create a new issue
  [ ] delete_workspace  Delete a Linear workspace
  ...

위 예시에서는 작업 공간을 통째로 지우는 delete_workspace 만 체크가 빠져 있습니다.

④ Hermes 를 시작합니다

hermes chat

Hermes 는 시작할 때 MCP 서버의 도구를 찾아 등록합니다. 이미 대화 중에 설정을 바꿨다면 대화 입력 칸에 /reload-mcp 를 넣어 다시 읽게 합니다.

⑤ 그 기능이 필요한 일을 부탁합니다

도구 이름을 내가 부를 필요는 없습니다. 평소처럼 일을 말하면 됩니다. 원문의 예(파일 시스템 서버):

List the files in /home/user/projects and summarize the repo structure.

뜻: /home/user/projects 의 파일 목록을 보고 저장소 구조를 요약해 줘. — Hermes 가 MCP 서버의 도구를 찾아내 다른 도구와 똑같이 씁니다. 도구가 쓰이지 않거나 오류가 나면 MCP 가 안 될 때를 봅니다.

고른 도구를 나중에 바꾸려면 hermes mcp configure linear 처럼 서버 이름을 붙여 실행하면 같은 체크리스트가 지금 선택 그대로 다시 열립니다. 서버에 새로 생긴 도구를 받아들일 때도 씁니다.
설치는 남의 코드를 실행하는 일입니다 카탈로그 항목을 설치하면 그 항목이 정한 설치 명령과 서버 코드가 내 컴퓨터에서 실행됩니다. 설치 전에 무엇이 실행되는지 확인합니다 — MCP 를 안전하게 쓰기.
한눈에 정리
  • 도구는 에이전트의 손입니다. 웹 검색 · 터미널 · 파일 · 기억 등이 내장돼 있고, 플러그인과 MCP 로 더 붙입니다.
  • 툴셋은 도구 꾸러미입니다. hermes tools 로 플랫폼마다 켜고 끄고, hermes chat --toolsets "web,terminal" 로 이번 대화에만 정합니다.
  • 터미널 백엔드는 명령이 실행되는 곳입니다. 기본은 내 컴퓨터(local)이고, docker 나 ssh 로 떼어 낼 수 있습니다. 에이전트의 명령만 멈추면 셸 시작 파일부터 의심합니다.
  • 오래 걸리는 명령은 백그라운드로 돌리고 process 도구로 확인합니다. sudo 비밀번호는 가려진 입력 칸으로만 넣고, 채팅으로 보내지 않습니다.
  • MCP 는 바깥 서비스의 도구를 꽂는 공통 규격입니다. 서버는 내 컴퓨터에서 실행되는 stdio 와 주소로 접속하는 HTTP 두 종류입니다.
  • 추가는 hermes mcp(카탈로그)나 ~/.hermes/config.yaml 의 mcp_servers 로 합니다. 설정을 바꿨으면 /reload-mcp, 로그인이 필요하면 hermes mcp login <server>.
  • 필요한 도구만 받고(include / exclude), 설치 전에는 무엇이 실행되는지 읽어 봅니다.

이 장의 나머지 소절과 🔧 세부는 완전 가이드 4장에 있습니다.

CHAPTER 05

기억 · 맥락 파일 · 성격

Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 도구를 써서 내 대신 일을 해 주는 AI 프로그램)는 대화가 끝나도 나와 내 프로젝트를 잊지 않도록 네 가지 장치를 씁니다. 스스로 적는 기억, 프로젝트 폴더에 두는 맥락 파일, 기본 성격을 정하는 SOUL.md, 잠깐 말투를 바꾸는 /personality 입니다. 이 장에서는 넷이 각각 무엇이고 어떻게 다른지, 무엇을 어디에 적어야 하는지를 차례로 봅니다.

기억이란 — 세션이 끝나도 남는 메모

Hermes 에는 세션(대화 한 묶음 — 시작부터 끝까지의 기록)이 끝나도 남는 기억(memory)이 있습니다. 원문은 이것을 “크기가 정해져 있고(bounded) 골라 담는(curated) 기억”이라고 부릅니다. 덕분에 Hermes 는 내 취향, 내 프로젝트, 내 컴퓨터 환경, 일하다 배운 것을 다음 대화에서도 압니다.

아주 쉽게 말하면 Hermes 에게는 포스트잇 몇 장 크기의 작은 수첩이 두 권 있습니다. 일하다 중요한 것을 알게 되면 수첩에 적어 두고, 다음 날 출근할 때(새 세션) 수첩부터 한 번 읽고 일을 시작합니다. 수첩이 작아서 정말 중요한 것만 골라 적어야 합니다.

수첩 두 권은 내 컴퓨터의 ~/.hermes/memories/ 폴더(~ 는 내 홈 폴더)에 있는 파일 두 개입니다.

파일무엇을 적나글자 수 한도
MEMORY.md에이전트의 개인 메모 — 환경 사실, 규칙, 배운 것2,200자 (약 800 토큰)
USER.md사용자 소개 — 내 취향, 소통 방식, 기대하는 것1,375자 (약 500 토큰)

토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)으로는 둘을 합쳐 약 1,300 토큰입니다. Hermes 는 memory 라는 도구(tool — 에이전트가 쓰는 기능 하나)로 이 파일에 항목을 추가하고, 고치고, 지웁니다. 내가 파일을 직접 관리할 필요가 없습니다.

지난 세션 일하다 알게 된 것을 memory 도구로 적음 기억 파일 (내 컴퓨터) ~/.hermes/memories/ MEMORY.md · USER.md 새 세션 시작할 때 한 번 읽어 시스템 프롬프트에 넣음 세션은 끝나도 파일은 남습니다 — 그래서 다음에 만나도 기억합니다
기억은 “적는 때”와 “읽는 때”가 다릅니다. 적는 것은 일하는 도중, 읽는 것은 세션을 시작할 때 한 번입니다.

세션이 시작되면 기억은 시스템 프롬프트(대화가 시작될 때 모델이 가장 먼저 읽는 지시문 묶음) 안에 아래처럼 들어갑니다. 원문에 실린 예시입니다.

시스템 프롬프트 안의 기억 (원문 예시)
══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker and Podman installed
§
User prefers concise responses, dislikes verbose explanations
  • 머리말은 어느 칸인지(에이전트 메모는 MEMORY, 사용자 소개는 USER PROFILE)와 지금 쓴 비율 · 글자 수를 보여 줍니다. Hermes 가 남은 자리를 알 수 있게 하려는 것입니다.
  • § 는 항목을 나누는 기호입니다. 항목 하나가 여러 줄일 수도 있습니다.
  • 세 항목의 뜻: “사용자의 프로젝트는 ~/code/myapi 에 있는 Rust 웹 서비스” · “이 컴퓨터는 Ubuntu 22.04 이고 Docker 와 Podman 이 깔려 있음” · “사용자는 짧은 답을 좋아하고 장황한 설명을 싫어함”

꼭 알아 둘 점 하나 — 기억은 세션을 시작할 때 “사진 찍듯” 한 번만 읽습니다. 원문은 이것을 고정된 스냅샷(frozen snapshot)이라고 부릅니다.

① 세션 시작 — 기억을 한 번 읽습니다

디스크(내 컴퓨터의 저장 공간)에 있는 기억 파일을 읽어 시스템 프롬프트에 넣습니다. 이 내용은 세션이 끝날 때까지 바뀌지 않습니다.

② 세션 도중 — 새로 적으면 파일에는 바로 저장됩니다

Hermes 가 기억을 추가하거나 지우면, 그 변경은 곧바로 파일에 남습니다. 사라질 걱정은 없습니다.

③ 하지만 지금 세션의 시스템 프롬프트는 그대로입니다

일부러 이렇게 만들었습니다. 시스템 프롬프트 앞부분이 바뀌지 않아야 모델이 앞부분을 다시 계산하지 않고 재사용(원문: prefix cache)할 수 있어 빠르기 때문입니다. 다만 도구의 응답에는 항상 지금 상태가 보입니다.

④ 다음 세션 — 새 내용이 반영됩니다

새 세션이 시작되면 그때의 파일을 다시 읽습니다. 그래서 “방금 저장한 것”은 다음 세션부터 보입니다.

어떻게 쓰나 — 따로 할 일은 거의 없습니다. Hermes 는 중요한 것을 알게 되면 스스로 저장합니다. 꼭 남기고 싶은 것은 “기억해 줘”라고 말하면 됩니다. 실제로 무엇이 적혔는지는 터미널(글자로 명령을 입력하는 창)에서 파일을 열어 확인할 수 있습니다.

cat ~/.hermes/memories/MEMORY.md
cat ~/.hermes/memories/USER.md

뜻: 두 기억 파일의 내용을 화면에 보여 줍니다.

Hermes 홈 폴더 하나에는 에이전트 하나만 실행 중인 에이전트 둘이 같은 Hermes 홈 폴더(~/.hermes)를 쓰게 하지 마세요. 기억은 자동으로 적히고 다시 읽히므로, 둘이 서로의 항목 위에 덧쌓아 누구도 쓴 적 없는 내용이 됩니다. 두 번째 에이전트에게는 자기 프로필(profile — 설정·기억·세션을 따로 쓰는 별도 Hermes 환경)을 주고, 기억을 함께 써야 한다면 외부 기억 제공자를 씁니다.

더 보기: 수첩이 꽉 차면 · 저장한 줄 알았는데 잊었다면.

맥락 파일 — 폴더에 두면 알아서 읽는 안내문

맥락 파일(context files)은 Hermes 가 알아서 찾아 읽는 안내문 파일입니다. 프로젝트 폴더에 정해진 이름으로 두면, 세션(대화 한 묶음)을 시작할 때 시스템 프롬프트(모델이 가장 먼저 읽는 지시문 묶음)에 들어가 Hermes 의 행동을 정합니다. “이 프로젝트는 이렇게 생겼고 이런 규칙이 있어”를 매번 말할 필요가 없어집니다.

아주 쉽게 말하면 사무실 벽에 붙여 둔 업무 안내문입니다. 그 사무실에 들어서면 먼저 읽고 일을 시작하고, 다른 사무실(다른 프로젝트 폴더)에는 그곳의 안내문이 따로 있습니다.
파일쓰임어디서 찾나
.hermes.md / HERMES.md프로젝트 지침 (가장 우선)git 저장소(git 으로 변경 이력을 관리하는 프로젝트 폴더)의 맨 위 폴더까지 올라가며
AGENTS.override.mdAGENTS.md 를 나만, 폴더별로 덮어쓰는 파일 (보통 저장소에 올리지 않음)시작할 때의 작업 폴더 + 하위 폴더는 차츰
AGENTS.md프로젝트 지침 · 규칙 · 구조위와 같음
CLAUDE.mdClaude Code 용 맥락 파일 (이것도 알아봄)위와 같음
SOUL.md이 Hermes 전체의 성격과 말투Hermes 홈 폴더(~/.hermes)의 SOUL.md 만
.cursorrulesCursor IDE 의 코딩 규칙작업 폴더만
.cursor/rules/*.mdcCursor IDE 의 규칙 모듈작업 폴더만

작업 폴더(working directory, 원문 표기 CWD)는 Hermes 를 실행한 그 폴더입니다.

프로젝트 맥락 파일 — 앞에서부터 찾아, 먼저 나온 한 종류만 .hermes.md가장 우선 AGENTS.override.md나만 쓰는 덮어쓰기 AGENTS.md기본 안내문 CLAUDE.mdClaude Code 용 .cursorrulesCursor 용 →→→→ 화살표 = “없으면 다음 것을 찾음” SOUL.md — 위 순서와 상관없이 항상 따로 읽습니다 성격을 정하는 파일 · 시스템 프롬프트의 첫 자리
프로젝트 맥락 파일은 한 세션에 한 종류만 읽습니다. 먼저 찾은 것이 이깁니다.

어떻게 쓰나 — 가장 흔한 방법은 프로젝트 폴더에 AGENTS.md 하나를 두는 것입니다.

  1. 프로젝트 폴더에 AGENTS.md 파일을 만듭니다보통의 글 파일입니다. 프로젝트 구조, 지킬 규칙, 하면 안 되는 일을 적습니다 — 쓰는 법은 AGENTS.md.
  2. 그 폴더에서 Hermes 를 실행합니다세션을 시작할 때 Hermes 가 파일을 찾아 읽습니다. 따로 알려 줄 필요가 없습니다.

기억과 다른 점은 둘입니다. 기억은 Hermes 가 스스로 적지만 맥락 파일은 내가 직접 씁니다. 기억은 어느 폴더에서든 읽히지만 맥락 파일은 그 파일이 있는 프로젝트에서만 읽힙니다.

  • AGENTS.override.md — AGENTS.md 옆에 이 파일이 있으면 AGENTS.md 대신 이것을 읽습니다. 저장소에 올라가 있는 AGENTS.md 는 건드리지 않고 나만 다른 지침을 쓰고 싶을 때 둡니다.
  • .cursorrules — Hermes 는 Cursor IDE 의 .cursorrules 파일, .cursor/rules/*.mdc 규칙 모듈과 호환됩니다. 프로젝트 맨 위 폴더에 이 파일이 있고 더 우선하는 맥락 파일이 없으면 프로젝트 맥락으로 읽습니다. 이미 써 둔 Cursor 규칙이 Hermes 에서도 그대로 적용된다는 뜻입니다.
남이 만든 프로젝트의 맥락 파일은 읽어 보고 쓰세요 맥락 파일은 Hermes 에게 주는 지시문입니다. Hermes 가 보안 검사를 하지만, 원문은 이것이 직접 살펴보는 일을 대신하지 못한다고 적습니다.

SOUL.md — Hermes 의 기본 성격

SOUL.md 는 Hermes 의 성격, 말투, 소통 방식을 정하는 파일입니다. 시스템 프롬프트(모델이 가장 먼저 읽는 지시문 묶음)의 맨 첫 자리에 들어가 “이 에이전트가 누구인가”를 정합니다. Hermes 가 누구인지를 바꾸고 싶다면 — 아예 다른 인물로 바꾸는 것까지 — 이 파일을 고칩니다.

아주 쉽게 말하면 비서의 자기소개서입니다. “돌려 말하지 않고, 모르면 모른다고 합니다” 같은 성격이 적혀 있습니다. 어느 사무실에서 일하든 성격은 같아야 하므로, 사무실이 아니라 비서의 가방(Hermes 홈 폴더)에 한 장만 있습니다.
~/.hermes/SOUL.md Hermes 홈 폴더 한 곳 — 성격은 여기서만 읽습니다 프로젝트 A 폴더같은 성격 프로젝트 B 폴더같은 성격 프로젝트 C 폴더여기 둔 SOUL.md 는 읽지 않음 ✗
어느 폴더에서 Hermes 를 열든 성격이 같습니다. 프로젝트마다 성격이 뜻밖에 바뀌지 않게 하려는 설계입니다.

어디에 있나 — 대부분의 사용자는 아래 한 곳입니다. ~ 는 내 홈 폴더입니다.

~/.hermes/SOUL.md

Hermes 홈 폴더를 다른 곳으로 정해 쓰는 경우(원문 표기 HERMES_HOME)에는 $HERMES_HOME/SOUL.md 입니다.

상황Hermes 가 하는 일
파일이 아직 없음시작용 SOUL.md 를 자동으로 만들어 둡니다
내가 쓴 SOUL.md 가 있음절대 덮어쓰지 않습니다
내용이 있음보안 검사를 하고, 너무 크면 잘라낸 뒤, 적힌 그대로 넣습니다. 앞뒤에 덧붙이는 말이 없습니다
비어 있거나 읽을 수 없음Hermes 에 들어 있는 기본 정체성으로 돌아갑니다
작업 폴더에 SOUL.md 가 있음보지 않습니다. Hermes 홈 폴더에서만 읽습니다

무엇을 적나 — 오래가는 목소리와 성격입니다. 프로젝트에 딸린 내용은 적지 않습니다.

✅ SOUL.md 에 적을 것

  • 말투, 소통 방식
  • 얼마나 직설적으로 말할지
  • 기본 대화 방식
  • 문체에서 피할 것
  • 확실하지 않을 때, 의견이 다를 때, 뜻이 모호할 때 어떻게 할지

❌ 여기 말고 AGENTS.md 에 적을 것

  • 한 번뿐인 프로젝트 지시
  • 파일 경로
  • 저장소의 규칙
  • 잠깐 쓰는 작업 절차

좋은 SOUL.md 는 ① 어떤 상황에서도 변하지 않고 ② 여러 대화에 두루 맞을 만큼 넓고 ③ 목소리를 실제로 바꿀 만큼 구체적이며 ④ 일의 지시가 아니라 소통과 정체성에 집중합니다. 원문 예시입니다.

SOUL.md (원문 예시)
# Personality
You are a pragmatic senior engineer with strong taste.
You optimize for truth, clarity, and usefulness over politeness theater.

## Style
- Be direct without being cold
- Prefer substance over filler
- Push back when something is a bad idea
- Admit uncertainty plainly
- Keep explanations compact unless depth is useful

## What to avoid
- Sycophancy
- Hype language
- Repeating the user's framing if it's wrong
- Overexplaining obvious things

## Technical posture
- Prefer simple systems over clever systems
- Care about operational reality, not idealized architecture
- Treat edge cases as part of the design, not cleanup

뜻: 성격 — 안목 있는 실용적인 선임 엔지니어, 겉치레 예의보다 사실 · 명확함 · 쓸모. 말투 — 차갑지 않게 직설적으로, 군말보다 알맹이, 나쁜 생각에는 반대, 모르면 모른다고, 깊이가 필요할 때가 아니면 짧게. 피할 것 — 아첨, 과장, 사용자의 틀린 전제 되풀이, 뻔한 것 길게 설명. 기술 태도 — 기발함보다 단순함, 이상적인 설계보다 실제 운영, 예외 상황도 설계의 일부.

SOUL.md 와 AGENTS.md — 원문이 “가장 중요한 구분”이라고 한 것입니다.

SOUL.mdAGENTS.md
적는 것정체성, 말투, 문체, 기본 소통 방식, 성격에서 나오는 행동프로젝트 구조, 코딩 규칙, 선호하는 도구, 저장소별 작업 절차, 명령 · 포트 · 경로 · 배포 메모
기준어디서나 나를 따라다녀야 하면 여기프로젝트에 속하면 여기
한눈에 정리
  • 네 가지 장치 — 기억(Hermes 가 스스로 적는 메모), 맥락 파일(프로젝트 폴더의 안내문), SOUL.md(기본 성격), /personality(잠깐 바꾸는 말투). 모두 시스템 프롬프트에 들어갑니다.
  • 기억은 ~/.hermes/memories/ 의 MEMORY.md(2,200자)와 USER.md(1,375자). 세션을 시작할 때 한 번 읽으므로 방금 저장한 것은 다음 세션부터 보입니다.
  • 메신저에서는 한 세션이 길게 이어지므로, 일이 끝나거나 주제가 바뀔 때 /new 로 경계를 만듭니다.
  • “기억했다”는 말만 믿지 말고 기억 파일을 열어 실제로 적혔는지 봅니다. 적지 않은 것은 session_search 가 지난 대화에서 찾습니다.
  • 맥락 파일은 한 세션에 한 종류만(먼저 찾은 것), SOUL.md 는 항상 따로 읽습니다.
  • 나를 따라다녀야 하면 SOUL.md, 프로젝트에 속하면 AGENTS.md. 말투를 잠깐 바꿀 때는 /personality teacher, 끌 때는 /personality none.
  • 맥락 파일 · SOUL.md · 기억은 넣기 전에 보안 검사를 거칩니다. 그래도 남이 만든 프로젝트의 AGENTS.md 는 직접 확인합니다.

이 장의 나머지 소절과 🔧 세부는 완전 가이드 5장에 있습니다.

CHAPTER 06

스킬 — 일하는 법을 배우고 다시 쓰기

Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트)는 일하는 방법을 스킬(skill — 특정 일을 하는 방법을 적은 설명서)이라는 문서로 갖고 있다가, 그 일이 필요해졌을 때만 꺼내 읽습니다. 이 장에서는 스킬이 무엇이고, 어떻게 불러 쓰며, 어디서 구해 설치하고, 에이전트가 어떻게 스스로 스킬을 만들어 가는지를 차례로 살펴봅니다.

스킬이란 무엇인가

스킬은 에이전트(AI 에이전트 — 말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)가 필요할 때 불러와 읽는 지식 문서입니다. 원문 표현으로는 “on-demand knowledge documents”, 곧 요청이 있을 때만 펼치는 문서입니다. 스킬 하나는 SKILL.md 라는 글 파일 하나가 중심이고, 그 안에 “이 일은 언제 하고, 어떤 순서로 하며, 어디서 자주 틀리고, 잘 됐는지는 어떻게 확인하는지”가 적혀 있습니다.

아주 쉽게 말하면 사무실 선반에 업무 설명서가 수십 권 꽂혀 있다고 생각해 보세요. 평소에는 책등에 적힌 제목과 한 줄 소개만 눈에 들어옵니다. “출장비 정산”을 해야 하는 날에만 그 책을 뽑아 펼쳐 읽고, 그 안의 부록 표가 필요하면 그 쪽만 넘겨 봅니다. 수십 권을 매일 처음부터 끝까지 읽지 않아도 되니 머리가 가볍습니다. Hermes 의 스킬이 이 설명서이고, 선반이 스킬 폴더입니다.
처음부터 들어 있는 스킬 bundled — 설치할 때 복사됩니다 Skills Hub 에서 설치한 스킬 hub-installed — 내가 골라 설치 에이전트가 스스로 만든 스킬 agent-created — 일하다 익힌 방법 ~/.hermes/skills/ 모든 스킬이 모이는 기본 폴더 SKILL.md SKILL.md SKILL.md 스킬 하나 = 폴더 하나 Hermes 필요한 스킬만 꺼내 읽고, 고치거나 지울 수도 있습니다 들어오는 길은 셋이어도 놓이는 곳은 하나입니다
스킬은 세 갈래로 생기지만 모두 한 폴더에 모입니다. 가운데 강조한 카드는 지금 꺼내 읽는 스킬 하나를 뜻합니다.

스킬은 모두 ~/.hermes/skills/ 에 있습니다(~ 는 내 홈 폴더를 뜻합니다). 원문은 이 폴더를 “기본 폴더이자 기준이 되는 원본”이라고 부릅니다. 처음 설치하면 Hermes 에 딸려 오는 스킬(bundled skills)이 이곳에 복사되고, Skills Hub(스킬을 찾아 설치하는 곳)에서 설치한 스킬과 에이전트가 만든 스킬도 이곳으로 들어옵니다. 에이전트는 어떤 스킬이든 고치거나 지울 수 있습니다.

스킬은 Hermes 만의 형식이 아닙니다. 원문은 스킬이 agentskills.io 공개 표준과 호환된다고 적습니다.

기억과 스킬은 무엇이 다른가

Hermes 에는 세션(대화 한 묶음)이 끝나도 남는 것이 두 가지 있습니다. 기억과 스킬입니다. 원문은 둘의 역할을 이렇게 나눕니다.

기억 (memory)스킬 (skill)
담는 것작고 오래가는 사실더 긴 절차(일하는 순서)
언제 읽히나항상 — 대화마다 들어 있어야 하는 것관련 있을 때만 불러옴
비유책상에 붙여 둔 메모지선반에 꽂아 둔 설명서

둘은 Hermes 가 스스로 나아지는 흐름(0장 「배우는 순환」) 안에서 함께 움직입니다. 에이전트가 스킬을 직접 만드는 과정은 아래 소절에서 다룹니다.

어떤 스킬이 들어 있는지 보려면 딸려 오는 스킬과 공식 선택 스킬의 전체 목록은 공식 문서의 Bundled Skills Catalog · Official Optional Skills Catalog 쪽에 있습니다(이 가이드는 다루지 않음). 내 컴퓨터에 지금 무엇이 있는지는 대화에서 물어보거나 /skills list 로 볼 수 있습니다.

스킬 쓰기 — 슬래시 명령으로 부르기

설치된 스킬은 저절로 슬래시 명령(대화 입력 칸에 / 로 시작해 넣는 명령)이 됩니다. 따로 등록할 것이 없습니다. 대화 입력 칸에 /스킬이름 을 쓰고 그 뒤에 부탁을 이어 적으면, 에이전트가 그 스킬을 읽은 다음 부탁을 처리합니다. 터미널(글자로 명령을 입력하는 창)의 CLI(터미널에서 글자로 쓰는 프로그램 화면)에서도, 메신저에서도 똑같이 씁니다.

Hermes 대화 — CLI 나 메신저 어디서든
/excalidraw sketch the request flow for our API

뜻: (excalidraw 스킬로) 우리 API 의 요청 흐름을 그려 줘

/axolotl help me fine-tune Llama 3 on my dataset

뜻: (axolotl 스킬로) 내 데이터로 Llama 3 를 미세 조정하는 것을 도와줘

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

뜻: (github-pr-workflow 스킬로) 인증 부분을 고친 작업의 PR 을 만들어 줘

/youtube-content summarize https://youtu.be/dQw4w9WgXcQ

뜻: (youtube-content 스킬로) 이 영상을 요약해 줘

앞의 /이름 이 스킬이고, 그 뒤가 내 부탁입니다. 위 네 줄은 원문의 예시입니다.

Hermes 대화
/excalidraw

부탁 없이 스킬 이름만 넣으면, 스킬을 불러온 뒤 에이전트가 무엇이 필요한지 나에게 묻습니다.

Hermes 대화
/github-pr-workflow /test-driven-development fix issue #123 and open a PR

뜻: 두 스킬을 함께 불러서, 이슈 123번을 고치고 PR 을 열어 줘

메시지 맨 앞에 /스킬 을 이어 쓰면 앞쪽의 스킬을 모두(최대 5개) 불러오고, 나머지 글이 내 부탁이 됩니다. 아래 그림에서 읽는 규칙을 봅니다.

터미널
hermes chat --toolsets skills -q "What skills do you have?"

뜻: 어떤 스킬을 갖고 있어?

hermes chat --toolsets skills -q "Show me the axolotl skill"

뜻: axolotl 스킬을 보여 줘

슬래시 명령을 몰라도 됩니다. 원문은 “자연스러운 대화로도 스킬을 다룰 수 있다”며 위 두 명령을 예로 듭니다. --toolsets skills 는 스킬용 툴셋(toolset — 도구 꾸러미)을 쓰겠다는 뜻입니다(4장 「툴셋」).

여러 스킬을 한 줄에 쓸 때 읽는 규칙

① 앞쪽에 이어진 /스킬 은 모두 불러옵니다 (최대 5개) /github-pr-workflow /test-driven-development fix issue #123 and open a PR 스킬 ① 스킬 ② 나머지 = 내 부탁 ② 설치된 스킬이 아닌 낱말을 만나면 거기서 멈춥니다 /ocr-and-documents ~/.hermes/cache/scratch/scan.pdf extract the tables 스킬 1개 전부 내 부탁 — 파일 경로와 “표를 뽑아 줘” 그래서 / 가 들어간 파일 경로 같은 글이 스킬 이름으로 잘못 읽히는 일이 없습니다
초록 테두리 칸이 스킬, 나머지 칸이 부탁입니다. Hermes 는 왼쪽부터 읽다가 스킬이 아닌 첫 낱말에서 스킬 읽기를 끝냅니다.
늘 같은 조합을 쓴다면 매번 여러 스킬을 이어 쓰는 대신 스킬 번들로 묶으면 짧은 명령 하나로 같은 효과를 냅니다.

Skills Hub 에서 찾아 설치하기

Skills Hub 는 스킬을 둘러보고, 찾고, 설치하고, 관리하는 곳입니다. 원문은 온라인 등록소들, skills.sh, 웹사이트가 직접 내주는 스킬 목록(well-known), 그리고 Hermes 의 공식 선택 스킬(official optional skills)을 다룬다고 적습니다. 흐름은 네 걸음입니다.

① 둘러보거나 찾습니다

hermes skills browse
hermes skills search kubernetes

첫 줄은 Hub 의 스킬을 모두 둘러봅니다(공식 스킬이 먼저 나옵니다). 둘째 줄은 낱말(여기서는 kubernetes)로 모든 출처를 검색합니다.

② 설치 전에 미리 봅니다

hermes skills inspect openai/skills/k8s

설치하지 않고 내용을 먼저 살핍니다. 정보가 있으면 원본 저장소 주소, 설치 명령, 주간 설치 수, 원본 쪽 보안 점검 상태 같은 것도 함께 보여 줍니다.

③ 설치합니다

hermes skills install openai/skills/k8s

설치 과정에 보안 검사가 들어 있습니다. Hub 로 설치하는 스킬은 모두 이 검사를 거칩니다 — 안전 소절.

④ 쓰고, 관리합니다

hermes skills list --source hub
hermes skills check
hermes skills update
hermes skills uninstall k8s

설치된 스킬은 곧바로 슬래시 명령으로 부를 수 있습니다(스킬 쓰기). 위 네 줄은 차례로 Hub 로 설치한 스킬 목록 보기, 원본에 새 버전이 있는지 확인, 새 버전으로 갱신, 스킬 제거입니다.

스킬 주소 읽는 법

install 뒤에 적는 글은 “어느 출처의 어느 스킬인가”를 가리키는 주소입니다.

official/ security/1password Hermes 공식 선택 스킬Hermes 저장소에서 관리 · 내장 수준의 신뢰 skills-sh/ vercel-labs/json-render/… skills.sh 목록Vercel 의 공개 스킬 목록 openai/skills/k8s GitHub 저장소 / 경로소유자/저장소/스킬 폴더 순서 https://sharethis.chat/SKILL.md 웹 주소 그대로SKILL.md 가 있는 주소를 바로 적음 앞머리(official/ · skills-sh/ …)가 출처를 알려 줍니다 — 전체 출처 목록은 아래 접힌 상자
네 주소 모두 원문의 예시입니다. 출처에 따라 설치할 때 적용되는 신뢰 등급이 달라집니다.

대화 안에서, 그리고 웹사이트에서

지금까지의 명령은 터미널에 넣는 것이고, 대화 안에서는 같은 명령을 /skills 로 씁니다. 원문은 “모든 같은 명령이 /skills 로도 동작한다”고 적습니다.

Hermes 대화
/skills browse
/skills search react --source skills-sh
/skills inspect skills-sh/vercel-labs/json-render/json-render-react
/skills check
/skills update
/skills list

차례로: 둘러보기 · 검색 · 미리 보기 · 새 버전 확인 · 갱신 · 목록

공개 Skills Hub 웹사이트의 설치 가능한 카드마다 Install in Hermes(Hermes 에 설치) 단추가 있습니다. 누르면 Hermes Desktop(Hermes 데스크톱 앱)이 열리며 확인 창이 뜹니다.

Hermes Desktop — 원문에 적힌 글귀만 옮긴 흉내

Install “skill-name”?

Source출처 — 어디서 받는 스킬인지
Install to설치할 곳

확인하면 Installing… → Installed 와 완료 알림 · Cancel(취소)을 누르면 아무것도 바뀌지 않음

오류가 나면 창에 그대로 남아 다시 시도할 수 있습니다. 실제 창의 모양은 원문에 없어 위 그림은 글귀만 옮겼습니다. 앱이 없거나 링크를 알아보지 못하면, 카드를 펼쳐 거기 적힌 CLI 설치 명령을 복사해 터미널에서 씁니다.

--force 는 “읽어 봤고 괜찮다”는 뜻일 때만 원문 예시에는 --force 가 붙은 설치 명령이 있습니다. 이것은 보안 검사의 가벼운 경고를 넘기는 옵션입니다. 무엇을 넘길 수 있고 무엇은 못 넘기는지 안전 소절에서 먼저 확인하세요.
한눈에 정리
  • 스킬은 일하는 방법을 적은 설명서(SKILL.md)입니다. 딸려 온 것·Hub 에서 설치한 것·에이전트가 만든 것이 모두 ~/.hermes/skills/ 에 모입니다.
  • 기억은 항상 실리는 작은 사실, 스킬은 관련 있을 때만 불러오는 긴 절차입니다.
  • 설치된 스킬은 저절로 슬래시 명령이 됩니다 — /스킬이름 부탁. 앞쪽에 이어 쓴 스킬은 최대 5개까지 함께 불러옵니다.
  • /learn 은 폴더·웹 주소·방금 한 일·메모·책을 가리키면 에이전트가 스킬로 써 줍니다. 큰 자료는 참고 파일로 나뉜 지식 창고형 스킬이 됩니다.
  • 불러오기는 3단계입니다: 목록(이름·한 줄 설명·분류, 약 3천 토큰) → 스킬 하나의 본문 → 참고 파일 하나. 전체 내용은 정말 필요할 때만 읽습니다.
  • SKILL.md 는 머리말(이름·설명·버전)과 본문(언제 쓰나·순서·함정·확인)으로 되어 있습니다.
  • Skills Hub: hermes skills browse/search → inspect → install. 대화 안에서는 같은 명령을 /skills 로 씁니다.
  • 갱신할 때 내가 고친 스킬은 덮어쓰지 않습니다. 원본으로 바꾸려면 --force(Hub 스킬)나 reset --restore(딸림 스킬)를 씁니다.
  • 에이전트는 skill_manage 로 스스로 스킬을 만들고 고칩니다. 내가 확인하고 싶으면 /skills approval on, 한 스킬을 못 바꾸게 하려면 잠급니다.
  • 번들은 여러 스킬을 명령 하나로 부르는 별명입니다. 스킬을 설치해 주지는 않습니다.
  • Hub 설치는 모두 보안 검사를 거칩니다. --force 는 가벼운 차단만 넘기고 dangerous 판정은 넘기지 못합니다.

이 장의 나머지 소절과 🔧 세부는 완전 가이드 6장에 있습니다.

CHAPTER 07

예약 작업과 위임

Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 도구를 써서 내 대신 일해 주는 AI 프로그램)는 내가 화면 앞에 없을 때에도 일할 수 있고, 한 가지 일을 여러 갈래로 나눠 동시에 할 수도 있습니다. 앞쪽이 예약 작업(cron — 정해 둔 시간에 자동 실행), 뒤쪽이 위임(delegation — 일을 나눠 다른 에이전트에게 맡기기)입니다. 이 장은 두 기능이 각각 무엇이고, 어떻게 시키고, 결과를 어디서 받는지를 설명합니다.

예약 작업이란 — 정해 둔 시간에 Hermes 가 혼자 하는 일

예약 작업(cron — 정해 둔 시간에 자동 실행)은 정해 둔 시간에 Hermes 가 혼자 실행하는 일입니다. “매일 아침 9시에 뉴스를 요약해 줘”, “30분 뒤에 빌드를 확인하라고 알려 줘”처럼 언제와 무엇을을 한 번 정해 두면, 그 시간이 될 때마다 Hermes 가 일을 하고 결과를 정해 둔 곳으로 보냅니다. 일정은 평소 쓰는 말(원문 예시는 모두 영어)이나 cron 표현식(‘0 9 * * *’ 처럼 칸을 나눠 시각을 적는 표기법)으로 적습니다.

아주 쉽게 말하면 알람 시계 옆에 쪽지를 붙여 두는 것과 같습니다. 알람이 울리면 비서가 쪽지에 적힌 것만 보고 일을 시작합니다. 어제 나와 나눈 이야기는 기억하지 못합니다. 일을 마치면 결과를 내가 정해 둔 우편함(대화방이나 파일)에 넣어 둡니다.

원문이 꼽는 “예약 작업으로 할 수 있는 일”은 다음과 같습니다.

한 번만 · 되풀이

“30분 뒤 한 번”도, “2시간마다 계속”도 됩니다.

멈춤 · 다시 시작 · 고치기

지우고 새로 만들 필요 없이 멈추고, 고치고, 지금 바로 돌려 보고, 지울 수 있습니다.

스킬 붙이기

스킬(일하는 방법을 적은 설명서)을 0개, 1개, 여러 개 붙일 수 있습니다.

결과 보낼 곳 고르기

작업을 만든 그 대화, 내 컴퓨터 파일, 연결해 둔 메신저로 보냅니다.

이 밖에 지금 돌고 있는 한 번만 멈추기, AI 없이 스크립트만 돌리기도 됩니다. 이 모든 것을 Hermes 자신이 도구(tool — 에이전트가 쓰는 기능 하나)로 할 수 있어, 터미널 명령을 몰라도 말로 부탁해서 만들고 멈추고 고치고 지울 수 있습니다.

어떻게 도나. 예약 작업을 실제로 실행하는 것은 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)입니다. 게이트웨이는 60초마다 예약 목록을 확인하고, 때가 된 작업이 있으면 작업마다 따로 떨어진 새 세션(session — 대화 한 묶음)을 열어 실행합니다.

게이트웨이 계속 켜 두는 프로그램 60초마다 목록 확인 예약 목록 jobs.json 파일 09:00 뉴스 요약 2시간마다 서버 확인 30분 뒤 알림 한 번 새 세션에서 실행 이전 대화 기억 없음 프롬프트 + 붙인 스킬만 보고 끝까지 일함 결과 전달 마지막 답을 보냄 원래 대화 내 컴퓨터 파일 메신저 초록 점 = 지금 때가 된 작업
예약 작업 한 번의 흐름. 게이트웨이가 꺼져 있으면 맨 왼쪽 시계가 멈추므로 아무 작업도 시작되지 않습니다.

여기서 꼭 기억할 것이 세 가지 있습니다.

기억할 것뜻
게이트웨이가 켜져 있어야 돈다hermes gateway install(사용자 서비스로 설치해 계속 켜 두기) 또는 hermes gateway(지금 창에서 직접 실행). 서비스로 켜 두는 법은 8장에서 다룹니다.
매번 완전히 새 세션이다이전 실행도, 나와 나눈 대화도 기억하지 못합니다. 필요한 것은 프롬프트(prompt — 그때 Hermes 에게 줄 지시문)와 붙인 스킬에 모두 들어 있어야 합니다.
예약 작업 안에서는 예약 작업을 또 만들 수 없다예약이 끝없이 불어나는 것을 막기 위해, 예약으로 실행된 세션에서는 예약 관리 도구가 꺼져 있습니다(설정으로 풀 수 있음 — 관리 소절의 접힌 상자).

예약 작업 만들기 — 세 가지 방법

예약 작업 하나는 일정(언제)과 프롬프트(그때 Hermes 에게 줄 지시문) 두 가지로 이루어집니다. 스킬, 결과 받을 곳(--deliver), 이름(--name)은 골라서 붙입니다. 만드는 길은 세 가지이고 결과는 같습니다.

Hermes 와 대화하다가 평소처럼 부탁합니다. 가장 쉬운 방법입니다.

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

뜻: 매일 아침 9시에 Hacker News 에서 AI 소식을 확인하고 Telegram 으로 요약을 보내 줘. — Hermes 가 안에서 예약 관리 도구를 써서 등록합니다.

대화 입력 칸에 슬래시 명령(/ 로 시작해 넣는 명령) /cron add "일정" "프롬프트" 를 넣습니다.

/cron add "in 30m" "Remind me to check the build"
/cron add "every 2h" "Check server status"
/cron add "every 1h" "Summarize new feed items" --skill blogwatcher

뜻(위에서부터): 30분 뒤에 빌드를 확인하라고 알려 줘 / 2시간마다 서버 상태 확인 / 1시간마다 새 피드 글 요약(blogwatcher 스킬을 붙여서).

대화 밖, 터미널(글자로 명령을 입력하는 창)에서 바로 만듭니다. 일정과 프롬프트를 이 순서로 적습니다.

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

뜻: 2시간마다 서버 상태 확인. 스킬은 끝에 --skill blogwatcher 처럼 붙입니다.

처음 만들어 보는 순서. 원문에 있는 명령만으로 한 바퀴를 돌면 이렇습니다.

1. 게이트웨이를 켭니다

예약 작업은 게이트웨이가 실행합니다.

hermes gateway install     # 사용자 서비스로 설치
hermes gateway             # 또는 지금 창에서 직접 실행

2. 짧은 예약을 하나 만듭니다

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

뜻: 30분 뒤에 빌드를 확인하라고 알려 줘.

3. 등록됐는지 봅니다

/cron list          # 대화 안에서
hermes cron list    # 터미널에서
hermes cron status  # 스케줄러가 살아 있는지, 가장 가까운 다음 실행이 언제인지

4. 기다리지 않고 한 번 돌려 봅니다

/cron run <job_id>

<job_id> 자리에 목록의 작업 ID 나 이름을 넣습니다. 다음 확인 때 실행되고, 덤으로 한 번 더 도는 것이라 원래 예약은 그대로 남습니다.

5. 결과를 받습니다

메신저에서 만든 작업은 기본으로 그 대화에 결과가 옵니다. 터미널(CLI)에서 만든 작업은 기본으로 내 컴퓨터 파일(~/.hermes/cron/output/)에만 저장됩니다. 받을 곳을 바꾸는 법은 결과를 어디로 받나에 있습니다.

프롬프트는 혼자서도 이해되게 씁니다. 예약 작업은 완전히 새 세션에서 돌기 때문에, 붙인 스킬이 알려 주지 않는 것은 모두 프롬프트에 들어 있어야 합니다. 원문의 나쁜 예와 좋은 예입니다.

❌ 나쁜 예

"Check on that server issue"

뜻: 그 서버 문제 좀 확인해 줘. — ‘그’ 문제가 무엇인지 새 세션은 알 길이 없습니다.

✅ 좋은 예

"SSH into server 192.168.1.100 as user 'deploy', check if nginx is running with 'systemctl status nginx', and verify https://example.com returns HTTP 200."

뜻: 어느 서버에 어떤 사용자로 들어가, 어떤 명령으로 무엇을 확인하고, 어느 주소가 정상 응답(200)을 주는지 볼지까지 다 적었습니다.

스킬을 붙이면 프롬프트가 짧아집니다. --skill 이름 을 달면 실행 전에 그 스킬을 먼저 읽습니다. 대화에서 /스킬이름 으로 부를 때와 똑같이 읽힙니다. 긴 절차를 프롬프트에 통째로 적지 않아도 됩니다(스킬은 6장).

프롬프트는 등록 전에 검사됩니다 예약 작업 프롬프트는 만들 때와 고칠 때 검사를 거칩니다. 눈에 안 보이는 유니코드 문자를 쓴 속임수, SSH 뒷문을 만들려는 시도, 비밀 값을 빼돌리려는 뻔한 내용이 들어 있으면 등록이 막힙니다.

위임이란 — 일을 나눠 하위 에이전트에게 맡기기

위임(delegation)은 Hermes 가 일의 한 덩어리를 떼어 하위 에이전트(subagent — 일을 나눠 받은 별도 에이전트)에게 맡기는 것입니다. Hermes 는 delegate_task 라는 도구로 하위 에이전트를 만듭니다. 하위 에이전트는 저마다 새 대화에서, 자기만의 터미널 세션을 갖고 따로 일합니다. 일을 마치면 마지막 요약만 부모(일을 맡긴 쪽 — 나와 대화하던 Hermes)의 컨텍스트(context — 모델이 한 번에 기억하며 볼 수 있는 글의 양)로 돌아옵니다.

아주 쉽게 말하면 팀장이 팀원 셋에게 쪽지로 일을 나눠 주는 것과 같습니다. 팀원들은 회의에 없었으므로 쪽지에 적힌 것만 압니다. 각자 자기 책상에서 일하고, 끝나면 보고서 한 장만 팀장 책상에 올려 둡니다. 팀장 책상에는 팀원들이 뒤적인 자료 더미가 아니라 보고서 세 장만 쌓입니다.
부모 에이전트 나와 대화하는 Hermes 지금까지의 긴 대화 읽은 파일 · 쓴 도구의 결과 + 돌아온 요약 3개 맡겨 두고 대화는 계속 일감 쪽지 (goal + context) 마지막 요약만 돌아옴 하위 에이전트 ①새 대화 · 자기 터미널 세션예: 주제 A 조사 하위 에이전트 ②새 대화 · 자기 터미널 세션예: 주제 B 조사 하위 에이전트 ③새 대화 · 자기 터미널 세션예: 빌드 고치기
보라 점이 일감 쪽지, 초록 점이 요약입니다. 하위 에이전트가 일하면서 읽고 시도한 것들은 부모의 대화에 쌓이지 않습니다.

왜 쓰나. 좋아지는 점은 세 가지입니다.

부모의 기억 공간을 아낍니다

파일 수십 개를 고치는 일을 부모가 직접 하면 그 과정이 부모의 대화를 가득 채웁니다. 맡기면 요약만 들어와 토큰이 덜 듭니다.

여러 일을 동시에 합니다

서로 상관없는 일 여러 개를 한꺼번에 맡길 수 있습니다. 기본으로 최대 10개가 동시에 돕니다.

대화가 막히지 않습니다

맡긴 일은 뒤에서 돕니다. Hermes 는 손잡이(handle)만 곧바로 돌려받아 대화를 이어 가고, 결과는 나중에 새 메시지로 올라옵니다.

어떻게 쓰나. 따로 시킬 필요가 없습니다. 원문은 “에이전트가 일의 복잡도를 보고 알아서 위임하므로, 위임하라고 일부러 말하지 않아도 된다”고 적습니다. 흐름은 이렇습니다.

1. Hermes 가 일감을 적어 맡깁니다

Hermes 가 안에서 도구를 부릅니다(내가 치는 명령이 아닙니다). goal 은 해 달라는 일, context 는 그 일에 필요한 배경입니다.

delegate_task(
    goal="Debug why tests fail",
    context="Error: assertion in test_foo.py line 42"
)

뜻: 테스트가 왜 실패하는지 찾아 줘 / 배경: test_foo.py 42번째 줄에서 오류.

2. 손잡이만 받고 대화는 계속됩니다

맡긴 일은 자동으로 뒤에서 돕니다. Hermes 는 곧바로 손잡이를 돌려받으므로, 나는 기다리지 않고 다른 이야기를 이어 갈 수 있습니다.

3. 하위 에이전트가 따로 일합니다

새 대화에서, 자기 터미널 세션으로, 부모가 켜 둔 도구 범위 안에서 일합니다. 부모와 나눈 이야기는 모릅니다 — 무엇을 알고 무엇을 모르나.

4. 요약이 새 메시지로 돌아옵니다

무엇을 했는지, 무엇을 찾았는지, 어떤 파일을 고쳤는지, 어떤 문제를 만났는지를 담은 요약이 대화에 올라오고, 부모 Hermes 가 그것을 보고 다음 일을 합니다.

언제 맞나. 원문은 위임을 execute_code(에이전트가 파이썬 코드를 짜서 기계적인 일을 한꺼번에 처리하는 도구)와 견주어 설명합니다. 한 줄로 줄이면 따져 보고 판단해야 하는 일은 위임, 정해진 대로 돌리면 되는 일은 코드 실행입니다.

견줄 점위임 (delegate_task)코드 실행 (execute_code)
생각하는 힘AI 가 처음부터 끝까지 따져 가며 일함파이썬 코드만 실행
쓸 수 있는 도구막히지 않은 모든 도구도구 7개
동시에기본 10개까지(조절 가능)스크립트 하나
토큰 비용더 큼더 작음(출력만 돌아옴)
맞는 일판단이 필요한 복잡한 일기계적인 여러 단계 처리
한눈에 정리
  • 예약 작업은 정해 둔 시간에 Hermes 가 혼자 하는 일입니다. 게이트웨이가 60초마다 목록을 확인하므로 게이트웨이가 켜져 있어야 돕니다.
  • 일정 + 프롬프트로 이루어지고, 말로 부탁하거나 /cron add, hermes cron create 로 만듭니다. 매번 새 세션이라 프롬프트는 혼자서도 이해되게 씁니다.
  • 일정은 in 30m(한 번) · every 2h(되풀이) · weekdays at 9am(요일·시각) · 0 9 * * *(cron 표현식)으로 적습니다.
  • 에이전트의 마지막 답이 자동으로 전달됩니다. 메신저에서 만들면 그 대화, CLI 에서 만들면 내 컴퓨터 파일이 기본입니다.
  • pause 는 앞으로의 실행을, cancel 은 지금 도는 실행을 멈춥니다. 안 돌 때는 hermes cron status → list → doctor 순으로 봅니다.
  • 위임은 일을 하위 에이전트에게 나눠 맡기는 것입니다. 하위 에이전트는 새 대화에서 따로 일하고 요약만 돌려줍니다.
  • 하위 에이전트는 쪽지(goal + context)에 적힌 것만 알고 나에게 되묻지 못합니다. 묶어 맡기면 기본 10개까지 동시에 돕니다.
  • 뒤에서 도는 위임은 /agents 로 보고 /stop 으로 멈춥니다. Hermes 가 꺼지면 이어지지 않으니, 살아남아야 하는 일은 예약 작업으로 만듭니다.

이 장의 나머지 소절과 🔧 세부는 완전 가이드 7장에 있습니다.

CHAPTER 08

메신저에서 쓰기 — 게이트웨이와 Telegram

Hermes Agent 는 터미널(글자로 명령을 입력하는 창) 앞에 앉아 있을 때만 쓰는 프로그램이 아닙니다. 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)를 켜 두면 휴대폰의 Telegram 같은 메신저에서 Hermes 에게 말을 걸고 답을 받을 수 있습니다. 이 장은 게이트웨이가 무엇인지, 어떤 메신저를 쓸 수 있는지, 그리고 Telegram 봇을 만들어 연결하는 순서를 처음부터 끝까지 따라갑니다.

게이트웨이란 무엇인가 — 왜 계속 켜 두나

Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 말만 하는 챗봇과 달리 도구를 써서 내 대신 일을 해 주는 AI 프로그램)와 대화하는 기본 창구는 터미널입니다. 그런데 밖에서 휴대폰으로 일을 시키고 싶을 때가 있습니다. 이때 필요한 것이 게이트웨이입니다. 원문은 게이트웨이를 이렇게 정의합니다 — “설정해 둔 모든 플랫폼(여기서는 메신저 서비스 하나하나)에 연결하고, 세션(대화 한 묶음)을 관리하고, 예약 작업(cron — 정해 둔 시간에 자동 실행)을 돌리고, 음성 메시지를 전달하는 하나의 백그라운드 프로그램(화면 뒤에서 조용히 계속 도는 프로그램)”.

아주 쉽게 말하면 게이트웨이는 회사의 안내 데스크입니다. 전화·문자·방문(여러 메신저)으로 들어오는 연락을 한 사람이 모두 받아 담당자(Hermes)에게 넘기고, 담당자의 답을 연락 온 길 그대로 돌려줍니다. 안내 데스크가 자리를 비우면 아무리 연락해도 받을 사람이 없습니다. 그래서 게이트웨이는 계속 켜 둡니다.
내 휴대폰·PC 의 메신저 Telegram내 봇과 나누는 대화 Discord · Slack팀이 쓰는 채널 WhatsApp · Email …그 밖의 메신저 게이트웨이 hermes gateway · 계속 켜 둠 ① 메신저와 연결 유지 ② 대화별 세션 보관 ③ 예약 작업 · 60초마다 ④ 음성 메시지 전달 메시지 → ← 답 AI 에이전트 모델로 생각하고 도구로 일합니다 메시지가 오면 → 게이트웨이가 받아 → 에이전트에게 넘기고 → 답을 같은 대화방으로 돌려보냅니다
게이트웨이 하나가 설정해 둔 메신저 전부를 맡습니다. 메신저마다 프로그램을 따로 켤 필요가 없습니다.

게이트웨이가 하는 일을 원문 순서대로 풀면 네 가지입니다.

① 메신저와 연결

메신저마다 메시지를 받아 오는 담당 부품이 있고, 게이트웨이가 이것들을 한꺼번에 돌립니다.

② 세션 관리

대화방마다 세션을 따로 보관합니다. 그래서 Hermes 가 앞에서 나눈 이야기를 기억한 채 이어 갑니다.

③ 예약 작업 실행

60초마다 “지금 실행할 예약 작업이 있나”를 확인해 실행합니다(7장).

④ 음성 메시지 전달

내가 보낸 음성을 글로 바꾸고, Hermes 의 답을 음성으로 돌려줄 수 있습니다(음성 메시지).

왜 계속 켜 두어야 할까요? 메시지를 받는 것도, 예약 작업 시계를 돌리는 것도 게이트웨이이기 때문입니다. 게이트웨이가 꺼져 있으면 두 가지가 함께 멈춥니다.

게이트웨이가 켜져 있을 때 ✓ 메신저로 보낸 말에 답이 옵니다 ✓ 예약 작업이 제시간에 실행됩니다 ✓ 그 결과가 홈 채널로 도착합니다 60초마다 실행할 예약 작업이 있는지 확인 꺼져 있을 때 ✗ 메시지를 받을 프로그램이 없습니다 ✗ 예약 작업 시계도 함께 멈춥니다 ✗ 꺼진 동안 온 Telegram 메시지는 다음에 켤 때 버려집니다 (기본값) 밤에 끄는 컴퓨터라면 설정으로 바꿀 수 있습니다
Telegram 은 게이트웨이가 꺼진 동안 온 메시지를 서버에 쌓아 두지만, Hermes 는 기본값으로 다음에 켜질 때 그 묶음을 버립니다. 바꾸는 설정은 봇 만들기의 접힌 표에 있습니다.
봇에게도 두뇌와 도구가 필요합니다 원문 안내: 봇에는 모델 제공자(provider — AI 모델을 빌려주는 서비스)와 도구 제공자(음성 읽어 주기 TTS, 웹 검색 등)가 모두 필요하며, Nous Portal 구독에는 이것들이 함께 들어 있습니다. 제공자를 아직 정하지 않았다면 1장부터 마치고 오세요.

빠른 설정 — hermes gateway setup

메신저를 연결하는 가장 쉬운 방법은 대화형 설정 마법사(질문에 차례로 답하면 설정을 대신 적어 주는 화면)입니다. 터미널(글자로 명령을 입력하는 창)에 아래 한 줄을 입력합니다. Hermes 설치(1장)가 끝나 있어야 합니다.

hermes gateway setup        # Interactive setup for all messaging platforms

뜻: 모든 메신저를 대화형으로 설정합니다.

1. 마법사를 엽니다

터미널에 hermes gateway setup 을 입력하고 Enter 를 누릅니다. 마법사는 메신저 목록을 보여 주고, 이미 설정된 메신저가 어느 것인지도 표시합니다.

2. 화살표 키로 메신저를 고릅니다

위·아래 화살표 키로 연결할 메신저를 고릅니다. 마법사가 그 메신저에 필요한 값을 묻습니다. Telegram 이라면 봇 토큰과 허용할 사용자 ID 두 가지입니다 — 이 둘을 준비하는 방법이 이 장 뒤쪽의 봇 만들기와 사용자 ID 알아내기입니다.

3. 설정이 저장됩니다

답한 값은 마법사가 설정 파일에 대신 적어 줍니다. 파일을 직접 열어 고칠 필요가 없습니다.

4. 게이트웨이를 켭니다

마법사는 끝날 때 게이트웨이를 시작(또는 다시 시작)할지 묻습니다. 켜고 나면 메신저에서 봇에게 말을 걸어 봅니다.

마법사 밖에서 게이트웨이를 다룰 때 쓰는 명령은 여섯 개만 알면 됩니다.

명령하는 일언제 쓰나
hermes gateway setup메신저를 대화형으로 설정메신저를 처음 연결하거나 추가할 때
hermes gateway지금 이 터미널 창에서 게이트웨이를 실행(foreground — 창을 차지한 채 실행)잘 되는지 시험해 볼 때
hermes gateway install서비스(컴퓨터가 알아서 켜 주는 프로그램)로 설치 — Linux 는 사용자 서비스, macOS 는 launchd 서비스계속 켜 두려 할 때
hermes gateway start설치한 서비스를 시작서비스로 설치한 뒤 켜고 · 끄고 · 상태를 볼 때
hermes gateway stop서비스를 멈춤
hermes gateway status서비스 상태 확인
처음에는 이렇게 ① hermes gateway setup 으로 설정하고 → ② 마법사가 켜 준 게이트웨이(또는 hermes gateway)로 봇이 답하는지 확인한 다음 → ③ 마음에 들면 서비스로 설치해 계속 켜 둡니다.

Telegram 봇 만들기 — BotFather

Telegram 에서 Hermes Agent 와 대화하려면 먼저 봇(bot — Telegram 안에서 프로그램이 대신 답하는 계정)을 하나 만들어야 합니다. 내가 이 봇에게 말을 걸면, 봇 뒤에서 게이트웨이(메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)가 메시지를 받아 Hermes 에게 넘깁니다. 연결하고 나면 어느 기기에서든 대화하고, 음성 메모를 보내면 자동으로 받아 적히고, 예약 작업 결과를 받고, 그룹 대화에서도 쓸 수 있습니다. 글·음성·이미지·첨부 파일을 지원합니다.

봇은 @BotFather 에게서 만듭니다. BotFather 는 Telegram 이 직접 운영하는 공식 봇 관리 도구이고, 모든 Telegram 봇은 BotFather 가 내주는 API 토큰(봇을 조종할 수 있는 긴 비밀 문자열 — 봇의 열쇠)이 있어야 합니다.

1. BotFather 를 찾습니다

Telegram 을 열고 @BotFather 를 검색합니다. 또는 t.me/BotFather 주소로 들어갑니다.

2. /newbot 을 보냅니다

Telegram — BotFather (흐름을 흉내 낸 그림)
/newbot
BotFather(봇의 표시 이름을 묻습니다)

3. 표시 이름을 정합니다

봇의 표시 이름입니다. 아무것이나 됩니다. 원문 예: Hermes Agent.

Telegram — BotFather (흐름을 흉내 낸 그림)
Hermes Agent
BotFather(이번에는 사용자 이름을 묻습니다)

4. 사용자 이름을 정합니다

@ 뒤에 붙는 봇의 사용자 이름입니다. 다른 봇과 겹치면 안 되고, 반드시 bot 으로 끝나야 합니다. 원문 예: my_hermes_bot.

5. API 토큰을 받습니다

BotFather 가 토큰을 답으로 보내 줍니다. 이런 모양입니다.

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

이 문자열을 복사해 둡니다. Hermes 에 연결하기에서 씁니다.

봇 토큰은 비밀번호처럼 다룹니다 이 토큰을 가진 사람은 누구든 내 봇을 조종할 수 있습니다. 대화방·문서·화면 공유에 올리지 마세요. 새어 나갔다면 곧바로 BotFather 에서 /revoke 로 무효로 만듭니다.
더 쉬운 길 — QR 로 만들기 대시보드와 데스크톱 앱의 Messaging → Telegram(메신저 → Telegram) 쪽에는 Create with QR(QR 로 만들기) 버튼이 있습니다. Telegram 으로 코드를 찍으면(또는 링크를 열면) Hermes 가 봇을 만들고, 내 Telegram 사용자 ID 를 알아내고, 설정 파일에 두 값을 적고, 게이트웨이를 다시 시작합니다. 원문은 이 화면을 이 정도로만 적습니다. 봇을 직접 만들고 싶으면 위 다섯 단계를 따릅니다.

Hermes 에 연결하고 켜기

이제 재료 두 개가 모였습니다 — BotFather 가 준 봇 토큰(봇 만들기)과 내 사용자 ID(사용자 ID 알아내기). 이 둘을 Hermes 에 알려 주고 게이트웨이(메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)를 켜면 끝입니다.

① BotFather 봇 토큰을 받습니다 ② @userinfobot 내 사용자 ID(숫자)를 받습니다 ③ Hermes 설정에 넣기 TELEGRAM_BOT_TOKEN=… TELEGRAM_ALLOWED_USERS=… (마법사가 대신 적어 줍니다) ④ hermes gateway 게이트웨이를 켭니다 몇 초 안에 봇이 깨어납니다 ⑤ Telegram 에서 내 봇에게 메시지를 보내 답이 오는지 확인합니다
토큰은 “어느 봇인가”, 사용자 ID 는 “누구의 말을 들을 것인가”를 정합니다.

값을 넣는 방법은 두 가지입니다. 처음이라면 A 를 권합니다.

hermes gateway setup

물으면 Telegram 을 고릅니다. 마법사가 봇 토큰과 허용할 사용자 ID 를 묻고, 답한 내용을 설정에 대신 적어 줍니다.

~/.hermes/.env 파일(~ 는 내 홈 폴더. .env 는 비밀 값을 적어 두는 Hermes 설정 파일 — 3장)에 아래 두 줄을 넣습니다. 값은 내 것으로 바꿉니다.

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users

뜻: 첫 줄은 봇 토큰, 둘째 줄은 봇에게 말을 걸 수 있는 사용자 ID. 여러 명이면 쉼표로 이어 적습니다.

그다음 게이트웨이를 켭니다(마법사가 이미 켜 주었다면 건너뜁니다).

hermes gateway

원문에 따르면 봇은 몇 초 안에 켜집니다. Telegram 에서 내 봇에게 메시지를 보내 확인합니다.

Telegram — 내 Hermes 봇 (흐름을 흉내 낸 그림)
안녕, 들려?
내 Hermes 봇(Hermes 의 답이 오면 연결 성공입니다)
TELEGRAM_ALLOWED_USERS 는 꼭 넣습니다 이 값은 “누구의 말을 들을지”를 정하는 허용 목록입니다. 넣지 않으면 게이트웨이는 안전을 위해 모든 사용자를 거절합니다 — 나 자신도 포함됩니다. 봇이 터미널까지 쓸 수 있기 때문에 기본값이 이렇게 닫혀 있습니다.
이렇게 되면먼저 볼 것
봇이 아무 반응도 없다TELEGRAM_BOT_TOKEN 이 맞는지, 게이트웨이가 켜져 있는지 확인합니다
봇이 “unauthorized”(권한 없음)라고 답한다내 사용자 ID 가 TELEGRAM_ALLOWED_USERS 에 없습니다. @userinfobot 으로 숫자를 다시 확인합니다
봇을 늘 켜 두고 싶다hermes gateway 는 지금 창에서 실행하는 방식(foreground)입니다. 계속 켜 두려면 서비스로 설치합니다(hermes gateway install)
한눈에 정리
  • 게이트웨이는 메신저와 Hermes 를 이어 주는 하나의 프로그램입니다. 메신저 연결, 세션 관리, 예약 작업 실행(60초마다 확인), 음성 메시지 전달을 맡습니다. 꺼져 있으면 답도 예약 작업도 멈추므로 계속 켜 둡니다.
  • 쓸 수 있는 메신저는 Telegram·Discord·Slack 을 비롯해 비교표 기준 28줄이고, 메신저마다 되는 기능(음성·파일·스레드 등)이 다릅니다.
  • 시작은 hermes gateway setup 한 줄입니다. 화살표 키로 메신저를 고르고 묻는 값에 답하면 설정이 저장되고, 게이트웨이를 켤지 묻습니다.
  • Telegram 연결 순서: BotFather 에 /newbot → 봇 토큰 · @userinfobot → 내 사용자 ID(숫자) · 두 값을 Hermes 에 넣고 hermes gateway. 봇은 몇 초 안에 켜집니다.
  • 기본값은 “허용 목록에 없는 사람은 전부 거절”입니다. TELEGRAM_ALLOWED_USERS 에 내 ID 를 꼭 넣고, 봇 토큰은 비밀번호처럼 다룹니다(새면 BotFather /revoke).
  • 그룹에서 봇이 조용하면 Telegram 의 개인 정보 보호 모드부터 봅니다. 끈 뒤에는 봇을 그룹에서 내보냈다가 다시 넣어야 합니다.
  • /sethome 을 보낸 대화방이 홈 채널이 되어 예약 작업 결과를 받습니다. 음성 메시지는 자동으로 글로 바뀌어 전달됩니다.
  • 계속 켜 두려면 hermes gateway install 로 서비스로 설치하고 start · stop · status 로 관리합니다.

이 장의 나머지 소절과 🔧 세부는 완전 가이드 8장에 있습니다.

CHAPTER 09

안전장치와 되돌리기

Hermes Agent 는 말만 하는 챗봇이 아니라, 내 컴퓨터에서 명령을 실행하고 파일을 고치는 AI 에이전트(도구를 써서 내 대신 일을 해 주는 AI 프로그램)입니다. 그래서 “엉뚱한 명령을 실행하면 어쩌지?”, “모르는 사람이 내 봇에게 말을 걸면?”, “파일을 망가뜨리면?” 같은 걱정이 따라옵니다. 이 장에서는 Hermes 가 그런 일을 막으려고 둔 여덟 겹의 안전장치와, 그래도 일이 틀어졌을 때 파일을 이전 상태로 돌려놓는 체크포인트와 /rollback 을 살펴봅니다.

안전장치는 여덟 겹 — 전체 그림

원문은 Hermes 의 보안 방식을 defense-in-depth(겹겹이 막기 — 한 겹이 뚫려도 다음 겹이 막도록 여러 겹을 두는 방식)라고 부르고, 그 겹이 여덟 개라고 적습니다. 여덟 개를 외울 필요는 없습니다. 요청 하나가 “누가 말을 거는가 → 위험한 명령인가 → 어디에 쓰는가 → 어디서 실행하는가” 네 개의 문을 차례로 지나고, 그 뒤에서 네 가지 검사가 늘 함께 돈다고 보면 됩니다.

아주 쉽게 말하면 은행을 떠올려 보세요. 들어갈 때 출입증을 확인하고(누구인가), 큰돈을 옮길 때는 책임자가 서명하고(위험한 일인가), 금고에는 직원도 함부로 못 들어가고(어디에 손대는가), 위험한 작업은 따로 마련한 방에서 합니다(어디서 하는가). 문 하나만 믿지 않고 여러 겹을 두는 것 — Hermes 의 안전장치도 같은 생각입니다.
요청 하나가 지나가는 길 요청 나 · 다른 사람 ① 누구인가 사용자 허가 허용 목록 · 페어링 ② 위험한가 위험 명령 승인 먼저 나에게 묻기 ③ 어디에 쓰나 파일 쓰기 보호 비밀 파일은 금지 ④ 어디서 하나 컨테이너 격리 Docker 등 안에서 내 컴퓨터 파일 · 시스템 뒤에서 항상 함께 도는 검사 ⑤ MCP 비밀 값 거르기 외부 도구에 열쇠를 안 넘김 ⑥ 맥락 파일 검사 숨은 지시문 찾기 ⑦ 세션 간 격리 대화끼리 서로 못 봄 ⑧ 입력 검사 작업 폴더 값 확인
번호는 원문이 여덟 겹을 나열한 순서입니다. 문 네 개와 뒤쪽 검사 네 개로 나눈 것은 이해를 돕기 위한 이 가이드의 묶음입니다.
겹원문 이름쉬운 말로이 장에서
①User authorization누가 에이전트에게 말을 걸 수 있는가 — 허용 목록, DM 페어링누가 쓸 수 있나
②Dangerous command approval무언가를 망가뜨릴 수 있는 작업은 사람이 중간에서 허락승인
③File write safety파일 쓰기 도구가 손대면 안 되는 곳의 금지 목록, 그리고 원하면 켜는 쓰기 울타리파일 쓰기 보호
④Container isolationDocker·Modal(그리고 Singularity 플러그인) 같은 격리된 공간 안에서, 단단히 조인 설정으로 실행격리
⑤MCP credential filteringMCP(외부 서비스의 도구를 에이전트에 연결하는 공통 규격) 서버 프로그램에는 비밀 값을 넘기지 않음알아서 도는 방어
⑥Context file scanning프로젝트 파일 속에 숨은 “AI 를 속이는 지시문”을 찾아냄
⑦Cross-session isolation세션(대화 한 묶음)끼리 서로의 자료·상태를 볼 수 없음. 예약 작업 저장 경로도 엉뚱한 폴더로 새지 않게 막아 둠
⑧Input sanitization터미널 도구에 넘어오는 “작업 폴더” 값을 허용 목록과 대조해, 명령을 몰래 끼워 넣는 수법을 막음

내가 그때그때 답하는 것

② 위험 명령 승인. 승인 창이 뜨면 허락할지 막을지 고릅니다.

내가 미리 정해 두는 것

① 누가 내 봇을 쓸 수 있는지, ④ 명령을 내 컴퓨터에서 바로 실행할지 격리된 곳에서 실행할지.

알아서 도는 것

③ ⑤ ⑥ ⑦ ⑧. 내가 따로 답하지 않아도 뒤에서 걸러 줍니다.

체크포인트는 여덟 겹과 별개입니다 여덟 겹은 사고를 막는 장치이고, 이 장 뒤쪽의 체크포인트는 사고가 난 뒤에 되돌리는 안전망입니다. 막는 장치는 처음부터 켜져 있지만 체크포인트는 내가 켜야 동작합니다.

위험한 명령은 먼저 묻습니다 — 승인

Hermes 는 어떤 명령이든 실행하기 전에 그 명령을 위험한 패턴 목록과 견주어 봅니다. 맞는 것이 있으면 내가 분명하게 승인(approval — 위험한 명령을 실행하기 전에 나에게 묻는 것)해야만 실행됩니다. 터미널(글자로 명령을 입력하는 창)에서 Hermes 와 대화하던 중이라면 이런 창이 대화 사이에 끼어듭니다.

터미널 — 승인 창
  ⚠️  DANGEROUS COMMAND: recursive delete
      rm -rf ~/old-project
      [o]nce  |  [s]ession  |  [a]lways  |  [d]eny
      Choice [o/s/a/D]:

첫 줄은 “위험한 명령: 폴더 안까지 통째로 지우기”, 둘째 줄은 Hermes 가 실행하려는 명령입니다. ~ 는 내 홈 폴더를 뜻합니다. 마지막 줄에서 글자 하나로 답합니다.

o once — 이번 한 번만

지금 이 실행 한 번만 허락합니다.

s session — 이번 세션 동안

이 패턴을 지금 세션이 끝날 때까지 허락합니다.

a always — 앞으로 계속

영구 허용 목록에 넣습니다(config.yaml 에 저장). 이후 모든 세션에서 묻지 않고 실행됩니다.

d deny — 거부 (기본값)

명령을 막습니다. 아무것도 실행되지 않습니다.

잘 모르겠으면 once 나 deny always 로 저장한 패턴은 다음부터 조용히 통과합니다. 무슨 명령인지 확신이 설 때만 고르세요.

어떤 명령에서 묻나

원문은 승인을 부르는 패턴을 서른 개 남짓 나열합니다. 성격별로 묶으면 다음과 같습니다(전체 표는 아래 접힌 상자).

통째로 지우기

rm -r, find -delete, xargs rm

권한을 활짝 열기

chmod 777, chown -R root

디스크 포맷·덮어쓰기

mkfs, dd if=, > /dev/sd

데이터베이스 지우기

DROP TABLE, TRUNCATE TABLE, 조건(WHERE) 없는 DELETE FROM

시스템 설정·비밀 파일 덮어쓰기

/etc/, ~/.ssh/, ~/.hermes/.env 에 쓰기

서비스·프로그램 강제로 멈추기

systemctl stop, kill -9 -1, pkill -9, docker stop

내려받은 것을 바로 실행

curl ... | sh, bash -c, python -e

명령 하나가 거치는 길

실행하려는 명령 에이전트가 터미널 도구로 절대 금지 목록 Hermes 에 박혀 있음 · 못 풂 내가 정한 금지 규칙 approvals.deny 걸리면 실행하지 않음 YOLO 여도 마찬가지 안 걸리면 위험한 패턴에 맞는가? rm -r · DROP TABLE · curl | sh … 아니면 바로 실행 대부분의 명령 맞으면 — 승인 방식에 따라 off 묻지 않음 (YOLO 와 같음) smart (기본) 보조 AI 가 위험도를 판단 manual 항상 나에게 묻기 위험 낮음 진짜 위험 애매함 실행 명령이 그대로 실행됨 자동 거부 실행되지 않음 나에게 묻기 답이 없으면 300초 뒤 거부
always 로 저장해 둔 패턴은 묻는 단계를 건너뛰고 실행됩니다. 명령을 컨테이너 같은 격리된 곳에서 실행하도록 해 두었다면 위험 패턴 검사 자체를 건너뜁니다(격리).

묻는 방식 세 가지 — smart · manual · off

얼마나 자주 물을지는 설정 파일 ~/.hermes/config.yaml 의 approvals.mode 로 정합니다(설정 파일 다루는 법은 3장).

보조 AI 가 먼저 위험도를 가늠합니다. 위험이 낮은 명령(예: python -c "print('hello')")은 그 명령에 한해 자동으로 승인하고, 정말 위험한 명령은 자동으로 거부합니다. 판단이 서지 않는 경우만 나에게 승인 창을 띄웁니다.

위험한 패턴에 맞으면 언제나 나에게 묻습니다. AI 의 판단에 맡기지 않고 모든 위험 명령을 직접 보고 싶을 때 고릅니다.

승인 검사를 모두 끕니다. --yolo 로 실행한 것과 같아서, 모든 명령이 묻지 않고 실행됩니다.

원문의 경고 approvals.mode: off 는 모든 안전 확인 창을 끕니다. 믿을 수 있는 환경(CI/CD, 컨테이너 등)에서만 쓰라고 원문은 적습니다. 이 설정은 그 프로필(설정·기억·세션을 따로 쓰는 별도 Hermes 환경)의 모든 대화와 예약 작업에 적용됩니다.

대답하지 않으면 — 자동 거부

승인 창이 뜬 뒤 정해진 시간(기본 300초, 5분) 안에 답하지 않으면 그 명령은 거부된 것으로 처리됩니다. 자리를 비운 사이에 위험한 명령이 저절로 실행되는 일이 없게 하려는 것입니다.

  1. 시간이 지난 승인 창은 다시 열 수 없습니다요청은 버려지고, 에이전트는 그 턴(내 메시지 하나에 에이전트가 일하고 답하는 한 차례) 안에서 스스로 재시도하지 말라는 안내를 받습니다.
  2. 그래도 실행하려면 새 메시지로 다시 부탁합니다예: go ahead and run that now (뜻: 이제 그거 실행해 줘). 에이전트가 명령을 새로 요청하고, 새 승인 창이 뜹니다.
  3. 불이익은 없습니다시간 초과는 “거부”로 세지 않습니다. once 로 승인하면 그 한 번의 실행에만 적용됩니다.

메신저에서는 답장으로 승인합니다

Telegram 같은 메신저로 Hermes 를 쓸 때는(8장) 글자 하나를 누르는 창 대신, 에이전트가 위험한 명령의 내용을 대화방에 보내고 내 답장을 기다립니다.

메신저 대화방 (모양만 흉내 낸 그림)
Hermes 봇
(실행하려는 위험한 명령의 내용이 여기에 옵니다 — 원문은 실제 문구를 싣지 않았습니다)
나
yes
하려는 것보낼 답장 (아무거나 하나)
승인yes · y · approve · ok · go
거부no · n · deny · cancel

YOLO 모드 — 묻지 않고 실행

YOLO 모드는 지금 세션에서 위험 명령 승인 창을 모두 건너뛰는 모드입니다. 켜는 방법은 세 가지입니다.

방법어떻게적용 범위
실행 옵션hermes --yolo 또는 hermes chat --yolo 로 시작그 옵션을 받은 Hermes 프로세스(실행 중인 프로그램 하나)의 세션들
슬래시 명령(대화 입력 칸에 / 로 시작해 넣는 명령)대화 중에 /yolo — 칠 때마다 켜짐·꺼짐이 바뀜입력한 그 대화 하나만(다른 대화는 여전히 물음)
환경 변수(프로그램에 넘겨주는 이름표 달린 설정값)HERMES_YOLO_MODE=1그 값을 받은 Hermes 프로세스의 세션들
터미널 — /yolo 는 켜고 끄는 스위치
> /yolo
  ⚡ YOLO mode ON — all commands auto-approved. Use with caution.
> /yolo
  ⚠ YOLO mode OFF — dangerous commands will require approval.

뜻: “YOLO 모드 켜짐 — 모든 명령을 자동 승인합니다. 조심해서 쓰세요.” / “YOLO 모드 꺼짐 — 위험한 명령은 승인이 필요합니다.”

켜 둔 것을 잊지 않도록, YOLO 가 켜진 채 세션을 시작하면 빨간 안내 줄이 뜨고 상태 표시줄에 ⚠ YOLO 가 계속 보입니다. /yolo 는 세션과 함께 저장되어 다시 시작해도 유지되며, 메신저에서는 /new 나 /resume 으로 다음 대화를 시작하면 승인이 다시 켜집니다.

원문의 경고(danger) YOLO 모드는 그 세션의 위험 명령 안전 검사를 모두 끕니다 — 아래의 절대 금지 목록만 빼고요. 만들어지는 명령을 완전히 믿을 수 있을 때만(예: 버려도 되는 환경에서 돌리는, 충분히 검증한 자동화 스크립트) 쓰라고 원문은 적습니다.

그래도 절대 실행하지 않는 것 — 절대 금지 목록

되돌릴 수 없는 재앙이 되는 몇몇 명령은 YOLO 를 켜도, approvals.mode: off 여도, 예약 작업이 자동 승인으로 돌아도, 내가 “always” 를 골랐어도 실행하지 않습니다. 원문은 이것을 Hardline Blocklist(절대 금지 목록 — YOLO 보다도 아래에 깔린 바닥)라고 부릅니다. 승인 단계가 명령을 보기도 전에 걸러 내며, 푸는 옵션이 없습니다.

패턴왜 절대 금지인가
rm -rf / 와 뻔한 변형컴퓨터의 맨 위 폴더부터 전부 지움
rm -rf --no-preserve-root /“정말로 맨 위부터”라고 못 박은 변형
:(){ :|:& };:자기 자신을 끝없이 복제해(fork bomb) 다시 켤 때까지 컴퓨터를 멈춰 세움
쓰고 있는 시스템 디스크에 mkfs.*돌아가는 중인 시스템을 포맷
dd if=/dev/zero of=/dev/sd*실제 디스크를 0 으로 덮어씀
믿을 수 없는 주소의 내용을 시스템 맨 위에서 sh 로 넘겨 실행남이 원격에서 아무 코드나 실행하게 되는 통로 — 승인하기엔 범위가 너무 넓음

이 목록(원문은 전부는 아니라고 덧붙입니다)에 걸리면 에이전트는 이유를 설명하는 오류만 돌려받고 아무것도 실행되지 않습니다. 정말 필요한 명령이라면 에이전트 밖에서 직접 실행하라고 원문은 안내합니다.

대답할 사람이 없는 자리에서는

예약 작업(cron — 정해 둔 시간에 자동 실행)(7장), 한 번 묻고 끝나는 hermes chat -q, webhook·API 처럼 프로그램이 부르는 연결에는 승인 창에 답할 사람이 없습니다. 그래서 이런 자리의 기본값은 모두 deny(막기)이고, 막히면 에이전트는 다른 방법을 찾아야 합니다. 설정에서 approve 로 바꾸면 그 자리의 위험 명령을 모두 자동 승인합니다(설정 키는 아래 접힌 표). 절대 금지 목록은 이때도 그대로입니다.

메신저에서는 누가 쓸 수 있나

게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)를 켜면 Hermes 는 메신저 봇이 됩니다. 봇에게 말을 거는 사람은 곧 내 컴퓨터에서 일하는 에이전트에게 일을 시키는 사람이므로, 누가 봇과 대화할 수 있는지를 Hermes 가 여러 단계로 확인합니다. 기억할 것은 하나입니다 — 아무것도 정해 두지 않으면 모두 거절합니다.

게이트웨이 시작 기록 — 허용 목록이 하나도 없을 때
No user allowlists configured. All unauthorized users will be denied.
Set GATEWAY_ALLOW_ALL_USERS=true in ~/.hermes/.env to allow open access,
or configure platform allowlists (e.g., TELEGRAM_ALLOWED_USERS=your_id).

뜻: “사용자 허용 목록이 설정되지 않았습니다. 허가받지 않은 사용자는 모두 거절됩니다. 누구에게나 열려면 ~/.hermes/.env 에 GATEWAY_ALLOW_ALL_USERS=true 를 넣거나, 플랫폼별 허용 목록을 설정하세요.”

메시지가 오면 Hermes 는 보낸 사람을 아래 순서로 확인합니다. 하나라도 맞으면 통과이고, 끝까지 맞는 것이 없으면 거절입니다.

메시지를 보낸 사람 위에서부터 차례로 확인 1. 그 플랫폼이 “모두 허용”인가 예: DISCORD_ALLOW_ALL_USERS=true 2. 페어링 코드로 승인받은 사람인가 DM 페어링 승인 목록 3. 그 플랫폼의 허용 목록에 있는가 예: TELEGRAM_ALLOWED_USERS=12345,67890 4. 공통 허용 목록에 있는가 GATEWAY_ALLOWED_USERS=12345,67890 5. 전체가 “모두 허용”인가 GATEWAY_ALLOW_ALL_USERS=true 6. 여기까지 모두 아니면 → 거절 (기본값) 하나라도 맞으면 통과 Hermes 와 대화 가능
허가 확인 순서(원문의 Authorization Check Order). 처음 쓰는 사람은 2번(페어링)이나 3번(플랫폼별 허용 목록) 가운데 하나만 준비하면 됩니다.

방법 1 — 허용 목록에 사용자 ID 적기

허용 목록(allowlist — 들어와도 되는 사람의 명단)은 비밀 값 파일 ~/.hermes/.env 에 사용자 ID 를 쉼표로 이어 적습니다. 내 Telegram ID 를 찾는 방법은 8장에 있습니다.

# 플랫폼별 허용 목록
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=111222333444555666
WHATSAPP_ALLOWED_USERS=15551234567
SLACK_ALLOWED_USERS=U01ABC123

# 모든 플랫폼에 공통으로 확인하는 허용 목록
GATEWAY_ALLOWED_USERS=123456789
“모두 허용”은 정말 조심해서 DISCORD_ALLOW_ALL_USERS=true 같은 플랫폼별 “모두 허용”에 원문은 “조심해서 쓸 것”, 전체에 적용되는 GATEWAY_ALLOW_ALL_USERS=true 에는 “극도로 조심해서 쓸 것”이라고 적습니다. 켜는 순간 그 봇을 찾은 누구나 내 에이전트에게 일을 시킬 수 있습니다.

방법 2 — DM 페어링: 코드로 한 사람씩 들이기

ID 를 미리 알아내 적어 두는 대신, 페어링 코드로 그때그때 들일 수도 있습니다. 모르는 사람이 봇에게 DM(일대일 대화)을 보내면 봇이 한 번만 쓸 수 있는 코드를 주고, 봇 주인이 터미널에서 그 코드를 승인하는 방식입니다.

1단계 — 처음 온 사람이 봇에게 DM 을 보냅니다

허용 목록에 없는 사람이 봇에게 일대일 메시지를 보냅니다. 이때 봇은 일을 해 주지 않습니다.

2단계 — 봇이 8자리 페어링 코드로 답합니다

코드는 헷갈리는 글자(0/O/1/I)를 뺀 32가지 글자로 만든 8자리이고, 1시간 뒤 만료됩니다. 같은 사람은 10분에 한 번만 코드를 요청할 수 있습니다.

3단계 — 봇 주인이 터미널에서 승인합니다

hermes pairing approve telegram ABC12DEF

형식은 hermes pairing approve <플랫폼> <코드> 입니다. 승인 시도를 5번 틀리면 1시간 동안 잠깁니다. 원문은 코드가 봇 주인에게 어떻게 전해지는지는 따로 적지 않습니다.

4단계 — 그 사람은 그 플랫폼에서 계속 허용됩니다

한 번 승인된 사람은 영구히 허용됩니다. 나중에 내보내려면 아래 revoke 명령을 씁니다.

# 대기 중인 요청과 승인된 사용자 보기
hermes pairing list
# 페어링 코드 승인
hermes pairing approve telegram ABC12DEF
# 사용자의 접근 권한 거두기
hermes pairing revoke telegram 123456789
# 대기 중인 코드 모두 지우기
hermes pairing clear-pending

허가받지 않은 사람이 DM 을 보냈을 때 봇이 어떻게 굴지는 ~/.hermes/config.yaml 의 unauthorized_dm_behavior 로 정합니다.

값봇의 행동
pair페어링 코드로 답합니다. 대화형 DM 플랫폼의 기본값입니다.
ignore아무 답 없이 버립니다.
decline짧고 정중한 거절 한 번(“I can only chat with my owner” — 저는 주인하고만 대화할 수 있어요)을 보내고, 그 사람의 이후 메시지를 24시간 동안 무시합니다.

체크포인트 — 바꾸기 전에 찍어 두는 사진

Hermes 는 파일을 망가뜨릴 수 있는 작업을 하기 직전에 프로젝트의 모습을 자동으로 찍어 두었다가, 명령 하나로 그때 모습으로 되돌릴 수 있습니다. 이 사진이 체크포인트(checkpoint — 파일을 바꾸기 전에 찍어 두는 자동 스냅샷)이고, 되돌리는 명령이 /rollback 입니다.

아주 쉽게 말하면 게임의 “저장 지점”과 같습니다. 어려운 구간에 들어가기 전에 게임이 알아서 저장해 두고, 잘못되면 그 지점부터 다시 할 수 있습니다. 다만 Hermes 에서는 이 자동 저장 기능을 내가 먼저 켜 두어야 합니다.
기본은 꺼져 있습니다 원문에 따르면 체크포인트는 v2 부터 내가 켜야 동작하는(opt-in) 기능입니다. 대부분의 사용자가 /rollback 을 쓰지 않고, 사진 보관소가 시간이 지나면 디스크를 적잖이 차지하기 때문입니다. 켜지 않은 채로는 되돌릴 사진이 없습니다.
hermes chat --checkpoints

이렇게 시작한 세션에서만 체크포인트를 찍습니다. 중요한 폴더를 맡길 때만 켜고 싶을 때 알맞습니다.

checkpoints:
  enabled: true

설정 파일 ~/.hermes/config.yaml 에 위 두 줄을 넣으면 모든 세션에서 켜집니다(설정 파일 다루는 법은 3장).

언제 찍히나

체크포인트는 아래 두 종류의 일이 일어나기 직전에 자동으로 찍힙니다.

파일 도구가 파일을 바꿀 때

write_file(파일 쓰기)와 patch(파일 일부 고치기)

파괴적인 터미널 명령을 실행할 때

rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, 출력 돌리기(>), 그리고 git reset/clean/checkout

사진이 너무 많이 쌓이지 않도록, 에이전트는 한 턴에 폴더 하나당 많아야 한 장만 찍습니다. 지난 사진 이후 달라진 것이 없으면 건너뜁니다.

턴 1 — “보고서를 고쳐 줘” 찰칵 write_file patch 첫 변경 직전에 한 장만 턴 2 — “무엇을 바꿨어?” 설명만 하고 끝 파일을 안 바꾸면 안 찍음 턴 3 — “옛 폴더는 지워 줘” 찰칵 rm -r old/ 지우기 직전에 한 장 체크포인트 보관소 — ~/.hermes/checkpoints/store/ 내 프로젝트의 .git 과는 따로 — 진짜 .git 은 건드리지 않습니다
턴(내 메시지 하나에 에이전트가 일하고 답하는 한 차례)마다 폴더당 최대 한 장. 사진은 내 프로젝트가 아니라 Hermes 의 보관소에 쌓입니다.

사진은 내 프로젝트 폴더 안이 아니라 Hermes 의 보관소(~/.hermes/checkpoints/store/)에 쌓입니다. 내부적으로는 git(파일의 변경 이력을 기록하는 도구)을 쓰지만, 내 프로젝트의 진짜 .git 은 절대 건드리지 않습니다. Hermes 가 일한 모든 프로젝트가 이 보관소 하나를 함께 써서, 같은 내용은 한 번만 저장됩니다.

한눈에 정리
  • 안전장치는 여덟 겹입니다. 내가 만나는 것은 위험 명령 승인(그때그때 답함)과 사용자 허가·격리(미리 정함)이고, 나머지는 알아서 돕니다.
  • 위험한 패턴에 맞는 명령은 실행 전에 묻습니다. 선택지는 once(한 번) · session(이번 세션) · always(계속) · deny(거부, 기본). 300초 안에 답하지 않으면 거부됩니다. 메신저에서는 yes/no 같은 답장으로 답합니다.
  • 승인 방식은 smart(기본 — 보조 AI 가 먼저 판단) · manual(항상 물음) · off(묻지 않음). YOLO 모드로도 끌 수 있지만 절대 금지 목록(rm -rf / 등)은 어떤 경우에도 실행하지 않습니다.
  • 파일 쓰기 도구는 열쇠·비밀 값이 있는 곳에 쓰지 못합니다. 다만 터미널 명령까지 막아 주는 완벽한 울타리는 아닙니다.
  • 메신저 봇은 정해 두지 않으면 모두 거절합니다. 허용 목록에 ID 를 적거나, 8자리 페어링 코드를 hermes pairing approve 로 승인해 들입니다.
  • Docker 같은 격리 백엔드에서는 명령이 내 컴퓨터에 닿지 않아 위험 명령 검사를 건너뜁니다. 계속 켜 두는 봇에 권하는 방식입니다.
  • 체크포인트는 기본이 꺼짐입니다. hermes chat --checkpoints 나 checkpoints.enabled: true 로 켜면, 파일을 바꾸거나 지우기 직전에 턴마다 폴더당 한 장씩 찍습니다.
  • /rollback 으로 목록을 보고, /rollback diff N 으로 미리 본 뒤, /rollback N 으로 되돌립니다. 내가 손으로 고친 파일은 남고(--all 이면 함께 되돌림), 마지막 대화 턴도 취소됩니다. /undo 는 대화만 되감습니다.
  • 너무 넓은 폴더, 파일 5만 개 초과, 10MB 넘는 파일, 컨테이너 백엔드에서는 체크포인트가 찍히지 않거나 빠집니다.

이 장의 나머지 소절과 🔧 세부는 완전 가이드 9장에 있습니다.

CHAPTER 10

문제 해결과 자주 묻는 질문

Hermes Agent 를 쓰다가 막혔을 때 펼쳐 보는 장입니다. 공식 문서 「FAQ & Troubleshooting」 쪽에 실린 질문과 증상을 하나도 빼지 않고 증상 → 원인 → 해결 순서로 옮겼습니다. 처음부터 끝까지 읽을 필요는 없습니다. 아래 그림에서 내 증상을 찾아 그 소절만 보면 됩니다.

자주 묻는 질문 9가지

Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 도구를 써서 내 대신 일을 해 주는 AI 프로그램)를 쓰기 전에 사람들이 가장 많이 묻는 것들입니다. 이후로는 줄여서 Hermes 라고 부릅니다. 먼저 짧은 답 여섯 개를 보고, 더 궁금한 것만 아래에서 읽으면 됩니다.

얼마가 드나요?

Hermes 자체는 무료이고 오픈 소스(MIT 라이선스)입니다. 돈은 내가 고른 제공자(provider — AI 모델을 빌려주는 서비스)의 모델 사용료만 냅니다. 내 컴퓨터에서 돌리는 로컬 모델은 돌리는 데 돈이 들지 않습니다.

내 자료가 어딘가로 보내지나요?

API 호출은 내가 설정한 제공자에게만 갑니다. Hermes 는 사용 통계나 분석 자료를 수집하지 않습니다. 대화·기억·스킬은 내 컴퓨터의 ~/.hermes/ 에 저장됩니다.

인터넷 없이, 로컬 모델로 쓸 수 있나요?

네. hermes model 을 실행해 Custom endpoint(직접 주소 입력)를 고르고 내 모델 서버 주소를 넣습니다.

여러 사람이 함께 쓸 수 있나요?

네. 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)를 통해 Telegram, Discord, Slack, WhatsApp, Home Assistant 에서 여러 사람이 같은 Hermes 와 대화할 수 있습니다.

Windows·Android 에서도 되나요?

원문은 “Platform Support 쪽의 지원 표를 보라”고만 답합니다. 이 가이드는 그 쪽을 다루지 않습니다. 설치 준비물은 1장을 봅니다.

기억과 스킬은 무엇이 다른가요?

기억은 사실을, 스킬은 절차를 담습니다. 둘 다 세션이 끝나도 남습니다.

어떤 제공자를 쓸 수 있나요?

Hermes 는 OpenAI 호환 API(OpenAI 와 같은 방식으로 주고받는 접속 규격)라면 어디든 연결됩니다. 원문이 꼽는 제공자는 다음과 같습니다.

제공자원문의 설명
Nous PortalNous Research 의 구독형 창구. OAuth(비밀번호를 넘기지 않고 로그인으로 사용 권한을 주는 방식) 로그인 한 번으로 300개가 넘는 모델과 웹·이미지·TTS(글을 소리로 읽어 주는 기능)·브라우저 기능을 씁니다. 처음 쓰는 사람에게 추천
OpenRouterAPI 키(제공자가 나를 알아보는 비밀번호 같은 문자열) 하나로 수백 가지 모델을 씁니다. 여러 모델을 오가며 쓰려는 사람에게 추천
OpenAIGPT-5.4, GPT-5-codex, GPT-4.1, GPT-4o 등
AnthropicClaude 모델. 직접 API, hermes auth add anthropic 으로 하는 OAuth, OpenRouter, 또는 호환 프록시(중간에서 요청을 대신 전달해 주는 서버)
GoogleGemini 모델. gemini 제공자로 직접 API, OpenRouter, 또는 호환 프록시
z.ai / ZhipuAIGLM 모델
Kimi / Moonshot AIKimi 모델
MiniMax글로벌용과 중국용 접속 주소
로컬 모델Ollama, vLLM, llama.cpp, SGLang, 또는 OpenAI 호환 서버 아무것이나

제공자는 터미널에서 hermes model 을 실행해 고르거나, ~/.hermes/.env(~ 는 내 홈 폴더 — 비밀 값을 적어 두는 설정 파일)를 직접 고쳐서 정합니다. 고르는 과정은 1장 「제공자 고르기」에 있습니다. 제공자별 키 이름 전체는 공식 문서 Environment Variables 쪽 참고(이 가이드는 다루지 않음).

내 자료는 어디로 가나요?

내 컴퓨터 Hermes Agent 내 요청을 모델에게 전달 ~/.hermes/ 폴더 대화 · 기억 · 스킬 내 컴퓨터에 저장 API 호출 내가 설정한 제공자 예: OpenRouter · 로컬 Ollama 호출은 여기로만 갑니다 ✕ 사용 통계 · 분석 자료 Hermes 는 수집하지 않습니다
밖으로 나가는 것은 모델에게 보내는 API 호출 하나뿐이고, 그 상대는 내가 정합니다. 로컬 모델을 쓰면 그 상대도 내 컴퓨터 안에 있습니다.
API 호출은 제공자에게 갑니다 “수집하지 않는다”는 것은 Hermes 가 사용 통계·분석 자료를 모으지 않는다는 뜻입니다. 모델에게 보내는 요청(API 호출) 자체는 내가 설정한 제공자에게 갑니다. 그 상대까지 내 컴퓨터 안에 두고 싶다면 아래의 로컬 모델을 씁니다.

인터넷 없이 — 로컬 모델 연결하기

내 컴퓨터에 모델 서버(Ollama, vLLM, llama.cpp server, SGLang, LocalAI 등)를 띄워 두었다면, 터미널에서 hermes model 을 실행하고 차례로 다음과 같이 답합니다.

묻는 항목원문의 입력 예뜻
고를 것Custom endpoint (enter URL manually)주소를 직접 입력하는 방식
API base URLhttp://localhost:11434/v1내 컴퓨터(localhost)에 떠 있는 모델 서버의 주소
API keyollama원문 예시에 적힌 값
Model nameqwen3.5:27b서버에 올려 둔 모델 이름
Context length64000컨텍스트(문맥 창 — 모델이 한 번에 기억하며 볼 수 있는 글의 양) 길이. 64000 은 Hermes 가 요구하는 최솟값이고, 실제로는 내 서버의 컨텍스트 크기에 맞춰 적습니다.

Hermes 는 이 주소·제공자 설정을 config.yaml 에 저장하므로 다시 켜도 유지됩니다.

기억과 스킬의 차이

기억 (memory) — 사실

에이전트가 나, 내 프로젝트, 내 취향에 대해 알고 있는 것을 담습니다. 관련이 있을 때 자동으로 꺼내 옵니다. → 5장

스킬 (skill) — 절차

어떤 일을 어떻게 하는지 단계별로 적은 설명서입니다. 비슷한 일을 만나면 떠올려 씁니다. → 6장

여러 사람이 쓸 때 — 누가 들어올 수 있나

함께 쓸 때 접근은 두 가지로 다스립니다. 허용 목록(allowlist — 들어와도 되는 사용자 ID 를 적어 둔 목록)과 DM 페어링(DM pairing — 처음 메시지를 보낸 사용자가 접근 권한을 가져가는 방식)입니다. 방식별 차이는 메신저 봇 문제의 표에 있습니다.

설치·실행이 안 될 때

설치 방법 자체는 1장 「설치」에 있습니다. 여기서는 설치 직후에 만나는 증상을 다룹니다. 가장 흔한 것은 방금 설치했는데 hermes: command not found(hermes 라는 명령을 찾을 수 없음)가 나오는 경우입니다.

이유를 알려면 낱말 두 개만 알면 됩니다. 셸(shell — 터미널 안에서 내 명령을 받아 실행해 주는 프로그램. bash, zsh 가 대표적)은 명령 이름을 받으면 PATH(명령 이름을 입력했을 때 셸이 프로그램을 찾아보는 폴더 목록)에 적힌 폴더들만 뒤집니다. 설치 프로그램은 hermes 를 ~/.local/bin 폴더에 넣고 그 폴더를 PATH 에 추가합니다. 그런데 설치 전부터 열려 있던 터미널은 예전 목록을 그대로 들고 있습니다.

설치 프로그램이 한 일 hermes 를 ~/.local/bin 에 넣고, 그 폴더를 PATH 에 추가 설치 전부터 열려 있던 터미널 예전 PATH 목록을 그대로 기억하는 중 hermes: command not found 새 터미널 · 설정을 다시 읽은 터미널 새 PATH 목록에 ~/.local/bin 이 들어 있음 hermes 가 실행됨
설치가 잘못된 것이 아니라, 열려 있던 터미널이 새 폴더 목록을 아직 읽지 않은 것입니다.

1. 터미널 창을 새로 열거나, 설정을 다시 읽게 합니다

가장 쉬운 방법은 터미널 창을 닫고 새로 여는 것입니다. 새 창은 바뀐 PATH 를 알아서 읽습니다. 창을 그대로 쓰고 싶다면 내 셸에 맞는 줄 하나를 입력합니다.

source ~/.bashrc    # bash 를 쓰는 경우
source ~/.zshrc     # zsh 를 쓰는 경우

확인: hermes 를 입력했을 때 command not found 가 더 나오지 않습니다.

2. 그래도 안 되면 설치 위치를 확인합니다

which hermes
ls ~/.local/bin/hermes

첫 줄은 “셸이 hermes 를 어디에서 찾았는지”, 둘째 줄은 “설치 폴더에 파일이 실제로 있는지”를 보여 줍니다.

확인: 둘째 줄이 파일을 보여 주는데 첫 줄이 아무것도 찾지 못한다면, 파일은 있고 PATH 에만 빠진 것입니다 → 3단계.

3. PATH 에 직접 한 줄을 추가합니다

설치 프로그램은 ~/.local/bin 을 PATH 에 넣어 주지만, 셸 설정을 남다르게 쓰고 있다면 빠질 수 있습니다. 그럴 때는 아래 줄을 셸 설정 파일에 직접 넣습니다(zsh 예시).

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

뜻: “내 홈 폴더의 .local/bin 도 찾아보는 폴더 목록에 넣어라”는 줄을 ~/.zshrc 파일 끝에 덧붙입니다. 그다음 1단계를 다시 합니다.

그 밖의 설치·첫 실행 증상은 탭에서 고릅니다.

증상설치하는 도중 Permission denied(권한이 없어 거부됨) 오류
원인설치 폴더에 파일을 쓸 권한이 모자랍니다.
해결설치 프로그램에 sudo(관리자 권한으로 실행하라는 말)를 붙이지 않습니다. 설치 위치가 내 홈 폴더 안의 ~/.local/bin 이라 관리자 권한이 필요 없습니다. 예전에 sudo 로 설치한 적이 있다면 그 흔적을 지우고 다시 설치합니다.
# 예전에 sudo 로 설치한 것이 있으면 지웁니다
sudo rm /usr/local/bin/hermes

# 표준 설치 명령을 다시 실행합니다
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
증상설치 뒤 source ~/.zshrc 를 입력하면 Permission denied
원인~/.zshrc(또는 ~/.bashrc)의 파일 권한이 잘못되었거나, 설치 프로그램이 그 파일에 깔끔하게 쓰지 못했습니다. Hermes 고유의 문제가 아니라 셸 설정 파일의 권한 문제입니다.
해결권한을 확인해 고치고 다시 읽습니다. 또는 그냥 새 터미널 창을 엽니다 — 새 창은 PATH 변경을 알아서 읽습니다.
ls -la ~/.zshrc      # 권한 확인
chmod 644 ~/.zshrc   # 필요하면 고침 (-rw-r--r-- 곧 644 가 정상)
source ~/.zshrc      # 다시 읽기

설치 프로그램이 PATH 줄을 넣다가 실패한 것 같다면 위 3단계의 echo … 줄로 직접 추가합니다.

증상uv: command not found
원인uv(Python 꾸러미를 설치·관리하는 도구)가 설치되지 않았거나 PATH 에 없습니다.
해결uv 를 설치하고 셸 설정을 다시 읽습니다.
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
증상설정은 문제없이 끝났는데 첫 대화가 HTTP 400 오류로 실패
원인대개 모델 이름이 맞지 않는 것입니다. 설정한 모델이 그 제공자에 없거나, 내 API 키로는 그 모델을 쓸 수 없습니다.
해결설정된 모델·제공자를 확인하고, 모델을 다시 고르거나, 확실히 되는 모델로 시험해 봅니다.
hermes config show | head -20        # 어떤 모델·제공자가 설정됐는지 확인
hermes model                         # 모델을 다시 고르기
hermes chat -q "hello" --model anthropic/claude-opus-4.7   # 잘 되는 모델로 시험

OpenRouter 를 쓴다면 키에 크레딧(미리 충전해 둔 사용 금액)이 있는지 확인합니다. OpenRouter 의 400 은 흔히 그 모델이 유료 요금제를 요구하거나 모델 ID 에 오타가 있다는 뜻입니다.

여기서 안 풀리면 설치 뒤 자주 나는 실패와 복구 순서는 1장의 「자주 나는 실패」와 「복구 순서」에도 정리되어 있습니다.
한눈에 정리
  • 막히면 먼저 어디에서 막혔는지를 가릅니다 — 설치·실행, 모델·제공자, 긴 대화·속도, 명령 실행, 메신저 봇, MCP·스킬.
  • Hermes 자체는 무료 오픈 소스이고, 돈은 고른 제공자의 모델 사용료만 듭니다. 대화·기억·스킬은 내 컴퓨터의 ~/.hermes/ 에 있고, Hermes 는 사용 통계를 수집하지 않습니다.
  • 설치 직후 hermes: command not found 는 터미널을 새로 열거나 source 로 설정을 다시 읽으면 대부분 풀립니다. 설치 프로그램에 sudo 는 붙이지 않습니다.
  • 제공자 추가와 키 입력은 터미널의 hermes model, 대화 도중 전환은 /model 입니다.
  • Context length exceeded 나 토큰 과다는 /compress, 새 세션, hermes prompt-size 로 다스립니다.
  • 위험한 명령을 막고 묻는 것은 고장이 아니라 안전장치입니다. 명령을 읽고 괜찮으면 y.
  • 봇이 조용하면 hermes gateway status → hermes gateway start → 기록 마지막 50줄 순서로 봅니다.
  • 프로필끼리는 기억·세션·스킬을 나눠 쓰지 않고, 봇 토큰도 따로 가져야 합니다. 프로필 하나에는 에이전트 하나만.
  • 통째로 옮길 때는 hermes backup → hermes import, 프로필 하나는 hermes profile export. 전체 백업에는 API 키가 들어 있습니다.
  • 그래도 안 풀리면 GitHub Issues 검색 → Discord 질문 → 버그 신고(OS · Python 버전 · Hermes 버전 · 오류 전문).

이 장의 나머지 소절과 🔧 세부는 완전 가이드 10장에 있습니다.