Hermes Agent — 쓸수록
스스로 배우는 AI 에이전트
Hermes Agent는 Nous Research가 만든 AI 에이전트(말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)입니다. 공식 문서는 이것을 “배우는 과정이 안에 들어 있는 에이전트”라고 소개합니다. 일을 해 본 경험으로 스킬(일하는 방법을 적은 설명서)을 만들고, 쓰면서 그 스킬을 고치고, 알아 둘 것을 기억에 남기고, 대화를 거듭할수록 내가 어떤 사람인지 더 잘 알게 됩니다.
먼저 알아 두면 좋은 용어
가이드 전체에서 자주 나오는 말입니다. ⭐ 표시한 8개만 알아도 대부분 따라갈 수 있습니다. 각 장에서도 처음 나올 때 괄호로 다시 풉니다.
| 용어 | 쉬운 풀이 |
|---|---|
| ⭐ AI 에이전트 | 말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램. Hermes Agent가 바로 이것입니다. 이 가이드에서는 줄여서 “Hermes”라고 부릅니다. |
| ⭐ 모델 · 제공자 | 모델은 에이전트의 두뇌 역할을 하는 AI입니다. 제공자(provider)는 그 모델을 빌려주는 서비스입니다. 어느 제공자의 어느 모델을 쓸지는 설치 뒤에 내가 고릅니다(Nous Portal, OpenRouter, OpenAI 등). |
| ⭐ 터미널 · CLI | 터미널은 글자로 명령을 입력하는 창입니다. CLI는 그 창 안에서 글자로 쓰는 프로그램 화면입니다. Hermes의 기본 화면이 CLI입니다. |
| ⭐ 도구 · 툴셋 | 도구(tool)는 에이전트가 쓰는 기능 하나입니다(터미널 명령 실행, 파일 고치기, 웹 검색 등). 툴셋(toolset)은 도구를 묶은 꾸러미로, 꾸러미 단위로 켜고 끕니다. |
| ⭐ 기억 | memory. 대화가 끝나도 남는 메모. 내 취향, 하고 있는 일, 내 컴퓨터 환경, 배운 것을 MEMORY.md와 USER.md 두 파일에 적어 둡니다. |
| ⭐ 스킬 | skill. 특정 일을 하는 방법을 적은 설명서. 평소에는 짧은 소개만 보고 있다가, 그 일이 필요해질 때만 전체를 꺼내 읽습니다. |
| ⭐ 세션 | 대화 한 묶음. 시작부터 끝까지의 기록이며, 나중에 이어서 할 수 있습니다. |
| ⭐ 게이트웨이 | gateway. Telegram 같은 메신저와 Hermes를 이어 주는, 계속 켜 두는 프로그램. 이것이 있어야 메신저로 Hermes에게 말을 걸 수 있습니다. |
용어 12개 더 보기 — 읽다가 모르는 말이 나오면 여기서 찾으세요
| 용어 | 쉬운 풀이 |
|---|---|
| TUI | hermes --tui 로 여는 새 터미널 화면. 기본 CLI와 같은 세션·명령·설정을 씁니다. |
| 슬래시 명령 | 대화 입력 칸에 / 로 시작해 넣는 명령. 예: /help, /model. |
| 토큰 | AI가 읽고 쓰는 글의 양을 세는 단위. 비용과 속도의 기준이 됩니다. |
| 컨텍스트(문맥 창) | 모델이 한 번에 기억하며 볼 수 있는 글의 양. |
| 맥락 파일 | context files. 대화마다 자동으로 읽혀서 Hermes의 행동을 정하는 파일. AGENTS.md, SOUL.md 등. |
| SOUL.md | Hermes의 기본 성격과 말투를 적는 파일. |
| 예약 작업 | cron. 정해 둔 시간에 Hermes가 혼자 실행하는 일. 결과는 메신저 등으로 받아 볼 수 있습니다. |
| 위임 · 하위 에이전트 | 큰일을 나눠 별도의 에이전트(하위 에이전트)에게 맡기는 것. 여러 일을 동시에 진행할 때 씁니다. |
| MCP | Model Context Protocol. 외부 서비스의 도구를 에이전트에 연결하는 공통 규격. 그 도구를 내주는 프로그램을 MCP 서버라고 합니다. |
| 터미널 백엔드 | 에이전트의 명령이 실제로 실행되는 곳. 내 컴퓨터(local), Docker, SSH로 연결한 다른 컴퓨터 등. |
| 승인 | 위험할 수 있는 명령을 실행하기 전에 Hermes가 나에게 먼저 묻는 것. |
| 체크포인트 · 되돌리기 | 체크포인트는 Hermes가 파일을 바꾸기 전에 자동으로 찍어 두는 스냅샷이고, /rollback 으로 그 시점으로 되돌립니다. 기본은 꺼져 있어서 켜야 찍힙니다. |
전체 그림 — 누가 누구에게 말하고, 일은 어디서 일어나나
Hermes를 쓰는 모습을 한 장으로 그리면 아래와 같습니다. 나는 터미널이나 메신저로 말을 겁니다. Hermes는 내가 고른 모델에게 “다음에 무엇을 할지”를 묻고, 도구를 써서 실제로 일을 합니다. 그 과정에서 기억과 스킬을 꺼내 쓰고, 새로 알게 된 것을 다시 적어 둡니다.
공식 문서는 Hermes가 무엇이 아닌지도 분명히 적습니다. 편집기(코드를 쓰는 프로그램)에 묶인 코딩 도우미가 아니고, AI 서비스 하나를 감싼 챗봇도 아닙니다. 오래 돌릴수록 할 수 있는 일이 늘어나는 자율 에이전트이며, 내 노트북에 묶여 있지 않습니다.
설치는 명령 한 줄 또는 Hermes Desktop 설치 프로그램으로 합니다. 순서는 1장 설치에서 다룹니다.
문서는 설치 뒤 hermes setup --portal 을 권합니다. 로그인 한 번으로 모델과 Tool Gateway의 네 가지 도구(웹 검색·이미지 생성·음성 합성·브라우저)가 함께 설정됩니다. → 1장 제공자 고르기
스스로 배우는 고리 — Hermes가 다른 점
문서가 맨 앞에 내세우는 특징은 닫힌 학습 고리(closed learning loop)입니다. 일을 하고 끝나는 것이 아니라, 일한 결과가 다음 일을 더 잘하게 만드는 재료로 돌아옵니다.
| 고리의 조각 | 문서의 설명 | 자세히 |
|---|---|---|
| 기억 | 에이전트가 스스로 골라 적는 기억. 주기적으로 “남길 것이 있나” 스스로 챙깁니다. | 5장 기억 |
| 스킬 만들기 | 경험에서 스킬을 스스로 만듭니다. | 6장 스킬 |
| 스킬 고치기 | 스킬을 쓰는 도중에 스스로 개선합니다. | 6장 스킬 |
| 지난 대화 찾기 | 지난 세션을 글자 검색으로 찾고, AI가 요약해서 떠올립니다. | 5장 세션 검색 |
| 사용자 이해 | 세션을 거듭하며 내가 어떤 사람인지에 대한 이해를 깊게 합니다. | 5장 두 가지 기억 |
🔧 문서의 원래 표현 (기술 용어)
문서는 이 고리를 이렇게 적습니다: 주기적 알림이 있는 에이전트 관리 기억, 자율 스킬 생성, 사용 중 스킬 자기 개선, FTS5 기반 세션 간 회상과 LLM 요약, Honcho 방식의 사용자 모델링. FTS5는 글자 검색 기능의 이름이고, Honcho는 외부 기억 제공자 가운데 하나입니다. 외부 기억 제공자는 5장의 접힌 상자에서 짧게 다룹니다.
어디서 돌고, 어디서 말을 거나
Hermes는 “내 노트북에서만”이 아닙니다. 문서의 두 문장으로 정리됩니다. 어디서나 돈다(Runs anywhere) 그리고 내가 있는 곳에 산다(Lives where you do).
게이트웨이 하나로 20개가 넘는 플랫폼에서 말을 걸 수 있습니다. 문서가 나열한 것은 다음과 같습니다.
CLI Telegram Discord Slack WhatsApp Signal Matrix Mattermost Email SMS DingTalk Feishu WeCom Weixin QQ Bot Yuanbao BlueBubbles Home Assistant Microsoft Teams Google Chat 그 밖
문서의 표현을 빌리면, “내가 직접 접속할 일이 없는 클라우드 컴퓨터에서 Hermes가 일하는 동안, 나는 Telegram으로 말을 겁니다.” 이 가이드는 그 가운데 Telegram 연결을 8장에서 자세히 다룹니다.
할 수 있는 일 — 기능 지도
공식 문서의 기능 목록을 다섯 묶음으로 옮겼습니다. 오른쪽 칸은 이 가이드에서 다루는 곳입니다. “다루지 않음”은 이번에 원문을 받지 않은 기능이라 이름과 한 줄 소개만 적었다는 뜻입니다.
| 묶음 | 기능 | 한 줄 소개 (문서 기준) | 이 가이드 |
|---|---|---|---|
| 핵심 | 도구와 툴셋 | 에이전트의 능력을 넓히는 기능들. 플랫폼별로 켜고 끌 수 있는 꾸러미로 묶여 있습니다. | 4장 |
| 스킬 | 필요할 때 꺼내 읽는 지식 문서. agentskills.io 공개 표준과 호환됩니다. | 6장 | |
| 기억 | 세션이 끝나도 남는, 크기가 정해진 기억. MEMORY.md·USER.md. | 5장 | |
| 맥락 파일 | 프로젝트 폴더의 .hermes.md·AGENTS.md·CLAUDE.md·SOUL.md·.cursorrules 를 찾아 자동으로 읽습니다. | 5장 | |
| 맥락 참조 | 메시지에 @ 를 쓰고 파일·폴더·변경 내역·웹 주소를 적으면 그 내용을 끌어와 붙입니다. | 다루지 않음 | |
| 체크포인트 | 파일을 바꾸기 전에 작업 폴더를 자동으로 찍어 두고, /rollback 으로 되돌립니다. 체크포인트 문서에 따르면 기본은 꺼져 있고, 켜야 동작합니다. | 9장 | |
| 자동화 | 예약 작업 | 평소 말이나 cron 표현으로 일정을 정해 자동 실행. 결과를 어느 플랫폼으로든 전달합니다. | 7장 |
| 위임 | delegate_task 도구가 따로 떨어진 하위 에이전트를 만들어 일을 나눕니다. 위임 문서 기준으로 기본 10개까지 동시에 돌립니다(바꿀 수 있음 — 기능 목록 쪽에는 3개로 적혀 있습니다). | 7장 | |
| 코드 실행 | execute_code 도구로, 여러 단계를 Python 스크립트 하나로 묶어 한 번에 처리합니다. | 다루지 않음 | |
| 이벤트 훅 | 정해진 시점에 내가 만든 코드를 실행합니다(기록, 알림 등). | 다루지 않음 | |
| 묶음 처리 | 수백~수천 개의 요청을 동시에 돌려 연구용 자료를 만듭니다. | 다루지 않음 | |
| 미디어 · 웹 | 음성 대화 | CLI와 메신저에서 마이크로 말하고 음성으로 답을 듣습니다. | 다루지 않음 |
| 부름말 | “Hey Hermes”라고 말하면 음성 대화가 시작됩니다(CLI·TUI·데스크톱 앱). | 다루지 않음 | |
| 브라우저 자동 조작 | 웹사이트를 열고, 양식을 채우고, 정보를 뽑아 옵니다. | 다루지 않음 | |
| 이미지 보기 | 클립보드의 이미지를 붙여 넣고 분석을 맡깁니다(이미지를 볼 수 있는 모델에서). | 다루지 않음 | |
| 이미지 만들기 | 글로 설명해 이미지를 만듭니다. 모델은 hermes tools 에서 고릅니다. | 다루지 않음 | |
| 글을 음성으로 | 답을 음성으로 읽어 주고, 받은 음성 메시지를 글로 옮깁니다. | 8장(Telegram 음성) | |
| 연결 | MCP | MCP 서버에 연결해 GitHub·데이터베이스 같은 외부 도구를 씁니다. | 4장 |
| 제공자 경로 정하기 | 어느 제공자가 요청을 처리할지 비용·속도·품질 기준으로 정합니다. | 다루지 않음 | |
| 예비 제공자 | 주 모델에 오류가 나면 예비 제공자로 자동 전환합니다. | 다루지 않음 | |
| 자격 증명 묶음 | 같은 제공자의 키 여러 개에 요청을 나눠 보냅니다. | 3장(설정 표) | |
| 프롬프트 캐싱 | Claude 모델용(Anthropic 직접 연결·OpenRouter·Nous Portal)으로, 세션이 달라도 요청의 앞부분을 1시간 동안 캐시(다시 쓰려고 잠시 보관)합니다. 항상 켜져 있고 설정이 필요 없습니다. | 3장(설정 표) | |
| API 서버 | Hermes를 다른 채팅 화면 프로그램이 연결할 수 있는 서버로 엽니다. | 다루지 않음 | |
| 편집기 연동(ACP) | VS Code·Zed·JetBrains 같은 편집기 안에서 Hermes를 씁니다. | 1장(명령만) | |
| 꾸미기 | 성격과 SOUL.md | SOUL.md 가 기본 성격을 정하고, /personality 로 세션마다 바꿉니다. | 5장 |
| 화면 색 · 테마 | CLI의 색, 진행 표시 문구 같은 겉모습을 바꿉니다. | 다루지 않음 | |
| 플러그인 | 핵심 코드를 고치지 않고 도구·훅·연동을 더합니다. | 다루지 않음 |
🔧 문서 첫 화면이 내세우는 그 밖의 특징
- Bot Mode — 저마다 모델·기억·스킬을 가진 전문 Bot 여러 개가 그룹 대화에서 함께 일합니다(이 가이드는 다루지 않음).
- 모델을 만드는 곳이 만든 에이전트 — Nous Research는 Hermes·Nomos·Psyche 모델을 만든 연구소입니다. Nous Portal, OpenRouter, OpenAI 또는 어떤 연결 주소(endpoint)와도 함께 씁니다.
- 웹 다루기 일체 — 검색, 본문 추출, 브라우저 조작, 이미지 보기·만들기, 음성 합성. Nous Portal 구독 하나에 묶여 있습니다.
- 연구용 기능 — 묶음 처리, 작업 기록(trajectory) 내보내기, Atropos를 쓴 강화 학습.
- AI가 읽기 좋은 문서 — 공식 문서는
/llms.txt(쪽마다 짧은 소개가 붙은 목록, 약 17 KB)와/llms-full.txt(모든 쪽을 하나로 이은 파일, 약 1.8 MB)를 함께 제공합니다.
이 가이드의 지도
처음이라면 1장 → 2장을 먼저 읽고, 나머지는 필요한 장부터 골라 읽어도 됩니다.
- Hermes Agent는 Nous Research가 만든 AI 에이전트로, 도구를 써서 내 대신 일을 하고 쓸수록 스스로 배웁니다.
- 배우는 방식은 두 가지 축입니다. 나와 내 환경에 대한 기억, 그리고 해 본 일을 설명서로 남기는 스킬.
- 말을 거는 곳(터미널·메신저 20곳 이상), 생각하는 곳(내가 고른 모델), 일이 실행되는 곳(내 컴퓨터·Docker·서버)이 나뉘어 있습니다.
- 제공자와 모델은 내가 고릅니다. 문서가 권하는 가장 빠른 길은
hermes setup --portal입니다. - 기본 대화가 잘 된 뒤에 메신저, 예약 작업, 스킬, MCP 같은 기능을 하나씩 더합니다.
출처: hermes-agent.nousresearch.com/docs (문서 첫 화면) · hermes-agent.nousresearch.com/docs/user-guide/features/overview · 수집일 2026-11-09의 공식 문서 기준(문서에 버전 표기 없음)
설치와 첫 대화
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트)를 내 컴퓨터에 설치하고, 두뇌가 될 모델을 고르고, 첫 대화가 되는지 확인한 다음, 그 대화를 다시 이어 하는 데까지 갑니다. 공식 문서는 설치를 “2분 안에 끝난다”고 소개하고, 빠른 시작 문서는 “설치는 됐는데 아무것도 안 된다”는 상황을 피하는 순서를 알려 줍니다. 이 장은 그 순서를 그대로 따릅니다.
- 내 목표에 맞는 가장 빠른 시작 길
- 설치하는 두 가지 방법 — Desktop 패키지와 명령 한 줄
- 제공자와 모델을 고르는 법, 그리고 모델의 최소 조건(컨텍스트 64K 토큰)
- 설정이 저장되는 두 파일과, 파일을 직접 열지 않고 값을 넣는 법
- 첫 대화가 성공했는지 판단하는 네 가지 기준과 이어 하기
- 잘 안 될 때 보는 표와, 이상할 때 따라가는 복구 순서
- 설치하기 — 두 방법 가운데 하나를 골라
hermes명령이 생기게 합니다. - 제공자와 모델 고르기 — 원문이 “가장 중요한 설정 단계”라고 부르는 곳입니다.
- 첫 대화 — 무엇을 물어보고, 무엇이 보이면 성공인지.
- 이어 하기 — 방금 한 대화로 돌아올 수 있는지 확인합니다.
나머지는 필요해질 때 읽습니다. 막히면 장 끝의 「자주 겪는 실패」와 「복구 순서」로 갑니다.
어떤 길로 시작할까 — 목표별 가장 빠른 길
Hermes Agent 는 AI 에이전트(말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)입니다. 이후로는 줄여서 Hermes 라고 부릅니다. 빠른 시작 문서는 자신이 이런 사람을 위한 글이라고 밝힙니다.
처음 써 보는 사람
돌아가는 상태까지 가장 짧은 길을 원할 때
제공자를 바꾸려는 사람
설정 실수로 시간을 잃고 싶지 않을 때. 제공자(provider — AI 모델을 빌려주는 서비스)
여럿이 쓰는 구성을 준비하는 사람
팀용, 봇용, 또는 항상 켜 두는 용도로 Hermes 를 차릴 때
“설치는 됐는데 아무것도 안 돼요”
이 상황에 지친 사람
이 장 전체는 아래 다섯 정거장을 차례로 지납니다. 앞의 네 개가 “깨끗한 대화 한 번”을 만드는 일이고, 다섯째는 그 뒤에 골라서 얹는 것입니다.
목표가 뚜렷하다면 아래 표에서 내 줄을 찾아 그 명령부터 시작합니다. 명령은 모두 터미널(글자로 명령을 입력하는 창)에 입력합니다.
| 내 목표 | 먼저 할 일 | 그다음 |
|---|---|---|
| 내 컴퓨터에서 일단 돌아가게 하고 싶다 | hermes setup | 실제로 대화를 해 보고 답이 오는지 확인합니다 |
| 쓸 제공자를 이미 정했다 | hermes model | 설정을 저장하고 대화를 시작합니다 |
| 봇이나 항상 켜 두는 구성을 원한다 | CLI(터미널에서 글자로 쓰는 프로그램 화면)가 된 뒤에 hermes gateway setup | Telegram, Discord, Slack 같은 플랫폼을 연결합니다 |
| 내 컴퓨터나 직접 운영하는 서버의 모델을 쓰고 싶다 | hermes model → custom endpoint(직접 지정하는 접속 주소) | 접속 주소, 모델 이름, 컨텍스트 길이를 확인합니다 |
| 제공자 여러 곳을 두고 하나가 안 되면 다른 곳으로 넘기고 싶다(multi-provider fallback) | 먼저 hermes model | 기본 대화가 된 뒤에만 routing·fallback 설정을 더합니다 |
설치하기 — 두 가지 방법
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)는 일부러 인증 정보를 빼므로 전체 백업이 아닙니다. 절차는 공식 문서 참고(이 가이드는 다루지 않음).
설치 스크립트가 하는 일과 옵션
원문은 스크립트가 의존성 준비를 PM 에 맡긴다고 적습니다. PM 은 원문이 부르는 이름 그대로이며, Hermes 가 필요한 프로그램을 버전까지 고정해 내려받고 맞춰 주는 관리 도구입니다(명령은 hermes pm …).
| 단계 | 내용 |
|---|---|
| 소스 받기 | 소스를 복제(clone)하고 uv 를 준비한 뒤, 의존성 준비를 PM 에 넘깁니다. |
| PM 이 갖추는 것 | 버전을 고정한 Python, Node.js, npm, pnpm, ripgrep, FFmpeg. |
| Python 추가 묶음 | all extra 를 고릅니다. 선택 extra 전부를 뜻하지는 않습니다. |
| 브라우저·컴퓨터 조작 도구 | 기본으로 설치합니다. 고정 버전 Chromium(Chrome for Testing — Hermes 가 내 컴퓨터에서 브라우징할 때 띄움)과 cua-driver(컴퓨터 조작 드라이버 — macOS, Windows, glibc Linux). 내려받기가 실패해도 설치는 끝나고, 다시 시도할 명령을 알려 줍니다. |
browser_exec 뒤의 드라이버 | browser-harness(Browser Use CLI 의 엔진)는 일반 Python 의존성이라, Desktop 앱을 포함한 모든 설치에 이미 들어 있습니다. |
| PM 에 Chromium 이 없는 곳 | Android/Termux, musl Linux 에서는 PATH 에 있는 시스템 chromium 을 대신 씁니다. |
| 마무리 | 실행 파일(launcher)을 만들고 데이터 폴더를 준비합니다. 사람이 직접 실행한 경우 setup 과 게이트웨이 구성도 이어서 띄웁니다. 그 밖의 선택 도구는 기능별 설치 경로를 따릅니다. |
옵션은 앞쪽이 POSIX(Linux·macOS) 스크립트, 뒤쪽이 Windows 스크립트의 표기입니다.
| 옵션 | 하는 일 |
|---|---|
--channel main / -Channel main | 새 설치는 기본으로 최신 안정 릴리스에 놓이고, 이후 hermes update 도 그 채널을 따릅니다. main 의 최신을 설치하려면 이 옵션을 줍니다(한 줄 명령에서는 먼저 HERMES_INSTALL_CHANNEL=main 을 설정). |
--skip-browser / -SkipBrowser | 브라우저 도구를 빼고 설치합니다. |
--skip-computer-use / -SkipComputerUse | 컴퓨터 조작 드라이버를 빼고 설치합니다. Hermes 는 이 선택을 기억해서, 이후 설치나 hermes update 가 다시 넣지 않습니다. hermes pm install chromium 또는 hermes pm install cua-driver 를 실행하면 설치되고 선택도 되돌려집니다. |
--non-interactive / -NonInteractive | 입력이 필요한 단계를 건너뜁니다. |
--include-desktop / -IncludeDesktop | 데스크톱을 소스에서 빌드하는 단계를 더합니다(선택). |
--verbose / -Verbose | git, uv, 빌드의 출력을 전부 흘려보냅니다. HERMES_INSTALL_VERBOSE=1, CI 환경(CI 나 GITHUB_ACTIONS 가 설정된 경우), 출력을 다른 곳으로 돌린 경우에도 같습니다. |
설치 위치 표 (Install layout)
| 방법 | 코드 | 명령 실행 지점 | 기본 사용자 데이터 |
|---|---|---|---|
| POSIX 소스 스크립트 | ~/.hermes/hermes-agent/ | ~/.local/bin/hermes wrapper | ~/.hermes/ |
| Windows 소스 스크립트 | %LOCALAPPDATA%\hermes\hermes-agent\ | %LOCALAPPDATA%\hermes\bin\ | %LOCALAPPDATA%\hermes\ |
| Desktop 꾸러미 | 설치된 앱 패키지 안 | 패키지에 든 launcher, Windows 실행 별칭 | 플랫폼 기본 Hermes 데이터 폴더 |
| Docker | /opt/hermes/ | 이미지 entrypoint 와 hermes shim | 마운트된 /opt/data/ |
| Termux APT | $PREFIX/lib/hermes-agent/ | $PREFIX/bin/ 의 심볼릭 링크 | ~/.hermes/ |
HERMES_HOME이 사용자 데이터 위치를 정합니다. POSIX 스크립트의--dir은 소스 위치를 그와 별개로 정합니다. Windows 는-HermesHome과-InstallDir을 씁니다.- POSIX 스크립트를 root 로 실행해도 FHS 배치를 자동으로 고르지 않습니다. 소스 경로를 직접 주지 않으면 root 의 홈 폴더를 씁니다.
- PM 의 도구 저장소와 설치본별 Python 은 수명이 서로 다릅니다(위치는 공식 문서 Package management 쪽).
- 프로그램 설치를 고치겠다고 데이터 폴더를 지우지 않습니다.
Desktop 의 다른 형태 — Hermes-Setup, 원격 백엔드, Store 패키지
- Hermes-Setup bootstrap installer 는 위 패키지와 다릅니다. 소스 설치본을 내려받아 데스크톱 앱을 빌드합니다(공식 문서 Hermes Desktop 쪽).
- 원격 전용 Desktop 은 따로 없습니다. 다른 컴퓨터에서 도는 Hermes 백엔드와 함께 쓰려면 위 패키지 가운데 하나를 설치하고 Settings → Gateways(설정 → 게이트웨이)에서 연결합니다(공식 문서 Connecting to a remote backend 쪽).
- Microsoft Store 패키지는 소유 주체가 Store 로 따로입니다. macOS 의 ZIP 파일에는 자동 업데이트가 쓰는 서명된 앱이 들어 있습니다.
- 어떤 운영체제·배포 방식·기능이 지원되는지 전체 표는 공식 문서 Platform Support 쪽에 있습니다(이 가이드는 다루지 않음).
미리 갖춰야 하는 것
결론부터 말하면, 준비물은 설치 방법에 따라 다릅니다. Desktop 패키지는 다 만들어진 꾸러미라 소스를 조립할 때 필요한 준비물이 해당하지 않습니다. 명령 한 줄로 설치할 때는 내 컴퓨터에 기본 도구 몇 가지가 있어야 하고, 나머지는 설치 과정이 알아서 가져옵니다.
| 설치 방법 | 내가 갖춰 둘 것 | 설치 과정이 알아서 하는 것 |
|---|---|---|
| Desktop 패키지 | macOS 는 Apple Silicon 이어야 합니다 | 에이전트, Python, 부품이 꾸러미에 들어 있습니다. 소스 빌드용 준비물은 해당하지 않습니다. |
| 명령 한 줄 (Linux·macOS·WSL2) | Git(파일의 변경 이력을 관리하는 프로그램), curl(인터넷에서 파일을 받아 오는 명령), tar(묶음 파일을 푸는 명령), SHA-256 도구(받은 파일이 원본과 같은지 확인) | uv(설치에 쓰는 도구) 는 스크립트가 검증된 고정 버전을 항상 직접 내려받습니다(내 컴퓨터에 이미 있는 uv 는 쓰지 않음). Python, Node.js 등은 PM(Hermes 의 프로그램 관리 도구)이 고정 버전으로 준비합니다. |
| 명령 한 줄 (Windows) | 원문에 따로 적힌 목록이 없습니다 | Git 이 없으면 고정 버전 Git for Windows 를 직접 받아 씁니다. |
Python 을 따로 설치할 필요는 없습니다. 현재 공식 설치본은 Python 3.14 로 돌고, 그 Python 은 설치 과정이 준비합니다. Node.js 도 PM 이 정해 둔 목록(pm/lock.json)의 버전을 쓰며, 내 컴퓨터에 깔린 임의의 Node 버전을 가져다 쓰지 않습니다. Linux 의 Chromium 은 배포판이 제공하는 시스템 라이브러리가 필요합니다.
설치가 준비물 때문에 멈췄다면 자주 겪는 실패와 10장의 설치 문제를 봅니다.
Python 버전 범위 · 소스 빌드 · Linux 의 libatomic
pyproject.toml의 넓은 범위>=3.11,<3.15는, 예전 Python 으로 깔린 설치본이 업데이트 프로그램을 돌릴 수 있게 하려는 것입니다. PM 이 그 설치본을 3.14 로 바꿔 줍니다. 3.11~3.13 에서 지금 실행이 지원된다는 약속은 아닙니다.- 소스에서 빌드하면 네이티브 컴파일러와 플랫폼 개발 라이브러리가 필요할 수 있습니다. Electron 을 소스에서 빌드하면 Node 네이티브 모듈 요구 사항이 더해집니다. 완성된 Desktop 패키지를 설치할 때는 해당하지 않습니다.
- glibc Linux 에서는 PM 이 관리하는 Node.js 가
libatomic.so.1을 필요로 하는데, 최소 구성의 Debian·Ubuntu·RHEL 계열 이미지에는 이 라이브러리가 없습니다. 없으면 설치 프로그램과hermes update가 배포판 패키지를 설치합니다.
| 패키지 관리자 | 설치하는 패키지 |
|---|---|
| apt, zypper | libatomic1 |
| dnf/yum, apk | libatomic |
| pacman | gcc-libs |
root 로 실행 중이면 패키지 관리자를 바로 부르고, 아니면 sudo -n 으로 부릅니다. 사람이 직접 실행한 경우 의존성을 설치하기 전에 sudo 비밀번호를 한 번 묻습니다. --non-interactive 실행은 묻지 않습니다. 설치를 못 하면 오류 메시지가 찾아낸 패키지 관리자에 맞는 정확한 명령을 알려 줍니다.
Nix 사용자
Nix 는 더 이상 명시적으로 지원하는 설치 경로가 아닙니다(되는 데까지만 지원). 이미 Nix 를 쓰고 있다면(NixOS, macOS, Linux) Nix flake, 선언형 NixOS 모듈, 선택형 컨테이너 모드를 갖춘 전용 설정 경로가 있습니다. 공식 문서 Nix & NixOS Setup 쪽 참고(이 가이드는 다루지 않음).
직접 설치 · 개발자용 설치 (Manual / Developer Installation)
소스를 직접 받아 쓰려면 PM developer workflow 부터 시작합니다. 활성화, 날마다 쓰는 명령, 의존성 새로 고침, 현재 bootstrap 의 한계를 다룹니다. 별도의 테스트 환경과 검사는 Development Setup 쪽에 있습니다(둘 다 이 가이드는 다루지 않음).
sudo 없는 계정 · 서비스 전용 계정으로 설치 (Non-Sudo / System Service User Installs)
소스 설치 프로그램은 실제로 서비스를 돌릴 그 사용자로 실행합니다. 홈 폴더, 도구 저장소, 설정, 실행 파일이 모두 그 사용자 소유여야 합니다.
- 관리자 계정으로: 소스 빌드 준비물과 Chromium 에 필요한 Linux 라이브러리를 설치합니다(서비스가 내 컴퓨터에서 브라우징할 때만).
- 서비스 사용자로: 평소와 같은 설치 명령(
curl … install.sh | bash한 줄)을 실행합니다. - 실행 파일이 있는 폴더를 서비스 사용자의 셸 환경에 더합니다.
export PATH="$HOME/.local/bin:$PATH" - 그 계정에서
hermes doctor를 실행합니다. 설치된 wrapper 를 쓰고,venv/bin/hermes같은 경로를 직접 적어 넣지 않습니다. - 로그아웃해도 살아 있어야 하는 Linux 사용자 서비스라면 관리자 계정으로 lingering 을 켭니다.
sudo loginctl enable-linger SERVICE_USER
현재 소스 설치 프로그램은 Playwright 의 --with-deps 단계를 실행하지 않습니다. Node.js 의 libatomic 말고는 시스템 패키지를 설치하지 않습니다. PM 은 도구 실행 파일을 관리하고, 시스템 라이브러리는 관리자가 제공합니다. sudo 가 없는 서비스 사용자에게는 관리자에게 부탁할 정확한 libatomic 명령이 표시됩니다. 관련 내용은 공식 문서 Browser automation, Messaging Gateway 쪽.
제공자와 모델 고르기 — 가장 중요한 단계
원문이 “가장 중요한 설정 단계”라고 부르는 곳입니다. 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) 쪽에 있습니다(이 가이드는 다루지 않음).
Blank Slate 가 끄는 것과 다시 켜는 법
- 남는 것: 제공자와 모델, File Operations 툴셋(toolset — 도구 꾸러미), Terminal 툴셋.
- 꺼지는 것: 웹, 브라우저, 코드 실행, 비전, 기억, 위임, 예약 작업(cron), 스킬, 플러그인, MCP 서버. 압축(compression), 체크포인트, smart routing, 기억 자동 저장(memory capture)도 모두 꺼집니다.
- 최소 구성이 적용된 뒤 두 길 가운데 하나를 고릅니다. 전부 꺼 둔 채 지금 끝내거나, 모든 설정을 하나씩 거치며 도구·스킬·플러그인·MCP·메신저를 골라 켭니다.
- Blank Slate 는
platform_toolsets.cli목록과agent.disabled_toolsets를 명시해 기록합니다. 그래서 고르지 않은 것은hermes update뒤에도 올라오지 않습니다. - 나중에 다시 켜려면
hermes tools, 스킬을 채우려면hermes skills opt-in --sync, 설정을 다듬으려면hermes setup agent를 씁니다.
원문 제공자 표의 나머지 33줄
원문 표는 38줄이고, 위 본문 표의 다섯 줄을 뺀 나머지입니다. 원문의 “Set …” 은 그 이름의 환경 변수(프로그램에 값을 건네주는 이름표)에 키를 넣는다는 뜻입니다. 값은 hermes config set 이름 값 으로 넣을 수 있습니다(다음 소절).
| 제공자 | 어떤 곳인가 | 설정 방법 |
|---|---|---|
| Fireworks AI | OpenAI 호환 모델 API 직접 연결 | FIREWORKS_API_KEY |
| Z.AI | GLM / Zhipu 가 호스팅하는 모델 | GLM_API_KEY / ZAI_API_KEY (Z_AI_API_KEY 도 받음) |
| Kimi / Moonshot | Moonshot 이 호스팅하는 코딩·대화 모델 | KIMI_API_KEY (또는 Kimi-Coding 전용 KIMI_CODING_API_KEY) |
| Kimi / Moonshot China | 중국 지역 Moonshot 접속점 | KIMI_CN_API_KEY |
| Arcee AI | Trinity 모델 | ARCEEAI_API_KEY |
| GMI Cloud | 여러 모델 직접 API | GMI_API_KEY |
| Actual Computer | 내 하드웨어를 비공개 추론 클러스터로 — 호스팅 relay 또는 로컬 daemon | ACTUAL_API_KEY(relay) 또는 ACTUAL_BASE_URL=http://127.0.0.1:8080(로컬, 키 없음) |
| MiniMax (OAuth) | 브라우저 OAuth 로 쓰는 MiniMax 최신 모델 — API 키 불필요(hermes_cli/models.py 의 모델 이름은 릴리스마다 바뀔 수 있음) | hermes model → MiniMax (OAuth) |
| MiniMax | MiniMax 국제 접속점 | MINIMAX_API_KEY |
| MiniMax China | 중국 지역 MiniMax 접속점 | MINIMAX_CN_API_KEY |
| Alibaba Cloud | DashScope 를 통한 Qwen 모델 | DASHSCOPE_API_KEY (Qwen Coding Plan 은 ALIBABA_CODING_PLAN_API_KEY 도 받음) |
| Hugging Face | 통합 라우터로 20개 넘는 공개 모델(Qwen, DeepSeek, Kimi 등) | HF_TOKEN |
| AWS Bedrock | native Converse API 로 Claude, Nova, Llama, DeepSeek | IAM role 또는 aws configure (원문은 별도 안내를 가리킴) |
| Azure Foundry | Azure AI Foundry 가 호스팅하는 모델 | AZURE_FOUNDRY_API_KEY + AZURE_FOUNDRY_BASE_URL |
| Google AI Studio | Gemini 모델 직접 API | GOOGLE_API_KEY / GEMINI_API_KEY |
| xAI | Grok 모델 직접 API | XAI_API_KEY |
| xAI Grok OAuth | SuperGrok / Premium+ 구독, API 키 불필요 | hermes model → xAI Grok OAuth |
| NovitaAI | 여러 모델 API 게이트웨이 | NOVITA_API_KEY |
| Ramp Router | OpenAI/Anthropic/xAI 등으로 이어 주는 Responses-native LLM 게이트웨이 | RAMP_ROUTER_API_KEY |
| Nebius Token Factory | Nebius AI 클라우드의 공개 모델 | NEBIUS_API_KEY |
| StepFun | Step Plan 모델 | STEPFUN_API_KEY |
| Xiaomi MiMo | Xiaomi 가 호스팅하는 모델 | XIAOMI_API_KEY |
| Tencent TokenHub | Tencent 가 호스팅하는 모델 | TOKENHUB_API_KEY |
| Tencent TokenPlan | Anthropic 방식 접속점으로 쓰는 Tencent Hy 모델 | TOKENPLAN_API_KEY |
| Ollama Cloud | 관리형 Ollama 호스팅 모델 | OLLAMA_API_KEY |
| LM Studio | OpenAI 호환 API 를 내주는 로컬 데스크톱 앱 | LM_API_KEY (기본값이 아니면 LM_BASE_URL 도) |
| Qwen OAuth | Qwen Portal 브라우저 OAuth — API 키 불필요 | hermes model → Qwen OAuth |
| Kilo Code | KiloCode 가 호스팅하는 모델 | KILOCODE_API_KEY |
| OpenCode Zen | 골라 둔 모델을 쓴 만큼 내고 사용 | OPENCODE_ZEN_API_KEY |
| OpenCode Go | 공개 모델용 월 $10 구독 | OPENCODE_GO_API_KEY |
| DeepSeek | DeepSeek API 직접 사용 | DEEPSEEK_API_KEY |
| NVIDIA NIM | build.nvidia.com 또는 로컬 NIM 의 Nemotron 모델 | NVIDIA_API_KEY (선택: NVIDIA_BASE_URL) |
| Vercel AI Gateway | Vercel AI Gateway 라우팅 | AI_GATEWAY_API_KEY |
설정이 저장되는 두 파일
Hermes 는 비밀 값과 보통 설정을 서로 다른 파일에 나눠 둡니다.
| 무엇을 | 어디에 | 예 |
|---|---|---|
| 비밀 값과 인증 토큰 | ~/.hermes/.env | API 키 같은 것. 여기서 토큰은 로그인 증표를 말하며, 글의 양을 세는 토큰과는 다른 뜻입니다 |
| 비밀이 아닌 설정 | ~/.hermes/config.yaml | 쓸 모델 이름, 터미널 백엔드 같은 것 |
~ 는 내 홈 폴더(내 계정의 개인 폴더)를 뜻합니다. 그 안의 .hermes 폴더가 Hermes 의 데이터 폴더입니다. Windows·Docker·Desktop 꾸러미는 위치가 다르며, 설치하기의 접힌 상자 「설치 위치 표」에 있습니다.
그래서 가장 쉽고 틀리지 않는 방법은 파일을 직접 열지 않고 명령으로 값을 넣는 것입니다. 원문의 예 세 줄과 그 뜻입니다.
| 명령 | 뜻 |
|---|---|
hermes config set model anthropic/claude-opus-4.6 | 쓸 모델을 정합니다 |
hermes config set terminal.backend docker | 터미널 백엔드(에이전트의 명령이 실제로 실행되는 곳 — 내 컴퓨터, Docker, SSH 등)를 Docker 로 정합니다 |
hermes config set OPENROUTER_API_KEY sk-or-... | OpenRouter 의 API 키를 넣습니다(sk-or-... 자리에 내 키) |
hermes config get 을 씁니다. 업데이트한 뒤 설정이 빠진 것 같으면 hermes config check 를 실행하고 이어서 hermes config migrate 를 실행합니다. 설정 파일을 본격적으로 다루는 법은 3장 「설정 파일」과 「설정 관리」에 있습니다.
첫 대화 — 되는지 확인하기
제공자(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(세션 목록 보기)로 확인합니다. |
핵심 기능 네 가지 맛보기
첫 대화가 됐다면 같은 화면에서 네 가지를 한 번씩 해 봅니다. 모두 2장에서 자세히 다루므로 여기서는 손에 익히는 정도면 됩니다.
❯ What's my disk usage? Show the top 5 largest directories.
뜻: 디스크를 얼마나 쓰고 있지? 가장 큰 폴더 다섯 개를 보여 줘.
에이전트가 내 대신 터미널 명령을 실행하고 결과를 보여 줍니다. 말로만 답하는 챗봇과 달라지는 지점입니다. 도구 전반은 4장에서 다룹니다.
입력 칸에 / 를 치면 모든 명령이 자동 완성 목록으로 뜹니다. 이렇게 / 로 시작하는 것을 슬래시 명령이라고 부릅니다.
| 명령 | 하는 일 |
|---|---|
/help | 쓸 수 있는 모든 명령을 보여 줍니다 |
/tools | 쓸 수 있는 도구 목록을 보여 줍니다 |
/model | 모델을 고르는 화면에서 바꿉니다 |
/personality pirate | 재미 삼아 성격을 바꿔 봅니다(pirate — 해적 말투) |
/save | 대화를 저장합니다 |
더 많은 명령은 2장 「슬래시 명령」.
Enter 는 보내기이므로, 줄을 바꾸려면 다른 키를 씁니다.
| 키 | 어디서 되나 |
|---|---|
| Alt+Enter, Ctrl+J | 모든 터미널 |
| Shift+Enter | 이 키를 별도 신호로 보내 주는 터미널에서만. Kitty, foot, WezTerm, Ghostty 는 기본으로 되고, iTerm2, Alacritty, VS Code 터미널은 Kitty keyboard protocol 을 켠 뒤에 됩니다 |
자세한 것은 2장 「여러 줄 입력」.
에이전트가 너무 오래 걸리면 기다리지 않아도 됩니다. 새 메시지를 입력하고 Enter 를 누르면 하던 작업을 멈추고 새 지시로 넘어갑니다. Ctrl+C 로도 멈출 수 있습니다. 자세한 것은 2장 「끼어들기」.
다음 층 올리기 — 기본 대화가 된 뒤에만
여기부터는 선택입니다. 원문은 “기본 대화가 된 뒤에만”이라고 못 박고, 필요한 것만 고르라고 합니다.
hermes gateway setup # Interactive platform configuration
뜻: 질문에 답하며 메신저 플랫폼 연결을 설정합니다.
게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)로 Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant(플러그인), Microsoft Teams 를 연결합니다. 봇으로 쓰거나 여럿이 함께 쓰는 비서로 만들 때 필요합니다. → 8장
스킬(skill — 특정 일을 하는 방법을 적은 설명서)은 필요할 때만 꺼내 읽는 지시 문서입니다. 하나하나가 이름, 설명, 단계별 절차를 담은 SKILL.md 파일입니다. 에이전트는 짧은 설명만 미리 읽고, 일이 실제로 그 스킬을 필요로 할 때에만 전체를 불러옵니다. 그래서 스킬을 늘려도 매 요청이 무거워지지 않습니다.
기본 스킬 묶음은 ~/.hermes/skills/ 에 이미 설치되어 있습니다. Skills Hub(스킬을 찾아 설치하는 곳)에서 더 받거나 직접 쓸 수도 있습니다.
| 명령 | 하는 일 |
|---|---|
hermes skills browse | 받을 수 있는 스킬을 모두 봅니다. 설치할 때 쓸 정확한 이름도 여기서 확인합니다 |
hermes skills search kubernetes | 낱말로 스킬을 찾습니다 |
hermes skills install openai/skills/k8s | 하나를 설치합니다(먼저 보안 검사를 함). openai/skills/k8s 는 “OpenAI 목록의 k8s 스킬”이라는 뜻의 출처/경로 이름입니다 |
/k8s deploy the staging manifest | 설치한 스킬은 자동으로 슬래시 명령이 됩니다. 요청을 붙여 실행합니다 |
/k8s | 스킬만 불러오고, 무엇이 필요한지는 Hermes 가 묻게 합니다 |
CLI 와 연결된 메신저 어디서나 됩니다. 전부 미리 설치할 필요는 없습니다. 평소 대화 중에 일이 맞으면 에이전트가 기본 스킬을 스스로 골라 씁니다. → 6장
안전을 위해 에이전트의 명령을 내 컴퓨터가 아니라 Docker 컨테이너(내 컴퓨터와 분리된 작은 실행 칸)나 원격 서버에서 실행하게 할 수 있습니다.
hermes config set terminal.backend docker # Docker isolation
hermes config set terminal.backend ssh # Remote server
뜻: 터미널 백엔드(명령이 실제로 실행되는 곳)를 Docker 또는 SSH 원격 서버로 바꿉니다. → 4장, 9장
Docker 에서 진짜 API 키를 감추는 egress proxy
Docker 를 쓸 때는 egress credential-injection proxy 를 켜서, 컨테이너 안에서는 진짜 API 키가 보이지 않게 할 수 있습니다. 안에서는 로컬의 TLS 가로채기 daemon 뒤에서만 통하는 대용 토큰만 보입니다. 설정은 hermes egress setup && hermes egress start 이고, hermes setup terminal 도 Docker 사용자에게 이것을 안내합니다. Modal, SSH, Daytona, Singularity 는 아직 연결되어 있지 않습니다(공식 문서 Egress proxy 쪽).
hermes tools 를 실행해 Voice providers 를 설정합니다. 그다음 CLI 에서 /voice on 으로 켜고 Ctrl+B 를 눌러 녹음합니다.
빠진 요구 사항 가운데 지원되는 것은 PM 이 처리하며, 의존성이 바뀌면 다시 시작해야 할 수 있습니다. 로컬 Faster-Whisper 는 모든 아키텍처에서 되지는 않습니다. 공식 문서 Voice Mode 쪽 참고(이 가이드는 다루지 않음).
MCP(Model Context Protocol — 외부 서비스의 도구를 에이전트에 연결하는 공통 규격) 서버는 ~/.hermes/config.yaml 에 적어 넣습니다. 원문은 여기에 GitHub 서버 예시만 싣습니다. 뜻과 추가 방법은 4장에서 다룹니다.
# Add to ~/.hermes/config.yaml
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
hermes acp
뜻: 편집기와 연동하는 ACP 를 실행합니다.
ACP 지원은 표준 [all] 묶음에 들어 있어서, curl 한 줄로 설치했다면 이미 포함되어 있습니다. 원문은 ACP 가 무엇인지 여기서 풀지 않고 ACP Editor Integration 쪽을 가리킵니다(이 가이드는 다루지 않음).
[all] 없이 설치한 경우
cd ~/.hermes/hermes-agent && python -c "import pm; pm.sync_venv(['acp'], explicit=True)"
먼저 위 명령을 실행합니다. 빠른 시작 문서의 Python 의존성 명령은 PM 이 준비한 소스 설치본을 전제로 하며, 의존성을 바꾼 뒤에는 그 설치본을 다시 활성화하고 Hermes 를 다시 시작해야 합니다.
자주 겪는 실패와 고치는 법
원문이 “시간을 가장 많이 잡아먹는 문제”로 꼽은 여섯 가지입니다. 증상 줄을 찾아 오른쪽 칸대로 합니다.
| 증상 | 흔한 원인 | 고치는 법 |
|---|---|---|
| Hermes 는 열리는데 답이 비어 있거나 깨져 있다 | 제공자 인증이나 모델 선택이 틀렸다 | hermes model 을 다시 실행해 제공자, 모델, 인증을 확인합니다 |
| custom endpoint 가 “되기는” 하는데 엉뚱한 글이 온다 | 접속 주소나 모델 이름이 틀렸거나, 실제로는 OpenAI 호환이 아니다 | 그 접속 주소를 다른 프로그램에서 먼저 확인합니다 |
| 게이트웨이는 켜졌는데 아무도 메시지를 보낼 수 없다 | 봇 토큰, 허용 목록, 플랫폼 설정이 덜 됐다 | hermes gateway setup 을 다시 돌리고 hermes gateway status 를 봅니다 |
hermes --continue 가 예전 세션을 못 찾는다 | 프로필을 바꿨거나 세션이 저장되지 않았다 | hermes sessions list 를 보고 맞는 프로필인지 확인합니다 |
| 모델을 쓸 수 없다고 나오거나 엉뚱한 모델로 넘어간다 | 제공자 routing·fallback 설정이 지나치게 적극적이다 | 기본 제공자가 안정될 때까지 routing 을 꺼 둡니다 |
hermes doctor 가 설정 문제를 짚는다 | 설정 값이 빠졌거나 오래됐다 | 설정을 고치고, 기능을 더하기 전에 평범한 대화부터 다시 시험합니다 |
설치 문서는 설치 직후에 만나는 세 가지를 따로 적습니다.
| 문제 | 해결 |
|---|---|
hermes: command not found(명령을 찾을 수 없음) | 셸 설정을 다시 읽거나(source ~/.bashrc) PATH(명령을 찾아보는 폴더 목록)를 확인합니다 |
API key not set(API 키가 없음) | hermes model 로 제공자를 설정하거나 hermes config set OPENROUTER_API_KEY your_key 를 실행합니다 |
| 업데이트 뒤 설정이 빠졌다 | hermes config check 다음에 hermes config migrate 를 실행합니다 |
hermes doctor
무엇이 빠졌고 어떻게 고치는지 알려 주는 진단 명령입니다. 더 많은 증상은 10장 「설치 문제」와 「제공자 문제」, 따라 하는 절차는 활용편 「막힘 해결 ①」에 있습니다.
홈 폴더를 심볼릭 링크·외장 저장소에 둔 경우
- Hermes 는 심볼릭 링크(다른 위치를 가리키는 바로 가기)로 된
HERMES_HOME과 그 아래 폴더(hooks, skills, sessions, logs 등)를 지원합니다. 홈 폴더를 준비할 때 기존 링크는 그대로 두고, 링크된 폴더와 그 아래(logs/curator등)의 권한은 주인에게 맡깁니다. - 링크가 가리키는 곳이 없거나, 접근할 수 없거나, 폴더가 아니면 준비를 멈추고 그 경로와 대상을 적은 storage 오류를 냅니다. Hermes 는 링크를 바꾸거나 빠진 대상을 만들지 않습니다. 외장·NAS 저장소가 연결되지 않은 사이에 내 디스크에 데이터를 써 버릴 수 있기 때문입니다.
- 고치는 법: 알려 준 링크를 확인하고, 저장소 연결을 되살리거나 대상을 바로잡고, 접근 권한을 확인한 뒤 다시 시도합니다. 새 대상을 일부러 쓰려면 의도한 저장소가 연결됐는지 확인한 뒤 직접 만듭니다.
hermes doctor는 이것을 잘못된 YAML 이 아니라 storage 문제로 보고합니다. 기존config.yaml은 그대로 둡니다. 폴더를 쓸 수 없는 문제는hermes setup으로 고쳐지지 않습니다. 폴더가 있는지만 보는 검사라서, 의도한 저장소가 연결됐다는 보증은 아닙니다.
복구 순서 — 이상하면 이 순서로
어디가 틀렸는지 감이 안 올 때는 고민하지 말고 정해진 순서대로 여섯 명령을 돌립니다. 원문은 이 순서가 “뭔가 이상한 느낌”에서 “상태를 아는 지점”으로 빨리 돌아오게 해 준다고 적습니다.
업데이트는 누가 맡나 — 설치 방식 자동 감지 (Install method auto-detection)
업데이트를 누가 맡는지는 데이터 폴더만이 아니라 지금 실행 중인 설치본에 따라 정해집니다. 소스로 설치한 경우는 Hermes 가 관리하는 Git 업데이트 경로를 씁니다. Desktop 꾸러미, Docker, Nix, Termux 패키지는 각 패키지 쪽의 업데이트 방식을 그대로 따릅니다. hermes doctor 가 어떤 방식으로 설치됐는지 알려 줍니다. 패키지가 관리하는 파일을 고치기 전에 공식 문서 Updating & Uninstalling 쪽을 봅니다(이 가이드는 다루지 않음).
자주 쓰는 명령 한 장과 다음에 읽을 것
| 명령 | 하는 일 |
|---|---|
hermes | 대화를 시작합니다 |
hermes model | 제공자와 모델을 고릅니다 |
hermes tools | 플랫폼별로 어떤 도구를 켤지 정합니다 |
hermes setup | 설정 마법사 전체(한 번에 다 정함) |
hermes doctor | 문제를 진단합니다 |
hermes update | 최신 버전으로 올립니다 |
hermes gateway | 메신저 게이트웨이를 시작합니다 |
hermes --continue | 마지막 세션을 이어 합니다 |
원문이 권하는 다음 읽을거리를 이 가이드의 장에 맞춰 옮기면 이렇습니다.
| 원문의 다음 단계 | 이 가이드에서 |
|---|---|
| CLI Guide — 터미널 화면 익히기 | 2장 |
| Configuration — 내 구성 다듬기 | 3장 |
| Tools & Toolsets — 쓸 수 있는 기능 살펴보기 | 4장 |
| Skills System — 다시 쓰는 작업 방법과 지식 | 6장 |
| Messaging Gateway — Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Teams 등 연결 | 8장 |
User Stories(커뮤니티의 실제 구성 사례 — 무엇부터 맡길지 모를 때), AI Providers, Tips & Best Practices, Moving to another machine(hermes backup 으로 구성 전체나 프로필 하나를 옮김) | 공식 문서 참고(이 가이드는 다루지 않음) |
- 순서는 설치 → 제공자 → 첫 대화 → 이어 하기. 대화 한 번이 되기 전에는 기능을 더 얹지 않습니다.
- 설치는 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부터 복구 순서 여섯 단계를 차례로 돌립니다.
출처: hermes-agent.nousresearch.com/docs/getting-started/installation · hermes-agent.nousresearch.com/docs/getting-started/quickstart — 수집일 2026-11-09 의 공식 문서(문서에 버전 표기 없음)
터미널에서 대화하기 — CLI 와 세션
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트)와 가장 기본적으로 만나는 곳은 터미널(글자로 명령을 입력하는 창)입니다. 이 장에서는 대화 화면을 여는 법, 화면 읽는 법, 슬래시 명령(입력 칸에 / 로 시작해 넣는 명령)과 단축키, 일하는 도중에 방향을 바꾸는 법을 익히고, 대화가 세션(대화 한 묶음)으로 저장되어 다시 이어지고·찾아지고·정리되는 방식을 살펴봅니다.
hermes로 대화 화면을 여는 법과, 한 번만 묻고 끝내는 법- 화면의 배너·대화·입력 칸·상태 줄이 각각 무엇을 알려 주는지
- 슬래시 명령과 꼭 필요한 단축키, 여러 줄로 입력하는 법
- Hermes 가 일하는 도중에 말을 걸어 방향을 바꾸거나 멈추는 법
- 세션이 무엇이고, 어떻게 이어 하고·이름 붙이고·찾는지
- 백그라운드 세션, 저장 위치, 오래된 세션을 정리하는 규칙
- CLI 실행하기 —
hermes한 줄로 대화를 시작합니다. - 슬래시 명령 — 입력 칸에
/를 치면 쓸 수 있는 명령이 나옵니다. - 일하는 도중에 방향 바꾸기 — 기다리지 않고 고쳐 말하는 법, 멈추는 법.
- 세션이란 — 대화가 자동으로 저장되는 방식.
나머지 소절은 필요할 때 찾아보면 됩니다. 점선 상자(개발자용 참고)는 모두 건너뛰어도 됩니다.
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 chat --query-file prompt.txthermes chat --query-file - < prompt.txt | 질문을 파일이나 표준 입력에서 읽습니다. 셸이 해석하지 않아 따옴표·$(...)·백틱도 글자 그대로 갑니다. |
hermes chat -s hermes-agent-dev,github-auth | 스킬을 미리 불러와 시작합니다(-s 를 여러 번 써도 됨). 대화형·한 번 묻기 모두. |
skills.auto_load( config.yaml 의 목록) | 적어 둔 스킬을 CLI·TUI·게이트웨이·예약 작업·API 의 모든 새 세션에 불러옵니다. 세션 시작 때 한 번만 읽으므로 고치면 다음 세션부터 적용되고, 없거나 꺼진 스킬은 경고 뒤 건너뜁니다. |
--ignore-rulesHERMES_IGNORE_RULES=1 | 자동 불러오기와 AGENTS.md·SOUL.md·.cursorrules·기억 주입을 건너뜁니다. -s 로 적은 스킬은 불러옵니다. 프로필마다 따로입니다. |
hermes chat --verbose | 디버그용 자세한 출력. 기본은 조용한 모드(quiet mode) — 도구의 장황한 기록을 숨기고 움직이는 표시로 깔끔하게 보여 줍니다. |
hermes -whermes -w -z "Fix issue #123" | 격리된 git 워크트리(같은 저장소를 따로 펼쳐 둔 작업 폴더)에서 실행합니다. 에이전트 여럿을 나란히 돌릴 때. |
원문 예시에는 hermes -w 와 --verbose 가 나오지만, 같은 원문의 다른 절은 기본 CLI 가 이 둘을 받지 않는다고도 적습니다(아래 상자). 거절 안내가 나오면 그 안내를 따르세요.
기본 CLI 는 게이트웨이에 붙는 화면입니다 — 고정·거절되는 옵션과 종료 코드
hermes chat(과 display.interface 가 cli 일 때의 hermes)은 에이전트를 터미널 안에서 직접 돌리지 않습니다. 프로필의 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)를 찾거나 시작해(hermes gateway ensure) 거기에 세션을 만들고 화면만 연결합니다. 그래서 같은 세션을 데스크톱 창·TUI·Telegram 토픽에서 동시에 열 수 있고, 터미널을 닫아도 화면만 떨어집니다(Detached; accepted work continues at the gateway.).
| 구분 | 내용 |
|---|---|
| 세션에 고정되는 것 | 작업 폴더, --model, --provider, --reasoning, --toolsets, --max-turns, --skills, --checkpoints, --yolo, --accept-hooks, --pass-session-id, --ignore-rules, --base-url/--api-key, --safe-mode/--ignore-user-config |
| 거절되는 옵션 (종료 코드 2) | --image, --worktree/-w, --no-restore-cwd, --run-budget, --verbose/-v, --compact, -c <이름> 없는 --create-if-missing. Unsupported gateway CLI options: … 와 함께, 옵션마다 그 기능이 지금 어디 있는지(TUI 옵션·config.yaml 키·hermes 하위 명령) 알려 줍니다. |
| 세션을 못 찾음 (종료 코드 1) | No session found matching '…'. 제목은 정확한 ID → 같은 제목의 가장 최근 “제목 #N” 순으로 찾습니다. |
--safe-mode · --ignore-user-config | 프로필의 기본 모델을 읽지 않으므로 모델을 직접 적습니다: hermes chat --safe-mode --provider openrouter --model anthropic/claude-sonnet-4 -q "hello" |
| 종료 코드 3 | 한 번 묻기로 넣은 질문이 줄 서 있는 동안 돌던 턴이 주인을 잃은 경우. 질문은 줄에 남아 있으니 다시 보내지 말고, 안내된 세션을 대화형으로 이어 열어 그 턴을 확인한 뒤 /discard <admission_id> 로 넘깁니다. |
워크트리(-w) 자동 정리와 플러그인 관리 명령
hermes -w 는 <저장소>/.worktrees/ 아래에 쓰고 버리는 워크트리를 만듭니다. 깨끗한 것은 끝낼 때 브랜치와 함께 지워지고, 커밋·푸시하지 않은 변경이 있거나 아직 쓰이는 중(대기 중인 턴, /loop·/heartbeat·/goal, 예약 작업, 다른 화면)이면 남습니다. 지워진 워크트리의 세션을 이어 하면 같은 경로에 다시 만듭니다(hermes --tui -w 가 만든 것만). 정리는 hermes -w 시작 때와 6시간마다 자동으로 돌며, .worktrees/ 가 10개나 5 GB 를 넘으면 시작할 때 안내가 나옵니다.
| 명령 | 뜻 |
|---|---|
hermes worktree list (--json) | 워크트리별 나이·크기·판정·이유와 보관본. |
hermes worktree prune | 지금 정리하고 합쳐진 브랜치를 지웁니다. --dry-run(무엇을 왜 할지만 출력), --older-than 7(7일 넘게 쉰 것만), --trees-only, --branches-only. |
hermes worktree restore <name> | 보관된 워크트리를 되살립니다(--path DIR). |
/worktree prune [--dry-run] | 세션 안에서 같은 일(지금 쓰는 워크트리는 제외). |
hermes plugins install owner/repository --no-enable | 플러그인을 설치만 합니다. 옮겨 쓰는 Agent Plugins v1 꾸러미는 직접 켜기 전까지 꺼져 있습니다. |
hermes plugins list · enable|disable|update|remove <plugin-name> | 목록 · 켜기/끄기/업데이트/제거. |
안전 약속(요약): 커밋하지 않은 변경과 올리지 않은 커밋은 되살릴 수 있는 보관본 없이 지우지 않고, 쓰는 중인 워크트리와 .worktrees/ 밖에 손으로 만든 것은 건드리지 않습니다. 무시(ignore)된 파일은 보관 없이 함께 지워집니다. 브랜치는 고유한 작업이 있거나 main/master/develop 이면 남깁니다.
화면 구성 — 배너 · 대화 · 입력 칸 · 상태 줄
대화 화면은 위에서 아래로 세 덩어리입니다. 맨 위 환영 배너는 지금 쓰는 모델, 터미널 백엔드(에이전트의 명령이 실제로 실행되는 곳 — 내 컴퓨터 등), 작업 폴더, 쓸 수 있는 도구, 설치된 스킬(특정 일을 하는 방법을 적은 설명서)을 한눈에 보여 줍니다. 가운데 대화 영역에는 내 메시지와 Hermes 가 한 일·답이 차례로 쌓이고, 맨 아래에는 항상 같은 자리에 입력 칸이 있습니다.
화면을 그리는 방식은 두 가지이고, 설정 display.cli_layout 으로 고릅니다. 기본값은 modern 입니다.
모든 내용을 기호 하나로 시작하는 평범한 줄로 찍습니다. 창 너비에 기대지 않으므로 창 크기를 바꿔도 앞선 출력이 깨지지 않습니다. 진행 표시는 입력 칸 바로 위 줄에, 상태 줄은 입력 칸 아래에 있습니다.
❯ add a multiply function and run the tests ∴ Thought for 3s · Planning the change 📖 Read calc.py 🔧 Patch 0.2s │ calc.py │ @@ -1,2 +1,6 @@ │ +def multiply(a, b): │ + return a * b ✗ $ pytest -q 0.4s [exit 1] ☤ Hermes Added multiply; pytest isn't installed here, so I ran the tests directly: 2 passed. ─ 15.0s · edited 1 file +4 -0 · read 2 files · 8:27 AM ── ⠹ Running tests · 14s ─────────── Add multiply to calc.py ─ ❯ type to redirect this turn · Tab queues it for after ────────────────────────────────────────────────────────────── gpt-5-mini · ctx [░░░░░░░░] 4% · ~/project (main) enter interrupt · tab queue · ctrl+c stop
| 줄 머리 기호 | 뜻 |
|---|---|
❯ | 내가 보낸 메시지 |
∴ Thought for 3s · … | Hermes 가 생각을 마쳤다는 표시(걸린 시간과 한 줄 제목) |
이모지 (📖 Read, 💻 $ …) | 끝난 도구 호출 하나. 실패하면 빨간 ✗ 와 종료 코드가 붙습니다. |
│ | 파일을 고쳤을 때 바뀐 줄(diff) |
☤ | Hermes 의 답 |
─ | 그 턴(내 메시지 하나에 에이전트가 일하고 답하는 한 차례)의 요약 줄 |
display.cli_layout: classic 으로 두면 생각과 답을 상자로 둘러 보여 주고, 상태 막대가 입력 칸 위에 놓입니다. 환영 배너는 두 방식이 같습니다.
☤ claude-sonnet-4-20250514 │ 12.4K/200K │ [██████░░░░] 6% │ $0.06 │ 15m
상태 줄 읽기. 상태 줄(classic 에서는 상태 막대)은 실시간으로 바뀌며, 가장 눈여겨볼 것은 컨텍스트(문맥 창 — 모델이 한 번에 기억하며 볼 수 있는 글의 양)가 얼마나 찼는지입니다. 12.4K/200K 는 최대 200K 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위) 가운데 12.4K 를 썼다는 뜻입니다. 막대 색은 찬 정도에 따라 바뀝니다.
/compress 로 대화를 요약해 줄이거나 /new 로 새 세션을 시작합니다.일하는 동안의 표시. Hermes 가 모델의 답을 기다리는 동안에는 생각 중이라는 움직이는 표시가, 도구를 쓸 때마다는 무엇을 했는지 한 줄씩 나옵니다. /verbose 를 입력할 때마다 표시 단계가 off → new → all → verbose 순으로 바뀝니다.
◜ (。•́︿•̀。) pondering... (1.2s) ✧٩(ˊᗜˋ*)و✧ got it! (3.1s) ┊ 💻 terminal `ls -la` (0.3s) ┊ 🔍 web_search (1.2s) ┊ 📄 web_extract (2.1s)
상태 막대의 모든 칸과 표시 규칙
| 칸·규칙 | 뜻 |
|---|---|
| 모델 이름 · 토큰 수 | 모델 이름은 26자를 넘으면 줄입니다. 토큰 수 앞의 ~ 는 로컬 어림값이 섞였다는 표시일 뿐, 압축 판단이나 요청 횟수에는 영향이 없습니다. |
| 비용 | 세션의 예상 비용. 가격을 모르거나 0 인 모델은 n/a. Hermes 에 든 공식 가격표 → 제공자의 /models 목록 순으로 찾고, 공식 직접 API 는 models.dev 정가로 보충합니다. 중계 서비스·직접 지정한 주소는 n/a 로 둡니다. |
🗜️ N · ▶ N · 📌 N | 자동 압축된 횟수 · 아직 도는 /bg 작업 수 · Ctrl+S 로 치워 둔 초안 수. |
| 지난 시간 · 세션 제목 | 세션이 열린 뒤 흐른 시간 · 제목이 생기면 오른쪽 끝에 금색 표지로. |
⚠ YOLO | 자동 승인 모드(hermes --yolo 또는 /yolo)가 켜져 있다는 경고. |
| 창 너비 | 76칸 이상이면 전체, 52–75칸이면 줄인 모양, 52칸 미만이면 모델과 시간(+YOLO 표지)만. |
| modern 의 상태 줄 | 같은 자료에 더해 왼쪽에 작업 폴더(git 브랜치), 오른쪽에 지금 쓸 수 있는 키. display.status_bar.fields 로 왼쪽 칸을 고릅니다. |
/usage | 입력·출력 토큰별 비용 상세. openai-codex 제공자에서는 ChatGPT 계정에 쌓인 한도 초기화 횟수도 보여 주고, /usage reset 으로 하나를 써서 5시간·주간 한도를 되돌립니다(한도가 남았으면 거절, --force 로 강제). |
화면 표시 설정 — 도구 미리 보기 길이·그림 표시·마크다운
~/.hermes/config.yaml(~ 는 내 홈 폴더)의 display: 아래에 적습니다(3장).
| 설정 키 | 하는 일 |
|---|---|
cli_layout | modern(기본) 또는 classic. |
tool_preview_length | 도구 호출 줄에 보여 줄 최대 글자 수. 기본 0 = 제한 없음. 좁은 터미널이면 80 처럼 줄입니다. |
inline_images | 내가 붙인 그림과, 도구가 만들거나 본 로컬 그림을 대화 안에 보여 줍니다. auto(kitty·Ghostty, 기본 CLI 에서는 iTerm2·WezTerm·Konsole 도 원본 해상도. 그 밖에는 블록 문자) · kitty · iterm · unicode · off(경로만). 원격 주소의 그림은 받아 오지 않습니다. 창 크기를 바꾸면 iTerm2 방식 그림은 빈 줄로 남습니다. |
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 를 쓰세요.
이 장의 원문에 나오는 슬래시 명령 모아 보기
전체 목록은 공식 문서 Slash Commands Reference 쪽에 있습니다(이 가이드는 다루지 않음). 아래는 CLI·세션 원문에 나온 나머지입니다. “—” 는 원문이 이름만 적은 명령입니다.
| 명령 | 원문의 설명 |
|---|---|
/new [이름] · /reset · /resume <이름> | 새 세션 시작(이름은 첫 제목이 됨) · 이름으로 세션 열기. |
/compress [here [N] | <focus>] [--preview] | 대화를 요약해 컨텍스트를 줄입니다. |
/stop | 지금 턴과 앞에서 돌던 작업을 취소합니다. |
/busy … · /queue … · /steer | 바쁠 때 입력 방식 · 다음 턴 줄 세우기와 줄 관리 · 지금 실행에 끼워 넣기(방향 바꾸기). |
/approve <id> <choice> · /answer <id> <text> · /branch [title] · /quit | — (승인은 9장) |
/discard <admission_id> | 결과를 알 수 없게 된 턴을 확인하고 넘깁니다. |
/yolo [on|off] | 자동 승인 모드. |
/usage · /verbose · /skin | 비용·토큰 상세 · 도구 진행 표시 단계 · CLI 꾸밈(스킨) 보기·바꾸기. |
/voice on · /voice tts | 음성 모드 켜기(Ctrl+B 로 녹음) · 답을 소리로 읽기. 공식 문서 Voice Mode 쪽 참고(이 가이드는 다루지 않음). |
/personality <이름> | 정해진 말투로 바꿉니다. |
/handoff <platform> · /sethome | 지금 대화를 메신저로 넘기기 · 넘겨받을 홈 채널 정하기(이어 하기). |
/rewind · /save json|md|html | 앞선 메시지로 되감기 · 세션을 파일로 저장. |
/autoprune on|off|later · /worktree prune | 오래된 세션 자동 정리 · 워크트리 정리. |
/paste · /image · /goal · /loop · /heartbeat | — (그림 붙이기, 세션에 걸어 두는 목표·반복으로 언급됨) |
빠른 명령(quick commands) 만들기와 말투(personality) 바꾸기
빠른 명령은 CLI 와 메신저 양쪽에서 됩니다. exec 는 셸 명령 실행, alias 는 다른 슬래시 명령의 별명입니다. 아래처럼 적으면 /status·/restart 를 쓸 수 있습니다.
# ~/.hermes/config.yaml
quick_commands:
status:
type: exec
command: systemctl status hermes-agent
restart:
type: alias
target: /gateway restart
말투. /personality pirate 처럼 고릅니다. 들어 있는 것: helpful, concise, technical, creative, teacher, kawaii, catgirl, pirate, shakespeare, surfer, noir, uwu, philosopher, hype. 되돌리기는 /personality none(default·neutral 도 됨). config.yaml 의 personalities: 아래에 이름: "지시문" 으로 내 것을 더할 수 있습니다(5장).
단축키와 ! 셸 모드
자주 쓰는 키는 많지 않습니다. 원문의 단축키는 모두 Ctrl·Alt 기준으로 적혀 있습니다.
| 키 | 하는 일 |
|---|---|
| Enter | 메시지를 보냅니다. |
| Alt+Enter · Ctrl+J · Shift+Enter | 보내지 않고 줄만 바꿉니다(여러 줄 입력). |
| Tab | 흐리게 뜬 추천 글을 받아들이거나 슬래시 명령을 자동 완성합니다. |
| Ctrl+C | 입력 칸에 쓰던 글이 있으면 그것부터 지웁니다. 입력 칸이 비어 있으면 Hermes 가 하던 일을 멈춥니다. 2초 안에 두 번 누르면 강제로 끝냅니다. |
| Ctrl+D | 빈 입력 칸에서 누르면 Hermes 화면에서 나갑니다. |
| Esc Esc | 앞서 보낸 메시지로 되돌아가 고쳐서 다시 보냅니다(/rewind 와 같음). 쓰던 글이 있을 때는 그 글을 버립니다(↑ 로 되살림). |
| Ctrl+G | 쓰던 글을 편집기($EDITOR — vim·nano·VS Code 등)에서 엽니다. 저장하고 닫으면 그 글이 보내집니다. 긴 글을 쓸 때 좋습니다. |
| Ctrl+V · Alt+V | 글 붙여넣기(클립보드에 그림이 있으면 함께 붙임) · 클립보드의 그림 붙이기(터미널이 지원할 때). |
! 셸 모드. 줄을 ! 로 시작하면 그 줄은 Hermes 에게 보내는 말이 아니라 내가 직접 실행하는 셸 명령(터미널 명령)이 됩니다. 폴더 내용이나 git 상태를 잠깐 확인할 때 대화를 끊지 않아도 됩니다.
> !git status > !ls -la > !pytest -x tests/hermes_cli
비용이 들지 않습니다
모델을 부르지 않습니다 — API 호출도, 토큰도, 기다림도 없습니다.
대화에 남지 않습니다
명령과 결과가 대화 기록에 들어가지 않아 컨텍스트가 깨끗하게 유지됩니다.
내 컴퓨터에서 돕니다
세션의 작업 폴더에서, Hermes 가 돌고 있는 그 컴퓨터에서 실행됩니다.
승인은 그대로입니다
rm -rf 같은 위험한 명령은 에이전트가 실행할 때와 똑같이 승인(실행 전에 나에게 묻는 것)을 거칩니다. 안전장치를 건너뛰는 길이 아닙니다.
나머지 단축키 전체와 셸 모드 세부
| 키 | 하는 일 |
|---|---|
| Ctrl+B | 음성 모드에서 녹음 시작/멈춤(voice.record_key). |
| Ctrl+X Ctrl+E | Ctrl+G 와 같은 외부 편집기 열기. |
| Ctrl+S | 쓰던 초안을 잠시 치워 두고 입력 칸을 비웁니다. 빈 입력 칸에서 다시 누르면 되돌아옵니다. 여러 번 누르면 쌓이고, 둘 이상이면 고르는 패널이 열립니다(Enter 되살림, D 버림). 초안은 디스크에 쓰지 않고 그 세션의 메모리에만 둡니다. |
| Esc Esc (자세히) | 빈 입력 칸에서 두 번 누르면 세션의 모든 질문(›)과 답(•)을 보여 주는 화면이 열립니다. ←/→ 로 질문을 고르고 Enter 로 입력 칸에 되돌립니다. 고쳐 보내면 세션이 그 질문 직전으로 잘리며, 보내기 전에는 아무것도 지워지지 않습니다. f 는 원래 세션을 둔 채 그 지점에서 새 세션을 갈라 냅니다. |
| Ctrl+T / F6 | 하위 에이전트(일을 나눠 받은 별도 에이전트)와 백그라운드 프로세스를 보는 전체 화면 모니터(7장). Enter 최근 기록, s 방향 지시, x 중지 요청. |
| Ctrl+R / F7 | 상태 막대 위의 작업 현황 칸을 여러 줄 ↔ 한 줄로. 걸어 둔 /goal 과 /queue 에 줄 선 메시지도 여기 보입니다. |
| Ctrl+D (자세히) | 글이 있으면 커서 아래 글자를 지웁니다. 턴 도중에 나가면 게이트웨이가 턴을 끝내고, 그 사이 승인·되묻는 질문이 나오면 제한 시간까지 또는 내가 돌아올 때까지 기다립니다. |
| Ctrl+Z | Hermes 를 잠시 뒤로 보냅니다(Unix 계열만). 셸에서 fg 로 돌아옵니다. |
| Tab (일하는 중) | modern 화면에서, 쓴 글을 다음 턴으로 줄 세웁니다. |
- macOS 의 F6·F7 은 맨 윗줄의 미디어 키가 아니라 실제 기능 키입니다. Fn 을 누른 채 누르거나 System Settings → Keyboard → Keyboard Shortcuts → Function Keys 에서 표준 기능 키로 쓰도록 켭니다. 확실한 대안은 Ctrl+T·Ctrl+R.
- 셸 모드는 터미널 백엔드를
ssh·docker로 바꿨어도 Hermes 가 도는 컴퓨터에서 실행됩니다(4장). 실패하면! exited <code>가 찍힙니다. CLI 전용이라 메신저·예약 작업에서는 무시됩니다.
여러 줄로 입력하기
Enter 는 곧바로 보내기이므로, 여러 줄짜리 부탁을 쓰려면 줄바꿈 방법을 알아야 합니다. 방법은 두 가지입니다.
| 방법 | 어떻게 |
|---|---|
| 줄바꿈 키 | Alt+Enter, Ctrl+J, 또는 Shift+Enter 를 누르면 새 줄이 들어갑니다. |
| 역슬래시로 잇기 | 줄 끝에 \ 를 붙이고 Enter 를 누르면 보내지 않고 다음 줄로 이어집니다. |
| 그냥 붙여넣기 | 여러 줄 글을 통째로 붙여 넣어도 됩니다. 화면에는 [pasted: 47 lines, 1,842 chars — press Enter to send] 같은 한 줄 미리 보기만 나오지만 보내지는 것은 전체 내용입니다. |
❯ Write a function that:\ 1. Takes a list of numbers\ 2. Returns the sum
뜻: “다음과 같은 함수를 써 줘: 1. 숫자 목록을 받아서 2. 합을 돌려준다”
터미널별 Shift+Enter 지원과 관련 설정
| 터미널 | Shift+Enter |
|---|---|
| Kitty, foot, WezTerm, Ghostty | 기본으로 구분됨 |
| iTerm2(최근 버전), Alacritty, VS Code 터미널, Warp, Windows Terminal Preview 1.25+ | 설정에서 Kitty 키보드 규격을 켜면 지원 |
| macOS Terminal.app, Windows Terminal(안정판) | 지원 안 됨 |
- Windows Terminal 은 Alt+Enter 를 가로채므로(전체 화면 전환) Ctrl+Enter 나 Ctrl+J 를 씁니다.
- Ctrl+J 와 역슬래시 잇기는 기본으로 켜져 있습니다. 예전처럼 Ctrl+J 를 보내기로 써야 하면
display:→cli_multiline_shortcuts: false. - Kitty 규격 터미널에서는 숫자 키패드의 Alt+Enter 도 줄바꿈입니다.
일하는 도중에 방향 바꾸기 · 멈추기
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초 안에 두 번 | 강제 종료. |
바쁠 때 입력 방식의 설정·예외, 대기 줄, 잠시 뒤로 보내기(Ctrl+Z)
- 설정 —
config.yaml의display:→busy_input_mode: "steer"(또는"queue"·"interrupt"). 모르는 값은interrupt로 처리합니다.steer는 에이전트가 아직 시작 전이거나 그림이 붙어 있으면queue처럼 동작합니다. - 대기 줄 — 게이트웨이에 있어 재시작해도 남고, 넣은 순서대로 한 번씩 실행됩니다. 함께 쓰는 줄이라
/queue list·rm N·edit N …·clear는 다른 창이나 자동화가 넣은 것까지 다룹니다. 게이트웨이가 쥔 메시지는/queue move A B로 옮길 수 없습니다. - 첫 안내 다시 보기 —
onboarding.seen.busy_input_prompt키를 지웁니다. - Ctrl+Z — Unix 계열에서 Hermes 를 통째로 뒤로 보냅니다.
Hermes Agent has been suspended. Run `fg` to bring Hermes Agent back.이 찍히고,fg로 그 자리에 돌아옵니다. Windows 는 지원하지 않습니다.
세션이란 — 자동으로 저장되는 대화 한 묶음
세션은 대화 한 묶음입니다. 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 를 이어 주는, 계속 켜 두는 프로그램)를 다시 시작하는 것은 끊는 것이 아닙니다 — 같은 세션이 이어집니다.
세션 출처(source) 표와, 첨부 파일이 컨텍스트에 들어가는 방식
| 출처 값 | 뜻 |
|---|---|
cli | 대화형 CLI |
oneshot | 한 번 묻고 끝나는 실행(hermes chat --oneshot -q, -Q, hermes -z 등). TUI·데스크톱·대시보드의 세션 고르기 화면에는 숨겨지지만 hermes -c 가 이어 가고 hermes sessions list 에 나옵니다. --source <tag> 를 주면 그 값이 우선합니다. |
telegram discord slack whatsapp signal matrix mattermost dingtalk feishu wecom weixin bluebubbles qqbot | 메신저(bluebubbles = Apple iMessage, wecom = WeChat Work, weixin = 개인 WeChat) |
email sms homeassistant webhook api-server acp | 이메일 · SMS(Twilio) · Home Assistant 이벤트 · 들어오는 웹훅 · API 서버 요청 · ACP 편집기 연동 |
cron batch | 예약 작업 · 일괄 처리 |
kanban tool | 칸반 작업자 · 외부 연동. 세션 고르기 화면에서 숨겨집니다. |
압축으로 이어진 세션은 같은 출처를 물려받습니다. 첨부 파일은 그 턴에만 쓰입니다 — 그림은 다음 모델 호출에 붙이거나(모델이 그림을 못 보면 글 설명으로), 음성은 글로 옮기고, 문서는 뽑아낸 글이나 저장 경로로 나타냅니다. 경로와 뽑아낸 글은 기록에 남을 수 있지만 원본 파일이 이후 턴마다 다시 실리지는 않습니다.
메신저에서는 세션이 어떻게 나뉘나 — 플랫폼별 세션 추적
| 대화 종류 | 기본 키 형식 | 동작 |
|---|---|---|
| Telegram · Discord DM | agent:main:telegram:dm:<chat_id> | DM 대화방마다 세션 하나 |
| WhatsApp DM | agent:main:whatsapp:dm:<canonical_identifier> | DM 사용자마다 하나 |
| 그룹 · 채널 | agent:main:<platform>:group:<chat_id>:<user_id>(채널은 group 자리에 channel) | 사용자 ID 를 알 수 있으면 사람마다 따로. 알 수 없으면 방 하나가 함께 씀 |
| 그룹의 스레드·토픽 | agent:main:<platform>:group:<chat_id>:<thread_id> | 참가자 모두가 함께 씀(기본). thread_sessions_per_user: true 면 따로 |
- 그룹: 따로 vs 함께 — 기본
group_sessions_per_user: true는 같은 채널의 두 사람이 기록을 나눠 쓰지 않게 합니다.false면 방마다 세션 하나를 함께 써서 맥락을 공유하지만 토큰 비용·중단 상태·컨텍스트 증가도 함께 나눕니다. /stop— “이 대화방에서 도는 것을 멈춰라”. 부른 사람의 세션 → 그 방에서 도는 턴 순으로 찾으므로 남이 시작한 턴도 멈출 수 있지만, 다른 방·프로필에는 닿지 않습니다. 스레드 안에서는 그 스레드까지만.- 끊기지 않음 — 게이트웨이 대화는 오래 쉬거나 날이 바뀌어도 초기화되지 않습니다. 예전
session_reset설정은 무시되며(남아 있으면hermes doctor가 경고), 시간 기준 초기화가 필요하면hermes plugins install hermes-session-reset-policy. /new는 실행한 화면만 옮깁니다 — 한 세션이 여러 화면에 열려 있어도 나머지는 원래 세션에 남고, 돌던 턴도 계속됩니다.- 충돌·재시작 뒤 — 각 대화방은 가장 최근에 실제로 쓰던 세션으로 다시 이어지고, 마지막 일이
/new였다면 새로 시작합니다.
여러 화면·계정이 같은 세션에 붙을 때 (게이트웨이 접근과 기록 — 관리자용)
실행의 주인은 화면이 아니라 게이트웨이입니다. 같은 게이트웨이 프로필의 확인된 운영자는 다른 인증 방법으로 만든 로컬 CLI·TUI·데스크톱 세션에도 붙을 수 있습니다(제한된 작업자·메신저·서비스 자격에는 해당 없음). 누가 만들고 누가 입력했는지는 계정별로 그대로 기록되며, 주인 정보가 불완전한 예전 원격 세션은 처음 요청한 계정에 자동으로 넘어가지 않습니다. 게이트웨이 충돌은 화면 끊김과 달라서, 중단된 일은 다시 실행되지 않고 “알 수 없음”으로 남아 정리가 필요할 수 있습니다.
이어 하기 — 하던 대화로 돌아가기
나갔다가 돌아오는 흐름은 세 걸음입니다. 아래에서 한 단계씩 넘겨 보세요.
① 나갈 때 — 다시 들어오는 명령이 찍힙니다
CLI 세션에서 나가면 Hermes 가 다시 들어오는 명령을 찍어 줍니다. 이 줄을 그대로 복사해 두면 됩니다.
Resume this session with: hermes --resume 20260225_143052_a1b2c3 Session: 20260225_143052_a1b2c3 Duration: 12m 34s Messages: 28 (5 user, 18 tool calls)
② 다시 열기 — 넷 중 편한 방법으로
| 무엇으로 찾나 | 명령 | 설명 |
|---|---|---|
| 가장 최근 대화 | hermes --continue줄여서 hermes -c | 가장 쉬운 방법. 터미널 창이 여럿이면 그 창에서 하던 세션을 이어 줍니다. |
| 이름(제목) | hermes -c "my project"hermes --resume "refactoring auth" | 세션에 이름을 붙여 두었을 때. |
| 세션 ID | hermes --resume 20260225_143052_a1b2c3줄여서 hermes -r … | 나갈 때 찍힌 ID, 또는 hermes sessions list 에서 본 ID. |
| 대화 화면 안에서 | /sessions · /resume <이름> | 목록에서 고르거나 이름으로 엽니다. |
③ 요약 패널을 확인하고 이어서 입력합니다
이어 하면 저장된 대화 기록 전체가 되살아납니다. Hermes 는 이전 메시지, 도구 호출, 답을 모두 본 상태가 되어 자리를 뜬 적이 없는 것처럼 이어 갑니다. 입력 칸 위에는 지난 대화를 간추린 “Previous Conversation” 패널이 먼저 나옵니다.
Previous Conversation
... 4 earlier messages ...
● Help me refactor the auth module please
◆ [3 tool calls: terminal, web_search]
◆ (Hermes 의 답 앞부분 …)
❯ ▍원문의 패널 그림은 글로 옮겨지지 않아, 원문이 적은 규칙으로 흉내 냈습니다 — 내 메시지는 금색 ●, Hermes 의 답은 초록 ◆, 도구 호출은 개수와 이름으로 접히고, 최근 10번의 주고받기까지만 보입니다.
이어 할 때 Hermes 는 그 세션이 쓰던 작업 폴더로도 되돌아갑니다(↪ restored workspace dir: … 줄로 알려 줌). 터미널에서 하던 대화를 메신저로 넘겨 계속할 수도 있습니다(/handoff telegram) — 아래 접힌 상자를 보세요.
이어 하기의 모든 옵션과 규칙
| 명령·항목 | 설명 |
|---|---|
hermes chat -c · hermes chat --resume <id> | chat 하위 명령으로도 같습니다. |
hermes -c "my project" --create-if-missing | 그 제목의 세션이 없으면 만들고, 있으면 이어 합니다. |
hermes --resume latest | 이름 없는 -c 와 같습니다. latest 는 예약어라, 제목이 정말 “latest” 인 세션은 ID 나 -c latest 로 엽니다. |
hermes --resume latest --in ./my-project | 그 폴더로 옮겨 가 그 폴더에 속한 가장 최근 세션을 엽니다(--tui 도 됨). 세션이 그 폴더에 고정됩니다. |
--no-restore-cwd | 작업 폴더로 되돌아가지 않고 지금 폴더에 머뭅니다. |
| 세션 ID 형식 | YYYYMMDD_HHMMSS_<hex> — CLI/TUI 는 끝이 6자, 게이트웨이는 8자. 겹치지 않는 앞부분만 써도 됩니다. |
| 터미널별 이어 하기 | ~/.hermes/terminal-sessions/ 에 어느 터미널에서 돌았는지 표식을 남깁니다. 표식이 없거나 30일이 넘었으면 전체에서 가장 최근 세션으로. 끄기: session.terminal_continue: false. |
| 요약 패널 | 내 메시지 300자, 답 200자·3줄에서 자르고 시스템 메시지·도구 결과·내부 생각은 숨깁니다. 한 줄만 보려면 display: → resume_display: minimal. |
| 설정 | 쉬던 세션을 이어 하면 프로필의 지금 설정(툴셋, MCP 서버(외부 도구를 내주는 프로그램), 터미널 설정, max_turns, 체크포인트, 기본 생각 깊이)을 따르고, 세션은 자기 모델·시작 옵션·도중에 바꾼 /reasoning 을 지킵니다. 달라진 것이 있으면 이어 한 뒤 첫 턴 비용이 더 듭니다. |
메신저로 넘기기 — /handoff <platform>
CLI 세션에서 /handoff telegram 을 넣으면 지금 대화가 같은 세션 ID·같은 기록 그대로 그 메신저의 홈 채널(8장)로 옮겨 갑니다.
| 순서 · 상황 | 일어나는 일 |
|---|---|
| ① 확인 | 플랫폼이 켜져 있고 홈 채널이 있는지 봅니다. 없으면 받을 대화방에서 /sethome 을 한 번 실행합니다. 에이전트가 턴 도중이면 거절합니다. |
| ② 새 스레드 | Telegram 은 새 토픽, Discord 는 1440분 뒤 자동 보관되는 스레드, Slack·Matrix 는 첫 메시지를 스레드 시작점으로. WhatsApp·Signal·SMS 는 홈 채널에 바로. |
| ③ 이어받기 | 에이전트가 새 스레드에 확인과 요약을 올리고, CLI 는 ↻ Handoff complete. The session is now active on telegram. 을 찍고 끝납니다. |
| ④ 돌아오기 | /resume <제목> 또는 hermes -r "<제목>". |
| 게이트웨이가 꺼져 있음 | 60초 뒤 시간 초과. CLI 세션은 그대로입니다. |
| 오래 걸림 | 긴 세션은 몇 분 걸립니다. “Still transferring...” 을 보이며 15분까지 기다립니다. |
| 스레드 생성·전송 실패 | 스레드를 못 만들면 홈 채널에 바로 넘깁니다. 전송이 실패하면 이유와 함께 실패로 표시되고 다시 시도할 수 있습니다. |
한계: 스레드가 없는 플랫폼에서 여럿이 쓰는 그룹을 홈 채널로 두면 1:1 대화처럼 묶여 잘 맞지 않습니다.
Claude Code · Codex CLI 에서 하던 대화 가져오기
Hermes 는 Claude Code 의 기록(~/.claude/projects/)과 Codex CLI 의 기록(~/.codex/sessions/)을 읽기만 해서 새 세션으로 가져옵니다. hermes sessions import 는 최신순 목록에서 고르게 하고(--from claude·--from codex [파일]), hermes --resume @claude·@codex 는 고르자마자 그 대화로 들어갑니다. 제목은 Imported from Claude Code: <첫 메시지> 가 됩니다. 넘어오는 것은 내 말과 답이고 도구 사용은 [ran tool: …] 메모로 줄어듭니다. 시스템 프롬프트·생각 기록·도구 원본 출력은 넘어오지 않습니다. 데스크톱 앱의 명령 팔레트(Import session)에도 같은 기능이 있습니다.
세션에 이름 붙이기
세션 ID 는 20260225_143052_a1b2c3 처럼 외우기 어렵습니다. 그래서 Hermes 는 첫 주고받기가 끝나면 3–7 단어짜리 짧은 제목을 자동으로 붙입니다. 빠른 보조 모델이 뒤에서 만들기 때문에 대화가 느려지지 않습니다. 자동 제목은 세션마다 한 번만 만들고, 내가 먼저 제목을 붙였다면 건너뜁니다.
직접 붙이려면 대화 안에서 /title 을, 밖에서는 hermes sessions rename 을 씁니다.
/title my research project
hermes sessions rename 20250305_091523_a1b2c3d4 "refactoring auth module"
뜻: 지금 세션의 제목을 “my research project” 로 / 그 ID 의 세션 제목을 “refactoring auth module” 로 바꿈
| 제목 규칙 | 내용 |
|---|---|
| 겹치지 않음 | 두 세션이 같은 제목을 가질 수 없습니다. 이미 쓰는 제목이면 오류가 납니다. |
| 최대 100자 | 목록이 깔끔하게 보이도록. |
| 자동 정리 | 제어 문자·폭 없는 문자 같은 것은 자동으로 걸러 냅니다. |
| 한글·이모지 가능 | 일반 유니코드 문자(이모지, 한중일 문자, 악센트 문자)는 모두 됩니다. |
대화가 길어져 압축되면(직접 /compress 하든 자동이든) Hermes 는 이어지는 새 세션을 만듭니다. 원래 세션에 제목이 있었다면 새 세션에는 번호가 붙은 제목이 자동으로 달립니다. 이름으로 이어 하면 그 줄기에서 가장 최근 것을 골라 줍니다.
제목의 세부 규칙
- 첫 메시지 전에
/title을 쓰면 기다렸다가 세션이 시작될 때 적용됩니다. hermes sessions rename은 여러 단어 제목에 따옴표가 없어도 됩니다./title은 메신저(Telegram·Discord·Slack·WhatsApp)에서도 됩니다./title만 넣으면 지금 제목을 보여 줍니다.
지난 세션 찾기 — 목록과 검색
지난 대화를 찾는 길은 둘입니다. 내가 목록에서 찾는 것과, Hermes 가 지난 대화를 검색해 떠올리는 것입니다.
① 내가 찾기. 터미널에서 hermes sessions list 를 입력하면 최근 세션 20개가 제목·첫 마디·마지막 사용 시각·ID 와 함께 나옵니다. 대화 화면 안에서는 /sessions 로 고르기 화면을 엽니다.
Title Preview Last Active ID ───────────────────────────────────────────────────────────────────────────────── refactoring auth Help me refactor the auth module please 2h ago 20250305_091523_a my project #3 Can you check the test failures? yesterday 20250304_143022_e — What's the weather in Las Vegas? 3d ago 20250303_101500_f
| 명령 | 뜻 |
|---|---|
hermes sessions list --limit 50 | 더 많이 봅니다. 더 있는데 잘렸으면 끝에 … more not shown (use --limit N to see more) 가 붙습니다. |
hermes sessions list --source telegram | 한 출처(플랫폼)의 세션만. |
hermes sessions list --workspace my-project | 어느 폴더(작업 공간)에서 한 세션만. 경로 일부나 폴더 이름으로 맞춥니다. |
② Hermes 가 찾기. Hermes 에게는 session_search 라는 도구가 들어 있어, 지난 모든 대화를 글자로 검색할 수 있습니다. 내가 “지난번에 하던 거”, “전에 말했듯이”, “기억나?” 처럼 지난 대화를 가리키면 Hermes 는 다시 설명해 달라고 하기 전에 먼저 이 도구로 찾아보도록 되어 있습니다. 이 검색은 모델을 부르지 않고, 요약을 지어내는 대신 저장된 실제 메시지를 돌려줍니다. 기억과의 관계는 5장에서 다룹니다.
session_search 도구의 네 가지 호출 모양과 검색 문법
SQLite 의 FTS5 전문 검색을 씁니다. 모드 값은 없고, 어떤 인자를 주느냐로 동작이 정해집니다.
| 모양 | 예 | 돌려주는 것 |
|---|---|---|
| 찾기 | session_search(query="auth refactor", limit=3) | 상위 N개 세션. 1위는 맞은 곳 앞뒤 ±5 메시지와 세션의 처음·끝 3개씩, 나머지는 간략히(detail="full" 이면 모두). |
| 넘겨 보기 | session_search(session_id="…", around_message_id=590803, window=10) | 그 메시지를 가운데 둔 ±window 조각. |
| 읽기 | session_search(session_id="…") | 세션 전체(크면 앞·뒤 일부). |
| 둘러보기 | session_search() | 최근 세션을 시간순으로. |
검색 문법: 낱말 docker deployment(둘 다 포함) · 구절 "exact phrase" · docker OR kubernetes, python NOT java · 앞부분 일치 deploy*. 선택 인자: sort(newest·oldest, 생략하면 관련도순), role_filter(기본 user,assistant, 도구 출력까지 보려면 tool 추가).
백그라운드 세션 — /bg 로 따로 시키기
오래 걸리는 조사를 시켜 놓고 그동안 다른 이야기를 하고 싶을 때는 /bg 뒤에 시킬 일을 적습니다. Hermes 는 그 일을 따로 떨어진 세션에서 돌리고, 입력 칸은 곧바로 돌려줍니다. 끝나면 결과가 내 터미널에 상자로 나타납니다.
❯ /bg Analyze the logs in /var/log and summarize any errors from today 🔄 Background task #1 started: "Analyze the logs in /var/log and summarize..." Task ID: bg_143022_a1b2c3 ╭─ ☤ Hermes (background #1) ─────────────────────────────╮ │ Found 3 errors in syslog from today: │ │ 1. OOM killer invoked at 03:22 — killed process nginx │ │ 2. Disk I/O error on /dev/sda1 at 07:15 │ ╰─────────────────────────────────────────────────────────╯
뜻: “/var/log 의 로그를 분석해서 오늘 난 오류를 요약해 줘” → “백그라운드 작업 #1 시작” → (나중에) 결과 상자
/bg 뒤의 지시문에 필요한 것을 모두 적어야 합니다.대화가 분리됩니다
백그라운드 에이전트는 지금 세션의 대화 기록을 모릅니다. 내가 준 지시문만 받습니다.
설정은 같습니다
지금 세션의 모델, 제공자, 툴셋, 생각 깊이 설정, 예비 모델을 물려받습니다.
기다리지 않습니다
앞의 대화는 그대로 쓸 수 있습니다. 대화하고, 명령을 실행하고, 백그라운드 작업을 더 띄워도 됩니다.
여러 개를 동시에
작업마다 번호가 붙습니다. 서로 다른 방향을 한꺼번에 조사시킬 수 있습니다.
원문이 드는 쓰임새는 오래 걸리는 조사, 파일 묶음 분석(“이 저장소의 Python 파일을 모두 살펴 보안 문제를 찾아 줘”), 여러 갈래 동시 조사입니다. 작업이 실패하면 결과 대신 오류 알림이 나옵니다.
bg_143022_a1b2c3)를 가진 별개의 세션입니다. 아직 도는 작업 수는 상태 막대의 ▶ N 으로 보이고, 설정 display.bell_on_complete 를 켜 두면 끝날 때 터미널 벨이 울립니다. Ctrl+Z 로 Hermes 를 통째로 잠시 뒤로 보내는 것(앞 소절의 접힌 상자)과는 다른 기능입니다.
저장 위치와 세션 정리
세션은 모두 내 컴퓨터의 ~/.hermes/state.db 한 파일에 들어 있습니다. SQLite(파일 하나로 된 작은 데이터베이스) 형식이며, 세션 정보·메시지 전체·검색용 색인이 함께 있습니다. CLI·TUI·게이트웨이의 세션이 모두 여기 있고, hermes sessions list·/sessions·대시보드가 모두 이 파일을 읽습니다.
| 무엇 | 위치 | 설명 |
|---|---|---|
| 세션 저장소 | ~/.hermes/state.db | 모든 세션의 정보와 메시지. 메신저(게이트웨이) 메시지의 원본도 여기입니다. |
| 게이트웨이 길 찾기 표 | state.db 안의 gateway_routing 표 | 메신저 대화방(세션 키)이 지금 어느 세션 ID 와 이어져 있는지. |
| 예전 방식의 사본 | ~/.hermes/sessions/sessions.json | 위 길 찾기 표를 옛 프로그램과 맞추려고 베껴 두는 파일(gateway.write_sessions_json: true 가 기본). |
sessions.json 은 세션 목록이 아닙니다
이 파일에는 메신저 쪽 항목만 들어 있습니다. 거기에 CLI 세션이 안 보인다고 세션이 사라진 것이 아닙니다 — 원문은 이것이 정상이라고 적습니다. 세션이 있는지는 hermes sessions list 로 확인하세요. 정말로 목록에 CLI 세션이 없다면 hermes sessions repair 를 실행하고, CLI 를 시작할 때 ⚠ Session store unavailable 경고가 나오는지 봅니다.
세션을 관리하는 명령은 터미널에서 hermes sessions … 로 씁니다.
| 명령 | 하는 일 |
|---|---|
hermes sessions list | 최근 세션 목록(기본 20개). |
hermes sessions rename <id> <제목> | 제목을 붙이거나 바꿉니다. |
hermes sessions export backup.jsonl | 세션을 파일로 내보냅니다(백업·공유용). |
hermes sessions pin <id> · unpin · pinned | 고정 — 자동 보관에서 빼고 목록에 항상 나오게 합니다 / 풉니다 / 고정된 것을 봅니다. |
hermes sessions archive --title "dry run" | 보관 — 지우지 않고 목록과 /resume 에서만 숨깁니다. 조건을 하나 이상 줘야 합니다. |
hermes sessions delete <id> | 세션 하나를 지웁니다(확인을 묻습니다). |
hermes sessions prune | 정리 — 끝난 세션 가운데 90일 동안 쓰지 않은 것을 지웁니다. 쓰고 있는 세션은 지우지 않고, 보관된 세션은 건너뜁니다. |
hermes sessions stats | 세션·메시지 수, 출처별 수, 저장소 크기. |
hermes sessions optimize | 세션은 건드리지 않고 저장소 파일만 정돈해 크기를 줄입니다. |
prune 과 delete 는 기록을 지웁니다. 원문은 정리하기 전에 hermes sessions export backup.jsonl 로 백업해 두는 순서를 보여 줍니다. --dry-run 을 붙이면 무엇이 지워질지 미리 보기만 합니다. 저장소 파일이 그저 커진 것뿐이라면 아무것도 지우지 않는 hermes sessions optimize 부터 써 보세요.
자동 정리는 기본으로 꺼져 있습니다. 정리를 전혀 하지 않으면 state.db 는 끝없이 커집니다. 그래서 저장소가 있는 디스크가 부족해지면 Hermes 가 한 번 묻습니다. /autoprune on(켜기), /autoprune off(모두 남겨 둠, 다시 묻지 않음), /autoprune later(일주일 뒤 다시 알림) 가운데 답하면 됩니다. 지난 기록은 session_search 가 떠올리는 재료이기도 하므로, 켤지 말지는 내가 정합니다.
내보내기(export)의 형식과 조건
--format | 나오는 것 · 쓰임 |
|---|---|
jsonl (기본) | 세션마다 JSON 한 줄. 백업용 — 압축으로 치워진 턴, 되감기로 뺀 메시지까지 저장된 모든 줄이 들어 있습니다. |
md / qmd | 세션마다 파일 하나 + manifest.jsonl(기본 위치 ~/.hermes/session-exports). 읽기 좋은 보관용. 묶음 내보내기는 조건이 하나 이상 필요합니다. |
html | 혼자 열리는 HTML 한 파일. 공유·둘러보기용. |
trace | Claude Code JSONL — Hugging Face 의 Agent Trace Viewer 용. --upload 로 내 비공개 데이터셋에 올립니다(HF_TOKEN). 기본으로 비밀 값을 가립니다. |
- 고르기 —
--session-id(하나), 또는 정리와 같은 조건(--older-than,--source,--title,--model등). 조건으로 고르면 끝난 세션만, 조건 없이 내보내면 쓰고 있는 것까지 전부.--dry-run은 미리 보기. --redact— API 키·토큰 같은 비밀 값을 가립니다. 남에게 줄 때는 화면에 보이는 기록만 담는md·html에--redact를 쓰라고 원문이 권합니다.--only user-prompts— 내가 쓴 질문만(jsonl·md).--delete-after-verified— 내보낸 것을 확인한 뒤 지웁니다.--session-id와--yes가 필요하고, 그 사이 기록이 바뀌면 지우지 않습니다.- 대화 안의
/save json|md|html도 같은 규칙을 따릅니다.
정리(prune)·보관(archive)·삭제(delete)의 조건과 규칙
| 명령 예 | 뜻 |
|---|---|
hermes sessions prune --older-than 30 | 숫자만 쓰면 일. 12h·2d·1w 같은 기간이나 날짜도 됩니다. |
hermes sessions prune --newer-than 5h | 최근 5시간 안의 것만(방금 만든 시험용 세션 등). |
hermes sessions prune --source telegram | 그 출처의 모든 기간. 조건을 하나라도 쓰면 90일 기준이 꺼지므로 시간 조건을 함께 줍니다. |
… --dry-run · … --yes | 미리 보기만 · 확인 없이 실행. |
hermes sessions archive --newer-than 5h | 같은 조건으로 숨기기. 데스크톱 등 “끝나지” 않는 로컬 세션은 --include-open 을 붙여야 포함됩니다. |
--older-than/--newer-than은 마지막 활동,--before/--after는 세션 시작 시각 기준입니다. 조건은 모두 AND 로 묶입니다.- 그 밖의 조건:
--title·--model·--branch(일부 일치),--provider·--end-reason·--user·--chat-id·--chat-type,--cwd,--min/--max-messages·-tokens·-cost·-tool-calls. - 보관된 세션까지 지우려면
--include-archived. 압축으로 여러 세션이 된 대화는 한 덩어리로 다룹니다. - 자동 보관(
sessions.auto_archive)으로 숨겨진 대화는 다시 쓰면 저절로 돌아오고, 내가 보관한 것은 데스크톱·대시보드에서 되돌릴 때까지 숨겨져 있습니다. - 열려 있는 대화의 세션을 지우면 다음 저장 때 같은 ID 로 다시 생깁니다 — 대화를 먼저 닫으세요. 턴이 돌거나 압축 중이면 삭제가 거절됩니다.
optimize와 게이트웨이 없는prune은 다른 Hermes 프로세스가state.db를 쥐고 있으면 거절합니다.
자동 정리 설정, 저절로 끝나는 세션, 너무 큰 기록 막기
sessions: 아래 키 (기본값) | 하는 일 |
|---|---|
auto_prune (false) | true 면 시작할 때, 끝난 세션 가운데 retention_days 동안 쓰지 않은 것을 지웁니다. 쓰고 있는 세션은 지우지 않습니다. |
retention_days (90) | 0 이상의 정수. 음수면 경고만 남기고 건너뜁니다. |
min_interval_hours (24) | 자동 정리를 이보다 자주 돌리지 않습니다. |
vacuum_after_prune (true) · min_vacuum_interval_days (30) | 지운 뒤 파일을 줄이는 작업은 마지막 뒤 30일이 지났고 되찾을 부분이 25% 를 넘을 때만 돕니다. 바로 돌려받으려면 hermes sessions optimize. |
orphan_end_grace_s (300) | 마지막 화면이 닫지 않고 사라진 CLI·TUI·데스크톱 세션을 이 시간(초) 뒤 끝냅니다(0 은 끝내지 않음). 끝난 뒤에도 다음 메시지가 같은 ID 로 다시 엽니다. |
max_resume_messages · max_export_messages (20000) | 너무 큰 기록을 한꺼번에 읽지 않게 막습니다(0 은 끔). 넘으면 이어 하기는 오류 4130, TUI·데스크톱의 /save 는 4131. |
- 디스크 부족 질문은
auto_prune키가 없을 때만, 남은 공간이 2 GB 미만이거나 10% 미만(남은 공간 20 GB 미만일 때)이면 나옵니다. 기본 CLI 는 시작할 때, TUI·데스크톱은 알림으로, 게이트웨이는 홈 채널에 묻습니다. - 끝내지 못하고 죽은 자동화 세션(예약 작업·칸반·하위 에이전트·한 번 묻기)은 자동 정리 때 닫습니다. 닫기는 지우기가 아니어서 이어 할 수 있습니다. 메신저·TUI·데스크톱 세션과 고정된 세션은 닫지 않습니다.
- 원문의 실제 사례: 세션 약 1000개에 384 MB 가 되자 검색 색인 쓰기와
/resume목록이 느려졌습니다.
문제가 생겼을 때의 복구·수리 명령 (관리자용)
| 명령 | 언제 · 무엇을 |
|---|---|
hermes sessions discard <id> --yes | 게이트웨이가 턴 도중에 멈추면 그 턴은 다시 실행되지 않고 세션을 막습니다. 이 명령(또는 대화 안의 /discard)으로 확인하고 넘깁니다. 일부 동작은 이미 실행됐을 수 있으니 다시 보내기 전에 확인합니다. |
hermes sessions refresh-prompts | 이어지는 세션은 첫 턴에 만든 시스템 프롬프트를 계속 쓰므로 SOUL.md·스킬·맥락 파일을 고쳐도 닿지 않습니다. 이 명령을 실행하면 각 세션이 다음 턴에 새로 만듭니다(--session ID 로 하나만). 대화 기록은 그대로입니다. |
hermes sessions repair-routing | 재시작 뒤 메신저 대화가 며칠 전으로 되돌아간 것처럼 보일 때. 증거가 분명할 때만 원래 대화에 다시 붙입니다. --apply 전에 게이트웨이를 멈추고 state.db 를 백업합니다. |
hermes sessions repair-prompts | 예전 버전의 문제(#122822)로 줄어든 시스템 프롬프트가 저장된 세션을 찾아 비웁니다. --apply 뒤 hermes gateway restart. |
hermes sessions repair-profiles | 프로필끼리 뒤섞여 저장된 세션을 제자리로 옮깁니다(10장). 게이트웨이를 멈춘 뒤 --apply. |
hermes sessions set-journal-mode delete|wal | state.db 의 기록 방식(WAL ↔ DELETE)을 바꿉니다. 저장소를 쓰는 모든 프로세스를 먼저 멈춥니다. |
원문은 이 밖에 hermes sessions repair·recover·browse, hermes insights(토큰·비용 분석)를 이름만 언급합니다.
저장소 내부 구조와 압축 설정
- 주요 표 —
sessions(세션 정보),messages(메시지 전체),messages_fts(전문 검색용 FTS5 색인). WAL 방식이라 여러 곳에서 동시에 읽고 한 곳에서 씁니다. - 옛 JSONL 기록 —
~/.hermes/sessions/의*.jsonl은 이제 쓰이지 않습니다. 세션이state.db에 있는지 확인한 뒤 지워도 됩니다.sessions/saved/*.json은/save로 만든 사본입니다. - 컨텍스트 압축 — 기본은
compression.enabled: true,threshold: 0.50(한도의 50% 에서 압축). 요약 모델은auxiliary.compression.model(비우면 대화 모델). 가운데 턴들이 요약되고 처음 3턴과 마지막 20턴은 그대로 남습니다(3장).
- 터미널에
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로 세션을 끊어 주세요. 자동 정리는 기본으로 꺼져 있고, 지우는 것은 끝난 세션뿐입니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/cli · hermes-agent.nousresearch.com/docs/user-guide/sessions (수집일 2026-11-09)
설정 — 파일 · 모델 · 한도
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 도구를 써서 내 대신 일을 해 주는 AI 프로그램)의 설정은 모두 ~/.hermes/ 폴더 한곳에 모여 있습니다. 이 장은 설정이 어디에 저장되고, 어떻게 바꾸고, 값이 여러 곳에 있을 때 무엇이 이기는지를 먼저 설명한 뒤, 꼭 알아 둘 한도·압축·보조 모델·화면 표시·터미널 백엔드를 차례로 봅니다. 나머지 설정은 장 끝의 접힌 표에 한 줄씩 정리했습니다.
~/.hermes/폴더 안에 무엇이 있고,config.yaml과.env가 어떻게 다른지hermes config명령으로 설정을 보고, 바꾸고, 되돌리는 방법- 같은 설정이 여러 곳에 있을 때 어떤 값이 쓰이는지(우선순위)
- 파일 읽기·도구 출력·반복 횟수에 걸린 한도와, 대화가 길어질 때 일어나는 압축
- 곁가지 일을 맡는 보조 모델, 화면에 보이는 정보의 양, 명령이 실제로 실행되는 곳(터미널 백엔드)
- 설정이 저장되는 곳 — 폴더 구조와 두 파일(
config.yaml·.env). - 설정 보고 바꾸기 —
hermes config명령 일곱 가지.
나머지 소절은 필요해질 때 찾아 읽어도 됩니다.
설정이 저장되는 곳 — ~/.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 쪽 참고(이 가이드는 다루지 않음).
config.yaml 자동 사본 · HERMES_HOME 이라는 이름
자동 사본. config.yaml 의 시점별 사본은 backups/config/config.yaml.<이유>.<시각> 으로 저장됩니다. 파일을 문제없이 읽을 때마다, 그리고 hermes setup 등이 파일을 고치기 전에 만들어지며, 이유마다 최신 5개만 남깁니다.
HERMES_HOME. 원문은 이 폴더를 HERMES_HOME(또는 $HERMES_HOME)이라고도 부릅니다. 프로필(profile — 설정·기억·세션을 따로 쓰는 별도 Hermes 환경)마다 이 폴더가 따로 있어, 설정·기억·세션·스킬이 프로필별로 나뉩니다. 프로필은 10장에서 다룹니다.
설정 보고 바꾸기 — 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 config set 의 세부 규칙 — 거절되는 이름 · 오타 · 점이 든 이름
| 상황 | 일어나는 일 |
|---|---|
쓰기 금지 목록의 이름 (HERMES_YOLO_MODE, PATH …) | 거절 |
아는 설정을 잘못된 접두어 아래에 씀 (예: gateway.discord.foo) | 아무것도 쓰지 않고 “혹시 이것?” 안내와 함께 거절. 그래도 쓰려면 --force |
아는 묶음 아래의 모르는 이름 (오타 agent.max_turnz 등) | 쓰기는 하되 “혹시 이것?” 알림. 나중에 get 으로 읽으면 “Hermes 가 이 값을 읽지 않을 수 있다”는 알림이 함께 나옴 |
이름 자체에 점이 든 경우 (모델 이름 qwen3.6:27b 등) | 점 앞에 \ 를 붙여 적거나 YAML 을 직접 고침 |
바꾼 값은 언제 적용되나 — 원문이 밝힌 것만
| 설정 | 적용 시점 |
|---|---|
model.context_length, compression.* (켜져 있는 게이트웨이) | 다음 메시지부터 — 다시 켤 필요 없음 |
display.status_bar.fields, skills.auto_load | 다음 세션부터 |
security.website_blocklist | 30초 안에 반영 |
webapp.enabled | 게이트웨이를 다시 켠 뒤 (hermes gateway restart) |
어떤 값이 이기나 — 우선순위
같은 설정이 여러 곳에 적혀 있으면 Hermes 는 정해진 순서로 찾아 먼저 발견한 값을 씁니다. 원문의 순서는 네 단계이고, 위에 있을수록 이깁니다.
| 상황 | 쓰이는 값 |
|---|---|
config.yaml 에 모델이 정해져 있는데, 실행할 때 --model 로 다른 모델을 붙임 | --model 로 붙인 모델. 단, 그 실행 한 번에만 |
비밀이 아닌 설정이 config.yaml 과 .env 양쪽에 있음 | config.yaml 의 값 |
| API 키·봇 토큰·비밀번호 | .env 에 둡니다 (비밀 값은 .env 가 필수) |
그래서 평소에는 config.yaml 만 고치면 되고, “이번 한 번만 다르게” 하고 싶을 때 명령에 옵션을 붙입니다. config.yaml 안에서는 ${이름} 꼴로 환경 변수의 값을 불러 쓸 수도 있습니다. 예를 들어 API 키 자리에 ${GOOGLE_API_KEY} 라고 적으면 그 이름의 값이 들어갑니다.
${이름} 으로 환경 변수 불러 쓰기 — 세부 규칙
- 한 값에 여러 개를 쓸 수 있습니다:
url: "${HOST}:${PORT}". - 그 이름의 환경 변수가 없으면 글자가 그대로 남고 경고가 기록됩니다. 중괄호 없는
$VAR은 바꿔 넣지 않습니다. ${env:VAR_NAME}도 똑같이 처리됩니다.${file:...},${vault:...}같은 다른 출처는 그 자리에서 풀리지 않습니다.- 프로필 여러 개를 한 게이트웨이가 함께 맡으면, 각 프로필의
config.yaml은 그 프로필의.env를 기준으로 풀립니다.
환경 변수가 설정값보다 앞선다고 따로 적힌 곳
일반 규칙은 위 네 단계이지만, 원문의 개별 설정 절은 몇몇 환경 변수가 config.yaml 값을 덮어쓴다고 따로 적습니다.
| 환경 변수 | 덮어쓰는 설정 |
|---|---|
TERMINAL_<대문자 키> | terminal: 아래의 모든 키 (예: TERMINAL_TIMEOUT → terminal.timeout) |
HERMES_TIMEZONE | timezone |
HERMES_LANGUAGE | display.language (세션 단위) |
반대로 providers.<id>.request_timeout_seconds 는 옛 환경 변수 HERMES_API_TIMEOUT 보다 앞섭니다.
꼭 알아 둘 한도
모델이 한 번에 기억하며 볼 수 있는 글의 양을 컨텍스트(context — 문맥 창)라고 합니다. 컨텍스트는 정해져 있고, 읽고 쓰는 글은 곧 비용입니다. 그래서 Hermes 는 큰 파일 하나나 긴 명령 출력 하나가 컨텍스트를 통째로 차지하지 못하게 곳곳에 한도를 둡니다. 기본값 그대로 써도 되고, 한도 때문에 일이 끊길 때만 조정합니다.
| 무엇의 한도 | 설정 이름 · 기본값 | 넘으면 |
|---|---|---|
| 파일 한 번 읽기 | file_read_max_chars · 100000자 (약 25~35K 토큰) | 읽기를 거절하고, 범위를 좁혀 다시 읽으라고 에이전트에게 알립니다 |
| 터미널 명령 출력 | tool_output.max_bytes · 50000자 | 앞 40%·뒤 60%만 남기고 가운데에 [OUTPUT TRUNCATED] |
| 파일을 한 번에 읽는 줄 수 | tool_output.max_lines · 2000줄 | 요청한 줄 수를 이 값으로 낮춥니다 |
| 한 줄의 길이 | tool_output.max_line_length · 2000자 | 뒤를 자르고 ... [truncated] 를 붙입니다 |
| 아주 큰 도구 결과 | 결과 하나에 100,000자 (MCP(외부 서비스의 도구를 에이전트에 연결하는 공통 규격) 도구는 50,000자) | 자르지 않고 전체를 디스크에 저장한 뒤, 대화에는 미리보기와 파일 위치만 남깁니다 |
| 명령 하나의 실행 시간 | terminal.timeout · 180초 | 원문은 “명령별 제한 시간”이라고만 적습니다 |
| 에이전트가 되물은 질문에 답을 기다리는 시간 | agent.clarify_timeout · 90초 | 시간 초과로 처리하고 에이전트가 알아서 계속합니다 (0 이하면 무제한) |
원문은 모델의 크기에 따라 한도를 올리거나(여유가 있을 때) 내리는(컨텍스트가 금방 찰 때) 예를 함께 싣습니다.
file_read_max_chars: 200000
tool_output:
max_bytes: 150000
max_lines: 5000
file_read_max_chars: 30000
tool_output:
max_bytes: 20000
max_lines: 500
글의 양 말고 “끝없이 도는 것”을 막는 한도도 있습니다. 에이전트는 도구를 부르고 결과를 보고 다시 도구를 부르는 일을 되풀이하는데, 이 되풀이가 헛돌지 않게 하는 장치들입니다.
반복 횟수 한도
agent.max_turns — 내 메시지 하나에 에이전트가 되풀이할 수 있는 횟수입니다. 설정 설명에 따르면 기본값은 무제한이고, 숫자를 넣으면 그 횟수로 묶입니다. 한도에 닿으면 “마무리하라”는 메시지와 마지막 한 번의 기회를 줍니다.
같은 실패 되풀이 감지
같은 도구 호출이 계속 실패하면 먼저 도구 결과에 경고를 붙여 모델이 스스로 고치게 합니다. 사람이 없는 게이트웨이·예약 작업에서는 일정 횟수를 넘으면 그 호출을 막습니다. 멈춰도 세션은 끝나지 않으며 “continue”(계속)라고 답하면 이어집니다.
한 번에 너무 많이 부르기
내 메시지 하나를 처리하는 동안 웹 검색은 50번, 하위 에이전트(subagent — 일을 나눠 받은 별도 에이전트) 만들기는 50개까지입니다. 넘으면 그 호출을 막고 멈춥니다.
제공자가 잠깐 죽었을 때
제공자 오류에는 먼저 3번 다시 시도하고, 그래도 안 되면 기다렸다 다시 하기를 5번까지 합니다. 기다리는 동안 Esc 나 /stop 으로 그만둘 수 있습니다.
반복·시간 한도의 세부 키
| 키 | 기본값 | 뜻 |
|---|---|---|
agent.max_turns | none | 양의 정수면 그 횟수로 제한. "none"·"unlimited"·0·-1 등은 무제한. 원문은 같은 절 첫 문단에서 “기본 500”이라고도 적어 두 설명이 엇갈립니다 |
agent.api_max_retries | 3 | 대체 제공자로 넘어가기 전 재시도 횟수. 빨리 넘기고 싶으면 0 |
agent.auto_recovery_cycles | 5 | 재시도와 대체 제공자를 다 쓴 뒤 기다렸다 다시 하는 횟수(대기 15/30/60/60/60초). 인증·요금·정책 오류에는 쓰이지 않음. 0이면 끔 |
tool_loop_guardrails.warn_after | 2 / 3 / 2 | 똑같은 실패 호출 · 같은 도구 실패 · 진전 없는 같은 결과가 이만큼 이어지면 경고 |
tool_loop_guardrails.hard_stop_after | 5 / 8 / 5 | 강제 중단 기준. hard_stop_enabled(기본 false)를 켜면 모든 곳에서, 꺼 두어도 게이트웨이·예약 작업에서는 적용 |
tool_loop_guardrails.loop_caps | 50 / 50 | max_web_searches · max_subagents. 0이면 그 상한을 끔 |
agent.stall_guards | true | 똑같은 호출·결과가 3번 이상 이어지면 “되풀이하지 말라”는 한 줄을 붙이고, 말만 하고 끝낸 턴은 실제로 하도록 다시 시킴 |
큰 결과를 디스크로 넘기기 · 같은 파일 다시 읽기 · 맥락 파일 한도
- 디스크로 넘기기. 전체 출력은
$HERMES_HOME/cache/spillover/에 저장되고 대화에는 미리보기와 파일 경로가 들어갑니다. MCP 도구의 기준은tool_budget.mcp_result_size_chars(기본 50000)로 바꿉니다. - 같은 파일 다시 읽기. 바뀌지 않은 같은 범위를 두 번 읽으면 내용 대신 짧은 표시만 돌려줍니다. 컨텍스트 압축 뒤에는 다시 읽을 수 있습니다.
- 맥락 파일 한도.
SOUL.md·AGENTS.md같은 맥락 파일(context files — 대화마다 자동으로 읽히는 파일)을 얼마까지 읽을지는context_file_max_chars로 정합니다. 기본null은 모델의 컨텍스트 크기에 맞춘 자동(최소 20K자·최대 500K자)입니다. 원문의 맥락 파일 절은 같은 설정의 기본값을 “20,000자”라고도 적어 두 설명이 엇갈립니다. 읽는 데context_file_read_timeout(기본 5.0초)보다 오래 걸리는 파일은 경고와 함께 건너뜁니다.
대화가 길어지면 — 컨텍스트 압축
대화가 길어지면 컨텍스트가 찹니다. 가득 차면 모델은 더 받을 수 없으므로, Hermes 는 그 전에 오래된 대화를 요약으로 바꿔 자리를 만듭니다. 이것이 컨텍스트 압축(context compression)이며, 기본으로 켜져 있어 따로 할 일은 없습니다.
| 기본 동작 | 설정 · 기본값 | 뜻 |
|---|---|---|
| 자동 압축 | compression.enabled · true | 끄면 자동으로 줄이지 않습니다 |
| 언제 시작하나 | compression.threshold · 0.50 | 컨텍스트 한도의 50%에 닿으면 |
| 처음 대화 지키기 | compression.protect_first_n · 3 | 맨 앞 메시지 3개는 압축을 거듭해도 고정 — 처음 목표가 계속 보이게 |
| 최근 대화 지키기 | compression.protect_last_n · 20 | 최근 메시지 최소 20개는 요약하지 않고 그대로 |
| 세션 이어 가기 | compression.in_place · true | 압축해도 같은 세션으로 이어지고, 압축 전 대화는 지워지지 않고 보관되어 세션 검색으로 다시 찾을 수 있습니다 |
압축이 가까워지면 화면에 알림이 뜹니다. 시작선까지 60% 왔을 때는 안내, 85% 왔을 때는 “곧 압축됩니다”라는 경고입니다. CLI(터미널에서 글자로 쓰는 프로그램 화면)에서는 도구 진행 표시 사이에 아래 같은 막대로, 메신저에서는 글 한 줄로 옵니다. 이 알림은 사람에게만 보이며 모델에게 가는 대화에는 아무것도 넣지 않습니다.
◐ context ████████████░░░░░░░░ 62% to compaction 48k threshold (50%) · approaching compaction
뜻: “압축 시작선까지 62% 왔습니다. 시작선은 48k 토큰(한도의 50%)이고, 압축이 다가옵니다.”
- 직접 압축하기. 기다리지 않고 지금 줄이고 싶으면 대화 중
/compress를 씁니다. - 메신저에서는 조용히. 자동 압축은 메신저 대화에서 진행 과정을 알리지 않고 뒤에서 일어납니다(실패 알림은 항상 보임).
- 요약은 누가 쓰나. 요약은 주 대화와 별개의 모델 호출입니다. 기본은 주 모델이 쓰고, 더 싼 모델에 맡길 수도 있습니다 — 다음 소절의 보조 모델
auxiliary.compression입니다.
compression 설정 전체 — 키 · 기본값 · 뜻
모든 압축 설정은 config.yaml 에만 있습니다(환경 변수 없음).
| 키 | 기본값 | 뜻 |
|---|---|---|
threshold_tokens | null | 토큰 수로 정하는 시작선. 정하면 비율 기준과 이 값 중 낮은 쪽에서 시작 |
target_ratio · tail_mode | 0.20 · lean | 최근 대화를 남기는 양과 방식. lean 은 한도의 2.5%(10K~25K 토큰)만 남기고 요약에 자세한 세션 기록을 넣음. legacy 는 0.20×threshold 를 그대로 남김 |
protect_first_n · in_place | 3 · true | 0 이면 처음 메시지를 고정하지 않음 / false 면 압축할 때마다 새 세션 id 로 넘어가는 옛 방식 |
progress_notices | false | 메신저에 압축 진행 알림을 보냄 |
idle_compact_after_seconds | 0 | 이 시간(초) 넘게 쉬었다 돌아온 세션은 첫 답 전에 미리 압축. 예: 1800 = 30분 |
prepare_ahead | false | 시작선이 가까워지면 다음 요약을 미리 써 둠 |
proactive_prune_tokens | 0 | 모델 호출 없이 오래된 큰 도구 결과만 줄이는 기능의 시작 토큰 수(원문 예 48000) |
context_timeout_seconds · context_total_ceiling_seconds | 120 · 600 | 대화 중 압축에서 요약 모델이 아무 출력 없이 버틸 수 있는 시간 / 출력이 나오고 있어도 넘지 못하는 총 대기 상한 |
hygiene_hard_message_limit | 5000 | 게이트웨이 전용 안전판 — 메시지 개수가 이 값을 넘으면 강제 압축 |
hygiene_timeout_seconds · hygiene_total_ceiling_seconds | 30 · 600 | 게이트웨이의 사전 압축에 적용되는 같은 두 가지 시간 |
hygiene_max_turn_hold_seconds | 10 | 들어온 메시지가 압축을 기다려 주는 최대 시간. 넘으면 압축 없이 먼저 답하고 요약은 나중에 반영 |
hygiene_failure_cooldown_seconds | 300 | 압축 실패 뒤 다시 시도하기까지 쉬는 시간의 첫 단계(1배 → 3배 → 9배, 최대 1시간) |
요약 모델의 두 가지 제한 시간. auxiliary.compression.timeout(기본 120초)은 요청 전체의 시간, auxiliary.compression.no_progress_timeout(기본 60초)은 요약이 흘러나오다 멈춘 채 버틸 수 있는 시간입니다. 둘은 따로 움직여서 timeout 만 600으로 늘려도 60초 동안 출력이 없으면 중단됩니다.
보조 모델 — 곁가지 일을 맡는 모델
Hermes 는 내가 대화하는 주 모델 말고도, 곁가지 일에 모델을 한 번씩 더 부릅니다. 이미지 분석, 브라우저 화면 분석, 세션 제목 짓기, 컨텍스트 압축 요약 같은 일입니다. 이런 일을 맡는 자리를 보조 모델(auxiliary model)이라고 합니다.
처음에는 아무것도 하지 않아도 됩니다. 기본값 auto 는 곁가지 일을 모두 hermes model 로 고른 주 모델에 보냅니다. 다만 원문은 주 모델이 비싼 추론 모델이면 곁가지 일의 비용도 눈에 띄게 붙는다고 알려 줍니다. 그럴 때 곁가지 일만 싸고 빠른 모델로 돌립니다.
가장 쉬운 방법은 hermes model 을 실행해 메뉴에서 “Configure auxiliary models”를 고르는 것입니다. 작업별 목록이 나옵니다.
[ ] vision currently: auto / main model
[ ] title_generation currently: openrouter / google/gemini-3-flash-preview
[ ] tts_audio_tags currently: auto / main model
[ ] voice_chat currently: auto / main model
[ ] compression currently: auto / main model
[ ] approval currently: auto / main model
[ ] triage_specifier currently: auto / main model
[ ] kanban_decomposer currently: auto / main model
[ ] profile_describer currently: auto / main model
[ ] delegation currently: auto / inherit main agent
뜻: 작업마다 “지금 무엇이 맡고 있나”가 보입니다. auto / main model 은 “자동 — 주 모델”입니다.
작업을 고르고, 제공자를 고르고, 모델을 고르면 그 선택이 config.yaml 의 auxiliary.<작업> 아래에 저장됩니다. 직접 적을 때는 어느 자리든 같은 세 가지 값을 씁니다.
| 값 | 하는 일 | 기본값 |
|---|---|---|
provider | 어느 제공자로 보낼지(인증과 경로) | "auto" |
model | 어떤 모델을 부를지 | 그 제공자의 기본 모델 |
base_url | 직접 지정하는 OpenAI 호환 서버 주소. 정하면 provider 보다 앞섭니다 | 없음 |
auxiliary:
vision:
provider: "openrouter"
model: "openai/gpt-4o"
뜻: “이미지 분석은 OpenRouter 를 거쳐 이 모델에 맡긴다.” 다른 작업은 그대로 주 모델이 맡습니다.
delegation 줄은 조금 다릅니다
하위 에이전트가 쓸 모델을 고르는 줄이며, auxiliary 가 아니라 delegation.provider·delegation.model 에 저장됩니다. 여기서 auto 는 “부모 에이전트의 것을 물려받음”입니다 (7장).
알아 둘 세 가지
이미지 분석 자리에는 이미지를 이해하는 모델이 필요합니다. 제목 자동 짓기는 auxiliary.title_generation.enabled: false 로 끕니다. provider: "main"(주 에이전트의 제공자 그대로)은 보조 자리에서만 쓸 수 있고 맨 위 model.provider 에는 쓸 수 없습니다.
모델과 관련해 함께 알아 둘 설정이 둘 더 있습니다. 둘 다 대화 중 슬래시 명령으로 바꿉니다.
| 설정 | 무엇 | 바꾸는 법 |
|---|---|---|
생각 깊이agent.reasoning_effort | 모델이 답하기 전에 얼마나 “생각”할지. 비워 두면 medium(중간). 높일수록 어려운 일의 결과는 좋아지지만 토큰과 시간이 더 듭니다. 단계: none · minimal · low · medium · high · xhigh · max · ultra | /reasoning high (이번 세션만)/reasoning high --global (저장) |
빠른 모드agent.service_tier | 웃돈을 내고 더 빠른 출력을 받는 기능. 기본은 꺼짐. 지원하는 제공자의 공식 주소로 직접 연결했을 때만 적용됩니다 | /fast fast, /fast normal |
보조 작업 목록 · 작업별 제한 시간 · 쓸 수 있는 제공자
| 작업 이름 | 맡는 일 | 제한 시간 기본값 |
|---|---|---|
vision | 이미지 분석과 브라우저 화면 캡처 분석 | 120초 |
approval | 위험한 명령 승인 판단 | 30초 |
compression | 컨텍스트 압축 요약 | 120초 |
title_generation | 세션 제목. language 로 제목 언어를 고정 | 30초 |
tts_audio_tags · mcp | Gemini 3.1 TTS 용 숨은 음성 태그 넣기 · MCP 도구 전달 | 30초 |
triage_specifier | Kanban 에서 한 줄짜리 일을 구체적인 명세로 풀어 쓰기 | 120초(설정 예시) |
voice_chat · kanban_decomposer · profile_describer · group_router · background_review · curator | 원문 메뉴와 본문에 이름으로 나오는 작업들. voice_chat 은 음성 모드에서 말로 한 턴에 답하는 모델 | 그 밖의 작업은 30초 |
쓸 수 있는 제공자. auto, main, 그리고 제공자 목록의 이름(원문은 openrouter, nous, openai-codex, anthropic, gemini, deepseek, xai, bedrock 등 29개를 나열) 또는 내 providers: 에 이름 붙여 둔 제공자. 내 컴퓨터의 서버는 provider: ollama 에 base_url 을 줍니다. 제공자별 준비는 공식 문서 AI Providers 쪽 참고(이 가이드는 다루지 않음).
연결이 안 되면. 보조 작업 설정을 풀 수 없으면(모르는 제공자, 주소·인증 없음) 그 작업은 주 모델로 돌아갑니다. hermes doctor 가 실패하는 설정을 보고합니다.
보조 모델 고급 — 대체 순서 · 동시 호출 제한 · 작업별 생각 깊이 · 옛 환경 변수
- 작업별 대체 순서(
fallback_chain). 보조 작업마다 제공자·모델 목록을 달 수 있습니다. 요청 한도 초과·연결 시간 초과·결제 필요 오류가 나면 목록을 차례로 시도하고, 모두 실패하면 마지막으로 주 모델을 씁니다. - 동시 호출 제한(
max_concurrency). 압축·제목 같은 보조 호출이 한꺼번에 몰리지 않게 합니다. 기본은 무제한, 흔한 값은 2. - 작업별 생각 깊이(
reasoning_effort). 예: 압축은"low", 이미지 설명은"none". - 직접 지정한 주소의 인증.
base_url을 쓰면 그 묶음의api_key, 없으면OPENAI_API_KEY를 씁니다. - 옛 환경 변수.
AUXILIARY_VISION_MODEL등으로도 이미지 분석 모델을 정할 수 있지만 원문은config.yaml을 권합니다. - 그 밖에.
auxiliary.stream_only_base_urls(스트리밍만 받는 서버), 작업별extra_body(OpenRouter 경로 지정), 맨 위vision:(주 모델이 이미지를 직접 볼 때 싣는 양). 원문의 “Video Tutorial” 항목은 받은 원문에 제목만 있고 내용이 없습니다.
화면 표시 — 얼마나 자세히 보여 줄까
에이전트가 일하는 동안 화면에는 “지금 어떤 도구를 쓰는지”가 지나갑니다. 이 정보의 양은 display 묶음에서 정합니다. 화면 표시 설정은 보이는 것만 바꿀 뿐, 모델에게 가는 대화 내용은 바꾸지 않습니다.
display.tool_progress 의 네 단계. CLI 에서는 /verbose 를 칠 때마다 다음 단계로 넘어갑니다.display.tool_progress 가 도구 진행 표시의 양을 정합니다(위 그림). 답만 보고 싶을 때는 /focus 로 집중 보기를 켭니다. 진행 표시를 숨기고, 턴이 끝날 때 몇 줄을 숨겼는지와 되돌리는 법(/focus off)만 한 줄로 남깁니다. 숨긴 내용은 화면에서만 가려질 뿐 버려지지 않습니다.
CLI 는 턴(내 메시지 하나에 에이전트가 일하고 답하는 한 차례)이 끝날 때마다 그 턴에 한 일을 한 줄로 정리합니다(display.turn_summary, 기본 켜짐).
⋯ 12.4s · edited 2 files +18 -3 · read 4 files · ran 3 commands
뜻: “12.4초 걸림 · 파일 2개 고침(18줄 더하고 3줄 뺌) · 파일 4개 읽음 · 명령 3개 실행”. 화면 맨 아래 상태 막대에는 모델, 컨텍스트 사용량, 걸린 시간 등이 보이며, 보일 항목은 display.status_bar.fields 로 고릅니다.
display.language 는 승인 질문 같은 정해진 안내 문구 몇 가지의 언어를 바꿉니다. 한국어는 ko 입니다.
hermes config set display.language ko
뜻: “정해진 안내 문구를 한국어로.” 에이전트의 답, 로그, 도구 출력은 바뀌지 않습니다 — 에이전트가 한국어로 답하게 하려면 대화에서 그렇게 말하면 됩니다. 오래 걸리는 일을 맡길 때는 display.bell_on_complete: true(끝나면 터미널 벨 소리)가 쓸모 있습니다.
display.streaming: true 로 켜면 답을 다 쓴 뒤 한꺼번에 보여 주지 않고 글자가 나오는 대로 보여 줍니다. display.show_reasoning(기본 켜짐)은 모델의 생각 과정을 답 위에 보여 줄지이며, 대화 중 /reasoning show·/reasoning hide 로 바꿉니다.
화면 표시 설정 가운데 하나는 꼭 알아 두면 좋습니다. 에이전트가 “다 고쳤습니다”라고 말해도 실제로는 파일 수정이 실패했을 수 있는데, Hermes 는 그런 턴의 답 끝에 아래 같은 경고를 붙입니다(display.file_mutation_verifier, 기본 켜짐).
⚠️ File-mutation verifier: 3 file edit(s) FAILED this turn despite any wording above that may suggest otherwise. Run `git status` or `read_file` to confirm what actually landed.
• concepts/lora.md — [patch] Could not find match for old_string
뜻: “위에 뭐라고 적혀 있든, 이번 턴에 파일 수정 3건이 실패했습니다. 실제로 무엇이 반영됐는지 확인하세요.”
display 설정 전체 — 키 · 기본값 · 뜻
| 키 | 기본값 | 뜻 |
|---|---|---|
tool_progress · tool_progress_command | all · false | 진행 표시 단계(off | new | all | verbose) / 메신저에서 /verbose 쓰기 |
focus_view | false | 집중 보기(/focus) |
platforms | {} | 메신저별 표시 설정. 예: hermes config set display.platforms.telegram.streaming false |
interim_assistant_messages · show_commentary | true | 게이트웨이: 턴 도중의 중간 답을 별도 메시지로 보냄 / Codex 계열 모델의 진행 설명을 보여 줌 |
skin · compact | default · false | CLI 겉모습 / 빈 줄을 줄인 촘촘한 출력 |
resume_display | full | 세션을 이어 할 때 이전 메시지를 다 보여 줌(full) / 한 줄만(minimal) |
bell_on_complete · bell_on_prompt | false | 끝났을 때 / 내 답이 필요한 질문이 열렸을 때 벨 |
show_reasoning · streaming · show_cost | true · false · false | 생각 과정 표시 / 글자가 나오는 대로 표시 / 상태 막대에 예상 비용($) |
timestamps · timestamp_format | false · "%H:%M" | 대화 기록에 시각 붙이기와 그 형식 |
turn_summary · spinner_token_flow | true | CLI: 턴 끝 한 줄 정리 / 진행 표시 옆에 이번 턴의 출력 토큰 수 |
runtime_footer | enabled: false | 게이트웨이: 턴의 마지막 답 끝에 모델·컨텍스트 사용률·작업 폴더를 덧붙임. 대화 중 /footer 로 전환 |
status_bar.fields | [] | 상태 막대에 보일 항목(빈 목록 = 기본 구성) |
file_mutation_verifier | true | 파일 수정 실패 경고 |
language | en | en · zh · zh-hant · ja · de · es · fr · tr · uk · af · ko · it · ga · pt · ru · hu (본문 목록에는 ar 도 있음) |
그 밖에 suppress_warning_notifications, cli_multiline_shortcuts, vim_mode, tool_preview_length, credits_notices, cli_rebuild_scrollback_on_redraw 가 있습니다.
터미널 백엔드 — 명령이 실제로 실행되는 곳
에이전트가 “이 명령을 실행하겠다”고 할 때, 그 명령이 실제로 어디에서 돌아가는지를 정하는 것이 터미널 백엔드(terminal backend)입니다. 기본값은 내 컴퓨터(local)이고, 따로 가둔 공간이나 다른 컴퓨터로 바꿀 수 있습니다. 원문에 따르면 Hermes 에는 여섯 가지 백엔드가 들어 있고, 플러그인으로 더할 수 있습니다.
왜 바꾸나. 기본값 local 은 준비할 것이 없어 가장 편하지만 격리가 없습니다. 원문은 이렇게 경고합니다 — 이때 에이전트는 내 사용자 계정과 똑같은 파일 접근 권한을 가집니다. 걱정되면 hermes tools 로 원하지 않는 도구를 끄거나, Docker 로 바꿔 가둬 둔 공간에서 실행하게 합니다.
hermes config set terminal.backend docker
뜻: “명령을 Docker 컨테이너 안에서 실행하게 바꾼다.” 원문의 조언은 간단합니다 — 헷갈리면 local 로 되돌려 거기서 명령이 되는지부터 확인합니다.
| 백엔드 | 명령이 실행되는 곳 | 격리 | 알맞은 쓰임 |
|---|---|---|---|
local | 내 컴퓨터에서 바로 | 없음 | 개발, 개인 용도 |
docker | 오래 유지되는 Docker 컨테이너 하나 (세션, /new, 하위 에이전트가 함께 씀) | 완전 | 안전하게 가둬 놓고 실행, 자동화 서버 |
ssh | SSH(다른 컴퓨터에 안전하게 접속하는 방법)로 연결한 원격 서버 | 네트워크 경계 | 원격 개발, 성능 좋은 장비 |
modal | Modal 클라우드 샌드박스(sandbox — 바깥과 분리해 둔 실행 공간) | 완전 (클라우드 VM) | 잠깐 쓰는 클라우드 연산, 평가 |
daytona | Daytona 작업 공간 | 완전 (클라우드 컨테이너) | 관리형 클라우드 개발 환경 |
vercel_sandbox | Vercel Sandbox | 완전 (클라우드 microVM) | 파일 상태를 스냅샷으로 보존하는 클라우드 실행 |
singularity (플러그인) | Singularity/Apptainer 컨테이너 | 네임스페이스 분리 | 고성능 계산 클러스터, 여럿이 쓰는 장비 |
sprites (플러그인) | Fly.io 의 Sprite | 완전 (클라우드 microVM) | 세션이 끝나도 상태가 남는 클라우드 샌드박스 |
준비물 없음. 명령이 내 컴퓨터에서 바로 실행됩니다. git, ssh, gh, npm 처럼 평소 쓰던 프로그램의 로그인과 설정을 에이전트의 명령도 그대로 찾습니다.
준비물: Docker Desktop 또는 Docker Engine 이 설치되어 켜져 있을 것. 컨테이너(내 컴퓨터 안에 칸막이를 쳐 만든 작은 실행 환경) 안에서 실행합니다. 기본 설정에서는 컨테이너 하나를 오래 두고 같은 프로필의 세션들이 함께 쓰므로, 설치한 패키지와 /workspace 의 파일이 다음 세션에도 이어집니다. 또 기본으로는 내가 Hermes 를 실행한 폴더를 컨테이너에 넘기지 않습니다 — 내 파일을 보게 하려면 폴더를 이어 줍니다(아래 접힌 상자).
준비물: 접속할 서버와 두 환경 변수.
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu
뜻: 접속할 서버 주소와 사용자 이름. 선택 항목으로 TERMINAL_SSH_PORT(기본 22)와 TERMINAL_SSH_KEY(개인 키 경로)가 있습니다.
| 백엔드 | 필요한 것 |
|---|---|
modal | MODAL_TOKEN_ID + MODAL_TOKEN_SECRET, 또는 ~/.modal.toml 파일 |
daytona | DAYTONA_API_KEY. 디스크는 최대 10 GiB |
vercel_sandbox | 선택 설치 항목인 SDK, 그리고 VERCEL_TOKEN·VERCEL_PROJECT_ID·VERCEL_TEAM_ID 모두 |
보존되는 것은 파일 상태뿐이고, 돌고 있던 프로세스가 나중에도 살아 있다고 보장하지는 않습니다.
hermes plugins install singularity
hermes plugins install NousResearch/hermes-plugin-sprites --enable
뜻: Singularity 백엔드 플러그인 설치 / Sprites 백엔드 플러그인 설치와 켜기. Singularity 는 Docker 를 쓸 수 없는 계산 클러스터용이고, Sprites 는 ~/.hermes/.env 에 SPRITES_TOKEN 이 있어야 합니다.
명령이 바로 실패하거나 터미널 도구가 꺼져 있다고 나오면 아래를 확인합니다.
| 백엔드 | 확인할 것 |
|---|---|
| Docker | docker version 을 실행해 Docker 가 되는지 봅니다. 안 되면 Docker 를 고치거나 hermes config set terminal.backend local |
| SSH | TERMINAL_SSH_HOST 와 TERMINAL_SSH_USER 가 둘 다 있는지 |
| 클라우드 · 플러그인 | 위 탭의 환경 변수와 플러그인이 갖춰졌는지. hermes doctor 로 점검합니다 |
도구 쪽에서 본 백엔드 이야기는 4장, 안전 관점의 격리는 9장에서 이어집니다.
공통 키와 작업 폴더 — terminal 묶음
| 키 | 기본값 | 뜻 |
|---|---|---|
backend | local | local | docker | ssh | modal | daytona | vercel_sandbox | 플러그인 백엔드 |
cwd | "." | 게이트웨이·예약 작업의 작업 폴더(CLI 는 언제나 실행한 폴더) |
timeout | 180 | 명령 하나의 제한 시간(초) |
home_mode | auto | 에이전트의 명령이 보는 홈 폴더. auto = 내 컴퓨터에서는 실제 홈, 컨테이너에서는 {HERMES_HOME}/home. profile = 프로필 전용 홈(프로필마다 git·SSH 로그인을 따로 두고 싶을 때) |
persistent_shell | true | SSH: 명령 사이에 export 한 환경 변수를 이어 감(local 은 TERMINAL_LOCAL_PERSISTENT). 작업 폴더는 항상 이어지고, Docker·클라우드·플러그인 백엔드는 이 설정을 무시 |
container_persistent | true | 파일 상태를 세션 사이에 보존 |
| 어디서 쓰나 | 작업 폴더 기본값 |
|---|---|
CLI (hermes) | 명령을 실행한 현재 폴더 |
| 메신저 게이트웨이 | terminal.cwd, 없으면 홈 폴더 ~ |
| Docker / Singularity / Modal / SSH | 컨테이너나 원격 컴퓨터 안의 사용자 홈 폴더 |
Docker 백엔드 세부 — 폴더 잇기 · 비밀 값 넘기기 · 컨테이너가 남는 때
| 키 | 기본값 | 뜻 |
|---|---|---|
docker_image | "nousresearch/hermes-sandbox:desktop" | 컨테이너 이미지 |
docker_volumes | — | 내 컴퓨터 폴더를 컨테이너에 잇기. "내컴퓨터경로:컨테이너경로", 읽기 전용은 끝에 :ro |
docker_mount_cwd_to_workspace | false | true 면 Hermes 를 실행한 폴더를 /workspace 에 이음. 컨테이너가 내 실제 파일을 직접 만지게 되므로 일부러 원할 때만 |
docker_forward_env | — | 컨테이너로 넘길 환경 변수 이름. 값은 내 셸, 다음으로 ~/.hermes/.env 에서 찾음. 넘긴 값은 컨테이너 안의 명령이 볼 수 있음 |
docker_env | — | 컨테이너에 넣을 고정 값. 비밀이 아닌 것에만 |
docker_network | true | false 면 컨테이너의 네트워크를 완전히 끊음 |
docker_run_as_host_user | false | true 면 이어 둔 폴더에 생긴 파일이 내 소유가 됨. 대신 컨테이너 안에서 apt install 은 못 함 |
- 컨테이너는 Hermes 를 꺼도 남습니다.
/quit이나 화면 닫기에도 기본 설정에서는 계속 돌고, 다음 Hermes 가 바로 다시 붙습니다. 컴퓨터를 다시 켜면 멈춘 상태로 남아 파일은 살아 있고 뒤에서 돌던 프로세스는 사라집니다. - 세션마다 새 컨테이너.
container_persistent: false로 두면 대화마다 새 컨테이너가 생기고 세션이 끝나면 지워집니다. 대화 사이를 보안 경계로 삼고 싶을 때 씁니다. - 원격 백엔드의 상태 되가져오기. SSH·Modal·Daytona 는 끝날 때 바뀐 Hermes 상태(
~/.hermes/)를 내 컴퓨터로 되가져옵니다. 샌드박스 안의 일반 작업 파일은 대상이 아니므로, 중요한 결과물은 지워지기 전에 따로 꺼내게 합니다.
나머지 설정 한눈에 — 분류별 접힌 표
공식 설정 문서의 큰 제목 63개를 여덟 묶음으로 나눠, 제목마다 “무엇을 하는 설정인지” 한 줄과 대표 설정 이름을 적었습니다. 앞에서 다룬 것은 그 소절로 가는 링크를 달았습니다. 외울 필요는 없고, 낯선 설정 이름을 만났을 때 찾아보는 곳입니다. 영어 제목은 공식 문서의 제목 그대로이고, 괄호 안은 기본값이나 고를 수 있는 값입니다.
① 파일 · 관리 · 기본 환경 (11)
| 설정 (원문 제목) | 무엇을 하나 | 대표 설정 이름 |
|---|---|---|
| 폴더 구조 Directory Structure | ~/.hermes/ 안의 파일과 폴더 — 설정이 저장되는 곳 | config.yaml · .env |
| 설정 관리 명령 Managing Configuration | 설정을 보고 바꾸는 명령 — 설정 보고 바꾸기 | hermes config set |
| 우선순위 Configuration Precedence | 값이 여러 곳에 있을 때 이기는 순서 — 어떤 값이 이기나 | — |
| 환경 변수 불러 쓰기 Environment Variable Substitution | config.yaml 안에서 ${이름} 으로 환경 변수 값을 불러 씀. 같은 절에 제공자별 요청 제한 시간(Provider Timeouts)도 있음 | ${VAR_NAME}providers.<id>.request_timeout_seconds |
| 업데이트 동작 Update Behavior | 새 버전 확인(하루 한 번 이하)과 업데이트 전 자동 백업 — quick(기본, 핵심 상태 파일만) · full · off | updates.pre_update_backupupdates.backup_keep (5) |
| 작업 폴더 Working Directory | 에이전트가 일을 시작하는 폴더. CLI 는 명령을 실행한 폴더, 게이트웨이는 설정값(없으면 홈) | terminal.cwd |
| 시간대 Timezone | 컴퓨터의 시간대 대신 쓸 시간대. 예약 작업 시각과 에이전트가 아는 현재 시각에 영향(로그 시각은 그대로) | timezone · HERMES_TIMEZONE |
| 네트워크 Network | IPv6 가 고장 난 서버에서 IPv4 로만 연결하게 함 | network.force_ipv4 |
| 첫 사용 안내 Onboarding | 맨 처음 메시지 때 사용자 프로필을 만들지 제안할지. 동의해야 진행되고 프로필당 한 번만 나옴 | onboarding.profile_build (ask | off) |
| 데이터베이스 Database Settings | 세션·메시지를 담는 state.db 를 여는 방식. 네트워크 저장소 위에 둘 때만 손댐 | database.journal_mode (wal | delete) |
| 실행 환경 한도 Runtime Limits | 오래 켜 두는 서버(게이트웨이 등)가 동시에 열 수 있는 파일 수와 Linux 에서의 메모리 구역 수 | runtime.nofile_soft_limit (4096)runtime.malloc_arena_max (4) |
② 모델 · 응답 방식 (7)
| 설정 (원문 제목) | 무엇을 하나 | 대표 설정 이름 |
|---|---|---|
| 보조 모델 Auxiliary Models | 곁가지 일을 맡는 모델 — 보조 모델 | auxiliary.<작업>.provider · model |
| 생각 깊이 Reasoning Effort | 답하기 전 생각의 양. 모델별로 따로 줄 수 있음. 같은 절에 답의 길이(text_verbosity)와 OpenAI Daybreak 스위치도 있음 | agent.reasoning_effortagent.reasoning_overrides |
| 빠른 모드 Fast Mode | 웃돈을 내고 빠른 출력을 요청 — fast(항상) · auto(매 턴 처음 60초) · cold(세션 첫 턴만) | agent.service_tieragent.fast_auto_seconds (60) |
| 프롬프트 캐시 Prompt caching | 매번 똑같이 보내는 앞부분을 제공자가 기억해 두었다가 할인 요금으로 다시 씀. 자동이고 끌 수 없으며, 기억해 둘 시간만 고름 | prompt_caching.cache_ttl ("5m" | "1h" | "auto") |
| 여러 키 돌려 쓰기 Credential Pool Strategies | 한 제공자에 API 키가 여러 개일 때 고르는 방식 — fill_first(기본) · round_robin · least_used · random | credential_pool_strategies.<제공자> |
| 도구 사용 다잡기 Tool-Use Enforcement | “하겠다”고 말만 하고 도구를 부르지 않는 모델에게 “바로 도구를 부르라”는 지침을 더함. "auto"(기본)는 필요한 모델 계열에만 | agent.tool_use_enforcement |
| 꼼꼼한 실행 지침 Execution-Discipline Guidance | 암산 대신 도구로 계산하기, 바깥에 쓴 뒤 다시 읽어 확인하기 같은 지침을 특정 모델 계열에 더함 | agent.execution_guidance |
③ 한도 · 시간 · 멈춤 방지 (9)
| 설정 (원문 제목) | 무엇을 하나 | 대표 설정 이름 |
|---|---|---|
| 파일 읽기 한도 File Read Safety | 파일을 한 번에 얼마나 읽을 수 있나 — 꼭 알아 둘 한도 | file_read_max_chars |
| 도구 출력 한도 Tool Output Truncation Limits | 명령 출력을 자르는 기준과 큰 결과를 디스크로 넘기는 기준 — 꼭 알아 둘 한도 | tool_output.max_bytes · max_linestool_budget.mcp_result_size_chars |
| 맥락 파일 한도 Context File Truncation | 자동으로 읽히는 맥락 파일을 얼마까지 읽어 들일지. 넘으면 앞과 뒤만 남김 | context_file_max_charscontext_file_read_timeout (5.0) |
| 반복 횟수 한도 Iteration Budget | 내 메시지 하나에 에이전트가 되풀이할 수 있는 횟수와 제공자 오류 때의 재시도 — 꼭 알아 둘 한도 | agent.max_turnsagent.api_max_retries (3) |
| 실행 시간 예산 Wall-Clock Run Budget | 실행 한 번에 쓸 시간(초). 일회성 실행·평가용이며 기본은 꺼짐 | agent.run_budget_seconds |
| 끝내기 전 확인 Verify-on-Stop (coding verification) | 코드를 고치고도 테스트·빌드 같은 확인 증거가 없으면 끝내지 않고 확인을 요구. 기본 꺼짐 | agent.verify_on_stop (true | false | "auto")agent.max_verify_nudges (3) |
| 이어 가는 목표 Standing Goals (/goal) | 세워 둔 목표를 이룰 때까지 같은 세션에서 계속 일하게 하는 기능의 최대 이어 가기 횟수. 같은 절에 제공자 응답 대기 시간 표(API Timeouts)와 스트리밍 끄기도 있음 | goals.max_turns (20)model.streaming |
| 되풀이 감지 Tool-Loop Guardrails | 같은 실패의 되풀이를 알아채 경고하거나 막음 — 꼭 알아 둘 한도 | tool_loop_guardrails.loop_capsagent.stall_guards · agent.turn_liveness |
| 되묻기 대기 Clarify | 에이전트가 되물은 질문에 답을 기다리는 시간(초) | agent.clarify_timeout (90) |
④ 컨텍스트 · 기억 · 스킬 (6)
| 설정 (원문 제목) | 무엇을 하나 | 대표 설정 이름 |
|---|---|---|
| 컨텍스트 압축 Context Compression | 긴 대화를 요약해 줄임 — 대화가 길어지면 | compression.enabled · compression.threshold |
| 컨텍스트 압력 알림 Context Pressure Warnings | 압축 시작선에 가까워지면 알림(60% 안내, 85% 경고). 자동 — 대화가 길어지면 | (설정 이름 없음) |
| 컨텍스트 엔진 Context Engine | 컨텍스트 관리 방식을 통째로 바꾸는 플러그인 고르기. 기본은 요약 방식 compressor | context.engine |
| 기억 설정 Memory Configuration | 기억 켜기, 크기 한도, 쓰기 전에 내 승인 받기 (5장) | memory.memory_char_limit (2200)memory.write_approval |
| 스킬 설정 Skill Settings | 스킬별 설정값, 세션마다 자동으로 불러올 스킬, 에이전트가 스킬을 고칠 때의 검사·승인 (6장) | skills.config.<스킬>skills.auto_load · skills.write_approval |
| 맥락 파일 Context Files (SOUL.md, AGENTS.md) | 자동으로 읽히는 파일. SOUL.md 는 항상, 프로젝트 파일은 .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules 중 처음 발견한 한 종류만 (5장) | (파일) ~/.hermes/SOUL.md |
⑤ 도구 · 실행 환경 (8)
| 설정 (원문 제목) | 무엇을 하나 | 대표 설정 이름 |
|---|---|---|
| 터미널 백엔드 Terminal Backend Configuration | 명령이 실제로 실행되는 곳 — 터미널 백엔드 | terminal.backend · terminal.timeout |
| 툴셋 한꺼번에 끄기 Global Toolset Disable | 적어 둔 툴셋을 CLI 와 모든 메신저에서 한 번에 끔 (4장) | agent.disabled_toolsets |
| 작업 사본 분리 Git Worktree Isolation | 같은 저장소에서 여러 에이전트를 동시에 돌릴 때, CLI 세션마다 별도 작업 사본(worktree)과 브랜치를 만듦 | worktree (hermes -w 와 같음)worktree_sync |
| 코드 실행 Code Execution | 에이전트가 스크립트를 짜서 돌리는 execute_code 도구의 실행 폴더·제한 시간·호출 수 | code_execution.mode (project | strict)code_execution.timeout (300) |
| 웹 검색 서비스 Web Search Backends | web_search·web_extract 도구가 쓸 검색 서비스. hermes tools 로도 고름 | web.backend (firecrawl 기본)web.search_backend · web.extract_backend |
| 브라우저 Browser | 브라우저 자동 조작 — 쉬는 브라우저를 닫는 시간, 창을 보이게 띄울지, 클라우드 브라우저 선택 | browser.inactivity_timeout (120)browser.headed · browser.cloud_provider |
| 위임 Delegation | 하위 에이전트가 쓸 모델, 동시에 돌릴 수, 위임의 깊이 (7장) | delegation.modeldelegation.max_concurrent_children (3)delegation.max_spawn_depth (1) |
| 빠른 명령 Quick Commands | 모델을 거치지 않고 셸 명령을 바로 실행하는 나만의 슬래시 명령(토큰을 쓰지 않음), 또는 다른 슬래시 명령의 별칭 | quick_commands.<이름>.type (exec | alias) |
⑥ 안전 · 개인정보 (6)
| 설정 (원문 제목) | 무엇을 하나 | 대표 설정 이름 |
|---|---|---|
| 비밀 값 가리기 Security | 도구 출력과 로그에서 API 키·토큰·비밀번호처럼 보이는 글자를 자동으로 가림. 기본 켜짐 | security.redact_secrets |
| 사이트 차단 목록 Website Blocklist | 웹·브라우저 도구가 들어가지 못할 사이트 목록. 기본 꺼짐 | security.website_blocklist.enabledsecurity.website_blocklist.domains |
| 승인 방식 Smart Approvals | 위험해 보이는 명령을 다루는 방식 — smart(기본, 보조 모델이 판단) · manual(매번 물음) · off(검사를 끔, 주의) (9장) | approvals.mode · approvals.deny |
| 체크포인트 Checkpoints | 파일을 바꾸기 전에 찍어 두는 자동 스냅샷. 기본 꺼짐 (9장) | checkpoints.enabledcheckpoints.max_snapshots (20) |
| 개인정보 가리기 Privacy | 메신저에서 전화번호·사용자 ID·대화방 ID 를 모델에 보내기 전에 알아볼 수 없는 값으로 바꿈(게이트웨이 전용) | privacy.redact_pii |
| 모르는 사람의 개인 메시지 Unauthorized DM Behavior | 허락하지 않은 사람이 봇에 개인 메시지를 보냈을 때 — pair(기본, 연결 코드 안내) · ignore(무시) · decline(짧게 거절) (9장) | unauthorized_dm_behavior |
⑦ 화면 · 소리 (5)
| 설정 (원문 제목) | 무엇을 하나 | 대표 설정 이름 |
|---|---|---|
| 화면 표시 Display Settings | 화면에 보이는 정보의 양과 모양 — 화면 표시 | display.tool_progress · display.language |
| 실시간 출력 Streaming | 답을 글자가 나오는 대로 보여 줌. 터미널과 메신저의 스위치가 따로 있음 | display.streaming (터미널)streaming.enabled (메신저) |
| 글을 소리로 TTS Configuration | 답을 소리로 읽어 주는 서비스·목소리·속도 | tts.provider ("edge" 등) · tts.speed |
| 소리를 글로 Speech-to-Text (STT) | 받은 음성 메시지를 글로 받아 적기. 기본 켜짐. 언어 기본값은 "en" 이며 다른 언어는 언어 코드를 정해 고정 | stt.enabled · stt.providerstt.language |
| 음성 모드 Voice Mode (CLI) | CLI 에서 마이크로 말하기. /voice on 으로 켬 (8장) | voice.record_key ("ctrl+b")voice.auto_tts |
⑧ 메신저 · 게이트웨이 · 서버 운영 (11)
| 설정 (원문 제목) | 무엇을 하나 | 대표 설정 이름 |
|---|---|---|
| 세션 수와 단체방 분리 Group Chat Session Isolation | 두 가지가 한 절에 있음 — 동시에 활동할 수 있는 세션 수(기본 무제한), 단체방에서 사람마다 세션을 따로 줄지(기본 true) | max_concurrent_sessionsgroup_sessions_per_user |
| 토론 방 상한 Native Hosted-Room Discussion Limits | 서버가 여는 방에서 구성원들이 주고받는 토론의 상한 | hosted_rooms.discussion.max_rounds (3)hosted_rooms.discussion.max_messages (10) |
| 사람처럼 늦게 답하기 Human Delay | 메신저 답장을 사람이 치는 것처럼 조금 늦춤. 기본 꺼짐 | human_delay.mode (off | natural | custom) |
| Discord 전용 Discord | Discord 서버 채널에서 @멘션해야 답할지, 스레드를 자동으로 만들지 | discord.require_mentiondiscord.auto_thread |
| 차례 기다리기 시간 Gateway Turn Lease Timeout | 같은 세션에 요청이 겹쳤을 때 뒤 요청이 기다리는 최대 시간(초). 넘으면 거절 알림이 오고 다시 보내야 함 | agent.gateway_turn_lease_timeout (5) |
| 재시작 때 기다려 주기 Gateway Restart Drain | 게이트웨이를 끄거나 다시 켤 때 진행 중인 턴을 기다려 줄 시간(초). 기본 0 은 바로 중단 (8장) | agent.restart_drain_timeout (0)agent.cron_drain_timeout (30) |
| 멈춘 세션 알림 Session Stall Watchdog | 세션이 오래 멈춘 듯하면 알림을 한 번 보냄. 알리기만 하고 중단하지는 않음 | agent.session_stall_timeout (300) |
| 연결 실패 알림 Reconnect Attention Escalation | 메신저 연결이 이 시간(기본 2시간) 넘게 재시도만 하고 있으면 hermes status 에 “확인 필요” 표시 | agent.reconnect_attention_after (7200) |
| 에이전트 캐시 Gateway Agent Cache | 게이트웨이가 세션별 에이전트를 메모리에 들고 있는 양(개수·쉬는 시간·메모리 예산) | agent.agent_cache.max_size (128)agent.agent_cache.idle_ttl_secs (3600) |
| 웹 화면 Webapp | 게이트웨이가 Desktop 작업 화면을 브라우저로 내주는 기능. 기본 꺼짐 | webapp.enabled · webapp.port (9120) |
| 대시보드 Dashboard | 웹 대시보드의 테마, 바깥에서 접속하는 주소, 로그인 방식 | dashboard.theme · dashboard.public_url |
- Hermes 의 설정은 모두
~/.hermes/폴더에 있습니다. 비밀 값은.env, 그 밖의 모든 설정은config.yaml입니다. hermes config get으로 보고,set으로 바꾸고,unset으로 지웁니다.set은 이름 모양을 보고 알맞은 파일에 저장합니다.- 값이 여러 곳에 있으면 명령에 붙인 옵션 →
config.yaml→.env→ 내장 기본값 순서로 이깁니다. - 파일 읽기(100000자), 터미널 출력(50000자), 명령 시간(180초) 같은 한도가 컨텍스트를 지킵니다.
- 대화가 컨텍스트 한도의 50%에 닿으면 오래된 부분을 요약으로 바꾸는 압축이 자동으로 일어납니다. 압축 전 대화도 지워지지 않습니다.
- 이미지 분석·제목 짓기·압축 요약 같은 곁가지 일은 보조 모델 자리가 맡습니다. 기본은 주 모델이며
hermes model메뉴에서 바꿉니다. - 답 끝에 파일 수정 실패 경고가 붙으면 모델의 말보다 그 경고를 믿습니다.
- 터미널 백엔드는 명령이 실행되는 곳입니다. 기본
local은 격리가 없고, 헷갈리면local로 되돌려 확인합니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/configuration (수집일 2026-11-09 의 공식 문서)
도구 · 툴셋 · MCP
Hermes Agent 는 AI 에이전트(말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)입니다. 그 “일을 해 주는” 부분을 맡는 것이 도구입니다. 이 장에서는 Hermes 에 어떤 도구가 들어 있는지, 도구 꾸러미인 툴셋을 어떻게 켜고 끄는지, 에이전트의 명령이 실제로 어디에서 실행되는지, 그리고 MCP 로 바깥 서비스의 도구를 어떻게 꽂아 쓰는지 차례로 살펴봅니다.
- 도구가 무엇이고 Hermes 에 어떤 종류가 들어 있는지
- 툴셋으로 도구를 켜고 끄는 방법(
hermes tools,--toolsets) - 명령이 실행되는 곳(터미널 백엔드)을 내 컴퓨터 · Docker · SSH 로 바꾸는 법
- 오래 걸리는 명령과 관리자 비밀번호(sudo)를 다루는 방식
- MCP 가 무엇이고, MCP 서버를 어떻게 추가하는지
- MCP 도구를 걸러 내고 안전하게 쓰는 법, 안 될 때 볼 곳
- 도구란 무엇인가 — 에이전트의 “손”. 어떤 종류가 있는지 표 하나로 봅니다.
- 툴셋 — 도구 꾸러미를 켜고 끄기 — 명령 두 개만 알면 됩니다.
- MCP 란 — 바깥 서비스의 도구를 꽂는 공통 규격.
- 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장의 메신저 “게이트웨이”와는 다른 것입니다.)
표의 작은 글씨 — X 검색 · 브라우저 · 자동화 · 플러그인
- X 검색 — xAI 자격 증명(SuperGrok OAuth 또는
XAI_API_KEY)이 있어야 하고 기본은 꺼져 있습니다.hermes tools→ 🐦 X (Twitter) Search 에서 켭니다. - 브라우저 —
browser_exec는 Python 으로 CDP 를 거쳐 Chromium 을 조종합니다. Camofox 브라우저는 별도 플러그인입니다(hermes plugins install camofox). - 자동화 — 결과를 바깥으로 보내는 일은 cron 자체의 전달 기능,
hermes sendCLI, 게이트웨이 알림이 맡습니다(에이전트가 부르는 도구가 아닙니다). - 플러그인 — Home Assistant 도구(
ha_*)는homeassistant카탈로그 플러그인에서 옵니다. 세션을 넘나드는 기억 Honcho 는 내장 툴셋이 아니라 기억 제공자 플러그인입니다(hermes plugins install honcho). - 정확한 전체 목록은 공식 문서 Built-in Tools Reference · Toolsets Reference · Memory Providers 쪽 참고(이 가이드는 다루지 않음).
도구 결과에 붙는 설명 두 가지 (Tool result annotations)
| 상황 | Hermes 가 하는 일 |
|---|---|
| 명령이 신호(signal)로 강제 종료됨 | 숫자 코드만 내놓지 않고 풀이를 붙입니다. 예: 종료 코드 -9 / 137 → “signal 9: SIGKILL — 흔히 메모리 부족으로 운영체제가 죽였거나 kill -9”. 세그폴트 · abort · SIGTERM · 끊어진 파이프 · CPU/파일 크기 한도도 같은 식이고, 셸의 “128+신호 번호” 코드에는 “usually(보통)”를 붙입니다. |
| UTF-16 글 파일을 읽음 | read_file 이 UTF-16(Windows 메모장, PowerShell 의 > 저장에 흔함)을 바이너리라고 거절하지 않고 UTF-8 로 바꿔 보여 주며, 변환했다고 알립니다. 고치면 UTF-8 로 저장됩니다. 10 MB 초과 파일과 진짜 바이너리는 여전히 거절합니다. |
툴셋 — 도구 꾸러미를 켜고 끄기
도구는 하나하나 따로 관리하지 않고 툴셋(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 쪽 참고(이 가이드는 다루지 않음).
터미널 백엔드 — 명령이 실제로 실행되는 곳
에이전트가 terminal 도구로 명령을 실행할 때, 그 명령이 어느 컴퓨터 · 어떤 환경에서 돌아가는지를 정하는 것이 터미널 백엔드(terminal backend — 에이전트의 명령이 실제로 실행되는 곳)입니다. 기본은 local, 곧 내 컴퓨터입니다. 에이전트가 내 컴퓨터를 직접 건드리는 것이 걱정되면 실행 장소를 따로 떼어 낼 수 있습니다.
| 백엔드 | 무엇인가 | 이럴 때 |
|---|---|---|
local | 내 컴퓨터에서 실행(기본) | 개발, 믿을 수 있는 작업 |
docker | 따로 떨어진 컨테이너(내 컴퓨터 안에 칸막이를 쳐 만든 작은 실행 환경) | 보안, 같은 환경을 다시 만들기 |
ssh | 원격 서버(SSH — 다른 컴퓨터에 안전하게 접속해 명령을 내리는 방법) | 격리, 에이전트를 자기 코드에서 떼어 놓기 |
singularity (플러그인) | HPC 컨테이너 | 클러스터 컴퓨팅, 관리자 권한 없이 실행 |
sprites (플러그인) | 상태가 유지되는 Fly.io 클라우드 샌드박스 | 체크포인트 · 복원이 되는, 오래 유지하는 클라우드 환경 |
modal | 클라우드 실행 | 서버를 직접 두지 않는 실행, 규모 키우기 |
daytona | 클라우드 샌드박스 작업 공간 | 오래 유지하는 원격 개발 환경 |
vercel_sandbox | Vercel Sandbox 클라우드 microVM | 스냅샷으로 파일을 보존하는 클라우드 실행 |
바꾸는 곳은 설정 파일 ~/.hermes/config.yaml 의 terminal 항목입니다(~ 는 내 홈 폴더. 설정 파일을 여는 방법은 3장, 터미널 관련 설정 전체는 3장 「터미널 설정」).
# ~/.hermes/config.yaml
terminal:
backend: local # 또는 docker, ssh, modal, daytona, vercel_sandbox, 플러그인 백엔드(singularity, sprites)
cwd: "." # 작업 폴더
timeout: 180 # 명령 하나가 기다려 주는 최대 시간(초)
기본값입니다. 에이전트의 명령이 내 컴퓨터에서 실행됩니다. 원문은 개발이나 믿을 수 있는 작업에 쓰라고 적습니다. 위험한 명령 앞에서 묻는 승인 절차는 9장에서 다룹니다.
terminal:
backend: docker
docker_image: python:3.11-slim
Docker(컨테이너를 만들어 돌리는 프로그램) 컨테이너 안에서 실행합니다. 명령마다 새 컨테이너가 아니라 오래 살아 있는 컨테이너 하나를 계속 씁니다 — 설치한 패키지, 옮겨 간 작업 폴더, /workspace 에 쓴 파일이 다음 호출에도 남고, Hermes 를 끝내면 컨테이너도 멈추고 지워집니다.
terminal:
backend: ssh
# 접속 정보는 ~/.hermes/.env 에
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa
명령을 다른 서버에서 실행합니다. 원문은 이 방식을 보안 면에서 권장합니다 — 에이전트가 자기 자신의 코드를 고칠 수 없기 때문입니다. 접속할 서버 주소 · 사용자 이름 · 열쇠 파일 위치는 비밀 값을 두는 ~/.hermes/.env 에 적습니다.
.bashrc, .zshrc)에 느리거나 입력을 기다리는 내용이 있으면 에이전트의 명령만 느려지거나 멈춥니다. 원문은 이 증상에서 셸 시작 파일을 가장 먼저 의심하라고 적습니다.
셸 시작 파일 손보기 — 사람이 없을 때는 일찍 빠져나가게
문제는 세 가지입니다: 느린 초기화(nvm 같은 버전 관리 도구 — 에이전트는 셸을 아주 많이 띄웁니다), 사람 입력을 기다리는 부분(묻기 · tmux/screen 붙기 · read · 메뉴), 무조건 찍히는 배너. .bashrc 맨 위 가까이에 아래 표준 가드를 두고, 무겁거나 사람과 주고받는 초기화는 그 아래에 둡니다.
case $- in
*i*) ;; # 대화형: 계속 진행
*) return;; # 비대화형: 여기서 멈춤
esac
zsh: 로그인 전용 설정은 .zprofile, 대화형 전용은 .zshrc, .zshenv 는 최소로 둡니다(모든 셸에서 실행됨). 에이전트에게 필요한 도구의 PATH 는 가드 위에서 내보내거나, 실행 파일을 ~/.local/bin 에 심볼릭 링크로 겁니다.
백엔드별 준비 명령 · 컨테이너 자원과 보안
| 백엔드 | 준비 | 알아 둘 점 |
|---|---|---|
| docker | docker_image: python:3.11-slim | 처음 쓸 때 컨테이너 하나를 띄우고(docker run -d ... sleep infinity) 모든 terminal · 파일 · execute_code 호출을 docker exec 로 보냅니다. /new, /reset, 하위 에이전트를 가리지 않고 이어집니다(공식 문서 Configuration → Docker Backend). |
| singularity | hermes plugins install singularity → apptainer build ~/python.sif docker://python:3.11-slim → hermes config set terminal.backend singularity → hermes config set terminal.singularity_image ~/python.sif | Singularity/Apptainer 공식 플러그인(예전에는 내장). 쓰던 프로필에는 hermes update 가 설치해 줍니다. |
| sprites | hermes plugins install NousResearch/hermes-plugin-sprites --enable → hermes config set terminal.backend sprites | ~/.hermes/.env 에 SPRITES_TOKEN 추가(공식 문서 Sprites Backend). |
| modal | python -c "import pm; pm.sync_venv(['modal'], explicit=True)" → modal setup → hermes config set terminal.backend modal | 서버리스 클라우드. |
| vercel_sandbox | python -c "import pm; pm.sync_venv(['vercel'], explicit=True)" → hermes config set terminal.backend vercel_sandbox → hermes config set terminal.vercel_image vercel/sandbox/universal:latest | VERCEL_TOKEN · VERCEL_PROJECT_ID · VERCEL_TEAM_ID 세 가지 모두 필요(일회성 로컬 개발에는 VERCEL_OIDC_TOKEN="$(vc project token)" hermes chat). container_disk 는 기본값 그대로 — 크기 지정 미지원이라 바꾸면 실패합니다. 재시작 뒤 떼어 낸 프로세스를 되찾는 기능은 없습니다. |
원문은 python -c "import pm; …" 명령이 “PM 이 준비한 소스 체크아웃”을 쓴다고만 적습니다(의존성을 바꾼 뒤에는 체크아웃을 다시 활성화하고 Hermes 재시작). hermes config set 은 3장.
terminal:
backend: docker # 또는 modal, daytona, vercel_sandbox, singularity(플러그인)
container_cpu: 1 # CPU 코어 수 (기본 1)
container_memory: 5120 # 메모리 MB (기본 5GB)
container_disk: 51200 # 디스크 MB (기본 50GB)
container_persistent: true # 세션이 바뀌어도 파일을 남김 (기본 true)
자원 — 위 값은 컨테이너를 쓰는 모든 백엔드에 공통입니다. container_persistent: true 이면 설치한 패키지 · 파일 · 설정이 세션을 넘어 남습니다(Vercel 은 스냅샷으로 파일만 보존 — 실행 중이던 프로세스는 아님).
보안 — 모든 컨테이너 백엔드는 읽기 전용 루트 파일 시스템(Docker), 리눅스 권한 전부 제거, 권한 상승 금지, 프로세스 256개 제한, 네임스페이스 완전 격리, 볼륨으로 보존하는 작업 공간으로 실행됩니다. terminal.docker_forward_env 로 Docker 에 넘긴 환경 변수는 컨테이너 안 명령이 볼 수 있습니다. 격리 전반은 9장.
오래 걸리는 명령 — 백그라운드 프로세스
테스트 전체 돌리기나 서버 띄우기처럼 오래 걸리는 명령을 에이전트가 끝날 때까지 붙잡고 기다리면 그동안 아무 일도 못 합니다. 그래서 에이전트는 명령을 백그라운드(background — 뒤에서 따로 돌려 두는 것)로 시작해 두고, 번호표를 받아 나중에 확인할 수 있습니다. 이 일은 에이전트가 도구로 하는 것이라 내가 직접 입력할 명령은 없습니다 — 대화 기록에서 아래와 같은 호출이 보이면 “뒤에서 돌려 두었구나” 하고 읽으면 됩니다.
terminal(command="pytest -v tests/", background=true)
# 돌려받는 값: {"session_id": "proc_abc123", "pid": 12345}
돌려받은 session_id 가 번호표입니다(대화 한 묶음을 뜻하는 “세션”과는 다른 것 — 뒤에서 도는 프로세스(실행 중인 프로그램 하나)에 붙은 이름입니다). 그다음에는 process 도구로 관리합니다.
| 호출 | 하는 일 |
|---|---|
process(action="list") | 실행 중인 프로세스를 모두 보여 줍니다. |
process(action="poll", session_id="proc_abc123") | 지금 상태를 확인합니다. |
process(action="wait", session_id="proc_abc123") | 끝날 때까지 기다립니다. |
process(action="log", session_id="proc_abc123") | 출력 전체를 읽습니다. |
process(action="kill", session_id="proc_abc123") | 강제로 끝냅니다. |
process(action="write", session_id="proc_abc123", data="y") | 실행 중인 프로그램에 입력을 보냅니다(예: “y”). |
알아 둘 동작이 두 가지 더 있습니다. 첫째, PTY 모드(pty=true)를 켜면 Codex 나 Claude Code 처럼 사람과 주고받도록 만든 터미널 프로그램도 돌릴 수 있습니다. 둘째, 조용한 프로세스를 에이전트가 자꾸 들여다보지 않게 하는 장치가 있습니다 — 아직 실행 중이고 새 출력도 없는 프로세스를 두 번 연속 확인(wait 또는 poll)하면, Hermes 가 그 프로세스에 “끝나면 알림”(notify_on_complete)을 켜고 에이전트에게 그만 확인하라고 알려 줍니다. 끝났다는 소식(종료 코드와 마지막 출력)은 나중에 별도 메시지로 도착하므로, 에이전트는 그동안 다른 일을 하거나 차례를 마칠 수 있습니다.
명령 끝의 & 는 자동으로 백그라운드가 됩니다
백그라운드 표시가 맨 끝의 & 하나뿐인 명령(예: python3 -m http.server 8765 &, cd app && npm start > app.log 2>&1 &)은 & 를 떼고 background=true 로 실행되며, 결과에 session_id 와 auto_backgrounded 표시가 붙습니다. 승인 검사는 똑같이 거칩니다. 다른 명령이 섞인 모양(server & curl ..., a; b &, 여러 줄 스크립트), nohup / disown / setsid 로 감싼 것, 명령 치환($(...), 백틱, <(...)), & 를 떼면 승인 분류가 달라지는 명령은 안내와 함께 거절됩니다 — 어느 부분을 계속 돌려야 할지 안전하게 가릴 수 없기 때문입니다.
“끝나면 알림”이 적용되는 곳 · 끄는 설정 · 끝난 결과의 보관
| 주제 | 내용 |
|---|---|
| 적용되는 곳 | 끝났다는 소식이 에이전트에 닿을 수 있는 곳 — 대화형 CLI(대화형 hermes chat -q 포함), TUI 와 데스크톱 앱, 메신저 대화. |
| 예전 방식 그대로인 곳 | 비대화형 hermes chat -q, hermes -z, 예약 작업, Kanban 작업자, 상태 없는 API 요청, 하위 에이전트, display.background_process_notifications: off 인 프로필, 소식이 다른 세션으로 가는 프로세스. |
| 횟수 초기화 · 끄기 | 새 출력, 프로세스 종료, 그 프로세스에 대한 다른 동작이 있으면 처음부터 다시 셉니다. 어디서나 끄려면 terminal.process_wait_auto_notify: false. |
| 끝난 결과 보관 | 최근 64개를 끝난 뒤 최대 7일, 프로필의 Hermes 홈 아래 logs/process-results/ 에 둡니다. 결과마다 출력 끝부분 최대 200,000자, 비밀 값 가림은 항상 적용됩니다. |
| 되찾는 법 | 그 명령을 시작한 대화(또는 압축되어 이어진 대화)를 이어 연 뒤 원래 session_id 로 process(action="log") · process(action="poll"). 관계없는 대화는 번호표를 알아도 읽을 수 없습니다. 명령을 다시 실행하거나 알림을 다시 보내지는 않습니다. |
sudo — 관리자 비밀번호가 필요한 명령
프로그램 설치처럼 컴퓨터 전체에 영향을 주는 명령은 sudo(관리자 권한으로 실행하라는 뜻의 명령. 보통 내 컴퓨터 비밀번호를 묻습니다)를 앞에 붙여야 할 때가 있습니다. 에이전트가 이런 명령을 실행하려 할 때 비밀번호를 어떻게 받는지는 내가 어디에서 Hermes 를 쓰고 있느냐에 따라 다릅니다.
| 상황 | 일어나는 일 |
|---|---|
| 내가 직접 마주 보고 쓰는 대화(대화형 부모 세션) | 지원되는 sudo 명령이면 글자가 가려지는 비밀번호 입력 칸이 뜹니다. 입력한 비밀번호는 그 세션 동안 기억됩니다. |
비밀번호 없이 sudo 가 되는 컴퓨터 | 묻지 않습니다. |
| 미리 적어 두고 싶을 때 | 에이전트가 도는 컴퓨터의 프로필 .env 파일에 SUDO_PASSWORD 를 설정할 수 있습니다. |
| 위임받은 하위 에이전트 | 비밀번호 창을 열 수 없습니다(여럿이 동시에 일해, 사람에게 차례로 물을 통로가 없습니다). 그 명령은 부모 세션에서 실행하거나, SUDO_PASSWORD 를 그 컴퓨터에 마련해 둡니다. |
| 메신저 · 화면 없이 도는 세션 | 비밀번호를 안전하게 답할 통로가 없습니다. 메신저에서 sudo 가 실패하면, 출력에 SUDO_PASSWORD 를 ~/.hermes/.env 에 추가하라는 안내가 들어 있습니다. |
sudo 비밀번호를 막는 장치도 그대로 작동합니다.
비밀번호 입력 칸이 뜨는 명령 모양과 뜨지 않는 모양
알아보는 모양: 글자 그대로 적힌 절대 경로나 따옴표로 감싼 실행 파일 경로, 평범한 옵션 · 값 지정이 붙은 env 접두어(예: env -u UNUSED /usr/bin/sudo id). 알아보지 못하는 모양: 셸에 통째로 넘기는 문자열(bash -c 'sudo id'), env -S 로 쪼개는 문자열, 실행 중에 정해지는 경로, 알 수 없는 env 옵션. 입력 칸이 필요하면 sudo 를 직접 부르는 모양으로 실행하게 합니다.
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 처럼 서버 이름을 붙여 실행하면 같은 체크리스트가 지금 선택 그대로 다시 열립니다. 서버에 새로 생긴 도구를 받아들일 때도 씁니다.
카탈로그 세부 — 미리 체크되는 도구 · n8n · GitHub · 자기 OAuth 앱 · ${VAR}
| 주제 | 내용 |
|---|---|
| 위치 · 승인 · 업데이트 | 항목은 hermes-agent 저장소의 optional-mcps/ 에 있고, 거기 있다는 것이 Nous 의 승인입니다(커뮤니티 제출 등급 없음, PR 병합으로만 추가). 자동 업데이트는 없습니다 — 매니페스트(manifest — 항목의 설치 명세 파일) 버전이 바뀌면 hermes mcp install <name> 을 다시 실행합니다. 내 Hermes 가 모르는 새 manifest_version 은 ⚠ '<name>' requires a newer Hermes 로 알립니다 → hermes update. |
| 미리 체크되는 도구 | ① 예전에 고른 것(재설치는 선택을 보존) ② 매니페스트의 tools.default_enabled ③ 없으면 전부. 체크한 것만 mcp_servers.<name>.tools.include 에 적히고, 전부 고르면 필터를 적지 않습니다. 도구가 아주 많은 항목(cloudflare, 약 3,300개)은 tools.default_excluded 를 선언해 체크리스트 없이 tools.exclude 를 적습니다. 서버에 닿지 못해 목록을 못 받아도 설치는 성공하며(카드에는 “Authorized. Tools unavailable.”), 나중에 hermes mcp configure <name> 으로 다듬습니다. |
| n8n | 공식 서버 n8n-official: n8n 관리자가 Settings > Instance-level MCP 를 켬 → Connect 에서 /mcp-server/http 로 끝나는 Server URL 복사(편집기 주소 아님) → hermes mcp install n8n-official 에 입력 → 브라우저 OAuth(필요하면 hermes mcp login n8n-official) → hermes mcp configure n8n-official → 새 세션 또는 /reload-mcp. 일부 도구는 워크플로를 고치거나 실행합니다. 예전 제3자 브리지: 카탈로그에서 빠졌습니다. 기존 설치는 그대로 작동하고 선택기에 사용자 지정 항목으로 보이지만, 재설치도 공식 서버로의 이전도 되지 않습니다. |
| GitHub | 일부러 카탈로그에 넣지 않았습니다 — 호스팅형 MCP 가 클라이언트마다 자기 OAuth 앱을 요구하고, 딸려 오는 github/* 스킬(gh CLI 사용)이 더 유능한 연동이기 때문입니다. (위 예시 화면의 github 줄은 원문 예시 그대로입니다.) |
| 자기 OAuth 앱이 필요한 항목 | 동적 클라이언트 등록(DCR)이 없는 업체(예: Asana V2 https://mcp.asana.com/v2/mcp)는 업체 콘솔에서 앱을 미리 등록합니다. 설치할 때 Client ID / secret 을 묻고 프로필 .env 에 저장하며, 설정에는 oauth.client_id: "${ASANA_CLIENT_ID}" 같은 참조와 redirect_host: localhost, redirect_port: 27890 만 적습니다. 항목의 post_install 안내대로 앱에 http://localhost:27890/callback 을 등록하고 hermes mcp login <name>. 승인하는 브라우저는 Hermes 와 같은 컴퓨터에 있어야 합니다. |
${VAR} 치환 | 항목의 transport.command · args · url 과 headers 속 ${VAR} 는 연결할 때 환경 변수(~/.hermes/.env 포함)로 채워집니다. ${userHome}, ${workspaceFolder}, ${workspaceFolderBasename}, ${pathSeparator} / ${/} 도 됩니다. ${INSTALL_DIR} 는 설치 시점에 채워지는 별개 값입니다. |
추천 표시 suggest: | 매니페스트의 keywords: · hosts: 를 보고 데스크톱 앱 입력 칸이 “Add <server>” 버튼을 권합니다. 권유일 뿐이고 설치 경로는 같습니다. |
로그인이 필요한 서버 — OAuth
Cloudflare, Linear, Sentry, Atlassian, Asana, Figma, Stripe 같은 호스팅형 MCP 서버의 대부분은 고정된 토큰 대신 OAuth(비밀번호를 넘겨주지 않고, 브라우저에서 “허용”을 눌러 권한을 내주는 로그인 방식)를 요구합니다. 설정에는 auth: oauth 한 줄만 더 적으면 되고, 나머지 절차(서버 찾기, 자기소개, 토큰 받기와 갱신)는 Hermes 가 알아서 합니다.
mcp_servers:
linear:
url: "https://mcp.linear.app/mcp"
auth: oauth
| 하고 싶은 일 | 명령 |
|---|---|
| 서버에 로그인하기 · 토큰이 죽었을 때 다시 인증하기 | hermes mcp login <server> (예: hermes mcp login figma) |
| 카탈로그에서 설치한 뒤 로그인하기 | hermes mcp install figma → hermes mcp login figma |
~/.hermes/config.yaml 을 고치면 CLI 가 MCP 연결을 자동으로 다시 읽지만, 기다려 주는 시간이 30초뿐이라 브라우저 로그인에는 모자랍니다. 항목을 추가한 뒤 새 터미널에서 hermes mcp login <server> 를 실행하면 5분을 기다려 줍니다.
Hermes 가 내 브라우저와 다른 컴퓨터(원격 서버 등)에서 돌고 있으면, 브라우저의 응답이 Hermes 에 닿지 못합니다. 원문은 이때 쓸 방법 다섯 가지와 자주 걸리는 함정을 적어 두었습니다 — 아래 접힌 상자에 옮겼습니다.
OAuth 세부 — 다른 컴퓨터에서 마치는 방법 · 함정 · 서버별 예외
| 주제 | 내용 |
|---|---|
| 방법 1: Desktop (자동) | 데스크톱 앱의 MCP 설정 화면에서 원격 백엔드에 로그인하면 데스크톱이 응답을 받아 전달합니다(앱 · 백엔드 모두 최신이어야 함). |
| 방법 2: 붙여 넣기 | 터미널에 “Or paste the redirect URL here…” 가 나오면, 브라우저에서 승인한 뒤 마지막에 도착한 전체 주소(연결 오류 화면이 정상)를 붙여 넣습니다. |
| 방법 3: 기기 코드 | hermes mcp login <server> --flow device — 출력된 주소를 아무 기기에서 열어 짧은 코드를 넣습니다(서버가 지원할 때). 기본 방식으로 두려면 oauth.flow: device. |
| 방법 4: SSH 포트 포워딩 | 다른 터미널에서 ssh -N -L <port>:127.0.0.1:<port> user@host. |
| 방법 5: 프록시된 콜백 | 공개 HTTPS 주소가 콜백 포트로 전달해 주면 oauth.redirect_port 와 oauth.redirect_uri 를 설정합니다. 터미널이 아예 없는 게이트웨이는 선택 스킬 mcp-oauth-remote-gateway 가 안내합니다(공식 문서 OAuth over SSH / Remote Hosts). |
함정: 127.0.0.1 거절 | 일부 제공자의 방화벽(WAF)이 주소에 127.0.0.1 이 든 요청을 403 으로 막습니다(예: Reclaim.ai) → oauth.redirect_host: localhost. |
| 함정: 자동 등록 미지원 | Google Drive(https://drivemcp.googleapis.com/mcp/v1) · Atlassian 등은 클라이언트 자동 등록을 거절합니다. 도구 목록은 보여 성공한 듯하지만 실제 호출은 모두 시간 초과됩니다. hermes mcp login 이 알려 주면, 제공자 콘솔에서 만든 oauth.client_id · oauth.client_secret 을 설정에 넣고 다시 로그인합니다. |
| 기다리는 시간 | 5분보다 더 필요하면 oauth.timeout(초). 넘기면 Connecting to MCP server '<name>' timed out after Ns. |
| 토큰 보호 | Hermes 는 OAuth 2.1 절차(서버 찾기 · 클라이언트 식별 · PKCE · 토큰 교환 · 갱신)를 자동 처리합니다. 갱신 토큰은 발급한 인증 서버에 묶여, 인증 서버가 바뀌면 보내지 않고 버립니다. 돌아오는 응답의 iss(RFC 9207)와 메타데이터 문서의 주인(RFC 8414 — 어긋나면 Authorization server metadata issuer mismatch)도 확인합니다. |
| 서버별 예외 | Figma: “Hermes Agent” 라는 이름이 403 으로 거절되므로 mcp.figma.com 에는 oauth.client_name: "Claude Code" 를 자동 설정합니다. Google(Gmail · Calendar): 갱신 토큰을 받도록 access_type=offline 과 prompt=consent 를 덧붙입니다. Strava: 경로가 붙은 메타데이터 문서 모양을 예외로 받아 줍니다. |
연결된 뒤 일어나는 일 — 이름 · 찾기 · 다시 읽기
MCP 서버를 연결하면 Hermes 는 그 서버의 도구를 자기 도구 목록에 올립니다. 이때 내장 도구와 이름이 겹치지 않도록 앞에 서버 이름을 붙입니다.
mcp_<server_name>_<tool_name>
이름 속의 - 나 . 는 _ 로 바뀝니다. 보통은 이 이름을 직접 부를 일이 없습니다 — Hermes 가 도구를 보고 알아서 고릅니다.
| 서버 | 서버 쪽 도구 이름 | Hermes 에 등록되는 이름 |
|---|---|---|
filesystem | read_file | mcp_filesystem_read_file |
github | create-issue | mcp_github_create_issue |
my-api | query.data | mcp_my_api_query_data |
연결된 서버가 움직이는 방식은 아래 표로 정리됩니다. 초보자가 기억할 것은 한 줄입니다 — MCP 설정을 바꿨으면 /reload-mcp.
| 언제 | 일어나는 일 |
|---|---|
| Hermes 를 시작할 때 | MCP 서버를 찾아 연결하고 도구를 일반 도구 목록에 등록합니다. 한 번에 최대 4개씩 연결합니다. |
| 설정을 바꿨을 때 | 대화 입력 칸에 슬래시 명령(/ 로 시작하는 명령 — 2장) /reload-mcp 를 넣습니다. 설정에서 MCP 서버를 다시 읽고 도구 목록을 새로 고칩니다. |
| 서버가 스스로 도구를 바꿨을 때 | 서버가 “도구 목록이 바뀌었다”고 알리면 Hermes 가 자동으로 목록을 다시 받아 옵니다. /reload-mcp 가 필요 없습니다. |
| 메신저 게이트웨이(메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램 — 8장)가 돌고 있을 때 | 게이트웨이가 config.yaml 을 스스로 지켜봅니다. 서버 항목을 지우거나 끄면 약 1분 안에 그 연결을 끊고, 새로 추가한 항목은 연결합니다. 다시 시작할 필요가 없습니다. |
| 서버가 도구를 하나라도 등록했을 때 | 그 서버 몫의 툴셋 mcp-<server> 가 생깁니다. 툴셋 단위로 서버를 다루기 쉬워집니다(툴셋). |
도구 말고도, 서버가 지원하면 MCP 의 자료(resources)와 프롬프트(prompts)를 다루는 보조 도구 네 개가 서버마다 같은 이름 규칙으로 붙습니다: list_resources, read_resource, list_prompts, get_prompt(예: mcp_github_list_resources, mcp_github_get_prompt). 서버가 실제로 그 기능을 지원할 때만 등록되므로, 부를 수 있는 도구만 내놓는 서버에는 붙지 않습니다.
연결 뒤 세부 — 동시 연결 수 · 지연 시작 · 재시도 · 결과 다듬기
| 주제 | 내용 |
|---|---|
| 동시 연결 수 | 찾기 한 번(시작, /reload-mcp, 설정 감시)에 최대 4개씩 — stdio 서버를 한꺼번에 띄우면 CPU · 메모리가 치솟기 때문입니다. mcp.discovery_concurrency(기본 4, 0 = 제한 없음). 차례마다 120초, 전체 300초 한도. |
지연 시작 lazy: true | 저장해 둔 도구 목록으로 먼저 등록하고 첫 도구 호출 때 실행 · 접속합니다. 화면의 3 tool(s) (lazy, starts on first use) 는 고장이 아닙니다. |
| 동적 도구 찾기 | 서버의 notifications/tools/list_changed 알림에 목록을 다시 받습니다. 프롬프트 · 자료 변경 알림에는 아직 반응하지 않습니다. |
/reload-mcp 의 다른 쓰임 | 세션 도중에 생긴 자격 증명 · 데몬(Docker, HASS_TOKEN, OAuth …)으로 켜지는 도구를 다시 살핍니다. 그 밖에는 /new 나 맥락 압축 때만 반영됩니다. |
| 재시도 · 만료된 토큰 | 게이트웨이는 첫 연결에 실패한 서버를 30초부터 두 배씩(최대 10분) 간격으로 다시 시도합니다. 뒤에서는 브라우저를 열지 않으므로, 갱신 토큰이 죽으면 gateway.log 에 경고를 남기고 멈춰 섭니다 → hermes mcp login <server> 로 한 번 다시 인증. |
| 결과 다듬기 | 화면에는 안 보이지만 모델에는 보이는 유니코드 TAG 문자(U+E0000–U+E007F)를 결과 · 자료 · 도구 설명에서 걷어 냅니다(몰래 지시를 넣는 통로). 서버가 붙인 업체용 _meta 는 모델에 넘기고 규격 예약 키는 버립니다. |
| 이미지 결과 | 이미지는 캐시에 저장되고 경로가 MEDIA:/path/to/image.png 로 적힙니다. 주 모델이 이미지를 볼 수 있으면 줄여서(결과당 최대 4장) 함께 붙입니다(공식 문서 Vision 쪽 참고). |
| 프록시 | HTTP · SSE 서버는 HTTPS_PROXY / HTTP_PROXY / ALL_PROXY, 그다음 운영체제 프록시를 따르고 NO_PROXY 의 호스트는 바로 연결합니다. |
필요한 도구만 보이게 — 서버별 걸러 내기
MCP 서버는 도구를 수십 개에서 많게는 수천 개까지 내놓습니다. 전부 받아들이면 에이전트의 도구 목록이 복잡해지고, “고객 삭제” 같은 위험한 도구까지 손에 쥐여 주게 됩니다. 그래서 Hermes 는 서버마다 어떤 도구를 받아들일지 정할 수 있게 합니다. 가장 쉬운 방법은 hermes mcp configure <서버 이름> 의 체크리스트이고(추가하기), 같은 일을 설정 파일의 tools 항목으로도 합니다.
| 하고 싶은 일 | 서버 항목 아래에 적는 것 | 결과 |
|---|---|---|
| 서버를 통째로 끄기 | enabled: false | 그 서버를 완전히 건너뜁니다. 연결조차 시도하지 않습니다. |
| 허용 목록 — 적은 것만 받기 | tools: 아래 include: [create_issue, list_issues] | 적힌 도구만 등록됩니다. |
| 제외 목록 — 적은 것만 빼기 | tools: 아래 exclude: [delete_customer] | 적힌 것을 뺀 나머지가 모두 등록됩니다. |
| 보조 도구 끄기 | tools: 아래 prompts: false / resources: false | list_prompts · get_prompt / list_resources · read_resource 를 끕니다. |
mcp_servers:
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
tools:
include: [create_issue, list_issues, search_code]
prompts: false
stripe:
url: "https://mcp.stripe.com"
headers:
Authorization: "Bearer ***"
tools:
exclude: [delete_customer]
resources: false
legacy:
url: "https://mcp.legacy.internal"
enabled: false
뜻: github 서버에서는 도구 세 개만 받고 프롬프트 보조 도구는 끕니다. stripe 서버에서는 고객 삭제만 빼고 자료 보조 도구는 끕니다. legacy 서버는 아예 연결하지 않습니다. 알아 둘 규칙은 세 가지입니다.
- 둘 다 적으면
include가 이깁니다. 같은 도구가 양쪽에 있어도 허용 목록이 우선합니다. - 이름에 별표 패턴을 쓸 수 있습니다.
include: ["*_dns_*"]는 이름에_dns_가 든 도구를 모두 받습니다. 패턴 문자(*,?,[)가 없는 이름은 글자 그대로만 맞습니다 —docs는docs만 빼고docs_search는 건드리지 않습니다. - 전부 걸러지면 툴셋도 생기지 않습니다. 부를 수 있는 도구도 보조 도구도 남지 않은 서버에는 빈
mcp-<server>툴셋을 만들지 않아 목록이 깔끔하게 유지됩니다.
원문의 쓰임새 예시 세 가지 · 글롭 패턴 예
| 예시 | 설정 요점 | 부탁하는 말 |
|---|---|---|
| 이슈 관리만 하는 GitHub 서버 | include: [list_issues, create_issue, update_issue], prompts: false, resources: false | Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior.뜻: bug 라벨이 붙은 열린 이슈를 보여 주고, 불안정한 MCP 재연결 문제로 새 이슈 초안을 써 줘. |
| 위험한 동작을 뺀 Stripe 서버 | exclude: [delete_customer, refund_payment] | Look up the last 10 failed payments and summarize common failure reasons.뜻: 최근 실패한 결제 10건을 찾아 흔한 실패 이유를 요약해 줘. |
| 프로젝트 폴더 하나만 여는 파일 시스템 서버 | args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"] (서버 이름 project_fs) | Inspect the project root and explain the directory layout.뜻: 프로젝트 맨 위 폴더를 살펴보고 폴더 구성을 설명해 줘. |
글롭은 fnmatch 방식이고 대소문자를 구분합니다. 도구가 약 3,300개인 Cloudflare API MCP(https://mcp.cloudflare.com/mcp?codemode=false)가 예입니다: exclude: ["*_radar_*", "*_accounts_dlp_*", "*_zones_web3_*"].
MCP 를 안전하게 쓰기
MCP 서버는 남이 만든 프로그램이고, 그 도구는 내 계정과 자료에 손을 댑니다. Hermes 가 해 주는 보호와 내가 챙길 일을 나누어 봅니다.
| 걱정 | Hermes 가 하는 일 | 내가 할 일 |
|---|---|---|
| 내 컴퓨터의 비밀 값이 서버로 새는 것 | stdio 서버에 내 셸의 환경 변수(프로그램에 넘겨주는 이름표 달린 값 — API 키가 여기 들어 있곤 합니다)를 통째로 넘기지 않습니다. 설정의 env 에 적은 것과 안전한 기본값만 넘깁니다. | 서버에 꼭 필요한 값만 env 에 적습니다. |
| 에이전트가 위험한 도구를 쓰는 것 | 걸러 내기 설정으로 보이는 도구를 제한합니다. | 위험한 도구는 빼고, 민감한 서버는 최소한의 허용 목록만 둡니다. 자료 · 프롬프트 보조 도구도 필요 없으면 끕니다(걸러 내기). |
| 설치할 때 남의 코드가 실행되는 것 | 카탈로그 항목은 Nous 가 PR 검토를 거쳐 받아들인 것만 실립니다. 선택기는 설치할 때 항목의 출처 주소를 보여 줍니다. | 그래도 설치 전에 매니페스트(항목의 설치 명세 파일)를 읽습니다 — 특히 출처 저장소(source:), 설치 명령(install.bootstrap:), 실행 명령(transport.command:). |
| 위험한 명령의 실행 | MCP 와 별개로, 위험한 명령 앞에서 묻는 승인 절차가 있습니다 — 9장. | |
신뢰 모델 세부 — 매니페스트는 어디서 보나
설치하면 매니페스트가 정한 git clone, 준비 명령(pip install, npm install 등), MCP 서버의 코드가 실행됩니다. 매니페스트는 GitHub 의 optional-mcps/<name>/manifest.yaml 에 있고, 웹 대시보드의 MCP 화면도 항목마다 연결 방식 · 인증 종류 · 접속 주소나 명령 · 설치 출처와 준비 명령을 보여 줍니다(source: 는 누를 수 있는 링크).
고급 기능과 설정 키 (필요할 때만)
서버를 운영하거나 회사 환경에 맞추는 사람을 위한 내용입니다. 이런 기능이 있다는 것만 표로 훑어보고, 필요할 때 접힌 상자를 펼칩니다.
| 기능 | 무엇을 하나 | 설정 · 명령 |
|---|---|---|
| 병렬 도구 호출 | 기본은 MCP 도구를 한 번에 하나씩 실행합니다. 동시에 돌려도 안전한 서버(읽기 전용 조회 등)만 한꺼번에 실행하게 켭니다. 같은 파일 · 데이터베이스를 읽고 쓰는 도구라면 충돌을 먼저 따져 봅니다. | supports_parallel_tool_calls: true |
| 샘플링 (Sampling) | MCP 서버가 Hermes 의 모델에게 글 생성을 부탁하는 기능 — 자체 모델이 없는 서버용. 기본으로 켜져 있고, 믿기 어려운 서버에는 끕니다. | sampling: 아래 enabled: false |
| 도구 비용과 지출 한도 | 호출마다 돈이나 크레딧이 드는 서버(이미지 · 영상 생성, 유료 API)에 도구별 비용과 대화당 한도를 적어 둡니다. 승인 창에 비용이 표시되고, 한도를 넘길 호출은 먼저 묻습니다. | tool_costs, spend_limit, cost_unit |
| Elicitation (도중에 되묻기) | 서버가 도구 실행 도중 나에게 값을 물어봅니다. 질문은 평소의 승인 화면(CLI 의 입력 창, 메신저의 버튼)으로 옵니다. 기본으로 켜져 있습니다. | elicitation: |
| Events 실험 기능 | 서버 쪽에서 일이 생기면(새 메일, 장애 등) 게이트웨이로 알려 와 에이전트 실행을 시작합니다. | events: true |
| mTLS 클라이언트 인증서 | 인증서로 서로를 확인하는 원격 서버에 접속합니다. | client_cert, client_key |
| 사용자 신원 헤더 | 요청마다 “누가 부르는지”를 알리는 헤더를 붙입니다(사용자별 한도 · 감사 기록 · 여러 조직을 나누는 서버용). | identity_header |
| 메모리를 많이 쓰는 서버 재활용 | 브라우저 기반 서버처럼 메모리를 붙잡는 stdio 서버를 쉬는 동안 내렸다가 다음 호출 때 다시 띄웁니다(도구 등록은 유지). | idle_timeout_seconds, max_lifetime_seconds |
| 내장 프리셋 | 잘 알려진 서버의 실행 명령을 대신 채워 줍니다(원문에 있는 것은 Codex CLI 하나). | hermes mcp add codex --preset codex |
| Hermes 를 MCP 서버로 실행하기 | 거꾸로, Claude Code · Claude Desktop · Cursor · Codex 같은 MCP 클라이언트가 Hermes 의 메신저 대화를 읽고 보내며, 원하면 Hermes 의 도구도 쓰게 합니다. | hermes plugins install mcp-serve |
설정 키 전체 (Basic configuration reference — mcp_servers 아래 서버마다)
| 키 | 형식 | 뜻 |
|---|---|---|
command / args / env | 글자 / 목록 / 묶음 | stdio 서버의 실행 파일, 인자, 넘겨줄 환경 변수 |
cwd | 글자 | stdio 서버의 작업 폴더. 기본은 세션 작업 폴더가 고정돼 있으면(ACP/게이트웨이 세션, terminal.cwd) 그것, 아니면 Hermes 프로세스의 폴더 |
url / headers | 글자 / 묶음 | HTTP MCP 주소, 원격 서버에 보낼 HTTP 헤더 |
client_cert / client_key | 글자 또는 목록 / 글자 | mTLS 용 인증서 — 합친 PEM 파일 하나, [cert, key], 또는 [cert, key, password]. 열쇠가 따로면 client_key. 파일이 없으면 서버 이름이 든 오류 |
identity_header | 묶음 | {name, value_from: static|profile, value} — static 은 적은 값, profile 은 지금 프로필 이름. headers 에 같은 이름이 있으면 그쪽이 우선. stdio 에서는 경고 후 무시 |
timeout / connect_timeout | 숫자 | 도구 호출 제한 시간 / 첫 연결 제한 시간 |
lazy | 참 · 거짓 | 참이면 첫 도구 호출 때 연결(기본 거짓). 한 번은 실제로 연결된 적이 있어야 함 |
idle_timeout_seconds / max_lifetime_seconds | 숫자 | 호출 없이 / 띄운 지 이만큼 지나면 stdio 서버를 내렸다가 다음 호출 때 다시 띄움(0 = 안 함, 기본). 예: @playwright/mcp 에 900 과 86400 |
enabled | 참 · 거짓 | 거짓이면 서버를 통째로 건너뜀 |
supports_parallel_tool_calls | 참 · 거짓 | 참이면 이 서버의 도구를 동시에 실행할 수 있음 |
events | 참 · 거짓 | 참이면 실험 기능인 이벤트 도구를 등록(기본 거짓) |
tools | 묶음 | 서버별 도구 걸러 내기와 보조 도구 설정 |
표에 없지만 원문 다른 곳에 나오는 키: auth, oauth, transport, sampling, elicitation, trust, tool_costs, spend_limit, cost_unit. 프리셋 codex 는 command: "codex", args: ["mcp-server"] 를 적어 줍니다(codex CLI 필요, 서버 이름은 자유).
고급 기능 세부 — 샘플링 · 비용 한도 · Elicitation · Events · Hermes 를 MCP 서버로
| 기능 | 세부 |
|---|---|
| 샘플링 | 서버가 sampling/createMessage 로 요청합니다. sampling: 아래 값(기본): enabled(true), model(바꿔 쓸 모델, 선택), max_tokens_cap(4096), timeout(30초), max_rpm(분당 10회), max_tool_rounds(5), allowed_models(빈 목록 = 아무 모델), log_level(info). 요청 수 · 오류 · 토큰 사용량을 서버별로 셉니다. |
| 비용 · 지출 한도 | 예: tool_costs: {create_image: 20}(범위는 {credits: [5, 20], note: "per animation"}), spend_limit: 100(대화당. 0 이나 생략 = 한도 없음), cost_unit: credits. 승인 창에 Costs about 20 credits. 처럼 표시됩니다. Hermes 는 승인해 시작한 호출의 선언 비용(범위면 위쪽 값)을 대화 · 서버별로 메모리에 합산합니다 — 업체 청구서가 아니라 대화 한 번의 예산입니다. 새 대화(/new)는 새 합계로 시작하고(메신저에서는 /new 뒤에도 유지), 예약 작업은 실행마다 따로, Hermes 를 다시 시작하면 0 이 됩니다. 한도를 넘길 호출은 trust: full 서버나 YOLO · approvals.mode: off 에서도 먼저 묻고(Allow Once / Deny 만), 답할 사람이 없는 곳(예약 작업, hermes chat -q)에서는 거절합니다. tool_costs 에는 mcp_<server>_ 접두어 없는 서버 쪽 도구 이름을 씁니다. |
| Elicitation | elicitation/create(mcp Python SDK 1.11.0 이상). 양식 방식만 지원하고, 외부 주소로 보내는 방식은 거절합니다. 답은 Allow Once / Deny 뿐이며 YOLO 와 approvals.mode: off 가 대신 답하지 않습니다(허락이 아니라 질문이므로). elicitation: 아래 enabled(true), timeout(300초). |
| Events | 아직 초안인 규격의 웹훅 전달 방식만 구현했습니다. 서버 항목에 events: true, 그리고 platforms.webhook 을 켜고 extra.public_url 에 공개 HTTPS 주소를 적습니다(포트 8644 앞에 TLS 프록시나 터널). 보조 도구 list_event_types · subscribe_event(사람 없이 에이전트를 실행시키므로 구독마다 승인) · unsubscribe_event 가 생깁니다. 구독은 hermes webhook list 에 보이고, 이벤트는 hermes gateway run 이 돌 때만 도착합니다(내용은 JSON 32,000자까지, 기본 분당 30회 제한). poll · push 방식과 gateway.multiplex_profiles 의 보조 프로필 구독은 아직 지원하지 않습니다. |
| Hermes 를 MCP 서버로 | 공식 플러그인 mcp-serve. MCP 클라이언트 설정에 "command": "hermes", "args": ["mcp-serve"] 를 적습니다. 예전의 내장 명령 hermes mcp serve(["mcp", "serve"])는 이 표기로 바꿉니다 — 도구 이름 · 인자는 그대로입니다. 도구 목록과 안전 한도는 플러그인 README 참고. |
MCP 가 안 될 때
대부분은 “서버가 안 붙었다”와 “붙었는데 도구가 안 보인다” 둘 중 하나입니다.
| 서버가 안 붙을 때 | 확인할 것 |
|---|---|
| 서버가 연결되지 않음 | 터미널에서 node --version, npx --version 이 버전을 출력하는지 봅니다. 그다음 설정을 확인하고 Hermes 를 다시 시작합니다. 어느 서버가 왜 실패했는지는 agent.log 의 시작 요약 한 줄에 적힙니다. |
| 원격(HTTP) 서버가 거절 | hermes mcp test <name> 이 서버의 실제 응답을 보여 줍니다. 400 / 405: 그 주소가 SSE 방식만 받거나(transport: sse 설정) 앞단 프록시가 거절. 401 / 403: 토큰이나 OAuth 권한이 잘못됨. HTML 이 돌아옴: 주소가 웹 페이지를 가리킴. |
| 로그인(OAuth)이 풀림 · 시간 초과 | 새 터미널에서 hermes mcp login <server> — 로그인이 필요한 서버. |
| 붙었는데 이상할 때 | 확인할 것 |
|---|---|
| 도구가 보이지 않음 | 원인은 다섯 가지 중 하나입니다: 서버 연결 실패, 도구 찾기 실패, 걸러 내기 설정이 그 도구를 뺌, 그 보조 기능이 서버에 없음, enabled: false. 일부러 걸러 냈다면 정상입니다. |
| 자료 · 프롬프트 보조 도구만 안 보임 | 설정이 허용하고 동시에 서버가 그 기능을 지원할 때만 등록됩니다. 의도된 동작입니다. |
| 서버 응답이 너무 큼 | 응답 하나는 10 MiB 까지 받습니다. 옛 SSE 방식(transport: sse)은 이벤트당 1 MiB 로 묶여 있으니, 서버가 Streamable HTTP 도 지원하면 그 줄을 지웁니다. |
로그에서 보이는 모양 · 의존성 확인 명령
MCP: registered 116 tool(s) from 4 server(s) (2 failed: github (Connection closed); notion (HTTP 401 from POST https://mcp.notion.com/mcp))
뜻: 서버 4개에서 도구 116개 등록, 2개 실패(github 는 연결이 닫힘, notion 은 HTTP 401). 앞선 실패의 재시도 대기 중이라 건너뛴 서버는 not attempted (in retry cooldown) 로 나옵니다.
hermes mcp test 는 오류에 HTTP 상태, 요청한 주소, 응답 앞부분을 덧붙여 줍니다(예: HTTP 400 from POST http://host:27200/mcp 와 Unsupported MCP-Protocol-Version). hermes logs --level debug 는 연결 시도마다 쓴 정확한 주소를 보여 줍니다. MCP 의존성(표준 설치에 이미 포함)을 다시 맞추는 원문의 명령은 cd ~/.hermes/hermes-agent && python -c "import pm; pm.sync_venv(['mcp'], explicit=True)" 입니다. 그 밖의 문제는 10장.
- 도구는 에이전트의 손입니다. 웹 검색 · 터미널 · 파일 · 기억 등이 내장돼 있고, 플러그인과 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), 설치 전에는 무엇이 실행되는지 읽어 봅니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/features/tools · hermes-agent.nousresearch.com/docs/user-guide/features/mcp — 2026-11-09 수집한 공식 문서 기준(문서에 버전 표기 없음). 원문 끝의 관련 문서(Use MCP with Hermes · CLI Commands · Slash Commands · FAQ)와 본문이 가리키는 참고 쪽은 받지 않은 것은 다루지 않았습니다.
기억 · 맥락 파일 · 성격
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 도구를 써서 내 대신 일을 해 주는 AI 프로그램)는 대화가 끝나도 나와 내 프로젝트를 잊지 않도록 네 가지 장치를 씁니다. 스스로 적는 기억, 프로젝트 폴더에 두는 맥락 파일, 기본 성격을 정하는 SOUL.md, 잠깐 말투를 바꾸는 /personality 입니다. 이 장에서는 넷이 각각 무엇이고 어떻게 다른지, 무엇을 어디에 적어야 하는지를 차례로 봅니다.
- 기억 · 맥락 파일 · SOUL.md · /personality 네 가지가 서로 어떻게 다른지
- 기억 파일 두 개(MEMORY.md · USER.md)에 무엇이 적히고 언제 읽히는지
- “기억하라고 했는데 다음에 잊어버렸다”를 차례로 확인하는 방법
- 지난 대화를 찾는 session_search 와 배운 것을 돌아보는 /journey
- AGENTS.md 같은 맥락 파일이 어떤 순서로 읽히는지
- SOUL.md 에 적을 것과, /personality 로 말투를 잠깐 바꾸는 방법
- 수상한 지시문을 걸러 내는 보안 검사
- 기억이란 — 세션이 끝나도 남는 메모 두 장. 언제 적히고 언제 읽히는지.
- 맥락 파일 — 프로젝트 폴더에 두면 알아서 읽는 안내문.
- SOUL.md — Hermes 의 기본 성격과 말투를 정하는 파일.
설정 키·도구 동작·크기 한도 같은 세부는 접힌 상자(🔧)에 있습니다. 필요해질 때 펼쳐 보면 됩니다.
먼저 구분하기 — 네 가지 장치
이 장의 네 가지는 모두 시스템 프롬프트(system prompt — 대화가 시작될 때 모델이 가장 먼저 읽는 지시문 묶음)에 들어가 Hermes 의 답에 영향을 줍니다. 그래서 헷갈리기 쉽습니다. 차이는 “누가 쓰는가, 어디에 있는가, 얼마나 오래 가는가” 세 가지입니다.
| ① 기억 | ② 맥락 파일 | ③ SOUL.md | ④ /personality | |
|---|---|---|---|---|
| 누가 쓰나 | Hermes 가 스스로 (memory 도구) | 나, 또는 프로젝트를 함께 쓰는 사람 | 나 (없으면 Hermes 가 기본 파일을 만들어 둠) | 내장 14종에서 고르거나 설정에 직접 추가 |
| 어디에 있나 | ~/.hermes/memories/ | 프로젝트 폴더 안 (AGENTS.md 등) | ~/.hermes/SOUL.md 한 곳 | 파일이 아니라 슬래시 명령(/ 로 시작하는 명령) |
| 언제 읽히나 | 세션(대화 한 묶음) 시작 때 한 번 | 세션 시작 때, 하위 폴더 것은 Hermes 가 그 폴더를 건드릴 때 | 세션 시작 때, 맨 첫 자리에 | 명령으로 켠 뒤 |
| 어디까지 적용 | 같은 프로필(별도 Hermes 환경)이면 어느 폴더에서든 | 그 프로젝트에서만 | 어느 폴더에서든 | 지금 대화에 덧씌움 (원문 표현: 세션 단위) |
| 무엇을 담나 | 환경 사실, 내 취향, 배운 요령 | 프로젝트 구조, 규칙, 명령·포트·경로 | 말투, 소통 방식, 피할 표현 | teacher·concise 같은 말투 한 가지 |
| 자세히 | 기억이란 | 맥락 파일 | SOUL.md | /personality |
고르는 기준은 간단합니다. 나를 따라다녀야 하면 SOUL.md, 프로젝트에 속하면 AGENTS.md, Hermes 가 일하다 알게 된 것은 기억입니다. 원문은 기억에 대해 “SOUL.md 와 AGENTS.md 에 이미 있는 내용은 기억에 저장하지 않는다”고도 적습니다.
기억이란 — 세션이 끝나도 남는 메모
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 환경)을 주고, 기억을 함께 써야 한다면 외부 기억 제공자를 씁니다.
더 보기: 수첩이 꽉 차면 · 저장한 줄 알았는데 잊었다면.
두 칸 — 에이전트 메모와 사용자 소개
기억은 두 칸으로 나뉩니다. 원문은 이 칸을 target(대상 — 어느 파일에 적을지)이라고 부르고, 이름은 memory 와 user 입니다. Hermes 가 기억을 적을 때마다 둘 중 하나를 고릅니다.
memory — 에이전트의 개인 메모
MEMORY.md · 2,200자 · 보통 8~15개 — 환경, 일하는 방식, 배운 교훈
- 환경 사실 (운영 체제, 도구, 프로젝트 구조)
- 프로젝트 규칙과 설정
- 도구의 별난 점과 찾아낸 우회 방법
- 끝낸 작업의 기록
- 잘 통했던 스킬(일하는 방법을 적은 설명서)과 요령
user — 사용자 소개
USER.md · 1,375자 · 보통 5~10개 — 내가 누구이고 무엇을 좋아하는지
- 이름, 역할, 시간대
- 소통 취향 (짧게/자세히, 선호하는 형식)
- 거슬려 하는 것, 피해야 할 것
- 일하는 습관
- 기술 수준
hermes -p work)도 있습니다. 헷갈리지 않도록 이 가이드는 USER.md 를 사용자 소개라고 부르고, “프로필”은 별도 Hermes 환경에만 씁니다.
무엇을 저장하고 무엇을 건너뛰나
원문은 “에이전트가 자동으로 저장하므로 부탁할 필요가 없다”고 적습니다. Hermes 는 아래 같은 것을 알게 되면 스스로 적습니다.
| 종류 | 원문 예시 (뜻) | 적는 칸 |
|---|---|---|
| 내 취향 | “I prefer TypeScript over JavaScript” (JavaScript 보다 TypeScript 가 좋아요) | user |
| 환경 사실 | “This server runs Debian 12 with PostgreSQL 16” (이 서버는 Debian 12, PostgreSQL 16) | memory |
| 바로잡아 준 것 | “Don't use sudo for Docker commands, user is in docker group” (Docker 명령에 sudo 를 쓰지 말 것) | memory |
| 규칙 | “Project uses tabs, 120-char line width, Google-style docstrings” (탭 사용, 한 줄 120자 등) | memory |
| 끝낸 일 | “Migrated database from MySQL to PostgreSQL on 2026-01-15” (2026-01-15 에 DB 를 옮김) | memory |
| 직접 부탁한 것 | “Remember that my API key rotation happens monthly” (API 키를 매달 바꾼다는 걸 기억해 줘) | memory |
반대로 아래는 저장하지 않습니다. 수첩이 작기 때문입니다.
뻔하거나 막연한 것
“사용자가 Python 에 대해 물었다” — 너무 막연해서 쓸모가 없습니다.
다시 찾기 쉬운 사실
“Python 3.12 는 f-string 중첩을 지원한다” — 웹에서 찾으면 됩니다.
통째로 붙인 자료
긴 코드, 로그 파일, 데이터 표 — 기억에 넣기엔 너무 큽니다.
그 세션에만 쓰는 것
임시 파일 경로, 한 번뿐인 문제 해결 과정.
맥락 파일에 이미 있는 것
SOUL.md 와 AGENTS.md 의 내용은 어차피 읽히므로 다시 적지 않습니다.
똑같은 내용을 두 번 적으려 하면 자동으로 걸러집니다. 이때 도구는 오류가 아니라 “중복이라 추가하지 않음”이라는 성공 응답을 돌려줍니다.
memory 도구의 동작 — add · patch · remove
| 동작 | 하는 일 |
|---|---|
add | 새 항목을 추가합니다 |
patch | 기존 항목 안의 한 구간만 바꾸고 나머지는 둡니다 (old_text 가 바꿀 구간, content 가 새 글) |
remove | 더는 필요 없는 항목을 지웁니다 (old_text 로 찾음) |
- read 는 없습니다 — 기억은 세션 시작 때 시스템 프롬프트에 자동으로 들어가기 때문입니다.
- 호출마다 맨 위에
target("memory"또는"user")이 필요하고, 한 묶음(batch)의 모든 작업에 그 하나가 적용됩니다. 없거나 null 이거나 작업 안의 target 과 다르면 쓰기 전에 오류가 납니다. 두 칸을 모두 고치려면 호출을 나눕니다.
{"target": "user", "operations": [{"action": "add", "content": "User prefers metric units"}]}
일부 글자만 맞추기(Substring Matching) — patch·remove 의 old_text 는 항목 전체가 아니라, 항목 하나만 가리키는 짧은 글자열이면 됩니다. 여러 항목에 맞으면 더 구체적으로 쓰라는 오류가 납니다.
# If memory contains "User prefers dark mode in all editors"
memory(action="patch", target="memory",
old_text="dark mode in all editors",
content="light mode in VS Code, dark mode in terminal")
# -> "User prefers light mode in VS Code, dark mode in terminal"
- 바꿀 구간이 그 항목 안에 두 번 이상 나오면 거부됩니다(앞뒤 글을 더 붙여 다시 시도). 글을 빼려면 그 글을 포함한 더 긴 구간을 patch 하고, 항목 전체를 다시 쓰려면 항목 전체를
old_text로 넘깁니다. replace는 없습니다 — 항목 전체를 덮어써 한 항목에 든 다른 사실까지 지우는 일이 있었기 때문입니다. 호출하면patch를 쓰라는 오류가 돌아옵니다.
용량 — 수첩이 꽉 차면
기억에는 엄격한 글자 수 한도가 있습니다. 시스템 프롬프트가 한없이 커지지 않게 하고, 기억을 중요한 것에 집중시키기 위해서입니다.
한도는 memory 칸 2,200자(보통 항목 8~15개), user 칸 1,375자(보통 5~10개)입니다. 지금 얼마나 찼는지는 시스템 프롬프트의 머리말([67% — 1,474/2,200 chars])에 늘 표시됩니다. 원문은 80% 를 넘으면 새로 적기 전에 항목을 합쳐 정리하라고 권합니다.
기억은 저절로 줄어들지 않습니다. 한도를 넘는 쓰기가 들어오면 항목을 조용히 버리는 대신 오류를 돌려주고, Hermes 가 직접 자리를 만듭니다.
① 새 항목을 적으려 합니다
예: 지금 2,100/2,200자인데 250자짜리 항목을 추가하려 합니다.
② 도구가 오류를 돌려줍니다
“이 항목을 더하면 한도를 153자 넘는다”는 내용과 함께, 지금 들어 있는 항목 목록과 사용량을 알려 줍니다. 아무것도 몰래 지우지 않습니다.
③ Hermes 가 같은 차례에 자리를 만듭니다
낡은 항목을 지우거나 줄이는 작업과 새 항목을 더하는 작업을 한 묶음으로 다시 보냅니다. 한도는 그 묶음의 최종 결과에만 검사합니다.
④ 저장 완료
최종 결과가 한도 안이면 저장됩니다. 예를 들어 “프로젝트는 X 를 쓴다” 같은 항목 세 개를 프로젝트 설명 한 항목으로 합치는 식입니다.
좋은 항목은 짧고 정보가 촘촘한 항목입니다. 원문 예시를 봅니다.
# Good: Packs multiple related facts
User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings.
# Good: Specific, actionable convention
Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions.
# Good: Lesson learned with context
The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519.
뜻: ① 서로 관련된 사실 여럿을 한 항목에 담음(운영 체제·설치된 도구·편집기) ② 구체적이고 바로 쓸 수 있는 규칙(쓰는 언어, 테스트 실행 명령) ③ 사정과 함께 적은 교훈(이 서버는 22번이 아니라 2222번 포트).
# Bad: Too vague
User has a project.
# Bad: Too verbose
On January 5th, 2026, the user asked me to look at their project which is
located at ~/code/api. I discovered it uses Go version 1.22 and...
뜻: ① 너무 막연함(“사용자에게 프로젝트가 있다”) ② 너무 장황함(“2026년 1월 5일에 사용자가 … 살펴봐 달라고 했고 …”) — 일기처럼 쓰면 자리만 차지합니다.
꽉 찼을 때 돌아오는 오류의 내용
- 오류에는
"success": false, 설명 글(error— 지금 사용량, 넘치는 글자 수, “낡은 항목을 지우거나 줄이는 작업과 새 항목 추가를 묶음 하나로 다시 보내라”는 안내), 지금 항목 목록(current_entries), 사용량(usage, 예:"2,100/2,200")이 들어 있습니다. patch도 한도에 묶입니다 — 항목을 더 길게 만드는 patch 는 넘칠 수 있습니다.patch/remove의old_text가 어느 항목에도 맞지 않으면 같은 방식으로 실패하고, 가장 비슷한 항목을closest_entries로 알려 줍니다.
기억은 세션이 바뀔 때 힘을 냅니다 — /new
기억 장치 전체는 세션이 끝나는 순간을 중심으로 만들어졌습니다. MEMORY.md 와 USER.md 가 핵심을 다음 세션으로 옮기고, 빠진 부분은 지난 대화 검색이 채웁니다. 한 세션 안에서는 중요한 내용이 아직 눈앞의 대화에 다 있으므로 이 장치들이 움직일 이유가 없습니다.
이 차이는 메신저(Telegram, Discord 등)에서 중요합니다. 메신저에서는 대화방 하나가 일부러 끊기지 않는 한 세션으로 만들어져 있어서, 재시작이나 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램. 8장) 중단, 컴퓨터 재부팅을 넘어 이어집니다. 밤에 컴퓨터를 꺼도 세션은 끝나지 않고, 다음 메시지가 정확히 그 자리에서 이어받습니다.
| 한 번도 끊지 않으면 생기는 일 | 이유 |
|---|---|
| 비용이 점점 커집니다 | 계속 길어지는 기록 위로 압축(긴 대화를 줄여 정리하는 것 — 3장)이 거듭 돌기 때문입니다 |
| 배우는 순환이 거의 돌지 않습니다 | “잊는다 → 기억에서 떠올린다 → 지난 세션을 찾아본다”는 순환은 세션이 바뀔 때 일어납니다 |
| 새로 적은 기억이 보이지 않습니다 | 기억은 세션 시작 때 한 번만 읽기 때문입니다 (고정된 스냅샷) |
/new
일 하나가 끝났을 때, 주제가 바뀔 때, 하루를 시작할 때 /new(새 세션을 시작하는 슬래시 명령 — 대화 입력 칸에 / 로 시작해 넣는 명령)를 넣습니다. 터미널에서는 실행할 때마다 새 세션이라 대체로 저절로 해결되지만, 게이트웨이에서는 경계를 내가 만들어야 합니다.
기억하라고 했는데 잊어버렸다면
가장 흔한 신고는 이렇습니다. 무언가의 위치(노트 보관 폴더, 프로젝트 폴더, 서버)를 알려 주자 Hermes 가 “기억해 둘게요”라고 답했는데, 새 세션에서는 모릅니다. 아래 순서로 확인합니다 — 첫 번째가 대부분의 경우를 설명합니다.
① 정말 적혔는지 파일을 엽니다
cat ~/.hermes/memories/MEMORY.md
cat ~/.hermes/memories/USER.md
항목이 없다면 모델이 하지도 않은 저장을 했다고 말한 것입니다. 작은 로컬 모델(내 컴퓨터에서 직접 돌리는 모델. 원문 기준 대략 30B 파라미터 미만)이나 도구 호출이 약한 모델이 자주 그럽니다. 도구를 쓰라고 분명히 말하고 파일을 다시 확인합니다.
use the memory tool to save the vault path /srv/vault
뜻: memory 도구를 써서 보관 폴더 경로 /srv/vault 를 저장해 줘.
계속 되풀이되면 지시를 늘리지 말고, 처음 기억을 채울 때만 더 강한 모델을 씁니다. 항목이 파일에 있기만 하면 작은 모델도 잘 읽습니다 — 시스템 프롬프트로 들어오기 때문입니다.
② 승인을 기다리는 중은 아닌지 봅니다
저장 전 승인(write_approval: true)을 켜 두었다면, 대화형 터미널 밖에서 일어난 쓰기는 검토를 기다리며 파일에 들어가지 않습니다.
/memory pending
/memory approve all
뜻: 기다리는 쓰기 목록 보기 / 모두 승인하기. 자세한 내용은 기억 설정.
③ 적은 곳과 읽는 곳이 같은 기억인지 봅니다
기억은 프로필마다 따로입니다. hermes -p work(또는 work chat / work gateway start)는 ~/.hermes/memories/ 가 아니라 ~/.hermes/profiles/work/memories/ 를 읽습니다. 기본 프로필의 터미널 세션과 다른 프로필의 Telegram 봇은 메모를 함께 쓰지 않습니다.
hermes profile list
뜻: 어떤 프로필이 있는지 보여 줍니다. 프로필은 10장.
④ 기억 기능이 켜져 있는지 봅니다
설정에 memory.memory_enabled: false 가 있거나 agent.disabled_toolsets 에 memory 가 들어 있으면 도구 자체가 사라집니다. 모델이 뭐라고 말하든 저장할 수 없습니다.
⑤ 새 세션에서 확인했는지 봅니다
지금 세션에서 저장한 사실은 다음 세션에 보입니다. 이미 돌고 있던 다른 세션에는 보이지 않습니다. 저장한 뒤 /new 를 넣거나 터미널에서 Hermes 를 새로 실행합니다.
| 이것으로는 기억되지 않습니다 | 이유 |
|---|---|
.env 파일의 변수 | 그것은 비밀 값과 설정이지 기억이 아닙니다 |
| 저장해 달라고 하지 않고 지나가듯 말한 사실 | 저장을 부탁해야 합니다 |
지난 대화 검색 — session_search
수첩에 적지 않은 것도 완전히 사라지지는 않습니다. Hermes 는 session_search 도구로 지난 대화 전체를 검색할 수 있습니다.
모두 저장됩니다
터미널과 메신저의 모든 세션이 내 컴퓨터의 데이터베이스 파일(~/.hermes/state.db, SQLite)에 저장되고, 전체 글 검색(FTS5)이 됩니다.
원문 그대로 돌려줍니다
검색 결과는 저장된 실제 메시지입니다. AI 가 요약하지도, 자르지도 않습니다.
몇 주 전 이야기도
지금 기억에 없더라도 몇 주 전에 나눈 이야기를 찾을 수 있고, 찾은 세션 안에서 앞뒤로 넘겨 볼 수 있습니다.
| 기억 (MEMORY.md · USER.md) | 지난 대화 검색 (session_search) | |
|---|---|---|
| 용량 | 합쳐서 약 1,300 토큰 | 제한 없음 (모든 세션) |
| 속도 | 즉시 (시스템 프롬프트 안에 있음) | 검색 약 20ms, 넘겨 보기 약 1ms |
| 비용 | 매 프롬프트마다 토큰이 듦 (세션마다 약 1,300 토큰으로 고정) | 무료 — AI 호출이 없고, 필요할 때만 찾음 |
| 쓰임 | 항상 알고 있어야 하는 핵심 사실 | 특정한 지난 대화 찾기 |
| 관리 | 에이전트가 골라서 관리 | 자동 — 모든 세션이 저장됨 |
정리하면, 기억은 늘 맥락에 있어야 하는 핵심 사실에, 지난 대화 검색은 “지난주에 X 이야기했었나?”처럼 옛 대화의 구체적인 내용을 떠올릴 때 씁니다. 내가 직접 지난 세션 목록을 보려면 터미널에서 아래 명령을 씁니다.
hermes sessions list # Browse past sessions
뜻: 지난 세션 목록을 봅니다. 세션을 이어 하고 찾는 방법은 2장 「세션 찾기」. 도구의 세 가지 호출 방식(discovery · scroll · browse)과 응답 형식은 공식 문서 Session Search Tool 쪽 참고(이 가이드는 다루지 않음).
배운 것 돌아보기 — /journey
learning journey(배움의 여정)는 Hermes 가 지금까지 배운 것 — 저장한 스킬과 기억 항목 — 을 시간 순서(위가 오래된 것, 아래가 최신)로 늘어놓은 화면입니다. 쌓여 온 과정을 재생해 볼 수도 있습니다. 같은 자료를 세 곳에서 볼 수 있습니다.
hermes journey 가 터미널에 타임라인을 그립니다. 같은 명령의 다른 이름은 hermes learning, hermes memory-graph 입니다.
TUI(hermes --tui 로 여는 새 터미널 화면)에서 /journey 를 넣으면 타임라인이 화면 위에 겹쳐 열립니다. 다른 이름은 /learning, /memory-graph.
/journey 가 Star Map / memory-graph 패널을 엽니다. 원문은 “같은 항목들을 눌러 볼 수 있는 그림”이라고만 적습니다.
여정은 보는 곳이면서 배운 것을 솎아 내고 바로잡는 곳이기도 합니다. Hermes 가 나에 대해 틀린 것을 적어 두었다면 여기서 고치거나 지웁니다.
| 명령 | 하는 일 |
|---|---|
hermes journey list | 항목의 id 목록 — 스킬 이름, 그리고 기억 조각의 memory:<source>:<index>:<fingerprint> 형식 id. 출력된 그대로 다시 넣습니다 |
hermes journey delete <node> [-y] | 항목 삭제. 스킬은 보관되어 되살릴 수 있고, 기억 조각은 지워집니다. -y 는 확인 질문을 건너뜁니다 |
hermes journey edit <node> | 항목 내용(스킬의 SKILL.md 또는 기억 조각)을 $EDITOR(내 컴퓨터에 기본으로 정해 둔 글 편집기)로 엽니다 |
같은 list / delete <id> / edit <id> 는 터미널 대화 안의 /journey 명령으로도 되고, 데스크톱 패널에서는 항목에서 바로 고치고 지울 수 있습니다.
hermes journey 의 옵션과, 타임라인에 나타나는 스킬의 조건
옵션: --play(쌓여 온 과정을 재생, --fps 로 속도) · --width/--height(그리는 크기) · --no-color(색 끔) · --json(원자료를 JSON 으로).
스킬은 “배웠다는 신호”가 생기면 타임라인에 나타납니다 — 이 프로필에서 만들어졌거나(/learn 결과, 또는 대화 중 skill_manage 로 생성), 뒤에서 도는 검토가 만들었거나, 한 번이라도 쓰인 경우. 딸려 온 스킬과 손으로 썼지만 한 번도 쓰지 않은 스킬은 나타나지 않습니다.
기억 설정 — 승인 · 알림 · 뒤에서 도는 검토
기억은 기본 설정 그대로 써도 됩니다. 다만 알아 둘 것이 하나 있습니다. Hermes 는 한 차례 답을 마친 뒤 뒤에서 조용히 도는 검토(원문: background self-improvement review)로 기억을 저장하거나 스킬을 고칠 수 있습니다. 되풀이해 바로잡아 준 것, 오래 쓸 만한 요령이 이렇게 기억과 스킬이 됩니다. 이때 기본으로는 대화에 💾 Memory updated(기억이 고쳐졌음) 같은 짧은 줄이 나타납니다.
바꾸고 싶은 것이 생기면 아래 표에서 찾습니다. 설정은 모두 ~/.hermes/config.yaml(Hermes 의 설정 파일 — 3장)에 적습니다.
| 하고 싶은 것 | 쓰는 설정·명령 |
|---|---|
| 저장되기 전에 내가 먼저 보고 승인하기 | memory.write_approval: true → /memory pending 으로 검토 |
| “💾 Memory updated” 알림을 끄거나 더 자세히 보기 | display.memory_notifications (off · on · verbose) |
| 뒤에서 도는 검토를 더 싼 모델로 돌리거나 끄기 | auxiliary.background_review |
| 스킬이 고쳐지기 전에 승인하기 | skills.write_approval: true |
| 내장 기억을 아예 끄기 | memory_enabled 와 user_profile_enabled 를 모두 false |
| 두 파일보다 더 깊은 기억 쓰기 | 외부 기억 제공자 — hermes memory setup |
write_approval: true 로 두면 모든 저장 — 특히 시키지 않았는데 뒤에서 일어나는 저장 — 이 내 승인을 받기 전에는 들어가지 않습니다. 이미 들어간 것은 /journey 에서 고치거나 지웁니다.
config.yaml 의 memory 설정과 켜고 끄는 조합
# In ~/.hermes/config.yaml
memory:
memory_enabled: true
user_profile_enabled: true
memory_char_limit: 2200 # ~800 tokens
user_char_limit: 1375 # ~500 tokens
write_approval: false # false = write freely (default) | true = require approval
prefetch_spill_enabled: false # external recall stays intact unless explicitly enabled
| 조합 | 결과 |
|---|---|
두 _enabled 모두 false | 내장 기억이 꺼지고 memory 도구와 그 안내 글이 빠집니다. memory.provider 로 정한 외부 제공자(Hindsight, Mem0, Honcho …)는 그대로 동작합니다 |
agent.disabled_toolsets 에 memory | 더 센 스위치 — 외부 제공자의 도구까지 숨깁니다 |
한쪽만 false | 도구는 남되 켜진 칸만 알리고, 꺼진 칸으로의 쓰기는 거부됩니다 |
External recall size — 외부 기억 제공자는 기본으로 미리 가져온 내용 전체를 돌려줍니다(안전 상한: hooks.output_spill.max_chars 의 10배, 최소 100,000자). prefetch_spill_enabled: true 면 큰 결과를 앞·뒤 미리보기와 파일 경로로 바꿉니다 — 양은 줄지만 가운데 부분이 모델에게 바로 보이지 않습니다. 원문은 제공자 쪽 한도 설정이 있으면 그것을 먼저 쓰라고 권합니다. 바꾼 뒤에는 Hermes 를 다시 시작합니다.
저장 전 승인 — memory.write_approval 과 /memory 명령
true 로 두면 대화 중의 쓰기와 뒤에서 도는 검토 모두 저장 전에 승인이 필요합니다. 대화형 터미널에서는 그 자리에서 묻고, 그 밖의 곳(메신저 · 스크립트 · 뒤에서 도는 검토)의 쓰기는 대기 목록에 올라갑니다. 기본값 false 는 자유롭게 씁니다.
/memory pending # list staged memory writes (auto ones tagged [auto])
/memory approve <id> # apply one (or 'all')
/memory reject <id> # drop one (or 'all')
/memory approval on # turn the gate on (or 'off') and persist it
뜻: 대기 목록 보기(자동으로 생긴 것은 [auto]) / 하나 또는 전부 적용 / 하나 또는 전부 버림 / 승인 기능을 켜거나 끄고 저장. 터미널과 모든 메신저에서 됩니다. 대기 중인 patch·remove 는 대상 항목 전체를 함께 기록해 두며, 그 사이 항목이 바뀌었으면 승인이 거부됩니다 — 버리고 다시 만듭니다.
뒤에서 도는 검토 — 알림(display.memory_notifications)과 모델·비용(auxiliary.background_review)
display.memory_notifications 는 게이트웨이 대화의 알림만 바꿉니다(플랫폼별: display.platforms.<platform>.memory_notifications). 검토와 쓰기 자체는 그대로입니다.
| 값 | 동작 |
|---|---|
off | 알림 없음 |
on (기본) | 한 줄 알림. 예: 💾 Memory updated, 💾 Skill 'foo' patched |
verbose | 바뀐 내용 미리보기 포함. 예: 💾 Memory ➕ User prefers terse replies |
검토를 돌리는 모델 — 기본은 주 대화 모델입니다(대화가 이미 캐시에 있어 싸게 읽힘). 다른 모델로 보내면 원문 벤치마크 기준 비용이 약 3~5배 낮고, 기억 저장은 같고 스킬 저장은 거의 같았습니다. 아래는 원문의 여러 예시를 한 블록에 모은 것입니다.
auxiliary:
background_review:
provider: openrouter
model: google/gemini-3-flash-preview # auto (default) = main chat model
enabled: true # false = skip automatic post-turn forks
max_input_tokens: 48000 # <= 0 = unlimited
extra_tools:
- propose_shared_memory
defer: auto # auto (default) | never
defer_max_age_s: 1800 # run a queued review anyway after this long
| 키 | 뜻 |
|---|---|
provider / model | 검토 모델. auto(기본) = 주 대화 모델 |
reasoning_effort | 다른 모델로 보낼 때만 적용. 같은 모델이면 주 대화의 추론 강도를 물려받습니다 |
enabled | false = 답 뒤의 자동 검토를 건너뜀(직접 넣는 /refine 은 됨) |
max_input_tokens | 검토 한 번이 다시 읽는 입력 토큰의 상한(0 이하 = 무제한). 정하지 않으면 검토 모델 문맥 창(모델이 한 번에 볼 수 있는 글의 양)의 75%, 최대 600,000 |
extra_tools | 검토에 더 허용할 도구 이름. 기본은 빈 목록(기억 · 스킬 관리 · 읽기 전용 파일 도구만 씀) |
defer / defer_max_age_s | 관리형 로컬 llama-server 에서 컴퓨터가 한가해질 때까지 검토를 미룸(auto, 기본). never = 바로 실행 |
보조 모델 설정 전반은 3장.
스킬 쓰기 승인(skills.write_approval)과 외부 기억 제공자
스킬 쓰기 승인 — skills.write_approval: true(기본 false)면 스킬 쓰기(create / edit / patch / write_file / delete)는 어디서 생겼든 항상 대기로 올라갑니다. SKILL.md 는 대화 말풍선에서 읽기에 너무 커서, 한 줄 요지만 보고 승인하거나 전체를 따로 엽니다.
검토 명령은 /skills pending(대기 목록과 한 줄 요지) · /skills diff <id>(바뀐 부분 전체) · /skills approve <id> · /skills reject <id> · /skills approval on(켜고 끄기)입니다. 대기 중인 파일은 ~/.hermes/pending/skills/<id>.json. 에이전트가 스킬을 고치는 방식은 6장.
외부 기억 제공자(External Memory Providers) — 두 파일을 넘어서는 더 깊은 기억이 필요할 때 쓰는 플러그인입니다. RetainDB 와 ByteRover 두 가지가 딸려 오고, Honcho · Hindsight · Supermemory · Mem0 · OpenViking · Holographic 등은 hermes plugins install <name> 으로 설치합니다. 내장 기억을 대신하지 않고 함께 돌며, 지식 그래프, 뜻으로 찾는 검색, 자동 사실 추출, 세션을 넘나드는 사용자 파악 같은 기능을 더합니다.
hermes memory setup # pick a provider and configure it
hermes memory status # check what's active
뜻: 제공자를 골라 설정 / 지금 무엇이 켜져 있는지 확인. 제공자별 설명은 공식 문서 Memory Providers 쪽 참고(이 가이드는 다루지 않음).
맥락 파일 — 폴더에 두면 알아서 읽는 안내문
맥락 파일(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 에서도 그대로 적용된다는 뜻입니다.
AGENTS.md — 프로젝트 안내문 쓰기
AGENTS.md 는 가장 기본이 되는 프로젝트 맥락 파일입니다. 프로젝트가 어떻게 짜여 있는지, 어떤 규칙을 따라야 하는지, 특별히 주의할 점이 무엇인지를 에이전트에게 알려 줍니다. 원문 예시입니다.
# Project Context
This is a Next.js 14 web application with a Python FastAPI backend.
## Architecture
- Frontend: Next.js 14 with App Router in `/frontend`
- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
- Database: PostgreSQL 16
- Deployment: Docker Compose on a Hetzner VPS
## Conventions
- Use TypeScript strict mode for all frontend code
- Python code follows PEP 8, use type hints everywhere
- All API endpoints return JSON with `{data, error, meta}` shape
- Tests go in `__tests__/` directories (frontend) or `tests/` (backend)
## Important Notes
- Never modify migration files directly — use Alembic commands
- The `.env.local` file has real API keys, don't commit it
- Frontend port is 3000, backend is 8000, DB is 5432뜻: 첫 줄은 프로젝트가 무엇인지 한 문장. ## Architecture(구조)에는 무엇이 어느 폴더에 있는지와 데이터베이스 · 배포 방식, ## Conventions(규칙)에는 코드를 쓰는 방식과 테스트를 두는 곳, ## Important Notes(주의)에는 하면 안 되는 일과 포트 번호를 적었습니다.
원문이 권하는 좋은 AGENTS.md 의 조건은 여섯 가지입니다.
짧게
정해 둔 글자 한도 안으로. 에이전트가 매 차례 읽습니다.
제목으로 나누기
## 제목으로 구조 · 규칙 · 주의를 나눕니다.
구체적인 예시
좋아하는 코드 모양, API 응답 형식, 이름 짓는 법을 보여 줍니다.
하면 안 되는 것
“migration 파일을 직접 고치지 말 것”처럼 적습니다.
주요 경로와 포트
에이전트가 터미널 명령에 그대로 씁니다.
계속 고치기
낡은 안내는 안내가 없는 것보다 나쁩니다.
프로젝트 안에 AGENTS.md 가 여러 개 있을 때 무엇이 읽히는지는 상황에 따라 다릅니다.
작업 폴더가 git 저장소 안에 있으면, 세션을 시작할 때 저장소 맨 위 폴더의 AGENTS.md 부터 작업 폴더까지 길목에 있는 AGENTS.md 를 모두 이어 붙여 읽습니다. 더 깊은 폴더의 파일이 뒤에 오므로, 더 구체적인 안내가 우선합니다. 파일마다 어디서 왔는지 머리말이 붙고(예: ## ../../AGENTS.md), 똑같은 내용은 한 번만 넣습니다.
monorepo/packages/webapp/ 에서 시작한 경우. 뒤에 올수록 더 구체적이라 우선합니다.git 저장소 밖에서는 작업 폴더 한 곳만 확인합니다. 위쪽 폴더는 절대 보지 않습니다. 그래서 /tmp 나 홈 폴더에 누가 놓아둔 AGENTS.md 가 상관없는 세션에 끼어들 수 없습니다.
세션 도중 에이전트가 하위 폴더의 파일을 읽거나 그 폴더에서 명령을 실행하면, 그 폴더의 맥락 파일을 그때 찾아 대화에 넣습니다. 원문은 이것을 점진적 발견(progressive discovery)이라고 부릅니다. 예를 들어 frontend/ 파일을 읽을 때 frontend/AGENTS.md 가, backend/ 파일을 읽을 때 backend/AGENTS.md 가 들어옵니다.
- 시작할 때 전부 읽지 않으므로 시스템 프롬프트가 불어나지 않고, 시스템 프롬프트가 바뀌지 않아 재사용(캐시)이 유지됩니다.
- 하위 폴더 하나는 한 세션에 한 번만 확인합니다.
- 위쪽 폴더로도 올라가며 찾습니다 —
backend/src/main.py를 읽으면backend/src/에 파일이 없어도backend/AGENTS.md를 찾습니다. - 하위 폴더의 맥락 파일도 시작 때와 같은 보안 검사를 거칩니다.
맥락 파일을 읽어 들이는 자세한 순서 (How Context Files Are Loaded)
시작할 때(agent/prompt_builder.py 의 build_context_files_prompt()) — ① 작업 폴더에서 .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules 순으로 찾아 먼저 나온 것을 고름 ② UTF-8 글로 읽음 ③ 보안 검사 ④ 글자 한도를 넘으면 앞 70% · 뒤 20% 만 남김(한도: context_file_max_chars, 없으면 모델 문맥 창에 맞춰 20,000~500,000자) ⑤ # Project Context 머리말 아래에 모음 ⑥ 시스템 프롬프트에 넣음.
세션 도중(agent/subdirectory_hints.py 의 SubdirectoryHintTracker) — ① 도구 호출 인자(path, workdir, 셸 명령)에서 파일 경로를 뽑음 ② 그 폴더와 최대 5단계 위 폴더까지 확인(이미 본 폴더에서 멈춤) ③ AGENTS.md, CLAUDE.md, .cursorrules 가운데 폴더마다 먼저 찾은 것 하나를 읽음 ④ 같은 보안 검사 ⑤ 파일당 32,000자로 자름(고정값. 넘쳐도 대화에 경고는 띄우지 않고 로그에만 적음) ⑥ 도구 결과 뒤에 붙임.
조립된 부분은 # Project Context 머리말과 “아래 프로젝트 맥락 파일을 읽었으니 따를 것”이라는 문장 아래에, ## AGENTS.md 처럼 파일 이름 제목과 그 내용이 이어지는 모양입니다.
하위 폴더별 안내 (Per-Subdirectory Context) — 여러 프로젝트가 한 저장소에 든 경우(monorepo), 하위 폴더 전용 지침을 그 폴더의 AGENTS.md 에 둡니다. 원문 예시: frontend/AGENTS.md 에 “npm 말고 pnpm 사용, Tailwind CSS 사용, 테스트는 pnpm test”, backend/AGENTS.md 에 “의존성 관리는 poetry, 모든 엔드포인트에 OpenAPI 설명 달기”.
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 | |
|---|---|---|
| 적는 것 | 정체성, 말투, 문체, 기본 소통 방식, 성격에서 나오는 행동 | 프로젝트 구조, 코딩 규칙, 선호하는 도구, 저장소별 작업 절차, 명령 · 포트 · 경로 · 배포 메모 |
| 기준 | 어디서나 나를 따라다녀야 하면 여기 | 프로젝트에 속하면 여기 |
SOUL.md 가 프롬프트에 들어가는 방식과, 원문 두 쪽이 다르게 적은 부분
- SOUL.md 내용은 시스템 프롬프트의 첫 자리(slot #1)에 감싸는 글 없이 들어가, 코드에 박혀 있던 기본 정체성을 대신합니다. 맥락 파일 구역에 또 들어가지 않습니다.
- 넣기 전에 프롬프트 인젝션 검사를 하고 너무 크면 잘라냅니다. 원문은 이상한 지시를 숨겨 넣으려 하지 말고 성격과 목소리에 집중하라고 적습니다.
- 비어 있거나 공백뿐이거나 읽을 수 없으면 내장 기본 정체성을 씁니다:
"You are Hermes Agent, built by Nous Research. Be direct: match the length of your reply to the weight of the ask...".skip_context_files가 켜진 경우(예: 하위 에이전트 · 위임 — 7장)에도 같습니다. - 원문끼리 다른 곳 — 빈 파일일 때 Personality 쪽은 “내장 기본 정체성으로 돌아간다”, Context Files 쪽은 “아무것도 더해지지 않는다”고 적습니다. 프롬프트 모양 예시도 Context Files 쪽은 SOUL 내용을 맨 끝에, Personality 쪽은 첫 자리에 둡니다. 이 가이드는 더 자세한 Personality 쪽을 따랐습니다.
/personality — 잠깐 바꾸는 말투
/personality 는 지금 대화의 시스템 프롬프트 위에 말투 하나를 덧씌우는 슬래시 명령(대화 입력 칸에 / 로 시작해 넣는 명령)입니다. 원문의 구분은 이렇습니다 — SOUL.md = 바탕 목소리, /personality = 잠깐 바꾸는 모드. 예를 들어 평소에는 실용적인 SOUL.md 를 두고, 공부할 때만 /personality teacher, 아이디어를 낼 때만 /personality creative 를 씁니다.
/personality
/personality concise
/personality technical
뜻: 인자 없이 넣으면 고를 수 있는 목록이 나오고 지금 켜진 것이 표시됩니다(none 도 함께 나옴). 이름을 붙이면 그 말투로 바꿉니다.
/personality teacher
뜻: 메신저 대화에서도 같은 명령을 씁니다.
/personality none
/personality default
/personality neutral
뜻: 셋 다 같은 일을 합니다 — 덧씌운 말투를 걷어 내고 바탕(내 SOUL.md)으로 돌아갑니다. 다음 메시지부터 적용됩니다.
Hermes 에 들어 있는 말투는 14가지입니다. 터미널, 메신저, TUI, 데스크톱 앱 어디서나 쓸 수 있습니다.
| 이름 | 어떤 말투 | 이름 | 어떤 말투 |
|---|---|---|---|
helpful | 친절한 범용 비서 | pirate | 기술에 밝은 해적 선장 Captain Hermes |
concise | 짧게, 요점만 | shakespeare | 극적인 셰익스피어풍 문장 |
technical | 자세하고 정확한 기술 전문가 | surfer | 느긋한 서퍼 말투 |
creative | 틀을 벗어난 새로운 발상 | noir | 하드보일드 탐정의 독백 |
teacher | 분명한 예시를 드는 참을성 있는 선생님 | uwu | uwu 말투로 최대한 귀엽게 |
kawaii | 귀여운 표현, 반짝임, 열정 ★ | philosopher | 질문마다 깊이 사색 |
catgirl | 고양이 같은 표현(nya~)의 Neko-chan | hype | 최대 에너지와 열정!!! |
/personality 는 Hermes 가 어떻게 말하는지를 바꿉니다. 터미널에서 어떻게 보이는지는 display.skin 설정과 /skin 명령이 맡습니다 — 공식 문서 Skins & Themes 쪽 참고(이 가이드는 다루지 않음).
덧씌운 말투가 있어도, 그 말투가 바탕을 크게 바꾸지 않는 한 SOUL.md 가 Hermes 의 기본 성격으로 계속 깔려 있습니다.
나만의 말투 만들기, 저장되는 곳, 업그레이드 때 한 번 초기화
~/.hermes/config.yaml 의 agent.personalities 아래에 나만의 말투를 더하거나, 내장 말투와 같은 이름으로 써서 덮어쓸 수 있습니다. 맨 위의 personalities: 블록도 되지만, 같은 이름이 양쪽에 있으면 agent.personalities 가 이깁니다.
agent:
personalities:
codereviewer: >
You are a meticulous code reviewer. Identify bugs, security issues,
performance concerns, and unclear design choices. Be precise and constructive.
뜻: “꼼꼼한 코드 검토자”라는 말투를 codereviewer 라는 이름으로 등록합니다. 그 뒤 /personality codereviewer 로 켭니다.
- 고른 말투는 이름으로
display.personality에 저장되고, 끄는 명령은 이 값을 비웁니다. 말투는agent.system_prompt(내가 직접 쓰는 시스템 프롬프트 칸 — 말투를 고르지 않았을 때만 적용)를 건드리지 않습니다. - 업그레이드 때 한 번 초기화 — 예전 버전은 말투 상태를 곳마다 다르게 저장해 꺼 둔 말투가 다시 켜질 수 있었습니다. 그래서 업그레이드 후 첫 실행 때 저장된 선택이 한 번
none으로 돌아갑니다(무엇이 지워졌는지 출력됨). 계속 쓰려면 다시 켭니다.
보안 검사 — 수상한 지시문 걸러 내기
맥락 파일과 기억은 시스템 프롬프트에 들어가는 글입니다. 누군가 그 안에 “앞의 지시는 무시해” 같은 문장을 몰래 넣으면 에이전트가 속을 수 있습니다. 이런 공격을 프롬프트 인젝션(prompt injection — 글 속에 몰래 숨긴 지시로 AI 를 속이는 것)이라고 합니다. 그래서 Hermes 는 이 글들을 넣기 전에 검사합니다.
| 검사기가 찾는 것 | 원문 예시 |
|---|---|
| 지시를 뒤집으려는 시도 | “ignore previous instructions”(앞의 지시를 무시해), “disregard your rules”(규칙을 무시해) |
| 속이라는 지시 | “do not tell the user”(사용자에게 말하지 마) |
| 시스템 프롬프트 덮어쓰기 | “system prompt override” |
| 숨긴 HTML 주석 | <!-- ignore instructions --> |
| 숨긴 div 요소 | <div style="display:none"> |
| 비밀 값 빼내기 | curl ... $API_KEY |
| 비밀 파일 읽기 | cat .env, cat credentials |
| 보이지 않는 문자 | 폭이 0인 공백, 글 방향을 뒤집는 문자, word joiner |
걸렸을 때 어떻게 되는지는 글의 종류마다 다릅니다.
| 대상 | 걸리면 |
|---|---|
프로젝트 맥락 파일 (.hermes.md, AGENTS.md, CLAUDE.md, .cursorrules) | 차단 — 파일 내용 대신 아래 같은 줄이 들어갑니다. 하위 폴더에서 찾은 파일도 같습니다 |
| 내 Hermes 홈 폴더의 SOUL.md | 경고만 하고 읽습니다. 내가 쓴 파일이기 때문입니다(파일 도구로 이 파일을 고치려면 내 승인이 필요하고, 프로젝트를 내려받는다고 이 파일이 바뀌지 않음). /context 에 ⚠ SOUL.md … loaded — matched prompt-injection pattern(s); review the file 로 표시됩니다 |
| 기억 항목 | 저장하지 않습니다. 프롬프트 인젝션, 비밀 값 빼내기, SSH 뒷문 패턴이나 보이지 않는 유니코드 문자가 든 내용은 막힙니다 |
[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]
뜻: AGENTS.md 에 프롬프트 인젝션으로 보이는 내용이 있어 읽지 않았습니다.
SOUL.md 예외의 범위, 크기 한도(Size Limits)와 잘라내기
SOUL.md 예외의 범위 — 공격 문구를 설명하는 SOUL.md(보안 안내 등)도 계속 쓸 수 있게 차단하지 않습니다. 다만 프로필 배포판이 가져온 SOUL.md 는 다릅니다. hermes profile install <git-url> 과 hermes profile update 는 남이 만든 SOUL.md 를 검사나 승인 없이 복사하므로, distribution.yaml 이 그 파일을 관리하면 검사에 걸릴 때 차단됩니다.
| 한도 | 값 |
|---|---|
| 파일당 최대 글자 수 | context_file_max_chars 를 정했으면 그 값, 아니면 자동(모델의 문맥 창에 맞춤, 최소 20,000 · 최대 500,000) |
| 파일당 읽기 제한 시간 | context_file_read_timeout (기본 5초). 더 오래 걸리는 파일 — 예: iCloud Drive, OneDrive, NFS 에 있는 파일 — 은 경고와 함께 건너뜀 |
| 넘쳤을 때 | 앞 70% + 뒤 20% 를 남기고, 가운데(10%)에 글자 수와 “파일 도구로 읽으라”는 표시를 넣음 |
[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]
뜻: AGENTS.md 25,000자 가운데 앞 14,000자 + 뒤 4,000자만 남겼음. 전체는 파일 도구로 읽을 것.
전체 그림 — 쌓이는 순서와 추천 구성
지금까지 본 것들이 시스템 프롬프트 안에서 어떤 순서로 쌓이는지, 원문은 “큰 틀에서” 아래처럼 적습니다. SOUL.md 가 바탕이고 나머지가 그 위에 올라갑니다.
원문이 권하는 기본 구성은 셋을 제자리에 두는 것입니다.
① 공들인 SOUL.md 하나
~/.hermes/SOUL.md 에 둡니다. → 한결같은 목소리
② 프로젝트 지침은 AGENTS.md
프로젝트 폴더에 둡니다. → 프로젝트에 맞는 행동이 제자리에
③ /personality 는 잠깐만
모드를 잠시 바꾸고 싶을 때만 씁니다. → 필요할 때의 조절
원문이 함께 보라고 가리키는 문서: Context Files · Configuration · Tips & Best Practices · SOUL.md Guide. 뒤의 둘은 이 가이드가 받은 원문에 없어 다루지 않습니다(공식 문서 참고).
- 네 가지 장치 — 기억(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 는 직접 확인합니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/features/memory · hermes-agent.nousresearch.com/docs/user-guide/features/context-files · hermes-agent.nousresearch.com/docs/user-guide/features/personality (수집일 2026-11-09 의 공식 문서)
스킬 — 일하는 법을 배우고 다시 쓰기
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트)는 일하는 방법을 스킬(skill — 특정 일을 하는 방법을 적은 설명서)이라는 문서로 갖고 있다가, 그 일이 필요해졌을 때만 꺼내 읽습니다. 이 장에서는 스킬이 무엇이고, 어떻게 불러 쓰며, 어디서 구해 설치하고, 에이전트가 어떻게 스스로 스킬을 만들어 가는지를 차례로 살펴봅니다.
- 스킬이 무엇이고 기억과 어떻게 다른지, 어디에 저장되는지
- 설치된 스킬을 슬래시 명령으로 부르는 법, 여러 개를 한 번에 부르는 법
/learn으로 내 자료를 스킬로 만드는 법- “필요할 때만 꺼내 읽는다”는 3단계 구조가 왜 글의 양(토큰)을 아끼는지
- Skills Hub 에서 스킬을 찾아 미리 보고 설치하고 최신으로 유지하는 법
- 에이전트가 스스로 스킬을 만드는 때와, 그것을 내가 승인하게 바꾸는 법
- 스킬 폴더 구조, 번들, 그리고 설치할 때 거치는 보안 검사와 신뢰 등급
- 스킬이란 무엇인가 — 설명서 선반이라는 큰 그림과 저장 위치.
- 스킬 쓰기 —
/스킬이름한 줄이면 됩니다. - Skills Hub 에서 찾아 설치하기 — 둘러보기 → 미리 보기 → 설치.
나머지 소절(형식·폴더·번들·안전)은 스킬을 직접 만들거나 팀과 나눠 쓸 때 돌아와서 읽어도 됩니다. 손으로 따라 해 보려면 활용편 실습 4가 이 장의 짝입니다.
스킬이란 무엇인가
스킬은 에이전트(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 로 볼 수 있습니다.
딸려 오는 스킬 없이 빈 상태로 시작하기 (Starting with a blank slate)
기본값으로는 모든 프로필(profile — 설정·기억·세션을 따로 쓰는 별도 Hermes 환경)에 딸려 오는 스킬 묶음이 채워지고, hermes update 를 할 때마다 새로 추가된 딸림 스킬이 더해집니다. 딸림 스킬이 하나도 없고 업데이트 뒤에도 비어 있는 프로필을 원하면 다음 가운데 하나를 씁니다.
| 언제 | 방법 |
|---|---|
| 설치할 때 (기본 ~/.hermes 프로필) | 설치 프로그램에 --no-skills 옵션은 없습니다. 설정 단계에서 Blank Slate 를 고르면 딸림 스킬을 채울지 묻고, “아니오”라고 답하면 아래의 표시 파일이 만들어집니다. 묻지 않고 진행되는 설치(non-interactive)는 스킬을 채우므로, 비우고 싶으면 설치 뒤 hermes skills opt-out 을 실행합니다. |
| 프로필을 만들 때 | hermes profile create research --no-skills |
| 이미 쓰는 프로필 | hermes skills opt-out — 앞으로 채우지 않음. 이미 있는 파일은 건드리지 않습니다.hermes skills opt-out --remove — 고치지 않은 딸림 스킬도 지움(먼저 확인을 받음).hermes skills opt-in --sync — 되돌리기: 표시를 지우고 지금 다시 채움. |
어느 길이든 프로필 폴더에 .no-bundled-skills 라는 표시 파일을 씁니다. 이 파일이 있는 동안 설치 프로그램, hermes update, 스킬 동기화가 모두 그 프로필에는 딸림 스킬을 채우지 않습니다. 표시 파일을 지우거나 hermes skills opt-in 을 실행하면 다시 켜집니다.
기본은 안전한 쪽입니다. --remove 도 Hermes 가 설치한 것과 한 글자도 다르지 않은 딸림 스킬만 지웁니다. 내가 고친 스킬, Hub 에서 설치한 스킬, 내가 쓴 스킬은 항상 남습니다.
스킬 쓰기 — 슬래시 명령으로 부르기
설치된 스킬은 저절로 슬래시 명령(대화 입력 칸에 / 로 시작해 넣는 명령)이 됩니다. 따로 등록할 것이 없습니다. 대화 입력 칸에 /스킬이름 을 쓰고 그 뒤에 부탁을 이어 적으면, 에이전트가 그 스킬을 읽은 다음 부탁을 처리합니다. 터미널(글자로 명령을 입력하는 창)의 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장 「툴셋」).
여러 스킬을 한 줄에 쓸 때 읽는 규칙
/plan 은 이제 스킬이 아니라 내장 명령입니다
원문은 괄호 안에 이렇게 덧붙입니다. 계획 모드(plan mode)도 같은 방식으로 쓰지만 지금은 내장 명령입니다. /plan [request] 를 넣으면 Hermes 는 필요하면 주변 상황을 살펴본 뒤, 일을 실행하는 대신 마크다운(간단한 기호로 제목·목록을 표시하는 글 형식)으로 실행 계획을 써서 저장합니다. 저장 위치는 지금 작업 폴더(작업 공간 또는 백엔드의 작업 폴더)를 기준으로 한 .hermes/plans/ 아래입니다.
/learn — 내 자료를 스킬로 만들기
/learn 은 내가 이미 아는 것이나 쌓아 둔 참고 자료를, SKILL.md 를 손으로 쓰지 않고 스킬로 바꾸는 빠른 길입니다. 형식이 정해져 있지 않아서, 말로 설명할 수 있는 것이면 무엇이든 가리킬 수 있습니다. 에이전트가 이미 가진 도구로 자료를 모으고, Hermes 의 스킬 작성 기준에 맞춰 스킬을 써 줍니다.
무엇을 가리킬 수 있는지는 원문의 다섯 가지 예시가 잘 보여 줍니다.
| 가리키는 것 | 예시 (원문) | 뜻 · 에이전트가 하는 일 |
|---|---|---|
| 내 컴퓨터의 폴더 (SDK(개발용 도구 묶음)·문서) | /learn the REST client in ~/projects/acme-sdk, focus on auth + pagination | “이 폴더의 REST 클라이언트를 익혀 줘. 인증과 페이지 넘김 위주로.” — 파일 읽기·찾기 도구(read_file / search_files)로 읽습니다. |
| 온라인 문서 한 쪽 | /learn https://docs.example.com/api/quickstart | 웹 쪽을 가져오는 도구(web_extract)로 받아 읽습니다. |
| 방금 이 대화에서 함께 한 일 | /learn how I just deployed the staging server | “방금 내가 스테이징 서버(실제 공개 전 시험용 서버)를 배포한 방법을 익혀 줘.” |
| 붙여 넣은 메모 · 말로 적은 절차 | /learn filing an expense: open the portal, New > Expense, attach the receipt, submit | “경비 청구: 포털 열기 → New > Expense → 영수증 첨부 → 제출.” |
| 책 한 권 · 논문 묶음 · 큰 문서 폴더 | /learn ~/books/designing-data-intensive-applications.pdf | 아래의 지식 창고형 스킬이 됩니다. |
에이전트가 따르는 작성 기준으로 원문은 네 가지를 듭니다: 설명은 60자 이내(≤60-char description), 정해진 절 순서(standard section order — 형식 참고), Hermes 도구 기준의 서술(Hermes-tool framing), 지어낸 명령 없음(no invented commands).
큰 자료는 “지식 창고형 스킬”이 됩니다
책, 논문 묶음, 규격서, 큰 문서 폴더처럼 자료가 클 때 에이전트는 그것을 파일 하나에 욱여넣지도, 내용이 빠져 버리는 요약 한 장으로 줄이지도 않습니다. 대신 넓게 펼친 지식 창고형 스킬(knowledge-base skill)을 만듭니다.
가벼운 SKILL.md
자료의 핵심 사고 틀(core mental models)과 색인만 담습니다.
references/ 폴더
장이나 주제마다 간추린 파일을 하나씩 둡니다.
용어집 · 요약표
자료가 그럴 만할 때만 덧붙입니다(glossary or cheatsheet).
참고 파일은 질문이 그 파일을 필요로 하기 전까지 비용이 들지 않습니다. 에이전트가 필요할 때 skill_view 로 그 파일만 불러오므로, 질문 하나에 드는 양은 자료 전체가 아니라 답의 크기에 비례합니다(다음 소절의 원리 그대로입니다). 같은 주제에 새 자료로 /learn 을 다시 실행하면 스킬이 하나 더 생기지 않고 기존 스킬에 합쳐집니다.
/learn 은 CLI, 메신저 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램), TUI(hermes --tui 로 여는 새 터미널 화면), 대시보드(dashboard — Hermes 를 화면으로 다루는 곳) 어디서나 똑같이 동작하고, 터미널 백엔드(에이전트의 명령이 실제로 실행되는 곳 — 내 컴퓨터·Docker·원격)가 무엇이든 상관없습니다. 대시보드에는 Skills 쪽에 Learn a skill(스킬 익히기) 단추가 있어서, 폴더 칸·URL 칸·자유롭게 적는 글 칸이 있는 패널을 엽니다. 이 패널은 /learn 요청을 대신 지어서 대화에서 실행해 줍니다.
/learn 이 어디서나 같은 이유 — 별도 장치가 없음
자료를 모으는 일을 살아 있는 에이전트가 직접 하므로 따로 도는 수집 엔진(ingestion engine)이 없습니다. 모델에게 새 도구를 추가하지도 않습니다(no model-tool footprint). /learn 은 작성 기준을 담은 프롬프트(AI 에게 주는 지시문)를 만들어 보통의 대화 한 차례로 에이전트에게 넘길 뿐입니다. 결과는 에이전트가 skill_manage 도구로 저장하므로, 스킬 쓰기 승인을 켜 두었다면 그 승인 절차가 그대로 적용됩니다(에이전트가 스스로 만드는 스킬).
필요할 때만 꺼내 읽는다 — 3단계 불러오기
에이전트의 두뇌 역할을 하는 모델(Claude·GPT·Gemini 같은 AI)은 한 번에 볼 수 있는 글의 양이 정해져 있습니다. 이 한도를 컨텍스트(문맥 창 — 모델이 한 번에 기억하며 볼 수 있는 글의 양)라 하고, 글의 양은 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)으로 셉니다. 스킬 수십 개의 본문을 대화마다 전부 읽으면 정작 내 일에 쓸 자리가 줄어듭니다.
그래서 스킬은 조금씩 단계적으로 펼쳐 보이는 방식(progressive disclosure)을 따릅니다. 원문 표현으로는 “토큰을 아끼는 불러오기 방식”이며, 요점은 한 문장입니다. 에이전트는 스킬의 전체 내용을 정말 필요할 때만 불러옵니다.
원문에 실린 표기는 다음과 같습니다. 숫자가 붙은 것은 0단계뿐이고, 나머지 두 단계는 “varies(그때그때 다름)”로 적혀 있습니다.
Level 0: skills_list() → [{name, description, category}, ...] (~3k tokens)
Level 1: skill_view(name) → Full content + metadata (varies)
Level 2: skill_view(name, path) → Specific reference file (varies)
한 번의 일을 따라가 보면 이렇습니다.
① 대화가 시작될 때 — 목록만 갖고 있습니다
에이전트가 고를 수 있는 스킬 목록에는 스킬마다 이름·한 줄 설명·분류만 들어 있습니다. 원문 기준으로 이 목록 전체가 약 3천 토큰입니다. 본문은 아직 아무것도 읽지 않았습니다.
② 일이 들어옵니다
내가 /excalidraw sketch the request flow for our API 처럼 스킬을 부르거나, 에이전트가 목록의 설명을 보고 지금 일에 맞는 스킬이 있다고 판단합니다.
③ 그 스킬 하나만 펼칩니다
skill_view(name) 으로 그 스킬의 SKILL.md 전체와 부가 정보를 불러옵니다. 나머지 스킬들은 여전히 목록 한 줄로만 남아 있습니다.
④ 더 필요하면 참고 파일 하나만
스킬 폴더에 딸린 참고 문서가 필요해지면 skill_view(name, path) 로 그 파일 하나만 더 읽습니다. 앞 소절의 지식 창고형 스킬이 책 한 권을 담고도 가벼운 까닭이 이것입니다.
대화 도중에 스킬이 생기거나 없어지면
대화가 열려 있는 동안 스킬이 설치·생성·삭제되면, 내가 에이전트에게 보내는 다음 메시지에 짧은 쪽지가 함께 실립니다. 쪽지에는 새로 생긴 스킬의 이름과 설명, 없어진 스킬의 이름이 적혀 있습니다. 변화 한 번에 쪽지도 한 번입니다. 그래서 대화를 새로 시작하지 않아도 에이전트가 새 스킬을 압니다.
왜 목록을 바로 고치지 않고 쪽지로 알리나 — 프롬프트 캐시와 /reload-skills
에이전트가 고르는 스킬 목록은 대화의 시스템 프롬프트(대화 맨 앞에 깔리는 기본 지시문)에 들어 있습니다. 시스템 프롬프트는 제공자(provider — AI 모델을 빌려주는 서비스)의 프롬프트 캐시(같은 앞부분을 다시 계산하지 않게 저장해 두는 기능)가 계속 통하도록 고정해 둡니다. 그래서 변화는 쪽지로 먼저 알리고, 시스템 프롬프트 자체는 다음 압축(compaction — 3장 「압축」) 때 바뀐 목록을 반영합니다.
변화가 생기는 길로 원문은 Skills Hub, 다른 터미널에서 실행한 hermes skills install, 플러그인, curator(스킬을 알아서 관리하는 기능 — 원문은 “자율 스킬 유지 관리”라고만 풉니다), 에이전트 자신을 듭니다. 이 알림 때문에 /reload-skills 를 실행할 필요는 없습니다. 다만 /reload-skills 는 지금도 /스킬이름 슬래시 명령 목록을 새로 고치는 데 쓰입니다.
SKILL.md 형식 — 스킬 한 장의 생김새
스킬의 중심인 SKILL.md 는 두 부분으로 되어 있습니다. 위쪽은 머리말(frontmatter — 파일 맨 위 --- 두 줄 사이에 적는 기본 정보)이고, 아래쪽은 사람이 읽는 글처럼 쓴 본문입니다.
원문의 예시 전체는 다음과 같습니다. # 뒤의 영어는 원문에 달린 설명이고, “Optional” 은 써도 되고 안 써도 되는 항목이라는 뜻입니다.
---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux] # Optional — restrict to specific OS platforms
metadata:
hermes:
tags: [python, automation]
category: devops
fallback_for_toolsets: [web] # Optional — conditional activation (see below)
requires_toolsets: [terminal] # Optional — conditional activation (see below)
config: # Optional — config.yaml settings
- key: my.setting
description: "What this controls"
default: "value"
prompt: "Prompt for setup"
---
# Skill Title
## When to Use
Trigger conditions for this skill.
## Procedure
1. Step one
2. Step two
## Pitfalls
- Known failure modes and fixes
## Verification
How to confirm it worked.
본문의 네 절(## When to Use · ## Procedure · ## Pitfalls · ## Verification)은 위 그림의 “언제 쓰나 · 순서 · 함정 · 확인”에 해당합니다. 머리말 항목의 뜻은 다음과 같습니다.
| 머리말 항목 | 뜻 |
|---|---|
name | 스킬 이름. 슬래시 명령의 이름이 됩니다. |
description | 이 스킬이 무엇을 하는지 짧게 적은 설명. |
version | 버전 번호. |
platforms | (선택) 특정 운영체제에서만 쓰이게 제한. |
metadata.hermes.tags · category | 꼬리표와 분류. |
fallback_for_toolsets · requires_toolsets | (선택) 도구가 있고 없음에 따라 스킬을 보이거나 숨김. |
metadata.hermes.config | (선택) 스킬이 쓰는 설정값을 config.yaml 에 두게 함. |
선택 항목의 자세한 동작, 스킬에 필요한 비밀 값을 안전하게 묻는 방식, 스킬이 만든 그림·소리 파일을 메신저로 보내는 방식은 아래 접힌 상자에 있습니다.
운영체제별 스킬 — platforms (Platform-Specific Skills)
| 값 | 해당 운영체제 |
|---|---|
macos | macOS (Darwin) |
linux | Linux |
windows | Windows |
platforms: [macos] # macOS only (e.g., iMessage, Apple Reminders, FindMy)
platforms: [macos, linux] # macOS and Linux
이 항목을 적으면 맞지 않는 운영체제에서는 그 스킬이 시스템 프롬프트, skills_list(), 슬래시 명령에서 자동으로 숨겨집니다. 적지 않으면 모든 운영체제에서 불러옵니다.
조건에 따라 보이는 스킬 — 대체용 스킬 (Conditional Activation / Fallback Skills)
스킬은 지금 세션에서 쓸 수 있는 도구에 따라 스스로 보이거나 숨을 수 있습니다. 가장 쓸모 있는 경우가 대체용 스킬(fallback skill)입니다 — 유료 도구를 쓸 수 없을 때만 나타나는 무료·로컬 대안입니다.
네 항목 모두 머리말의 metadata.hermes 아래에 fallback_for_toolsets: [web], requires_tools: [terminal] 같은 꼴로 적습니다.
| 항목 | 동작 |
|---|---|
fallback_for_toolsets | 적어 둔 툴셋을 쓸 수 있으면 스킬이 숨고, 없으면 나타납니다. |
fallback_for_tools | 같지만 툴셋이 아니라 도구 하나하나를 봅니다. |
requires_toolsets | 적어 둔 툴셋을 쓸 수 없으면 스킬이 숨고, 있으면 나타납니다. |
requires_tools | 같지만 도구 하나하나를 봅니다. |
예: curl 로 검색하는 스킬이 fallback_for_toolsets: [web] 을 적어 두면, web 툴셋을 쓸 수 있는 동안은 숨어 있다가 그 툴셋이 꺼졌을 때만 나타납니다. 그래서 에이전트에게 검색할 길이 하나는 남습니다. 조건 항목이 하나도 없는 스킬은 예전처럼 항상 보입니다.
스킬에 필요한 비밀 값과 설정 (Secure Setup on Load · Skill Config Settings)
비밀 값. 스킬은 자기에게 필요한 환경 변수(프로그램에 넘겨주는 이름 붙은 값 — API 키 등)를 선언할 수 있고, 값이 없어도 스킬 목록에서 사라지지 않습니다.
required_environment_variables:
- name: TENOR_API_KEY
prompt: Tenor API key
help: Get a key from https://developers.google.com/tenor
required_for: full functionality
값이 비어 있으면 Hermes 는 그 스킬이 내 컴퓨터의 CLI 에서 실제로 불려 올 때에만 안전하게 물어봅니다. 건너뛰고 스킬을 계속 써도 됩니다. 메신저에서는 대화창으로 비밀 값을 묻는 일이 없고, 내 컴퓨터에서 hermes setup 을 쓰거나 ~/.hermes/.env 에 적으라고 안내합니다. 값을 넣고 나면 선언된 환경 변수는 execute_code 와 terminal 의 격리 실행 환경(sandbox)으로 자동 전달되어, 스킬의 스크립트가 $TENOR_API_KEY 를 바로 쓸 수 있습니다. 스킬과 무관한 환경 변수는 terminal.env_passthrough 설정을 씁니다(공식 문서 Environment Variable Passthrough 쪽 참고 — 이 가이드는 다루지 않음).
비밀이 아닌 설정. 경로나 취향 같은 값은 config.yaml 에 두도록 선언합니다.
metadata:
hermes:
config:
- key: myplugin.path
description: Path to the plugin data directory
default: "~/myplugin-data"
prompt: Plugin data directory path
이 값들은 config.yaml 의 skills.config 아래에 저장됩니다. hermes config migrate 가 아직 정하지 않은 값을 물어보고, hermes config show 가 보여 줍니다. 스킬이 불려 올 때 정해진 값이 대화에 함께 실리므로 에이전트가 설정값을 저절로 압니다. (공식 문서 Skill Settings · Creating Skills — Config Settings 쪽 참고. 설정 파일 자체는 3장 「설정 파일」.)
스킬이 만든 파일을 메신저로 보내는 방식 (Skill output and media delivery)
스킬의 답(또는 에이전트의 어떤 답이든)에 그림·소리 같은 미디어 파일의 절대 경로가 홀로 적혀 있으면 — 예: /home/user/screenshots/diagram.png — 게이트웨이가 알아채서 글에서는 그 경로를 지우고, 파일을 대화방에 맞는 방식(Telegram 사진, Discord 첨부 등)으로 보냅니다.
| 지시어 | 하는 일 |
|---|---|
[[audio_as_voice]] | 소리 파일을, 지원하는 플랫폼(Telegram, WhatsApp)에서 음성 메시지 말풍선으로 보냅니다. |
[[as_document]] | 그 답에서 뽑힌 모든 미디어 경로를 그림 말풍선이 아니라 내려받는 파일(문서 첨부)로 보냅니다. |
[[as_document]] 가 필요한 까닭: Telegram 의 sendPhoto 는 그림을 1280 px, 약 200 KB 로 다시 압축해서 고해상도 화면 갈무리나 도표의 글씨가 뭉개집니다. 1~2 MB PNG 를 sendDocument 로 보내면 원본 그대로 갑니다.
Here is your rendered chart:
/home/user/.hermes/cache/chart-q4-2025.png
[[as_document]]
지시어는 보통 답의 마지막 줄에 두며, 전달 전에 지워져 사용자에게 보이지 않습니다. 적용 단위는 일부러 “답 하나 전체”입니다([[audio_as_voice]] 와 같은 범위). 스킬에서는 사용자가 파일 그대로 필요로 하는 화면 갈무리·도표를 만들 때(편집·보관·원본 공유), 또는 기본 미리보기가 작은 글씨·픽셀 단위 그림·색에 민감한 결과물의 세부를 가릴 때 씁니다. 문서 전송 경로가 따로 없는 플랫폼(예: SMS)은 가진 첨부 방식으로 대신 보냅니다.
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 가 붙은 설치 명령이 있습니다. 이것은 보안 검사의 가벼운 경고를 넘기는 옵션입니다. 무엇을 넘길 수 있고 무엇은 못 넘기는지 안전 소절에서 먼저 확인하세요.
웹사이트 설치 링크의 세부 (Install from the website)
단추는 출처가 명시된 스킬 주소를 URL 형식으로 담아 Hermes Desktop 을 엽니다. 선택 스킬은 official/..., ClawHub 는 clawhub/..., 딸림 스킬은 이름만 적는 모호한 꼴 대신 저장소 경로를 그대로 씁니다. 카드에 적힌 CLI 명령도 같은 주소를 씁니다.
hermes://skill/install?identifier=official%2Fsecurity%2F1password
설치는 보통의 Skills Hub 절차(보안 검사, 작업 기록, 설치 목록 새로 고침)를 그대로 거칩니다. 확인 창이 열린 사이에 프로필이나 연결을 바꿨다면 새 대상에서 링크를 다시 엽니다 — 링크로 검사를 건너뛰거나 다른 프로필을 고를 수는 없습니다. 열려 있던 대화는 다음 메시지 때 새 스킬을 알게 됩니다. skill/install 경로는 최신 Desktop 빌드가 있어야 합니다.
본문에 나오지 않은 나머지 명령 (Common commands)
둘러보기·검색·미리 보기·설치·목록·확인·갱신·제거 명령은 위 본문에 있습니다. 원문 명령 목록의 나머지입니다.
| 명령 (원문) | 뜻 |
|---|---|
hermes skills browse --source official | 공식 선택 스킬만 둘러보기 |
hermes skills search react --source skills-sh | skills.sh 목록에서 검색 |
hermes skills search https://mintlify.com/docs --source well-known | 그 사이트가 내주는 스킬 찾기 |
hermes skills install official/security/1password | 공식 선택 스킬 설치 |
hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force | skills.sh 스킬을 경고를 넘기고 설치 |
hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify | 웹사이트가 내주는 스킬 설치 |
hermes skills install https://sharethis.chat/SKILL.md | 웹 주소에서 바로 설치(가리키는 지원 파일 포함) |
hermes skills install https://example.com/SKILL.md --name my-skill | 머리말에 이름이 없을 때 이름을 지정 |
hermes skills audit | Hub 스킬 전체를 보안 재검사 |
hermes skills reset google-workspace | 딸림 스킬의 “내가 고침(user-modified)” 표시 풀기 |
hermes skills reset google-workspace --restore | 딸림 원본으로 되돌리고 내 수정은 삭제 |
hermes skills publish skills/my-skill --to github --repo owner/repo | 스킬을 GitHub 저장소로 공개(원문에 설명 주석 없음) |
hermes skills snapshot export setup.json | 스킬 구성 내보내기 |
hermes skills tap add myorg/skills-repo | 내 GitHub 저장소를 출처로 추가 |
대화 안 예시로 원문은 /skills install openai/skills/skill-creator --force, /skills reset google-workspace 도 듭니다. 공식 선택 스킬은 대화 안에서도 official/security/1password, official/mcp/fastmcp 같은 주소를 씁니다.
Hub 가 다루는 출처 전체 (Supported hub sources · Integrated hubs and registries)
| 출처 id | 예시 | 설명 |
|---|---|---|
official | official/security/1password | Hermes 와 함께 제공되는 선택 스킬. Hermes 저장소(optional-skills/)에서 관리하며 내장 수준 신뢰로 설치됩니다. |
skills-sh | skills-sh/vercel-labs/agent-skills/vercel-react-best-practices | Vercel 의 공개 스킬 목록 skills.sh. 직접 검색하고, 상세 쪽을 살피고, 별칭 꼴 이름(목록의 이름과 저장소 폴더 이름이 다른 경우)을 풀어 원본 저장소에서 설치합니다. |
well-known | well-known:https://mintlify.com/docs/.well-known/skills/mintlify | 웹사이트가 /.well-known/skills/index.json 으로 직접 내주는 스킬. 중앙 Hub 하나가 아니라 “웹에서 찾는 약속”입니다. 사이트나 문서 주소로 검색합니다. |
github | openai/skills/k8s | GitHub 저장소·경로에서 바로 설치, 그리고 내가 추가한 tap(스킬 출처로 등록한 GitHub 저장소). |
clawhub | 출처별 주소 | ClawHub(clawhub.ai) — 커뮤니티 출처로 연결된 외부 스킬 장터. |
lobehub | 출처별 주소 | LobeHub 공개 목록의 에이전트 항목을 찾아 설치 가능한 Hermes 스킬로 바꿉니다. |
browse-sh | browse-sh/airbnb.com/search-listings-ddgioa | Browserbase 의 browse.sh — 사이트별 브라우저 자동화 SKILL.md 200개 이상(Airbnb, Amazon, arXiv, 12306.cn, Etsy, Xero 등). 주소 꼴은 browse-sh/<hostname>/<task-id>. 신뢰 등급 community. |
url | https://sharethis.chat/SKILL.md | 아무 HTTP(S) 주소의 SKILL.md 를 바로 설치. 주소 자체가 식별자(앞머리 없음). 신뢰 등급은 항상 community. |
GitHub 기본 tap(설정 없이 둘러볼 수 있음): openai/skills, anthropics/skills, huggingface/skills, NVIDIA/skills(NVIDIA 검증 스킬 — 서명 파일 skill.oms.sig 와 관리 문서 skill-card.md 포함), 각 회사가 자기 제품용으로 낸 wandb/skills · qdrant/skills · pinecone-io/skills · makenotion/skills · Airtable/skills · Shopify/Shopify-AI-Toolkit, garrytan/gstack, 그리고 K-Dense-AI/scientific-agent-skills 와 synthetic-sciences/openscience(과학 연구 스킬 약 480개 — 생물정보학, 화학, 물리, ML 학습, 학술 도구. science 분류 하나로 묶임). 과학 스킬은 커뮤니티 신뢰 등급이라 설치마다 보안 검사를 받고, 자체 라이선스가 있는 외부 도구를 감싼 것이 많으니(일부 GPL, KEGG 는 비학술 용도에 상용 라이선스 필요) 스킬마다 전제 조건을 확인하라고 원문은 적습니다.
분류 묶음(skills.sh.json). GitHub tap 은 저장소 맨 위에 skills.sh 형식의 skills.sh.json 파일을 둘 수 있습니다. 그 안의 groupings(제목과 스킬 이름 목록)가 색인을 만들 때 읽혀, 꼬리표에서 짐작한 분류 대신 Skills Hub 쪽의 분류 이름이 됩니다.
웹 주소로 설치할 때 이름을 정하는 순서. ① SKILL.md 머리말의 name:(권장) → ② 주소 경로의 폴더 이름(예: .../my-skill/SKILL.md → my-skill, 쓸 수 있는 이름 꼴 ^[a-z][a-z0-9_-]*$ 일 때) → ③ 터미널이면 물어봄 → ④ 물어볼 수 없는 곳(TUI 안의 /skills install, 게이트웨이, 스크립트)에서는 --name 을 쓰라는 오류.
hermes skills install https://example.com/SKILL.md --name sharethis-chat
/skills install https://example.com/SKILL.md --name sharethis-chat
hermes skills install https://example.com/my-skill/SKILL.md --category productivity
웹 주소 설치는 SKILL.md 와, 그것이 명시적으로 가리키는 references/·templates/·scripts/·assets/·examples/ 아래 파일만 받아 검사 후 설치합니다. 그 사이트의 무관한 파일을 훑거나 복사하지 않습니다. 주소가 설치 식별자로 저장되므로 hermes skills update 가 같은 주소에서 다시 받아 옵니다. browse.sh 스킬의 내용은 목록의 GitHub sourceUrl 이 아니라 스킬별 상세 주소(/api/skills/<slug> → skillMdUrl)에서 가져옵니다.
검색이 느리거나 결과가 없을 때 — 검색 동작과 GitHub 한도
검색 동작. 출처를 지정하지 않은 검색(CLI, TUI, 대시보드)은 외부 등록소들을 담아 둔 중앙 색인의 저장본에서 답합니다. 색인은 주기적으로 다시 만들어지므로, 색인에 결과가 없으면 Hermes 가 skills.sh, ClawHub, LobeHub, well-known 주소에 직접 한 번 더 묻습니다 — 몇 분 전에 올라온 스킬도 나옵니다. 이 추가 조회는 최대 8초까지만 쓰므로 느린 등록소 때문에 오래 기다리게 되지는 않습니다. 내가 추가한 GitHub tap 은 이 추가 조회에 들어가지 않습니다(--source github 로 찾거나 색인이 따라올 때까지 기다림). --source nvidia 같은 공급처 필터(provider filter — 여기서 provider 는 AI 모델 제공자가 아니라 스킬을 낸 곳)도 추가 조회를 일으키지 않습니다(그 등록소들에는 공급처 정보가 없기 때문).
GitHub 호출 한도. Skills Hub 는 GitHub API 를 쓰는데, 로그인하지 않은 사용자는 시간당 60회로 제한됩니다. 설치 한 번에 호출 두 번쯤(저장소와 파일 목록)이 들고, 스킬 파일 자체는 한도에 들지 않는 raw.githubusercontent.com 에서 받습니다. 설치·검색 중 한도 오류가 나면 .env 파일에 GITHUB_TOKEN 을 넣어 한도를 시간당 5,000회로 올립니다. 오류 메시지에도 이 안내가 들어 있습니다.
내 스킬 모음을 tap 으로 공개하기 (Publishing a custom skill tap)
팀·조직·공개용으로 고른 스킬 모음을 나누려면 tap 으로 공개합니다. tap 은 다른 Hermes 사용자가 hermes skills tap add <owner/repo> 로 추가하는 GitHub 저장소입니다. 서버도, 등록소 가입도, 배포 절차도 필요 없고 SKILL.md 파일이 든 폴더면 됩니다. 공개·비공개 저장소 모두 되며 비공개는 GITHUB_TOKEN 이 필요합니다.
owner/repo
├── skills/ # default path; configurable per-tap
│ ├── my-workflow/
│ │ ├── SKILL.md # required
│ │ ├── references/ # optional supporting files
│ │ ├── templates/
│ │ └── scripts/
│ ├── another-skill/
│ │ └── SKILL.md
│ └── third-skill/
│ └── SKILL.md
└── README.md # optional but helpful
- 스킬마다 tap 의 기준 경로(기본
skills/) 아래 자기 폴더를 가집니다. 폴더 이름이 설치할 때 쓰는 이름이 됩니다. - 폴더마다 표준 머리말(
name,description, 선택으로metadata.hermes.tags,version,author,platforms,metadata.hermes.config)이 있는SKILL.md가 있어야 합니다. references/,templates/,scripts/,assets/같은 하위 폴더는 설치할 때 함께 받습니다. 이름이.이나_로 시작하는 폴더는 무시합니다.- Hermes 는 tap 경로의 하위 폴더마다
SKILL.md가 있는지 확인해 스킬을 찾습니다.
가장 작은 예는 my-org/hermes-skills 저장소에 skills/deploy-runbook/SKILL.md 하나만 둔 것입니다. 올린 뒤 다른 사용자는 이렇게 씁니다(출처 추가 → 검색 → 설치).
hermes skills tap add my-org/hermes-skills
hermes skills search deploy
hermes skills install my-org/hermes-skills/deploy-runbook
저장소 전체를 추가하지 않고 스킬 하나만 받으려면 hermes skills install owner/repo/skills/my-workflow 처럼 경로를 끝까지 적습니다.
| 명령 | 뜻 |
|---|---|
hermes skills tap list · /skills tap list | 등록된 tap 과 tap 별 실제 경로 보기 |
hermes skills tap add myorg/skills-repo · /skills tap add myorg/skills-repo | 추가(기본 경로 skills/) |
hermes skills tap remove myorg/skills-repo · /skills tap remove myorg/skills-repo | 제거 |
tap 목록은 ~/.hermes/skills/.hub/taps.json 에 저장됩니다(필요할 때 만들어짐). 스킬이 skills/ 아래에 있지 않으면 이 파일을 직접 고쳐 경로를 바꿉니다 — tap add 명령은 항상 path: "skills/" 로 추가합니다.
{
"taps": [
{"repo": "my-org/platform-docs", "path": "internal/skills/"}
]
}
새 tap 은 기본으로 community 신뢰 등급입니다. 거기서 설치한 스킬은 표준 보안 검사를 거치고 첫 설치 때 외부 출처 경고 창이 뜹니다. 더 높은 신뢰를 주려면 tools/skills_guard.py 의 TRUSTED_REPOS 에 저장소를 넣어야 하며, 이는 Hermes 본체에 변경 요청(PR)을 보내야 하는 일입니다.
스킬을 최신으로 유지하기 — 내가 고친 것은 덮어쓰지 않는다
원본 스킬이 고쳐지면 내 것도 따라가야 합니다. Hermes 는 여기에 한 가지 원칙을 둡니다. 내가 손댄 스킬은 조용히 덮어쓰지 않는다. 받은 뒤 내용이 달라졌는지는 해시(내용이 한 글자만 바뀌어도 달라지는, 지문 같은 값)를 비교해 알아냅니다.
hermes update 때마다 이 판단을 거칩니다.| Hub 로 설치한 스킬 | 딸려 오는 스킬 (bundled) | |
|---|---|---|
| 언제 갱신되나 | 내가 실행할 때 — hermes skills check 로 확인, hermes skills update 로 갱신 | 설치할 때와 hermes update 를 할 때마다 자동 |
| 내가 고쳤다면 | 그 스킬은 건너뜀 | “내가 고친 것(user-modified)”으로 보고 계속 건너뜀 |
| 그래도 원본으로 바꾸려면 | hermes skills update react --force | hermes skills reset google-workspace --restore |
표의 react, google-workspace 는 원문 예시에 나온 스킬 이름입니다. --force 와 --restore 는 내 수정을 지우는 옵션이니 필요한 때만 씁니다.
Hub 스킬 갱신의 세부 (Update lifecycle)
hermes skills check 는 원본이 바뀐 스킬을 알려 주고, hermes skills update 는 바뀐 것만 다시 설치합니다(hermes skills update react 처럼 이름을 붙이면 그 스킬 하나만). Hub 는 저장해 둔 출처 식별자와 지금 원본 묶음의 내용 해시를 비교해 달라졌는지 알아냅니다.
- 설치 폴더가 없거나 폴더가 아닌 항목(
orphaned), 기록된 경로가 안전하지 않거나 풀 수 없는 항목(invalid_install)은 네트워크 요청 없이 건너뜁니다. 폴더가 없는 항목은hermes skills uninstall <name>으로 지울 수 있고, 잘못된 경로는 그 프로필의skills/.hub/lock.json을 살펴 고친 뒤 다시 시도해야 합니다. 자동으로 지워지는 항목은 없습니다. - 확인 전체에 대한 엄격한 제한 시간은 없습니다. 닿지 않거나 느린 출처가 하나 있으면 뒤 항목이 늦어질 수 있습니다.
딸림 스킬 동기화와 hermes skills reset (Bundled skill updates)
Hermes 는 저장소 안 skills/ 에 딸림 스킬을 싣고 옵니다. 설치할 때와 hermes update 때마다 동기화가 이것을 ~/.hermes/skills/ 로 복사하고, ~/.hermes/skills/.bundled_manifest 에 스킬 이름별로 “복사할 때의 내용 해시(origin hash)”를 적어 둡니다. 동기화 때마다 내 사본의 해시를 다시 계산해 이것과 비교합니다(위 그림).
스킬 안에 생기는 실행 중 임시 저장물(__pycache__/, .pytest_cache/, .mypy_cache/, .ruff_cache/, .py 옆의 .pyc)은 해시에 들어가지 않습니다. 그래서 스킬의 보조 스크립트를 실행했다고 “고친 것”으로 찍히거나 hermes skills list-modified / diff 에서 가려지지 않습니다.
한 가지 날카로운 모서리. 딸림 스킬을 고쳤다가 마음을 바꿔 ~/.hermes/hermes-agent/skills/ 에서 원본을 복사해 덮어쓰면, 기록부에는 여전히 예전 해시가 남아 있어 새로 붙여 넣은 내용과 맞지 않습니다. 동기화는 계속 “고친 것”으로 봅니다. 이때 쓰는 비상구가 hermes skills reset 입니다.
| 명령 | 뜻 |
|---|---|
hermes skills reset google-workspace | 안전한 쪽. 이 스킬의 기록만 지웁니다. 지금 사본은 그대로 두고, 다음 동기화가 그것을 새 기준으로 삼아 이후 갱신이 정상으로 돌아옵니다. |
hermes skills reset google-workspace --restore | 완전 복원. 내 사본을 지우고 지금의 딸림 원본을 다시 복사합니다. |
hermes skills reset google-workspace --restore --yes | 확인 질문 없이 복원(스크립트나 TUI 처럼 물어볼 수 없는 곳). |
/skills reset google-workspace · /skills reset google-workspace --restore | 대화 안에서 같은 일. |
프로필마다 자기 HERMES_HOME 아래에 자기 .bundled_manifest 가 있으므로, hermes -p coder skills reset <name> 은 그 프로필에만 영향을 줍니다.
에이전트가 스스로 스킬을 만들고 고친다
Hermes 가 “쓸수록 배운다”고 할 때 그 배움이 쌓이는 곳이 스킬입니다. 에이전트는 skill_manage 라는 도구(tool — 에이전트가 쓰는 기능 하나)로 자기 스킬을 직접 만들고, 고치고, 지울 수 있습니다. 원문은 이것을 에이전트의 절차 기억(procedural memory)이라고 부릅니다 — 간단하지 않은 일의 방법을 알아냈을 때, 다음에 다시 쓰려고 그 방법을 스킬로 남깁니다.
시스템 프롬프트(대화 맨 앞에 깔리는 기본 지시문)가 에이전트에게 “간단하지 않은 일의 방법은 skill_manage 로 기록해 두라”고 일러둡니다. 실제로는 다음 세 경우입니다.
여러 단계짜리 일을 해냈을 때
되풀이할 만한 여러 단계의 작업 방법을 알아낸 경우.
헤맨 끝에 길을 찾았을 때
오류나 막다른 길을 만났다가 되는 방법을 찾은 경우.
내가 방식을 바로잡아 줬을 때
사용자가 에이전트의 접근을 고쳐 준 경우.
스킬에 적히는 것 — 일지가 아니라 교훈
원문은 스킬을 “어떤 종류의 일을, 내가 원하는 대로, 가장 효율적이고 올바르게 하는 방법의 설명서”라고 정의합니다. 누가 쓰든(대화 중의 에이전트, 뒤에서 도는 검토, curator(스킬을 알아서 관리하는 기능)의 정리 작업) 기준은 같습니다. 기록(log)이 아니라 교훈(lesson)을 담는다.
| 스킬에 들어가는 것 | 스킬에 들어가지 않는 것 |
|---|---|
| 순서대로 적은 절차 | 그날 무슨 일이 있었는지 늘어놓는 경위 |
| 실제로 통하는 명령과 도구 사용법 | PR·이슈 번호, 날짜 |
| 결과물이 어떤 모습이어야 하는지 | 대화를 그대로 따온 인용 |
| 시간을 잡아먹는 함정 — 두루 통하는 규칙 하나와 “왜 그런지” 한 마디를, 해당 단계에 한 번만 | 매 차례 이미 읽히는 내용의 반복(저장소의 AGENTS.md, 도구 설명) |
요컨대 그 규칙은 뒷이야기 없이도 혼자 서야 합니다.
스킬 쓰기를 내가 승인하게 바꾸기
기본값에서는 에이전트가 스킬을 자유롭게 씁니다. 한 차례의 일이 끝난 뒤 뒤에서 도는 자기 개선 검토(background review)가 쓰는 것도 포함입니다. 이것이 마음에 걸리면 세 가지 선택지가 있습니다.
아무것도 바꾸지 않으면 이 상태입니다. 에이전트가 배운 것을 바로 스킬로 남기고 고칩니다. 설정으로는 skills.write_approval: false 입니다.
스킬 쓰기 승인(approval — 실행하기 전에 나에게 묻는 것)을 켜면, skill_manage 의 모든 쓰기(만들기·고치기·지우기·파일 추가와 삭제)가 바로 적용되지 않고 대기 목록에 올라갑니다. 원문이 드는 쓸 만한 경우는 배운 것을 잘못 판단하는 작은 모델을 쓸 때, 보안이 중요한 환경, 또는 그저 자기 개선 과정을 눈으로 보고 싶을 때입니다. 검토는 위험한 명령을 승인·거부할 때와 같은 익숙한 방식입니다(9장 「승인」).
| 대화 안 명령 | 뜻 |
|---|---|
/skills approval on | 승인 켜기(off 로 끄기). 설정에 저장됩니다. |
/skills pending | 대기 중인 스킬 쓰기 목록과 한 줄 요지 |
/skills diff <id> | 무엇이 바뀌는지 전체 보기(CLI 나 대시보드에서 보기 좋음) |
/skills approve <id> | 적용(all 로 전부) |
/skills reject <id> | 버리기(all 로 전부) |
대기 중인 쓰기는 ~/.hermes/pending/skills/ 아래에 남아 Hermes 를 다시 시작해도 사라지지 않습니다.
hermes curator lock <skill>
특정 스킬 하나를 에이전트가 아예 못 바꾸게 잠급니다(Desktop 의 잠금 스위치로도 가능). 잠긴 스킬은 여전히 읽히고 자동으로 불려 오지만, 어떤 세션에서도 에이전트의 도구(skill_manage, write_file, patch, terminal)는 그 스킬을 바꾸기를 거부합니다. 내가 직접 고치는 것은 그대로 됩니다. (공식 문서 Locking a skill 쪽 참고 — 이 가이드는 다루지 않음.)
승인 설정 파일과 세부 (skills.write_approval)
skills:
write_approval: false # false = write freely (default) | true = require approval
true 이면 모든 skill_manage 쓰기(create / edit / patch / delete / write_file / remove_file)가 적용 대신 대기 상태가 됩니다. SKILL.md 는 대화 안에서 훑어보기에 너무 크기 때문에, 쓰기가 대화 중에 나왔든 뒤에서 도는 검토에서 나왔든 똑같이 대기시킵니다. 검토는 CLI 와 메신저 모두에서 되지만, 메신저에서는 diff 가 말풍선 길이에 맞춰 잘리므로 전체는 CLI 나 대기 JSON 파일에서 봅니다. 기억 쓰기에도 같은 문이 memory.write_approval 로 있습니다(공식 문서 Controlling memory writes 쪽 참고).
별개의 skills.guard_agent_created 설정은 승인 문이 아니라 내용 검사기(위험한 패턴을 어림으로 찾음)입니다. 둘은 서로 독립입니다(공식 문서 Guard on agent-created skill writes 쪽 참고).
skill_manage 의 동작 목록과 자동 점검 (Actions · linter)
| 동작 | 쓰임 | 주요 값 |
|---|---|---|
create | 새 스킬을 처음부터 만들기 | name, content(SKILL.md 전체), 선택 category |
patch | 필요한 곳만 고치기(권장) | name, old_string, new_string |
patch + content | 구조를 크게 다시 쓰기(SKILL.md 전체 교체. edit 는 옛 이름) | name, content |
delete | 스킬을 통째로 지우기 | name |
write_file | 지원 파일 추가·갱신 | name, file_path, file_content |
remove_file | 지원 파일 지우기 | name, file_path |
필요한 곳만 고치는 patch 가 권장됩니다 — 바뀐 글만 도구 호출에 실리므로 전체를 다시 쓰는 것보다 토큰이 적게 듭니다. 글을 싣는 칸은 동작마다 하나입니다(content → 만들기·전체 교체, new_string → 부분 수정, file_content → write_file). 다른 동작의 칸을 실은 요청(예: create 에 file_content)은 묶음 안의 어떤 동작도 적용되기 전에 거부되고, 글을 어느 칸으로 옮겨야 하는지 알려 주는 오류가 납니다.
자동 점검(linter). skill_manage 는 만들 때, SKILL.md 를 고칠 때, references/ 에 쓸 때 조언용 점검을 돌려 결과를 돌려줍니다. “교훈이지 일지가 아니다”를 위한 규칙이 셋 있습니다: incident-log-shape(본문에 PR·이슈 번호가 빽빽함), references-sprawl(참고 파일이 60개 초과), oversized-body(SKILL.md 본문이 약 24k 글자 초과 — skill_view 는 파일 전체를 불러오고 그것이 세션 끝까지 컨텍스트에 남기 때문). 경고만 할 뿐 쓰기를 막지는 않습니다.
참고 파일 규칙. 항상 지켜야 할 규칙은 SKILL.md 자체에 둡니다. references/ 에는 주제별 이름을 붙인 소수의 파일(판단표, 조리법, 제공자별 특이점)을 두고, 세션마다 파일을 하나씩 쌓지 않고 있는 파일을 그 자리에서 늘려 갑니다.
스킬 폴더 — 어디에 무엇이 놓이나
스킬 하나는 폴더 하나입니다. 폴더 안에 SKILL.md 가 꼭 있어야 하고, 참고 문서나 보조 파일이 곁들여질 수 있습니다. 스킬 폴더들은 분류 폴더(mlops/, devops/ 등) 아래에 모입니다. 원문의 예시 구조입니다.
~/.hermes/skills/ # Single source of truth
├── mlops/ # Category directory
│ ├── axolotl/
│ │ ├── SKILL.md # Main instructions (required)
│ │ ├── references/ # Additional docs
│ │ ├── templates/ # Output formats
│ │ ├── scripts/ # Helper scripts callable from the skill
│ │ ├── examples/ # Referenced example outputs
│ │ └── assets/ # Supplementary files
│ └── vllm/
│ └── SKILL.md
├── devops/
│ └── deploy-k8s/ # Agent-created skill
│ ├── SKILL.md
│ └── references/
├── .hub/ # Skills Hub state
│ ├── lock.json
│ ├── quarantine/
│ └── audit.log
└── .bundled_manifest # Tracks seeded bundled skills
| 이름 | 무엇인가 |
|---|---|
SKILL.md | 주 설명서 — 필수 |
references/ | 추가 문서(2단계에서 하나씩 꺼내 읽는 참고 파일) |
templates/ | 결과물의 틀(출력 형식) |
scripts/ | 스킬이 불러 쓰는 보조 스크립트(작은 프로그램) |
examples/ | 스킬이 가리키는 예시 결과물 |
assets/ | 그 밖의 보조 파일 |
.hub/ | Skills Hub 가 쓰는 상태 — 설치 기록(lock.json), 격리 보관(quarantine/), 검사 기록(audit.log) |
.bundled_manifest | 딸려 온 스킬을 추적하는 기록부(최신으로 유지하기) |
스킬을 찾는 네 곳과 우선순위
Hermes 는 스킬을 최대 네 곳에서 찾을 수 있고, 같은 이름의 스킬이 여러 곳에 있으면 우선순위가 높은 쪽이 어디서나 이깁니다(목록, 슬래시 명령, 예약 작업(cron — 정해 둔 시간에 자동 실행) 모두).
| 곳 | 언제 쓰나 |
|---|---|
| ① 프로젝트 스킬 | 저장소(repo — 프로젝트 파일과 변경 이력을 담은 폴더)가 자기 스킬을 싣고 다닐 때. 내가 그 저장소를 신뢰한다고 해 줘야 불러옵니다. |
| ② 내 기본 폴더 | 항상. 딸림·Hub·에이전트가 만든 스킬이 모두 여기 놓입니다. |
| ③ 새 스킬 저장 폴더 | 에이전트가 만드는 새 스킬을 다른 곳(공유 폴더, git(파일 변경 이력을 관리하는 도구)으로 관리하는 저장소 등)에 쌓고 싶을 때. |
| ④ 외부 스킬 폴더 | ~/.agents/skills/ 처럼 Hermes 밖에서 관리하는 스킬 폴더도 함께 훑게 할 때. |
③④는 ~/.hermes/config.yaml(3장 「설정 파일」)의 skills 아래에 적습니다. 자세한 설정은 아래 접힌 상자에 있습니다.
프로젝트 스킬과 신뢰 (Project-Local Skills)
git 저장소 안에서 Hermes 를 시작하면 다음 두 곳에서 스킬을 찾습니다. 프로젝트 맨 위(project root)는 .git 이 들어 있는 가장 가까운 윗폴더입니다(worktree 와 submodule 도 해당).
<project-root>/.hermes/skills/ # Hermes-native location
<project-root>/.agents/skills/ # cross-tool convention (shared with other agent CLIs)
신뢰하기. 스킬은 에이전트가 따르는 절차 문서이므로, Hermes 는 아무 저장소에서나 자동으로 불러오지 않습니다. 프로젝트 스킬이 있는 저장소에서 처음 실행하면 시작 화면에 이런 알림이 뜹니다.
◆ 3 project skill(s) found in /home/you/myproject but not loaded — run `hermes skills trust` to enable them.
뜻: 프로젝트 스킬 3개를 찾았지만 불러오지 않았습니다 — 켜려면 `hermes skills trust` 를 실행하세요.
hermes skills trust # trust the current repo
hermes skills trust ~/myproject # or explicitly
hermes skills untrust # revoke
차례로: 지금 저장소 신뢰 · 경로를 적어 신뢰 · 신뢰 취소. 신뢰한 저장소는 config.yaml 의 skills.trusted_project_dirs 에 저장됩니다. skills.project_discovery: false 로 두면 기능 전체가 꺼집니다(찾지도, 알리지도 않음).
우선순위. 프로젝트 스킬이 가장 높습니다. 프로젝트의 deploy 스킬은 그 저장소 안의 세션에서 같은 이름의 내 스킬·딸림 스킬을 이깁니다 — 내 전체 프로필은 건드리지 않고 저장소가 자기 마당에서 이기게 하려는 것입니다. 에이전트의 스킬 목록에는 [project] 표시가 붙어 출처가 보입니다. 외부 폴더와 마찬가지로 저장소 소유로 취급되어 curator 가 고치지 않으며, 에이전트가 새로 만드는 스킬은 항상 ~/.hermes/skills/ 로 갑니다.
불러올 때마다 검사해 격리(Scan-time quarantine). 신뢰는 저장소 단위의 결정이지만 저장소의 스킬 내용은 git pull 때마다 바뀝니다. 그래서 프로젝트 스킬은 목록에 들어가기 전에 Skills Hub 설치와 같은 보안 검사기로 매번 검사합니다. 판정이 dangerous(지시 끼워 넣기, 인증 정보 빼돌리는 명령, 숨긴 글 수법)인 스킬은 격리되어 목록·skills_list·슬래시 명령에 나타나지 않고, 이름으로 불러도 이유를 설명하는 오류와 함께 거부됩니다. 검사 결과는 ~/.hermes/cache/project_skill_scans/(저장소 안이 아님)에 내용 해시별로 저장되고, 스킬 내용이 바뀌면 자동으로 다시 검사합니다.
사람이 지켜보지 않는 실행(cron, API, ACP). 예약 작업 같은 곳은 내가 대화형으로 내린 신뢰 결정을 물려받습니다 — 묻지도, 스스로 신뢰하지도 않습니다. 프로젝트 위치는 그 실행의 작업 폴더로 정해지므로, 신뢰한 저장소 안에서 도는 예약 작업만 그 저장소의 프로젝트 스킬을 불러옵니다. TUI 와 Desktop 에서는 세션마다의 작업 공간(사이드바에 보이는 폴더)을 따릅니다 — 신뢰한 저장소 안에서 hermes --tui 를 시작하면 terminal.cwd 가 기본값 . 이어도 프로젝트 스킬이 슬래시 명령으로 등록되고, 두 저장소에 연 두 세션은 각자 자기 것을 봅니다.
외부 스킬 폴더 (External Skill Directories)
skills:
external_dirs:
- ~/.agents/skills
- /home/shared/team-skills
- ${SKILLS_REPO}/skills
경로에는 ~ 와 ${VAR} 꼴 환경 변수를 쓸 수 있습니다.
- 새로 만들 때는 내 폴더에, 고칠 때는 있는 자리에서. 에이전트가 새로 만드는 스킬은
~/.hermes/skills/(또는 정해 둔skills.create_dir)에 쓰입니다. 이미 있는 스킬은 발견된 자리에서 고쳐집니다 — 외부 폴더 안의 스킬도 포함입니다(skill_manage의patch,write_file,remove_file,delete). - 외부 폴더는 쓰기 보호 경계가 아닙니다. Hermes 가 그 폴더에 쓸 수 있으면 에이전트의 스킬 수정이 그 파일을 바꿀 수 있습니다. 공유 스킬을 읽기 전용으로 지켜야 한다면 파일 권한이나 별도 프로필·툴셋 구성을 씁니다.
- 완전히 같은 대접. 외부 스킬도 시스템 프롬프트의 목록,
skills_list,skill_view,/스킬이름슬래시 명령에 똑같이 나옵니다. - 없는 경로는 조용히 건너뜁니다. 모든 컴퓨터에 있지는 않은 선택적 공유 폴더에 쓸모가 있습니다.
원문 예: 내 폴더에 devops/deploy-k8s, mlops/axolotl 이 있고 ~/.agents/skills/ 에 my-custom-workflow, team-conventions 가 있으면 네 스킬이 모두 목록에 나옵니다. 내 폴더에 my-custom-workflow 를 새로 만들면 그것이 외부 쪽 같은 이름을 가립니다.
새 스킬이 쓰이는 곳 바꾸기 (Redirecting Skill Creation — skills.create_dir)
skills:
create_dir: /opt/brain/skills
기본으로 에이전트는 새 스킬을 프로필의 ~/.hermes/skills/ 에 씁니다. 다른 곳 — 공유하는 “두뇌” 폴더, git 으로 관리하는 저장소, 여러 대가 함께 쓰는 저장 공간 — 에 쌓이게 하려면 create_dir 을 정합니다.
skill_manage의create가 거기에 씁니다(분류 폴더 포함). 폴더가 없으면 처음 쓸 때 만들어집니다.- 에이전트에게 주는 안내문도 설정을 따라갑니다 — 스킬 만드는 경로를 말하는 모든 안내에 정해 둔 폴더가 나타나므로 따로 손쓸 것이 없습니다.
- 그 폴더의 스킬은 내 폴더와 함께 훑어져 목록,
skills_list,skill_view, 슬래시 명령에 나오고 고치거나 지울 수 있습니다. - 나머지는 그대로입니다. 있는 스킬은 있는 자리에서 고쳐지고, 딸림 스킬 동기화·Hub·curator 는 계속 프로필의 기본 폴더에서 일합니다.
경로에 ~ 와 ${VAR} 를 쓸 수 있고, 상대 경로는 Hermes 홈 폴더를 기준으로 풉니다. create_dir 을 기본 폴더로 정하는 것은 정하지 않은 것과 같습니다.
이름이 겹칠 때 · 외부에서 설치할 때 복사되는 파일 (Duplicate skill names)
- 폴더끼리 겹칠 때 — 우선순위가 높은 폴더가 이깁니다(프로젝트 → 내 폴더 →
skills.create_dir→external_dirs). 상대 경로까지 같아도 마찬가지입니다(productivity/xdup이 내 폴더와 외부에 있으면 내 것을 불러옴). 가려진 사본은 숨겨지고 경고가 기록됩니다. 이 규칙은 스킬 목록,skills_list,hermes skills list,skill_view, 슬래시 명령,-s미리 불러오기, cron 에 똑같이 적용됩니다. - 한 폴더 안에서 겹칠 때 — 이름이 같은 서로 다른 스킬 둘 사이에서는 짐작하지 않습니다. 둘 다 정확한 상대 경로(예:
a/one,b/two)로 나열되고, 이름만으로 부르면Ambiguous skill name dup-demo: use one of a/one, b/two로 실패합니다.hermes -s dup-demo와 예약 작업도 같은 메시지를 냅니다. 한 스킬의 똑같은 사본(심볼릭 링크나 한 글자도 다르지 않은 복사본)은 가장 얕은 경로로 정해집니다. - 플러그인 스킬은
plugin:skill꼴의 자기 이름을 쓰므로 이들과 부딪히지 않습니다.
외부 설치 때 복사되는 것. 웹 주소·GitHub 에서 설치하면 SKILL.md 와, 그것이 가리키는 references/·templates/·scripts/·assets/·examples/ 아래의 바로 그 파일들만 복사됩니다. 가리키지 않은 저장소 파일은 복사하지 않습니다. Hermes 는 격리해 둔 묶음 전체를 검사하고, 출처 주소·정확한 내용 해시·검사기 버전·발견 사항·시각·새로 검사했는지 저장본을 썼는지를 skills/.hub/lock.json 에 기록합니다.
스킬 번들 — 여러 스킬을 명령 하나로
스킬 번들(skill bundle)은 여러 스킬을 슬래시 명령 하나로 묶는 아주 작은 설정 파일입니다. /번들이름 을 실행하면 번들에 적힌 스킬이 한꺼번에 불려 옵니다. 어떤 일에 늘 같은 스킬 묶음이 필요할 때 씁니다.
backend-dev 입니다.만들 때는 터미널에서 번들 이름과 넣을 스킬을 적습니다. 원문 예시입니다.
hermes bundles create backend-dev \
--skill github-code-review \
--skill test-driven-development \
--skill github-pr-workflow \
-d "Backend feature work — review, test, PR workflow"
뜻: 세 스킬을 묶어 backend-dev 라는 번들을 만든다. -d 뒤는 설명(“백엔드 기능 작업 — 검토, 시험, PR 절차”). 줄 끝의 \ 는 명령이 다음 줄로 이어진다는 표시입니다.
그다음 CLI 나 메신저에서 /backend-dev refactor the auth middleware(뜻: 인증 처리 부분을 손봐 줘)처럼 씁니다. 대화 안에서 /bundles 를 넣으면 설치된 번들과 그 안의 스킬이 나열됩니다.
| 알아 둘 동작 | 내용 |
|---|---|
| 이름이 겹치면 번들이 이김 | research 라는 번들과 스킬이 둘 다 있으면 /research 는 번들을 부릅니다. 그 이름을 붙인 것이 곧 번들을 택한 것이라는, 의도된 동작입니다. |
| 없는 스킬은 건너뜀 | 번들에 적힌 스킬이 설치되어 있지 않아도 실패하지 않습니다. 찾은 스킬만 불러오고, 무엇을 건너뛰었는지 에이전트에게 알려 줍니다. |
| 어디서나 동작 | CLI, TUI, 대시보드 대화, 모든 게이트웨이 플랫폼(Telegram, Discord, Slack 등). |
| 번들이 스킬을 설치해 주지는 않음 | 번들은 별명일 뿐입니다. 스킬 자체는 ~/.hermes/skills/ 나 외부 스킬 폴더에 이미 있어야 합니다. |
/backend-dev, /release-prep, /incident-response), /스킬 을 여러 개 이어 치는 것보다 간단히 기억하고 싶을 때, 번들 파일을 팀이 함께 쓰는 저장소에 넣어 같은 스킬 묶음을 팀 전체가 쓰게 하고 싶을 때입니다.
번들 파일 형식과 관리 명령 (YAML schema · Managing bundles)
번들은 ~/.hermes/skill-bundles/<slug>.yaml 에 있는 YAML(들여쓰기로 구조를 나타내는 설정 글 형식) 파일입니다.
name: backend-dev
description: Backend feature work — review, test, PR workflow.
skills:
- github-code-review
- test-driven-development
- github-pr-workflow
instruction: |
Always start by writing failing tests, then implement.
Open the PR through the standard workflow with co-author tags.
| 항목 | 뜻 |
|---|---|
name (선택) | 번들의 표시 이름. 적지 않으면 파일 이름을 씁니다. 슬래시 명령용으로 붙임표 꼴로 다듬어집니다(Backend Dev → /backend-dev). |
description (선택) | /bundles 와 hermes bundles list 에 보이는 짧은 설명. |
skills (필수, 비어 있으면 안 됨) | 스킬 이름, 또는 스킬 폴더 기준 상대 경로. /스킬이름 에 쓰는 것과 같은 이름을 적습니다. |
instruction (선택) | 불러온 스킬 내용 앞에 붙는 추가 지침. “우리는 이 스킬들을 늘 이렇게 함께 쓴다”를 적어 두는 데 씁니다. 위 예는 “항상 실패하는 테스트부터 쓰고 구현한다. PR 은 표준 절차로, 공동 작성자 표시와 함께 연다”입니다. |
| 명령 | 뜻 |
|---|---|
hermes bundles list | 설치된 번들 모두 보기 |
hermes bundles show backend-dev | 번들 하나 살펴보기 |
hermes bundles create research | 물어 가며 만들기(--skill 을 빼면 스킬을 한 줄에 하나씩 입력) |
hermes bundles create backend-dev --skill ... --force | 있는 번들 덮어쓰기 |
hermes bundles delete backend-dev | 번들 지우기 |
hermes bundles reload | ~/.hermes/skill-bundles/ 를 다시 훑고 바뀐 것 알리기 |
번들은 프롬프트 캐시를 깨지 않습니다. /스킬이름 과 마찬가지로 부를 때 새 사용자 메시지를 만들 뿐 시스템 프롬프트를 바꾸지 않습니다. 어디서나 동작하는 것은 번들 명령의 처리가 개별 스킬 명령과 같은 한 곳에서 이루어지기 때문입니다. 팀에 돌릴 때는 번들 YAML 을 공유 dotfiles 저장소에 넣고 ~/.hermes/skill-bundles/ 로 심볼릭 링크를 겁니다.
안전 — 보안 검사 · 신뢰 등급 · 승인
스킬은 에이전트가 그대로 따르는 절차 문서입니다. 그래서 나쁜 스킬 하나는 나쁜 지시서 하나와 같습니다. Hermes 는 스킬이 들어오는 길마다 문을 하나씩 세워 두었습니다. 먼저 Skills Hub 설치 때의 보안 검사입니다 — Hub 로 설치하는 스킬은 모두 거칩니다.
검사기가 찾는 것으로 원문은 다음을 듭니다: 정보를 밖으로 빼돌리는 것(data exfiltration), 프롬프트 인젝션(prompt injection — 글 속에 숨긴 지시로 AI 를 속이는 수법), 파괴적인 명령, 공급망 위험 신호(supply-chain signals — 스킬이 끌어오는 외부 재료 쪽의 수상한 징후), 그 밖의 위협.
| 신뢰 등급 | 어떤 출처인가 | 적용되는 정책 |
|---|---|---|
builtin | Hermes 에 딸려 오는 스킬 | 항상 신뢰 |
official | Hermes 저장소의 optional-skills/ (공식 선택 스킬) | 내장 수준 신뢰. 외부 출처 경고 창이 뜨지 않음 |
trusted | 신뢰하는 등록소·저장소 — openai/skills, anthropics/skills, huggingface/skills, NVIDIA/skills 등 | community 출처보다 너그러운 정책 |
community | 그 밖의 모든 것 — skills.sh, well-known 주소, 내가 추가한 GitHub 저장소, 대부분의 장터 | 위험하지 않은 발견은 --force 로 넘길 수 있음. dangerous 판정은 계속 막힘 |
--force 가 하는 일과 못 하는 일
--force 는 외부 스킬을 내가 직접 읽어 본 뒤, 위험하지 않은 정책 차단을 넘기고 싶을 때 씁니다. 주의·경고 수준의 발견으로 막힌 것은 넘길 수 있지만, dangerous 판정은 넘기지 못합니다. 먼저 hermes skills inspect … 로 내용을 확인하세요.
스킬이 들어오는 다른 두 길에도 문이 있습니다.
내려받은 프로젝트 저장소 안의 스킬
자동으로 불러오지 않습니다. 내가 hermes skills trust 로 신뢰한 뒤에도 불러올 때마다 같은 검사를 받고, dangerous 판정이면 격리됩니다 — 스킬 폴더.
에이전트가 스스로 쓰는 스킬
기본은 자유입니다. /skills approval on 으로 내 승인을 거치게 하거나 스킬 하나를 잠글 수 있습니다 — 에이전트가 만드는 스킬.
Hermes 전체의 안전장치(위험한 명령 승인, 되돌리기)는 9장에서 다룹니다.
미리 보기에 나오는 원본 정보 · 전체 신뢰 저장소 목록 (Security scanning and --force · Trust levels)
hermes skills inspect ... 는 정보가 있으면 원본 쪽 자료도 보여 줍니다: 저장소 주소, skills.sh 상세 쪽 주소, 설치 명령, 주간 설치 수, 원본 쪽 보안 점검 상태, well-known 색인·주소.
hermes skills install skills-sh/anthropics/skills/pdf --force
공식 선택 스킬(official/...)은 내장 수준 신뢰로 취급되어 외부 출처 경고 창이 뜨지 않습니다. trusted 등급에는 표의 네 곳 말고도 wandb/skills, qdrant/skills, pinecone-io/skills, makenotion/skills, Airtable/skills, Shopify/Shopify-AI-Toolkit 가 들어 있습니다. 설치한 Hub 스킬 전체를 다시 검사하려면 hermes skills audit 을 씁니다.
두 번째 의견 — NVIDIA SkillEvaluator 조언용 검사 (Advisory SkillEvaluator scan)
설치 정책을 집행하는 내장 검사기와 별도로, Hermes 는 Hub 설치 때마다 NVIDIA SkillEvaluator 의 Tier 1 점검을 “두 번째 의견”으로 돌릴 수 있습니다. Tier 1 은 결과가 늘 같고(deterministic) 열쇠(API 키)가 필요 없습니다 — 개인 정보 탐지(새어 나간 이메일, 개인 경로, 접속 문자열), 유니코드로 숨긴 글 탐지, 스크립트 점검, 라이선스 준수, 그리고 NVIDIA SkillSpector 를 통한 정적 보안 검사입니다.
이 검사는 조언용입니다. 발견 사항은 설치 확인 전에 파일·줄 번호와 함께 출력되고 설치는 계속됩니다. 진짜 인증 정보처럼 보이는 것(개인 키, 클라우드 접근 키, 토큰, 인증 정보가 든 접속 문자열)은 빨갛게 강조됩니다. 개인 정보류 발견은 참고용이며, 알려진 오탐(git@github.com SSH 표기, 문서의 예시 이메일 등)이 있어 아무것도 막지 않습니다.
uv tool install --python 3.13 \
"skillevaluator @ git+https://github.com/NVIDIA/SkillEvaluator.git@v0.1.0"
uv tool install "git+https://github.com/NVIDIA/SkillSpector.git@v2.9.5"
켜려면 위의 선택 검사 프로그램 둘을 설치합니다(둘째가 보안 점검을 맡으며, 없으면 그 점검은 “not run” 으로만 나옵니다). 프로그램이 PATH 에 없으면 검사는 조용히 건너뜁니다. 완전히 끄려면 다음과 같이 설정합니다.
skills:
tier1_advisory: false
대시보드의 Browse-hub 검사 단추도 내장 검사기의 판정과 함께 같은 조언 자료(tier1 항목)를 돌려줍니다.
- 스킬은 일하는 방법을 적은 설명서(
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판정은 넘기지 못합니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/features/skills (수집일 2026-11-09 의 공식 문서 · 원문 파일 sources/raw/user-guide_features_skills.md)
예약 작업과 위임
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 에게 줄 지시문)와 붙인 스킬에 모두 들어 있어야 합니다. |
| 예약 작업 안에서는 예약 작업을 또 만들 수 없다 | 예약이 끝없이 불어나는 것을 막기 위해, 예약으로 실행된 세션에서는 예약 관리 도구가 꺼져 있습니다(설정으로 풀 수 있음 — 관리 소절의 접힌 상자). |
스케줄러가 한 번 확인할 때 하는 일 · 도구 이름
확인 한 번(tick)의 순서: ① ~/.hermes/cron/jobs.json 에서 목록을 읽음(~ 는 내 홈 폴더) ② 작업별 다음 실행 시각(next_run_at)을 지금과 견줌 ③ 때가 된 작업마다 새 세션 시작 ④ 붙인 스킬 넣기 ⑤ 프롬프트를 끝까지 실행 ⑥ 마지막 답 전달 ⑦ 실행 기록과 다음 시각 갱신. 잠금 파일 ~/.hermes/cron/.tick.lock 이 같은 작업이 두 번 도는 것을 막습니다.
원문 설명 글은 예약 관리 도구를 cronjob_manage 로, 예시 코드는 cronjob(action="create", …) 로 적습니다. 동작(action)을 골라 쓰는 도구 하나입니다. 외부 이벤트(webhook)로 작업을 실행시키는 방법은 공식 문서 Event-Triggered Cron Jobs 쪽 참고(이 가이드는 다루지 않음).
예약 작업 만들기 — 세 가지 방법
예약 작업 하나는 일정(언제)과 프롬프트(그때 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장).
스킬을 붙인 예약 작업 · 프로젝트 폴더 안에서 실행하기
| 스킬 하나·여러 개 | 도구 호출에서는 skill="blogwatcher" 또는 skills=["blogwatcher", "maps"], 명령에서는 --skill 을 여러 번. 적힌 순서대로 읽히고 프롬프트는 그 위에 얹는 지시가 됩니다. 스킬 설정값이 담긴 [Skill config ...] 블록도 함께 읽힙니다. |
--workdir | 기본은 어느 프로젝트에도 속하지 않고 게이트웨이가 시작된 폴더에서 돕니다. 바꾸려면 만들 때 --workdir /home/me/projects/acme 처럼 폴더를 줍니다(도구 호출에서는 workdir=). |
| workdir 를 주면 | 그 폴더의 맥락 파일(대화마다 자동으로 읽히는 파일 — AGENTS.md·CLAUDE.md·.cursorrules)이 읽히고, 터미널·파일·코드 실행 도구가 그 폴더를 기준으로 돕니다. |
| 조건 · 지우기 | 실제로 있는 폴더의 절대 경로만 됩니다. --workdir "" 로 지웁니다. 동시에 도는 예약 작업 수는 cron.max_parallel_jobs 로 줄입니다. |
일정 적는 법 — 한 번만 · 간격 · 요일과 시각 · cron 표현식
일정은 네 가지 모양으로 적을 수 있습니다. 앞의 셋은 영어 낱말로, 마지막은 숫자 칸으로 적습니다.
| 적는 말 | 뜻 |
|---|---|
in 30m | 30분 뒤에 한 번 |
in 1d | 하루 뒤에 한 번 |
2026-03-15T09:00:00 | 2026년 3월 15일 오전 9시에 한 번 (날짜와 시각을 직접 적는 방식) |
| 적는 말 | 뜻 |
|---|---|
every 30m | 30분마다 |
every 2h | 2시간마다 |
every hour | 1시간마다 (숫자가 없으면 1) |
30m | 30분마다 — in 없이 시간만 쓰면 되풀이입니다 |
in 30m 은 30분 뒤 한 번, 30m 은 30분마다 계속입니다.| 적는 말 | 뜻 |
|---|---|
every monday 9am | 매주 월요일 오전 9시 |
every day at 9am · daily at 7am | 매일 오전 9시 · 매일 오전 7시 |
weekdays at 9am | 평일 오전 9시 |
weekends at 10am | 토·일 오전 10시 |
monday, wednesday at 9am | 월·수 오전 9시 |
시각은 9am, 9:30pm, 14:00, at 7(24시간제 숫자만), noon(정오), midnight(자정)으로 적을 수 있습니다. 이 모양들은 안에서 cron 표현식으로 바뀝니다.
| 표현식 | 뜻 |
|---|---|
0 9 * * * | 매일 오전 9시 |
0 9 * * 1-5 · 0 9 * * MON-FRI | 평일 오전 9시 (요일·달 이름도 쓸 수 있음) |
0 */6 * * * | 6시간마다 |
30 8 1 * * | 매달 1일 오전 8시 30분 |
0 0 * * 0 | 매주 일요일 자정 |
원문은 칸의 뜻을 따로 풀지 않습니다. 예시를 견주면 첫 칸이 분, 둘째가 시, 셋째가 날짜, 다섯째가 요일로 읽힙니다. 낯설면 앞의 세 탭 방식으로 충분합니다.
몇 번 도나. 일정의 종류에 따라 기본 횟수가 정해집니다.
| 일정 종류 | 기본 횟수 | 동작 |
|---|---|---|
한 번만 (in 30m, 날짜·시각) | 1 | 한 번 돌고 끝 |
간격 (every 2h) | 계속 | 지울 때까지 돎 |
| cron 표현식 | 계속 | 지울 때까지 돎 |
횟수를 직접 정할 수도 있습니다. 도구 호출에 repeat=5 를 주면 “2시간마다, 다섯 번만”이 됩니다.
시간대 · 놓친 실행을 늦게라도 돌리는 범위
| 시간대 (Per-job timezone) | cron 표현식은 기본으로 프로필(설정·기억·세션을 따로 쓰는 Hermes 환경)의 시간대(config.yaml 의 timezone:)로 읽습니다. 작업별로 고정하려면 --timezone Asia/Hong_Kong. 그 시간대 시계로 돌고 서머타임이 바뀌어도 같은 시각을 지킵니다. --timezone "" 로 해제. 간격 일정에는 영향이 없습니다. |
| 날짜·시각을 직접 적은 경우 | 시간대 표시가 없는 2026-06-01T09:00:00 은 그 작업의 시간대로 읽습니다. |
| 따라잡기 범위 (Catch-up window) | 놓친 실행은 이 범위 안에서만 늦게 돕니다. 기본은 주기의 절반(최소 2분·최대 2시간). 작업별로 --grace-minutes 0~1440: 0 은 놓치면 건너뜀, 180 은 3시간 늦게까지, "" 는 기본으로. cron 표현식 일정에만 적용됩니다. |
결과를 어디로 받나
예약 작업이 끝나면 에이전트의 마지막 답이 자동으로 정해 둔 곳(deliver)에 전달됩니다. 에이전트가 스스로 메시지를 보내는 것이 아니므로, 프롬프트에 “보내 줘”를 처리할 방법을 따로 적을 필요가 없습니다. 받는 사람이 읽을 내용이 곧 마지막 답입니다.
~/.hermes/cron/output/ 에도 남습니다.그림에 없는, 더 콕 집어 적는 법입니다. 홈 채널(home channel — 그 메신저에서 Hermes 가 기본으로 보내는 대화방)은 8장에서 정합니다.
| 값 | 어디로 가나 |
|---|---|
"telegram" | Telegram 홈 채널 |
"telegram:123456" | ID 로 지정한 특정 Telegram 대화 |
"discord:#engineering" | 이름으로 지정한 특정 Discord 채널 |
"telegram,discord" | 쉼표로 이어 여러 곳에 한꺼번에 |
받은 메시지는 기본으로 머리말과 꼬리말에 싸여 옵니다. 예약 작업이 보낸 것임을 알아보라는 표시입니다.
Cronjob Response: Morning feeds ------------- <agent output here> Note: The agent cannot see this message, and therefore cannot respond to it.
맨 아래 줄은 “에이전트는 이 메시지를 볼 수 없어 답할 수 없습니다”라는 뜻입니다. 기본 상태에서 예약 결과는 보내고 끝이라, 답장해도 에이전트는 자기가 무엇을 보냈는지 모릅니다. 답장으로 이어 가려면 접힌 상자의 “이어서 대화하기”를 켭니다.
[SILENT] 가 들어 있으면 전달이 통째로 생략됩니다(결과는 내 컴퓨터에 기록으로 남음). 살펴보는 일을 예약할 때 프롬프트에 이렇게 적습니다: Check if nginx is running. If everything is healthy, respond with only [SILENT]. Otherwise, report the issue. 뜻: nginx 가 도는지 확인하고, 다 정상이면 [SILENT] 만 답하고, 아니면 문제를 보고해 줘. — 실패한 실행은 이 표시와 상관없이 항상 알림이 옵니다.
받을 곳 전체 목록 · 전달 상태 · 이어서 대화하기 · 그 밖의 전달 설정
그 밖의 값: "telegram:-100123:17585"(특정 Telegram 토픽 — chat_id:thread_id), 홈 채널로 가는 discord · slack · mattermost · whatsapp · signal · matrix, 그리고 email · sms(Twilio) · homeassistant(플러그인 필요) · dingtalk · feishu · wecom · weixin · bluebubbles(iMessage) · qqbot, Bot Chat 으로 가는 "bot-chat"·"bot-chat:research", 섞어 쓰는 "origin,all"(같은 곳은 한 번만). all 은 실행하는 순간에 풀리므로 나중에 연결한 메신저도 포함되고, 홈 채널이 하나도 없으면 전달 실패로 기록됩니다.
| 전달 실패는 따로 기록 | 일은 끝났는데 결과가 닿지 못하면 last_status: delivery_failed, 이유는 last_delivery_error. 연속 실패 횟수에는 세지 않습니다. |
| 머리말 빼기 · 알림 소리 | cron: wrap_response: false 는 답만 보냅니다. cron: delivery: notify: false 는 알림 없이 조용히 보냅니다(기본 true). |
| 이어서 대화하기 (Continuable jobs) | 기본 꺼짐. cron: mirror_delivery: true 또는 작업별 attach_to_session. 스레드가 있는 메신저는 전달마다 전용 스레드를 열고, 없는 곳(WhatsApp·Signal·SMS)은 그 1:1 대화에 결과를 넣어 답장이 이어지게 합니다. all 로 뿌린 것은 대상이 아닙니다. |
| Telegram 예약 전용 토픽 | 토픽 모드에서는 첫 화면에 온 예약 메시지에 답장할 수 없습니다. 봇 대화에 토픽을 만들고 그 링크 끝의 숫자를 .env 의 TELEGRAM_CRON_THREAD_ID 에 넣습니다. |
| Bot Chat 전달과 완료 (Bot Chat delivery completion) | 결과가 봇에게 들어온 메시지로 전달되어 봇이 읽고 반응합니다(전달 한 번 = 봇의 한 턴). 같은 컴퓨터의 프로필만 되고 all 에는 들어가지 않습니다. 접수만 된 동안은 delivery_outcome=queued, 대상 게이트웨이가 꺼져 있으면 delivery_failed 로 남습니다. |
| 제한 시간 (Media send · Standalone send timeout) | 첨부 하나 올리기 기본 300초(cron.media_send_timeout_seconds), 게이트웨이 없이 보내는 단독 전송 기본 60초(cron.standalone_send_timeout_seconds). |
[CRON_FAILURE] | 턴은 끝났지만 일이 안 됐을 때, 답의 첫 줄에 단독으로 쓰면 그 실행이 실패로 기록되고 실패 알림이 갑니다. |
관리하기 — 보기 · 멈추기 · 고치기 · 지우기
한 번 만든 예약 작업은 지우고 새로 만들 필요 없이 그대로 두고 다룰 수 있습니다. 대화 안에서는 /cron …, 터미널에서는 hermes cron … 을 쓰고, 말로 “그 아침 뉴스 예약을 잠깐 멈춰 줘”처럼 부탁해도 Hermes 가 같은 일을 합니다.
| 하고 싶은 일 | 대화 안 | 터미널 | 무슨 일이 일어나나 |
|---|---|---|---|
| 목록 보기 | /cron list | hermes cron list | 작업과 마지막 실행 상태가 보입니다. |
| 잠시 멈추기 | /cron pause <job_id> | hermes cron pause … | 작업은 남기고 예약만 멈춥니다. |
| 다시 시작 | /cron resume <job_id> | hermes cron resume … | 다시 예약합니다. 멈춘 동안 차례가 지나갔다면 다음 확인 때 한 번 따라잡아 실행합니다. |
| 지금 한 번 실행 | /cron run <job_id> | hermes cron run … | 다음 확인 때 실행합니다. 덤으로 한 번 도는 것이라 원래 예약과 남은 횟수는 그대로입니다. |
| 돌고 있는 실행 멈추기 | — | hermes cron cancel … | 지금 도는 그 한 번만 멈춥니다. 일정은 그대로입니다. |
| 고치기 | /cron edit <job_id> … | hermes cron edit … | 일정·프롬프트·스킬·전달 위치 등을 바꿉니다. |
| 지우기 | /cron remove <job_id> | hermes cron remove … | 완전히 지웁니다. 그때 돌고 있던 실행도 멈춥니다. |
고칠 때는 바꿀 것만 적습니다.
/cron edit <job_id> --schedule "every 4h"
/cron edit <job_id> --prompt "Use the revised task"
뜻: 일정을 4시간마다로 바꾸기 / 프롬프트를 새 지시문으로 바꾸기.
ID 대신 이름으로
<job_id> 자리에 작업 이름을 넣어도 됩니다(대소문자 구분 없음). 같은 이름이 여럿이면 명령을 거부하고 후보 ID 를 보여 줍니다.
pause 와 cancel 은 다릅니다
pause 는 앞으로의 실행을 막을 뿐, 이미 돌고 있는 실행은 끝나거나 제한 시간에 걸릴 때까지 계속됩니다. 지금 도는 것을 멈추려면 cancel 입니다. 멈춘다고 이미 해 버린 일이 되돌려지지는 않습니다.
어디에 저장되나
작업 목록은 ~/.hermes/cron/jobs.json, 실행 결과는 ~/.hermes/cron/output/{job_id}/{timestamp}.md 에 남습니다. hermes update, 게이트웨이 재시작, 컴퓨터 재부팅을 거쳐도 작업은 사라지지 않습니다.
hermes cron edit, /cron 으로 고칩니다. 파일을 직접 고치면 저장되지 않았는데도 모르고 지나갈 수 있다고 원문은 경고합니다.
전부 멈추기 · 실행 취소 상세 · 멈춘 채로 만들기 · tick
hermes pause [--reason …] | 전체 비상 정지(hermes resume 으로 해제). 새 예약 실행이 시작되지 않고, 이미 도는 것은 그대로 두며, 밀린 일은 해제 뒤 따라잡습니다. 손으로 돌리는 것은 정지 중에도 실행됩니다. |
hermes cron cancel … [--reason "…"] | 스크립트 작업은 딸린 프로세스까지 종료하고, 에이전트 작업은 다음 확인 지점에서 턴을 끊습니다. cancelled 로 기록되며 실패 알림도 연속 실패도 아닙니다. |
--paused [--paused-reason "…"] | 처음부터 멈춘 상태로 만듭니다. hermes cron resume 으로 시작합니다. 손으로 돌리는 것까지 막는 보안 장치는 아닙니다. |
hermes cron tick | 확인을 한 번만 하고 끝냅니다(바깥 스케줄러용). 게이트웨이가 꺼져 있으면 에이전트 작업은 건너뛰고, 스크립트만 도는 작업은 돕니다. |
어떤 모델로 도나 — 고정(pin) · 생각 깊이 · 쓰는 툴셋
실행하는 순간 모델(에이전트의 두뇌 역할을 하는 AI)은 작업별 고정 → cron.model → 평소 쓰는 주 모델 순으로 정해집니다.
| 작업별 고정 | hermes cron edit <job_id> --pin(지금 주 모델로) · --provider … --model …(직접 지정) · --unpin(해제). 에이전트는 내가 시킬 때만 고정·해제할 수 있고, 작업을 다른 모델로 바꿀 수는 없습니다. |
cron.model | 고정하지 않은 모든 예약 작업의 기본 모델(hermes config set cron.model <model>). 없으면 실행 순간의 주 모델을 따르므로, 주 모델을 바꾸면 함께 옮겨 갑니다(Moving unpinned jobs to a new global default). |
| 툴셋 (Toolsets available to cron jobs) | hermes tools 의 cron 플랫폼에 켜 둔 툴셋(toolset — 도구 꾸러미)을 씁니다. 작업별 enabled_toolsets=["web", "file"] 가 있으면 그것이 우선합니다. 필요 없는 도구를 싣고 다니면 호출마다 비용이 늘어납니다. 로그인이 필요한 사이트를 다루려면 실행 전에 로그인되어 있어야 합니다. |
도구 호출로 관리하기 · 예약 작업이 예약 작업을 관리하게 하기 · 저장 방식
에이전트 쪽 창구는 도구 하나이고 동작만 바꿉니다: cronjob(action="create" | "list" | "update" | "pause" | "resume" | "run" | "remove", job_id="…").
| 손으로 돌린 실행 (Manual runs are asynchronous) | action="run" 은 손잡이(handle)만 돌려주고 뒤에서 돕니다. 끝나면 결과가 새 메시지로 대화에 돌아옵니다. prompt="CONTEXT: …" 를 함께 주면 그 한 번에만 지시가 덧붙습니다. |
cron: allow_agent_scheduling: true | 기본 false. 켜면 예약으로 실행된 에이전트도 예약 목록을 다룹니다. 그렇게 만든 작업도 같은 jobs.json 에 들어가 내 것과 똑같이 다룰 수 있습니다. 원문은 매번 새로 만들기보다 기존 작업을 고치게 하라고 권합니다. |
| 저장 방식 (Job storage) | 평범한 JSON 파일입니다. 재시작 도중 돌던 실행은 unknown 으로 남고 자동으로 다시 돌지 않지만 다음 차례는 정상으로 돕니다. 형식이 깨진 항목은 다음에 읽을 때 버리고 경고를 남깁니다. 작업별 base_url 은 provider 와 함께 적어야 하고 설정해 둔 주소와 같은 곳이어야 합니다. |
스크립트와 함께 쓰기 — AI 없이 돌리기 · 깨울지 먼저 확인하기
예약 작업이 돌 때마다 AI 를 부르면 그때마다 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)이 듭니다. 그런데 “메모리가 85% 를 넘으면 알려 줘” 같은 일은 AI 의 판단이 필요 없습니다. 이런 일에는 스크립트(script — 정해진 명령을 순서대로 실행하는 작은 프로그램 파일)를 씁니다. 쓰임은 두 가지입니다.
① AI 없이 돌리기. 감시, 디스크·메모리 경보, “살아 있음” 신호처럼 판단이 필요 없는 되풀이 일에 씁니다. 스케줄러가 스크립트를 제때 실행하고, 스크립트가 화면에 내놓은 글(출력)을 그대로 보냅니다.
| 스크립트가 이렇게 끝나면 | 일어나는 일 |
|---|---|
| 출력이 있다 | 앞뒤 공백만 다듬어 그대로 메시지로 전달합니다. |
| 출력이 비어 있다 | 아무것도 보내지 않습니다 — “문제가 있을 때만 말하기”가 이렇게 됩니다. |
| 오류로 끝나거나 제한 시간을 넘겼다 | 오류 알림을 보냅니다. 고장 난 감시가 조용히 죽어 있는 일을 막습니다. |
마지막 줄이 {"wakeAgent": false} | 아무것도 보내지 않습니다. |
이것도 말로 부탁할 수 있습니다. 원문 예: Ping me on Telegram if RAM is over 85%, every 5 minutes. 뜻: 5분마다 확인해서 메모리 사용이 85% 를 넘으면 Telegram 으로 알려 줘. — Hermes 가 확인 스크립트를 ~/.hermes/scripts/ 에 써 넣고 AI 없는 방식으로 등록합니다. 보낼 내용이 스크립트만으로 정해지는 일이면 Hermes 가 알아서 이 방식을 고릅니다.
② 깨울지 먼저 확인하기. AI 를 쓰는 예약 작업에 확인 스크립트를 붙이면, 스크립트가 마지막 줄에 {"wakeAgent": false} 를 내놓은 차례에는 에이전트 실행을 건너뜁니다. 자주(1~5분마다) 살펴보되 바뀐 것이 있을 때만 AI 를 쓰고 싶을 때 맞습니다. 이 줄이 없으면 평소대로 실행됩니다.
AI 없는 작업을 명령으로 만들기 · 스크립트 규칙 · 제한 시간
hermes cron create "every 5m" \
--no-agent \
--script memory-watchdog.sh \
--deliver telegram \
--name "memory-watchdog"
| 스크립트는 파일 | --script "echo hi" 처럼 명령을 직접 적으면 거부됩니다. $HERMES_HOME/scripts/ 안의 파일이어야 합니다. |
| 실행 방식 | .sh·.bash 는 bash 로, 그 밖은 Hermes 의 파이썬으로 돕니다. 내 파이썬 환경은 --interpreter(공식 문서 참고 — 이 가이드는 다루지 않음). |
| 비밀 값 | 스크립트는 Hermes 의 API 키를 물려받지 않습니다. 필요한 값은 config.yaml 의 terminal: env_passthrough: 에 변수 이름을 적고 값은 .env 에 둡니다. |
| 제한 시간 (Script timeout) | 스크립트 기본 3600초(cron: script_timeout_seconds 또는 환경 변수 HERMES_CRON_SCRIPT_TIMEOUT). 실행 뒤 정리 단계는 기본 10초(cleanup_timeout_seconds). |
확인 스크립트(wakeAgent)의 세 가지 본보기
확인 스크립트는 작업에 script= 로 붙이고, 마지막 줄에 {"wakeAgent": false}(건너뜀) 또는 {"wakeAgent": true, "context": {…}}(깨우면서 자료를 함께 넘김)를 내놓습니다.
| 본보기 | 언제 깨우나 |
|---|---|
| 파일이 바뀌었을 때 | 지켜보는 파일의 수정 시각이 지난번보다 새로울 때 (feed-changed.sh) |
| 바깥에서 신호를 줬을 때 | 다른 프로그램이 준비됐다는 표시 파일을 놓아 뒀을 때 (flag-ready.sh) |
| 새 자료가 쌓였을 때 | 내 데이터베이스에 새 줄이 1개 이상 있을 때 (new-rows.py) |
Hermes 자신의 ~/.hermes/state.db 는 버전마다 구조가 바뀌므로 확인 스크립트에서 들여다보지 말라고 원문은 적습니다.
작업끼리 잇기 — 앞 작업의 결과를 다음 작업에 넘기기
예약 작업은 매번 기억 없이 시작합니다. 그런데 “모으기 → 고르기 → 글쓰기”처럼 앞 작업의 결과가 다음 작업의 재료인 경우가 있습니다. 이때 다음 작업에 context_from 으로 앞 작업을 가리켜 두면, 다음 작업이 돌 때 앞 작업의 가장 최근 결과가 프롬프트 앞에 자동으로 붙습니다.
| 기능 | 무엇을 이어받나 | 언제 쓰나 |
|---|---|---|
context_from | 다른 작업의 가장 최근 결과(여러 개면 적은 순서대로 이어 붙임) | 여러 단계로 나눈 일, 앞 단계 결과에 기대는 일, 여러 작업의 결과를 하나로 모으는 일 |
continuity | 자기 자신의 지난번 결과 | 되풀이해 살펴보는 작업이 지난번에 알린 것을 또 알리지 않게 할 때 |
context_from · continuity 적는 법
| 가리키는 법 | context_from="a1b2c3d4" 또는 ["job_a", "job_b"]. 원문의 다른 대목은 작업 이름도 된다고 적습니다. 결과는 ~/.hermes/cron/output/{job_id}/*.md 에서 읽습니다. |
continuity=True | 내용이 있는 가장 최근 결과가 “이미 보고한 것은 되풀이하지 말라”는 안내와 함께 붙습니다. 조용히 지나간 차례와 빈 결과는 건너뜁니다. 명령으로는 --continuity / --no-continuity. |
예약 작업이 안 돌 때
대부분은 “게이트웨이가 꺼져 있다”, “설정이 빠졌다”, “일은 했는데 전달이 안 됐다” 셋 가운데 하나입니다. 먼저 아래 순서로 봅니다.
hermes cron status스케줄러가 살아 있는지, 다음 실행이 언제인지 봅니다.hermes cron list작업마다 마지막 실행이 어땠는지 봅니다(대화 안에서는/cron list).hermes cron doctor모든 작업을 한꺼번에 점검해 문제를 작업별로 묶어 보여 줍니다. 읽기만 하고 아무것도 바꾸지 않습니다.hermes cron runs <job-id>그 작업의 최근 실행 기록을 봅니다.
| 보이는 모습 | 뜻 | 할 일 |
|---|---|---|
시각이 지났는데 아무 일도 없다. OVERDUE · Overdue: 표시 | 스케줄러가 확인을 멈췄습니다(게이트웨이가 꺼진 경우 등). 예정 시각이 15분 넘게 지나면 이렇게 표시됩니다. | hermes gateway restart 로 게이트웨이를 다시 켭니다. 급하면 hermes cron run <id> 로 바로 돌립니다. |
상태가 blocked_config | 실행 전 점검에서 설정 문제(API 키, 스킬의 준비물, 전달할 메신저, MCP 서버(외부 서비스의 도구를 내주는 프로그램))가 발견됐습니다. AI 를 부르지 않아 토큰이 들지 않고, 알림은 한 번만 옵니다. | 알림에 적힌 것을 고칩니다. 다음 실행이 정상으로 끝나면 풀립니다. |
delivery_failed (노란색) | 일은 끝났지만 결과가 전달되지 못했습니다. | 메신저 연결과 홈 채널을 확인합니다. 결과는 ~/.hermes/cron/output/ 에 남아 있습니다. |
| “N번 연속 실패” 안내 | 되풀이 작업이 기본 3번 연속 실패했습니다. 같은 오류는 매번 알리지 않고 처음 한 번만 알립니다. | 고치거나, hermes cron pause 로 멈추거나, 지웁니다. |
⚠ late · ⚠ catch-up after missed fire | 게이트웨이가 꺼져 있던 사이에 지나간 차례를 따라잡아 돌린 것입니다. 오래 꺼져 있었어도 한 번만 돕니다. | 정상입니다. 끄는 법은 접힌 상자에 있습니다. |
⚠ Cron store is NOT writable | 예약 저장 폴더에 쓸 수 없습니다(디스크 가득 참, 권한 문제 등). 기록할 수 없는 실행은 시작하지 않습니다. | 디스크를 비우거나 권한을 고칩니다. 재시작은 필요 없습니다. |
게이트웨이 자체가 말썽일 때는 10장을 함께 보세요.
실패를 다루는 방식 — 실행 전 점검 · 자동 재실행 · 알림 줄이기 · doctor
| 실행 전 점검 (Pre-dispatch configuration validation) | 제공자(provider — AI 모델을 빌려주는 서비스) API 키, 붙인 스킬의 준비물, 전달할 메신저의 자격 증명, 작업이 지정한 MCP 서버를 봅니다. 판정에는 읽은 프로필과 HERMES_HOME 경로가 적히므로, 대화에서는 되는데 예약에서만 안 되면 그 경로를 견줘 봅니다. 끄려면 cron: preflight: false. |
| 연속 실패 안내 | cron: failure_nudge_threshold: 3(0 = 끔). 전달 실패는 세지 않고, 한 번 성공하면 0 으로 돌아갑니다. |
| 자동 재실행 | 모델을 부르기도 전에 네트워크 오류로 실패한 되풀이 작업은 5·15·30분 뒤 다시 돕니다. 끄려면 cron: retry_unreachable: false. |
| 같은 실패는 한 번만 (Failure incidents) | 계속 고장 나 있으면 cron: failure_repeat_alert_hours: 6 뒤 한 번 더 알립니다(0 = 매번). hermes cron incidents 로 보고, hermes cron incidents ack <id> 로 그 오류의 알림을 끕니다. |
hermes cron doctor | 마지막 실행·전달 실패, 늦은 실행, 닿지 못한 예약 신호, 다음 실행 시각 이상, 없어진 스크립트·workdir 를 봅니다. 문제가 있으면 종료 코드 1. |
| 오류가 적히는 곳 | last_error = 실행 자체의 실패(Run failures), last_fire_error = 예약 신호가 닿지 못함, last_delivery_error = 전달 실패. 자세한 흔적은 cron/output/<job_id>/ 실행 문서의 ## Error 절에 있습니다. |
| 제공자 복구 (Provider recovery) | 같은 제공자의 다른 자격 증명으로 돌려 쓰고(모든 작업), fallback_providers 의 다른 제공자로 넘어갑니다(고정하지 않은 작업만). 모델을 고정한 작업은 넘어가지 않고 실패합니다. |
놓친 실행 · 실행 기록 · 복구 — 관리자용 세부
| 놓친 실행 정책 | 기본은 돌아오면 한 번 따라잡기. 전체로 끄려면 cron: catch_up_missed: false, 작업별로는 --catch-up on / off. 한 번만 도는 작업은 120초를 넘겨 놓치면 버려집니다. 지나친 차례는 기록에 missed ×N 으로 남습니다. |
| 호스팅형 배포 (Missed scheduled fires) | 예약 신호가 게이트웨이에 닿지 못하면 “손으로 돌리면 되는데 자동으로는 안 도는” 모습이 되고 last_fire_error 가 찍힙니다. 대개 hermes gateway restart 로 풉니다. cron: misfire_grace_minutes: 10 뒤 게이트웨이가 스스로 따라잡습니다. |
| 실행 기록 (Execution history) | ~/.hermes/cron/executions.db. 상태는 claimed → running → completed·failed·unknown 가운데 하나. unknown 은 자동으로 다시 돌지 않습니다. hermes cron runs [job-id] --limit 20. “정확히 한 번” 보장은 아니라고 원문은 적습니다. |
| 접수 복구 (Admission recovery) | 덜 끝난 실행을 확인 때마다 맞춰 봅니다. 결과가 이미 나온 것은 다시 돌리지 않고 전달만 하며, 중간에 끊긴 실행은 사람이 살펴볼 때까지 멈춰 둡니다. |
위임이란 — 일을 나눠 하위 에이전트에게 맡기기
위임(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개까지(조절 가능) | 스크립트 하나 |
| 토큰 비용 | 더 큼 | 더 작음(출력만 돌아옴) |
| 맞는 일 | 판단이 필요한 복잡한 일 | 기계적인 여러 단계 처리 |
여러 일을 한꺼번에 맡기기
일감을 여러 개 묶어 한 번에 맡기면 하위 에이전트들이 동시에 일합니다. 기본으로 최대 10개까지 동시에 돌고, 이 수는 설정으로 바꿀 수 있습니다(정해진 상한은 없음). 한도보다 많은 묶음은 일부만 조용히 잘라 돌리지 않고 오류로 돌려보냅니다. 원문의 세 가지 쓰임새입니다.
delegate_task(tasks=[
{"goal": "Research the current state of WebAssembly in 2025",
"context": "Focus on: browser support, non-browser runtimes, language support"},
{"goal": "Research the current state of RISC-V adoption in 2025",
"context": "Focus on: server chips, embedded systems, software ecosystem"},
{"goal": "Research quantum computing progress in 2025",
"context": "Focus on: error correction breakthroughs, practical applications, key players"}
])
뜻: 세 가지 기술 주제를 저마다 살펴볼 점을 정해 동시에 조사시키고 요약을 모읍니다.
맡길 일(goal)은 "Review the authentication module for security issues and fix any found" — 로그인 모듈의 보안 문제를 새 눈으로 검토하고 찾으면 고쳐 달라는 것입니다. context 에 적은 줄을 풀면 이렇습니다.
| context 에 적은 줄 | 뜻 |
|---|---|
| Project at /home/user/webapp. | 프로젝트가 있는 폴더 |
| Auth module files: src/auth/login.py, … | 살펴볼 파일 세 개 |
| The project uses Flask, PyJWT, and bcrypt. | 이 프로젝트가 쓰는 기술 |
| Focus on: SQL injection, JWT validation, … | 특히 살필 네 가지 약점 |
| Fix any issues found and run the test suite (pytest tests/auth/). | 고친 뒤 테스트로 확인 |
세 번째 예의 goal 은 "Refactor all Python files in src/ to replace print() with proper logging" — 폴더 안 모든 파이썬 파일의 print() 를 로그 기록으로 바꾸라는 것입니다. context 에는 프로젝트 위치, 바꾸는 규칙(오류는 logger.error, 경고는 logger.warning 등), 건드리지 말 것(테스트 파일과 CLI 출력), 끝난 뒤 확인 방법(pytest)을 적었습니다. 부모가 직접 하면 대화가 넘칠 큰 일을 통째로 맡기는 예입니다.
묶어서 맡길 때의 규칙은 다음과 같습니다.
| 궁금한 것 | 답 |
|---|---|
| 결과는 언제 오나 | 기본은 모든 일이 끝난 뒤 한 번에, 메시지 하나로 옵니다. |
| 결과 순서 | 먼저 끝난 순서가 아니라 맡긴 순서대로 정리됩니다. |
| 순서가 필요한 일 | 묶음 안의 일은 모두 동시에 돕니다. B 가 A 의 결과를 써야 한다면 A 를 먼저 맡기고, 결과가 돌아온 뒤 B 를 맡겨야 합니다. |
| 기다리는 동안 | 결과는 부모의 턴(내 메시지 하나에 에이전트가 일하고 답하는 한 차례)과 턴 사이에 전달됩니다. 부모는 남은 일을 마치고 턴을 끝냅니다. |
| 진행 모습 | CLI 에서는 하위 에이전트마다 쓰는 도구가 나무 모양으로 실시간 표시됩니다. 메신저에서는 묶어서 전합니다. |
| 멈추려면 | 다음 메시지나 Ctrl+C·Esc 로는 뒤에서 도는 묶음이 멈추지 않습니다. /stop 을 쓰거나 그 세션을 닫아야 멈추고, 멈춘 것도 그때까지 한 것을 돌려줍니다. |
끝나는 대로 따로 받기 · 정해진 모양으로 답 받기 · 작업 폴더 나눠 주기
| 끝나는 대로 받기 | delegation.independent_completions: true(기본 꺼짐). 같은 group 이름을 준 일감은 다 끝난 뒤 한 메시지로 옵니다. 일감 15개가 부모를 15번 깨울 수 있어 기본은 꺼져 있습니다. |
정해진 모양으로 답 받기 (output_schema) | 일감에 JSON Schema(자료의 모양을 정해 둔 규칙)를 달면 답이 그 모양을 지켜야 합니다. 어기면 딱 한 번 고칠 기회를 주고, 그래도 안 맞으면 버리지 않고 schema_valid: false 로 돌려줍니다. |
| 하위 에이전트가 띄운 프로세스 | 완료 알림은 기본으로 부모 대화에 띄우지 않습니다(surface_child_process_notifications). 하위 에이전트는 끝나기 전에 기다리거나(wait), 종료하거나(kill), 부모에게 넘길(handoff, 3개까지) 수 있습니다. |
| 작업 폴더 나눠 주기 (Worktree Isolation) | delegation: worktree_isolation: true 면 하위 에이전트마다 자기 git worktree(같은 저장소의 별도 작업 사본)와 브랜치를 받아 서로의 수정이 부딪치지 않습니다. 끝나면 부모가 브랜치를 살펴 합칩니다. git 저장소이고 터미널 백엔드(명령이 실제로 실행되는 곳)가 local 일 때만 동작합니다. |
하위 에이전트는 무엇을 알고 무엇을 모르나
위임에서 가장 중요한 사실입니다. 하위 에이전트는 아무것도 모른 채 시작합니다. 부모의 대화 기록도, 앞서 쓴 도구의 결과도, 위임 전에 나눈 이야기도 전혀 모릅니다. 아는 것은 부모가 delegate_task 를 부르며 적어 준 goal 과 context 뿐입니다.
그래서 부모는 필요한 것을 전부 쪽지에 적어 넘겨야 합니다. 원문의 나쁜 예와 좋은 예입니다.
❌ 나쁜 예
delegate_task(goal="Fix the error")뜻: 그 오류를 고쳐 줘. — 하위 에이전트는 ‘그 오류’가 무엇인지 알 길이 없습니다.
✅ 좋은 예
goal="Fix the TypeError in api/handlers.py" 에 더해, context 에 오류가 난 줄(47번째 줄)과 오류 글, 원인으로 보이는 것, 프로젝트 위치(/home/user/myproject), 쓰는 파이썬 버전(3.11)을 적음어느 파일의 무슨 오류인지, 어디서부터 볼지, 어떤 환경인지가 다 들어 있습니다.
| 구분 | 내용 |
|---|---|
| 아는 것 | goal, context. 그리고 부모에게 정해진 작업 폴더가 있으면 그 폴더의 프로젝트 맥락 파일(대화마다 자동으로 읽히는 파일 — .hermes.md, AGENTS.md, CLAUDE.md, .cursorrules). 프로젝트의 규칙을 다시 알아낼 필요가 없게 하려는 것입니다(5장). |
| 모르는 것 | 부모의 대화 기록, 앞선 도구 호출, 위임 전에 의논한 것. 성격을 정하는 SOUL.md 도 넘어가지 않습니다. |
| 물려받는 것 | 부모가 켜 둔 툴셋(toolset — 도구 꾸러미), 부모의 API 키·제공자 설정. 터미널 세션은 물려받지 않고 자기 것을 새로 가집니다. |
그림을 함께 넘기기 (images)
눈으로 봐야 하는 일에는 일감마다 images 목록(최대 8개 — 파일 경로, http(s) 주소, data:image/... 주소)을 답니다. 그림을 볼 수 있는 모델이면 그림 그대로, 아니면 [Image attached at: <path>] 안내와 함께 vision_analyze 도구로 보라는 지시가 전달됩니다. 그림 전달이 실패해도 위임은 글만으로 진행됩니다.
/review — 방금 한 일을 다른 눈으로 검토받기
위임을 내가 직접 불러 쓰는 가장 쉬운 방법이 /review 입니다. 이 슬래시 명령은 방금 대화에서 만든 결과물(코드, 문서, 설계 등)을 검토하는 일만 하는 독립된 하위 에이전트를 뒤에서 띄웁니다. CLI, TUI(hermes --tui 로 여는 새 터미널 화면), 데스크톱 앱, 모든 메신저에서 쓸 수 있습니다.
/review # 최근 메시지 10개가 보여 준 것을 검토 /review focus on security # 검토자에게 줄 지시를 덧붙임 (뜻: 보안에 집중해서) Review started. Results will return here.
맨 아래 줄은 명령을 넣었을 때 나오는 안내로, “검토를 시작했습니다. 결과는 여기로 돌아옵니다”라는 뜻입니다.
| 순서 | 일어나는 일 |
|---|---|
| ① 증거 모으기 | 나와 Hermes 가 주고받은 최근 메시지 10개가 검토자의 출발 자료가 됩니다(도구 출력과 시스템 메시지는 빠짐). |
| ② 검토자 출발 | 검토자는 보통의 하위 에이전트와 같은 도구를 모두 받아, 발췌만 보고 평하지 않고 실제로 변경 내용을 읽고 코드를 돌려 봅니다. |
| ③ 같은 규칙으로 판단 | 본래 에이전트가 읽어 둔 스킬과 작업 폴더의 맥락 파일을 검토자도 기준으로 삼습니다. |
| ④ 결과가 돌아옴 | 검토 전문이 같은 세션에 보통의 위임 결과처럼 올라오고, 본래 에이전트가 그것을 보고 고치거나 나에게 답합니다. |
헷갈리기 쉬운 /refine 과는 다릅니다. /refine 은 대화를 돌아보며 기억과 스킬을 고치고, /review 는 대화가 만든 결과물을 검토합니다.
검토 전용 모델 · 화면에 보이는 이름
검토자는 기본으로 주 모델을 씁니다. 따로 정하려면 config.yaml 의 auxiliary.review 에 provider 와 model 을 적습니다(보조 모델은 3장). 실시간 화면에는 Review: 덧붙인 지시(없으면 Review recent work)로 보입니다. 메신저에서는 오래 쉰 세션이라도 저장된 기록에서 메시지를 가져오므로 바로 /review 를 쓸 수 있습니다.
지켜보기 · 방향 바꾸기 · 멈추기
하위 에이전트가 일하는 동안 가만히 기다릴 필요는 없습니다. CLI, TUI, 데스크톱 앱은 입력 칸 바로 위에 지금 일하는 하위 에이전트를 자동으로 보여 줍니다. 몇 개가 도는지, 일감 이름, 지난 시간, 가장 최근에 한 일이 보이고, 그동안에도 글을 계속 쓸 수 있습니다.
| 화면 | 펼쳐서 들여다보기 | 고른 하위 에이전트 다루기 |
|---|---|---|
| 기본 CLI (classic CLI) | Ctrl+T(또는 F6)로 전체 화면 목록. 화살표로 고르고 Enter 로 최근 기록 보기 | s 로 방향 지시 입력, x 다음 y 로 멈춤 요청 |
| TUI | Ctrl+T 또는 /agents 로 나무 모양 목록. Enter/t 로 최근 기록, d 로 자세히 | e 로 방향 지시, x 로 그 하나만 멈춤, X 로 그 아래까지 멈춤 |
| 데스크톱 앱 | 입력 칸 위 Subagents 를 펼쳐 하나를 고름 | Steer(방향 지시) · Stop(멈춤 요청) |
기본 CLI 와 메신저(Telegram, Discord, Slack 등)에서는 /agents 를 넣으면 뒤에서 도는 위임이 글로 정리되어 나옵니다.
Background delegations: 1 running - deleg_ab12cd34 · running · research the delegation stall monitor - child 1: 4 api calls · in web_search · active 12s ago - child 2: 7 api calls · between turns · active 3s ago
뜻: 뒤에서 도는 위임 1건. 첫째 하위 에이전트는 모델을 4번 불렀고 웹 검색 중이며 12초 전에 움직였습니다. 조용한 시간이 함께 보여 “느린 것”과 “멈춘 것”을 가려볼 수 있습니다.
방향 바꾸기 (steer)
멈추면 하던 일이 버려지므로, 방향만 틀 때는 지시를 끼워 넣습니다. 하위 에이전트는 하던 일을 끊지 않고 다음 구간에서 읽습니다. “queued” 는 접수됐다는 뜻이지 읽었다는 뜻이 아닙니다.
멈추기 (stop)
고른 하나만 멈추고 다른 하위 에이전트는 건드리지 않습니다. 멈춘 것도 그때까지의 결과를 돌려줍니다.
실패는 반드시 보입니다
CLI 에는 이유 한 줄이, 메신저에는 따로 알림이 오고, 부모 에이전트도 오류 내용을 받아 다시 시도하거나 보고합니다.
화면 표시 · 부모가 직접 다루기 · 실패와 멈춤 감지 — 세부
TUI 의 /agents (/tasks) | 부모별 나무 보기, 가지별 비용·토큰·건드린 파일 합계, 멈춤·일시 정지, 끝난 뒤 턴별 기록 되짚기. |
| 부모가 직접 다루기 (Steering) | 부모는 delegate_task 에 {"action": "list"} · {"action": "steer", …} · {"action": "stop", …} 를 줘서 자기가 띄운 것만 다룹니다. 닿지 못한 지시는 결과에 missed_steer 로 남습니다. |
| 실시간 기록 (Live Transcripts) | 일감마다 일하는 모습이 그대로 적히는 파일이 생깁니다. 예: tail -f ~/.hermes/cache/delegation/live/deleg_ab12cd34/task-0.log. 같은 폴더의 manifest.json 이 묶음을 설명하고, 7일이 넘으면 자동으로 지워집니다. |
| 실패 표시 (Failure Visibility) | 예: ⚠️ Subagent failed — "your goal": HTTP 404: model not found (after 12s). 부모는 status: "failed" 와 오류 글을 받습니다. |
| 멈춘 것 감지 (Stall Detection) | 진행 신호가 완전히 얼어붙은 채 쉬는 중 450초·도구 안 1200초를 넘기면 중단시키고 120초의 정리 시간을 줍니다. 그래도 돌아오지 않으면 stalled 로 마감합니다. 움직이는 것은 아무리 오래 걸려도 건드리지 않습니다. |
| 완료 전달 (Completion delivery) | 메신저 게이트웨이는 완료 알림이 세션의 대기 줄에 실제로 들어간 뒤에야 받았다고 표시하고, 넣지 못하면 다시 시도하도록 남겨 둡니다. |
한계와 안전장치
위임은 편리하지만 하위 에이전트가 마음대로 불어나거나 엉뚱한 일을 하지 않도록 여러 제한이 걸려 있습니다. 먼저 깊이입니다. 기본 상태에서 위임은 한 단계뿐입니다. 부모(깊이 0)가 하위 에이전트(깊이 1)를 만들 수 있고, 그 하위 에이전트는 다시 맡길 수 없습니다.
다음은 도구입니다. 하위 에이전트는 부모가 켜 둔 툴셋을 그대로 물려받습니다. 부모가 갖지 않은 능력을 하위 에이전트에게 줄 수는 없으므로, 맡길 일에 필요한 도구는 대화를 시작하기 전에 부모 쪽에 켜 두어야 합니다(툴셋은 4장). 거꾸로, 부모에게 있어도 하위 에이전트에게는 막히는 도구가 있습니다.
| 막힌 도구 | 그래서 하위 에이전트는 |
|---|---|
delegate_task | 다시 맡길 수 없습니다(기본인 leaf 역할일 때). |
clarify | 나에게 되물을 수 없습니다. |
memory | 함께 쓰는 기억에 적을 수 없습니다. |
send_message | 메신저로 메시지를 보낼 수 없습니다. |
cronjob | 부모 이름으로 예약 작업을 만들 수 없습니다. |
execute_code 는 막히지 않아, 하위 에이전트도 기계적인 일은 코드로 묶어 처리합니다. 기본 한도를 숫자로 보면 동시에 10개, 깊이 1단계, 하위 에이전트 하나가 도구를 쓰며 일하는 차례 250번입니다. 시간 제한은 기본으로 없습니다. 오래 걸린다는 이유만으로 끊지 않고, 완전히 멈춰 버린 하위 에이전트만 감지해 중단시킵니다.
/stop 이나 세션 닫기로도 멈춥니다. 하위 에이전트가 뒤에서 띄운 프로세스(서버 등)도 그가 끝날 때 함께 종료됩니다. 꺼져도 살아남아야 하는 일은 예약 작업으로 만들거나 부모 세션에서 뒤쪽 터미널 명령(4장)으로 띄우라고 원문은 권합니다.
비용. 원문에 따르면 토큰의 대부분은 한꺼번에 맡긴 하위 에이전트들이 씁니다. 그래서 일을 쪼개고 판단하는 부모는 가장 좋은 모델로, 분명한 일감을 받아 실행하는 하위 에이전트는 값싼 모델로 돌리기를 권합니다. config.yaml 의 delegation.model 에 적고, 비워 두면 부모와 같은 모델을 씁니다.
하위 에이전트의 모델 · 위임 방식 고르기
| 모델 정하기 (Model Override) | config.yaml 의 delegation: 아래 model: "your-inexpensive-model", 필요하면 provider: "openrouter". 직접 주소(base_url)를 적으면 그것이 우선합니다. 기본 방식에서는 일감마다 모델을 따로 고를 수 없습니다. |
위임 방식 delegation.backend | 공식 advanced-delegation 플러그인이 model_map(이름 붙인 모델 목록에서 일감마다 고름)과 profile_routes(하위 에이전트가 내 프로필 가운데 하나로 돎)를 더합니다. 고른 방식을 쓸 수 없으면 몰래 기본으로 돌리지 않고 오류를 냅니다. 되돌리기는 /delegation default 또는 hermes config set delegation.backend default. |
| 주의 | profile_routes 에 적은 프로필의 키·SOUL.md·터미널 정책을 하위 에이전트가 쓰게 됩니다. 그래도 괜찮은 프로필만 적습니다. |
반복 한도 · 시간 제한 · 깊이 · 수명 — 세부
| 반복 한도 (Max Iterations) | delegation: max_iterations(기본 250). 호출마다가 아니라 전체에 적용됩니다. 다 쓰면 exit_reason: max_iterations 로 돌아옵니다. |
| 시간 제한 (Child Timeout) | 기본 child_timeout_seconds: 0(없음). 양수를 주면 전체 시간이 아니라 진행 없는 시간의 한도가 됩니다(최소 30초). 멈춘 것 감지(450초·1200초)는 항상 켜져 있고, 걸리면 부모가 status: "timeout" 을 받습니다. |
| 깊이 (Depth Limit and Nested Orchestration) | role="orchestrator" 에 delegation.max_spawn_depth 2 이상이 함께 있어야 합니다. 원문의 경고: 깊이 3·동시 3 이면 3×3×3 = 27개가 동시에 돕니다. orchestrator_enabled: false 는 전체 차단 스위치입니다. |
| 한 번 답하고 끝나는 실행 (Finite chat runs) | -Q, chat --oneshot 에서는 하위 에이전트를 기다렸다가 같은 턴에 결과를 받습니다. 이때 하위 에이전트 총수는 oneshot_max_children(기본 2)로 묶입니다. |
| 메신저에서 답을 한 번만 받기 (Messaging chats without interim messages) | delegation: gateway_mode: auto | inline | background. 기본 auto 는 그 메신저의 중간 메시지가 꺼져 있으면 턴 안에서 기다려 완성된 답 하나만 보냅니다. 바꾼 설정은 다음 세션(/new)부터 적용됩니다. |
| 수명 (Lifetime and Durability) | 원문의 표현은 “끝난 결과가 남는 것이지, 실행이 이어지는 것은 아니다”입니다. Ctrl+C·Esc·Stop 버튼은 그 턴만 끝냅니다. 데스크톱 앱을 닫거나 연결이 끊긴 것만으로는 하위 에이전트가 멈추지 않습니다. 멈춘 것은 status="interrupted" 와 마지막 글을 돌려줍니다. |
| 프로세스의 주인 (Background process lifetime) | 뒤에서 띄운 프로세스는 그것을 시작한 에이전트의 것입니다. 하위 에이전트를 닫으면 그의 것만 종료됩니다. |
위임 설정 키 한눈에 (Configuration)
모두 config.yaml 의 delegation: 아래에 둡니다(괄호는 기본값). max_iterations(250) · max_concurrent_children(10) · independent_completions(false) · gateway_mode(auto) · worktree_isolation(false) · max_spawn_depth(1) · orchestrator_enabled(true) · model·provider(비어 있으면 부모와 같음) · base_url·api_key·api_mode(제공자 대신 직접 주소를 쓸 때) · request_overrides(하위 에이전트의 모든 모델 호출에 덧붙일 요청 설정) · compression_threshold_tokens(0 = 끔. 하위 에이전트가 대화를 줄이기 시작하는 토큰 수의 상한 — 평소에는 부모와 같은 기준, 3장).
- 예약 작업은 정해 둔 시간에 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 가 꺼지면 이어지지 않으니, 살아남아야 하는 일은 예약 작업으로 만듭니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/features/cron · hermes-agent.nousresearch.com/docs/user-guide/features/delegation (수집일 2026-11-09 의 공식 문서)
메신저에서 쓰기 — 게이트웨이와 Telegram
Hermes Agent 는 터미널(글자로 명령을 입력하는 창) 앞에 앉아 있을 때만 쓰는 프로그램이 아닙니다. 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)를 켜 두면 휴대폰의 Telegram 같은 메신저에서 Hermes 에게 말을 걸고 답을 받을 수 있습니다. 이 장은 게이트웨이가 무엇인지, 어떤 메신저를 쓸 수 있는지, 그리고 Telegram 봇을 만들어 연결하는 순서를 처음부터 끝까지 따라갑니다.
- 게이트웨이가 하는 네 가지 일과, 왜 계속 켜 두어야 하는지
- 쓸 수 있는 메신저 종류와 메신저마다 되는 기능의 차이
hermes gateway setup한 줄로 시작하는 빠른 설정- Telegram 봇 만들기(BotFather) → 내 사용자 ID 알아내기 → Hermes 에 연결하기
- 누가 내 봇에 말을 걸 수 있는지 정하는 허용 목록과 DM(1:1 대화) 페어링
- 그룹 대화·홈 채널·음성 메시지, 그리고 게이트웨이를 서비스로 계속 켜 두는 방법
- 게이트웨이란 무엇인가 — 무엇을 하고, 왜 계속 켜 두는지.
- 빠른 설정 —
hermes gateway setup마법사와 꼭 쓰는 명령 여섯 개. - Telegram 봇 만들기 — BotFather 에게 봇 토큰 받기.
- Hermes 에 연결하고 켜기 — 토큰과 내 사용자 ID 를 넣고 첫 메시지 보내기.
그룹 대화·음성·서비스 설치와 접힌 상자는 봇이 답하기 시작한 뒤에 읽어도 됩니다. 직접 따라 해 보려면 활용편 실습 7로 가세요.
게이트웨이란 무엇인가 — 왜 계속 켜 두나
Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 말만 하는 챗봇과 달리 도구를 써서 내 대신 일을 해 주는 AI 프로그램)와 대화하는 기본 창구는 터미널입니다. 그런데 밖에서 휴대폰으로 일을 시키고 싶을 때가 있습니다. 이때 필요한 것이 게이트웨이입니다. 원문은 게이트웨이를 이렇게 정의합니다 — “설정해 둔 모든 플랫폼(여기서는 메신저 서비스 하나하나)에 연결하고, 세션(대화 한 묶음)을 관리하고, 예약 작업(cron — 정해 둔 시간에 자동 실행)을 돌리고, 음성 메시지를 전달하는 하나의 백그라운드 프로그램(화면 뒤에서 조용히 계속 도는 프로그램)”.
게이트웨이가 하는 일을 원문 순서대로 풀면 네 가지입니다.
① 메신저와 연결
메신저마다 메시지를 받아 오는 담당 부품이 있고, 게이트웨이가 이것들을 한꺼번에 돌립니다.
② 세션 관리
대화방마다 세션을 따로 보관합니다. 그래서 Hermes 가 앞에서 나눈 이야기를 기억한 채 이어 갑니다.
③ 예약 작업 실행
60초마다 “지금 실행할 예약 작업이 있나”를 확인해 실행합니다(7장).
④ 음성 메시지 전달
내가 보낸 음성을 글로 바꾸고, Hermes 의 답을 음성으로 돌려줄 수 있습니다(음성 메시지).
왜 계속 켜 두어야 할까요? 메시지를 받는 것도, 예약 작업 시계를 돌리는 것도 게이트웨이이기 때문입니다. 게이트웨이가 꺼져 있으면 두 가지가 함께 멈춥니다.
원문 용어와 내부 구조 — 어댑터 · Hermes Relay · 데스크톱·대시보드의 상태 표시
| 원문 제목·용어 | 내용 |
|---|---|
| Architecture(구조) | 메신저별 담당 부품을 원문은 platform adapter(플랫폼 어댑터)라고 부릅니다. 어댑터가 메시지를 받고 → 대화별 세션 저장소를 거쳐 → AIAgent 에 넘깁니다. 게이트웨이는 예약 작업 스케줄러도 돌리며 60초마다 실행할 작업을 확인합니다. 원문 이 절은 한 문단뿐입니다(그림은 받은 글에 없음). |
| Hermes Relay 실험 | 메신저 자체가 아니라 연결 장치입니다. Discord·Telegram·Slack·WhatsApp 같은 플랫폼 앞에 외부 커넥터를 두고 인증 정보는 그 커넥터가 가집니다. 되는 기능은 비교표처럼 고정이 아니라 연결할 때 커넥터마다 정해집니다. |
| Messaging status in Desktop and the dashboard | 데스크톱 앱과 대시보드의 메신저 상태는 고른 기기의 고른 프로필(profile — 설정·기억·세션을 따로 쓰는 별도 Hermes 환경)의 것입니다. hermes gateway setup 으로 저장한 인증 정보만으로도 플랫폼이 켜질 수 있고, platforms.<name>.enabled: false 를 명시하면 꺼집니다. Saved 는 “인증 정보가 저장됨”일 뿐 게이트웨이가 실행 중이라는 뜻이 아니어서, 켜 둔 플랫폼이 Messaging gateway stopped 로 보일 수 있습니다. |
음성 기능 전체(터미널 마이크 모드, Discord 음성 채널 대화 등)는 공식 문서 Voice Mode 쪽 참고(이 가이드는 다루지 않음).
어떤 메신저를 쓸 수 있나
원문 첫 문장이 나열하는 곳은 Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles(iMessage), QQ, Yuanbao, Microsoft Teams, LINE, ntfy, 그리고 브라우저입니다. 비교표에는 여기에 몇 개가 더해져 28줄이 실려 있습니다. 다만 메신저마다 되는 일이 다릅니다. 많이 쓰는 여섯 개만 먼저 봅니다.
| 메신저 | 음성 | 이미지 | 파일 | 스레드 | 반응 | 입력 중 | 실시간 갱신 |
|---|---|---|---|---|---|---|---|
| Telegram | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
| Discord | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Slack | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| — | ✅ | ✅ | — | — | ✅ | ✅ | |
| Signal | — | ✅ | ✅ | — | — | ✅ | — |
| — | ✅ | ✅ | ✅ | — | — | — |
| 칸 | 원문 이름 | 뜻 |
|---|---|---|
| 음성 | Voice | Hermes 가 음성으로 답하거나(TTS), 내가 보낸 음성 메시지를 글로 받아 적습니다 |
| 이미지 | Images | 이미지를 주고받습니다 |
| 파일 | Files | 첨부 파일을 주고받습니다 |
| 스레드 | Threads | 한 대화방 안에서 주제별로 갈라지는 대화 가닥을 지원합니다 |
| 반응 | Reactions | 메시지에 이모지 반응을 답니다 |
| 입력 중 | Typing | Hermes 가 처리하는 동안 “입력 중…” 표시가 뜹니다 |
| 실시간 갱신 | Streaming | 답을 다 쓴 뒤 한 번에 보내지 않고, 보낸 메시지를 고쳐 가며 글이 점점 늘어나게 보여 줍니다 |
비교표 전체(28줄) · 메신저별 툴셋 · 공식 문서의 메신저별 Setup 쪽 목록
Platform Comparison 전체 — 칸이 똑같은 플랫폼은 한 줄로 묶었습니다(원문은 28줄).
| 플랫폼 | 음성 | 이미지 | 파일 | 스레드 | 반응 | 입력 중 | 실시간 갱신 |
|---|---|---|---|---|---|---|---|
| Discord · Slack · Matrix · Feishu/Lark | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Telegram · Mattermost | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
| Yuanbao (Labs plugin) | ✅ | ✅ | ✅ | — | — | ✅ | ✅ |
| — | ✅ | ✅ | — | — | ✅ | ✅ | |
| WhatsApp Cloud API · Weixin · QQ · SimpleX | ✅ | ✅ | ✅ | — | — | ✅ | — |
| Photon (iMessage) | ✅ | ✅ | ✅ | — | ✅ | ✅ | — |
| BlueBubbles | — | ✅ | ✅ | — | ✅ | ✅ | — |
| Google Chat | — | ✅ | ✅ | ✅ | — | ✅ | — |
| Signal · LINE | — | ✅ | ✅ | — | — | ✅ | — |
| — | ✅ | ✅ | ✅ | — | — | — | |
| DingTalk | — | ✅ | ✅ | — | ✅ | — | ✅ |
| WeCom | ✅ | ✅ | ✅ | — | — | — | — |
| Microsoft Teams | — | ✅ | — | ✅ | — | ✅ | — |
| Buzz | — | ✅ | — | ✅ | — | — | — |
| SMS · Home Assistant (plugin) · WeCom Callback · ntfy · Raft · IRC | — | — | — | — | — | — | — |
Telegram 줄의 “반응”은 — 이지만, Telegram 쪽 원문에는 봇이 처리 상태를 이모지 반응으로 알리는 기능(기본 꺼짐)이 따로 있습니다 — Telegram 세부 기능 참고.
Platform-Specific Toolsets — 플랫폼마다 자기 툴셋(toolset — 도구 꾸러미, 4장)이 있습니다. 이름은 hermes-telegram · hermes-discord · hermes-slack 처럼 hermes- 뒤에 플랫폼 이름을 붙인 꼴이고(Google Chat 은 hermes-google_chat, Feishu/Lark 는 hermes-feishu, QQBot 은 hermes-qqbot, Microsoft Teams 는 hermes-teams, WeCom Callback 은 hermes-wecom-callback, Webhooks 는 hermes-webhook), 대부분 “터미널을 포함한 전체 도구”입니다. 아래만 다릅니다.
| 플랫폼 | 툴셋 | 쓸 수 있는 것 |
|---|---|---|
| CLI(터미널에서 글자로 쓰는 Hermes 화면) | hermes-cli | 전체(Full access) |
| WhatsApp · WhatsApp Cloud API | hermes-whatsapp | 전체 도구 — 두 연결 방식이 같은 툴셋을 함께 씁니다 |
| Home Assistant (plugin) | hermes-homeassistant | 전체 도구 + 집 안 기기 제어(ha_list_entities, ha_get_state, ha_call_service, ha_list_services) |
| Yuanbao (Labs plugin) | hermes-yuanbao | 전체 도구 + yb_* 그룹/DM/스티커 도구 |
| API Server | hermes-api-server | 전체 도구에서 clarify, text_to_speech 제외(마주 앉은 사람이 없는 창구) |
| Raft | hermes-raft | 깨우기 전용 채널 — 메시지 주고받기는 에이전트가 Raft CLI 로 합니다 |
Next Steps — 원문 끝의 문서 목록(이 가이드는 Telegram 만 다룸): Telegram · Discord · Slack · Google Chat · WhatsApp · WhatsApp Business Cloud API · Signal · SMS(Twilio) · Email · Home Assistant Integration · Mattermost · Matrix · DingTalk · Feishu/Lark · WeCom · WeCom Callback · Weixin(WeChat) · BlueBubbles(iMessage) · Photon(iMessage) · QQBot · Yuanbao · Microsoft Teams · Teams Meetings Pipeline · Microsoft Graph Webhook Listener · LINE · ntfy · SimpleX Chat · Open WebUI + API Server · Raft · IRC · Buzz · A2A(Agent-to-Agent) · Webhooks.
빠른 설정 — 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)로 봇이 답하는지 확인한 다음 → ③ 마음에 들면 서비스로 설치해 계속 켜 둡니다.
Gateway Commands 전체 · 멈춘 게이트웨이 들여다보기(SIGUSR2) · 감시 장치(watchdog)
hermes gateway # Run in foreground
hermes gateway setup # Configure messaging platforms interactively
hermes gateway install # Install as a user service (Linux) / launchd service (macOS)
sudo hermes gateway install --system # Linux only: install a boot-time system service
hermes gateway start # Start the default service
hermes gateway stop # Stop the default service
hermes gateway status # Check default service status
hermes gateway status --system # Linux only: inspect the system service explicitly
뜻(위에서부터): 창에서 바로 실행 · 대화형 설정 · 서비스로 설치 · (Linux 전용) 부팅 때 켜지는 시스템 서비스로 설치 · 시작 · 멈춤 · 상태 확인 · (Linux 전용) 시스템 서비스 상태 확인.
| 원문 소제목 | 내용 |
|---|---|
| Stack dump on demand (SIGUSR2) | Linux·macOS 에서 kill -USR2 <gateway pid> 를 보내면 게이트웨이가 지금 무엇을 하고 있는지를 ~/.hermes/logs/gateway_faulthandler.log 에 적고 계속 돕니다. 멈춘 듯한 게이트웨이를 끄지 않고 들여다볼 때 씁니다. |
| Built-in event-loop liveness watchdog | 게이트웨이 안의 감시 장치가 gateway.loop_watchdog_probe_interval_s(기본 30초)마다 내부 처리가 살아 있는지 확인합니다. 연속 gateway.loop_watchdog_max_strikes 번(기본 3) 반응이 없으면 기록을 남기고 종료 코드 75 로 끝내 서비스 관리자가 다시 켜게 합니다. 이때 hermes gateway status 는 ⚠ Gateway exited degraded: …, 대시보드 배지는 Degraded 로 보입니다. 끄려면 gateway.loop_watchdog: false. |
| 심장 박동(heartbeat) | gateway_state.json 의 updated_at 이 60초마다 새로 찍힙니다. 프로세스는 살아 있는데 이 값이 120초 넘게 낡았으면 ⚠ Gateway heartbeat stale: …(대시보드 Heartbeat stale) — 켜진 듯 보이지만 아무것도 예약 실행되지 않는 경우입니다. 게이트웨이를 다시 시작합니다. |
| Optional Linux event-loop watchdog | systemd 가 관리하는 게이트웨이의 선택 기능. gateway.systemd_watchdog_seconds: 120 처럼 양수를 넣고 hermes gateway install --force 로 서비스 파일을 다시 만들면, Hermes 의 신호가 끊길 때 systemd 가 다시 시작합니다. 기본 0(끔). 메신저의 평범한 네트워크 끊김은 고장으로 치지 않습니다. |
메신저 안에서 쓰는 명령
메신저 대화창에서도 슬래시 명령(대화 입력 칸에 / 로 시작해 넣는 명령)을 쓸 수 있습니다. 터미널에서 쓰던 것(2장)과 대부분 같고, 메신저에서 특히 자주 쓰는 것은 아래입니다.
| 명령 | 하는 일 |
|---|---|
/new 또는 /reset | 새 대화를 시작합니다 |
/stop | 일하고 있는 에이전트를 멈춥니다 |
/status | 지금 세션 정보를 보여 줍니다 |
/model [provider:model] | 모델(에이전트의 두뇌 역할을 하는 AI)을 보거나 바꿉니다 |
/retry · /undo | 마지막 메시지를 다시 시도 · 마지막으로 주고받은 한 쌍을 지웁니다 |
/sessions · /resume [name] | 이전 세션 목록 보기 · 이름 붙인 세션 이어 하기 |
/approve · /deny | 대기 중인 위험한 명령을 승인 · 거절합니다 |
/sethome | 이 대화를 홈 채널로 정합니다(홈 채널) |
/bg <prompt> | 별도의 백그라운드 세션에서 일을 시킵니다 |
/help | 쓸 수 있는 명령을 보여 줍니다 |
/<skill-name> | 설치된 스킬(특정 일을 하는 방법을 적은 설명서, 6장)을 실행합니다 |
Telegram 에서는 게이트웨이가 켜질 때 Hermes 가 명령 메뉴(입력 칸의 / 버튼)를 자동으로 등록합니다. 또 /model 을 아무것도 붙이지 않고 보내면 버튼으로 고르는 화면이 나옵니다.
OpenAI (15)✓ Anthropic (12)
PrevNextBackCancel
모델 이름을 정확히 안다면 /model <name> 으로 바로 바꿀 수 있습니다.
Chat Commands 의 나머지 명령 12개 · /model 고르기 화면 상세
원문 표는 26줄입니다 — 위 표의 14개에 아래 12개를 더한 것입니다.
| 명령 | 설명 |
|---|---|
/personality [name] | 성격 설정(none 이면 초기화) |
/whoami | 이 범위에서 내가 쓸 수 있는 슬래시 명령 권한 보기(admin / user / unrestricted) |
/compress | 대화 문맥을 직접 압축 |
/title [name] | 세션 제목 정하기·보기 |
/usage | 이 세션의 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위) 사용량(/usage reset [--force] 는 쌓아 둔 Codex 한도 초기화권을 씀) |
/insights [days] | 사용 통계와 분석 |
/reasoning [level|show|hide] | 추론 강도 바꾸기, 추론 과정 표시 켜고 끄기 |
/voice [on|off|tts|join|leave|status] | 메신저 음성 답과 Discord 음성 채널 동작 제어 |
/rollback [number] | 파일 체크포인트(파일을 바꾸기 전에 찍어 두는 자동 스냅샷, 9장) 목록·복원 |
/btw <question> | 지금 대화를 끊지 않고 곁가지 질문 |
/reload-mcp | 설정에서 MCP 서버(외부 도구를 내주는 프로그램) 다시 읽기 |
/update | Hermes Agent 를 최신 버전으로 업데이트 |
Interactive Model Picker(Telegram) — 제공자 선택(예: “OpenAI (15)”, 현재 제공자는 “✓ Anthropic (12)”) → 모델 선택(Prev/Next 로 쪽 넘김, Back 은 제공자로, Cancel). /model <name> --global 은 세션이 바뀌어도 유지되게 저장합니다.
대화가 이어지는 방식 — 세션 · 끼어들기 · 백그라운드 · 승인
메신저 대화는 내가 새로 시작하기 전까지 한 세션으로 이어집니다. 원문 표현으로는 “에이전트가 대화 맥락을 기억”하며, 한동안 말이 없었다고 또는 날짜가 바뀌었다고 세션이 초기화되지 않습니다. 새 대화를 원하면 /new(또는 /reset)를 보냅니다. 대화가 길어지면 문맥 압축(오래된 대화를 줄여 요약해 두는 일)은 자동으로 됩니다.
일하는 중에 벌어지는 네 가지 상황을 탭으로 봅니다.
Hermes 가 일하는 도중에 메시지를 보내면, 기본값으로는 지금 하던 일의 방향을 고칩니다. 이미 끝낸 작업 결과는 그대로 남고, 돌고 있던 도구는 안전하게 끝난 뒤 다음 단계에서 내 말이 반영됩니다. 완전히 멈추려면 /stop 입니다.
/stop.
/bg 뒤에 시킬 일을 적으면 별도의 세션에서 따로 진행됩니다. 그동안 원래 대화는 계속 쓸 수 있고, 끝나면 결과가 같은 대화방으로 옵니다.
Task ID: bg_143022_a1b2c3
주의: 백그라운드 세션은 지금 대화 내용을 모릅니다. /bg 뒤에 적은 글만 받으므로, 필요한 정보를 그 한 줄에 다 적어야 합니다.
에이전트가 위험할 수 있는 명령을 실행하려 하면 대화창에서 먼저 묻습니다. 승인(approval — 위험한 명령을 실행하기 전에 나에게 묻는 것)의 원리는 9장에서 다룹니다.
yes/y 로 승인, no/n 으로 거절합니다(원문 Exec Approval). /approve · /deny 명령도 있습니다.
에이전트가 어느 쪽으로 할지 물어야 할 때(원문: clarify 도구) Telegram 은 질문을 버튼으로 보여 줍니다.
1. Next.js2. Remix3. Astro✏️ Other (type answer)
skip 이라고 답하면 질문을 건너뜁니다.
Telegram 은 주로 휴대폰에서 보므로, 진행 상황 알림이 기본값으로 조용하게 맞춰져 있습니다. 도구를 쓸 때마다 알리는 메시지는 꺼져 있고, 오래 걸리는 일에는 “⏳ Working — N min” 메시지 하나가 몇 분마다 고쳐지며 살아 있음을 알려 줍니다. 처리 중에는 “입력 중…” 표시도 뜹니다.
Session Management 상세 — /sessions · /model 유지 · 답 전달 보장 · 세션 연속성
| 원문 소제목 | 내용 |
|---|---|
| Session Persistence | 세션은 초기화될 때까지 메시지 사이에 유지됩니다. |
Finding Past Sessions (/sessions) | 지금 대화방의 이전 세션 목록(지금 것은 (current)). /sessions <name> 은 /resume 과 같고, /sessions search <query>(별칭 find)는 제목·세션 id 로 거릅니다. 다른 대화방까지 보는 /sessions all 은 관리자 전용입니다. |
Persistent /model Overrides | /model 로 바꾼 모델은 그 세션에 적용되고 게이트웨이를 다시 시작해도 유지됩니다. /model reset 은 대화는 두고 되돌림, /new·/reset 은 새 대화와 함께 되돌림, --global 은 config.yaml 에 저장, --once 는 한 차례만 적용. |
| Delivery Reliability | 최종 답은 전달 장부(state.db)에 기록됩니다. 답을 만든 뒤 메신저가 받기 전에 게이트웨이가 죽으면, 다음에 켜질 때 일을 다시 하지 않고 저장된 답을 다시 보냅니다. 보내던 중이라 애매한 답에는 “♻️ Recovered reply — … may be a duplicate”(중복일 수 있음) 머리말이 붙습니다. 속도 제한으로 거절된 답은 벌칙 시간 뒤, 그 밖의 거절은 30초 → 2분 뒤 다시 보내고, 닿을 수 없는 대화방(봇 차단·그룹 삭제)은 다시 보내지 않습니다. 한도 3회·24시간, 전달된 기록은 7일 뒤 정리. 끄려면 gateway.delivery_ledger: false. |
| Session continuity | 게이트웨이 대화는 오래 조용해도, 날짜가 바뀌어도 초기화되지 않습니다. 예전 session_reset 설정은 무시되며, mode 가 idle·daily·both 로 남아 있으면 게이트웨이 시작과 hermes doctor 가 경고합니다. 시간 기준 초기화를 계속 쓰려면 hermes plugins install hermes-session-reset-policy. |
바쁜 에이전트에게 보낸 메시지 처리 방식 — interrupt · queue · steer
Redirecting the Agent — 일하는 중에 메시지를 보내면 모델은 지금까지 보인 추론·부분 답을 간직한 채 다시 쓰기 시작하고, 끝난 도구 결과는 남으며, 돌고 있는 도구는 죽이지 않고 다음 도구 결과 뒤에 고침이 적용됩니다. /stop 은 강제 중단입니다.
display.busy_input_mode | 동작 |
|---|---|
interrupt (기본) | 하던 차례의 방향을 고칩니다. 앞에서 돌던 터미널 명령은 죽이지 않고 백그라운드로 옮겨, 내 메시지를 바로 읽습니다. |
queue | 뒤이은 메시지는 지금 일이 끝난 뒤 다음 차례로, 도착 순서대로 하나씩 실행됩니다. 연달아 보낸 사진 묶음만 한 차례로 합쳐집니다. |
steer | /steer 방식으로 지금 실행에 끼워 넣어 다음 도구 호출 뒤에 닿습니다. 끊지도, 새 차례를 만들지도 않습니다. 에이전트가 아직 시작 전이면 queue 처럼 동작합니다. |
같이 쓰는 키(display 아래, 프로필마다 따로): busy_ack_enabled(false 면 ⚡/⏳/⏩ 확인 답을 숨김 — 입력 처리는 그대로) · busy_text_debounce_seconds: 0.35 · busy_text_hard_cap_seconds: 1.0. 바쁜 에이전트에게 처음 말을 걸면 한 번만 안내 줄(“💡 First-time tip — …”)이 붙습니다. 끼워 넣는 메시지에는 플랫폼·대화방·보낸 사람 등의 식별자가 함께 실리며, privacy.redact_pii: true 면 지원 플랫폼에서 해시로 가려집니다.
진행 상황 알림 설정 — Tool Progress · 백그라운드 프로세스 알림 · 되묻기 여러 개 고르기
Tool Progress Notifications — 켜면 봇이 일하는 동안 💻 `ls -la`... · 🔍 web_search... 같은 상태 메시지를 보냅니다. ~/.hermes/config.yaml 에서 정합니다.
| 설정 | 값과 뜻 |
|---|---|
display.tool_progress | off | new | all | verbose | log. log 는 대화창 대신 ~/.hermes/logs/tool_calls.log 에 도구 호출을 한 줄씩 적습니다(5 MB × 백업 3개, 비밀 값은 가려서 기록). |
display.tool_progress_command | true 면 메신저에서 /verbose 를 쓸 수 있습니다. |
display.tool_progress_grouping | accumulate(기본 — 말풍선 하나를 고쳐 가며 표시) | separate(도구마다 메시지 하나). |
| Configurable status phrases | 오래 걸릴 때 나오는 “아직 일하는 중…” 류 문구를 바꿉니다. ~/.hermes/status_phrases.yaml 이나 ~/.hermes/status_phrases/*.yaml 이 자동으로 읽히고, display.status_phrases 의 path·mode(append 기본 | replace)로도 지정합니다. 표면(status, generic)마다 최대 80개·160자. |
| Message timestamps in model context | gateway.message_timestamps.enabled: true 면 모델이 보는 내 메시지 앞에 [Tue 2026-04-28 13:40:53 CEST] 같은 보낸 시각이 붙습니다. 기본 꺼짐. |
Background Sessions — /bg 에이전트는 자기 세션을 가지며(지금 대화는 모름) 모델·제공자·툴셋·추론 설정은 물려받습니다. 원문 용례: 서버 점검, 긴 빌드, 조사, 파일 정리. 그 에이전트가 terminal(background=true) 로 띄운 오래 도는 프로세스의 알림은 display.background_process_notifications(환경 변수 HERMES_BACKGROUND_NOTIFICATIONS)로 정합니다.
| 값 | 받는 것 |
|---|---|
concise (기본) | 끝났을 때 한 줄. 실패하면 출력 끝부분이 붙습니다 |
all | 진행 중 출력 갱신 + 끝났을 때 상태와 출력 끝부분 |
result · error | 끝났을 때 상태와 출력 끝부분만 · 그중 실패했을 때만 |
off | 알림 없음. CLI·TUI(hermes --tui 화면)·데스크톱에서도 프로세스 완료가 에이전트를 깨우지 않습니다(하위 에이전트 결과는 깨움) |
notify_on_complete=true 로 띄운 프로세스는 끝나면 새 차례를 시작해 에이전트가 직접 결과를 보고합니다.
Clarify Questions (Multi-Select) — 되묻기는 여러 개를 고르는 질문도 됩니다. 메신저에서는 “Multiple selections allowed” 라고 나오고 번호를 쉼표나 빈칸으로 나눠 답합니다(예: 1, 3). CLI·TUI 에서는 체크 상자(Space 로 고르고 Enter). Telegram 이 버튼을 그리지 못하면 번호 목록 글로 다시 묻고, 그것도 못 보내면 에이전트는 기다리지 않고 풀려납니다. 대기 시간은 agent.clarify_timeout(기본 90초).
채널별 모델·프롬프트 바꾸기 · 일부러 답하지 않기(침묵 토큰)
| 원문 제목 | 내용 |
|---|---|
| Per-Channel Model & System Prompt Overrides | 게이트웨이 하나에서 채널마다 다른 모델·역할을 씁니다. config.yaml 의 플랫폼 아래 channel_overrides 에 채널/스레드 id 별로 model · provider · system_prompt(모두 선택)를 적습니다. 찾는 순서는 정확한 id → 부모 채널, 모델 우선순위는 세션의 /model → channel_overrides → 전체 설정. system_prompt 는 그 채널에서 게이트웨이 기본 지시문을 대신하며 기록에 저장되지 않습니다. |
| Intentional Silence Tokens | 에이전트의 최종 답이 정확히 침묵 토큰 하나면 게이트웨이는 아무것도 보내지 않습니다(세션 기록에는 남음). 토큰: [SILENT] · SILENT · NO_REPLY · NO REPLY · [静默]/静默 · [沉默]/沉默. 사람이 보낸 메시지에 토큰만 답하면 짧은 알림으로 바뀝니다 — 답이 필요한 메시지가 사라지면 안 되기 때문입니다. 내부 알림이나 봇에게 한 말이 아니라고 판단된 메시지(Slack·Telegram 그룹의 일부)는 침묵이 유지됩니다. 실패한 차례는 오류로 드러납니다. |
| Per-Room Intentional Silence | 봇이 호명됐더라도 토큰만 있는 차례를 조용히 넘기려면 그 방의 channel_overrides 에 allow_silence: true. 방 단위 설정이고 처음 맞는 항목이 이깁니다. 고친 뒤 게이트웨이를 다시 시작합니다. 최종 전달에만 영향을 주며, 빈·실패·중단된 결과는 숨기지 않습니다. |
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 로 무효로 만듭니다.
Step 2: 봇 꾸미기(선택) — BotFather 명령과 Hermes 쪽 선택 설정 7가지
| BotFather 명령 | 용도 |
|---|---|
/setdescription | 대화를 시작하기 전에 보이는 “이 봇은 무엇을 하나요?” 소개 글 |
/setabouttext | 봇 프로필 쪽의 짧은 글 |
/setuserpic | 봇 프로필 사진 |
/setcommands | 명령 메뉴(대화창의 / 버튼). 원문이 권하는 시작 묶음: help · new · sethome |
/setprivacy | 봇이 그룹의 모든 메시지를 볼지(그룹 대화) |
Hermes 쪽 선택 설정 — ~/.hermes/config.yaml 의 Telegram extra 아래에 둡니다.
| 원문 소제목 | 무엇을 하나 | 설정 키 |
|---|---|---|
| Online/Offline status indicator | Telegram 봇에는 접속 중 초록 점이 없습니다. 켜 두면 게이트웨이가 연결될 때 봇의 짧은 소개 글을 Online, 정상 종료 때 Offline 으로 바꿉니다(갑자기 죽으면 마지막 글이 남음). 기본 꺼짐. | status_indicator: true |
| Cold-boot pending queue | 기본값은 새로 켜질 때 Telegram 서버에 쌓인 메시지를 버립니다. 밤에 끄는 컴퓨터라면 false 로 두어 꺼진 동안 온 메시지를 순서대로 받습니다(그동안 보낸 명령이 켜질 때 실행됨에 주의). | drop_pending_on_cold_boot: false |
| Concurrent update handling | 다른 대화방의 메시지는 동시에, 같은 대화방은 온 순서대로 처리합니다. | max_concurrent_updates: 32 |
| Albums | 사진·파일 여러 장을 한꺼번에 보내면 메시지 하나로 묶어 넘깁니다(느린 내려받기는 최대 8초, 마지막 항목 뒤 기본 1.5초 기다림). | media_group_wait_seconds |
| Repeated inbound updates | 같은 update_id 가 다시 오면 걸러 냅니다. 최근 4096건을 메모리에만 기억하며 “정확히 한 번”을 보장하지는 않습니다. | 없음 |
| Command menu priority and cap | 명령 메뉴는 자동 등록되고 기본 60개로 자릅니다(Telegram 한도 100개). 꼭 보여야 하는 명령·스킬을 앞세울 수 있습니다. 전체 목록은 /commands. | command_menu 의 max_commands · priority_mode · priority |
| Inline command picker | 아무 대화방에서 @봇이름 검색어 를 치면 모든 명령·스킬을 검색해 고릅니다. 허용 목록을 통과한 사용자에게만 결과가 나옵니다. | BotFather /setinline 으로 켬 |
Hermes Cloud with Team Gateway — 공용 봇으로 연결되는 경우
Team Gateway 가 켜진 Hermes Cloud 인스턴스에서는 Telegram(과 Discord·Slack)이 공용 Hermes 봇을 거쳐 내 에이전트에 닿습니다. 내 봇은 거기서 돌지 않습니다 — 인스턴스가 쉴 때 잠들 수 있도록 게이트웨이가 시작할 때마다 직접 연결을 끕니다. Telegram 카드에는 Create with QR 대신 Via Team Gateway 가 보입니다.
- Nous Portal 에서 만든 에이전트는 Portal 에서 계정을 연결합니다 — 카드의 Link accounts in Nous Portal 버튼, 에이전트의 Message platforms 에서 연결 코드.
- 그 밖에는 카드의 Link Telegram →
/link AB12CD같은 1회용 메시지·QR·Open Telegram 버튼 → 공용 봇에게 그 메시지를 보내면 카드에 계정이 나타나고, 이후 공용 봇에게 말하면 내 에이전트와 대화합니다. - 게이트웨이가 켜져 있어야 버튼이 동작합니다. 내 봇도 함께 돌리려면
GATEWAY_RELAY_ALLOW_DIRECT_PLATFORMS=true(이러면 인스턴스가 잠들지 않음).
내 사용자 ID 알아내기
Hermes 는 “누가 말을 걸었는지”를 숫자로 된 Telegram 사용자 ID 로 구분합니다. 사용자 ID 는 @ 로 시작하는 사용자 이름이 아니라 123456789 같은 숫자입니다.
숫자는 알려 주는 봇에게 물으면 됩니다.
- 방법 1 (권장) —
@userinfobot에게 메시지 보내기Telegram 에서@userinfobot을 찾아 아무 메시지나 보내면 곧바로 내 사용자 ID 를 답해 줍니다. - 방법 2 —
@get_id_bot같은 일을 하는 또 다른 봇입니다. - 숫자를 적어 둡니다다음 단계 Hermes 에 연결하기에서 씁니다.
-1001234567890 처럼 음수입니다. 홈 채널이나 그룹 허용 설정에서 이 숫자가 나옵니다.
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 봇은 내 컴퓨터에서 명령을 실행할 수 있습니다. 그래서 게이트웨이의 기본값은 “허용 목록(allowlist — 통과시킬 사람을 적어 둔 명단)에 없고 DM 페어링도 하지 않은 사용자는 전부 거절”입니다. 원문은 이것을 “터미널을 쓸 수 있는 봇을 위한 안전한 기본값”이라고 부릅니다.
문을 여는 방법은 세 가지이고, 원문은 첫 번째를 권합니다.
① 사람을 지정 (권장)
메신저별 허용 목록에 사용자 ID 를 적습니다. Telegram 은 TELEGRAM_ALLOWED_USERS=123456789,987654321 처럼 쉼표로 잇습니다.
② 모든 메신저 공통 목록
GATEWAY_ALLOWED_USERS=… 에 적습니다.
③ 모두 허용 (비권장)
GATEWAY_ALLOW_ALL_USERS=true. 원문은 터미널을 쓸 수 있는 봇에는 권하지 않는다고 못 박습니다.
DM 페어링(pairing — 1회용 코드로 사람을 짝지어 허용하는 방법)은 ID 를 미리 알아내 적어 두는 대신 쓰는 방법입니다.
- 모르는 사용자가 봇에게 DM 을 보냅니다그 사람에게 1회용 코드가 표시됩니다 — 원문 예:
Pairing code: XKGH5N7P - 그 사람이 코드를 나에게 알려 줍니다코드는 1시간 뒤 만료되고, 요청 횟수에 제한이 있으며, 암호학적으로 안전한 난수로 만들어집니다.
- 내가 터미널에서 승인합니다
hermes pairing approve telegram XKGH5N7P— 이제 그 사람이 봇과 대화할 수 있습니다.
허용된 사람끼리도 등급을 나눌 수 있습니다. 허용 목록이 “들어올 수 있는가”라면, 이 구분은 “들어와서 무엇을 할 수 있는가”입니다.
| 등급 | 할 수 있는 것 |
|---|---|
| 관리자 (Admin) | 모든 슬래시 명령을 쓸 수 있습니다 |
| 일반 사용자 (Regular user) | 에이전트와 평소처럼 대화할 수 있지만, 슬래시 명령은 내가 허락한 것만 씁니다. /help 와 /whoami 는 항상 됩니다 |
관리자 목록을 따로 정하지 않으면 이 구분은 꺼져 있고 허용된 사람 모두가 전체 권한을 가집니다. 내 등급은 대화창에서 /whoami 로 확인합니다. 메신저 사용자 인증이 Hermes 의 다른 안전장치와 어떻게 맞물리는지는 9장 「메신저에서는 누가 쓸 수 있나」에서 이어집니다.
Security 상세 — 메신저별 허용 목록 변수 · 페어링 명령 · 다른 봇 · 관리자 설정
# Restrict to specific users (recommended):
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SIGNAL_ALLOWED_USERS=+155****4567,+155****6543
EMAIL_ALLOWED_USERS=trusted@example.com,colleague@work.com
# Or allow
GATEWAY_ALLOWED_USERS=123456789,987654321
# Or explicitly allow all users (NOT recommended for bots with terminal access):
GATEWAY_ALLOW_ALL_USERS=true
뜻: 메신저별로 특정 사용자만 허용(권장) · 공통 목록 · 모두 허용(비권장). 같은 꼴의 변수가 SMS · MATTERMOST · MATRIX · DINGTALK · FEISHU · WECOM · WECOM_CALLBACK · TEAMS 에도 있습니다(…_ALLOWED_USERS). 전화번호의 **** 와 “# Or allow” 주석은 받은 원문 그대로입니다.
hermes pairing approve telegram XKGH5N7P
hermes pairing list # View pending + approved users
hermes pairing revoke telegram 123456789 # Remove access
뜻: 코드 승인 · 대기 중·승인된 사용자 보기 · 접근 권한 거두기. Email 은 예외로, 모르는 발신자는 이메일 페어링을 따로 켜지 않는 한 무시됩니다.
| 원문 소제목 | 내용 |
|---|---|
| Other bots in a chat | 플랫폼이 봇이라고 알려 주는 발신자(Discord·Slack·Telegram 등)는 봇으로 취급하고, 그런 표시가 없는 플랫폼(Matrix·Signal·IRC 등)은 config.yaml 의 bot_users 에 상대 봇 id 를 적습니다. 봇 발신자는 *_ALLOW_BOTS 설정으로만 받아들여지고, Hermes 는 봇에게 진행·재시도 같은 알림 없이 모델의 답만 보냅니다. gateway.bot_loop_guard 가 봇끼리 끝없이 주고받는 것을 끊습니다(max_hops 기본 4). |
| Admins vs Regular Users | 등급은 플랫폼별·범위별(DM 과 그룹/채널이 따로)입니다. 지금 등급이 막는 것은 슬래시 명령이고 평범한 대화는 영향이 없습니다. 원문은 앞으로 도구 접근·모델 바꾸기 같은 것도 같은 구분에 걸릴 수 있다고 적습니다. |
| Slash Command Access Control (Telegram) | gateway.platforms.telegram.extra 아래: allow_from(기존 허용 목록) · allow_admin_from(모든 슬래시 명령을 쓰는 관리자) · user_allowed_commands(일반 사용자가 쓸 명령, 예: status, model, history) · group_allow_admin_from · group_user_allowed_commands(그룹용 별도 목록). allow_admin_from 이 없는 범위는 제한이 꺼집니다. 그룹 쪽만 두면 DM 은 제한 없는 상태로 남습니다. |
| Inspecting your access | /whoami 는 지금 범위·내 등급(admin / user / unrestricted)·쓸 수 있는 명령을 보여 줍니다. 관리자 목록이 있으면 /help·/commands 도 쓸 수 있는 명령만 보여 줍니다. |
Telegram 그룹 허용 목록(Group Allowlisting) · 손님 모드 · Telegram 쪽 Security
Telegram 그룹·포럼에는 서로 독립된 문이 두 개 있습니다.
| 문 | 설정 (yaml / 환경 변수) | 뜻 |
|---|---|---|
| 전체 접근 | allow_from / TELEGRAM_ALLOWED_USERS | 모든 대화 종류(DM·그룹·포럼)에서 봇을 부를 수 있는 사용자 |
| 그룹 전용 사용자 | group_allow_from / TELEGRAM_GROUP_ALLOWED_USERS | 그룹·포럼에서만 허용되는 발신자. DM 권한은 주지 않습니다 |
| 대화방 단위 | group_allowed_chats / TELEGRAM_GROUP_ALLOWED_CHATS | 적어 둔 그룹·포럼의 모든 구성원이 허용됩니다(팀·지원용 봇) |
어느 값이든 * 를 쓰면 모든 발신자/대화방을 허용합니다. 이 문들은 멘션·패턴 조건과 group_topics·ignored_threads 위에 겹쳐 적용됩니다.
- Migration from before PR #17686 — 예전에는
TELEGRAM_GROUP_ALLOWED_USERS하나뿐이라 대화방 ID 도 여기에 넣었습니다.-로 시작하는 값은 지금도 대화방 ID 로 인정되지만 경고가 한 번 기록됩니다. 새 방식은TELEGRAM_GROUP_ALLOWED_CHATS="-1001234567890". - Guest @mention bypass (
guest_mode) — 보통group_allowed_chats밖의 그룹 메시지는 봇을 멘션해도 조용히 버려집니다.guest_mode: true(환경 변수TELEGRAM_GUEST_MODE=true, 기본false)면 목록 밖 그룹에서도 봇을 직접 @멘션한 메시지만 처리합니다. 멘션은 매번 필요합니다. - Security(Telegram 쪽) — 항상
TELEGRAM_ALLOWED_USERS를 설정하세요. 없으면 게이트웨이가 기본으로 모든 사용자를 거절합니다. 봇 토큰은 공개하지 말고, 새어 나가면 BotFather/revoke. 더 자세한 것은 공식 문서 Security 쪽(이 가이드에서는 9장).
그룹 대화에서 쓰기
Hermes 봇은 Telegram 그룹 대화에도 넣을 수 있습니다. 다만 1:1 대화와 달리 “봇이 무엇을 볼 수 있는가”부터 정해야 합니다. Telegram 봇에는 개인 정보 보호 모드(privacy mode — 그룹에서 봇이 볼 수 있는 메시지를 줄이는 Telegram 의 설정)가 기본으로 켜져 있고, 원문은 이것을 “그룹에서 봇을 쓸 때 가장 흔한 혼란의 원인”이라고 부릅니다.
평범한 그룹 대화에도 봇이 반응하게 하려면 개인 정보 보호 모드를 끕니다.
- @BotFather 에게
/mybots를 보냅니다내 봇 목록이 나오면 봇을 고릅니다. - Bot Settings → Group Privacy → Turn off(봇 설정 → 그룹 개인 정보 보호 → 끄기)
- 봇을 그룹에서 내보냈다가 다시 넣습니다Telegram 은 봇이 그룹에 들어올 때의 설정을 기억해 둡니다. 다시 넣기 전까지 바뀐 설정이 적용되지 않습니다.
그룹에서도 규칙은 이어집니다.
| 규칙 | 뜻 |
|---|---|
| 허용 목록은 그룹에서도 적용 | TELEGRAM_ALLOWED_USERS 에 있는 사람만 봇을 움직일 수 있습니다. 그룹 구성원 전체가 아닙니다 |
| 부를 때만 답하게 하기 | telegram.require_mention: true 로 두면 봇은 ① 봇 메시지에 단 답글 ② @봇이름 멘션 ③ /명령@봇이름 ④ 내가 정한 호출어에만 반응합니다 |
| 설정하지 않으면 | require_mention 을 비워 두거나 false 면, 봇은 자기가 볼 수 있는 평범한 그룹 메시지에 반응합니다 |
1:1 대화에서는 답하는데 그룹에서는 조용하다면 원문이 권하는 순서대로 다섯 개의 문을 확인합니다.
| 순서 | 확인할 것 |
|---|---|
| ① Telegram 이 전해 주는가 | 개인 정보 보호 모드를 끄거나, 봇을 관리자로 올리거나, 봇을 직접 멘션합니다 |
| ② 다시 넣었는가 | 설정을 바꾼 뒤 봇을 그룹에서 내보냈다가 다시 넣습니다 |
| ③ Hermes 가 허용하는가 | 보낸 사람이 TELEGRAM_ALLOWED_USERS 나 TELEGRAM_GROUP_ALLOWED_USERS 에 있는지, 또는 그룹이 TELEGRAM_GROUP_ALLOWED_CHATS 에 있는지 봅니다 |
| ④ 멘션 조건 | require_mention: true 면 명령·답글·멘션·호출어가 아닌 대화는 무시됩니다 |
| ⑤ 봇이 여러 개인가 | Hermes 프로필마다 봇 토큰이 달라야 합니다 |
그룹 대화방 ID 가 음수인 것은 정상입니다. 대화방 단위로 허용할 때는 그 음수 ID 를 사용자 목록이 아니라 TELEGRAM_GROUP_ALLOWED_CHATS 에 넣습니다.
그룹 세부 설정 — 호출어(mention_patterns) · 지켜보기만 하기 · 조용히 있기 · 봇 여러 개
telegram:
require_mention: true
exclusive_bot_mentions: true
mention_patterns:
- "^\\s*chompy\\b"
ignored_threads:
- 31
- "42"
뜻(~/.hermes/config.yaml): 평소의 직접 호출에 더해 chompy 로 시작하는 메시지에도 반응하고, 토픽 31·42 의 메시지는 항상 무시합니다.
| 원문 소제목·설정 | 내용 |
|---|---|
Notes on mention_patterns | Python 정규식(글자 무늬를 적는 표기법), 대소문자 구분 없음, 글과 미디어 설명 글 모두에 적용. 잘못된 무늬는 경고만 남기고 무시됩니다. 맨 앞에서만 맞게 하려면 ^. |
ignored_threads | 특정 포럼 토픽에서는 Hermes 가 항상 조용히 있습니다. |
exclusive_bot_mentions (기본 켜짐) | Hermes 봇이 여러 개인 그룹에서, 메시지가 특정 봇 이름으로 시작하면(@OtherBot do this) 호명된 봇만 처리합니다. 글 중간에 나온 봇 이름은 영향이 없습니다. |
| 봇 이름 바꾸기 | BotFather 에서 @사용자 이름을 바꿔도 게이트웨이를 다시 시작할 필요가 없습니다. bot 으로 끝나지 않는 수집용(Fragment) 이름도 지원합니다. |
| Observe group chatter without auto-replying | 평범한 그룹 대화를 읽기만 하고 불렸을 때만 답합니다. allowed_chats 와 group_allowed_chats 에 같은 대화방 ID, require_mention: true, observe_unmentioned_group_messages: true(환경 변수 TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES). 멘션 없는 메시지는 세션 기록에 “지켜본 맥락”으로만 쌓이고, 나중에 부르면 그 맥락을 씁니다. 개인 정보 보호 모드를 끄거나 봇을 관리자로 올려야 합니다. |
| Letting the bot stay silent in a group | 봇이 정확히 [SILENT] 로 답했을 때: 봇을 멘션·답글·호출어·/명령 으로 부른 메시지면 짧은 알림으로 바뀌고, 다른 구성원에게 한 말이면 침묵이 유지됩니다. 그 밖의 메시지는 ? 가 있으면 알림, 없으면 침묵. 설명 글 없는 음성·영상에도 알림이 나갑니다. |
| Multiple Hermes bots in one group | 프로필마다 봇 토큰 하나, 게이트웨이 하나 — 같은 토큰을 두 게이트웨이에서 쓰면 Telegram 이 거부합니다. 권장: require_mention: true · exclusive_bot_mentions: true · mention_patterns: []. 프로필별로 hermes -p research gateway start 처럼 명령을 한 번씩 줍니다. |
| 봇끼리 끝없이 답하는 것 막기 | telegram.bots_require_mention: true 면 다른 봇의 메시지는 이 봇을 직접 @멘션했을 때만 반응을 일으킵니다. gateway.bot_loop_guard: 한 대화방에 5분 안에 봇 메시지 20개(max_events)가 오면 10분 동안 봇 메시지를 버리고(사람 메시지는 세지 않음), max_hops: 4 가 그보다 먼저 주고받기를 끊습니다. |
홈 채널 — 예약 작업 결과가 도착하는 곳
홈 채널(home channel — Hermes 가 먼저 보낼 소식이 도착하는 기본 대화방)은 Hermes 가 스스로 보내는 메시지의 받는 곳입니다. 예약 작업(cron — 정해 둔 시간에 자동 실행)은 결과를 이 대화방으로 보냅니다. 내가 묻지 않았는데 오는 메시지이므로, 어디로 받을지를 미리 정해 두는 것입니다.
정하는 방법은 간단합니다. 결과를 받고 싶은 Telegram 대화방(1:1 대화든 그룹이든)에서 /sethome 을 보냅니다.
예약 작업의 결과를 어디로 보낼지 고르는 방법 전체는 7장 「결과를 어디로 받나」에 있습니다. 홈 채널은 그 밖에도 쓰입니다 — 게이트웨이가 다시 시작되면 “에이전트가 돌아왔다”는 한 줄 알림이 각 메신저의 홈 채널로 올 수 있습니다(기본 켜짐).
파일로 홈 채널 정하기 · 토픽 모드에서 예약 작업 결과 받기
TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"
뜻: ~/.hermes/.env 에 홈 채널의 대화방 ID 와 표시 이름을 직접 적습니다. 그룹 ID 는 음수(예: -1001234567890), 내 1:1 대화의 ID 는 내 사용자 ID 와 같습니다.
Cron deliveries in topic mode — 봇 DM 에서 토픽 모드를 켜 두었다면, 맨 위 대화(root)로 온 예약 작업 메시지는 시스템 전용 로비에 떨어집니다. 거기에 답해도 세션이 열리지 않고 “main chat is reserved for system commands” 안내가 나옵니다. 전용 토픽(예: Cron)을 만들고 아래를 설정합니다.
TELEGRAM_CRON_THREAD_ID=<topic_thread_id>
TELEGRAM_CRON_THREAD_ID 는 예약 작업 전달에 한해 TELEGRAM_HOME_CHANNEL_THREAD_ID 보다 우선합니다. 그 토픽에 단 답은 토픽의 기존 세션을 이어 갑니다.
음성 메시지
Telegram 에서는 글 대신 말로 시킬 수 있습니다. 내가 보낸 음성 메시지는 자동으로 글로 받아 적혀 대화에 들어가고, 에이전트가 음성으로 답하면 Telegram 의 동그란 음성 말풍선으로 옵니다.
받을 때 — Hermes 에 설정된 받아쓰기 제공자가 음성을 글로 바꿉니다. 고를 수 있는 것은 세 가지입니다.
| 제공자 | 어디서 받아쓰나 | 필요한 것 |
|---|---|---|
local | Hermes 가 도는 컴퓨터에서 직접(faster-whisper) | API 키(서비스 이용 열쇠) 필요 없음 |
groq | Groq Whisper | GROQ_API_KEY |
openai | OpenAI Whisper | VOICE_TOOLS_OPENAI_KEY |
보낼 때 — 읽어 주기 제공자는 config.yaml 의 tts.provider 로 정합니다. OpenAI 와 ElevenLabs 는 Telegram 음성 말풍선에 맞는 형식(Opus)을 바로 만들어 따로 할 일이 없습니다. 기본 무료 제공자인 Edge TTS 는 MP3 를 만들기 때문에 형식을 바꿔 주는 프로그램 ffmpeg 가 필요합니다. ffmpeg 가 없어도 소리는 오지만, 동그란 말풍선이 아니라 네모난 재생기가 달린 일반 오디오 파일로 옵니다.
ffmpeg 설치 · 받아쓰기 끄고 원본 파일 넘기기 · 20MB 넘는 파일(Local Bot API Server)
# Ubuntu/Debian
sudo apt install ffmpeg
# macOS
brew install ffmpeg
MP3·M4A 파일은 Telegram 오디오 트랙으로 나가며, ffmpeg 가 있으면 가수·제목·앨범 그림이 재생기에 채워집니다.
Skipping STT — 에이전트가 오디오를 직접 다루게 하려면(화자 구분, 녹음 보관 등) config.yaml 에 stt.enabled: false. 게이트웨이는 파일을 내려받되 받아쓰지 않고, 에이전트는 [The user sent a voice message: /home/<user>/.hermes/cache/audio/<hash>.ogg] 같은 표시가 달린 메시지를 받습니다.
Large Files (>20MB) via Local Bot API Server — Telegram 공개 Bot API 는 내려받기를 20 MB 로 제한해, 더 큰 파일은 Hermes 가 “too large” 로 거절합니다. 내 네트워크에 telegram-bot-api 서버를 직접 돌리면 한도가 2 GB 로 올라갑니다(긴 회의 녹음, 큰 영상).
| 원문 단계 | 하는 일 |
|---|---|
| Step 1: Obtain Telegram API credentials | my.telegram.org/apps 에서 앱을 만들고 api_id · api_hash 를 받습니다. |
| Step 2: Run the telegram-bot-api server | aiogram/telegram-bot-api Docker 이미지에 TELEGRAM_API_ID · TELEGRAM_API_HASH · TELEGRAM_LOCAL: "1" 을 주고 127.0.0.1:8081 로 띄웁니다. 보안: 이 서버는 봇 토큰만 있으면 추가 인증 없이 봇을 조종할 수 있으므로 8081 포트를 인터넷에 절대 열지 않습니다. |
| Step 3: Log the bot out of the public API (one-time) | 봇은 한 번에 한 서버에서만 활성이므로 공개 서버에서 한 번 로그아웃시킵니다: curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/logOut". |
| Step 4: Point Hermes at the local server | config.yaml 의 platforms.telegram.extra 아래 base_url: "http://127.0.0.1:8081/bot" · base_file_url: "http://127.0.0.1:8081/file/bot" · local_mode: true. 맨 위 telegram.extra 에 두면 조용히 버려집니다. hermes gateway restart 후 로그에서 Using custom Telegram base_url 줄을 확인합니다. |
Step 5: local_mode — file access on disk | 서버가 파일을 자기 디스크에 쓰고 경로만 알려 주므로, Hermes 가 그 경로(보통 /var/lib/telegram-bot-api)를 읽을 수 있어야 합니다 — 같은 컴퓨터면 폴더 연결과 소유자 맞추기, 다른 컴퓨터면 같은 절대 경로로 폴더 공유(NFS 등). 못 읽으면 로그에 [Telegram] Failed to cache voice: Not Found. |
| Step 6: Test it | 20 MB 넘는 음성을 보내고 ~/.hermes/logs/gateway.log 에 [Telegram] Cached user voice at … 줄이 나오는지 봅니다. |
계속 켜 두기 — 서비스로 설치
hermes gateway 는 지금 연 터미널 창에서 게이트웨이를 돌립니다(원문: foreground). 연결이 잘 되는지 시험할 때 알맞습니다. 늘 켜 두려면 hermes gateway install 을 씁니다 — 이 명령은 게이트웨이를 운영체제의 서비스(컴퓨터가 알아서 켜고 지켜 주는 프로그램)로 등록합니다.
hermes gateway install # Install as launchd agent
tail -f ~/.hermes/logs/gateway.log # View logs
뜻: launchd(macOS 가 프로그램을 자동으로 켜 주는 장치)에 등록 · 로그 보기.
설치하면 바로 게이트웨이가 시작됩니다. 설치 뒤에 새 도구(예: ffmpeg)를 깔았다면 hermes gateway install 을 한 번 더 실행합니다.
hermes gateway install # Install as user service
journalctl --user -u hermes-gateway -f # View logs
sudo loginctl enable-linger $USER # keeps running after logout
뜻: systemd(Linux 가 프로그램을 자동으로 켜 주는 장치) 사용자 서비스로 설치 · 로그 보기 · 로그아웃한 뒤에도 계속 돌게 하기.
원문 권고: 노트북·개발용 컴퓨터는 사용자 서비스, 부팅 때 스스로 켜져야 하는 서버는 시스템 서비스(sudo hermes gateway install --system).
hermes gateway install # Register the Hermes_Gateway Scheduled Task (runs at logon)
hermes gateway start # Start the gateway hidden, without a console window
뜻: 로그온할 때 실행되는 예약된 작업(Hermes_Gateway)으로 등록 · 창 없이 숨겨서 시작.
주의: 밖에서 강제로 끝낸 게이트웨이는 저절로 다시 켜지지 않습니다. hermes gateway start 로 다시 켭니다.
hermes gateway restart 를 권합니다. 다시 시작할 때 진행 중이던 대화는 표시해 두었다가, 내가 아무 메시지나 보내면 이어서 하려고 시도합니다.
Linux (systemd) 상세 — 시스템 서비스 · 금지 설정 · 다시 시작 방식 · 컨테이너
# Or install a boot-time system service that still runs as your user
sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f
| 원문 항목 | 내용 |
|---|---|
| Don't add a custom ExecStopPost kill drop-in | Hermes 가 설치한 서비스 파일은 이미 깔끔하게 끄고 다시 켭니다. ExecStopPost=/bin/kill -9 $MAINPID 같은 덧설정을 넣으면 다시 시작할 때마다 새 프로세스를 죽여 무한 재시작이 됩니다(Telegram 에 재시작 알림이 쏟아짐). 넣었다면 systemctl --user edit hermes-gateway 로 지우고 systemctl --user daemon-reload. |
| Direct systemctl restart / stop exits cleanly | systemctl --user restart hermes-gateway 도 정상 종료로 기록됩니다. 다만 진행 중인 일이 중요하면 hermes gateway restart — 하던 일을 마무리하게 한 뒤 새 프로세스를 기다립니다. Hermes 를 업데이트한 뒤에도 한 번 실행해 새 서비스 파일을 반영합니다. systemctl reload 는 설정만 다시 읽는 것이 아니라 마무리 후 종료·재실행입니다. |
| Headless VMs: user service + linger | 시스템 서비스는 다시 시작할 때마다 root 권한이 필요합니다(hermes update 끝의 자동 재시작 포함 — 권한이 없으면 건너뛰고 직접 칠 명령을 출력). 로그인하지 않는 서버라면 사용자 서비스 + sudo loginctl enable-linger $USER 로 root 없이 부팅 때 켜지게 합니다. |
| 두 종류를 함께 두지 않기 | 사용자 서비스와 시스템 서비스가 둘 다 있으면 start/stop/status 가 모호해져 Hermes 가 경고합니다. |
| Inside a container, only the system scope is offered | 컨테이너 안에서는 사용자 서비스 설치를 거절합니다(호스트도 같은 서비스를 켜서 같은 봇 토큰을 두 게이트웨이가 쓰게 되기 때문). 컨테이너의 주 프로세스로 hermes gateway run 을 돌리거나 sudo hermes gateway install --system --run-as-user <user>. |
| Multiple installations | HERMES_HOME 이 다른 설치마다 서비스 이름이 따로입니다(기본 hermes-gateway, 나머지 hermes-gateway-<hash>). 서비스 파일은 그것이 가리키는 홈의 것이라 다른 홈에서는 고치지 않습니다(일부러 옮기려면 hermes gateway install --force-unit-path). |
macOS (launchd) · Windows (Task Scheduler) 상세
| 원문 항목 | 내용 |
|---|---|
| macOS — 만들어지는 파일 | ~/Library/LaunchAgents/ai.hermes.gateway.plist. 환경 변수 PATH(설치 시점의 것) · VIRTUAL_ENV · HERMES_HOME 이 들어갑니다. 다른 설치는 ai.hermes.gateway-<suffix>. |
| PATH changes after install | plist 는 고정 파일이라, 설치 뒤 새 도구(새 Node.js, ffmpeg 등)를 깔았으면 hermes gateway install 을 다시 실행합니다. |
| Installing without starting | hermes gateway install --no-start-now(또는 마법사의 “Start the gateway now?” 에 No)는 파일만 쓰고, 게이트웨이는 다음 로그인 때 또는 hermes gateway start 때 시작됩니다. |
| Local Network access | launchd 로 뜬 게이트웨이가 집 안 네트워크 기기(Home Assistant, 로컬 모델 서버)에 닿지 못하고 No route to host 가 나던 문제를 피하려고, 게이트웨이를 /usr/bin/osascript 를 거쳐 실행합니다. 그래서 파일 접근 허락 창에는 Hermes 가 아니라 osascript 이름이 나옵니다. 예전 plist 는 hermes gateway install 로 갱신됩니다. |
| Picking up new credentials | hermes auth add / hermes auth reset 뒤 모든 세션이 새 로그인을 쓰게 하려면 다시 시작합니다. hermes gateway restart 는 진행 중인 차례를 최대 agent.restart_after_turn_timeout(기본 1800초) 기다립니다. launchctl kickstart -k gui/$UID/ai.hermes.gateway 는 진행 중인 대화를 곧바로 끊습니다. 다시 켠 뒤에도 401 이 나면 다른 게이트웨이 프로세스가 또 있는지 hermes gateway status 로 봅니다. |
| Windows — 동작 방식 | 예약된 작업이 %USERPROFILE%\.hermes\gateway-service\ 아래의 실행기를 돌리고, 실행기는 창을 숨긴 채 게이트웨이를 띄운 뒤 곧바로 끝납니다. |
| RestartOnFailure covers the launcher, not the gateway | 작업 스케줄러는 실행기만 지켜보므로 나중에 죽은 게이트웨이는 다시 켜 주지 않습니다. 게이트웨이 스스로의 재시작(/restart, 업데이트, hermes gateway restart)만 됩니다. 밖에서 끝냈다면 hermes gateway start 또는 schtasks /Run /TN <task>. |
| Windows — 낡은 등록 고치기 | 등록된 작업이 낡았으면 hermes gateway status 가 ⚠ Scheduled Task registration predates the current template … 와 고치는 명령을 보여 줍니다. hermes gateway start 와 hermes update 가 자동으로 다시 등록하며, 권한이 모자라면 hermes gateway install 을 다시 실행합니다. |
Operating a multi-platform gateway — 메신저 여러 개를 한 게이트웨이로 운영하기
| 원문 소제목 | 내용 |
|---|---|
/platform command | /platform list(메신저 연결마다 상태 — running · paused · paused-by-breaker) · /platform pause <name>(새 메시지 넘기기 중단, 연결은 유지) · /platform resume <name>. 전체 요약은 /platforms. |
| Disabling a platform whose credentials are still in .env | config.yaml 의 platforms.<name>.enabled: false 가 최종 결정입니다. .env 에 인증 정보가 남아 있어도 그 메신저는 시작되지 않고 시작할 때 WARNING 을 남깁니다. 키를 아예 빼면 “인증 정보가 있으면 시작”입니다. |
Ignoring an inherited proxy (gateway.trust_env) | 서비스로 뜬 게이트웨이가 엉뚱한 프록시를 물려받아 Cannot connect to host 127.0.0.1:7890 이 반복되면 gateway.trust_env: false. TELEGRAM_PROXY 같은 플랫폼별 변수는 계속 적용됩니다. |
| Automatic circuit breaker | 실패(네트워크 끊김, 속도 제한, 5xx 등)가 거듭되면 그 메신저 연결을 자동으로 멈추고, 다른 살아 있는 플랫폼의 홈 채널로 알립니다. 자동으로 풀리지 않습니다 — /platform resume <name>. |
| Where to look when a platform is paused | ① 게이트웨이 로그에서 플랫폼 이름과 circuit breaker · paused · disabled 검색 ② /platform list ③ 그 메신저 회사의 상태 페이지. |
| Restart notifications · Typing indicators | 플랫폼별 gateway_restart_notification(다시 시작 알림을 홈 채널로 한 번) · typing_indicator(처리 중 표시). 둘 다 기본 true. |
| Session resume across gateway restarts | 일하던 도중에 꺼진 세션은 다음에 켜질 때 “Send any message after restart and I'll try to resume where you left off.” 안내를 받고, 진행 중이던 차례만 한 번 이어집니다. 기본 켜짐. |
| Mobile-friendly progress defaults | Telegram 기본값: tool_progress off · busy_ack_detail off · interim_assistant_messages on · long_running_notifications on. display: 바로 아래 같은 키를 두면 모든 플랫폼에 적용되고, 플랫폼별로는 display.platforms.telegram 아래에 둡니다. |
| Warning and error notifications (opt-in suppression) | display.suppress_warning_notifications: true(전역 또는 플랫폼별)로 자동 경고·오류 알림을 숨깁니다. 실행·로그·재시도는 그대로이고, 승인·되묻기와 내가 요청한 결과는 숨기지 않습니다. |
| Progress bubble cleanup (opt-in) | display.platforms.<platform>.cleanup_progress: true 면 최종 답 뒤에 진행 표시 말풍선을 지웁니다(지금은 Telegram·Discord, 실패한 실행은 남김). |
Telegram 세부 기능 — 필요할 때 펼쳐 보기
Telegram 쪽 원문에는 위에서 다룬 것 말고도 기능이 많습니다. 처음에는 몰라도 되지만, “이런 것도 되나?” 싶을 때 찾아볼 수 있게 한 줄씩 정리합니다. 설정 방법은 아래 접힌 상자에 있습니다.
| 기능 | 한 줄 설명 | 기본 |
|---|---|---|
| DM 토픽 (Private Chat Topics) | 봇과의 1:1 대화 안에 주제별 방을 만들어, 방마다 따로 세션을 씁니다 | 설정해야 켜짐 |
여러 세션 DM (/topic) | 내가 /topic 을 보내 켜고, 토픽을 원하는 만큼 만들어 대화를 여러 개 나란히 진행합니다 | /topic 으로 켬 |
| 그룹 토픽에 스킬 묶기 | 그룹의 특정 토픽에서 새 세션이 시작될 때 정해 둔 스킬을 자동으로 불러옵니다 | 설정해야 켜짐 |
| 채널별 지시문 | 그룹·토픽마다 다른 역할 지시문을 줍니다 | 설정해야 켜짐 |
파일 보내기 (MEDIA:) | 에이전트의 답에 든 MEDIA:/경로 표시를 게이트웨이가 첨부 파일로 바꿔 보냅니다 | 켜짐 |
| 답이 써지는 모습 보기 | 1:1 대화에서 답이 글자 단위로 늘어나는 미리 보기를 보여 줍니다 | 실시간 갱신을 켜면 |
| 표·체크 목록 그대로 보이기 | Telegram 의 Rich Messages 로 표·할 일 목록·접는 글·수식을 본래 모양대로 보냅니다 | 꺼짐 |
| 이모지 반응 | 처리 시작 👀 → 성공 👍 / 오류 👎 로 상태를 알립니다 | 꺼짐 |
| 알림 소리 줄이기 | 최종 답·승인 요청·명령 확인에만 알림이 울리고, 진행 표시는 무음으로 옵니다 | 켜짐 (important) |
| 상태 메시지 제자리 고침 · 내 메시지 고정 | 되풀이되는 상태 글은 새로 쌓지 않고 같은 말풍선을 고칩니다. 일하는 동안 내 메시지를 대화방 위에 고정했다가 끝나면 풉니다 | 켜짐 (설정 없음) |
| Webhook 모드 · 프록시 · 대체 IP | 클라우드 배포나 Telegram 접속이 막힌 네트워크를 위한 연결 방식입니다 | 상황에 따라 |
토픽 — Private Chat Topics · Multi-session DM mode (/topic) · Group Forum Topic Skill Binding · Per-Channel Prompts
Private Chat Topics (Bot API 9.4) — 2026년 2월부터 봇이 1:1 대화 안에 토픽을 만들 수 있고, 토픽마다 세션·기록·문맥이 따로입니다. 먼저 BotFather Mini App(검색 결과에서 Open — 옛 /mybots 글 메뉴에는 없음)에서 My bots → 내 봇 → Bot Settings → Threads Settings → Threaded Mode 를 켭니다. 켜지 않으면 로그에 The chat is not a forum 이 남고 토픽이 만들어지지 않습니다.
platforms:
telegram:
extra:
dm_topics:
- chat_id: 123456789 # Your Telegram user ID
topics:
- name: Research
icon_color: 16766590
skill: arxiv # Auto-load a skill in this topic
| 항목 | 내용 |
|---|---|
| 필드 · How it works | name(필수) · icon_color · icon_custom_emoji_id · skill · thread_id(자동으로 채워짐 — 직접 넣지 않음). 게이트웨이가 켜질 때 없는 토픽을 만들고 번호를 config.yaml 에 저장합니다. 토픽마다 세션 열쇠가 따로입니다(agent:main:telegram:dm:{chat_id}:{thread_id}). |
| Root DM handling | ignore_root_dm: true 면 토픽을 설정한 사용자의 맨 위 대화는 로비가 되어 일반 메시지는 무시되고 /start·/help·/status 같은 명령만 됩니다. |
| Skill binding | skill 이 있는 토픽은 새 세션이 시작될 때 그 스킬을 자동으로 불러옵니다 — 대화 첫머리에 /skill-name 을 친 것과 같습니다. |
Multi-session DM mode (/topic) — 설정 파일 없이 사용자가 /topic 으로 켜고, 토픽을 원하는 만큼 만들면 하나하나가 독립된 세션이 됩니다. 허용 목록에 있는 사용자만 쓸 수 있습니다.
| 보내는 것 | 어디서 | 결과 |
|---|---|---|
/topic | 맨 위 DM | 아직 안 켰으면 BotFather 설정을 확인하고 켠 뒤 System 토픽을 만듭니다. 이미 켰으면 되살릴 수 있는 세션 목록을 보여 줍니다 |
/topic · /topic <session-id> | 토픽 안 | 지금 토픽에 묶인 세션 표시 · 이전 세션을 지금 토픽에 되살림(같은 사용자의 것이고 다른 토픽에 묶여 있지 않아야 함) |
/topic off · /topic help | 맨 위 DM · 어디서나 | 끄고 토픽 묶음을 지움(Telegram 의 토픽은 남음) · 사용법 |
| 항목 | 내용 |
|---|---|
| DM Topics vs Multi-session DM mode | extra.dm_topics 는 운영자가 설정 파일로 정한 고정 토픽, /topic 은 사용자가 마음대로 만들고 지우는 즉석 세션(맨 위 DM 이 로비가 되고 토픽 이름이 세션 제목을 따라 바뀜). 둘은 한 봇에서 함께 쓸 수 있습니다. |
| Prerequisites · Activation flow | Threads Settings 에서 Threaded Mode 를 켜고 사용자의 토픽 만들기를 끄지 않습니다. 조건이 안 맞으면 Hermes 가 설정 화면 그림과 함께 알려 줍니다. 새 토픽은 봇 DM 맨 위의 All Messages 를 누르고 아무 메시지나 보내면 생깁니다. |
| Messages sent in the root DM | 기본은 가장 최근에 쓴 토픽에서 이어서 답합니다. dm_topic_auto_transfer: true 면 메시지마다 새 토픽(“Hermes Chat”)을 만듭니다. |
Auto-renamed topics · /new | 세션 제목이 생기면 토픽 이름도 바뀝니다(끄려면 disable_topic_auto_rename: true). 토픽 안의 /new 는 그 토픽의 세션만 새로 시작합니다. |
| Under the hood · Disabling · Downgrading | 상태는 state.db 의 telegram_dm_topic_mode · telegram_dm_topic_bindings 표에 프로필별로 저장되며 처음 /topic 을 쓸 때 만들어집니다. 로비 안내는 30초에 한 번만 보냅니다. 여러 대화를 한꺼번에 정리하려면 sqlite3 ~/.hermes/state.db 로 두 표를 고칩니다. 이전 버전으로 내리면 기능만 멈추고, 다시 올리면 이어집니다. |
Group Forum Topic Skill Binding — 토픽 모드가 켜진 슈퍼그룹은 토픽마다 이미 세션이 따로입니다. platforms.telegram.extra.group_topics 에 chat_id(필수, -100 으로 시작) · thread_id(필수 — DM 토픽과 달리 직접 넣음) · name · skill 을 적으면 그 토픽에서 스킬을 자동으로 불러옵니다(예: Engineering → software-development). thread_id 는 토픽 주소 t.me/c/1234567890/5 의 마지막 숫자입니다. 설정에 없는 토픽은 오류 없이 지나갑니다.
Per-Channel Prompts — telegram.channel_prompts 에 대화방 ID 나 토픽 ID 별로 지시문을 적습니다. 매 차례 끼워 넣고 기록에는 저장하지 않아 고치면 바로 적용됩니다. 토픽의 지시문이 그룹 것보다 우선합니다.
연결 방식 — Webhook Mode · Proxy Support(두 절) · DNS-over-HTTPS Fallback IPs
Webhook Mode — 기본은 long polling: 게이트웨이가 Telegram 서버에 새 소식을 계속 물으러 나갑니다. 클라우드(Fly.io, Railway, Render 등)는 들어오는 요청으로만 잠든 기계를 깨울 수 있어, 폴링 봇은 잠들 수 없습니다. Webhook 은 방향을 뒤집어 Telegram 이 내 봇의 HTTPS 주소로 소식을 밀어 넣습니다.
| Polling (기본) | Webhook | |
|---|---|---|
| 방향 · 알맞은 곳 | 게이트웨이 → Telegram · 내 컴퓨터, 늘 켜 둔 서버 | Telegram → 게이트웨이 · 자동으로 깨어나는 클라우드 |
| 설정 · 쉴 때 | 추가 설정 없음 · 기계가 계속 켜져 있어야 함 | TELEGRAM_WEBHOOK_URL · 메시지 사이에 잠들 수 있음 |
변수 (~/.hermes/.env) | 설명 |
|---|---|
TELEGRAM_WEBHOOK_URL | 필수. Telegram 이 소식을 보낼 공개 HTTPS 주소(예: https://my-app.fly.dev/telegram). 설정하면 폴링 대신 웹훅 서버가 뜹니다. |
TELEGRAM_WEBHOOK_SECRET | URL 을 설정했다면 필수. 요청 확인용 비밀 값이며 없으면 게이트웨이가 시작을 거부합니다(GHSA-3vpc-7q5r-276h). openssl rand -hex 32 로 만듭니다. |
TELEGRAM_WEBHOOK_PORT | 선택. 웹훅 서버가 듣는 로컬 포트(기본 8443). |
Fly.io 예: fly secrets set 으로 두 값을 넣고, fly.toml 에서 internal_port = 8443 을 443 으로 열고, fly deploy. 로그에 [telegram] Connected to Telegram (webhook mode). 가 보이면 됩니다.
Proxy Support — 원문에 같은 제목의 절이 두 개 있습니다. ① Telegram 전용: config.yaml 의 telegram.proxy_url: "socks5://127.0.0.1:1080"(권장) 또는 TELEGRAM_PROXY. http:// · https:// · socks5:// 를 지원하고 일반 프록시 변수보다 우선합니다. ② 표준 환경 변수: 회사 네트워크처럼 프록시가 필요한 곳에서는 HTTPS_PROXY → HTTP_PROXY → ALL_PROXY → 소문자 변수 순으로 처음 설정된 것을 자동으로 씁니다(게이트웨이를 켜기 전에 export 하거나 ~/.hermes/.env 에 적음).
DNS-over-HTTPS Fallback IPs — 제한된 네트워크에서 api.telegram.org 에 닿지 않을 때 다른 IP 로 조용히 다시 시도합니다. 순서: TELEGRAM_FALLBACK_IPS → Google·Cloudflare DNS 에 DoH 로 물어 찾은 IP → 내장 목록(149.154.166.110, 149.154.167.220) → 호스트 이름. 보통은 설정할 필요가 없고, 직접 줄 때는 TELEGRAM_FALLBACK_IPS 나 platforms.telegram.extra.fallback_ips. 끄려면 HERMES_TELEGRAM_DISABLE_FALLBACK_IPS=true, IPv6 가 고장 난 컴퓨터는 network.force_ipv4: true.
표시 — Recent Bot API Features · Rendering · Message Reactions · Push notification volume · Status messages · Pin
| 원문 제목 | 내용 |
|---|---|
| Recent Bot API Features | ① Bot API 9.4(2026년 2월): Private Chat Topics. ② Privacy policy: Telegram 이 봇에 개인정보 처리방침을 요구합니다 — BotFather /setprivacy_policy 로 정하지 않으면 임시 문서가 자동으로 만들어질 수 있습니다. ③ Bot API 9.5(2026년 3월): sendMessageDraft 를 이용한 실시간 표시. |
| Streaming transport | gateway.streaming.enabled: true 일 때 gateway.streaming.transport: auto(기본 — Telegram DM 에서는 글자 단위로 늘어나는 draft 미리 보기, 나머지는 메시지 고치기) · draft · edit(항상 메시지 고치기) · off(최종 답만). 미리 보기가 깜빡이면 edit. 그룹은 Telegram 제한으로 항상 edit 방식입니다. |
| Rendering: Rich Messages, Tables and Link Previews | rich_messages: true 로 켜면 표·할 일 목록·접는 글·수식을 본래 모양대로 보냅니다(Bot API 10.1). 기본은 꺼짐 — rich 메시지는 일반 글로 복사하기 어렵기 때문입니다. 한국어·중국어·일본어 글은 일부 데스크톱 앱에서 글자가 겹쳐 보여 기본으로 예전 방식에 남습니다(allow_cjk_rich_messages: true 로 감수하고 켬). 예전 방식(MarkdownV2)에서는 작은 표는 글머리 목록으로, 큰 표는 코드 블록으로 바뀝니다(telegram.pretty_tables: false 면 항상 코드 블록). 주소 미리 보기는 disable_link_previews: true 로 끕니다. 4,096자를 넘는 답은 (1/3) 처럼 번호를 붙여 나눠 보냅니다. |
| Message Reactions | 👀 처리 시작 · 👍 성공 · 👎 오류. 기본 꺼짐 — telegram.reactions: true 또는 TELEGRAM_REACTIONS=true. 반응은 통째로 바뀌므로 둘이 함께 보이지 않습니다. |
| Push notification volume | display.platforms.telegram.notifications: important(기본 — 최종 답·승인 요청·명령 확인만 울림) | all. 환경 변수 HERMES_TELEGRAM_NOTIFICATIONS. |
| Status messages edited in place | 되풀이되는 상태 알림(“Compressing context…”)은 새로 보내지 않고 기존 말풍선을 고칩니다. 설정 없음. |
| Pin incoming user message during agent turn | 일하는 동안 내 메시지를 무음으로 고정했다가 답이 끝나면 풉니다 — 일하는 중이라는 표시입니다. 설정 없음. |
파일 보내기 — Sending Generated Files from Docker-backed Terminals · 지원 확장자
터미널 백엔드(에이전트의 명령이 실제로 실행되는 곳 — 4장)가 docker 일 때 주의: 첨부는 컨테이너 안이 아니라 게이트웨이가 보내므로, MEDIA:/… 경로는 게이트웨이가 도는 컴퓨터에서 읽을 수 있어야 합니다. 컨테이너 안에만 있는 /workspace/report.txt 를 가리키면 전송에 실패합니다.
terminal:
backend: docker
docker_volumes:
- "/home/user/.hermes/cache/documents:/output"
뜻: 컨테이너의 /output 을 호스트 폴더에 연결합니다. 컨테이너 안에서는 /output/… 에 쓰고, MEDIA: 에는 호스트 경로(MEDIA:/home/user/.hermes/cache/documents/report.txt)를 적습니다.
| 종류 | 지원 확장자 (모든 게이트웨이 플랫폼 공통) |
|---|---|
| 이미지 | png, jpg, jpeg, gif, webp, bmp, tiff, svg |
| 오디오 · 영상 | mp3, wav, ogg, m4a, opus, flac, aac · mp4, mov, webm, mkv, avi |
| 문서 · 오피스 | pdf, txt, md, csv, json, xml, html, yaml, yml, log · docx, xlsx, pptx, odt, ods, odp |
| 압축 · 책/패키지 | zip, rar, 7z, tar, gz, bz2 · epub, apk, ipa |
지원하지 않는 플랫폼에서는 링크나 글 표시로 대신합니다. 원문은 “굵게 표시한 종류는 최근에 추가됐다”고 적지만, 받은 글에는 굵은 표시가 남아 있지 않습니다.
문제 해결
Telegram 쪽 원문의 문제 해결 표를 옮깁니다. 대부분은 토큰·허용 목록·개인 정보 보호 모드 셋 중 하나입니다.
| 증상 | 해결 |
|---|---|
| 봇이 전혀 답하지 않는다 | TELEGRAM_BOT_TOKEN 이 맞는지 확인합니다. hermes gateway 로그에서 오류를 찾습니다 |
| 봇이 “unauthorized” 라고 답한다 | 내 사용자 ID 가 TELEGRAM_ALLOWED_USERS 에 없습니다. @userinfobot 으로 다시 확인합니다 |
| 그룹 메시지를 무시한다 | 개인 정보 보호 모드가 켜져 있을 가능성이 큽니다. 끄거나(그룹 대화) 봇을 그룹 관리자로 만듭니다. 바꾼 뒤 봇을 내보냈다가 다시 넣는 것을 잊지 마세요 |
| 음성 메시지가 글로 바뀌지 않는다 | 받아쓰기를 쓸 수 있는지 확인합니다 — 로컬 받아쓰기용 faster-whisper 를 설치하거나, ~/.hermes/.env 에 GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY 를 넣습니다 |
| 음성 답이 말풍선이 아니라 파일로 온다 | ffmpeg 를 설치합니다(Edge TTS 의 형식 변환에 필요) |
| 봇 토큰이 무효가 됐다 | BotFather 에서 /revoke 뒤 /newbot 또는 /token 으로 새 토큰을 받고 .env 를 고칩니다 |
| Webhook 으로 소식이 오지 않는다 | TELEGRAM_WEBHOOK_URL 이 밖에서 닿는지(curl 로 시험), 들어오는 HTTPS 요청이 TELEGRAM_WEBHOOK_PORT 의 로컬 포트로 이어지는지(두 포트 번호가 같을 필요는 없음), SSL/TLS 가 켜져 있는지(Telegram 은 HTTPS 로만 보냄), 방화벽 규칙을 확인합니다 |
게이트웨이 자체를 볼 때는 이 순서가 빠릅니다.
| 순서 | 무엇을 보나 |
|---|---|
① hermes gateway status | 게이트웨이가 실제로 돌고 있는지 봅니다. 설정이 저장돼 있다는 것과 게이트웨이가 켜져 있다는 것은 다릅니다 |
| ② 로그 | macOS 는 tail -f ~/.hermes/logs/gateway.log, Linux 사용자 서비스는 journalctl --user -u hermes-gateway -f |
③ /platform list | 메신저 하나만 조용하면 그 연결이 멈춰(paused) 있는지 봅니다. 실패가 거듭되면 Hermes 가 그 연결을 자동으로 멈추며 저절로 풀리지 않습니다 — 메신저가 회복된 뒤 /platform resume <name> |
더 많은 증상은 10장 「메신저 봇 문제」와 활용편 실습 10에서 다룹니다.
- 게이트웨이는 메신저와 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로 관리합니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/messaging · hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram (수집일 2026-11-09 의 공식 문서, 문서에 버전 표기 없음)
안전장치와 되돌리기
Hermes Agent 는 말만 하는 챗봇이 아니라, 내 컴퓨터에서 명령을 실행하고 파일을 고치는 AI 에이전트(도구를 써서 내 대신 일을 해 주는 AI 프로그램)입니다. 그래서 “엉뚱한 명령을 실행하면 어쩌지?”, “모르는 사람이 내 봇에게 말을 걸면?”, “파일을 망가뜨리면?” 같은 걱정이 따라옵니다. 이 장에서는 Hermes 가 그런 일을 막으려고 둔 여덟 겹의 안전장치와, 그래도 일이 틀어졌을 때 파일을 이전 상태로 돌려놓는 체크포인트와 /rollback 을 살펴봅니다.
- Hermes 의 안전장치가 몇 겹이고, 각각 무엇을 막는지
- 위험한 명령을 실행하기 전에 Hermes 가 나에게 어떻게 묻는지, 네 가지 선택지(once · session · always · deny)가 무슨 뜻인지
- 메신저 봇을 누가 쓸 수 있는지 정하는 두 가지 방법 — 허용 목록과 페어링 코드
- 명령을 Docker 같은 격리된 곳에서 실행하면 무엇이 달라지는지
- 체크포인트가 언제 찍히고,
/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 로 바꾸면 그 자리의 위험 명령을 모두 자동 승인합니다(설정 키는 아래 접힌 표). 절대 금지 목록은 이때도 그대로입니다.
approvals 설정 키 전체
~/.hermes/config.yaml 의 approvals: 아래에 둡니다.
| 키 | 기본값 | 무엇을 정하나 |
|---|---|---|
mode | smart | 위험한 셸 명령의 승인 방식 — smart · manual · off. |
timeout | 300 | 승인 답을 기다리는 시간(초). |
discord_prompt_timeout | 300 | Discord 의 버튼(승인·되묻기·업데이트·슬래시 명령 확인)이 눌리는 시간(초). 최소 30. |
cron_mode | deny | 예약 작업이 위험 명령을 만났을 때. deny 는 막고, approve 는 예약 작업 안의 모든 것을 자동 승인. |
single_query_mode | deny | hermes chat -q 한 번짜리 세션이 만났을 때. cron_mode 와 같은 방식. |
unattended_mode | deny | 사람 없는 프로그램용 플랫폼(webhook, msgraph_webhook, api_server) 세션이 만났을 때. 시간 초과를 기다리지 않고 바로 판정. 예외: 클라이언트가 승인 카드에 답할 수 있는 api_server 세션(/v1/runs, 스트리밍 chat completions — POST /v1/runs/{id}/approval)은 승인 요청을 그대로 받음. |
mcp_reload_confirm | true | /reload-mcp 가 MCP 도구 묶음을 다시 만들기 전에 물음. 다시 만들면 제공자(provider — AI 모델을 빌려주는 서비스) 쪽 프롬프트 캐시가 무효가 되어 다음 메시지에서 입력 토큰을 전부 다시 보냄. Always Approve 를 누르면 false 로 바뀜. |
destructive_slash_confirm | true | /clear·/new·/reset·/undo 가 대화 상태를 버리기 전에 물음(Approve Once / Always Approve / Cancel). Telegram·Discord·Slack 은 버튼, 그 밖은 글자. Always Approve 를 누르면 false. TUI(hermes --tui 로 여는 새 터미널 화면)도 이 설정을 따르며, HERMES_TUI_NO_CONFIRM=1 은 설정과 무관하게 확인 창을 건너뜀. |
CLI 는 /quit --delete(/exit --delete 도 같은 명령)도 실행 전에 확인합니다. Discord 와 Slash Commands 의 세부는 공식 문서 해당 쪽 참고(이 가이드는 다루지 않음).
승인을 부르는 패턴 전체와 내용 기반 검사
원문의 패턴 표(tools/approval.py 에 정의)를 성격별로 모았습니다.
| 부류 | 패턴 |
|---|---|
| 삭제 | rm -r / rm --recursive(폴더째 삭제) · rm ... /(맨 위 경로에서 삭제) · xargs rm · find -exec rm / find -delete |
| 권한·소유자 | chmod 777/666 / o+w / a+w(누구나 쓰기) · chmod --recursive + 위험한 권한 · chown -R root / chown --recursive root |
| 디스크 | mkfs(포맷) · dd if=(디스크 복사) · > /dev/sd(장치에 직접 쓰기) |
| SQL | DROP TABLE/DATABASE · DELETE FROM(WHERE 없이) · TRUNCATE TABLE |
| 시스템 설정·민감한 파일 | > /etc/ · tee 또는 >/>> 로 /etc/, ~/.ssh/, ~/.hermes/.env 덮어쓰기 · cp/mv/install 로 /etc/ 에 · sed -i / sed --in-place 를 /etc/ 에 |
| 서비스·프로세스 | systemctl stop/restart/disable/mask · kill -9 -1(모든 프로세스) · pkill -9 · fork bomb 패턴 |
| 코드 바로 실행 | bash -c / sh -c / zsh -c / ksh -c(-lc 처럼 붙여 쓴 것 포함) · python -e / perl -e / ruby -e / node -c · curl ... | sh / wget ... | sh · bash <(curl ...) / sh <(wget ...) |
| Hermes 자신 | pkill/killall hermes/gateway(자기 종료 방지) · gateway run 을 &/disown/nohup/setsid 와 함께(서비스 관리자 밖에서 게이트웨이를 띄우는 것 방지) |
| 컨테이너 | docker stop/kill/restart, docker compose down/stop/kill/restart(전역 옵션·docker-compose 포함) · docker -H/--host/--context, DOCKER_HOST=/DOCKER_CONTEXT=(다른 데몬을 겨냥) · docker context use(기본 데몬 변경) · podman --remote/-r/--url/--connection/--identity, CONTAINER_HOST= |
내용 기반 검사(Content-Level Command Checks). 위험한 동사 목록으로는 놓치는 두 가지 모양도 같은 승인 흐름에 태웁니다. ① 비밀 값을 실어 보내는 curl/wget — 비밀스러운 이름의 변수(-d "k=$OPENAI_API_KEY")나 자격 증명 파일(-F file=@.env, -T ~/.ssh/id_rsa, --post-file=/etc/passwd)을 올리는 경우. Authorization 헤더는 평범한 API 사용이라 잡지 않습니다. ② 보이지 않거나 글자 방향을 뒤집는 유니코드 제어 문자 — 승인한 명령과 실행되는 명령이 달라지게 만듭니다(이모지용 문자는 제외).
이전 버전에 들어 있던 외부 검사기 tirith 는 제거되었습니다. 업그레이드하면 security.tirith_* 설정이 사라지고 그 자리에 새로 켜지는 것은 없습니다.
내가 정하는 금지 규칙 — approvals.deny
절대 금지 목록은 Hermes 코드에 고정되어 있습니다. approvals.deny 는 그것의 “내가 고칠 수 있는 판”으로, 여기 적은 패턴에 맞는 터미널 명령은 --yolo·/yolo·approvals.mode: off 를 따지기 전에 무조건 막힙니다. “무엇이든 하게 두되 이것만은 절대 안 됨” 식으로 YOLO 를 쓸 때 유용합니다.
approvals:
deny:
- "git push --force*"
- "*curl*|*sh*"
- "dd if=* of=/dev/*"
- 패턴은 fnmatch glob(
*,?,[...])이며 대소문자를 가리지 않습니다. 명령 전체 글과, 그 안에서 실제 실행되는 명령 후보 하나하나에 대조합니다.git push --force*는git push --force origin main에 맞고git push origin main에는 맞지 않습니다. - 위험 패턴 탐지기와 같은 “정리된” 명령 변형에 대조하므로
git pu""sh --force같은 따옴표 속임수는 통하지 않습니다.;·&&·파이프 뒤의 명령,sudo·env·nohup같은 실행 도우미 뒤의 명령, 셸-c안쪽도 봅니다(전체 목록은 원문 참고). - 실행 파일은 적힌 경로와 파일 이름 양쪽으로 대조합니다 —
sudo *는/usr/bin/sudo -n id도 막습니다. 경로를 적은/usr/bin/sudo *는 그 경로에만 맞습니다.echo 'sudo -n id'처럼 따옴표 안에서 언급만 한 것은 명령으로 치지 않지만,*sudo*같은 전체 글 대상 glob 은 언급에도 맞습니다. - YAML 에서는 패턴을 항상 따옴표로 감쌉니다(맨 앞
*,{,!,:는 YAML 에서 다른 뜻). 작은따옴표가 가장 안전합니다. - 격리된 컨테이너를 포함한 모든 터미널 백엔드에 적용됩니다. 막힌 명령은 에이전트에게 “다시 시도하거나 말을 바꾸지 말라”는
BLOCKED오류를 돌려주고, 아무것도 실행되지 않습니다. 설정을 바꾸면 세션을 다시 시작하지 않아도 바로 적용됩니다.
절대 금지 목록은 셸 따옴표를 해석할 수 없는 명령(grep 'unterminated)도 막습니다 — 오류에 malformed executable payload 라고 나옵니다. 따옴표 안의 정상적인 이스케이프는 문제 삼지 않고, 이스케이프된 따옴표로 뒤따르는 명령(echo "a\"b"; reboot)을 숨길 수도 없습니다.
영구 허용 목록(command_allowlist)과 승인 기록에서 제안 받기
승인 창에서 always 로 답한 명령은 ~/.hermes/config.yaml 에 저장되어, Hermes 가 시작할 때 읽히고 이후 모든 세션에서 묻지 않고 승인됩니다.
# Permanently allowed dangerous command patterns
command_allowlist:
- rm
- systemctl
- 항목은 정확한 명령 글, 셸식 glob(
podman *), 또는 위험 패턴의 규칙 키(승인 창에 표시되는 이름, 예:script execution via heredoc)일 수 있습니다. 규칙 키는 사람이 없는 실행에서도 통합니다 —cron_mode등이deny여도 탐지된 규칙 키가 목록에 있으면 실행됩니다. - 값은 문자열 목록이어야 합니다. 잘못된 값은 경고와 함께 무시되고(예전 방식의 따옴표 친 목록은 되살려 읽음), 읽는 과정에서 설정 파일을 고쳐 쓰지는 않습니다.
hermes config edit로 살펴보고 지웁니다. 지운 뒤에는 Hermes 를 다시 시작하세요 — 목록은 시작할 때 읽으므로, 돌아가던 세션에서는 그 세션이 파일을 다시 쓰거나 재시작할 때까지 계속 승인된 상태입니다.
승인 기록에서 제안 받기(hermes approvals suggest). 세션 데이터베이스(~/.hermes/state.db)에서 내가 승인해 실제로 실행된 위험 명령을 찾아 패턴으로 모으고, 승인 횟수 순으로 허용 목록 후보를 보여 줍니다.
hermes approvals suggest # 미리 보기 — 번호 붙은 제안만 출력
hermes approvals suggest --apply 1,3 # 고른 번호를 command_allowlist 에 합침
hermes approvals suggest --json # 프로그램이 읽기 좋은 출력
Proposed command_allowlist additions (from approval history, last 90 days):
1. git push * — approved 14x
2. docker restart/stop/kill (container lifecycle) — approved 9x (class key)
- 자동으로 적용되는 것은 없습니다.
--apply N[,M...]을 붙여야config.yaml에 씁니다. 이미 목록에 있는 것은 건너뜁니다. - 파괴적인 부류(재귀 삭제, sudo, 디스크·장치 쓰기, 자격 증명·시스템 설정 수정, 파이프로 셸에 넘기기, SQL DROP/TRUNCATE, 프로세스 종료, 절대 금지 부류)는 아무리 자주 승인했어도 제안하지 않습니다.
- 명령 속 자격 증명은 출력에서 가려지고 허용 패턴으로 쓰이지 않습니다(세션 데이터베이스에는 실행된 그대로 남아 있음).
- 옵션:
--days N(기본 90),--min-count N(기본 2),--limit N,--db PATH.
execute_code 스크립트 · 게이트웨이 자기 재시작 금지 · YOLO 가 건너뛰지 않는 것
execute_code 스크립트. execute_code 도구로 돌리는 스크립트는 subprocess·os·shutil 을 직접 부를 수 있어 위의 패턴 검사를 거치지 않습니다. 그래서 메신저·API 등 게이트웨이 세션에서는 시작 전에 스크립트 전체에 대해 한 번 묻고, 거부하거나 답하지 않으면 실행하지 않습니다. cron_mode·single_query_mode·unattended_mode 는 스크립트도 즉시 판정하고, YOLO 와 mode: off 는 이 확인을 건너뜁니다.
내 컴퓨터에서 여는 세션(기존 CLI, TUI, Desktop, ACP 편집기)에서는, 보는 사람이 직접 입력한 턴이고 승인에 답할 사람이 붙어 있으면 스크립트 전체 승인 없이 스크립트 안의 terminal() 호출만 하나씩 묻습니다. 아무도 입력하지 않은 턴(플러그인 inject_message, 위임 완료·백그라운드 알림, /loop 틱, heartbeat, hosted-room 작업), delegate_task 의 하위 에이전트(일을 나눠 받은 별도 에이전트)와 /bg·/btw 작업, 승인할 사람이 없을 때는 전체 승인이 유지됩니다.
게이트웨이 자기 재시작 금지(Supervised-gateway lifecycle restriction). 터미널 도구에는, 감독받으며 도는 게이트웨이(메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)를 그 안에서 멈추거나 재시작하지 못하게 하는 별도의 가드가 있습니다(자기 재시작은 도구가 끝나기 전에 종료시켜 재시작이 되풀이될 수 있음). 사용자 승인, YOLO, force=True 로도 풀리지 않습니다.
- 게이트웨이가 돌아가는 python 자체를 겨냥한 이름 기반 종료(
pkill -9 python3,killall python,taskkill /F /IM python.exe,Stop-Process -Name python,pgrep python | xargs kill등)도 거부합니다. 에이전트가 가진 프로세스만 겨냥한 종료(백그라운드 작업의proc_*id, 명시한 PID)와 다른 프로그램 이름은 통과합니다. - 모든 실행기(systemd, launchd, s6, Windows 예약 작업)에서
HERMES_SUPERVISED_CHILD표시로 켜집니다. macOS 에서는launchctl submit·bootstrap이 작업 이름과 관계없이 제한되므로, LaunchAgent 정비는 게이트웨이 밖의 별도 셸에서 합니다(launchctl print는 해당 없음). - 도구가 거절했다는 것은 그 명령이 그 도구 호출로는 실행되지 않았다는 뜻입니다. 모델을 바꿔도 이 가드의 정책은 바뀌지 않습니다.
YOLO 가 건너뛰지 않는 것. YOLO 와 approvals.mode: off 는 trust: untrusted MCP 서버의 쓰기 도구 확인도 건너뜁니다. 그러나 ① MCP 서버의 지출 한도(spend_limit)를 넘게 될 호출은 여전히 묻고, 답할 사람이 없는 곳에서는 거절됩니다(한도는 내가 정한 예산이지 안전 확인 창이 아님). ② MCP 서버가 나에게 던지는 질문(elicitation), ③ 자격 증명 보관함의 결제 카드 입력 확인, ④ MCP 이벤트 구독도 그대로 묻습니다.
게이트웨이를 실행하면 환경 변수 HERMES_EXEC_ASK=1 이 자동으로 설정됩니다.
파일 쓰기 보호 — 손대면 안 되는 곳
승인이 “터미널 명령”을 지키는 문이라면, 파일 쓰기 보호는 Hermes 의 파일 쓰기 도구(write_file·patch)를 지키는 문입니다. 이 도구들이 디스크에 손대기 전에 Hermes 는 대상 경로를 금지 목록과(켜 두었다면) 쓰기 울타리에 대조합니다. 막힌 쓰기는 곧바로 오류로 돌아갑니다. 승인 창이 뜨지 않고, 대화 화면에서 풀 방법도 없습니다.
~/.ssh/config)는 원문이 든 유일한 예외입니다.언제나 막히는 곳은 크게 세 부류입니다.
| 부류 | 예 | 쉬운 말로 |
|---|---|---|
| 운영체제의 자격 증명(로그인 열쇠·비밀번호 같은 것) 보관 장소 | ~/.ssh/, ~/.aws/, ~/.kube/, /etc/sudoers, ~/.netrc | 다른 서버·클라우드에 들어가는 열쇠가 있는 곳 |
| Hermes 의 비밀 보관 장소 | .env, vault/, mcp-tokens/, pairing/ 등(Hermes 홈 폴더 아래) | API 키(서비스를 쓸 때 내는 비밀 열쇠 글자)와 로그인 토큰, 페어링 기록 |
| Windows 의 특수 장치 경로 | \??\..., \\.\... 등 | 경로를 확인하는 것만으로도 로그인 정보가 새어 나갈 수 있는 특수 주소 — 읽기·쓰기 모두 거절 |
.env, .env.local, .env.production, .envrc 파일은 디스크 어디에 있든 파일 도구가 읽기를 거절합니다. 쓰기는 됩니다 — 에이전트가 나 대신 만들거나 고칠 수는 있지만, 안에 든 값을 다시 읽어 올 수는 없습니다.
display.file_mutation_verifier(기본 켜짐)가 켜져 있을 때, 답변 끝의 요약보다 파일 변경 확인 표시(file-mutation verifier footer)를 믿으라고 적습니다.
write_file·patch 에만 적용됩니다. 터미널 도구는 나와 같은 운영체제 사용자로 실행되므로, 셸 명령으로는 여전히 금지된 경로를 읽거나 덮어쓸 수 있습니다. 실수로 인한 피해를 줄이고 모델에게 분명한 멈춤 신호를 주는 것이지, 악의적이거나 탈취된 에이전트를 가두지는 못합니다. 확실히 가두려면 격리가 필요합니다.
~/.hermes/cron/jobs.json 을 직접 고치라고 하지 말고 cronjob_manage 도구나 hermes cron, /cron 을 쓰세요. 쓰기 보호가 막는 다른 Hermes 제어 파일도 마찬가지입니다.
보호 경로 전체 · 오류 문구 · ~/.ssh/config 예외 · HERMES_WRITE_SAFE_ROOT
항상 거절되는 경로 — HERMES_WRITE_SAFE_ROOT 를 설정하지 않아도, 그리고 쓰기 울타리 안이어도 적용됩니다.
| 부류 | 예 |
|---|---|
| OS 자격 증명 보관소 | ~/.ssh/(열쇠, authorized_keys), ~/.aws/, ~/.kube/, /etc/sudoers, ~/.netrc. 여기서 ~ 는 쓰기가 닿을 수 있는 모든 홈(OS 사용자의 실제 홈, 프로필 홈, ~root 같은 이름 있는 계정)을 뜻합니다. |
| Hermes 비밀 보관소 | .env, .anthropic_oauth.json, auth/google_oauth.json, Bitwarden·1Password 캐시(bws_cache.json, bws_cache.enc.json, op_cache.json), photon-sidecar.json, vault/, browser-profile/, mcp-tokens/, pairing/ — HERMES_HOME 아래(활성 프로필과 전역 루트). 제어 파일(auth.json, config.yaml, webhook_subscriptions.json)은 읽기만 거절되고 쓰기는 됩니다. |
| Windows NT/장치 이름 공간 경로 | \??\..., \\.\..., \\?\UNC\..., \\?\GLOBALROOT... — 모든 플랫폼에서 읽기·쓰기 모두 거절(Windows 에서는 경로 확인만으로 NTLM 해시가 샐 수 있음). read_file·search_files·@file:/@folder:·ACP 파일 다리도 거절. 평범한 \\?\C:\... 와 \\server\share 는 영향 없음. |
오류 문구: 울타리 위반은 Write denied: '…' is outside HERMES_WRITE_SAFE_ROOT (…), 자격 증명 경로는 Write denied: '…' is a protected system/credential file.
예외 — ~/.ssh/config 는 막지 않고 승인을 받습니다. 이 파일에는 개인 열쇠가 없고 고칠 일(호스트 별칭, ProxyJump, VS Code Remote-SSH 대상)이 흔해서, write_file/patch 는 once/session/always 승인 창으로 보냅니다. 명령을 실행하는 ProxyCommand/Match exec 가 들어갈 수 있어 조용히 쓰이는 일은 없고, 사람이 답할 길이 없는 호출은 거절됩니다. 개인 열쇠와 authorized_keys 등 ~/.ssh/ 의 나머지는 여전히 무조건 막힙니다.
HERMES_WRITE_SAFE_ROOT — 선택형 쓰기 울타리. 설정하면 write_file·patch 는 적어 둔 폴더 안쪽에만 쓸 수 있고, 바깥은 승인으로 넘어가지 않고 무조건 막힙니다.
export HERMES_WRITE_SAFE_ROOT=/path/to/project:/home/you/.hermes
- 공식 Docker 이미지에는 자동 설정(
/opt/data). 여러 폴더는 Unix 에서:, Windows 에서;로 구분합니다. ~/.hermes/.env에 가볍게 넣지 마세요. 프로젝트 폴더로만 잡으면 에이전트가~/.hermes/cron/jobs.json, 프로필 스킬 등 그 바깥의 Hermes 상태에 쓸 수 없습니다. 위 예처럼 Hermes 홈을 함께 적습니다.- 변수를 지우면 제한 없는 쓰기로 돌아갑니다(보호 경로 금지 목록은 그대로).
메신저에서는 누가 쓸 수 있나
게이트웨이(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시간 동안 무시합니다. |
페어링 세부 — 플랫폼별 설정 · 보안 사양 · 저장 위치 · Docker 주의 · 모두 허용을 config.yaml 에 둘 때
unauthorized_dm_behavior: pair
whatsapp:
unauthorized_dm_behavior: ignore
- 플랫폼 구역의 값이 전체 기본값보다 우선합니다. 위 예는 Telegram 등에서는 페어링을 유지하고 WhatsApp 에서는 조용히 무시합니다.
decline의 문구는unauthorized_dm_decline_message로 바꿉니다.- Email 은
platforms.email.unauthorized_dm_behavior: pair를 설정하지 않는 한 기본이ignore입니다 — 받은 편지함에는 관계없는 읽지 않은 메일이 있을 수 있기 때문입니다.
보안 사양(원문: OWASP 와 NIST SP 800-63-4 지침에 기반):
| 항목 | 내용 |
|---|---|
| 코드 형식 | 헷갈리지 않는 32글자 알파벳에서 뽑은 8글자(0/O/1/I 없음) |
| 무작위성 | 암호학적 난수(secrets.choice()) |
| 코드 수명 | 1시간 뒤 만료 |
| 요청 제한 | 사용자당 10분에 1번 |
| 대기 한도 | 플랫폼당 대기 중 코드 최대 3개 |
| 잠금 | 승인 시도 5번 실패 → 1시간 잠금 |
| 파일 보안 | 모든 페어링 데이터 파일에 chmod 0600 |
| 기록 | 코드는 표준 출력에 절대 기록하지 않음 |
저장 위치: ~/.hermes/pairing/ 아래 플랫폼별 JSON 파일 — {platform}-pending.json(대기 중인 요청), {platform}-approved.json(승인된 사용자), _rate_limits.json(요청 제한·잠금 기록).
hermes 사용자(uid 10000)로 실행하는데, docker exec 는 기본이 root 입니다. root 가 만든 승인 파일은 0600 root:root 로 쓰여 게이트웨이가 읽지 못하고, 승인은 아무 표시 없이 무시됩니다(#10270). 항상 -u hermes 를 붙입니다.
docker exec -u hermes hermes-agent hermes pairing approve telegram ABC12DEF
이미 root 로 실행했고 사용자가 여전히 허가되지 않는다면 컨테이너를 다시 시작합니다 — 시작 스크립트가 다음 시작 때 소유권을 고칩니다.
전체 “모두 허용”을 config.yaml 에 둘 때. gateway.allow_all_users: true(또는 맨 위 단계의 allow_all_users: true)로도 둘 수 있습니다. true 값은 게이트웨이 시작 때 GATEWAY_ALLOW_ALL_USERS 로 옮겨지고(false 로 되돌리면 문이 닫힘), 명시한 환경 변수가 있으면 그쪽이 우선하며, 출처가 config.yaml 이라는 경고가 기록됩니다. 다중 프로필 게이트웨이의 보조 프로필은 이 값을 자기 .env 에 둡니다.
격리 — 명령을 어디에서 실행하나
지금까지의 장치는 “위험한 일을 하기 전에 막거나 묻는” 방식이었습니다. 격리는 방향이 다릅니다. 에이전트의 명령을 내 컴퓨터와 떨어진 곳에서 실행해, 무슨 일이 벌어져도 내 컴퓨터에는 닿지 않게 합니다. 명령이 실제로 실행되는 곳을 Hermes 는 터미널 백엔드(에이전트의 명령이 실제로 실행되는 곳 — 내 컴퓨터 local · Docker · SSH 등)라고 부릅니다(고르는 법은 4장).
원문이 정리한 백엔드별 비교입니다.
| 백엔드 | 격리 | 위험 명령 검사 | 알맞은 곳 |
|---|---|---|---|
local | 없음 — 내 컴퓨터에서 실행 | 함 | 개발, 믿을 수 있는 사용자 |
ssh | 다른 컴퓨터 | 함 | 별도 서버에서 실행 |
docker | 컨테이너 | 건너뜀(컨테이너가 경계) | 실제 운영하는 게이트웨이 |
singularity (플러그인) | 컨테이너 | 건너뜀 | HPC(고성능 계산용 공용 서버) 환경 |
sprites (플러그인) | 클라우드 microVM | 건너뜀 | 상태가 유지되는 클라우드 샌드박스 |
modal | 클라우드 샌드박스 | 건너뜀 | 규모를 늘리기 쉬운 클라우드 격리 |
daytona | 클라우드 샌드박스 | 건너뜀 | 오래 유지되는 클라우드 작업 공간 |
vercel_sandbox | 클라우드 microVM | 건너뜀 | 스냅샷으로 상태를 남기는 클라우드 실행 |
docker 백엔드를 쓰면 Hermes 는 컨테이너마다 단단히 조인 설정을 적용합니다. 쉬운 말로 옮기면 이렇습니다.
특권을 내려놓음
컨테이너 안 프로그램의 시스템 특권을 전부 뺀 뒤 꼭 필요한 몇 개만 다시 주고, 실행 도중에 권한을 올리는 길을 막습니다.
프로세스·임시 폴더 제한
프로세스는 256개까지, /tmp 는 512MB, /var/tmp 는 256MB 로 묶습니다.
자원 한도
CPU·메모리·디스크 한도를 config.yaml 에서 정합니다. 기본값은 메모리 5GB, 디스크 50GB 입니다.
남길지 버릴지
container_persistent: true 면 세션이 바뀌어도 작업 공간이 남고, false 면 정리할 때 사라집니다.
docker, modal, daytona, vercel_sandbox 백엔드를 써서 에이전트의 명령을 내 컴퓨터(호스트)와 떼어 놓으라고 합니다. 그러면 위험 명령 승인이 아예 필요 없어집니다.terminal.docker_forward_env) 컨테이너 안의 코드가 그 값을 읽고 밖으로 빼낼 수도 있습니다. GITHUB_TOKEN 처럼 그 작업에만 쓰는 값만 넣습니다. ② 컨테이너 백엔드에서는 체크포인트가 찍히지 않습니다 — 파일 경로가 내 컴퓨터가 아니라 컨테이너에 속하기 때문입니다.
Docker 보안 옵션 원문 · 자원 한도 설정 · 파일 보존 방식
모든 컨테이너는 다음 옵션으로 실행됩니다(원문: tools/environments/docker.py 에 정의).
_BASE_SECURITY_ARGS = [
"--cap-drop", "ALL", # Linux capability 를 모두 버림
"--cap-add", "DAC_OVERRIDE", # root 가 bind mount 한 폴더에 쓸 수 있게
"--cap-add", "CHOWN", # 패키지 관리자에 파일 소유권 변경이 필요
"--cap-add", "FOWNER", # 패키지 관리자에 파일 소유권 변경이 필요
"--security-opt", "no-new-privileges", # 권한 상승 차단
"--pids-limit", "256", # 프로세스 수 제한
"--tmpfs", "/tmp:rw,nosuid,size=512m", # 크기 제한된 /tmp
"--tmpfs", "/var/tmp:rw,noexec,nosuid,size=256m", # 실행 불가 /var/tmp
]
SETUID/SETGID 는 컨테이너가 root 로 시작해 권한을 내려놓아야 할 때만 조건부로 추가됩니다. /run tmpfs 는 이미지별로 따로 마운트합니다(기본 noexec, s6-overlay 이미지에만 exec 허용).
terminal:
backend: docker
docker_image: "nousresearch/hermes-sandbox:desktop"
docker_forward_env: [] # 명시적 허용 목록만. 비워 두면 비밀 값이 컨테이너에 들어가지 않음
container_cpu: 1 # CPU 코어 수
container_memory: 5120 # MB (기본 5GB)
container_disk: 51200 # MB (기본 50GB, XFS 위의 overlay2 필요)
container_persistent: true # 세션이 바뀌어도 파일 시스템 유지
- 유지 모드(
container_persistent: true):~/.hermes/sandboxes/docker/<task_id>/에서/workspace와/root를 bind mount 합니다. - 일회용 모드(
container_persistent: false): 작업 공간에 tmpfs 를 써서, 정리할 때 모두 사라집니다. - 위험 명령 검사를 건너뛰는 백엔드:
docker,modal,daytona,vercel_sandbox, 그리고singularity·sprites같은 컨테이너 플러그인 백엔드.
환경 변수 전달(Environment Variable Passthrough) — 스킬 · 자격 증명 파일 · 빌려 쓰는 로그인
execute_code 와 terminal 은 AI 가 만든 코드가 자격 증명을 빼돌리지 못하도록 자식 프로세스에서 민감한 환경 변수를 걷어 냅니다. 정당하게 필요한 변수만 통과시키는 길이 둘 있습니다.
| 방식 | 어떻게 |
|---|---|
| 스킬 범위 전달(자동) | 스킬(특정 일을 하는 방법을 적은 설명서)이 읽힐 때(skill_view 또는 /skill) 머리말의 required_environment_variables 에 선언된 변수 가운데 실제로 설정된 것만 자동 등록. execute_code, terminal(local), Docker·Modal 로 전달됩니다(v0.5.1 부터 Docker 의 forward_env 와 합쳐져 docker_forward_env 에 따로 적지 않아도 됨). |
| 설정 기반 전달(수동) | 어떤 스킬도 선언하지 않은 변수는 config.yaml 의 terminal.env_passthrough 목록에 적습니다. |
# 스킬의 SKILL.md 머리말
required_environment_variables:
- name: TENOR_API_KEY
prompt: Tenor API key
# config.yaml
terminal:
env_passthrough:
- MY_CUSTOM_KEY
credential_files:
- google_token.json
- 두 목록은
terminal,execute_code,no_agent예약 작업 스크립트에 똑같이 적용됩니다. 한 프로세스가 여러 프로필을 맡을 때는 프로필마다 자기.env의 값이 전달되고, 프로세스를 띄운 프로필의 자격 증명은 다른 프로필의 자식에게 가지 않습니다. - 자격 증명 파일 전달. 파일이 필요한 스킬(예: Google Workspace 의
google_token.json)은 머리말에required_credential_files를 선언하거나, 위처럼terminal.credential_files에 직접 적습니다(경로는~/.hermes/기준, 컨테이너 안에서는/root/.hermes/). Docker 는 읽기 전용 bind mount, Modal 은 만들 때 마운트 + 명령마다 동기화, local 은 할 일 없음. - 보안상 고려. 전달은 명시적으로 선언한 변수에만 영향을 줍니다. 없는 변수는 등록되지 않고, Skills Guard 가 설치 전에 수상한 환경 변수 접근을 검사합니다(6장). 제공자 API 키·게이트웨이 토큰 같은 Hermes 기반 비밀은
env_passthrough에 넣을 수 없습니다(선언할 때 거절).
| 샌드박스 | 기본 필터 | 전달 설정의 효과 |
|---|---|---|
execute_code | 이름에 KEY, TOKEN, SECRET, PASSWORD, CREDENTIAL, PASSWD, AUTH 가 든 변수를 막고 안전한 접두어만 통과 | 두 검사를 모두 통과 |
terminal (local) | Hermes 기반 변수(제공자 키, 게이트웨이 토큰, 도구 API 키)를 막음 | 금지 목록을 통과 |
terminal (Docker) | 호스트 환경 변수 없음 | 전달 변수 + docker_forward_env 가 -e 로 전달 |
terminal (SSH) | 호스트 환경 변수 없음 | SendEnv 로 전달(원격 sshd_config 에 AcceptEnv 필요) |
terminal (Modal) | 호스트 환경 변수·파일 없음 | 자격 증명 파일 마운트, 변수는 동기화로 |
| MCP | 안전한 시스템 변수와 명시한 env 외 모두 막음 | 영향 없음(MCP 의 env 설정 사용) |
빌려 쓰는 CLI 로그인(Codex CLI, Claude Code). Hermes 에 openai-codex·anthropic 용 자체 로그인이 없으면 Codex CLI 의 ~/.codex/auth.json 과 Claude Code 의 ~/.claude/.credentials.json(또는 Keychain)을 빌려 쓰고 대신 갱신합니다. 둘 다 한 번만 쓰는 갱신 토큰이라 두 프로그램이 함께 쥐면 먼저 갱신한 쪽이 다른 쪽을 무효로 만듭니다(“터미널에서 로그인했는데 Hermes 가 계속 실패한다”). 그 CLI 들을 함께 쓴다면 hermes auth add anthropic / hermes auth add openai-codex 로 자체 로그인을 주고 auth.adopt_external_logins: false(기본 true)로 끕니다.
Buzz 플랫폼 예외. Buzz 메시징 플랫폼의 BUZZ_* 변수는 세션이 실제로 Buzz 에이전트로 동작할 때만 터미널 자식 프로세스에 전달됩니다. 같은 컴퓨터의 Telegram/CLI/예약 작업 세션에서는 걷어 내며, execute_code·Docker/Modal 자식에는 적용되지 않습니다.
알아서 도는 방어 — 웹 주소 · 맥락 파일 · MCP
내가 답하지 않아도 뒤에서 걸러 주는 장치들입니다. 무언가를 막았을 때만 오류나 경고로 모습을 드러냅니다.
| 장치 | 무엇을 막나 | 내가 보게 되는 것 |
|---|---|---|
| MCP 비밀 값 거르기 | MCP 서버 프로그램에는 PATH·HOME 같은 안전한 기본값과, 그 서버 설정에 내가 직접 적은 값만 넘깁니다. 그 밖의 API 키·토큰은 걷어 냅니다. | 보통은 아무것도 없음 |
| 오류 속 비밀 값 가리기 | MCP 도구의 오류 글에 열쇠처럼 보이는 글자가 섞여 있으면 모델에게 넘기기 전에 가립니다. | [REDACTED] |
| 웹사이트 차단 목록 | 내가 적어 둔 주소(사내 서비스, 관리자 화면 등)에 웹·브라우저 도구가 접근하지 못하게 합니다. 직접 켜야 합니다. | “정책으로 막힌 주소”라는 오류 |
| 내부 주소 차단(SSRF 방어) | 웹 주소를 여는 도구들이, 내 컴퓨터 자신이나 집·회사 내부망, 클라우드의 비밀 정보 주소로 요청을 보내지 못하게 합니다. 항상 켜져 있습니다. | 내부 주소라서 막혔다는 오류 |
| 맥락 파일 검사 | 맥락 파일(AGENTS.md·SOUL.md 처럼 대화마다 자동으로 읽히는 파일)에 “이전 지시를 무시하라” 같은 프롬프트 주입(AI 를 속이려고 글 속에 몰래 넣은 지시문)이 있는지 살핍니다. | 아래의 BLOCKED 경고 |
[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]뜻: “막음: AGENTS.md 에 프롬프트 주입으로 보이는 내용이 있어 읽어 들이지 않았습니다.” 맥락 파일 자체는 5장에서 다룹니다.
MCP 자격 증명 처리(MCP Credential Handling) · 웹사이트 차단 목록 · 맥락 파일 검사 세부
안전한 환경 변수. 호스트에서 MCP stdio 하위 프로세스로 넘어가는 것은 PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR 과 XDG_* 뿐입니다. 그 밖의 환경 변수는 모두 걷어 내고, MCP 서버의 env 설정에 명시한 변수만 전달합니다(MCP 서버 추가는 4장, 보안은 4장 MCP 보안).
mcp_servers:
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..." # 이것만 전달됨
자격 증명 가리기. MCP 도구의 오류 메시지에서 GitHub PAT(ghp_...), OpenAI 식 키(sk-...), Bearer 토큰, token=·key=·API_KEY=·password=·secret= 매개변수가 [REDACTED] 로 바뀝니다.
웹사이트 접근 정책. web_search, web_extract, browser_exec 와 주소를 다루는 모든 도구에 적용됩니다. 자세한 것은 공식 문서 설정 가이드의 Website Blocklist 참고.
# ~/.hermes/config.yaml
security:
website_blocklist:
enabled: true
domains:
- "*.internal.company.com"
- "admin.example.com"
shared_files:
- "/etc/hermes/blocked-sites.txt"
맥락 파일 주입 방어. 맥락 파일(AGENTS.md, .cursorrules, SOUL.md)은 시스템 프롬프트에 넣기 전에 검사합니다. 찾는 것: 이전 지시를 무시하라는 지시, 수상한 낱말이 든 숨은 HTML 주석, 비밀 값(.env, credentials, .netrc)을 읽으려는 시도, curl 로 자격 증명을 빼내려는 시도, 보이지 않는 유니코드 문자. 이 패턴들은 어림 규칙이지 뜻을 이해하는 탐지가 아닙니다.
HERMES_HOME의 내SOUL.md는 내가 쓴 파일이므로 검사에 걸려도 막지 않습니다. 경고를 기록하고 평소처럼 읽으며/context에⚠ SOUL.md … loaded — matched prompt-injection pattern(s); review the file로 표시됩니다. 내가 쓰지 않은 글이 걸렸다면 다른 무언가가 파일을 고쳤다는 신호입니다.- 프로필 배포판(
hermes profile install <git-url>,hermes profile update)이 실어 온SOUL.md에는 이 예외가 없습니다 — 검사에 걸리면 막힙니다.
내부 주소 차단(SSRF Protection) 세부 — 막는 주소 · allow_private_urls · fake-ip
주소를 다루는 모든 도구(웹 검색, 웹 추출, 비전, 브라우저)는 가져오기 전에 주소를 검증합니다. 리디렉션은 단계마다 다시 검증하고, DNS 실패는 “막힘”으로 처리합니다. 생성 제공자가 돌려준 이미지·영상 주소처럼 원격 상대에게서 온 주소에도 같은 검사가 적용됩니다.
| 막는 부류 | 주소 |
|---|---|
| 사설망(RFC 1918) | 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 |
| 루프백(자기 자신) | 127.0.0.0/8, ::1 |
| 링크 로컬 | 169.254.0.0/16(클라우드 메타데이터 169.254.169.254 포함) |
| CGNAT(RFC 6598) | 100.64.0.0/10(Tailscale, WireGuard VPN) |
| 클라우드 메타데이터 이름 | metadata.google.internal, metadata.goog |
| 그 밖 | 예약·멀티캐스트·미지정 주소 |
security:
allow_private_urls: true # 기본값: false
fake_ip_ranges: # 기본값: 비어 있음
- 198.18.0.0/15
allow_private_urls— 집 내부망의 로컬 모델 서버나 사내 위키처럼 사설 주소가 정말 필요할 때 켭니다. 웹 도구·브라우저·비전·게이트웨이 미디어 내려받기가 사설 주소를 거절하지 않게 됩니다. 클라우드 메타데이터 주소와, 비슷하게 생긴 유니코드 도메인을 막는 가드는 켜도 그대로입니다. 공개된 게이트웨이에서는 꺼 두라고 원문은 적습니다.- 꺼져 있을 때의 범위 —
web_extract, 비전·미디어 내려받기, 클라우드/원격 브라우저는 사설 주소를 거절합니다. 반면 local 터미널 백엔드의 로컬 Chromium 과terminal(curl http://localhost)은 열립니다. 클라우드 브라우저 제공자를 쓸 때 사설 주소는 기본적으로 Hermes 호스트의 로컬 Chromium 에서 열리며(browser.auto_local_for_private_urls: true), 막으려면false로 둡니다. 검사는 에이전트가 적은 주소 글자만 읽으므로(실행 중 조립된 주소·이후 리디렉션은 못 봄) 클라우드 VM 에서는 메타데이터 서비스를 네트워크에서도 막으라고 권합니다. fake_ip_ranges— fake-ip 모드의 TUN 프록시(Mihomo/Clash, Surge enhanced mode)는 DNS 에 자기 대역(기본198.18.0.0/15)의 주소로 답해서, 그대로면 모든 바깥 요청이URL targets a private or internal network address로 거절됩니다. 그 대역을 선언하면 통과합니다.allow_private_urls보다 좁아서 선언한 대역만 면제되고, 사설망·루프백 등과 겹치는 항목은 경고와 함께 무시됩니다.
여럿이 쓰는 봇이라면 — 운영 점검표
게이트웨이를 계속 켜 두고 여러 사람이 메신저로 쓰는 실제 운영 환경(production — 시험이 아니라 실제로 계속 돌리는 환경)에서는 원문이 다음 열 가지를 점검하라고 합니다.
| # | 할 일 | 쉬운 말로 |
|---|---|---|
| 1 | 허용 목록을 명시 | GATEWAY_ALLOW_ALL_USERS=true 를 절대 쓰지 않습니다. |
| 2 | 컨테이너 백엔드 사용 | config.yaml 에 terminal.backend: docker. |
| 3 | 자원 한도 조이기 | CPU·메모리·디스크 한도를 알맞게 정합니다. |
| 4 | 비밀 값을 안전하게 보관 | API 키는 ~/.hermes/.env 에 두고 파일 권한을 제대로 겁니다. |
| 5 | DM 페어링 켜기 | 가능하면 ID 를 적어 두는 대신 페어링 코드를 씁니다. |
| 6 | 허용 명령 목록 점검 | config.yaml 의 command_allowlist 를 주기적으로 살펴봅니다. |
| 7 | terminal.cwd 지정 | 에이전트가 민감한 폴더에서 일하지 않게 합니다. |
| 8 | root 가 아닌 사용자로 실행 | 게이트웨이를 최고 관리자(root)로 돌리지 않습니다. |
| 9 | 기록 살피기 | ~/.hermes/logs/ 에서 허가받지 않은 접근 시도를 확인합니다. |
| 10 | 최신으로 유지 | hermes update 로 보안 수정을 받습니다. |
비밀 값 파일은 나만 읽고 쓸 수 있게 권한을 겁니다. 서비스마다 열쇠를 따로 쓰고, .env 파일을 버전 관리(git 등)에 올리지 않습니다.
chmod 600 ~/.hermes/.env
가장 단단하게 하려면 게이트웨이를 별도의 컴퓨터나 가상 머신에서 돌리고, 에이전트의 명령은 SSH(다른 컴퓨터에 안전하게 접속해 명령을 실행하는 방법)로 또 다른 컴퓨터에서 실행하게 합니다. 메신저 연결과 명령 실행이 서로 다른 곳에 놓입니다.
config.yaml 이 아니라 .env 에 둡니다 — 설정을 공유하거나 프로필을 내보낼 때 함께 딸려 나가지 않게 하려는 것입니다.네트워크 격리 설정 예 (SSH 백엔드)
# ~/.hermes/config.yaml
terminal:
backend: ssh
# ~/.hermes/.env
TERMINAL_SSH_HOST=agent-worker.local
TERMINAL_SSH_USER=hermes
TERMINAL_SSH_KEY=~/.ssh/hermes_agent_key
SSH 접속 정보는 .env 에 두므로(config.yaml 이 아님) 버전 관리에 올라가거나 프로필 내보내기에 딸려 가지 않습니다. 이렇게 하면 게이트웨이의 메신저 연결과 에이전트의 명령 실행이 분리됩니다.
TLS 인증서 신뢰(TLS certificate trust) — 회사 프록시를 쓸 때
- Hermes 는
truststore로 운영체제의 인증서 검증기를 씁니다(Windows 인증서 저장소, macOS 시스템 신뢰 서비스, Linux 의 OpenSSL 시스템 경로). 초기화에 실패하면 기록을 남기고 OpenSSL 기본값으로 물러납니다. - 회사 TLS 프록시의 루트 인증서는 조직의 운영체제 신뢰 절차대로 설치합니다. 제공자 연결은 더 이상
HERMES_CA_BUNDLE이나 예전 CA 환경 변수로 신뢰를 고르지 않습니다. - 시작할 때 CA 변수를 검증하던 검사는 사라졌습니다(
SSLConfigurationError없음,HERMES_SKIP_SSL_GUARD효과 없음).HERMES_CA_BUNDLE은 Nous Portal 로그인(hermes login,--ca-bundle)에서만 쓰입니다.SSL_CERT_FILE/REQUESTS_CA_BUNDLE/CURL_CA_BUNDLE은 일부 도구(pip, uv, curl, Node 포함)가 여전히 읽으므로, 낡은 경로는 그 호출에서 실패합니다 — 고치거나 지웁니다. - 사용자 정의 제공자는
ssl_ca_cert로 자기 끝점의 인증서 묶음을 선언할 수 있습니다(파일이 없으면 경고 후 플랫폼 신뢰로).ssl_verify: false는 검증을 끄며 안전하지 않습니다 — 회사 루트 인증서가 없다는 문제의 영구 해결책으로 쓰지 마세요.
놓아두기만 하면 신뢰되는 확장 지점(Trusted-by-placement) — 게이트웨이 이벤트 훅
Hermes 가 실행할 수 있는 제3자 코드는 대부분 명시적인 허용을 거칩니다(플러그인은 plugins.enabled, 셸 훅은 첫 사용 승인, MCP 서버는 설정에 나열). 한 곳만 일부러 다릅니다.
| 확장 지점 | 읽어 오는 곳 | 읽는 때 | 동의 방식 |
|---|---|---|---|
| 게이트웨이 이벤트 훅 | <프로필 홈>/hooks/<name>/ (HOOK.yaml + handler.py) | 게이트웨이 시작 때, 맡은 프로필마다 | 폴더를 놓아두는 것 자체. 확인 창이 없고 HERMES_SAFE_MODE 로도 건너뛰지 않음 |
게이트웨이는 올바른 훅 폴더를 모두 자기 권한으로 들여옵니다. 원문은 이것이 실수가 아니라 문서화된 약속이라고 적습니다 — 프로필 홈에 쓸 수 있는 사람은 이미 config.yaml 로 코드를 실행할 수 있기 때문입니다. ~/.hermes/hooks/ 는 config.yaml 처럼 다루세요. handler.py 는 놓기 전에 읽어 보고, 점검할 때 ls ~/.hermes/hooks/ 도 함께 봅니다(이 폴더는 보호 경로 금지 목록에 없습니다).
공급망 경고 검사(Supply-chain advisory checking)와 선택 의존성의 필요 시 설치
Hermes 에는, 지금 쓰는 Python 환경의 패키지 가운데 “오염된 것으로 알려진 버전” 목록에 맞는 것을 알려 주는 검사기가 들어 있습니다(예: 2026년 5월의 mistralai 2.4.6 오염). 맞는 것이 있으면 CLI 시작 배너에 한 줄 경고가 뜨고, hermes doctor 가 버전 정보와 2~4단계 조치 방법을 보여 주며, 게이트웨이는 gateway.log 에 기록하고 첫 대화 메시지에 짧은 안내를 붙입니다.
hermes doctor --ack <advisory-id> # 읽고 조치한 경고를 영구히 닫기
hermes config set security.allow_lazy_installs false # 필요 시 설치 끄기
- 확인 기록은
config.security.acked_advisories에 남아 재시작 뒤에도 유지됩니다. 오래된 경고는 일부러 목록에서 지우지 않습니다. - 필요 시 설치(Lazy install of optional dependencies). 선택적인 Python 기능(extra)이 없을 때 Hermes 의 패키지 관리자(PM)가 그때 설치합니다. 선언된 extra 이름만 받고 임의의 pip 명령은 받지 않으며, 관리되는 도구는 버전과 SHA-256 해시로 검증하고, 새 환경을 준비·검증한 뒤에야 바꿉니다(실패하면 이전 환경 유지, 설치된 플러그인을 조용히 지우지 않음). 바꾼 환경을 쓰려면 Hermes 를 다시 시작해야 합니다.
- 위 설정으로 끄면 이미 설치된 것은 계속 쓸 수 있고, 명시적인 설치 명령은 별개입니다. 공식 Docker 이미지도 필요 시 설치를 끕니다. 빠진 의존성은
hermes tools와hermes doctor로 확인하고, 서명된 묶음이나 시스템 Python 에 대고 pip 를 실행하지 마세요. 자세한 것은 공식 문서 Package management 쪽 참고(이 가이드는 다루지 않음).
체크포인트 — 바꾸기 전에 찍어 두는 사진
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 가 일한 모든 프로젝트가 이 보관소 하나를 함께 써서, 같은 내용은 한 번만 저장됩니다.
체크포인트 설정 키와 동작 원리
~/.hermes/config.yaml 의 checkpoints: 아래에 둡니다.
| 키 | 기본값 | 뜻 |
|---|---|---|
enabled | false | 주 스위치. false 면 아무 일도 하지 않고 git 작업을 시도하지도 않습니다. |
max_snapshots | 20 | 프로젝트당 보관하는 체크포인트 수의 상한. |
max_total_size_mb | 500 | 보관소 전체 크기의 상한. 넘으면 가장 오래된 것부터 버립니다. |
max_file_size_mb | 10 | 이보다 큰 파일은 사진에서 뺍니다. |
auto_prune | true | 자동 정리. 뒤에서(CLI 는 실행 직후, 게이트웨이는 정기 관리 주기에) 마지막 사용이 retention_days 보다 오래된 프로젝트 항목을 지웁니다. 프롬프트나 게이트웨이 시작을 막지 않습니다. false 면 직접 hermes checkpoints prune 을 돌릴 때까지 보관소가 커집니다. |
retention_days | 7 | 자동 정리가 남겨 두는 날 수. |
min_interval_hours | 24 | 자동 정리 사이의 최소 간격(시간). |
- 자동 정리는 “고아” 항목(작업 폴더를 찾을 수 없는 것)은 지우지 않습니다 — 지운 프로젝트인지 아직 연결되지 않은 외장 디스크·네트워크 공유인지 알 수 없기 때문입니다. 고아 정리는 확인 창이 뜨는
hermes checkpoints prune으로만 합니다. - 모두 끄려면
enabled: false와auto_prune: false를 함께 둡니다. - 동작 원리(How Checkpoints Work). 내부의 Checkpoint Manager 가 도구들이 파일을 바꾸려는 순간을 감지하고, 대화 턴마다 한 번(폴더별로) 알맞은 프로젝트 뿌리 폴더를 정해 공유 “그림자 git 저장소”의 프로젝트별 ref(
refs/hermes/<project-hash>)에 커밋합니다. 이 ref 들이/rollback으로 살펴보는 체크포인트 이력입니다.
/rollback 으로 되돌리기
되돌리기는 대화 입력 칸에 /rollback 을 넣어서 합니다. 뒤에 무엇을 붙이느냐에 따라 하는 일이 달라집니다.
| 명령 | 하는 일 |
|---|---|
/rollback | 체크포인트 목록을 변경 통계와 함께 보여 줍니다 |
/rollback <N> | N번 체크포인트로 복원합니다. 내가 손으로 고친 것은 남겨 둡니다(마지막 대화 턴도 취소) |
/rollback <N> --all | 전체 복원 — 내가 손으로 고친 것까지 덮어씁니다 |
/rollback diff <N> | N번 체크포인트와 지금의 차이를 미리 봅니다 |
/rollback <N> <file> | N번 체크포인트에서 파일 하나만 복원합니다 |
먼저 /rollback 만 넣어 목록을 봅니다.
📸 Checkpoints for /path/to/project:
1. 4270a8c 2026-03-16 04:36 before patch (1 file, +1/-0)
2. eaf4c1f 2026-03-16 04:35 before write_file
3. b3f9d2e 2026-03-16 04:34 before terminal: sed -i s/old/new/ config.py (1 file, +1/-1)
/rollback <N> restore to checkpoint N (keeps your hand-edits)
/rollback <N> --all full restore, overwriting your hand-edits too
/rollback diff <N> preview changes since checkpoint N
/rollback <N> <file> restore a single file from checkpoint N각 줄은 번호(N) · 고유 이름(해시 — 번호 대신 쓸 수 있음) · 찍힌 시각 · 무엇을 하기 직전인지(before patch = patch 직전) · 변경 통계(1 file, +1/-0 = 파일 1개, 1줄 추가·0줄 삭제) 순입니다. 예시에서는 가장 최근 것이 1번입니다.
번호를 골라 /rollback 1 처럼 넣으면 Hermes 는 뒤에서 네 가지 일을 차례로 합니다.
1 — 고른 체크포인트가 있는지 확인합니다
보관소에 그 사진이 실제로 있는지 먼저 확인합니다.
2 — 지금 상태를 한 장 더 찍어 둡니다
되돌리기 직전의 모습도 사진으로 남깁니다. 그래서 되돌린 것이 마음에 들지 않으면 “되돌리기를 되돌릴” 수 있습니다.
3 — 작업 폴더의 파일을 복원합니다
기록해 둔 파일들을 그때 내용으로 되돌립니다. 내가 손으로 고친 파일은 남겨 둡니다(아래 설명).
4 — 마지막 대화 턴도 취소합니다
파일만 옛 모습이 되고 대화는 그대로면 에이전트가 “이미 고쳤다”고 착각합니다. 그래서 에이전트가 기억하는 대화도 복원된 파일 상태와 맞도록 마지막 턴을 함께 취소합니다.
내가 손으로 고친 것은 남겨 둡니다
/rollback <N> 은 Hermes 가 바꾼 파일만 복원합니다. Hermes 는 자기가 성공적으로 쓴 파일마다 내용의 지문(hash)을 장부에 적어 둡니다. 복원할 때 어떤 파일의 지금 내용이 그 지문과 다르면 — 내가 나중에 고쳤거나 Hermes 가 애초에 손대지 않은 파일이면 — 덮어쓰지 않고 건너뛴 뒤 이름을 알려 줍니다.
--all 은 내가 고친 것까지 모두 그때로 돌립니다.✅ Restored to checkpoint a1b2c3d4: before write_file
↷ Kept your hand-edits: src/config.py, notes.md
Use /rollback <N> --all to restore those too.뜻: “체크포인트 a1b2c3d4(write_file 직전)로 복원했습니다. 손으로 고친 파일은 남겼습니다: src/config.py, notes.md. 이것들도 되돌리려면 /rollback <N> --all 을 쓰세요.”
처음 되돌릴 때는 /rollback 으로 목록을 보고 → /rollback diff N 으로 무엇이 달라질지 확인한 뒤(다음 소절) → /rollback N 순서가 안전합니다. 실제로 따라 해 보려면 활용편 실습 5를 보세요.
미리 보기 · 파일 하나만 · /undo 와의 차이
되돌리기에는 곁가지 기능이 둘 있고, 이름이 비슷한 /undo 와는 하는 일이 다릅니다.
| 명령 | 파일 | 대화 | 언제 쓰나 |
|---|---|---|---|
/rollback diff N | 바꾸지 않음(보기만) | 그대로 | 되돌리기 전에 무엇이 달라질지 확인 |
/rollback N <file> | 그 파일 하나만 복원 | — | 파일 하나만 망가졌을 때 |
/rollback N | Hermes 가 바꾼 파일을 복원 | 마지막 턴 취소 | 작업 전체를 그때로 돌릴 때 |
/undo | 건드리지 않음 | 대화만 되감기 | 방금 주고받은 말만 없던 일로 할 때 |
되돌리기 전에 미리 보기
/rollback diff 1
1번 체크포인트 이후 무엇이 달라졌는지 보여 줍니다. 먼저 어떤 파일이 얼마나 바뀌었는지 요약(git diff stat)이 나오고, 이어서 실제로 달라진 줄(diff(두 상태의 차이를 줄 단위로 보여 주는 것))이 나옵니다. 원문은 되돌리기 전에 이것으로 알맞은 체크포인트를 고르라고 권합니다.
파일 하나만 되돌리기
/rollback 1 src/broken_file.py
폴더의 나머지는 그대로 두고, 1번 체크포인트에서 그 파일 하나만 가져옵니다.
/undo 는 대화만 되감습니다
/undo 는 대화만 되감고 파일에는 손대지 않습니다. 체크포인트가 켜져 있고 되감은 턴에서 프로젝트 파일이 바뀌었다면, /undo 는 그 파일들의 이름과 함께 /rollback 을 안내하는 한 줄을 덧붙입니다.
/undo
↶ Files changed in the undone turns: app.js, notes.md. Run /rollback to see checkpoints and restore them.뜻: “되감은 턴에서 바뀐 파일: app.js, notes.md. /rollback 을 실행해 체크포인트를 보고 복원하세요.” 대화를 되감았다고 파일까지 돌아간 것은 아니라는 알림입니다.
/undo 안내 줄과 “마지막 턴 취소”의 세부 조건
- 안내 줄은 체크포인트를 지정하지 않습니다.
/rollback으로 목록을 보고 번호나 해시로 고릅니다. - 파일 목록은 최선을 다한 추정입니다. 되감은 턴이 시작될 즈음 찍힌 체크포인트와 프로젝트를 비교한 것이고, “무엇이 바뀌었는지”만 말할 뿐 “복원하면 무엇이 돌아오는지”를 말하지는 않습니다.
- 이 줄 자체는 아무것도 쓰지 않습니다. 체크포인트가 꺼져 있거나 되감은 턴이 체크포인트를 찍지 않았다면
/undo는 예전과 똑같이 출력합니다. - 편집기(ACP)와 게이트웨이 대화 클라이언트는
/rollback을 실행하지 않으므로 이 줄을 출력하지 않습니다. - 폴더 전체
/rollback은 남아 있는 가장 최근 대화 턴도 취소하지만, 그 턴이 그 체크포인트를 만들었거나 그 뒤에 온 경우에만 그렇습니다./undo뒤에 남겨 둔 턴들은 체크포인트 전에 끝났으므로 그대로 남습니다. 체크포인트는 정확한 시각을 기록합니다. 예전 버전이 만든 체크포인트는 초 단위까지만 알 수 있어서, 같은 초에 있던 남겨 둔 턴도 유지됩니다.
체크포인트가 찍히지 않는 경우와 보관 한도
체크포인트는 “켜 두면 무엇이든 되돌려 주는” 장치가 아닙니다. 속도와 디스크를 지키려고 Hermes 가 일부러 찍지 않거나 빼는 경우가 있습니다.
| 경우 | 어떻게 되나 |
|---|---|
| 컴퓨터에 git 이 없음 | 체크포인트가 조용히 꺼집니다. |
| 폴더가 너무 넓음 | 컴퓨터 맨 위 폴더(/), 내 홈 폴더, 홈 폴더를 품은 폴더(/home, /Users 등)는 건너뜁니다. 프로젝트용 폴더 안에서 일을 시키세요. |
| 파일이 5만 개를 넘는 폴더 | 건너뜁니다. node_modules/·.venv/·build/ 같은 제외 폴더는 세지 않습니다. |
| 파일 하나가 10MB 를 넘음 | 그 파일만 사진에서 뺍니다(데이터 묶음, 모델 파일, 생성된 미디어 등). |
| 지난 사진 이후 달라진 것이 없음 | 찍지 않습니다. |
| 프로젝트당 사진 수 | 기본으로 20장까지만 보관합니다. |
| 보관소 전체가 500MB 를 넘음 | 프로젝트마다 돌아가며 가장 오래된 것부터 버립니다. 프로젝트마다 최소 한 장은 남깁니다. |
| 7일 넘게 쓰지 않은 프로젝트 | 자동 정리가 그 프로젝트의 사진을 지웁니다. |
| 사진 찍기에 실패 | 도구 실행을 막지 않습니다. 작업은 계속되지만 그 순간의 사진은 없습니다. |
docker, modal, daytona, vercel_sandbox, singularity 같은 컨테이너 플러그인)에서는 파일 경로가 내 컴퓨터가 아니라 격리된 공간에 속해서, Hermes 는 체크포인트를 찍지 않습니다. /rollback 은 이미 있던 내 컴퓨터 쪽 목록은 보여 주지만 미리 보기(diff)와 복원은 이유를 설명하며 거절합니다. local 과 ssh 백엔드는 영향이 없습니다.
[nested git repos not captured: …] 라고 표시되고 전체 되돌리기는 거절됩니다. 안쪽 저장소는 따로 백업하거나 그 폴더에서 직접 체크포인트를 찍으라고 원문은 권합니다.
원문이 권하는 사용 습관입니다.
필요할 때만 켜기
hermes chat --checkpoints 로 그 세션만, 또는 프로필별로 enabled: true.
되돌리기 전에 diff
/rollback diff 로 무엇이 바뀔지 보고 알맞은 체크포인트를 고릅니다.
에이전트가 한 일만 되돌릴 때
git reset 대신 /rollback 을 씁니다.
가끔 보관소 확인
자주 쓴다면 hermes checkpoints status 로 어떤 프로젝트가 얼마나 차지하는지 봅니다.
Git worktree 와 함께
세션마다 별도의 worktree/브랜치에서 일하게 하고, 체크포인트를 한 겹 더 얹습니다.
터미널에서 보관소 살피기 — hermes checkpoints 명령
| 명령 | 하는 일 |
|---|---|
hermes checkpoints | 전체 크기, 프로젝트 수, 프로젝트별 내역 표시 |
hermes checkpoints status | 위와 같음 |
hermes checkpoints list | status 의 다른 이름 |
hermes checkpoints prune | 강제 정리 — 고아·오래된 항목 삭제, GC, 크기 상한 적용 |
hermes checkpoints clear | 체크포인트 보관 폴더 전체 삭제(먼저 물음) |
hermes checkpoints clear-legacy | v1 에서 옮겨 온 legacy-* 보관분만 삭제 |
Checkpoint base: /home/you/.hermes/checkpoints
Total size: 142.3 MB
store/ 138.1 MB
legacy-* 4.2 MB
Projects: 12
WORKDIR COMMITS LAST TOUCH STATE
/home/you/code/hermes-agent 20 2h ago live
/home/you/code/experiments/rl-runner 8 1d ago live
/home/you/code/old-prototype 3 9d ago orphan
...
Legacy archives (1):
legacy-20260506-050616 4.2 MB
Clear with: hermes checkpoints clear-legacy
STATE 의 live 는 작업 폴더가 있는 프로젝트, orphan 은 작업 폴더를 찾을 수 없는 프로젝트입니다. 24시간 간격 표시를 무시하고 강제로 전체 정리를 하려면:
hermes checkpoints prune --retention-days 3 --max-size-mb 200
보관 위치 · v1 에서 옮겨 오기 · 중첩 저장소와 정리 동작의 세부
~/.hermes/checkpoints/
├── store/ # 하나뿐인 공유 bare git 저장소
│ ├── HEAD, objects/ # git 내부 (프로젝트들이 함께 씀)
│ ├── refs/hermes/<hash> # 프로젝트별 가지 끝
│ ├── indexes/<hash> # 프로젝트별 git index
│ ├── projects/<hash>.json # 작업 폴더 + created_at + last_touch
│ ├── .gc-pending # 지난 gc 이후 ref 가 다시 쓰였다는 표시
│ └── info/exclude
├── .last_prune # 자동 정리 간격 표시
└── legacy-<ts>/ # v2 이전의 프로젝트별 그림자 저장소 보관분
<hash>는 작업 폴더의 절대 경로에서 만들어집니다. 직접 만지지 말고hermes checkpoints status/prune/clear를 씁니다. 옆의.checkpoints.lock은 Hermes 가 도는 동안 지우지 마세요.- v1 에서 옮겨 오기. v2 이전에는 작업 폴더마다 그림자 저장소가 따로 있어 보관소가 끝없이 커졌습니다. v2 를 처음 실행하면 예전 저장소들이
legacy-<timestamp>/로 옮겨집니다. 예전 이력은 git 으로 직접 들여다볼 수 있고, 필요 없으면hermes checkpoints clear-legacy로 지웁니다(retention_days뒤 자동 정리도 됨). - 중첩 git 저장소. 바깥 폴더의 체크포인트는 안쪽 저장소를 파일 사본이 아니라 gitlink(커밋 참조)로 담습니다. 고른 체크포인트에 gitlink 가 있으면 전체 되돌리기(
--all포함)와, 안쪽 저장소나 그 아래 파일을 고르는 복원은 거절됩니다. 관계없는 파일은 복원할 수 있습니다(예:/rollback 1 notes.txt). - 컨테이너 백엔드 보충. 에이전트가 쓴 파일의 장부도 기록하지 않습니다. 거절은 CLI·메신저·TUI·Desktop 에서 같고
/diff session도 같은 이유로 답합니다. 마운트한 폴더의 경로 맞추기는terminal.docker_mount_cwd_to_workspace참고. - 정리 동작. Hermes 는 자기 체크포인트 보관소를 사진에 담지 않습니다. 실제 공간 회수(
git gc)는 주기적 정리가 따로 하므로 도구 호출이 기다리지 않습니다. 사진 찍기·복원·diff·정리는 잠금 하나를 함께 써서 겹치면 “보관소가 사용 중”이라고 알리고, git 작업이 실패하면 정리를 멈추고 알립니다. - 여러 에이전트를 같은 저장소에서 동시에 돌리는 방법은 공식 문서의 Git worktrees 안내 참고(이 가이드는 다루지 않음).
- 안전장치는 여덟 겹입니다. 내가 만나는 것은 위험 명령 승인(그때그때 답함)과 사용자 허가·격리(미리 정함)이고, 나머지는 알아서 돕니다.
- 위험한 패턴에 맞는 명령은 실행 전에 묻습니다. 선택지는 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 넘는 파일, 컨테이너 백엔드에서는 체크포인트가 찍히지 않거나 빠집니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/security · hermes-agent.nousresearch.com/docs/user-guide/checkpoints-and-rollback (수집일 2026-11-09, 문서에 버전 표기 없음)
문제 해결과 자주 묻는 질문
Hermes Agent 를 쓰다가 막혔을 때 펼쳐 보는 장입니다. 공식 문서 「FAQ & Troubleshooting」 쪽에 실린 질문과 증상을 하나도 빼지 않고 증상 → 원인 → 해결 순서로 옮겼습니다. 처음부터 끝까지 읽을 필요는 없습니다. 아래 그림에서 내 증상을 찾아 그 소절만 보면 됩니다.
- 증상만 보고 어느 소절을 펼칠지 고르는 법
- 자주 묻는 질문 9가지 — 비용, 내 자료가 어디로 가는지, 인터넷 없이 쓸 수 있는지 등
- 설치 직후 가장 흔한
hermes: command not found를 푸는 순서 - 모델·제공자 오류, 대화가 길어져 생기는 오류, 메신저 봇이 답하지 않을 때의 확인 순서
- 프로필에 관한 질문 5가지와, 다른 컴퓨터로 옮기기 같은 활용 패턴
- 그래도 안 풀릴 때 어디에 무엇을 적어 물어볼지
- 자주 묻는 질문 9가지 — 쓰기 전에 가장 궁금한 것들(비용·내 자료·로컬 모델).
- 설치·실행이 안 될 때 — 설치 직후 가장 많이 만나는 막힘과 푸는 순서.
나머지 소절은 그 증상을 만났을 때 찾아보면 됩니다. 접힌 상자(▸)는 드문 경우와 관리자용 내용입니다.
어디가 막혔나 — 증상으로 소절 찾기
문제를 풀 때 가장 먼저 할 일은 “어디에서 막혔는가”를 가르는 것입니다. 원문은 문제를 설치 · 제공자와 모델 · 터미널 · 메신저 · 성능 · MCP · 스킬 일곱 묶음으로 나눕니다. 이 가이드는 그것을 아래 여섯 갈래로 묶었습니다. 오른쪽 상자를 누르면 그 소절로 갑니다.
화면에 찍힌 문구를 알고 있다면 아래 표가 더 빠릅니다.
| 보이는 문구·증상 | 볼 소절 |
|---|---|
hermes: command not found | 설치·실행이 안 될 때 |
Permission denied (설치 중, 또는 source 할 때) | 설치·실행이 안 될 때 |
uv: command not found · node: command not found · Python 버전 오류 | 설치·실행이 안 될 때 |
| 설정은 끝났는데 첫 대화에서 HTTP 400 | 설치·실행이 안 될 때 |
| API 키가 통하지 않음 · model not found · 429 | 모델·제공자 문제 |
| “Hermes policy”, “Hermes guardrails” 때문에 거절한다는 답 | 모델·제공자 문제 |
/model 에 제공자가 하나만 보임 | 모델·제공자 문제 |
Context length exceeded · 답이 느림 · 토큰이 많이 듦 | 대화가 길어져 막힐 때 |
위험한 명령이라며 승인을 물음 · sudo 가 안 됨 · Docker 연결 실패 | 명령 실행이 막힐 때 |
| 봇이 답하지 않음 · 게이트웨이가 시작되지 않음 | 메신저 봇 문제 |
| 메신저에 “interrupted mid-request”, “not running or is unreachable”, “could not reach” | 메신저 봇 문제 |
| MCP 서버가 연결되지 않음 · 도구가 안 보임 · 시간 초과 · Skills Hub 403 | MCP·스킬 문제 |
| 프로필끼리 무엇을 나눠 쓰는지 궁금함 | 프로필 질문 5가지 |
| 다른 컴퓨터로 옮기기 · 일마다 다른 모델 쓰기 · Telegram 화면 정리 | 자주 쓰는 활용 패턴 |
원문은 여러 증상에서 같은 확인 도구를 되풀이해 권합니다. 어느 갈래인지 모르겠다면 이 다섯 가지부터 써 봅니다.
| 확인 도구 | 어디에 입력하나 | 원문이 권하는 때 |
|---|---|---|
hermes doctor | 터미널(글자로 명령을 입력하는 창) | 설치본에서 오류가 날 때, 모델 서비스에 연결되지 않을 때. 무엇을 검사하는지는 원문의 이 쪽에 설명이 없습니다. |
hermes config show | 터미널 | 지금 설정(제공자·모델·키)을 확인할 때 |
/status | 대화 입력 칸 | 지금 쓰는 모델과 제공자를 확인할 때 |
/usage | 대화 입력 칸 | 이 세션(대화 한 묶음)의 토큰 사용량과 감지된 컨텍스트 길이를 볼 때 |
| 기록 파일 | 터미널 | logs/agent.log(시도마다 난 오류의 자세한 내용), ~/.hermes/logs/gateway.log(게이트웨이 기록), hermes logs |
설치 직후 무엇부터 다시 해 볼지 정리한 복구 순서는 1장 「복구 순서」에 있습니다.
자주 묻는 질문 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 에 저장하므로 다시 켜도 유지됩니다.
로컬 모델 — config.yaml 로 직접 쓰기, Ollama 주의점, 시간 초과
~/.hermes/config.yaml 에 직접 적어도 됩니다.
model:
default: qwen3.5:27b
provider: custom
base_url: http://localhost:11434/v1
| 항목 | 원문 내용 |
|---|---|
provider: custom | 다른 제공자의 별명이 아니라 정식 제공자입니다. config.yaml 에 그대로 적을 수 있습니다. |
/model custom | 로컬 서버에 모델이 정확히 하나만 올라가 있으면 그 모델을 자동으로 찾아냅니다. |
Ollama 의 num_ctx | Ollama 에서 num_ctx 를 따로 정했다면(예: ollama run --num_ctx 64000) Hermes 쪽 컨텍스트 길이도 같은 값으로 맞춥니다. Ollama 의 /api/show 는 내가 정한 값이 아니라 모델의 최대 컨텍스트를 알려 주기 때문입니다. |
| 시간 초과 | Hermes 는 로컬 주소를 알아보고 기다리는 시간을 늘립니다(읽기 제한 시간 120초 → 1800초, 멈춘 스트림 감지 끔). 아주 큰 컨텍스트에서 그래도 시간 초과가 나면 .env 에 HERMES_STREAM_READ_TIMEOUT=1800 을 적습니다. |
자세한 내용은 공식 문서 Configuration, Local LLM 쪽 참고. 설정 파일은 3장.
기억과 스킬의 차이
기억 (memory) — 사실
에이전트가 나, 내 프로젝트, 내 취향에 대해 알고 있는 것을 담습니다. 관련이 있을 때 자동으로 꺼내 옵니다. → 5장
스킬 (skill) — 절차
어떤 일을 어떻게 하는지 단계별로 적은 설명서입니다. 비슷한 일을 만나면 떠올려 씁니다. → 6장
여러 사람이 쓸 때 — 누가 들어올 수 있나
함께 쓸 때 접근은 두 가지로 다스립니다. 허용 목록(allowlist — 들어와도 되는 사용자 ID 를 적어 둔 목록)과 DM 페어링(DM pairing — 처음 메시지를 보낸 사용자가 접근 권한을 가져가는 방식)입니다. 방식별 차이는 메신저 봇 문제의 표에 있습니다.
WSL2 에서 Hermes 를 쓰며 Windows 의 Chrome 을 조종하고 싶을 때
WSL2(Windows 안에서 Linux 를 돌리는 기능)에서 Hermes 를 쓰는 경우, 원문은 /browser connect 보다 MCP 로 이어 붙이는 방식을 권합니다.
- Hermes 는 WSL2 안에서 실행평소대로 씁니다.
- Chrome 은 Windows 의 것을 그대로이미 로그인해 둔 평소 Chrome 을 계속 씁니다.
chrome-devtools-mcp를 MCP 서버로 추가cmd.exe나powershell.exe를 거쳐 실행되게 등록합니다.- Hermes 가 그 MCP 브라우저 도구를 쓰게 둠WSL2 와 Windows 의 경계를 넘어 Hermes 기본 브라우저 연결을 억지로 붙이는 것보다 안정적이라고 원문은 설명합니다.
MCP 서버 추가는 4장. 원문이 가리키는 Use MCP with Hermes, Browser Automation 쪽은 이 가이드가 다루지 않습니다.
내 Python 프로그램 안에서 Hermes 쓰기
가능합니다. AIAgent 클래스를 불러와 프로그램에서 직접 씁니다.
from run_agent import AIAgent
agent = AIAgent(model="anthropic/claude-opus-4.7")
response = agent.chat("Explain quantum computing briefly")
뜻: 에이전트를 하나 만들고 “양자 컴퓨팅을 짧게 설명해 줘”라고 물어 답을 받습니다. 전체 사용법은 공식 문서 Python Library 쪽 참고(이 가이드는 다루지 않음).
설치·실행이 안 될 때
설치 방법 자체는 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 에 오타가 있다는 뜻입니다.
Python 버전이 맞지 않는다는 오류 (Unsupported Python version)
| 항목 | 원문 내용 |
|---|---|
| 필요한 버전 | 현재 공식 설치본은 Python 3.14 를 요구합니다. “그보다 새 버전이면 아무것이나”가 아닙니다. |
pyproject.toml 의 >=3.11,<3.15 | 예전 설치본이 3.14 로 넘어가기 전에 업데이트 프로그램을 돌릴 수 있게 열어 둔 범위입니다. 지금 실행 환경이 3.11–3.13 을 지원한다는 뜻이 아닙니다. |
| 일반 설치 | 설치 프로그램과 꾸러미로 배포되는 판은 정해진 Python 을 함께 가져옵니다. |
| 소스로 직접 꾸린 환경 | 개발용 설정(development setup)을 씁니다. |
| 하지 말 것 | 설치된 앱이나 컨테이너 안의 Python 을 다른 것으로 바꿔 끼우지 않습니다. |
| 관리형 설치에서 오류 | hermes doctor 를 실행하고, 그 설치 방식에 맞는 업데이트 방법을 씁니다. |
원문 머리말: 이 쪽의 Python 의존성 명령은 PM 이 준비한 소스 체크아웃을 쓴다고 적혀 있습니다. 의존성을 바꾼 뒤에는 체크아웃을 다시 활성화하고 Hermes 를 다시 시작합니다.
에이전트가 실행한 명령이 node: command not found 라고 할 때 (nvm · pyenv · asdf 등)
증상. 내 터미널에서는 되는 node, nvm, pyenv, asdf 같은 도구를 Hermes 가 실행하면 찾지 못합니다.
원인. Hermes 는 시작할 때 bash -l 을 한 번 실행해 세션용 환경을 찍어 둡니다. bash 로그인 셸은 /etc/profile, ~/.bash_profile, ~/.profile 은 읽지만 ~/.bashrc 는 읽지 않습니다. 그래서 거기에 자기를 등록하는 도구(nvm, asdf, pyenv, cargo, 직접 적은 PATH)가 보이지 않습니다. Hermes 가 systemd 아래에서 돌거나, 대화형 셸 설정을 미리 읽지 않는 최소 셸에서 돌 때 가장 흔합니다.
해결. Hermes 는 기본으로 ~/.bashrc 를 자동으로 읽습니다. 그것으로 모자라면(예: zsh 사용자라 PATH 가 ~/.zshrc 에 있거나, nvm 을 별도 파일로 시작하는 경우) 추가로 읽을 파일을 ~/.hermes/config.yaml 에 적습니다.
terminal:
shell_init_files:
- ~/.zshrc # zsh 사용자: zsh 쪽 PATH 를 가져옴
- ~/.nvm/nvm.sh # nvm 을 직접 시작 (셸 종류와 무관)
- /etc/profile.d/cargo.sh # 시스템 공통 설정 파일
# 이 목록을 정하면 기본 ~/.bashrc 자동 읽기는 더해지지 않습니다.
# 둘 다 원하면 ~/.bashrc 도 목록에 직접 적습니다.
| 알아 둘 점 | 원문 내용 |
|---|---|
| 없는 파일 | 조용히 건너뜁니다. |
| zsh 전용 문법 | 파일은 bash 로 읽으므로 zsh 전용 문법이 있으면 오류가 날 수 있습니다. 걱정되면 설정 파일 전체 대신 PATH 를 정하는 부분만(예: nvm 의 nvm.sh) 읽게 합니다. |
| 자동으로 보태지는 PATH | 위 설정과 별개로, 모든 터미널 명령의 PATH 뒤에 표준 시스템 폴더(/usr/local/bin, /opt/homebrew/bin …), Hermes 가 관리하는 실행 폴더, 그리고 있으면 ~/.local/bin 이 덧붙습니다. 내 항목 뒤에 붙으므로 우선순위는 바뀌지 않습니다. systemd, GUI 실행기, Desktop SSH 원격 백엔드처럼 PATH 가 빈약한 곳에서도 설정 없이 통합니다. |
| 자동 읽기 끄기 | terminal: 아래에 auto_source_bashrc: false — 로그인 셸 규칙만 엄격히 따릅니다. |
모델·제공자 문제
Hermes 는 스스로 생각하지 않고 모델(에이전트의 두뇌 역할을 하는 AI)을 빌려 씁니다. 그 모델을 빌려주는 곳이 제공자입니다. “답 대신 오류가 온다”는 증상에 원문이 드는 원인은 주로 키 · 모델 이름 · 사용 한도입니다.
| 증상 | 원인 | 해결 |
|---|---|---|
| API 키가 통하지 않는다 | 키가 없거나, 만료됐거나, 잘못 넣었거나, 다른 제공자의 키입니다. | hermes config show 로 확인 → hermes model 로 다시 설정 |
| Model not available / model not found(모델을 찾을 수 없음) | 모델 이름이 틀렸거나 그 제공자에 없는 모델입니다. | hermes model 로 쓸 수 있는 모델을 보고 다시 고름 |
/model 에 제공자가 하나만 보인다 | /model 은 이미 설정해 둔 제공자 사이에서만 바꿀 수 있습니다. | 대화를 끝내고 터미널에서 hermes model 로 제공자 추가 |
| 429 오류 (Rate limiting) | 제공자가 정한 사용 한도(일정 시간 안에 보낼 수 있는 요청 수)를 넘었습니다. | 잠시 기다렸다 다시 시도 |
| 첫 대화에서 400 오류 | 대개 모델 이름 불일치 | 설치·실행이 안 될 때의 「첫 대화에서 400 오류」 탭 |
hermes config show # 지금 설정 확인
hermes model # 제공자를 다시 설정
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx # 또는 키를 직접 저장
~/.hermes/.env 에 서로 부딪치는 항목이 없는지도 봅니다.
hermes model # 내 제공자에서 쓸 수 있는 모델 목록 보기
hermes config set model.default anthropic/claude-opus-4.7 # 기본 모델 지정
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct # 이번 대화만 다른 모델로
원인이 “모델 이름(식별자)이 틀렸거나 그 제공자에 없다”는 것이므로, 먼저 hermes model 의 목록에서 실제로 있는 모델을 확인합니다.
계속 많이 쓰는 경우라면 원문은 세 가지를 권합니다.
- 제공자의 요금제를 올립니다.
- 다른 모델이나 다른 제공자로 바꿉니다.
hermes chat --provider <alternative>로 이번 대화만 다른 제공자에게 보냅니다(<alternative>자리에 제공자 이름).
hermes model 과 /model 은 하는 일이 다릅니다
/quit 로 대화를 끝냅니다.| 하고 싶은 일 | 쓸 것 |
|---|---|
| 새 제공자 추가 | hermes model (터미널에서) |
| API 키 입력·변경 | hermes model (터미널에서) |
| 대화 도중 모델 바꾸기 | /model <name> (대화 안에서) |
| 설정해 둔 다른 제공자로 바꾸기 | /model provider:model (대화 안에서) |
“Hermes 정책 때문에 못 한다”는 답을 들었을 때
에이전트가 “Hermes policy” 나 “Hermes guardrails” 때문에 요청을 거절한다고 말로만 답할 때가 있습니다. 원문의 설명은 이렇습니다. 모델은 자기가 왜 거절했는지를 믿을 만하게 알아내지 못합니다. 숨은 Hermes 정책 탓이라는 말은 모델이 지어낸 설명이거나, 고른 모델·제공자 쪽에서 건 제한일 수 있습니다.
Hermes 가 막았다면 — 흔적이 남습니다
- 막힌 명령이나 경로의 이름이 적힌 도구 오류가 나옵니다.
- 승인이 필요한 동작이면 승인을 묻는 창이 뜹니다.
- Hermes 는 이런 실행 통제를 “내용을 이유로 한 거절”로 조용히 바꾸지 않습니다.
글로만 거절한다면 — 모델·제공자 쪽입니다
- 도구 오류도 승인 창도 없이 문장으로만 거절합니다.
- 모델을 바꾸면 거절이 달라집니다.
- 제공자 쪽 통제(예: Amazon Bedrock Guardrails)는 설정되어 있으면 적용될 수 있습니다.
/status를 입력합니다지금 쓰는 모델과 제공자를 확인합니다.- 거절에 도구 오류나 승인 창이 있는지 봅니다글뿐이라면 “Hermes 탓”이라는 모델의 말을 증거로 삼지 않습니다.
- 새 세션에서 다른 모델·제공자로 다시 해 봅니다모델에 따라 달라지는 거절은 모델·제공자의 동작이지 Hermes 의 실행 통제가 아닙니다.
- 도구 오류가 분명히 나왔다면문제를 알릴 때 그 문구를 한 글자도 바꾸지 말고 그대로 적습니다.
Hermes 가 실제로 무엇을 막는지는 9장 「안전장치」와 「승인」에 있습니다.
오류 문구 — “…refused this request because of a policy on your account”
| 뜻 | 제공자가 계정 차원의 이유로 요청을 거절했고, 다시 시도해도 바뀌지 않습니다. 여러 모델을 모아 파는 중개 서비스의 데이터·개인정보 설정 때문에 그 모델의 접속처가 모두 제외됐거나, 모델의 원래 제공자가 계정을 막은 경우입니다(예: 이전 정책 위반으로 차단 — OpenRouter 는 이것을 겉보기에 정상인 HTTP 200 응답 안에 실어 전달할 수 있습니다). |
| Hermes 의 동작 | 요청을 한 번만 보내고, 재시도하거나 다른 인증 정보로 돌려 쓰지 않습니다. 대체 경로(fallback chain)가 설정되어 있으면 그쪽으로 넘어갑니다. |
| 해결 | 답에 이름이 나온 제공자에서 계정 상태와 데이터·개인정보 설정을 확인하거나, /model 로 다른 모델·제공자로 바꿉니다. hermes fallback add 를 해 두면 앞으로 이런 차단이 예비 제공자로 자동으로 넘어갑니다. |
오류 문구 — “Could not open a stream to <host> after N attempts (request X KB)”
| 뜻 | 그 접속처로 연결을 여러 번 시도했지만 응답이 한 조각도 오기 전에 모두 실패했습니다. 그래서 요금은 청구되지 않았고, 평소의 재시도·대체 경로는 그 뒤에 그대로 돕니다. |
| 문구에 담긴 세 가지 | 실제로 접속한 호스트 이름, 시도 횟수, 보낸 요청의 크기. “서비스 장애”인지 “요청 크기 제한”인지를 가르는 단서입니다. |
| 요청이 클 때 (수백 KB) | 긴 코딩 세션에서 컨텍스트가 커지면 이 크기에 이릅니다. 짧은 새 대화는 되는데 이것만 안 된다면, 접속처나 그 앞의 프록시가 그 크기의 본문을 거절하는 것일 가능성이 큽니다. 본문 크기 제한을 올리거나 /compress 로 컨텍스트를 줄입니다. |
| 요청이 작을 때 | 접속처에 닿지 않는 것입니다. base_url 을 확인하고 /retry 로 다시 시도합니다. |
| 기록 | logs/agent.log 에 시도마다 오류가 이어진 경로가 남습니다. |
메신저에서 보이는 세 가지 짧은 연결 오류 문구(“interrupted mid-request” 등)는 메신저 봇 문제에서 다룹니다.
대화가 길어져 막힐 때 — 컨텍스트 초과 · 토큰 · 속도
모델이 한 번에 볼 수 있는 글의 양은 정해져 있습니다. 이 양을 컨텍스트라고 하고, 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)으로 셉니다. 대화가 길어지고 도구 결과가 쌓이면 이 칸이 차오르고, 가득 차면 Context length exceeded(컨텍스트 길이 초과) 오류가 납니다. 원문이 드는 원인은 둘입니다. 대화가 정말로 너무 길어졌거나, Hermes 가 내 모델의 컨텍스트 길이를 잘못 알고 있거나.
/compress # (대화 안에서) 지금 세션을 압축
hermes chat # (터미널에서) 새 세션 시작
hermes chat --model openrouter/google/gemini-3-flash-preview # 컨텍스트가 더 큰 모델로 시작
첫 번째 긴 대화에서 벌써 이 오류가 난다면 Hermes 가 컨텍스트 길이를 잘못 알고 있을 수 있습니다. Hermes 를 켤 때 나오는 첫 줄에 감지한 값이 보입니다(예: 📊 Context limit: 128000 tokens — 컨텍스트 한도 128000 토큰). 대화 중에는 /usage 로도 볼 수 있습니다. 값이 틀렸다면 아래 접힌 상자대로 직접 적어 줍니다.
느리다 · 토큰을 많이 쓴다 · 세션이 너무 길다
원문이 「성능 문제」로 묶은 세 가지입니다. 해결책이 위와 겹칩니다.
| 증상 | 원인 | 해결 |
|---|---|---|
| 답이 느리다 | 큰 모델, 멀리 있는 API 서버, 또는 도구가 많아 무거워진 시스템 프롬프트(대화마다 모델에게 먼저 건네는 기본 지시문) | 더 빠르고 작은 모델로: hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct켜 둔 툴셋(toolset — 도구 꾸러미) 줄이기: hermes chat -t "terminal"제공자까지의 네트워크 지연 확인 로컬 모델이면 GPU VRAM(그래픽 카드의 메모리)이 충분한지 확인 |
| 토큰을 많이 쓴다 | 긴 대화, 장황한 시스템 프롬프트, 도구 호출이 쌓여 불어난 컨텍스트 | hermes prompt-size 로 고정 비용 재기 → /compress 로 대화 줄이기 → /usage 로 세션 사용량 확인 |
| 세션이 너무 길어졌다 | 메시지와 도구 출력이 쌓여 컨텍스트 한도에 다가갑니다. | /compress(핵심 맥락은 남김) → 또는 hermes chat 으로 새 세션 → 필요하면 나중에 hermes chat --continue 로 이어 하기 |
/compress 는 지금까지의 대화를 요약해, 맥락은 지키면서 토큰 사용량을 크게 줄입니다. 압축이 어떻게 이루어지는지는 3장 「압축」에 있습니다.
hermes prompt-size 가 이 비용을 시스템 프롬프트 · 스킬 목록 · 기억 · 도구 스키마 덩어리별로 보여 줍니다(인터넷 없이 실행됩니다). 그다음 hermes tools 로 안 쓰는 툴셋을 끄고, hermes skills 로 필요 없는 스킬을 지우거나 끕니다.
컨텍스트 길이를 직접 정하기 · 로컬 서버(llama.cpp · Ollama · LM Studio)에서 나오는 문구 두 가지
직접 정하기. ~/.hermes/config.yaml 에 내 모델의 실제 컨텍스트 크기를 적습니다.
model:
default: your-model-name
context_length: 131072 # 내 모델의 실제 컨텍스트 크기
직접 주소를 넣은 접속처(custom endpoint)라면 제공자 항목 아래에 모델별로 적을 수도 있습니다.
providers:
my-server:
api: "http://localhost:11434/v1"
models:
qwen3.5:27b:
context_length: 64000
예전 설정의 custom_providers: 목록도 아직 지원되며 providers: 로 자동으로 옮겨집니다. 자동 감지 방식과 모든 덮어쓰기 방법은 공식 문서 Context Length Detection 쪽 참고. 한도 설정은 3장.
| 보이는 문구 | 무슨 일인가 | 해결 |
|---|---|---|
Context length exceeded: compression could not reduce the rebuilt request below the safe threshold | 제공자가 요청이 너무 크다고 거절하면 Hermes 는 대화를 압축하고 요청을 다시 만듭니다. 다시 만든 요청 전체(시스템 프롬프트 + 도구 스키마 + 메시지)를 다시 재고, 여전히 기준을 넘으면 정해진 횟수 안에서 압축을 더 합니다. 그래도 들어가지 않으면 이 문구로 그 차례를 끝냅니다. 너무 큰 요청을 그대로 보내면 llama.cpp 는 오류 없이 조용히 잘라 버리기 때문입니다(서버 기록의 stop processing: n_tokens = 65535, truncated = 1). | 거의 언제나 위의 context_length 설정이 답입니다. 서버의 실제 -c / --ctx-size 값과 맞춥니다. |
The model server rejected this request as too large, but this conversation is only about N tokens… | 로컬 서버(localhost, LAN, Tailscale)가 측정값 없이 “컨텍스트 초과”라고만 했는데, Hermes 가 어림한 요청 크기는 모델의 창보다 훨씬 작은 경우입니다. 그래서 Hermes 는 압축하지도, 대화 탓을 하지도 않고 그 차례를 다시 시도할 수 있게 둡니다. 한 번에 요청 하나만 받는 로컬 서버(LM Studio, Ollama)에서는 거의 언제나 그 순간 다른 요청이 서버를 쓰고 있던 것입니다. 보통 이전 세션의 백그라운드 기억 검토입니다(logs/agent.log 의 thread=bg-review). | 잠시 기다렸다가 /retry. 다른 Hermes 가 돌고 있지 않은데도 반복되면, 서버가 Hermes 의 짐작보다 작은 창으로 모델을 올린 것입니다. 서버의 컨텍스트 설정을 올리거나 model.context_length 를 낮춰 맞춥니다. |
호스팅형 제공자에서는 둘째 문구가 나오지 않습니다. 기다려 줄 공유 자리가 없으므로, 같은 거절은 그 경로의 실제 창이 Hermes 의 짐작보다 작다는 뜻이고 Hermes 는 압축한 뒤 다시 시도합니다.
명령 실행이 막힐 때 — 위험 명령 · sudo · Docker
Hermes 가 내 대신 터미널 명령을 실행하다가 멈추는 경우입니다. 셋 중 첫째는 고장이 아니라 안전장치가 제대로 일한 것입니다.
| 증상 | 원인 | 해결 |
|---|---|---|
| 명령이 위험하다며 막힌다 (Command blocked as dangerous) | Hermes 가 자료를 망가뜨릴 수 있는 명령이라고 알아챘습니다(예: rm -rf — 폴더째 지우기, DROP TABLE — 데이터베이스 표 지우기). | 물음이 뜨면 명령을 읽어 보고, 괜찮으면 y 를 입력해 승인합니다. 또는 에이전트에게 더 안전한 방법을 쓰라고 합니다. |
메신저로 시킨 sudo 가 안 된다 | 게이트웨이는 대화형 터미널 없이 돌기 때문에 sudo 가 비밀번호를 물어볼 수 없습니다. | 메신저에서는 sudo 를 피하고 다른 방법을 찾게 합니다. 관리 작업은 터미널에서 hermes chat 으로 합니다. 꼭 필요하면 특정 명령만 비밀번호 없이 쓰도록 /etc/sudoers 에 설정합니다. |
| Docker 백엔드가 연결되지 않는다 | 터미널 백엔드(에이전트의 명령이 실제로 실행되는 곳)를 Docker 로 골랐는데 Docker 데몬(뒤에서 계속 돌며 일하는 프로그램)이 꺼져 있거나 내 사용자에게 권한이 없습니다. | 아래 접힌 상자의 세 단계 |
sudo 다루기는 4장, 터미널 백엔드는 4장 「백엔드」에 있습니다.
Docker 백엔드가 연결되지 않을 때 확인 명령
docker info # Docker 가 돌고 있는지 확인
sudo usermod -aG docker $USER # 내 사용자를 docker 그룹에 추가
newgrp docker
docker run hello-world # 되는지 시험
메신저 봇 문제
Telegram 같은 메신저에서 Hermes 를 쓰려면 게이트웨이가 계속 켜져 있어야 합니다(8장 「설정」). 내 메시지는 메신저 → 게이트웨이 → Hermes → 모델 서비스를 차례로 거치므로, 어느 고리에서 끊겼는지에 따라 증상이 다릅니다.
봇이 답하지 않을 때 — 세 단계
원인은 셋 중 하나입니다. 봇(게이트웨이)이 돌고 있지 않거나, 권한이 없거나, 내 사용자가 허용 목록에 없습니다.
1. 게이트웨이가 켜져 있는지 봅니다
hermes gateway status
확인: 게이트웨이가 돌고 있는지 알려 줍니다. 꺼져 있다면 2단계, 켜져 있다면 3단계로 갑니다.
2. 꺼져 있으면 켭니다
hermes gateway start
확인: 메신저에서 다시 말을 걸어 답이 오는지 봅니다. 시작 자체가 실패하면 아래 접힌 상자 「게이트웨이가 시작되지 않을 때」를 봅니다.
3. 켜져 있는데도 조용하면 기록을 봅니다
cat ~/.hermes/logs/gateway.log | tail -50
뜻: 게이트웨이 기록 파일의 마지막 50줄을 보여 줍니다. 오류가 적혀 있는지 찾습니다.
확인: 오류가 없다면 내가 대화할 권한이 있는 사용자인지 아래 표에서 확인합니다.
누가 봇과 대화할 수 있나 — 권한 방식 세 가지
| 방식 | 동작 |
|---|---|
| Allowlist 허용 목록 | 설정에 적어 둔 사용자 ID 만 대화할 수 있습니다. |
| DM pairing DM 페어링 | DM(일대일 대화)으로 처음 메시지를 보낸 사용자가 혼자 쓰는 권한을 갖습니다. |
| Open 열어 둠 | 누구나 대화할 수 있습니다. 실제로 운영하는 환경에는 권하지 않습니다. |
이 방식은 ~/.hermes/config.yaml 의 게이트웨이 설정 아래에서 정합니다. 자세한 것은 9장 「권한」.
메신저에 뜨는 세 가지 짧은 오류 문구
채팅 화면(Telegram, Discord, Slack …)에는 원래의 통신 오류가 그대로 보이지 않습니다. 게이트웨이가 그것을 세 가지 짧은 답 중 하나로 바꿔 보여 주는데, 어느 문구냐에 따라 살펴볼 곳이 다릅니다.
| 답으로 온 문구 | 무슨 일인가 | 할 일 |
|---|---|---|
| “The connection to the AI model service was interrupted mid-request — usually transient.” 뜻: 요청 도중 연결이 끊김 — 대개 일시적 | 이미 맺어진 연결이 중간에 끊겼습니다(Connection reset by peer, EOF, RemoteProtocolError). 접속처가 연결에는 응답했으므로 서버는 켜져 있습니다. | /retry. 큰 요청에서 되풀이되면 모델·제공자 문제의 접힌 상자 「Could not open a stream…」 |
| “The AI model service isn't reachable right now — the configured model endpoint is not running or is unreachable.” 뜻: 설정된 모델 접속처가 꺼져 있거나 닿지 않음 | 연결을 받아 주는 곳이 없습니다(Connection refused — 연결 거부, no route to host — 경로 없음, DNS 실패 — 주소 찾기 실패). | 모델 서버를 켜거나 base_url 을 확인한 뒤 /retry. Hermes 가 도는 컴퓨터에서 hermes doctor |
| “Hermes could not reach the AI model service (no further detail from the SDK).” 뜻: 모델 서비스에 닿지 못함 — 더 자세한 정보 없음 | SDK(제공자와 통신하는 데 쓰는 프로그램 부품)가 일반적인 APIConnectionError 만 알리고 원인은 남기지 않았습니다. 위 둘 중 어느 쪽인지 확실하지 않습니다. | /retry. 계속되면 hermes doctor. 원래 오류는 hermes logs 에 있습니다. |
메시지가 전달되지 않을 때 (Messages not delivering)
원인. 네트워크 문제, 만료된 봇 토큰(봇을 움직일 수 있는 비밀 열쇠 문자열), 또는 플랫폼 웹훅(webhook — 새 메시지가 오면 플랫폼이 내 서버로 알려 주는 방식) 설정 오류.
hermes gateway setup으로 봇 토큰이 유효한지 확인합니다.- 게이트웨이 기록을 봅니다:
cat ~/.hermes/logs/gateway.log | tail -50 - 웹훅 방식 플랫폼(Slack, WhatsApp)은 내 서버가 인터넷에서 접근할 수 있어야 합니다.
게이트웨이가 시작되지 않을 때 (Gateway won't start)
원인. 필요한 구성 요소가 빠졌거나, 포트(프로그램이 통신에 쓰는 번호 창구)가 겹치거나, 토큰 설정이 틀렸습니다.
# 메신저 게이트웨이의 기본 구성 요소 설치 (Telegram, Discord, Slack 과 공통 부분)
cd ~/.hermes/hermes-agent && python -c "import pm; pm.sync_venv(['messaging'], explicit=True)"
# 포트가 겹치는지 확인
lsof -i :8080
# 설정 확인
hermes config show
WSL — 게이트웨이가 자꾸 끊기거나 hermes gateway start 가 실패할 때
원인. WSL 의 systemd(Linux 에서 프로그램을 서비스로 계속 켜 두는 장치) 지원이 불안정합니다. 많은 WSL2 설치본은 systemd 가 꺼져 있고, 켜져 있어도 WSL 이 다시 시작되거나 Windows 가 쉬는 동안 종료되면 서비스가 살아남지 못할 수 있습니다.
해결. systemd 서비스 대신 터미널에 띄워 두는 방식(foreground)을 씁니다.
# 방법 1: 그대로 띄워 두기 (가장 간단)
hermes gateway run
# 방법 2: tmux 로 유지 (터미널을 닫아도 살아 있음)
tmux new -s hermes 'hermes gateway run'
# 나중에 다시 붙기: tmux attach -t hermes
# 방법 3: nohup 으로 뒤에서 실행
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &
그래도 systemd 를 써 보려면 켜져 있는지부터 확인합니다.
/etc/wsl.conf를 엽니다없으면 새로 만듭니다.- 아래 두 줄을 넣습니다
[boot]와 그 아랫줄systemd=true - PowerShell 에서
wsl --shutdown그다음 WSL 터미널을 다시 엽니다. - 확인:
systemctl is-system-running“running” 또는 “degraded” 가 나와야 합니다.
Windows 를 켤 때 자동 시작. 안정적으로 자동 시작하려면 Windows 작업 스케줄러(Task Scheduler)에 wsl -d Ubuntu -- bash -lc 'hermes gateway run' 을 실행하는 작업을 만들고, 사용자 로그온 때 실행되게 합니다.
macOS — 게이트웨이가 Node.js · ffmpeg 같은 도구를 찾지 못할 때
원인. launchd(macOS 에서 프로그램을 서비스로 계속 켜 두는 장치)로 도는 서비스는 최소한의 PATH(/usr/bin:/bin:/usr/sbin:/sbin)만 물려받습니다. Homebrew, nvm, cargo 처럼 내가 설치한 도구의 폴더가 빠져 있어 WhatsApp 연결 다리(node 를 못 찾음)나 음성 받아쓰기(ffmpeg 를 못 찾음)가 흔히 깨집니다.
해결. 게이트웨이는 hermes gateway install 을 실행하는 순간의 셸 PATH 를 담아 둡니다. 게이트웨이를 설정한 뒤에 도구를 설치했다면 설치를 다시 실행해 새 PATH 를 담습니다.
hermes gateway install # 지금의 PATH 를 다시 담음
hermes gateway start # 바뀐 설정 파일(plist)을 알아채고 다시 읽음
설정 파일에 PATH 가 제대로 들어갔는지 확인하려면:
/usr/libexec/PlistBuddy -c "Print :EnvironmentVariables:PATH" \
~/Library/LaunchAgents/ai.hermes.gateway.plist
Telegram 에 한정된 문제는 8장 「문제 해결」, 게이트웨이를 서비스로 켜 두는 방법은 8장 「서비스」에 있습니다. 메신저로 시킨 sudo 가 안 되는 경우는 명령 실행이 막힐 때를 봅니다.
MCP · 스킬 문제
MCP(Model Context Protocol — 외부 서비스의 도구를 에이전트에 연결하는 공통 규격) 서버를 붙였는데 도구가 보이지 않거나, 스킬을 찾는 화면이 열리지 않는 경우입니다. MCP 서버는 Hermes 와 별개의 프로그램이라, 서버 쪽이 죽었는지부터 가르는 것이 요령입니다.
| 증상 | 원인 | 해결 |
|---|---|---|
| MCP 서버가 연결되지 않는다 | 서버 실행 파일을 찾지 못했거나, 명령 경로가 틀렸거나, 서버를 돌릴 실행 환경(예: Node.js)이 없습니다. | node --version, npx --version 으로 Node.js 확인 → 서버를 손으로 직접 실행해 봄 → config.yaml 의 mcp_servers 항목 확인 |
| MCP 서버의 도구가 보이지 않는다 | 서버는 떴지만 도구 목록을 받아 오지 못했거나, 설정에서 걸러졌거나, 서버가 기대한 MCP 기능을 지원하지 않습니다. | 기록에서 MCP 연결 오류 확인 → 그 서버의 포함·제외 설정 검토 → 설정을 바꿨다면 /reload-mcp |
| MCP 시간 초과 오류 | 서버의 응답이 너무 느리거나, 실행 도중 서버가 죽었습니다. | 서버 설정이 지원하면 제한 시간을 늘림 → 서버 프로세스가 살아 있는지 확인 → 원격 HTTP 서버라면 네트워크 확인 |
| 데스크톱 앱에서 Skills Hub 화면이 열리지 않는다 (403 · 차단) | 문서 사이트가 거치는 서비스의 방화벽이 일부 가정용 인터넷 주소 대역을 막습니다. 내 네트워크가 그 대역이면 요청마다 403 차단 화면이 돌아옵니다. | Skills Hub 선택 화면이 알아서 같은 목록을 가진 예비 주소로 넘어갑니다. 그래도 안 되면 프록시 · DNS 필터 · 방화벽이 두 주소를 다 막는지 확인 |
MCP 서버를 추가하는 방법은 4장 「MCP 추가」, 도구 걸러내기는 「MCP 필터」, MCP 쪽 문제 해결은 「MCP 문제」, Skills Hub 는 6장에 있습니다.
MCP — 확인 명령과 설정 예, 도구가 안 보일 때 점검 목록
연결되지 않을 때.
# MCP 구성 요소 설치 확인 (표준 설치에는 이미 들어 있음)
cd ~/.hermes/hermes-agent && python -c "import pm; pm.sync_venv(['mcp'], explicit=True)"
# npm 기반 서버라면 Node.js 가 있는지 확인
node --version
npx --version
# 서버를 손으로 직접 실행해 보기
npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir
~/.hermes/config.yaml 의 MCP 설정이 이런 모양인지 확인합니다.
mcp_servers:
filesystem:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
도구가 보이지 않을 때 점검 목록.
- 게이트웨이·에이전트 기록에서 MCP 연결 오류를 찾습니다.
- 서버가
tools/list요청(도구 목록을 달라는 호출)에 응답하는지 확인합니다. - 그 서버 아래의
tools.include,tools.exclude,tools.resources,tools.prompts,enabled설정을 검토합니다. - resource · prompt 용 보조 도구는 세션이 그 기능을 실제로 지원할 때만 등록됩니다.
- 설정을 바꾼 뒤에는
/reload-mcp를 씁니다.
hermes config show | grep -A 12 mcp_servers # MCP 서버가 설정돼 있는지 확인
hermes chat # 설정을 바꿨다면 다시 시작하거나 /reload-mcp
원문이 함께 가리키는 쪽: MCP (Model Context Protocol), Use MCP with Hermes, MCP Config Reference.
Skills Hub 403 — 원문의 자세한 설명
문서 사이트(hermes-agent.nousresearch.com)는 Vercel 을 거쳐 제공되고, Vercel 의 WAF(웹 방화벽)는 의심스럽다고 표시한 일부 가정용 IP 대역을 거부합니다. Skills Hub 선택 화면은 먼저 원래 주소를 찔러 보고, 막히면 같은 목록을 제공하는 GitHub Pages 판(nousresearch.github.io/hermes-agent)으로 자동으로 넘어갑니다. 두 곳 모두에서 실패한다면 프록시, DNS 필터, 방화벽이 두 호스트를 다 막고 있는지 확인하고, 막힌 대역을 관리자(maintainers)에게 알려 배포 쪽에서 검토할 수 있게 합니다.
프로필 질문 5가지
프로필(profile — 설정·기억·세션을 따로 쓰는 별도 Hermes 환경)은 한 컴퓨터에서 Hermes 를 여러 벌로 나눠 쓰는 방법입니다. 예를 들어 업무용과 개인용을 따로 둡니다. 원문 FAQ 가 답하는 다섯 가지를 그림 하나로 먼저 봅니다.
| 질문 | 답 |
|---|---|
| 두 프로필이 같은 봇 토큰을 써도 되나요? | 안 됩니다. 메신저 플랫폼(Telegram, Discord 등)은 봇 토큰 하나를 한 곳에서만 쓰게 합니다. 두 프로필이 동시에 같은 토큰을 쓰면 두 번째 게이트웨이가 연결에 실패합니다. 프로필마다 봇을 따로 만듭니다 — Telegram 이라면 @BotFather 에게 말을 걸어 봇을 더 만듭니다(8장). |
| 프로필끼리 기억이나 세션을 나눠 쓰나요? | 아닙니다. 프로필마다 자기 기억 저장소, 세션 데이터베이스, 스킬 폴더가 있고 완전히 분리되어 있습니다. 지금 프로필의 기억과 세션을 가지고 새 프로필을 시작하려면 hermes profile create newname --clone-all 로 전부 복사합니다. 특정 프로필에서 복사하려면 --clone-from <profile> 을 덧붙입니다. |
hermes update 를 하면 어떻게 되나요? | 최신 코드를 받아 오고 필요한 구성 요소를 한 번만 다시 설치합니다(프로필마다 하지 않음). 그다음 갱신된 스킬을 모든 프로필에 자동으로 맞춥니다. 한 번 실행하면 그 컴퓨터의 모든 프로필에 적용됩니다. |
| 프로필을 몇 개까지 돌릴 수 있나요? | 정해진 한도는 없습니다. 실제 한계는 디스크 공간과, 동시에 켜 둘 수 있는 게이트웨이 수입니다(게이트웨이 하나는 가벼운 Python 프로세스). 수십 개도 괜찮고, 쉬고 있는 프로필은 자원을 쓰지 않습니다. |
그냥 HERMES_HOME 을 정하는 것과 무엇이 다른가요? | 프로필은 HERMES_HOME(Hermes 가 자료를 두는 폴더를 가리키는 설정값) 위에 얹은 관리 기능입니다. 손으로 해야 할 일을 대신 해 줍니다(자세한 것은 아래 접힌 상자). |
HERMES_HOME 과의 차이 · 프로필로 인정되는 폴더의 조건
HERMES_HOME 과의 차이. 명령마다 앞에 HERMES_HOME=/some/path 를 직접 붙여도 되지만, 프로필은 그 뒷일을 모두 맡습니다.
- 폴더 구조를 만들어 줍니다.
- 셸 별칭(긴 명령을 짧게 부르는 이름)을 만들어 줍니다(예:
hermes-work). - 지금 쓰는 프로필을
~/.hermes/active_profile에 적어 둡니다. - 스킬 업데이트를 모든 프로필에 자동으로 맞춥니다.
- 탭 자동 완성과 이어져 있어 경로를 외울 필요가 없습니다.
프로필로 인정되는 폴더. 프로필은 ~/.hermes/profiles/ 아래의 폴더이고, 신원 파일(config.yaml, .env, SOUL.md, profile.yaml, auth.json, state.db) 가운데 하나 이상을 가지고 있어야 합니다. 그런 파일이 없는 빈 폴더(기록 정리나 예약 작업이 남긴 흔적)는 프로필이 아닙니다. 목록에 나오지 않고, -p <name> 으로 부르면 없다고 나오며, hermes profile create <name> 은 그 폴더를 옮기거나 지우기 전에는 덮어쓰지 않습니다.
프로필 사용법 자체는 공식 문서 Profiles 쪽 참고(이 가이드는 다루지 않음).
자주 쓰는 활용 패턴
고장은 아니지만 “이럴 때는 어떻게 하지?” 하고 자주 묻는 상황들입니다. 원문 「Workflows & Patterns」의 항목을 표로 먼저 훑고, 자주 쓰일 세 가지는 탭에서 자세히 봅니다.
| 상황 | 한 줄 답 | 자세히 |
|---|---|---|
| 일마다 다른 모델을 쓰고 싶다 | 위임 설정으로 하위 에이전트만 다른 모델을 쓰게 합니다. | 아래 탭 ① |
| Telegram 에 기록·추론 과정까지 다 보인다 | display.tool_progress 로 보이는 양을 줄입니다. | 아래 탭 ② |
| Hermes 를 다른 컴퓨터로 통째로 옮긴다 | hermes backup → 복사 → hermes import | 아래 탭 ③ |
| 프로필 하나만 옮기거나 나눠 준다 | hermes profile export → hermes profile import | 아래 탭 ③ |
hermes backup 과 hermes profile export 의 차이 | 전체 이사용 대 프로필 하나용. 인증 정보 포함 여부가 다릅니다. | 탭 아래 표 |
| WhatsApp 번호 하나에 에이전트 여럿을 붙이고 싶다 | 지금은 안 됩니다(번호마다 세션 하나). 우회 방법 네 가지가 있습니다. | 접힌 상자 |
| Telegram 슬래시 명령 100개 한도에 걸린다 | Telegram 에서만 일부 스킬을 끕니다. | 접힌 상자 |
| 여러 사람이 한 대화 스레드를 함께 쓰고 싶다 | 대부분 플랫폼은 사용자별 세션입니다. Slack · Discord 채널이 대안입니다. | 접힌 상자 |
원문은 이 묶음 끝에 「설치 뒤 셸을 다시 읽을 때 Permission denied」와 「첫 실행에서 400 오류」도 넣어 두었습니다. 이 가이드에서는 둘 다 설치·실행이 안 될 때의 탭으로 옮겼습니다.
상황. 평소에는 GPT-5.4 를 쓰지만 SNS 글은 Gemini 나 Grok 이 더 잘 씁니다. 매번 손으로 모델을 바꾸기는 번거롭습니다.
해결. 위임(delegation — 일을 나눠 맡기기) 설정을 씁니다. Hermes 가 하위 에이전트(subagent — 일을 나눠 받은 별도 에이전트)를 자동으로 다른 모델에 맡기게 됩니다. ~/.hermes/config.yaml 에 적습니다.
delegation:
model: "google/gemini-3-flash-preview" # 하위 에이전트가 쓸 모델
provider: "openrouter" # 하위 에이전트가 쓸 제공자
| 내가 하는 말 | 일어나는 일 |
|---|---|
| “write me a Twitter thread about X” 뜻: X 에 대한 트위터 글타래를 써 줘 | Hermes 가 delegate_task 로 하위 에이전트를 만들면, 그 하위 에이전트는 Gemini 로 돕니다. 내 주 대화는 GPT-5.4 그대로입니다. |
| “Delegate a task to write social media posts about our product launch. Use your subagent for the actual writing.” 뜻: 제품 출시에 대한 SNS 글 쓰기를 위임해 줘. 실제 글쓰기는 하위 에이전트에게 시켜. | 이렇게 분명히 말하면 에이전트가 delegate_task 를 쓰고, 위 설정이 자동으로 적용됩니다. |
위임 없이 한 번만 바꾸려면 대화 안에서 /model 을 씁니다.
/model google/gemini-3-flash-preview # 이 세션만 바꿈
# ... 글을 씀 ...
/model openai/gpt-5.4 # 되돌림
상황. Telegram 에 최종 답만이 아니라 게이트웨이 실행 기록, Hermes 의 추론, 도구 호출 내용까지 올라옵니다.
해결. config.yaml 의 display.tool_progress 가 도구 활동을 얼마나 보여 줄지 정합니다.
display:
tool_progress: "off" # 고를 수 있는 값: off, new, all, verbose
| 값 | 보이는 것 |
|---|---|
off | 최종 답만. 도구 호출도, 추론도, 기록도 없음 |
new | 새 도구 호출이 일어날 때마다 짧게 한 줄 |
all | 결과를 포함한 모든 도구 활동 |
verbose | 도구에 넘긴 값과 출력까지 전부 |
메신저에서는 보통 off 나 new 가 알맞습니다. config.yaml 을 고친 뒤에는 게이트웨이를 다시 시작해야 적용됩니다. 세션마다 바꾸고 싶다면 아래 설정을 켜서 게이트웨이에서 /verbose 명령을 쓸 수 있게 합니다.
display:
tool_progress_command: true # 게이트웨이에서 /verbose 를 쓸 수 있게 함
상황. 한 컴퓨터에서 스킬, 예약 작업(cron — 정해 둔 시간에 자동 실행), 기억을 쌓아 왔고, 이것을 새 Linux 컴퓨터로 전부 옮기려 합니다.
- 새 컴퓨터에 Hermes 를 설치합니다
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash - 원래 컴퓨터에서 전체 백업을 만듭니다
hermes backup—~/hermes-backup-<timestamp>.zip이 생깁니다. 설정, 인증 정보, 기억, 스킬, 세션, 프로필이 들어갑니다. 프로그램 자체나 실행 환경의 복사본은 아닙니다. - zip 을 새 컴퓨터로 복사해 불러옵니다원래 컴퓨터에서
scp ~/hermes-backup-<timestamp>.zip newmachine:~/, 새 컴퓨터에서hermes import ~/hermes-backup-<timestamp>.zip - 새 컴퓨터에서
hermes setup을 실행합니다API 키와 제공자 설정이 제대로 동작하는지 확인합니다.
프로필 하나만 옮기거나 나눠 줄 때는 전체 백업 대신 이렇게 합니다.
hermes profile export work ./work-backup.tar.gz # 원래 컴퓨터에서
hermes profile import ./work-backup.tar.gz work # 파일을 복사한 뒤, 받는 컴퓨터에서
불러온 프로필에는 내보낸 설정, 기억, 세션, 스킬이 모두 들어 있습니다. 새 컴퓨터의 환경이 다르면 경로를 고치거나 제공자에 다시 로그인해야 할 수 있습니다.
hermes backup 과 hermes profile export 의 차이
| 항목 | hermes backup | hermes profile export |
|---|---|---|
| 쓰임새 | 컴퓨터를 통째로 옮길 때 | 프로필 하나를 옮기거나 나눠 줄 때 |
| 범위 | Hermes 자료 폴더 전체(일부 제외 — 아래 접힌 상자) | 프로필 폴더 하나 |
| 들어가는 것 | 모든 프로필, 공통 설정, API 키, 세션 | 그 프로필의 SOUL.md, 기억, 세션, 스킬 |
| 인증 정보 | 포함 (.env 와 auth.json) | 제외 (안전하게 나눠 줄 수 있게 뺌) |
| 파일 형식 | .zip | .tar.gz |
hermes backup 의 zip 에는 .env 와 auth.json 이 그대로 들어갑니다. 남에게 건넬 것이라면 인증 정보가 빠지는 hermes profile export 를 씁니다.
전체 백업에서 빠지는 것 · --quick · 건너뛴 파일 보고 · rsync 로 직접 복사
전체 백업이 넣지 않는 것.
- 소스 체크아웃, 의존성 환경, 내려받은 도구·모델·실행 환경
- 빌드 캐시, 체크포인트, 이전 백업, 빠른 스냅샷
- 브라우저 프로필(실제 브라우저의 인증 정보 복사본 포함)
- 바이트코드, SQLite 보조 파일,
gateway.pid,cron.pid,.backup.lock
| 항목 | 원문 내용 |
|---|---|
hermes backup --quick | 전체 묶음 대신 골라낸 상태 파일만 저장합니다. 컴퓨터를 옮기기 전의 전체 백업을 대신하지 못합니다. |
| 건너뛴 파일 보고 | 전체 백업은 복사에 실패한 파일을 알려 줍니다. 곧 자료가 빠진 채로도 묶음 파일은 만들어질 수 있습니다. 원래 설치본을 지우기 전에 건너뛴 파일 보고를 꼭 확인합니다. |
| 빠진 것은 어떻게 되나 | 복원된 꾸러미 목록을 보고 PM 이 의존성을 다시 내려받습니다. 바이트코드와 SQLite 보조 파일은 그 컴퓨터에서 다시 만들어집니다. 제외 목록 때문에 .env 나 auth.json 이 빠지지는 않습니다. |
| 실행 중 백업 | hermes backup 은 Hermes 가 돌고 있는 중에도 앞뒤가 맞는 스냅샷을 만듭니다. 복원된 묶음에는 gateway.pid, cron.pid 같은 그 컴퓨터 전용 실행 파일이 빠져 있습니다. |
rsync 로 직접 복사(수동 대안). 파일을 직접 복사하고 싶다면 코드 저장소 폴더는 빼고 복사합니다.
rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/
WhatsApp 번호 하나에 에이전트 여럿 (채팅별로 묶기)
상황. OpenClaw 에서는 특정 WhatsApp 채팅마다 독립된 에이전트를 묶어 썼습니다(가족 장보기 목록 그룹용 하나, 개인 채팅용 하나). Hermes 에서도 되는지 묻는 경우입니다.
지금의 제약. Hermes 프로필은 각자 자기 WhatsApp 번호(세션)가 필요합니다. 같은 번호의 서로 다른 채팅에 여러 프로필을 묶을 수 없습니다. WhatsApp 연결 다리(Baileys)가 번호 하나에 인증된 세션 하나만 쓰기 때문입니다.
| 우회 방법 | 내용 |
|---|---|
| 프로필 하나로 성격만 바꾸기 | 맥락 파일(대화마다 자동으로 읽히는 파일) AGENTS.md 를 다르게 만들거나 /personality 명령으로 채팅마다 행동을 바꿉니다. 에이전트는 자기가 어느 채팅에 있는지 보고 맞출 수 있습니다. |
| 예약 작업 쓰기 | 장보기 목록 관리 같은 특정 일이라면, 정해진 채팅을 살피며 목록을 관리하는 예약 작업을 만듭니다. 별도 에이전트가 필요 없습니다. |
| 번호를 따로 쓰기 | 정말 독립된 에이전트가 필요하면 프로필마다 WhatsApp 번호를 따로 붙입니다. Google Voice 같은 서비스의 가상 번호를 쓸 수 있습니다. |
| Telegram · Discord 쓰기 | 이 플랫폼들은 채팅별 묶기가 더 자연스럽습니다. Telegram 그룹이나 Discord 채널마다 자기 세션이 생기고, 같은 계정에서 봇 토큰을 여러 개(프로필마다 하나) 돌릴 수 있습니다. |
성격·맥락 파일은 5장, 예약 작업은 7장. 원문이 가리키는 Profiles, WhatsApp setup 쪽은 이 가이드가 다루지 않습니다.
Telegram 슬래시 명령 100개 한도 — Telegram 에서만 스킬 끄기
상황. Telegram 은 슬래시 명령(/ 로 시작하는 명령)을 100개까지만 받는데, 스킬이 늘어 그 수를 넘습니다. Telegram 에서 필요 없는 스킬을 끄고 싶은데 hermes skills config 설정이 먹히지 않는 것처럼 보입니다.
해결. hermes skills config 로 플랫폼별로 스킬을 끕니다. 그 결과는 config.yaml 에 이렇게 적힙니다.
skills:
disabled: [] # 모든 곳에서 끈 스킬
platform_disabled:
telegram: [skill-a, skill-b] # telegram 에서만 끈 스킬
바꾼 뒤에는 게이트웨이를 다시 시작합니다(hermes gateway restart, 또는 끄고 다시 실행). Telegram 봇의 명령 메뉴는 게이트웨이가 시작할 때 다시 만들어지기 때문입니다.
참고. 설명이 아주 긴 스킬은 전송 크기 제한을 지키려고 Telegram 메뉴에서 40자로 잘립니다. 스킬이 보이지 않는다면 100개 한도가 아니라 전체 전송 크기 문제일 수도 있습니다. 안 쓰는 스킬을 끄면 두 문제에 모두 도움이 됩니다.
여러 사람이 한 스레드에서 하나의 대화를 함께 쓰기
상황. Telegram 이나 Discord 의 한 스레드에서 여러 사람이 봇을 부릅니다. 그 스레드의 모든 부름이 사람별로 따로가 아니라 하나의 공유 대화가 되기를 바랍니다.
지금의 동작. Hermes 는 대부분의 플랫폼에서 사용자 ID 를 기준으로 세션을 만듭니다. 그래서 사람마다 자기만의 대화 맥락을 갖습니다. 개인정보 보호와 맥락 분리를 위해 일부러 그렇게 만든 것입니다.
| 우회 방법 | 내용 |
|---|---|
| Slack 쓰기 | Slack 의 세션은 사용자가 아니라 스레드 기준입니다. 같은 스레드의 여러 사용자가 한 대화를 함께 씁니다. 원문이 가장 잘 맞는다고 꼽는 방법입니다. |
| 그룹 채팅에 운영자 한 명 두기 | 한 사람이 질문을 모아 전하는 역할을 맡으면 세션이 하나로 유지됩니다. 다른 사람들은 읽으며 따라갑니다. |
| Discord 채널 쓰기 | Discord 의 세션은 채널 기준이라 같은 채널의 모든 사용자가 맥락을 함께 씁니다. 공유 대화 전용 채널을 하나 만듭니다. |
그래도 안 풀리면
이 장에 없는 문제라면 원문은 세 군데를 차례로 권합니다. 먼저 찾아보고, 그다음 묻고, 마지막으로 신고합니다.
1. 이미 올라온 문제 찾기
GitHub Issues 에서 같은 문제가 올라와 있는지 검색합니다.
2. 커뮤니티에 묻기
Nous Research Discord 에서 다른 사용자들에게 물어봅니다.
3. 버그 신고하기
새 문제라면 버그로 신고합니다. 아래 네 가지를 꼭 함께 적습니다.
| 신고에 넣을 것 | 알아내는 방법 |
|---|---|
| 운영 체제 (OS) | 내 컴퓨터가 macOS 인지, Linux 인지, Windows(WSL) 인지 |
| Python 버전 | python3 --version |
| Hermes 버전 | hermes --version |
| 오류 문구 전체 | 화면에 나온 오류를 줄이지 말고 처음부터 끝까지 복사합니다. |
받은 원문에는 두 곳의 이름만 있고 주소는 빠져 있습니다. 공식 문서 FAQ 쪽 맨 아래의 링크로 들어갑니다.
- 막히면 먼저 어디에서 막혔는지를 가릅니다 — 설치·실행, 모델·제공자, 긴 대화·속도, 명령 실행, 메신저 봇, 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 버전 · 오류 전문).
출처: hermes-agent.nousresearch.com/docs/reference/faq (수집일 2026-11-09 의 공식 문서)