설치와 첫 대화
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트)를 내 컴퓨터에 설치하고, 두뇌가 될 모델을 고르고, 첫 대화가 되는지 확인한 다음, 그 대화를 다시 이어 하는 데까지 갑니다. 공식 문서는 설치를 “2분 안에 끝난다”고 소개하고, 빠른 시작 문서는 “설치는 됐는데 아무것도 안 된다”는 상황을 피하는 순서를 알려 줍니다. 이 장은 그 순서를 그대로 따릅니다.
설치하기 — 두 가지 방법
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 이하 Hermes)를 내 컴퓨터에 들이는 방법은 크게 둘입니다. Desktop 패키지를 내려받아 실행하거나, 터미널(글자로 명령을 입력하는 창)에 명령 한 줄을 붙여 넣습니다. 빠른 시작 문서는 macOS·Windows 라면 Desktop 설치 프로그램을 추천합니다. 명령줄 프로그램(CLI — 터미널에서 글자로 쓰는 프로그램)과 데스크톱 앱을 한 번에 쉽게 설치해 주기 때문입니다.
hermes 라는 명령으로 대화를 시작합니다.
내 환경에 맞는 탭을 골라 따라 합니다.
Hermes 웹사이트에서 내 플랫폼에 맞는 패키지를 내려받습니다.
| 플랫폼 | 하는 일 |
|---|---|
| macOS | DMG(macOS 설치용 묶음 파일)를 열고 Hermes.app 을 Applications(응용 프로그램) 폴더로 복사합니다. |
| Windows | 내려받은 .appinstaller 파일을 Windows App Installer 로 엽니다. 서명된 MSIX 묶음이 설치되고, 업데이트를 받아 올 곳도 함께 기록됩니다. |
패키지 안에 에이전트, Python, 지원되는 부품, 미리 만들어 둔 화면이 들어 있어서 처음 켤 때 따로 조립하지 않습니다. 다만 제공자에 접속하거나 선택 기능을 연결할 때는 인터넷이 필요할 수 있습니다.
데스크톱 앱의 화면 구성은 받은 원문에 설명이 없습니다. 원문은 「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 import 로 전체 백업을 되살리거나, hermes profile import 로 에이전트 하나만 옮겨 올 수 있습니다. 프로필 내보내기(profile export)는 일부러 인증 정보를 빼므로 전체 백업이 아닙니다. 절차는 공식 문서 참고(이 가이드는 다루지 않음).
제공자와 모델 고르기 — 가장 중요한 단계
원문이 “가장 중요한 설정 단계”라고 부르는 곳입니다. Hermes 는 도구(tool — 에이전트가 쓰는 기능 하나. 터미널 실행, 파일 읽기, 웹 검색 등)를 써서 일하는 손발이고, 무엇을 할지 생각하는 두뇌는 모델(에이전트의 두뇌 역할을 하는 AI — Claude, GPT, Gemini 등)입니다. 모델은 제공자(provider — AI 모델을 빌려주는 서비스)를 통해 빌려 씁니다. 제공자를 정하지 않으면 Hermes 는 답을 만들 두뇌가 없는 상태이므로, 어느 제공자의 어떤 모델을 쓸지 정해 주는 일이 먼저입니다.
고르는 명령은 하나입니다. 터미널(글자로 명령을 입력하는 창)에 입력하면 질문에 답하며 따라가는 방식으로 진행됩니다.
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 Codex | ChatGPT 또는 Codex 구독으로 Codex 모델을 씁니다 | hermes model → ChatGPT or Codex Subscription 에서 기기 코드 인증 |
| Anthropic | Claude 모델을 직접 씁니다. Max 요금제 + 추가 사용 크레딧(OAuth), 또는 쓴 만큼 내는 API 키 | hermes model → OAuth 로그인(Max + 추가 크레딧 필요), 또는 Anthropic API 키 |
| OpenRouter | 여러 제공자의 많은 모델로 이어 줍니다 | API 키 입력 |
| Custom Endpoint | VLLM, SGLang, Ollama 등 OpenAI 호환 API 라면 무엇이든 | 접속 주소(base URL) + API 키 |
--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(새 터미널 화면) — 겹쳐 뜨는 창, 마우스로 고르기, 일하는 중에도 막히지 않는 입력 |
두 화면은 세션(대화 한 묶음), 슬래시 명령(입력 칸에 / 로 시작해 넣는 명령), 설정을 함께 씁니다. 그러니 둘 다 열어 보고 편한 쪽을 쓰면 됩니다.
단순하게 흉내 낸 그림입니다. 원문은 “모델, 쓸 수 있는 도구, 스킬이 담긴 환영 배너가 보인다”고만 적습니다.
첫 질문은 구체적이고, 맞았는지 확인하기 쉬운 것으로 고릅니다. 원문의 예 세 가지입니다. 영어 그대로 입력해도 되고, 뜻을 참고해 내 상황에 맞게 바꿔도 됩니다.
| 입력할 글 (원문) | 뜻 |
|---|---|
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 --continue # Resume the most recent session
hermes -c # Short form
뜻: 가장 최근 세션을 이어서 엽니다. 둘째 줄은 같은 명령의 짧은 형태입니다.
hermes --continue 가 가장 최근 것을 다시 엽니다.이 명령을 입력하면 방금 나눈 그 세션으로 돌아와야 합니다. 돌아오지 않는다면 원문이 일러 주는 두 가지를 확인합니다.
| 확인할 것 | 설명 |
|---|---|
| 같은 프로필인가 | 프로필(profile — 설정·기억·세션을 따로 쓰는 별도 Hermes 환경)을 바꾼 것이 원인일 수 있습니다. |
| 세션이 실제로 저장됐는가 | hermes sessions list(세션 목록 보기)로 확인합니다. |
- 순서는 설치 → 제공자 → 첫 대화 → 이어 하기. 대화 한 번이 되기 전에는 기능을 더 얹지 않습니다.
- 설치는 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장에 있습니다.
터미널에서 대화하기 — CLI 와 세션
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트)와 가장 기본적으로 만나는 곳은 터미널(글자로 명령을 입력하는 창)입니다. 이 장에서는 대화 화면을 여는 법, 화면 읽는 법, 슬래시 명령(입력 칸에 / 로 시작해 넣는 명령)과 단축키, 일하는 도중에 방향을 바꾸는 법을 익히고, 대화가 세션(대화 한 묶음)으로 저장되어 다시 이어지고·찾아지고·정리되는 방식을 살펴봅니다.
CLI 실행하기 — hermes 한 줄로 시작
Hermes 의 CLI(터미널에서 글자로 쓰는 프로그램 화면)는 웹 페이지가 아니라 터미널 안에서 열리는 대화 화면입니다. 원문은 이 화면이 여러 줄 입력, 슬래시 명령 자동 완성, 대화 기록, 도중에 끼어들어 방향 바꾸기, 도구(tool — 에이전트가 쓰는 기능 하나. 터미널 실행·파일 읽기·웹 검색 등)가 내는 결과를 실시간으로 보여 주기를 갖췄다고 소개합니다. AI 에이전트(말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)에게 일을 시키는 창구인 셈입니다.
여는 방법은 터미널에 hermes 라고 입력하고 Enter 를 누르는 것이 전부입니다. 처음 쓰는 컴퓨터라면 먼저 hermes setup --portal 한 줄로 준비를 마쳐야 합니다 — 1장 설치와 제공자 고르기를 보세요.
시작할 때 뒤에 옵션을 붙이면 모델(에이전트의 두뇌 역할을 하는 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 을 씁니다.
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 browse | Skills 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 (기본) | 지금 턴이 내 말을 반영해 다시 진행합니다. 오래 걸리는 터미널 명령(빌드 등)이 돌고 있었다면 죽이지 않고 뒤로 보내고(끝나면 알림), 내 메시지를 바로 읽습니다. 다른 도구는 먼저 끝냅니다. | /busy interrupt |
queue | Hermes 가 지금 일을 끝낸 뒤 다음 턴으로 실행합니다. | /busy queue |
steer | 끊지도, 새 턴을 만들지도 않고 지금 실행에 끼워 넣습니다. 다음 도구 호출 뒤에 Hermes 에게 닿습니다. | /busy steer |
지금 방식은 /busy status 로 확인합니다. 방식과 상관없이 /queue <prompt> 로 다음 턴을 직접 줄 세울 수도 있습니다. 일하는 중에 처음 Enter 를 누르면 이 설정을 알려 주는 한 줄 안내가 한 번 나옵니다.
멈추기와 나가기는 다릅니다. 헷갈리기 쉬워 표로 정리합니다.
| 하고 싶은 것 | 방법 | 결과 |
|---|---|---|
| 방향만 바꾸기 | 새 메시지 + Enter | 지금 턴이 내 말을 반영합니다. |
| 이번 일 그만두기 | 빈 입력 칸에서 Ctrl+C, 또는 /stop | 하던 일을 멈춥니다. 대화 화면은 그대로입니다. |
| 화면에서 나가기 | Ctrl+D | Hermes 화면을 닫습니다. 돌고 있던 턴은 취소되지 않고 끝까지 진행되며, 나중에 hermes --resume 으로 답을 볼 수 있습니다. |
| 강제로 끝내기 | Ctrl+C 를 2초 안에 두 번 | 강제 종료. |
세션이란 — 자동으로 저장되는 대화 한 묶음
세션은 대화 한 묶음입니다. Hermes 는 모든 대화를 따로 저장 버튼을 누르지 않아도 자동으로 세션으로 저장합니다. 터미널에서 한 대화든 Telegram·Discord·Slack 같은 메신저에서 한 대화든 마찬가지이고, 주고받은 메시지 전체가 남습니다. 덕분에 세 가지가 가능해집니다 — 어제 하던 대화를 이어 하기, 지난 대화들 속에서 찾기, 쌓인 기록을 관리하기.
~/.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 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장에 있습니다.
설정 — 파일 · 모델 · 한도
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 도구를 써서 내 대신 일을 해 주는 AI 프로그램)의 설정은 모두 ~/.hermes/ 폴더 한곳에 모여 있습니다. 이 장은 설정이 어디에 저장되고, 어떻게 바꾸고, 값이 여러 곳에 있을 때 무엇이 이기는지를 먼저 설명한 뒤, 꼭 알아 둘 한도·압축·보조 모델·화면 표시·터미널 백엔드를 차례로 봅니다. 나머지 설정은 장 끝의 접힌 표에 한 줄씩 정리했습니다.
설정이 저장되는 곳 — ~/.hermes/ 폴더
Hermes 는 모든 설정을 ~/.hermes/ 폴더에 둡니다. 맨 앞의 ~(물결표 — 내 홈 폴더, 곧 내 계정의 개인 폴더)는 “내 홈 폴더”를 뜻하므로, 내 홈 폴더 안의 .hermes 라는 폴더입니다. 원문은 “쉽게 찾을 수 있도록” 한곳에 모았다고 설명합니다. 설정뿐 아니라 기억, 스킬, 예약 작업, 기록도 이 폴더에 함께 있습니다.
config.yaml)에는 “어떤 모델을 쓸지, 화면에 얼마나 자세히 보여 줄지” 같은, 남이 봐도 괜찮은 선택을 적습니다. 금고(.env)에는 열쇠에 해당하는 비밀 값만 넣습니다. Hermes 는 일할 때마다 이 서랍을 열어 둘을 함께 봅니다.
| 파일·폴더 | 들어 있는 것 (원문 설명) |
|---|---|
config.yaml | 설정 — 모델(에이전트의 두뇌 역할을 하는 AI), 터미널, TTS(글을 소리로 읽어 주는 기능), 압축 등 |
.env | API 키(AI 서비스를 쓸 자격을 증명하는 비밀 문자열)와 그 밖의 비밀 값 |
auth.json | OAuth(브라우저에서 로그인해 사용 권한을 받는 방식)로 로그인한 제공자(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(야믈 — 들여쓰기로 묶음을 나타내는 설정 파일 형식)로 적습니다.
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 쪽 참고(이 가이드는 다루지 않음).
설정 보고 바꾸기 — hermes config 명령
설정 파일을 직접 열어 고쳐도 되지만, 터미널(글자로 명령을 입력하는 창)에서 hermes config 명령을 쓰면 값이 알맞은 파일로 알아서 들어갑니다. 계열 명령은 일곱 가지입니다.
| 명령 | 하는 일 |
|---|---|
hermes config | 지금 설정을 보여 줍니다 |
hermes config edit | config.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
뜻: “내가 정한 터미널 백엔드 값을 지워라”, 그리고 “빠지거나 낡은 설정이 없는지 봐라”. 지운 설정은 우선순위의 아래 단계 값(다음 소절)을 따릅니다.
set 명령 하나가 이름의 모양에 따라 두 파일 중 알맞은 곳에 저장합니다.OPENROUTER_API_KEY, HERMES_TIMEZONE 처럼 대문자와 밑줄로 된 이름은 환경 변수(프로그램이 시작할 때 읽어 가는, 이름표가 붙은 값)로 보고 언제나 .env 에 저장하며, 점으로 이은 이름은 config.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장에 있습니다.
도구 · 툴셋 · MCP
Hermes Agent 는 AI 에이전트(말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)입니다. 그 “일을 해 주는” 부분을 맡는 것이 도구입니다. 이 장에서는 Hermes 에 어떤 도구가 들어 있는지, 도구 꾸러미인 툴셋을 어떻게 켜고 끄는지, 에이전트의 명령이 실제로 어디에서 실행되는지, 그리고 MCP 로 바깥 서비스의 도구를 어떻게 꽂아 쓰는지 차례로 살펴봅니다.
도구란 무엇인가 — 에이전트의 손
도구(tool — 에이전트가 쓰는 기능 하나. 웹 검색, 터미널 명령 실행, 파일 읽기 같은 것)는 에이전트의 능력을 넓혀 주는 기능입니다. 모델(에이전트의 두뇌 역할을 하는 AI — Claude · GPT · Gemini 등)은 혼자서는 글을 읽고 쓸 수만 있습니다. 실제로 웹을 찾아보거나, 내 컴퓨터에서 명령을 실행하거나, 파일을 고치려면 그 일을 대신 해 줄 도구가 있어야 합니다. Hermes 는 이런 도구를 폭넓게 갖춘 채로 설치됩니다.
원문은 내장 도구를 아래처럼 큰 묶음으로 소개합니다. 도구 이름은 대화 기록에 그대로 나오므로, “이런 이름이 보이면 이런 일을 하는 중이구나” 정도로만 알아 두면 됩니다.
| 묶음 | 도구 이름 예 | 하는 일 |
|---|---|---|
| 웹 (Web) | web_search, web_extract | 웹을 검색하고, 찾은 페이지의 내용을 뽑아 옵니다. |
| X 검색 (X Search) | x_search | X(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 카탈로그 플러그인에서 옵니다.
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 의 좋은 점은 다섯 가지입니다.
| 좋은 점 | 뜻 |
|---|---|
| 도구를 새로 만들지 않아도 | 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.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). |
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 로 더 붙입니다.
- 툴셋은 도구 꾸러미입니다.
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장에 있습니다.
기억 · 맥락 파일 · 성격
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 도구를 써서 내 대신 일을 해 주는 AI 프로그램)는 대화가 끝나도 나와 내 프로젝트를 잊지 않도록 네 가지 장치를 씁니다. 스스로 적는 기억, 프로젝트 폴더에 두는 맥락 파일, 기본 성격을 정하는 SOUL.md, 잠깐 말투를 바꾸는 /personality 입니다. 이 장에서는 넷이 각각 무엇이고 어떻게 다른지, 무엇을 어디에 적어야 하는지를 차례로 봅니다.
기억이란 — 세션이 끝나도 남는 메모
Hermes 에는 세션(대화 한 묶음 — 시작부터 끝까지의 기록)이 끝나도 남는 기억(memory)이 있습니다. 원문은 이것을 “크기가 정해져 있고(bounded) 골라 담는(curated) 기억”이라고 부릅니다. 덕분에 Hermes 는 내 취향, 내 프로젝트, 내 컴퓨터 환경, 일하다 배운 것을 다음 대화에서도 압니다.
수첩 두 권은 내 컴퓨터의 ~/.hermes/memories/ 폴더(~ 는 내 홈 폴더)에 있는 파일 두 개입니다.
| 파일 | 무엇을 적나 | 글자 수 한도 |
|---|---|---|
MEMORY.md | 에이전트의 개인 메모 — 환경 사실, 규칙, 배운 것 | 2,200자 (약 800 토큰) |
USER.md | 사용자 소개 — 내 취향, 소통 방식, 기대하는 것 | 1,375자 (약 500 토큰) |
토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)으로는 둘을 합쳐 약 1,300 토큰입니다. Hermes 는 memory 라는 도구(tool — 에이전트가 쓰는 기능 하나)로 이 파일에 항목을 추가하고, 고치고, 지웁니다. 내가 파일을 직접 관리할 필요가 없습니다.
세션이 시작되면 기억은 시스템 프롬프트(대화가 시작될 때 모델이 가장 먼저 읽는 지시문 묶음) 안에 아래처럼 들어갑니다. 원문에 실린 예시입니다.
══════════════════════════════════════════════
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)를 쓰게 하지 마세요. 기억은 자동으로 적히고 다시 읽히므로, 둘이 서로의 항목 위에 덧쌓아 누구도 쓴 적 없는 내용이 됩니다. 두 번째 에이전트에게는 자기 프로필(profile — 설정·기억·세션을 따로 쓰는 별도 Hermes 환경)을 주고, 기억을 함께 써야 한다면 외부 기억 제공자를 씁니다.
더 보기: 수첩이 꽉 차면 · 저장한 줄 알았는데 잊었다면.
맥락 파일 — 폴더에 두면 알아서 읽는 안내문
맥락 파일(context files)은 Hermes 가 알아서 찾아 읽는 안내문 파일입니다. 프로젝트 폴더에 정해진 이름으로 두면, 세션(대화 한 묶음)을 시작할 때 시스템 프롬프트(모델이 가장 먼저 읽는 지시문 묶음)에 들어가 Hermes 의 행동을 정합니다. “이 프로젝트는 이렇게 생겼고 이런 규칙이 있어”를 매번 말할 필요가 없어집니다.
| 파일 | 쓰임 | 어디서 찾나 |
|---|---|---|
.hermes.md / HERMES.md | 프로젝트 지침 (가장 우선) | git 저장소(git 으로 변경 이력을 관리하는 프로젝트 폴더)의 맨 위 폴더까지 올라가며 |
AGENTS.override.md | AGENTS.md 를 나만, 폴더별로 덮어쓰는 파일 (보통 저장소에 올리지 않음) | 시작할 때의 작업 폴더 + 하위 폴더는 차츰 |
AGENTS.md | 프로젝트 지침 · 규칙 · 구조 | 위와 같음 |
CLAUDE.md | Claude Code 용 맥락 파일 (이것도 알아봄) | 위와 같음 |
SOUL.md | 이 Hermes 전체의 성격과 말투 | Hermes 홈 폴더(~/.hermes)의 SOUL.md 만 |
.cursorrules | Cursor IDE 의 코딩 규칙 | 작업 폴더만 |
.cursor/rules/*.mdc | Cursor IDE 의 규칙 모듈 | 작업 폴더만 |
작업 폴더(working directory, 원문 표기 CWD)는 Hermes 를 실행한 그 폴더입니다.
어떻게 쓰나 — 가장 흔한 방법은 프로젝트 폴더에 AGENTS.md 하나를 두는 것입니다.
- 프로젝트 폴더에
AGENTS.md파일을 만듭니다보통의 글 파일입니다. 프로젝트 구조, 지킬 규칙, 하면 안 되는 일을 적습니다 — 쓰는 법은 AGENTS.md. - 그 폴더에서 Hermes 를 실행합니다세션을 시작할 때 Hermes 가 파일을 찾아 읽습니다. 따로 알려 줄 필요가 없습니다.
기억과 다른 점은 둘입니다. 기억은 Hermes 가 스스로 적지만 맥락 파일은 내가 직접 씁니다. 기억은 어느 폴더에서든 읽히지만 맥락 파일은 그 파일이 있는 프로젝트에서만 읽힙니다.
AGENTS.override.md— AGENTS.md 옆에 이 파일이 있으면 AGENTS.md 대신 이것을 읽습니다. 저장소에 올라가 있는 AGENTS.md 는 건드리지 않고 나만 다른 지침을 쓰고 싶을 때 둡니다..cursorrules— Hermes 는 Cursor IDE 의.cursorrules파일,.cursor/rules/*.mdc규칙 모듈과 호환됩니다. 프로젝트 맨 위 폴더에 이 파일이 있고 더 우선하는 맥락 파일이 없으면 프로젝트 맥락으로 읽습니다. 이미 써 둔 Cursor 규칙이 Hermes 에서도 그대로 적용된다는 뜻입니다.
SOUL.md — Hermes 의 기본 성격
SOUL.md 는 Hermes 의 성격, 말투, 소통 방식을 정하는 파일입니다. 시스템 프롬프트(모델이 가장 먼저 읽는 지시문 묶음)의 맨 첫 자리에 들어가 “이 에이전트가 누구인가”를 정합니다. 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 는 ① 어떤 상황에서도 변하지 않고 ② 여러 대화에 두루 맞을 만큼 넓고 ③ 목소리를 실제로 바꿀 만큼 구체적이며 ④ 일의 지시가 아니라 소통과 정체성에 집중합니다. 원문 예시입니다.
# 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.md | AGENTS.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장에 있습니다.
스킬 — 일하는 법을 배우고 다시 쓰기
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트)는 일하는 방법을 스킬(skill — 특정 일을 하는 방법을 적은 설명서)이라는 문서로 갖고 있다가, 그 일이 필요해졌을 때만 꺼내 읽습니다. 이 장에서는 스킬이 무엇이고, 어떻게 불러 쓰며, 어디서 구해 설치하고, 에이전트가 어떻게 스스로 스킬을 만들어 가는지를 차례로 살펴봅니다.
스킬이란 무엇인가
스킬은 에이전트(AI 에이전트 — 말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)가 필요할 때 불러와 읽는 지식 문서입니다. 원문 표현으로는 “on-demand knowledge documents”, 곧 요청이 있을 때만 펼치는 문서입니다. 스킬 하나는 SKILL.md 라는 글 파일 하나가 중심이고, 그 안에 “이 일은 언제 하고, 어떤 순서로 하며, 어디서 자주 틀리고, 잘 됐는지는 어떻게 확인하는지”가 적혀 있습니다.
스킬은 모두 ~/.hermes/skills/ 에 있습니다(~ 는 내 홈 폴더를 뜻합니다). 원문은 이 폴더를 “기본 폴더이자 기준이 되는 원본”이라고 부릅니다. 처음 설치하면 Hermes 에 딸려 오는 스킬(bundled skills)이 이곳에 복사되고, Skills Hub(스킬을 찾아 설치하는 곳)에서 설치한 스킬과 에이전트가 만든 스킬도 이곳으로 들어옵니다. 에이전트는 어떤 스킬이든 고치거나 지울 수 있습니다.
스킬은 Hermes 만의 형식이 아닙니다. 원문은 스킬이 agentskills.io 공개 표준과 호환된다고 적습니다.
기억과 스킬은 무엇이 다른가
Hermes 에는 세션(대화 한 묶음)이 끝나도 남는 것이 두 가지 있습니다. 기억과 스킬입니다. 원문은 둘의 역할을 이렇게 나눕니다.
| 기억 (memory) | 스킬 (skill) | |
|---|---|---|
| 담는 것 | 작고 오래가는 사실 | 더 긴 절차(일하는 순서) |
| 언제 읽히나 | 항상 — 대화마다 들어 있어야 하는 것 | 관련 있을 때만 불러옴 |
| 비유 | 책상에 붙여 둔 메모지 | 선반에 꽂아 둔 설명서 |
둘은 Hermes 가 스스로 나아지는 흐름(0장 「배우는 순환」) 안에서 함께 움직입니다. 에이전트가 스킬을 직접 만드는 과정은 아래 소절에서 다룹니다.
/skills list 로 볼 수 있습니다.
스킬 쓰기 — 슬래시 명령으로 부르기
설치된 스킬은 저절로 슬래시 명령(대화 입력 칸에 / 로 시작해 넣는 명령)이 됩니다. 따로 등록할 것이 없습니다. 대화 입력 칸에 /스킬이름 을 쓰고 그 뒤에 부탁을 이어 적으면, 에이전트가 그 스킬을 읽은 다음 부탁을 처리합니다. 터미널(글자로 명령을 입력하는 창)의 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 스킬로) 이 영상을 요약해 줘
앞의 /이름 이 스킬이고, 그 뒤가 내 부탁입니다. 위 네 줄은 원문의 예시입니다.
/excalidraw
부탁 없이 스킬 이름만 넣으면, 스킬을 불러온 뒤 에이전트가 무엇이 필요한지 나에게 묻습니다.
/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장 「툴셋」).
여러 스킬을 한 줄에 쓸 때 읽는 규칙
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 뒤에 적는 글은 “어느 출처의 어느 스킬인가”를 가리키는 주소입니다.
대화 안에서, 그리고 웹사이트에서
지금까지의 명령은 터미널에 넣는 것이고, 대화 안에서는 같은 명령을 /skills 로 씁니다. 원문은 “모든 같은 명령이 /skills 로도 동작한다”고 적습니다.
/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 데스크톱 앱)이 열리며 확인 창이 뜹니다.
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장에 있습니다.
예약 작업과 위임
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 — 대화 한 묶음)을 열어 실행합니다.
여기서 꼭 기억할 것이 세 가지 있습니다.
| 기억할 것 | 뜻 |
|---|---|
| 게이트웨이가 켜져 있어야 돈다 | 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장).
위임이란 — 일을 나눠 하위 에이전트에게 맡기기
위임(delegation)은 Hermes 가 일의 한 덩어리를 떼어 하위 에이전트(subagent — 일을 나눠 받은 별도 에이전트)에게 맡기는 것입니다. Hermes 는 delegate_task 라는 도구로 하위 에이전트를 만듭니다. 하위 에이전트는 저마다 새 대화에서, 자기만의 터미널 세션을 갖고 따로 일합니다. 일을 마치면 마지막 요약만 부모(일을 맡긴 쪽 — 나와 대화하던 Hermes)의 컨텍스트(context — 모델이 한 번에 기억하며 볼 수 있는 글의 양)로 돌아옵니다.
왜 쓰나. 좋아지는 점은 세 가지입니다.
부모의 기억 공간을 아낍니다
파일 수십 개를 고치는 일을 부모가 직접 하면 그 과정이 부모의 대화를 가득 채웁니다. 맡기면 요약만 들어와 토큰이 덜 듭니다.
여러 일을 동시에 합니다
서로 상관없는 일 여러 개를 한꺼번에 맡길 수 있습니다. 기본으로 최대 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장에 있습니다.
메신저에서 쓰기 — 게이트웨이와 Telegram
Hermes Agent 는 터미널(글자로 명령을 입력하는 창) 앞에 앉아 있을 때만 쓰는 프로그램이 아닙니다. 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)를 켜 두면 휴대폰의 Telegram 같은 메신저에서 Hermes 에게 말을 걸고 답을 받을 수 있습니다. 이 장은 게이트웨이가 무엇인지, 어떤 메신저를 쓸 수 있는지, 그리고 Telegram 봇을 만들어 연결하는 순서를 처음부터 끝까지 따라갑니다.
게이트웨이란 무엇인가 — 왜 계속 켜 두나
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 말만 하는 챗봇과 달리 도구를 써서 내 대신 일을 해 주는 AI 프로그램)와 대화하는 기본 창구는 터미널입니다. 그런데 밖에서 휴대폰으로 일을 시키고 싶을 때가 있습니다. 이때 필요한 것이 게이트웨이입니다. 원문은 게이트웨이를 이렇게 정의합니다 — “설정해 둔 모든 플랫폼(여기서는 메신저 서비스 하나하나)에 연결하고, 세션(대화 한 묶음)을 관리하고, 예약 작업(cron — 정해 둔 시간에 자동 실행)을 돌리고, 음성 메시지를 전달하는 하나의 백그라운드 프로그램(화면 뒤에서 조용히 계속 도는 프로그램)”.
게이트웨이가 하는 일을 원문 순서대로 풀면 네 가지입니다.
① 메신저와 연결
메신저마다 메시지를 받아 오는 담당 부품이 있고, 게이트웨이가 이것들을 한꺼번에 돌립니다.
② 세션 관리
대화방마다 세션을 따로 보관합니다. 그래서 Hermes 가 앞에서 나눈 이야기를 기억한 채 이어 갑니다.
③ 예약 작업 실행
60초마다 “지금 실행할 예약 작업이 있나”를 확인해 실행합니다(7장).
④ 음성 메시지 전달
내가 보낸 음성을 글로 바꾸고, Hermes 의 답을 음성으로 돌려줄 수 있습니다(음성 메시지).
왜 계속 켜 두어야 할까요? 메시지를 받는 것도, 예약 작업 시계를 돌리는 것도 게이트웨이이기 때문입니다. 게이트웨이가 꺼져 있으면 두 가지가 함께 멈춥니다.
빠른 설정 — 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 을 보냅니다
3. 표시 이름을 정합니다
봇의 표시 이름입니다. 아무것이나 됩니다. 원문 예: Hermes Agent.
4. 사용자 이름을 정합니다
@ 뒤에 붙는 봇의 사용자 이름입니다. 다른 봇과 겹치면 안 되고, 반드시 bot 으로 끝나야 합니다. 원문 예: my_hermes_bot.
5. API 토큰을 받습니다
BotFather 가 토큰을 답으로 보내 줍니다. 이런 모양입니다.
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
이 문자열을 복사해 둡니다. Hermes 에 연결하기에서 씁니다.
/revoke 로 무효로 만듭니다.
Hermes 에 연결하고 켜기
이제 재료 두 개가 모였습니다 — BotFather 가 준 봇 토큰(봇 만들기)과 내 사용자 ID(사용자 ID 알아내기). 이 둘을 Hermes 에 알려 주고 게이트웨이(메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)를 켜면 끝입니다.
값을 넣는 방법은 두 가지입니다. 처음이라면 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_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장에 있습니다.
안전장치와 되돌리기
Hermes Agent 는 말만 하는 챗봇이 아니라, 내 컴퓨터에서 명령을 실행하고 파일을 고치는 AI 에이전트(도구를 써서 내 대신 일을 해 주는 AI 프로그램)입니다. 그래서 “엉뚱한 명령을 실행하면 어쩌지?”, “모르는 사람이 내 봇에게 말을 걸면?”, “파일을 망가뜨리면?” 같은 걱정이 따라옵니다. 이 장에서는 Hermes 가 그런 일을 막으려고 둔 여덟 겹의 안전장치와, 그래도 일이 틀어졌을 때 파일을 이전 상태로 돌려놓는 체크포인트와 /rollback 을 살펴봅니다.
안전장치는 여덟 겹 — 전체 그림
원문은 Hermes 의 보안 방식을 defense-in-depth(겹겹이 막기 — 한 겹이 뚫려도 다음 겹이 막도록 여러 겹을 두는 방식)라고 부르고, 그 겹이 여덟 개라고 적습니다. 여덟 개를 외울 필요는 없습니다. 요청 하나가 “누가 말을 거는가 → 위험한 명령인가 → 어디에 쓰는가 → 어디서 실행하는가” 네 개의 문을 차례로 지나고, 그 뒤에서 네 가지 검사가 늘 함께 돈다고 보면 됩니다.
| 겹 | 원문 이름 | 쉬운 말로 | 이 장에서 |
|---|---|---|---|
| ① | User authorization | 누가 에이전트에게 말을 걸 수 있는가 — 허용 목록, DM 페어링 | 누가 쓸 수 있나 |
| ② | Dangerous command approval | 무언가를 망가뜨릴 수 있는 작업은 사람이 중간에서 허락 | 승인 |
| ③ | File write safety | 파일 쓰기 도구가 손대면 안 되는 곳의 금지 목록, 그리고 원하면 켜는 쓰기 울타리 | 파일 쓰기 보호 |
| ④ | Container isolation | Docker·Modal(그리고 Singularity 플러그인) 같은 격리된 공간 안에서, 단단히 조인 설정으로 실행 | 격리 |
| ⑤ | MCP credential filtering | MCP(외부 서비스의 도구를 에이전트에 연결하는 공통 규격) 서버 프로그램에는 비밀 값을 넘기지 않음 | 알아서 도는 방어 |
| ⑥ | 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 — 거부 (기본값)
명령을 막습니다. 아무것도 실행되지 않습니다.
어떤 명령에서 묻나
원문은 승인을 부르는 패턴을 서른 개 남짓 나열합니다. 성격별로 묶으면 다음과 같습니다(전체 표는 아래 접힌 상자).
통째로 지우기
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
명령 하나가 거치는 길
묻는 방식 세 가지 — smart · manual · off
얼마나 자주 물을지는 설정 파일 ~/.hermes/config.yaml 의 approvals.mode 로 정합니다(설정 파일 다루는 법은 3장).
보조 AI 가 먼저 위험도를 가늠합니다. 위험이 낮은 명령(예: python -c "print('hello')")은 그 명령에 한해 자동으로 승인하고, 정말 위험한 명령은 자동으로 거부합니다. 판단이 서지 않는 경우만 나에게 승인 창을 띄웁니다.
위험한 패턴에 맞으면 언제나 나에게 묻습니다. AI 의 판단에 맡기지 않고 모든 위험 명령을 직접 보고 싶을 때 고릅니다.
승인 검사를 모두 끕니다. --yolo 로 실행한 것과 같아서, 모든 명령이 묻지 않고 실행됩니다.
approvals.mode: off 는 모든 안전 확인 창을 끕니다. 믿을 수 있는 환경(CI/CD, 컨테이너 등)에서만 쓰라고 원문은 적습니다. 이 설정은 그 프로필(설정·기억·세션을 따로 쓰는 별도 Hermes 환경)의 모든 대화와 예약 작업에 적용됩니다.대답하지 않으면 — 자동 거부
승인 창이 뜬 뒤 정해진 시간(기본 300초, 5분) 안에 답하지 않으면 그 명령은 거부된 것으로 처리됩니다. 자리를 비운 사이에 위험한 명령이 저절로 실행되는 일이 없게 하려는 것입니다.
- 시간이 지난 승인 창은 다시 열 수 없습니다요청은 버려지고, 에이전트는 그 턴(내 메시지 하나에 에이전트가 일하고 답하는 한 차례) 안에서 스스로 재시도하지 말라는 안내를 받습니다.
- 그래도 실행하려면 새 메시지로 다시 부탁합니다예:
go ahead and run that now(뜻: 이제 그거 실행해 줘). 에이전트가 명령을 새로 요청하고, 새 승인 창이 뜹니다. - 불이익은 없습니다시간 초과는 “거부”로 세지 않습니다. once 로 승인하면 그 한 번의 실행에만 적용됩니다.
메신저에서는 답장으로 승인합니다
Telegram 같은 메신저로 Hermes 를 쓸 때는(8장) 글자 하나를 누르는 창 대신, 에이전트가 위험한 명령의 내용을 대화방에 보내고 내 답장을 기다립니다.
| 하려는 것 | 보낼 답장 (아무거나 하나) |
|---|---|
| 승인 | 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 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 으로 다음 대화를 시작하면 승인이 다시 켜집니다.
그래도 절대 실행하지 않는 것 — 절대 금지 목록
되돌릴 수 없는 재앙이 되는 몇몇 명령은 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 — 허용 목록에 사용자 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 입니다.
/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
사진이 너무 많이 쌓이지 않도록, 에이전트는 한 턴에 폴더 하나당 많아야 한 장만 찍습니다. 지난 사진 이후 달라진 것이 없으면 건너뜁니다.
사진은 내 프로젝트 폴더 안이 아니라 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장에 있습니다.
문제 해결과 자주 묻는 질문
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 Portal | Nous Research 의 구독형 창구. OAuth(비밀번호를 넘기지 않고 로그인으로 사용 권한을 주는 방식) 로그인 한 번으로 300개가 넘는 모델과 웹·이미지·TTS(글을 소리로 읽어 주는 기능)·브라우저 기능을 씁니다. 처음 쓰는 사람에게 추천 |
| OpenRouter | API 키(제공자가 나를 알아보는 비밀번호 같은 문자열) 하나로 수백 가지 모델을 씁니다. 여러 모델을 오가며 쓰려는 사람에게 추천 |
| OpenAI | GPT-5.4, GPT-5-codex, GPT-4.1, GPT-4o 등 |
| Anthropic | Claude 모델. 직접 API, hermes auth add anthropic 으로 하는 OAuth, OpenRouter, 또는 호환 프록시(중간에서 요청을 대신 전달해 주는 서버) |
Gemini 모델. gemini 제공자로 직접 API, OpenRouter, 또는 호환 프록시 | |
| z.ai / ZhipuAI | GLM 모델 |
| Kimi / Moonshot AI | Kimi 모델 |
| MiniMax | 글로벌용과 중국용 접속 주소 |
| 로컬 모델 | Ollama, vLLM, llama.cpp, SGLang, 또는 OpenAI 호환 서버 아무것이나 |
제공자는 터미널에서 hermes model 을 실행해 고르거나, ~/.hermes/.env(~ 는 내 홈 폴더 — 비밀 값을 적어 두는 설정 파일)를 직접 고쳐서 정합니다. 고르는 과정은 1장 「제공자 고르기」에 있습니다. 제공자별 키 이름 전체는 공식 문서 Environment Variables 쪽 참고(이 가이드는 다루지 않음).
내 자료는 어디로 가나요?
인터넷 없이 — 로컬 모델 연결하기
내 컴퓨터에 모델 서버(Ollama, vLLM, llama.cpp server, SGLang, LocalAI 등)를 띄워 두었다면, 터미널에서 hermes model 을 실행하고 차례로 다음과 같이 답합니다.
| 묻는 항목 | 원문의 입력 예 | 뜻 |
|---|---|---|
| 고를 것 | Custom endpoint (enter URL manually) | 주소를 직접 입력하는 방식 |
| API base URL | http://localhost:11434/v1 | 내 컴퓨터(localhost)에 떠 있는 모델 서버의 주소 |
| API key | ollama | 원문 예시에 적힌 값 |
| Model name | qwen3.5:27b | 서버에 올려 둔 모델 이름 |
| Context length | 64000 | 컨텍스트(문맥 창 — 모델이 한 번에 기억하며 볼 수 있는 글의 양) 길이. 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 에 추가합니다. 그런데 설치 전부터 열려 있던 터미널은 예전 목록을 그대로 들고 있습니다.
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 에 오타가 있다는 뜻입니다.
- 막히면 먼저 어디에서 막혔는지를 가릅니다 — 설치·실행, 모델·제공자, 긴 대화·속도, 명령 실행, 메신저 봇, 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장에 있습니다.