전체 문서 목록
HERMES AGENT 완전 가이드 · 2026-11-09 수집 문서 기준

Hermes Agent — 쓸수록
스스로 배우는 AI 에이전트

Hermes Agent는 Nous Research가 만든 AI 에이전트(말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)입니다. 공식 문서는 이것을 “배우는 과정이 안에 들어 있는 에이전트”라고 소개합니다. 일을 해 본 경험으로 스킬(일하는 방법을 적은 설명서)을 만들고, 쓰면서 그 스킬을 고치고, 알아 둘 것을 기억에 남기고, 대화를 거듭할수록 내가 어떤 사람인지 더 잘 알게 됩니다.

Nous Research 제작기억 · 스킬로 배움터미널 + 메신저 20곳 이상내장 도구 60개 이상정해 둔 시간에 혼자 실행
아주 쉽게 말하면 보통의 AI 챗봇은 상담 창구와 같습니다. 물으면 답해 주지만, 창구를 떠나면 나를 잊고, 내 컴퓨터의 파일을 만지거나 대신 무언가를 해 주지는 않습니다. Hermes는 곁에 두는 비서에 가깝습니다. 내 컴퓨터(또는 내가 정해 준 다른 컴퓨터)에서 명령을 실행하고 파일을 고치고 웹을 찾아보며, 한 번 해 본 일의 요령은 메모(스킬)로 남겨 다음에 다시 씁니다. 그리고 나에 대해 알게 된 것을 공책(기억)에 적어 두어 다음 대화에서도 이어 갑니다.
이 가이드를 읽는 법 이 가이드는 두 층으로 되어 있습니다. 본문만 읽어도 “무엇이고, 왜 필요하고, 어떻게 쓰는지”를 알 수 있게 썼고, 명령 옵션·설정 값·예외 같은 세부는 🔧 접힌 상자에 넣어 두었습니다. 처음에는 접힌 상자를 건너뛰고, 각 장 맨 위의 🚩 처음이라면 이것만을 따라가세요. 모르는 말은 바로 아래 용어표에서 찾습니다. 더 짧게 보려면 한눈에 보기나 필수판을, 그림으로 먼저 감을 잡으려면 쉬운 설명을, 처음부터 따라 하려면 활용편을 보세요.

먼저 알아 두면 좋은 용어

가이드 전체에서 자주 나오는 말입니다. ⭐ 표시한 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개 더 보기 — 읽다가 모르는 말이 나오면 여기서 찾으세요
용어쉬운 풀이
TUIhermes --tui 로 여는 새 터미널 화면. 기본 CLI와 같은 세션·명령·설정을 씁니다.
슬래시 명령대화 입력 칸에 / 로 시작해 넣는 명령. 예: /help, /model.
토큰AI가 읽고 쓰는 글의 양을 세는 단위. 비용과 속도의 기준이 됩니다.
컨텍스트(문맥 창)모델이 한 번에 기억하며 볼 수 있는 글의 양.
맥락 파일context files. 대화마다 자동으로 읽혀서 Hermes의 행동을 정하는 파일. AGENTS.md, SOUL.md 등.
SOUL.mdHermes의 기본 성격과 말투를 적는 파일.
예약 작업cron. 정해 둔 시간에 Hermes가 혼자 실행하는 일. 결과는 메신저 등으로 받아 볼 수 있습니다.
위임 · 하위 에이전트큰일을 나눠 별도의 에이전트(하위 에이전트)에게 맡기는 것. 여러 일을 동시에 진행할 때 씁니다.
MCPModel Context Protocol. 외부 서비스의 도구를 에이전트에 연결하는 공통 규격. 그 도구를 내주는 프로그램을 MCP 서버라고 합니다.
터미널 백엔드에이전트의 명령이 실제로 실행되는 곳. 내 컴퓨터(local), Docker, SSH로 연결한 다른 컴퓨터 등.
승인위험할 수 있는 명령을 실행하기 전에 Hermes가 나에게 먼저 묻는 것.
체크포인트 · 되돌리기체크포인트는 Hermes가 파일을 바꾸기 전에 자동으로 찍어 두는 스냅샷이고, /rollback 으로 그 시점으로 되돌립니다. 기본은 꺼져 있어서 켜야 찍힙니다.

전체 그림 — 누가 누구에게 말하고, 일은 어디서 일어나나

Hermes를 쓰는 모습을 한 장으로 그리면 아래와 같습니다. 나는 터미널이나 메신저로 말을 겁니다. Hermes는 내가 고른 모델에게 “다음에 무엇을 할지”를 묻고, 도구를 써서 실제로 일을 합니다. 그 과정에서 기억과 스킬을 꺼내 쓰고, 새로 알게 된 것을 다시 적어 둡니다.

🙂 나 터미널 (CLI) hermes 로 시작 메신저 Telegram 등 · 게이트웨이 Hermes Agent 기억 나와 내 환경에 대한 메모 스킬 일하는 방법 설명서 도구 터미널 · 파일 · 웹 검색 … 세션(대화 기록)도 여기에 저장 모델 (두뇌) 내가 고른 제공자의 AI Nous Portal · OpenRouter … 실제 일이 일어나는 곳 내 컴퓨터 · Docker · 서버 (터미널 백엔드) 모델은 “무엇을 할지”를 정하고, 도구는 “실제로” 합니다. 기억과 스킬은 다음 대화에도 남습니다.
말을 거는 곳(터미널·메신저), 생각하는 곳(모델), 일이 일어나는 곳(터미널 백엔드)이 서로 나뉘어 있습니다. 그래서 휴대폰 메신저로 말을 걸고, 일은 다른 컴퓨터에서 시킬 수 있습니다.

공식 문서는 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).

터미널 백엔드 6가지 (기본 내장) local내 컴퓨터 Docker격리된 상자 안 SSH다른 컴퓨터·서버 Daytona쉴 때 잠드는 클라우드 Modal쉴 때 잠드는 클라우드 Vercel Sandbox클라우드 실행 칸 Daytona·Modal: 안 쓸 때는 잠들어 비용이 거의 들지 않음 이 밖에 Singularity 같은 플러그인 백엔드도 있습니다
문서의 예: 월 5달러짜리 서버(VPS), GPU 여러 대를 묶은 클러스터, 쉴 때 비용이 거의 들지 않는 서버리스 환경까지. 고르는 법은 4장 터미널 백엔드.

게이트웨이 하나로 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장에서 자세히 다룹니다.

할 수 있는 일 — 기능 지도

공식 문서의 기능 목록을 다섯 묶음으로 옮겼습니다. 오른쪽 칸은 이 가이드에서 다루는 곳입니다. “다루지 않음”은 이번에 원문을 받지 않은 기능이라 이름과 한 줄 소개만 적었다는 뜻입니다.

핵심도구 · 스킬 · 기억맥락 파일@ 로 파일 끌어오기체크포인트 자동화예약 작업위임코드 실행 · 훅묶음 처리 미디어 · 웹음성 대화 · 부름말브라우저 자동 조작이미지 보기 · 만들기글을 음성으로 연결MCP제공자 고르기 · 예비API 서버편집기 연동(ACP) 꾸미기성격 · SOUL.md화면 색 · 테마플러그인 문서 분류: Core · Automation · Media & Web · Integrations · Customization
처음에는 “핵심” 묶음만 알아도 충분합니다. 나머지는 기본 대화가 잘 된 뒤에 하나씩 더합니다.
묶음기능한 줄 소개 (문서 기준)이 가이드
핵심도구와 툴셋에이전트의 능력을 넓히는 기능들. 플랫폼별로 켜고 끌 수 있는 꾸러미로 묶여 있습니다.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 음성)
연결MCPMCP 서버에 연결해 GitHub·데이터베이스 같은 외부 도구를 씁니다.4장
제공자 경로 정하기어느 제공자가 요청을 처리할지 비용·속도·품질 기준으로 정합니다.다루지 않음
예비 제공자주 모델에 오류가 나면 예비 제공자로 자동 전환합니다.다루지 않음
자격 증명 묶음같은 제공자의 키 여러 개에 요청을 나눠 보냅니다.3장(설정 표)
프롬프트 캐싱Claude 모델용(Anthropic 직접 연결·OpenRouter·Nous Portal)으로, 세션이 달라도 요청의 앞부분을 1시간 동안 캐시(다시 쓰려고 잠시 보관)합니다. 항상 켜져 있고 설정이 필요 없습니다.3장(설정 표)
API 서버Hermes를 다른 채팅 화면 프로그램이 연결할 수 있는 서버로 엽니다.다루지 않음
편집기 연동(ACP)VS Code·Zed·JetBrains 같은 편집기 안에서 Hermes를 씁니다.1장(명령만)
꾸미기성격과 SOUL.mdSOUL.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는 내 대신 진짜 명령을 실행하고 진짜 파일을 고칩니다. 위험할 수 있는 명령은 먼저 묻고(승인), 켜 두면 파일을 바꾸기 전에 되돌릴 지점(체크포인트)도 찍어 주지만, 어디까지 맡길지는 내가 정합니다. 체크포인트는 기본이 꺼져 있습니다. 처음에는 중요하지 않은 폴더에서 시험해 보고, 9장 안전장치를 한 번 읽어 두세요.
한눈에 정리
  • 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의 공식 문서 기준(문서에 버전 표기 없음)

CHAPTER 01

설치와 첫 대화

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

이 장에서 배우는 것
  • 내 목표에 맞는 가장 빠른 시작 길
  • 설치하는 두 가지 방법 — Desktop 패키지와 명령 한 줄
  • 제공자와 모델을 고르는 법, 그리고 모델의 최소 조건(컨텍스트 64K 토큰)
  • 설정이 저장되는 두 파일과, 파일을 직접 열지 않고 값을 넣는 법
  • 첫 대화가 성공했는지 판단하는 네 가지 기준과 이어 하기
  • 잘 안 될 때 보는 표와, 이상할 때 따라가는 복구 순서
처음이라면 이것만
  • 설치하기 — 두 방법 가운데 하나를 골라 hermes 명령이 생기게 합니다.
  • 제공자와 모델 고르기 — 원문이 “가장 중요한 설정 단계”라고 부르는 곳입니다.
  • 첫 대화 — 무엇을 물어보고, 무엇이 보이면 성공인지.
  • 이어 하기 — 방금 한 대화로 돌아올 수 있는지 확인합니다.

나머지는 필요해질 때 읽습니다. 막히면 장 끝의 「자주 겪는 실패」와 「복구 순서」로 갑니다.

어떤 길로 시작할까 — 목표별 가장 빠른 길

Hermes Agent 는 AI 에이전트(말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)입니다. 이후로는 줄여서 Hermes 라고 부릅니다. 빠른 시작 문서는 자신이 이런 사람을 위한 글이라고 밝힙니다.

처음 써 보는 사람

돌아가는 상태까지 가장 짧은 길을 원할 때

제공자를 바꾸려는 사람

설정 실수로 시간을 잃고 싶지 않을 때. 제공자(provider — AI 모델을 빌려주는 서비스)

여럿이 쓰는 구성을 준비하는 사람

팀용, 봇용, 또는 항상 켜 두는 용도로 Hermes 를 차릴 때

“설치는 됐는데 아무것도 안 돼요”

이 상황에 지친 사람

이 장 전체는 아래 다섯 정거장을 차례로 지납니다. 앞의 네 개가 “깨끗한 대화 한 번”을 만드는 일이고, 다섯째는 그 뒤에 골라서 얹는 것입니다.

이 장이 따라가는 순서 ① 설치 hermes 명령이 생김 ② 제공자 고르기 두뇌(모델) 연결 ③ 첫 대화 답이 오는지 확인 ④ 이어 하기 세션이 남는지 확인 ⑤ 다음 층 메신저·예약·스킬 ①~④ — 깨끗한 대화 한 번을 먼저 만듭니다 그 뒤에 골라서
움직이는 점이 가는 순서대로 읽으면 됩니다. ⑤는 ①~④가 된 뒤의 일이라 점선으로 그렸습니다.

목표가 뚜렷하다면 아래 표에서 내 줄을 찾아 그 명령부터 시작합니다. 명령은 모두 터미널(글자로 명령을 입력하는 창)에 입력합니다.

내 목표먼저 할 일그다음
내 컴퓨터에서 일단 돌아가게 하고 싶다hermes setup실제로 대화를 해 보고 답이 오는지 확인합니다
쓸 제공자를 이미 정했다hermes model설정을 저장하고 대화를 시작합니다
봇이나 항상 켜 두는 구성을 원한다CLI(터미널에서 글자로 쓰는 프로그램 화면)가 된 뒤에 hermes gateway setupTelegram, Discord, Slack 같은 플랫폼을 연결합니다
내 컴퓨터나 직접 운영하는 서버의 모델을 쓰고 싶다hermes model → custom endpoint(직접 지정하는 접속 주소)접속 주소, 모델 이름, 컨텍스트 길이를 확인합니다
제공자 여러 곳을 두고 하나가 안 되면 다른 곳으로 넘기고 싶다(multi-provider fallback)먼저 hermes model기본 대화가 된 뒤에만 routing·fallback 설정을 더합니다
원문의 경험칙 — 대화 한 번이 먼저 Hermes 가 평범한 대화 한 번을 끝내지 못한다면 기능을 더 얹지 않습니다. 깨끗한 대화 한 번을 먼저 되게 한 다음에 게이트웨이(메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램), 예약 작업(cron — 정해 둔 시간에 자동 실행), 스킬, 음성, 라우팅을 한 겹씩 올립니다.
영상으로 보고 싶다면 원문은 Onchain AI Garage 의 Masterclass 영상(설치·설정·기본 명령)과 「Hermes Agent Tutorials & Use Cases」 재생 목록을 소개합니다. 받은 원문에 영상 주소가 없어 이 가이드에는 싣지 못했습니다.

설치하기 — 두 가지 방법

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

원문은 스크립트가 의존성 준비를 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 / -Verbosegit, 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, zypperlibatomic1
dnf/yum, apklibatomic
pacmangcc-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)

소스 설치 프로그램은 실제로 서비스를 돌릴 그 사용자로 실행합니다. 홈 폴더, 도구 저장소, 설정, 실행 파일이 모두 그 사용자 소유여야 합니다.

  1. 관리자 계정으로: 소스 빌드 준비물과 Chromium 에 필요한 Linux 라이브러리를 설치합니다(서비스가 내 컴퓨터에서 브라우징할 때만).
  2. 서비스 사용자로: 평소와 같은 설치 명령(curl … install.sh | bash 한 줄)을 실행합니다.
  3. 실행 파일이 있는 폴더를 서비스 사용자의 셸 환경에 더합니다.
    export PATH="$HOME/.local/bin:$PATH"
  4. 그 계정에서 hermes doctor 를 실행합니다. 설치된 wrapper 를 쓰고, venv/bin/hermes 같은 경로를 직접 적어 넣지 않습니다.
  5. 로그아웃해도 살아 있어야 하는 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 는 그 답대로 움직입니다 Hermes 내 컴퓨터에서 돎 손발 — 도구를 써서 일함 제공자 provider — 모델을 빌려주는 서비스 Nous Portal · OpenRouter … 모델 두뇌 — 생각하고 답을 씀 Claude · GPT · Gemini … 질문 질문 답 답 hermes model 로 고릅니다 — 언제든 다시 바꿀 수 있습니다
제공자는 모델로 가는 창구입니다. 창구를 정하고 그 안에서 모델을 고릅니다.

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

hermes model

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

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

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

hermes setup --portal

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

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

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

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

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

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

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

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

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

제공자어떤 곳인가설정 방법
Nous Portal구독형. 따로 설정할 것이 없습니다hermes model 에서 OAuth 로그인
OpenAI CodexChatGPT 또는 Codex 구독으로 Codex 모델을 씁니다hermes model → ChatGPT or Codex Subscription 에서 기기 코드 인증
AnthropicClaude 모델을 직접 씁니다. Max 요금제 + 추가 사용 크레딧(OAuth), 또는 쓴 만큼 내는 API 키hermes model → OAuth 로그인(Max + 추가 크레딧 필요), 또는 Anthropic API 키
OpenRouter여러 제공자의 많은 모델로 이어 줍니다API 키 입력
Custom EndpointVLLM, SGLang, Ollama 등 OpenAI 호환 API 라면 무엇이든접속 주소(base URL) + API 키
모델의 최소 조건 — 컨텍스트 64K 토큰 Hermes 는 컨텍스트(문맥 창 — 모델이 한 번에 기억하며 볼 수 있는 글의 양)가 최소 64,000 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)인 모델이 필요합니다. 그보다 작은 모델은 여러 단계에 걸쳐 도구를 부르는 일에 필요한 작업 기억을 유지하지 못해 시작할 때 거부됩니다. 서비스로 제공되는 모델 대부분(Claude, GPT, Gemini, Qwen, DeepSeek)은 이 조건을 쉽게 넘습니다. 내 컴퓨터에서 직접 모델을 돌린다면 컨텍스트 크기를 64K 이상으로 맞춥니다(예: llama.cpp 는 --ctx-size 65536, Ollama 는 -c 65536).
처음이라면 제공자를 하나 고르고, 바꿔야 할 이유를 알기 전에는 기본값을 그대로 둡니다. 제공자는 hermes model 로 언제든 바꿀 수 있어 한곳에 묶이지 않습니다. 제공자 전체 목록과 환경 변수, 설정 절차는 공식 문서 Providers(AI Providers) 쪽에 있습니다(이 가이드는 다루지 않음).
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 AIOpenAI 호환 모델 API 직접 연결FIREWORKS_API_KEY
Z.AIGLM / Zhipu 가 호스팅하는 모델GLM_API_KEY / ZAI_API_KEY (Z_AI_API_KEY 도 받음)
Kimi / MoonshotMoonshot 이 호스팅하는 코딩·대화 모델KIMI_API_KEY (또는 Kimi-Coding 전용 KIMI_CODING_API_KEY)
Kimi / Moonshot China중국 지역 Moonshot 접속점KIMI_CN_API_KEY
Arcee AITrinity 모델ARCEEAI_API_KEY
GMI Cloud여러 모델 직접 APIGMI_API_KEY
Actual Computer내 하드웨어를 비공개 추론 클러스터로 — 호스팅 relay 또는 로컬 daemonACTUAL_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)
MiniMaxMiniMax 국제 접속점MINIMAX_API_KEY
MiniMax China중국 지역 MiniMax 접속점MINIMAX_CN_API_KEY
Alibaba CloudDashScope 를 통한 Qwen 모델DASHSCOPE_API_KEY (Qwen Coding Plan 은 ALIBABA_CODING_PLAN_API_KEY 도 받음)
Hugging Face통합 라우터로 20개 넘는 공개 모델(Qwen, DeepSeek, Kimi 등)HF_TOKEN
AWS Bedrocknative Converse API 로 Claude, Nova, Llama, DeepSeekIAM role 또는 aws configure (원문은 별도 안내를 가리킴)
Azure FoundryAzure AI Foundry 가 호스팅하는 모델AZURE_FOUNDRY_API_KEY + AZURE_FOUNDRY_BASE_URL
Google AI StudioGemini 모델 직접 APIGOOGLE_API_KEY / GEMINI_API_KEY
xAIGrok 모델 직접 APIXAI_API_KEY
xAI Grok OAuthSuperGrok / Premium+ 구독, API 키 불필요hermes model → xAI Grok OAuth
NovitaAI여러 모델 API 게이트웨이NOVITA_API_KEY
Ramp RouterOpenAI/Anthropic/xAI 등으로 이어 주는 Responses-native LLM 게이트웨이RAMP_ROUTER_API_KEY
Nebius Token FactoryNebius AI 클라우드의 공개 모델NEBIUS_API_KEY
StepFunStep Plan 모델STEPFUN_API_KEY
Xiaomi MiMoXiaomi 가 호스팅하는 모델XIAOMI_API_KEY
Tencent TokenHubTencent 가 호스팅하는 모델TOKENHUB_API_KEY
Tencent TokenPlanAnthropic 방식 접속점으로 쓰는 Tencent Hy 모델TOKENPLAN_API_KEY
Ollama Cloud관리형 Ollama 호스팅 모델OLLAMA_API_KEY
LM StudioOpenAI 호환 API 를 내주는 로컬 데스크톱 앱LM_API_KEY (기본값이 아니면 LM_BASE_URL 도)
Qwen OAuthQwen Portal 브라우저 OAuth — API 키 불필요hermes model → Qwen OAuth
Kilo CodeKiloCode 가 호스팅하는 모델KILOCODE_API_KEY
OpenCode Zen골라 둔 모델을 쓴 만큼 내고 사용OPENCODE_ZEN_API_KEY
OpenCode Go공개 모델용 월 $10 구독OPENCODE_GO_API_KEY
DeepSeekDeepSeek API 직접 사용DEEPSEEK_API_KEY
NVIDIA NIMbuild.nvidia.com 또는 로컬 NIM 의 Nemotron 모델NVIDIA_API_KEY (선택: NVIDIA_BASE_URL)
Vercel AI GatewayVercel AI Gateway 라우팅AI_GATEWAY_API_KEY

설정이 저장되는 두 파일

Hermes 는 비밀 값과 보통 설정을 서로 다른 파일에 나눠 둡니다.

무엇을어디에예
비밀 값과 인증 토큰~/.hermes/.envAPI 키 같은 것. 여기서 토큰은 로그인 증표를 말하며, 글의 양을 세는 토큰과는 다른 뜻입니다
비밀이 아닌 설정~/.hermes/config.yaml쓸 모델 이름, 터미널 백엔드 같은 것

~ 는 내 홈 폴더(내 계정의 개인 폴더)를 뜻합니다. 그 안의 .hermes 폴더가 Hermes 의 데이터 폴더입니다. Windows·Docker·Desktop 꾸러미는 위치가 다르며, 설치하기의 접힌 상자 「설치 위치 표」에 있습니다.

hermes config set … 값 하나를 정하는 명령 자동 분류 비밀 값인가? ~/.hermes/.env 비밀 값 API 키 · 인증 토큰 ~/.hermes/config.yaml 그 밖의 설정 모델 이름 · 터미널 백엔드 …
값을 명령으로 넣으면 어느 파일에 둘지는 Hermes 가 정합니다. 원문 표현으로 “맞는 값이 맞는 파일로 자동으로 갑니다.”

그래서 가장 쉽고 틀리지 않는 방법은 파일을 직접 열지 않고 명령으로 값을 넣는 것입니다. 원문의 예 세 줄과 그 뜻입니다.

명령뜻
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(새 터미널 화면) — 겹쳐 뜨는 창, 마우스로 고르기, 일하는 중에도 막히지 않는 입력

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

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

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

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

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

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

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

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

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

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

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

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

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

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

확인할 것설명
같은 프로필인가프로필(profile — 설정·기억·세션을 따로 쓰는 별도 Hermes 환경)을 바꾼 것이 원인일 수 있습니다.
세션이 실제로 저장됐는가hermes sessions list(세션 목록 보기)로 확인합니다.
왜 지금 확인하나요 원문은 이 확인이 나중에 설정을 여럿 쓰거나 컴퓨터를 여러 대 오갈 때 중요해진다고 적습니다. 세션을 더 다루는 법은 2장 「세션」과 「이어 하기」에서 다룹니다.

핵심 기능 네 가지 맛보기

첫 대화가 됐다면 같은 화면에서 네 가지를 한 번씩 해 봅니다. 모두 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장 「끼어들기」.

다음 층 올리기 — 기본 대화가 된 뒤에만

여기부터는 선택입니다. 원문은 “기본 대화가 된 뒤에만”이라고 못 박고, 필요한 것만 고르라고 합니다.

기본 대화가 된 뒤에, 필요한 것만 골라 올립니다 음성/voice on · Ctrl+B MCP 서버config.yaml 에 추가 편집기 연동 (ACP)hermes acp 메신저 봇hermes gateway setup 도구 · 스킬 · 예약 작업hermes tools · hermes skills 격리된 터미널Docker · 원격 서버(SSH) 기본 대화 — 설치 · 제공자 · 첫 대화 · 이어 하기 이것이 먼저 깨끗하게 되어야 합니다
위 여섯 칸은 필요한 것만 고릅니다. 예약 작업만은 봇이나 CLI 구성이 안정된 뒤에 쓰라고 원문이 조건을 답니다.
hermes gateway setup    # Interactive platform configuration

뜻: 질문에 답하며 메신저 플랫폼 연결을 설정합니다.

게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)로 Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant(플러그인), Microsoft Teams 를 연결합니다. 봇으로 쓰거나 여럿이 함께 쓰는 비서로 만들 때 필요합니다. → 8장

무엇하는 일자세히
hermes tools플랫폼별로 어떤 도구를 쓰게 할지 조절합니다4장
hermes skills다시 쓸 수 있는 작업 방법을 둘러보고 설치합니다6장
Cron예약 작업(정해 둔 시간에 자동 실행). 봇이나 CLI 구성이 안정된 뒤에만7장

스킬(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 으로 고쳐지지 않습니다. 폴더가 있는지만 보는 검사라서, 의도한 저장소가 연결됐다는 보증은 아닙니다.

복구 순서 — 이상하면 이 순서로

어디가 틀렸는지 감이 안 올 때는 고민하지 말고 정해진 순서대로 여섯 명령을 돌립니다. 원문은 이 순서가 “뭔가 이상한 느낌”에서 “상태를 아는 지점”으로 빨리 돌아오게 해 준다고 적습니다.

이상하면 ①부터 차례로 1 hermes doctor무엇이 빠졌는지 진단 2 hermes model제공자·모델·인증 다시 확인 3 hermes setup설정 마법사 전체를 다시 4 hermes sessions list세션이 저장됐는지 확인 5 hermes --continue마지막 세션으로 돌아가기 6 hermes gateway status메신저 연결 상태 확인
노란 고리가 지나가는 순서대로 실행합니다. 윗줄은 “대화가 되는가”, 아랫줄은 “세션과 메신저가 살아 있는가”를 봅니다.
업데이트는 누가 맡나 — 설치 방식 자동 감지 (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 의 공식 문서(문서에 버전 표기 없음)

CHAPTER 02

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

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

이 장에서 배우는 것
  • hermes 로 대화 화면을 여는 법과, 한 번만 묻고 끝내는 법
  • 화면의 배너·대화·입력 칸·상태 줄이 각각 무엇을 알려 주는지
  • 슬래시 명령과 꼭 필요한 단축키, 여러 줄로 입력하는 법
  • Hermes 가 일하는 도중에 말을 걸어 방향을 바꾸거나 멈추는 법
  • 세션이 무엇이고, 어떻게 이어 하고·이름 붙이고·찾는지
  • 백그라운드 세션, 저장 위치, 오래된 세션을 정리하는 규칙
처음이라면 이것만

나머지 소절은 필요할 때 찾아보면 됩니다. 점선 상자(개발자용 참고)는 모두 건너뛰어도 됩니다.

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

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

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

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

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

입력뜻
hermes대화형 세션을 시작합니다(기본).
hermes chat -q "Hello"한 번만 묻고 답을 받은 뒤 끝냅니다.
hermes chat --model "anthropic/claude-sonnet-4"쓸 모델을 정해서 엽니다.
hermes chat --provider nous제공자를 정해서 엽니다(nous = Nous Portal, openrouter = OpenRouter).
hermes chat --toolsets "web,terminal,skills"쓸 툴셋을 정해서 엽니다(4장).
hermes --continue가장 최근 세션(대화 한 묶음)을 이어 합니다(이어 하기).
시작 옵션은 그 세션에 고정됩니다 작업 폴더와 --model·--provider·--toolsets 같은 시작 옵션은 세션을 만들 때 그 세션에 고정됩니다. 이어 하기를 하면서 다른 값으로 바꿀 수는 없습니다. 대화 도중에 모델을 바꾸려면 슬래시 명령 /model 을 씁니다.
새 화면 TUI 도 있습니다 Hermes 에는 hermes --tui 로 여는 TUI(새 터미널 화면)도 들어 있습니다. 원문은 겹쳐 뜨는 창, 마우스로 고르기, 입력을 막지 않는 화면을 갖췄다고만 소개하고 공식 문서 TUI 쪽을 가리킵니다(이 가이드는 다루지 않음). 이 장은 hermes 로 여는 기본 화면(원문 표현으로 classic CLI)을 기준으로 설명합니다.
시작 옵션 더 보기 — 파일로 질문 넘기기·스킬 미리 불러오기·자세한 출력
옵션 (원문 그대로)뜻
hermes chat --query-file prompt.txt
hermes chat --query-file - < prompt.txt
질문을 파일이나 표준 입력에서 읽습니다. 셸이 해석하지 않아 따옴표·$(...)·백틱도 글자 그대로 갑니다.
hermes chat -s hermes-agent-dev,github-auth스킬을 미리 불러와 시작합니다(-s 를 여러 번 써도 됨). 대화형·한 번 묻기 모두.
skills.auto_load
(config.yaml 의 목록)
적어 둔 스킬을 CLI·TUI·게이트웨이·예약 작업·API 의 모든 새 세션에 불러옵니다. 세션 시작 때 한 번만 읽으므로 고치면 다음 세션부터 적용되고, 없거나 꺼진 스킬은 경고 뒤 건너뜁니다.
--ignore-rules
HERMES_IGNORE_RULES=1
자동 불러오기와 AGENTS.md·SOUL.md·.cursorrules·기억 주입을 건너뜁니다. -s 로 적은 스킬은 불러옵니다. 프로필마다 따로입니다.
hermes chat --verbose디버그용 자세한 출력. 기본은 조용한 모드(quiet mode) — 도구의 장황한 기록을 숨기고 움직이는 표시로 깔끔하게 보여 줍니다.
hermes -w
hermes -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 가 한 일·답이 차례로 쌓이고, 맨 아래에는 항상 같은 자리에 입력 칸이 있습니다.

☤ 환영 배너모델 · 터미널 백엔드 · 작업 폴더 · 도구 · 스킬 ❯ 내 메시지 📖 Read … 🔧 Patch … (Hermes 가 쓴 도구) ☤ Hermes 의 답 ─ 이번 턴 요약: 걸린 시간 · 고친 파일 · 읽은 파일 … 대화가 아래로 계속 쌓입니다 지금 하는 일 · 걸린 시간세션 제목 ❯ 모델 · ctx 4% · 작업 폴더지금 쓸 수 있는 키 ① 환영 배너지금 무엇으로 일하는지 ② 대화 영역내 말 · 도구 사용 · 답 · 요약 ③ 진행 표시줄일하는 중에 움직입니다 ④ 입력 칸 — 여기에 씁니다 ⑤ 상태 줄모델 · 남은 여유 · 쓸 수 있는 키
기본 화면(modern)의 약도. 원문의 화면 그림은 글로 옮겨지지 않아, 원문의 설명과 예시 출력을 바탕으로 자리만 나타냈습니다.

화면을 그리는 방식은 두 가지이고, 설정 display.cli_layout 으로 고릅니다. 기본값은 modern 입니다.

모든 내용을 기호 하나로 시작하는 평범한 줄로 찍습니다. 창 너비에 기대지 않으므로 창 크기를 바꿔도 앞선 출력이 깨지지 않습니다. 진행 표시는 입력 칸 바로 위 줄에, 상태 줄은 입력 칸 아래에 있습니다.

hermes — 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 으로 두면 생각과 답을 상자로 둘러 보여 주고, 상태 막대가 입력 칸 위에 놓입니다. 환영 배너는 두 방식이 같습니다.

classic 화면의 상태 막대 (원문 예시)
 ☤ claude-sonnet-4-20250514 │ 12.4K/200K │ [██████░░░░] 6% │ $0.06 │ 15m

상태 줄 읽기. 상태 줄(classic 에서는 상태 막대)은 실시간으로 바뀌며, 가장 눈여겨볼 것은 컨텍스트(문맥 창 — 모델이 한 번에 기억하며 볼 수 있는 글의 양)가 얼마나 찼는지입니다. 12.4K/200K 는 최대 200K 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위) 가운데 12.4K 를 썼다는 뜻입니다. 막대 색은 찬 정도에 따라 바뀝니다.

☤ claude-sonnet-4-20250514│ 12.4K/200K│ [██████░░░░] 6%│ $0.06│ 15m 모델 이름 쓴 토큰 / 최대 컨텍스트 채움 막대 예상 비용 지난 시간 컨텍스트 막대의 색 초록 · 50% 미만여유가 많음 노랑 · 50–80%차는 중 주황 · 80–95%한계에 가까움 빨강 · 95% 이상 넘치기 직전 — /compress 를 고려
위: 상태 막대의 칸(원문 예시). 아래: 대화가 길어질수록 동그라미가 오른쪽으로 갑니다. 빨강이 되면 /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_layoutmodern(기본) 또는 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 browseSkills Hub 와 공식 선택 스킬을 둘러봅니다(6장).
/reasoning high생각을 더 깊이 하도록 올립니다.

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

① 기본 명령

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

② 스킬 명령

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

③ 빠른 명령

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

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

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

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

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

전체 목록은 공식 문서 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+ECtrl+G 와 같은 외부 편집기 열기.
Ctrl+S쓰던 초안을 잠시 치워 두고 입력 칸을 비웁니다. 빈 입력 칸에서 다시 누르면 되돌아옵니다. 여러 번 누르면 쌓이고, 둘 이상이면 고르는 패널이 열립니다(Enter 되살림, D 버림). 초안은 디스크에 쓰지 않고 그 세션의 메모리에만 둡니다.
Esc Esc (자세히)빈 입력 칸에서 두 번 누르면 세션의 모든 질문(›)과 답(•)을 보여 주는 화면이 열립니다. ←/→ 로 질문을 고르고 Enter 로 입력 칸에 되돌립니다. 고쳐 보내면 세션이 그 질문 직전으로 잘리며, 보내기 전에는 아무것도 지워지지 않습니다. f 는 원래 세션을 둔 채 그 지점에서 새 세션을 갈라 냅니다.
Ctrl+T / F6하위 에이전트(일을 나눠 받은 별도 에이전트)와 백그라운드 프로세스를 보는 전체 화면 모니터(7장). Enter 최근 기록, s 방향 지시, x 중지 요청.
Ctrl+R / F7상태 막대 위의 작업 현황 칸을 여러 줄 ↔ 한 줄로. 걸어 둔 /goal 과 /queue 에 줄 선 메시지도 여기 보입니다.
Ctrl+D (자세히)글이 있으면 커서 아래 글자를 지웁니다. 턴 도중에 나가면 게이트웨이가 턴을 끝내고, 그 사이 승인·되묻는 질문이 나오면 제한 시간까지 또는 내가 돌아올 때까지 기다립니다.
Ctrl+ZHermes 를 잠시 뒤로 보냅니다(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. 합을 돌려준다”

macOS 기본 터미널에서는 Shift+Enter 가 안 됩니다 대부분의 터미널은 Enter 와 Shift+Enter 를 같은 신호로 보내서 프로그램이 둘을 구분할 수 없습니다. 원문 표에 따르면 macOS 의 Terminal.app 과 Windows Terminal(안정판)은 지원하지 않습니다. 이럴 때는 Alt+Enter 나 Ctrl+J 를 쓰세요. 아주 긴 글은 Ctrl+G 로 편집기에서 쓰는 편이 편합니다.
터미널별 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 (기본)지금 방향을 바꿉니다 일하는 중 내 말을 반영해 다시 진행 queue끝난 뒤 다음 차례로 일하는 중… 끝까지 마침 줄 서서 기다림 다음 턴: 내 메시지 steer멈추지 않고 전달 일하는 중… 계속 진행 다음 도구 호출이 끝난 뒤 내 말이 전달됨
세로 점선이 내가 Enter 를 누른 순간입니다. 방식에 따라 내 메시지가 언제 Hermes 에게 닿는지가 달라집니다.
방식Enter 를 누르면바꾸는 명령
interrupt (기본)지금 턴이 내 말을 반영해 다시 진행합니다. 오래 걸리는 터미널 명령(빌드 등)이 돌고 있었다면 죽이지 않고 뒤로 보내고(끝나면 알림), 내 메시지를 바로 읽습니다. 다른 도구는 먼저 끝냅니다./busy interrupt
queueHermes 가 지금 일을 끝낸 뒤 다음 턴으로 실행합니다./busy queue
steer끊지도, 새 턴을 만들지도 않고 지금 실행에 끼워 넣습니다. 다음 도구 호출 뒤에 Hermes 에게 닿습니다./busy steer

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

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

하고 싶은 것방법결과
방향만 바꾸기새 메시지 + Enter지금 턴이 내 말을 반영합니다.
이번 일 그만두기빈 입력 칸에서 Ctrl+C, 또는 /stop하던 일을 멈춥니다. 대화 화면은 그대로입니다.
화면에서 나가기Ctrl+DHermes 화면을 닫습니다. 돌고 있던 턴은 취소되지 않고 끝까지 진행되며, 나중에 hermes --resume 으로 답을 볼 수 있습니다.
강제로 끝내기Ctrl+C 를 2초 안에 두 번강제 종료.
바쁠 때 입력 방식의 설정·예외, 대기 줄, 잠시 뒤로 보내기(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 는 대화가 시작되면 새 공책을 꺼내 오간 말을 모두 적고, 책장 한 곳에 꽂아 둡니다. 공책에 제목을 붙여 두면 나중에 꺼내기 쉽고, 꺼낸 공책 뒤에 이어서 쓸 수도 있습니다.
CLI터미널에서 한 대화 메신저Telegram · Discord · Slack … 그 밖예약 작업 · API … state.db~/.hermes/state.db — 모든 세션이 여기에 📓 refactoring auth 📓 my project #3 📓 (제목 없는 세션) 이어 하기hermes -c 찾기목록 · 검색 관리이름 · 내보내기 · 정리
어디서 한 대화든 내 컴퓨터의 한 파일(~/.hermes/state.db, ~ 는 내 홈 폴더)에 세션으로 쌓입니다. 예약 작업은 정해 둔 시간에 Hermes 가 혼자 실행하는 일입니다(7장).

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

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

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

일이 끝나면 /new 로 끊어 주세요 원문은 일이나 주제가 끝날 때마다 /new 로 새 세션을 시작하라고 권합니다. ① 기억(memory — 세션이 끝나도 남는 메모)은 세션이 시작될 때 불러오고 끝날 때 정리해 저장하므로, 끝나지 않는 세션에서는 “스스로 배우는” 장치가 거의 돌지 않습니다(5장). ② 대화가 길수록 매 턴 실어 보내는 앞부분이 커져 비용이 늡니다. 끊기 전에 “기억해 둘 만한 것은 기억해 줘” 하고 말해 두면 도움이 됩니다. 컴퓨터나 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)를 다시 시작하는 것은 끊는 것이 아닙니다 — 같은 세션이 이어집니다.
저장된 기록이 전부 매번 모델에게 가는 것은 아닙니다 매 턴 모델이 보는 것은 시스템 프롬프트, 지금 대화 창, 그 턴에 Hermes 가 일부러 넣는 내용입니다. 컨텍스트를 빨리 채우는 것은 그림 파일이 아니라 장황한 글(통째로 붙인 로그, 큰 도구 출력, 긴 변경 내역)이니, 큰 자료는 요약·파일 경로·필요한 부분만 주는 편이 좋습니다.
세션 출처(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 DMagent:main:telegram:dm:<chat_id>DM 대화방마다 세션 하나
WhatsApp DMagent: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"
세션에 이름을 붙여 두었을 때.
세션 IDhermes --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 는 이어지는 새 세션을 만듭니다. 원래 세션에 제목이 있었다면 새 세션에는 번호가 붙은 제목이 자동으로 달립니다. 이름으로 이어 하면 그 줄기에서 가장 최근 것을 골라 줍니다.

my project 압축 my project #2 압축 my project #3 hermes -c "my project"→ 가장 최근인 #3 을 엽니다 앞의 세션들도 지워지지 않고 남아 있습니다
압축이 일어날 때마다 제목에 번호가 붙은 새 세션으로 이어집니다. 압축 자체는 3장에서 다룹니다.
제목의 세부 규칙
  • 첫 메시지 전에 /title 을 쓰면 기다렸다가 세션이 시작될 때 적용됩니다.
  • hermes sessions rename 은 여러 단어 제목에 따옴표가 없어도 됩니다.
  • /title 은 메신저(Telegram·Discord·Slack·WhatsApp)에서도 됩니다. /title 만 넣으면 지금 제목을 보여 줍니다.

지난 대화를 찾는 길은 둘입니다. 내가 목록에서 찾는 것과, Hermes 가 지난 대화를 검색해 떠올리는 것입니다.

① 내가 찾기. 터미널에서 hermes sessions list 를 입력하면 최근 세션 20개가 제목·첫 마디·마지막 사용 시각·ID 와 함께 나옵니다. 대화 화면 안에서는 /sessions 로 고르기 화면을 엽니다.

hermes sessions list (원문 예시)
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 를 넣었을 때와 결과가 왔을 때 (원문 예시)
❯ /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 …다른 질문 · 다른 일 · 또 다른 /bg결과 상자 도착 백그라운드 #1따로 일함 받은 지시문 하나만 가지고 일함
백그라운드 세션은 지금 대화의 내용을 모릅니다. 그래서 /bg 뒤의 지시문에 필요한 것을 모두 적어야 합니다.

대화가 분리됩니다

백그라운드 에이전트는 지금 세션의 대화 기록을 모릅니다. 내가 준 지시문만 받습니다.

설정은 같습니다

지금 세션의 모델, 제공자, 툴셋, 생각 깊이 설정, 예비 모델을 물려받습니다.

기다리지 않습니다

앞의 대화는 그대로 쓸 수 있습니다. 대화하고, 명령을 실행하고, 백그라운드 작업을 더 띄워도 됩니다.

여러 개를 동시에

작업마다 번호가 붙습니다. 서로 다른 방향을 한꺼번에 조사시킬 수 있습니다.

원문이 드는 쓰임새는 오래 걸리는 조사, 파일 묶음 분석(“이 저장소의 Python 파일을 모두 살펴 보안 문제를 찾아 줘”), 여러 갈래 동시 조사입니다. 작업이 실패하면 결과 대신 오류 알림이 나옵니다.

알아 둘 점 백그라운드 세션은 내 대화 기록에 나타나지 않는, 자기 작업 ID(예: 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 한 파일. 공유·둘러보기용.
traceClaude 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|walstate.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)

CHAPTER 03

설정 — 파일 · 모델 · 한도

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

이 장에서 배우는 것
  • ~/.hermes/ 폴더 안에 무엇이 있고, config.yaml 과 .env 가 어떻게 다른지
  • hermes config 명령으로 설정을 보고, 바꾸고, 되돌리는 방법
  • 같은 설정이 여러 곳에 있을 때 어떤 값이 쓰이는지(우선순위)
  • 파일 읽기·도구 출력·반복 횟수에 걸린 한도와, 대화가 길어질 때 일어나는 압축
  • 곁가지 일을 맡는 보조 모델, 화면에 보이는 정보의 양, 명령이 실제로 실행되는 곳(터미널 백엔드)
처음이라면 이것만

나머지 소절은 필요해질 때 찾아 읽어도 됩니다.

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

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

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

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

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

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

직접 고치지 않는 가장 쉬운 길 원문은 가장 쉬운 길로 hermes setup --portal 을 듭니다. 로그인 한 번으로 모델 제공자와 Tool Gateway 의 도구 네 가지가 연결되어 YAML 을 손으로 고칠 필요가 없고, Nous Portal 구독자는 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위) 단위로 요금을 매기는 제공자에서 10% 할인도 받는다고 합니다. Nous Portal 자체는 공식 문서 Nous Portal 쪽 참고(이 가이드는 다루지 않음).
config.yaml 을 잘못 고쳐 깨뜨렸다면 Hermes 는 내장 기본값으로 돌아가지 않고 가장 최근의 멀쩡한 사본으로 대신 동작하며, YAML 을 고칠 때까지 시작할 때마다 경고합니다. 깨진 파일 자체는 건드리지 않으므로, 천천히 열어 고치면 됩니다.
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 editconfig.yaml 을 편집기로 엽니다
hermes config get KEY그 설정이 실제로 어떤 값으로 쓰이는지 출력합니다
hermes config set KEY VAL설정 하나를 정합니다
hermes config unset KEY내가 정한 값을 지웁니다
hermes config check빠진 옵션과 오래되어 맞지 않는 저장된 선택을 점검합니다
hermes config migrate빠진 옵션을 하나씩 물어 가며 채웁니다

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

1. 지금 값 보기

hermes config get model

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

2. 값 바꾸기

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

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

3. 비밀 값 넣기

hermes config set OPENROUTER_API_KEY sk-or-...

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

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

hermes config unset terminal.backend
hermes config check

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

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

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

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

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

명령무엇을 정하나
hermes model주 모델과 제공자. 메뉴의 “Configure auxiliary models”(보조 모델 설정)로 보조 모델도 고릅니다
hermes tools도구(tool — 에이전트가 쓰는 기능 하나)와 툴셋 켜고 끄기, 웹 검색·브라우저 서비스 고르기 (4장)
hermes doctor바꾸지는 않고 진단만 합니다 — 잘못 적은 시간대, 연결되지 않는 보조 모델 설정 등
대화 중 슬래시 명령(대화 입력 칸에 / 로 시작해 넣는 명령)/reasoning high --global, /fast fast --global 처럼 --global 을 붙이면 config.yaml 에 저장되고, 붙이지 않으면 이번 세션에만 적용됩니다
hermes 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_blocklist30초 안에 반영
webapp.enabled게이트웨이를 다시 켠 뒤 (hermes gateway restart)

어떤 값이 이기나 — 우선순위

같은 설정이 여러 곳에 적혀 있으면 Hermes 는 정해진 순서로 찾아 먼저 발견한 값을 씁니다. 원문의 순서는 네 단계이고, 위에 있을수록 이깁니다.

먼저 봄 (이김) 나중에 봄 ① 명령에 붙인 옵션 (CLI arguments) 예: hermes chat --model anthropic/claude-sonnet-4 — 이번 실행에만 적용 ② ~/.hermes/config.yaml 비밀이 아닌 모든 설정의 기본 자리 ③ ~/.hermes/.env 환경 변수의 대비용 자리 — 비밀 값(API 키·토큰·비밀번호)은 반드시 여기 ④ 내장 기본값 아무것도 정하지 않았을 때 쓰는, 프로그램에 들어 있는 안전한 값
점이 내려가는 순서대로 찾습니다. 위 단계에 값이 있으면 아래 단계는 보지 않습니다.
상황쓰이는 값
config.yaml 에 모델이 정해져 있는데, 실행할 때 --model 로 다른 모델을 붙임--model 로 붙인 모델. 단, 그 실행 한 번에만
비밀이 아닌 설정이 config.yaml 과 .env 양쪽에 있음config.yaml 의 값
API 키·봇 토큰·비밀번호.env 에 둡니다 (비밀 값은 .env 가 필수)

그래서 평소에는 config.yaml 만 고치면 되고, “이번 한 번만 다르게” 하고 싶을 때 명령에 옵션을 붙입니다. config.yaml 안에서는 ${이름} 꼴로 환경 변수의 값을 불러 쓸 수도 있습니다. 예를 들어 API 키 자리에 ${GOOGLE_API_KEY} 라고 적으면 그 이름의 값이 들어갑니다.

회사에서 나눠 준 Hermes 라면 원문에 따르면 관리자는 시스템 수준의 관리 폴더를 통해 특정 설정과 비밀 값을 고정해 둘 수 있고, 일반 사용자는 그 값을 바꿀 수 없습니다. 값을 바꿔도 반영되지 않으면 관리자에게 물어봅니다. 자세한 내용은 공식 문서 Managed Scope 쪽 참고(이 가이드는 다루지 않음).
${이름} 으로 환경 변수 불러 쓰기 — 세부 규칙
  • 한 값에 여러 개를 쓸 수 있습니다: url: "${HOST}:${PORT}".
  • 그 이름의 환경 변수가 없으면 글자가 그대로 남고 경고가 기록됩니다. 중괄호 없는 $VAR 은 바꿔 넣지 않습니다.
  • ${env:VAR_NAME} 도 똑같이 처리됩니다. ${file:...}, ${vault:...} 같은 다른 출처는 그 자리에서 풀리지 않습니다.
  • 프로필 여러 개를 한 게이트웨이가 함께 맡으면, 각 프로필의 config.yaml 은 그 프로필의 .env 를 기준으로 풀립니다.
환경 변수가 설정값보다 앞선다고 따로 적힌 곳

일반 규칙은 위 네 단계이지만, 원문의 개별 설정 절은 몇몇 환경 변수가 config.yaml 값을 덮어쓴다고 따로 적습니다.

환경 변수덮어쓰는 설정
TERMINAL_<대문자 키>terminal: 아래의 모든 키 (예: TERMINAL_TIMEOUT → terminal.timeout)
HERMES_TIMEZONEtimezone
HERMES_LANGUAGEdisplay.language (세션 단위)

반대로 providers.<id>.request_timeout_seconds 는 옛 환경 변수 HERMES_API_TIMEOUT 보다 앞섭니다.

꼭 알아 둘 한도

모델이 한 번에 기억하며 볼 수 있는 글의 양을 컨텍스트(context — 문맥 창)라고 합니다. 컨텍스트는 정해져 있고, 읽고 쓰는 글은 곧 비용입니다. 그래서 Hermes 는 큰 파일 하나나 긴 명령 출력 하나가 컨텍스트를 통째로 차지하지 못하게 곳곳에 한도를 둡니다. 기본값 그대로 써도 되고, 한도 때문에 일이 끊길 때만 조정합니다.

터미널 명령의 출력이 한도(기본 50,000자)를 넘으면 원래 출력 — 아주 깁니다 앞부분 40% 남김 [OUTPUT TRUNCATED] 뒷부분 60% 남김 가운데는 잘라 내고, 잘랐다는 표시를 넣어 모델이 알 수 있게 합니다
잘린 사실을 숨기지 않습니다 — 모델은 표시를 보고 출력이 다 오지 않았음을 압니다.
무엇의 한도설정 이름 · 기본값넘으면
파일 한 번 읽기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_turnsnone양의 정수면 그 횟수로 제한. "none"·"unlimited"·0·-1 등은 무제한. 원문은 같은 절 첫 문단에서 “기본 500”이라고도 적어 두 설명이 엇갈립니다
agent.api_max_retries3대체 제공자로 넘어가기 전 재시도 횟수. 빨리 넘기고 싶으면 0
agent.auto_recovery_cycles5재시도와 대체 제공자를 다 쓴 뒤 기다렸다 다시 하는 횟수(대기 15/30/60/60/60초). 인증·요금·정책 오류에는 쓰이지 않음. 0이면 끔
tool_loop_guardrails.warn_after2 / 3 / 2똑같은 실패 호출 · 같은 도구 실패 · 진전 없는 같은 결과가 이만큼 이어지면 경고
tool_loop_guardrails.hard_stop_after5 / 8 / 5강제 중단 기준. hard_stop_enabled(기본 false)를 켜면 모든 곳에서, 꺼 두어도 게이트웨이·예약 작업에서는 적용
tool_loop_guardrails.loop_caps50 / 50max_web_searches · max_subagents. 0이면 그 상한을 끔
agent.stall_guardstrue똑같은 호출·결과가 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)이며, 기본으로 켜져 있어 따로 할 일은 없습니다.

아주 쉽게 말하면 회의가 세 시간째 이어진다고 해 보세요. 처음부터 한 말을 전부 기억하며 이야기할 수는 없으니, 앞부분은 회의록 요약으로 바꾸고 방금 나눈 이야기만 그대로 둡니다. 회의의 목적(맨 처음 한 말)은 잊지 않도록 따로 적어 둡니다.
압축 시작선 — 한도의 50% 컨텍스트 한도 안내 알림 경고 알림 압축 전 기본 지시문system prompt 처음 메시지3개 오래된 대화길고, 대부분 지금은 덜 중요 최근 대화그대로 둠 압축 후 기본 지시문언제나 보존 처음 메시지고정 요약모델이 따로 작성 최근 대화그대로 오래된 대화만 요약으로 줄어듭니다 — 처음 목표와 방금 한 이야기는 남습니다
위 막대가 시작선에 닿으면 압축이 일어나 다시 줄어듭니다. 아래는 그때 대화가 어떻게 재구성되는지입니다.
기본 동작설정 · 기본값뜻
자동 압축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(터미널에서 글자로 쓰는 프로그램 화면)에서는 도구 진행 표시 사이에 아래 같은 막대로, 메신저에서는 글 한 줄로 옵니다. 이 알림은 사람에게만 보이며 모델에게 가는 대화에는 아무것도 넣지 않습니다.

CLI — 압축까지 남은 거리 (원문 예시)
  ◐ context ████████████░░░░░░░░ 62% to compaction  48k threshold (50%) · approaching compaction

뜻: “압축 시작선까지 62% 왔습니다. 시작선은 48k 토큰(한도의 50%)이고, 압축이 다가옵니다.”

  • 직접 압축하기. 기다리지 않고 지금 줄이고 싶으면 대화 중 /compress 를 씁니다.
  • 메신저에서는 조용히. 자동 압축은 메신저 대화에서 진행 과정을 알리지 않고 뒤에서 일어납니다(실패 알림은 항상 보임).
  • 요약은 누가 쓰나. 요약은 주 대화와 별개의 모델 호출입니다. 기본은 주 모델이 쓰고, 더 싼 모델에 맡길 수도 있습니다 — 다음 소절의 보조 모델 auxiliary.compression 입니다.
요약 모델을 바꿀 때 한 가지 요약 모델의 컨텍스트는 주 모델의 컨텍스트 이상이어야 합니다. 더 작으면 요약 호출이 길이 오류로 실패하고, 그때는 대화 가운데 부분이 요약 없이 그냥 빠져 맥락을 조용히 잃습니다.
compression 설정 전체 — 키 · 기본값 · 뜻

모든 압축 설정은 config.yaml 에만 있습니다(환경 변수 없음).

키기본값뜻
threshold_tokensnull토큰 수로 정하는 시작선. 정하면 비율 기준과 이 값 중 낮은 쪽에서 시작
target_ratio · tail_mode0.20 · lean최근 대화를 남기는 양과 방식. lean 은 한도의 2.5%(10K~25K 토큰)만 남기고 요약에 자세한 세션 기록을 넣음. legacy 는 0.20×threshold 를 그대로 남김
protect_first_n · in_place3 · true0 이면 처음 메시지를 고정하지 않음 / false 면 압축할 때마다 새 세션 id 로 넘어가는 옛 방식
progress_noticesfalse메신저에 압축 진행 알림을 보냄
idle_compact_after_seconds0이 시간(초) 넘게 쉬었다 돌아온 세션은 첫 답 전에 미리 압축. 예: 1800 = 30분
prepare_aheadfalse시작선이 가까워지면 다음 요약을 미리 써 둠
proactive_prune_tokens0모델 호출 없이 오래된 큰 도구 결과만 줄이는 기능의 시작 토큰 수(원문 예 48000)
context_timeout_seconds · context_total_ceiling_seconds120 · 600대화 중 압축에서 요약 모델이 아무 출력 없이 버틸 수 있는 시간 / 출력이 나오고 있어도 넘지 못하는 총 대기 상한
hygiene_hard_message_limit5000게이트웨이 전용 안전판 — 메시지 개수가 이 값을 넘으면 강제 압축
hygiene_timeout_seconds · hygiene_total_ceiling_seconds30 · 600게이트웨이의 사전 압축에 적용되는 같은 두 가지 시간
hygiene_max_turn_hold_seconds10들어온 메시지가 압축을 기다려 주는 최대 시간. 넘으면 압축 없이 먼저 답하고 요약은 나중에 반영
hygiene_failure_cooldown_seconds300압축 실패 뒤 다시 시도하기까지 쉬는 시간의 첫 단계(1배 → 3배 → 9배, 최대 1시간)

요약 모델의 두 가지 제한 시간. auxiliary.compression.timeout(기본 120초)은 요청 전체의 시간, auxiliary.compression.no_progress_timeout(기본 60초)은 요약이 흘러나오다 멈춘 채 버틸 수 있는 시간입니다. 둘은 따로 움직여서 timeout 만 600으로 늘려도 60초 동안 출력이 없으면 중단됩니다.

보조 모델 — 곁가지 일을 맡는 모델

Hermes 는 내가 대화하는 주 모델 말고도, 곁가지 일에 모델을 한 번씩 더 부릅니다. 이미지 분석, 브라우저 화면 분석, 세션 제목 짓기, 컨텍스트 압축 요약 같은 일입니다. 이런 일을 맡는 자리를 보조 모델(auxiliary model)이라고 합니다.

주 모델 내가 대화하는 모델 기본값 auto 따로 정하지 않으면 곁가지 일도 주 모델이 맡음 vision이미지·브라우저 화면 분석 title_generation세션 제목 자동으로 짓기 compression컨텍스트 압축 요약 쓰기 approval위험해 보이는 명령인지 판단
오른쪽 자리마다 다른 모델을 앉힐 수 있습니다. 비워 두면 모두 주 모델이 맡습니다.

처음에는 아무것도 하지 않아도 됩니다. 기본값 auto 는 곁가지 일을 모두 hermes model 로 고른 주 모델에 보냅니다. 다만 원문은 주 모델이 비싼 추론 모델이면 곁가지 일의 비용도 눈에 띄게 붙는다고 알려 줍니다. 그럴 때 곁가지 일만 싸고 빠른 모델로 돌립니다.

가장 쉬운 방법은 hermes model 을 실행해 메뉴에서 “Configure auxiliary models”를 고르는 것입니다. 작업별 목록이 나옵니다.

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 · mcpGemini 3.1 TTS 용 숨은 음성 태그 넣기 · MCP 도구 전달30초
triage_specifierKanban 에서 한 줄짜리 일을 구체적인 명세로 풀어 쓰기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 묶음에서 정합니다. 화면 표시 설정은 보이는 것만 바꿀 뿐, 모델에게 가는 대화 내용은 바꾸지 않습니다.

off 조용히 최종 답만 보여 줌 new 도구가 바뀔 때만 표시 all (기본값) 도구 호출마다 짧은 미리보기 verbose 인자·결과·디버그 기록 전부 적게 보임 많이 보임
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_commandall · false진행 표시 단계(off | new | all | verbose) / 메신저에서 /verbose 쓰기
focus_viewfalse집중 보기(/focus)
platforms{}메신저별 표시 설정. 예: hermes config set display.platforms.telegram.streaming false
interim_assistant_messages · show_commentarytrue게이트웨이: 턴 도중의 중간 답을 별도 메시지로 보냄 / Codex 계열 모델의 진행 설명을 보여 줌
skin · compactdefault · falseCLI 겉모습 / 빈 줄을 줄인 촘촘한 출력
resume_displayfull세션을 이어 할 때 이전 메시지를 다 보여 줌(full) / 한 줄만(minimal)
bell_on_complete · bell_on_promptfalse끝났을 때 / 내 답이 필요한 질문이 열렸을 때 벨
show_reasoning · streaming · show_costtrue · false · false생각 과정 표시 / 글자가 나오는 대로 표시 / 상태 막대에 예상 비용($)
timestamps · timestamp_formatfalse · "%H:%M"대화 기록에 시각 붙이기와 그 형식
turn_summary · spinner_token_flowtrueCLI: 턴 끝 한 줄 정리 / 진행 표시 옆에 이번 턴의 출력 토큰 수
runtime_footerenabled: false게이트웨이: 턴의 마지막 답 끝에 모델·컨텍스트 사용률·작업 폴더를 덧붙임. 대화 중 /footer 로 전환
status_bar.fields[]상태 막대에 보일 항목(빈 목록 = 기본 구성)
file_mutation_verifiertrue파일 수정 실패 경고
languageenen · 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 에는 여섯 가지 백엔드가 들어 있고, 플러그인으로 더할 수 있습니다.

Hermes 에이전트가 명령을 내림 terminal.backend 어디서 실행할지 고르는 설정 local — 내 컴퓨터 (기본값) 격리 없음 · 개발, 개인 용도 docker — Docker 컨테이너 완전 격리 · 안전하게 가둬 놓고 실행 ssh — 원격 서버 네트워크로 분리 · 성능 좋은 다른 컴퓨터에서 modal · daytona · vercel_sandbox 완전 격리 · 클라우드에 빌린 실행 공간 플러그인으로 singularity · sprites 백엔드를 더할 수 있습니다
같은 명령이라도 백엔드에 따라 실행되는 곳이 달라집니다. 깜빡이는 점이 기본값입니다.

왜 바꾸나. 기본값 local 은 준비할 것이 없어 가장 편하지만 격리가 없습니다. 원문은 이렇게 경고합니다 — 이때 에이전트는 내 사용자 계정과 똑같은 파일 접근 권한을 가집니다. 걱정되면 hermes tools 로 원하지 않는 도구를 끄거나, Docker 로 바꿔 가둬 둔 공간에서 실행하게 합니다.

hermes config set terminal.backend docker

뜻: “명령을 Docker 컨테이너 안에서 실행하게 바꾼다.” 원문의 조언은 간단합니다 — 헷갈리면 local 로 되돌려 거기서 명령이 되는지부터 확인합니다.

백엔드명령이 실행되는 곳격리알맞은 쓰임
local내 컴퓨터에서 바로없음개발, 개인 용도
docker오래 유지되는 Docker 컨테이너 하나 (세션, /new, 하위 에이전트가 함께 씀)완전안전하게 가둬 놓고 실행, 자동화 서버
sshSSH(다른 컴퓨터에 안전하게 접속하는 방법)로 연결한 원격 서버네트워크 경계원격 개발, 성능 좋은 장비
modalModal 클라우드 샌드박스(sandbox — 바깥과 분리해 둔 실행 공간)완전 (클라우드 VM)잠깐 쓰는 클라우드 연산, 평가
daytonaDaytona 작업 공간완전 (클라우드 컨테이너)관리형 클라우드 개발 환경
vercel_sandboxVercel 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(개인 키 경로)가 있습니다.

백엔드필요한 것
modalMODAL_TOKEN_ID + MODAL_TOKEN_SECRET, 또는 ~/.modal.toml 파일
daytonaDAYTONA_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 이 있어야 합니다.

명령이 바로 실패하거나 터미널 도구가 꺼져 있다고 나오면 아래를 확인합니다.

백엔드확인할 것
Dockerdocker version 을 실행해 Docker 가 되는지 봅니다. 안 되면 Docker 를 고치거나 hermes config set terminal.backend local
SSHTERMINAL_SSH_HOST 와 TERMINAL_SSH_USER 가 둘 다 있는지
클라우드 · 플러그인위 탭의 환경 변수와 플러그인이 갖춰졌는지. hermes doctor 로 점검합니다

도구 쪽에서 본 백엔드 이야기는 4장, 안전 관점의 격리는 9장에서 이어집니다.

공통 키와 작업 폴더 — terminal 묶음
키기본값뜻
backendlocallocal | docker | ssh | modal | daytona | vercel_sandbox | 플러그인 백엔드
cwd"."게이트웨이·예약 작업의 작업 폴더(CLI 는 언제나 실행한 폴더)
timeout180명령 하나의 제한 시간(초)
home_modeauto에이전트의 명령이 보는 홈 폴더. auto = 내 컴퓨터에서는 실제 홈, 컨테이너에서는 {HERMES_HOME}/home. profile = 프로필 전용 홈(프로필마다 git·SSH 로그인을 따로 두고 싶을 때)
persistent_shelltrueSSH: 명령 사이에 export 한 환경 변수를 이어 감(local 은 TERMINAL_LOCAL_PERSISTENT). 작업 폴더는 항상 이어지고, Docker·클라우드·플러그인 백엔드는 이 설정을 무시
container_persistenttrue파일 상태를 세션 사이에 보존
어디서 쓰나작업 폴더 기본값
CLI (hermes)명령을 실행한 현재 폴더
메신저 게이트웨이terminal.cwd, 없으면 홈 폴더 ~
Docker / Singularity / Modal / SSH컨테이너나 원격 컴퓨터 안의 사용자 홈 폴더
Docker 백엔드 세부 — 폴더 잇기 · 비밀 값 넘기기 · 컨테이너가 남는 때
키기본값뜻
docker_image"nousresearch/hermes-sandbox:desktop"컨테이너 이미지
docker_volumes—내 컴퓨터 폴더를 컨테이너에 잇기. "내컴퓨터경로:컨테이너경로", 읽기 전용은 끝에 :ro
docker_mount_cwd_to_workspacefalsetrue 면 Hermes 를 실행한 폴더를 /workspace 에 이음. 컨테이너가 내 실제 파일을 직접 만지게 되므로 일부러 원할 때만
docker_forward_env—컨테이너로 넘길 환경 변수 이름. 값은 내 셸, 다음으로 ~/.hermes/.env 에서 찾음. 넘긴 값은 컨테이너 안의 명령이 볼 수 있음
docker_env—컨테이너에 넣을 고정 값. 비밀이 아닌 것에만
docker_networktruefalse 면 컨테이너의 네트워크를 완전히 끊음
docker_run_as_host_userfalsetrue 면 이어 둔 폴더에 생긴 파일이 내 소유가 됨. 대신 컨테이너 안에서 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 · offupdates.pre_update_backup
updates.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_effort
agent.reasoning_overrides
빠른 모드
Fast Mode
웃돈을 내고 빠른 출력을 요청 — fast(항상) · auto(매 턴 처음 60초) · cold(세션 첫 턴만)agent.service_tier
agent.fast_auto_seconds (60)
프롬프트 캐시
Prompt caching
매번 똑같이 보내는 앞부분을 제공자가 기억해 두었다가 할인 요금으로 다시 씀. 자동이고 끌 수 없으며, 기억해 둘 시간만 고름prompt_caching.cache_ttl ("5m" | "1h" | "auto")
여러 키 돌려 쓰기
Credential Pool Strategies
한 제공자에 API 키가 여러 개일 때 고르는 방식 — fill_first(기본) · round_robin · least_used · randomcredential_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_lines
tool_budget.mcp_result_size_chars
맥락 파일 한도
Context File Truncation
자동으로 읽히는 맥락 파일을 얼마까지 읽어 들일지. 넘으면 앞과 뒤만 남김context_file_max_chars
context_file_read_timeout (5.0)
반복 횟수 한도
Iteration Budget
내 메시지 하나에 에이전트가 되풀이할 수 있는 횟수와 제공자 오류 때의 재시도 — 꼭 알아 둘 한도agent.max_turns
agent.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_caps
agent.stall_guards · agent.turn_liveness
되묻기 대기
Clarify
에이전트가 되물은 질문에 답을 기다리는 시간(초)agent.clarify_timeout (90)
④ 컨텍스트 · 기억 · 스킬 (6)
설정 (원문 제목)무엇을 하나대표 설정 이름
컨텍스트 압축
Context Compression
긴 대화를 요약해 줄임 — 대화가 길어지면compression.enabled · compression.threshold
컨텍스트 압력 알림
Context Pressure Warnings
압축 시작선에 가까워지면 알림(60% 안내, 85% 경고). 자동 — 대화가 길어지면(설정 이름 없음)
컨텍스트 엔진
Context Engine
컨텍스트 관리 방식을 통째로 바꾸는 플러그인 고르기. 기본은 요약 방식 compressorcontext.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.model
delegation.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.enabled
security.website_blocklist.domains
승인 방식
Smart Approvals
위험해 보이는 명령을 다루는 방식 — smart(기본, 보조 모델이 판단) · manual(매번 물음) · off(검사를 끔, 주의) (9장)approvals.mode · approvals.deny
체크포인트
Checkpoints
파일을 바꾸기 전에 찍어 두는 자동 스냅샷. 기본 꺼짐 (9장)checkpoints.enabled
checkpoints.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.provider
stt.language
음성 모드
Voice Mode (CLI)
CLI 에서 마이크로 말하기. /voice on 으로 켬 (8장)voice.record_key ("ctrl+b")
voice.auto_tts
⑧ 메신저 · 게이트웨이 · 서버 운영 (11)
설정 (원문 제목)무엇을 하나대표 설정 이름
세션 수와 단체방 분리
Group Chat Session Isolation
두 가지가 한 절에 있음 — 동시에 활동할 수 있는 세션 수(기본 무제한), 단체방에서 사람마다 세션을 따로 줄지(기본 true)max_concurrent_sessions
group_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_mention
discord.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 의 공식 문서)

CHAPTER 04

도구 · 툴셋 · MCP

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

이 장에서 배우는 것
  • 도구가 무엇이고 Hermes 에 어떤 종류가 들어 있는지
  • 툴셋으로 도구를 켜고 끄는 방법(hermes tools, --toolsets)
  • 명령이 실행되는 곳(터미널 백엔드)을 내 컴퓨터 · Docker · SSH 로 바꾸는 법
  • 오래 걸리는 명령과 관리자 비밀번호(sudo)를 다루는 방식
  • MCP 가 무엇이고, MCP 서버를 어떻게 추가하는지
  • MCP 도구를 걸러 내고 안전하게 쓰는 법, 안 될 때 볼 곳
처음이라면 이것만

나머지 소절은 필요해질 때 읽어도 됩니다. 접힌 회색 상자는 설정 값과 예외를 모아 둔 곳입니다.

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

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

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

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

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

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

API 키 없이 쓰는 길 — Nous Tool Gateway 유료 Nous Portal 구독자는 웹 검색 · 이미지 생성 · 음성 합성(TTS) · 브라우저 자동화를 Tool Gateway 로, 서비스마다 따로 API 키(그 서비스를 쓸 자격을 증명하는 비밀 문자열)를 마련하지 않고 쓸 수 있습니다. hermes model 로 켜거나 hermes tools 에서 도구별로 설정합니다. (8장의 메신저 “게이트웨이”와는 다른 것입니다.)
표의 작은 글씨 — 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 send CLI, 게이트웨이 알림이 맡습니다(에이전트가 부르는 도구가 아닙니다).
  • 플러그인 — 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_sandboxVercel 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 에 적습니다.

내 터미널에서는 되는데 에이전트의 명령만 멈추거나 시간 초과가 난다면 에이전트는 셸(shell — 터미널에서 내 명령을 받아 실행해 주는 프로그램. bash, zsh 등)을 “사람이 앞에 없는” 방식으로 실행합니다. 셸을 열 때마다 실행되는 시작 파일(.bashrc, .zshrc)에 느리거나 입력을 기다리는 내용이 있으면 에이전트의 명령만 느려지거나 멈춥니다. 원문은 이 증상에서 셸 시작 파일을 가장 먼저 의심하라고 적습니다.
셸 시작 파일 손보기 — 사람이 없을 때는 일찍 빠져나가게

문제는 세 가지입니다: 느린 초기화(nvm 같은 버전 관리 도구 — 에이전트는 셸을 아주 많이 띄웁니다), 사람 입력을 기다리는 부분(묻기 · tmux/screen 붙기 · read · 메뉴), 무조건 찍히는 배너. .bashrc 맨 위 가까이에 아래 표준 가드를 두고, 무겁거나 사람과 주고받는 초기화는 그 아래에 둡니다.

case $- in
  *i*) ;;      # 대화형: 계속 진행
  *) return;;  # 비대화형: 여기서 멈춤
esac

zsh: 로그인 전용 설정은 .zprofile, 대화형 전용은 .zshrc, .zshenv 는 최소로 둡니다(모든 셸에서 실행됨). 에이전트에게 필요한 도구의 PATH 는 가드 위에서 내보내거나, 실행 파일을 ~/.local/bin 에 심볼릭 링크로 겁니다.

백엔드별 준비 명령 · 컨테이너 자원과 보안
백엔드준비알아 둘 점
dockerdocker_image: python:3.11-slim처음 쓸 때 컨테이너 하나를 띄우고(docker run -d ... sleep infinity) 모든 terminal · 파일 · execute_code 호출을 docker exec 로 보냅니다. /new, /reset, 하위 에이전트를 가리지 않고 이어집니다(공식 문서 Configuration → Docker Backend).
singularityhermes 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.sifSingularity/Apptainer 공식 플러그인(예전에는 내장). 쓰던 프로필에는 hermes update 가 설치해 줍니다.
spriteshermes plugins install NousResearch/hermes-plugin-sprites --enable → hermes config set terminal.backend sprites~/.hermes/.env 에 SPRITES_TOKEN 추가(공식 문서 Sprites Backend).
modalpython -c "import pm; pm.sync_venv(['modal'], explicit=True)" → modal setup → hermes config set terminal.backend modal서버리스 클라우드.
vercel_sandboxpython -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:latestVERCEL_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 에 추가하라는 안내가 들어 있습니다.
비밀번호를 채팅으로 보내지 않습니다 원문은 메신저 대화에 비밀번호를 적어 보내지 말라고 분명히 적습니다. 위험 명령 승인 규칙(9장)과, 에이전트가 지어낸 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 는 멀티탭의 콘센트 모양 같은 것입니다. 콘센트 모양이 하나로 정해져 있으니, 어느 회사가 만든 기기든 플러그만 맞으면 꽂아 쓸 수 있습니다. MCP 서버는 “플러그가 달린 기기”, Hermes 는 “멀티탭”입니다. 꽂기만 하면 Hermes 가 그 기기에 어떤 기능이 있는지 알아서 살펴봅니다.
Hermes 내장 도구 + MCP 로 꽂은 도구 stdio 서버 내 컴퓨터에서 Hermes 가 함께 실행하는 프로그램 HTTP 서버 다른 곳에서 운영되는 주소(URL)에 바로 접속 바깥의 도구 · 자료 GitHub 데이터베이스 파일 시스템 브라우저 회사 내부 API … 그 밖에도
MCP 서버는 Hermes 와 바깥 서비스 사이의 연결 부품입니다. Hermes 는 시작할 때 서버에 어떤 도구가 있는지 알아보고 자기 도구 목록에 올립니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

④ Hermes 를 시작합니다

hermes chat

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

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

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

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

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

고른 도구를 나중에 바꾸려면 hermes mcp configure linear 처럼 서버 이름을 붙여 실행하면 같은 체크리스트가 지금 선택 그대로 다시 열립니다. 서버에 새로 생긴 도구를 받아들일 때도 씁니다.
설치는 남의 코드를 실행하는 일입니다 카탈로그 항목을 설치하면 그 항목이 정한 설치 명령과 서버 코드가 내 컴퓨터에서 실행됩니다. 설치 전에 무엇이 실행되는지 확인합니다 — MCP 를 안전하게 쓰기.
카탈로그 세부 — 미리 체크되는 도구 · 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 가 주소를 출력하고 가능하면 브라우저를 엶 ② 내가 “허용” 브라우저에서 그 서비스에 로그인하고 승인 ③ 응답 받기 Hermes 가 내 컴퓨터의 포트에서 기다리다 받음 ④ 토큰 저장 ~/.hermes/mcp-tokens/ <server>.json 다음 실행부터는 저장된 토큰을 조용히 다시 씁니다 — 갱신이 실패할 때까지
처음 한 번만 브라우저에서 허용하면 됩니다. 토큰 파일은 나만 읽을 수 있는 권한(0o600)으로 저장됩니다.
하고 싶은 일명령
서버에 로그인하기 · 토큰이 죽었을 때 다시 인증하기hermes mcp login <server> (예: hermes mcp login figma)
카탈로그에서 설치한 뒤 로그인하기hermes mcp install figma → hermes mcp login figma
실행 중인 대화에서 설정을 고쳤다면 — 새 터미널에서 로그인 Hermes 를 켜 둔 채 ~/.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 에 등록되는 이름
filesystemread_filemcp_filesystem_read_file
githubcreate-issuemcp_github_create_issue
my-apiquery.datamcp_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 항목으로도 합니다.

서버가 내놓는 도구 create_issue list_issues search_code … 그 밖의 도구들 걸러 내기 (tools) include: [create_issue, list_issues] 나머지는 등록되지 않음 Hermes 가 보는 도구 mcp_github_create_issue mcp_github_list_issues
에이전트는 걸러 내기를 통과한 도구만 알고, 그것만 쓸 수 있습니다.
하고 싶은 일서버 항목 아래에 적는 것결과
서버를 통째로 끄기enabled: false그 서버를 완전히 건너뜁니다. 연결조차 시도하지 않습니다.
허용 목록 — 적은 것만 받기tools: 아래 include: [create_issue, list_issues]적힌 도구만 등록됩니다.
제외 목록 — 적은 것만 빼기tools: 아래 exclude: [delete_customer]적힌 것을 뺀 나머지가 모두 등록됩니다.
보조 도구 끄기tools: 아래 prompts: false / resources: falselist_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: falseShow 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>_ 접두어 없는 서버 쪽 도구 이름을 씁니다.
Elicitationelicitation/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)와 본문이 가리키는 참고 쪽은 받지 않은 것은 다루지 않았습니다.

CHAPTER 05

기억 · 맥락 파일 · 성격

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는 “오늘은 선생님처럼 말해 줘” 하고 잠깐 씌우는 역할 모자입니다.
① 기억 — MEMORY.md · USER.md Hermes 가 스스로 적는 메모 · 세션이 끝나도 남음 ② 맥락 파일 — AGENTS.md 등 내가 프로젝트 폴더에 두는 안내문 · 그 프로젝트에서만 ③ SOUL.md 내가 적는 기본 성격·말투 · 어느 폴더에서 열든 항상 ④ /personality 잠깐 덧씌우는 말투 · 끄면 원래 성격으로 시스템 프롬프트 대화가 시작될 때 모델이 가장 먼저 읽는 지시문 묶음 모델 두뇌 역할 AI 넷 모두 여기로 들어가 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 에게는 포스트잇 몇 장 크기의 작은 수첩이 두 권 있습니다. 일하다 중요한 것을 알게 되면 수첩에 적어 두고, 다음 날 출근할 때(새 세션) 수첩부터 한 번 읽고 일을 시작합니다. 수첩이 작아서 정말 중요한 것만 골라 적어야 합니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

두 칸 — 에이전트 메모와 사용자 소개

기억은 두 칸으로 나뉩니다. 원문은 이 칸을 target(대상 — 어느 파일에 적을지)이라고 부르고, 이름은 memory 와 user 입니다. Hermes 가 기억을 적을 때마다 둘 중 하나를 고릅니다.

memory — 에이전트의 개인 메모

MEMORY.md · 2,200자 · 보통 8~15개 — 환경, 일하는 방식, 배운 교훈

  • 환경 사실 (운영 체제, 도구, 프로젝트 구조)
  • 프로젝트 규칙과 설정
  • 도구의 별난 점과 찾아낸 우회 방법
  • 끝낸 작업의 기록
  • 잘 통했던 스킬(일하는 방법을 적은 설명서)과 요령

user — 사용자 소개

USER.md · 1,375자 · 보통 5~10개 — 내가 누구이고 무엇을 좋아하는지

  • 이름, 역할, 시간대
  • 소통 취향 (짧게/자세히, 선호하는 형식)
  • 거슬려 하는 것, 피해야 할 것
  • 일하는 습관
  • 기술 수준
“프로필”이라는 말이 두 가지입니다 원문은 USER.md 를 user profile(사용자 프로필)이라고 부릅니다. 그런데 Hermes 에는 설정·기억·세션을 통째로 따로 쓰는 프로필(profile, 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 가 핵심을 다음 세션으로 옮기고, 빠진 부분은 지난 대화 검색이 채웁니다. 한 세션 안에서는 중요한 내용이 아직 눈앞의 대화에 다 있으므로 이 장치들이 움직일 이유가 없습니다.

터미널 (CLI) 세션 1 세션 2 세션 3 세션 4 세션 5 실행할 때마다 새 세션 — 초록 점마다 기억을 다시 읽습니다 (경계가 저절로 생김) 메신저 대화방 하나 = 세션 하나 — 며칠, 몇 주 동안 이어질 수 있음 /new/new 컴퓨터를 꺼도 세션이 끝나지 않습니다 — 경계는 내가 /new 로 만들어야 합니다
세션의 경계가 생길 때마다 Hermes 는 새로 고친 기억을 다시 읽고, 짧은 대화에서 가볍게 시작합니다.

이 차이는 메신저(Telegram, Discord 등)에서 중요합니다. 메신저에서는 대화방 하나가 일부러 끊기지 않는 한 세션으로 만들어져 있어서, 재시작이나 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램. 8장) 중단, 컴퓨터 재부팅을 넘어 이어집니다. 밤에 컴퓨터를 꺼도 세션은 끝나지 않고, 다음 메시지가 정확히 그 자리에서 이어받습니다.

한 번도 끊지 않으면 생기는 일이유
비용이 점점 커집니다계속 길어지는 기록 위로 압축(긴 대화를 줄여 정리하는 것 — 3장)이 거듭 돌기 때문입니다
배우는 순환이 거의 돌지 않습니다“잊는다 → 기억에서 떠올린다 → 지난 세션을 찾아본다”는 순환은 세션이 바뀔 때 일어납니다
새로 적은 기억이 보이지 않습니다기억은 세션 시작 때 한 번만 읽기 때문입니다 (고정된 스냅샷)
자연스러운 경계에서 /new 일 하나가 끝났을 때, 주제가 바뀔 때, 하루를 시작할 때 /new(새 세션을 시작하는 슬래시 명령 — 대화 입력 칸에 / 로 시작해 넣는 명령)를 넣습니다. 터미널에서는 실행할 때마다 새 세션이라 대체로 저절로 해결되지만, 게이트웨이에서는 경계를 내가 만들어야 합니다.

기억하라고 했는데 잊어버렸다면

가장 흔한 신고는 이렇습니다. 무언가의 위치(노트 보관 폴더, 프로젝트 폴더, 서버)를 알려 주자 Hermes 가 “기억해 둘게요”라고 답했는데, 새 세션에서는 모릅니다. 아래 순서로 확인합니다 — 첫 번째가 대부분의 경우를 설명합니다.

나: “이 위치 기억해 줘” 모델이 답합니다 말로만 “저장했어요” 도구를 부르지 않음 — 그냥 글자 memory 도구를 실제로 호출 파일에 항목이 적힘 다음 세션은 모릅니다 파일에 아무것도 없음 다음 세션이 읽습니다 시스템 프롬프트에 들어옴
“기억에 추가했어요”라는 문장은 글자일 뿐입니다. 기억은 모델이 memory 도구를 실제로 호출했을 때만 남습니다.

① 정말 적혔는지 파일을 엽니다

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 파일의 변수그것은 비밀 값과 설정이지 기억이 아닙니다
저장해 달라고 하지 않고 지나가듯 말한 사실저장을 부탁해야 합니다
되풀이하는 일에 매번 필요한 위치라면 스킬이 더 낫습니다 원문은 이런 정보는 기억 항목보다 스킬(skill — 특정 일을 하는 방법을 적은 설명서. 6장)에 두는 편이 낫다고 적습니다. 스킬은 관련 있을 때만 읽히고, 2,200자 예산을 차지하지 않기 때문입니다.

수첩에 적지 않은 것도 완전히 사라지지는 않습니다. 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
“Hermes 가 나에 대해 틀린 짐작을 저장했어요” 원문이 주는 답은 저장 전 승인입니다. 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다른 모델로 보낼 때만 적용. 같은 모델이면 주 대화의 추론 강도를 물려받습니다
enabledfalse = 답 뒤의 자동 검토를 건너뜀(직접 넣는 /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.mdAGENTS.md 를 나만, 폴더별로 덮어쓰는 파일 (보통 저장소에 올리지 않음)시작할 때의 작업 폴더 + 하위 폴더는 차츰
AGENTS.md프로젝트 지침 · 규칙 · 구조위와 같음
CLAUDE.mdClaude Code 용 맥락 파일 (이것도 알아봄)위와 같음
SOUL.md이 Hermes 전체의 성격과 말투Hermes 홈 폴더(~/.hermes)의 SOUL.md 만
.cursorrulesCursor IDE 의 코딩 규칙작업 폴더만
.cursor/rules/*.mdcCursor IDE 의 규칙 모듈작업 폴더만

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

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

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

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

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

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

AGENTS.md — 프로젝트 안내문 쓰기

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/AGENTS.mdgit 저장소의 맨 위 폴더 packages/AGENTS.md중간 폴더 webapp/AGENTS.md지금 작업 폴더 시스템 프롬프트 ① 저장소 전체 규칙 ② packages 규칙 ③ webapp 규칙 — 가장 우선
원문 예시: 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 홈 폴더)에 한 장만 있습니다.
~/.hermes/SOUL.md Hermes 홈 폴더 한 곳 — 성격은 여기서만 읽습니다 프로젝트 A 폴더같은 성격 프로젝트 B 폴더같은 성격 프로젝트 C 폴더여기 둔 SOUL.md 는 읽지 않음 ✗
어느 폴더에서 Hermes 를 열든 성격이 같습니다. 프로젝트마다 성격이 뜻밖에 바뀌지 않게 하려는 설계입니다.

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

~/.hermes/SOUL.md

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

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

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

✅ SOUL.md 에 적을 것

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

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

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

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

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

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

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

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

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

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

SOUL.mdAGENTS.md
적는 것정체성, 말투, 문체, 기본 소통 방식, 성격에서 나오는 행동프로젝트 구조, 코딩 규칙, 선호하는 도구, 저장소별 작업 절차, 명령 · 포트 · 경로 · 배포 메모
기준어디서나 나를 따라다녀야 하면 여기프로젝트에 속하면 여기
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분명한 예시를 드는 참을성 있는 선생님uwuuwu 말투로 최대한 귀엽게
kawaii귀여운 표현, 반짝임, 열정 ★philosopher질문마다 깊이 사색
catgirl고양이 같은 표현(nya~)의 Neko-chanhype최대 에너지와 열정!!!
말투와 화면 모양은 따로입니다 SOUL.md 와 /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 에 프롬프트 인젝션으로 보이는 내용이 있어 읽지 않았습니다.

검사기가 전부 막아 주지는 않습니다 이 검사는 흔한 패턴을 막을 뿐입니다. 원문은 여럿이 함께 쓰는 저장소의 맥락 파일은 직접 살펴보아야 하고, 내가 만들지 않은 프로젝트의 AGENTS.md 는 항상 확인하라고 적습니다. 그리고 SOUL.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 가 바탕이고 나머지가 그 위에 올라갑니다.

1 · SOUL.md — 에이전트의 정체성 (없으면 내장 기본값) 2 · 도구에 맞춘 행동 안내 3 · 기억 · 사용자 소개 (MEMORY.md · USER.md) 4 · 스킬 안내 5 · 맥락 파일 (AGENTS.md, .cursorrules) 6 · 현재 시각 7 · 플랫폼별 형식 안내 8 · /personality 같은 덧씌우기 (선택) 바탕 → 덧씌움 →
점이 찍힌 네 층이 이 장에서 다룬 네 가지입니다. 스킬은 6장에서 다룹니다.

원문이 권하는 기본 구성은 셋을 제자리에 두는 것입니다.

① 공들인 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 의 공식 문서)

CHAPTER 06

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

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

이 장에서 배우는 것
  • 스킬이 무엇이고 기억과 어떻게 다른지, 어디에 저장되는지
  • 설치된 스킬을 슬래시 명령으로 부르는 법, 여러 개를 한 번에 부르는 법
  • /learn 으로 내 자료를 스킬로 만드는 법
  • “필요할 때만 꺼내 읽는다”는 3단계 구조가 왜 글의 양(토큰)을 아끼는지
  • Skills Hub 에서 스킬을 찾아 미리 보고 설치하고 최신으로 유지하는 법
  • 에이전트가 스스로 스킬을 만드는 때와, 그것을 내가 승인하게 바꾸는 법
  • 스킬 폴더 구조, 번들, 그리고 설치할 때 거치는 보안 검사와 신뢰 등급
처음이라면 이것만

나머지 소절(형식·폴더·번들·안전)은 스킬을 직접 만들거나 팀과 나눠 쓸 때 돌아와서 읽어도 됩니다. 손으로 따라 해 보려면 활용편 실습 4가 이 장의 짝입니다.

스킬이란 무엇인가

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

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

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

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

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

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

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

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

어떤 스킬이 들어 있는지 보려면 딸려 오는 스킬과 공식 선택 스킬의 전체 목록은 공식 문서의 Bundled Skills Catalog · Official Optional Skills Catalog 쪽에 있습니다(이 가이드는 다루지 않음). 내 컴퓨터에 지금 무엇이 있는지는 대화에서 물어보거나 /skills list 로 볼 수 있습니다.
딸려 오는 스킬 없이 빈 상태로 시작하기 (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(터미널에서 글자로 쓰는 프로그램 화면)에서도, 메신저에서도 똑같이 씁니다.

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

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

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

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

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

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

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

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

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

Hermes 대화
/excalidraw

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

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

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

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

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

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

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

뜻: axolotl 스킬을 보여 줘

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

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

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

원문은 괄호 안에 이렇게 덧붙입니다. 계획 모드(plan mode)도 같은 방식으로 쓰지만 지금은 내장 명령입니다. /plan [request] 를 넣으면 Hermes 는 필요하면 주변 상황을 살펴본 뒤, 일을 실행하는 대신 마크다운(간단한 기호로 제목·목록을 표시하는 글 형식)으로 실행 계획을 써서 저장합니다. 저장 위치는 지금 작업 폴더(작업 공간 또는 백엔드의 작업 폴더)를 기준으로 한 .hermes/plans/ 아래입니다.

/learn — 내 자료를 스킬로 만들기

/learn 은 내가 이미 아는 것이나 쌓아 둔 참고 자료를, SKILL.md 를 손으로 쓰지 않고 스킬로 바꾸는 빠른 길입니다. 형식이 정해져 있지 않아서, 말로 설명할 수 있는 것이면 무엇이든 가리킬 수 있습니다. 에이전트가 이미 가진 도구로 자료를 모으고, Hermes 의 스킬 작성 기준에 맞춰 스킬을 써 줍니다.

① 자료를 가리킵니다 폴더 · 웹 주소 · 방금 한 일 메모 · 책이나 문서 묶음 ② 에이전트가 모읍니다 이미 가진 도구로 파일 읽기 · 웹 쪽 가져오기 ③ 스킬로 정리합니다 작성 기준에 맞춘 SKILL.md 큰 자료는 참고 파일로 나눔 ④ 저장합니다 skill_manage 도구로 승인을 켜 두면 내 확인 뒤 /learn 한 줄을 보내면 에이전트가 이 일을 보통의 대화 한 차례로 처리합니다
따로 돌아가는 “자료 수집 장치”는 없습니다. 지금 대화 중인 에이전트가 직접 자료를 읽고 스킬을 씁니다.

무엇을 가리킬 수 있는지는 원문의 다섯 가지 예시가 잘 보여 줍니다.

가리키는 것예시 (원문)뜻 · 에이전트가 하는 일
내 컴퓨터의 폴더
(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단계 — 목록만 훑어봅니다 늘 보임 skills_list() 스킬마다 이름 · 한 줄 설명 · 분류 — 전부 합쳐 약 3천 토큰 그 일이 필요해지면 1단계 — 스킬 하나를 펼칩니다 필요할 때만 skill_view(name) SKILL.md 전체 내용 + 부가 정보 — 양은 스킬마다 다름 더 자세한 자료가 필요해지면 2단계 — 참고 파일 하나만 더 봅니다 필요할 때만 skill_view(name, path) 스킬 폴더 안의 특정 참고 파일 — 양은 파일마다 다름 책등(제목)만 보이는 선반 한 권을 뽑아 펼침 부록 한 쪽만 넘겨 봄 아래로 갈수록 자세해지고, 필요한 만큼만 내려갑니다
왼쪽이 Hermes 의 세 단계, 오른쪽이 같은 일을 설명서 선반에 빗댄 그림입니다. 괄호가 붙은 영어는 에이전트가 쓰는 도구 이름입니다.

원문에 실린 표기는 다음과 같습니다. 숫자가 붙은 것은 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 — 파일 맨 위 --- 두 줄 사이에 적는 기본 정보)이고, 아래쪽은 사람이 읽는 글처럼 쓴 본문입니다.

--- name: my-skill description: Brief description … version: 1.0.0 --- # Skill Title ## When to Use ## Procedure ## Pitfalls ## Verification 머리말 (frontmatter) 이름 · 한 줄 설명 · 버전 같은 기본 정보 0단계 목록에 실리는 이름과 설명이 여기서 나옵니다 위아래의 --- 두 줄 사이에 적습니다 본문 — 원문 예시의 네 절 언제 쓰나 — 이 스킬을 꺼낼 조건 순서 — 차례대로 할 일 함정 — 알려진 실패와 해결법 확인 — 잘 됐는지 보는 법
왼쪽이 파일, 오른쪽이 각 부분의 뜻입니다. 선반 비유로는 머리말이 책등, 본문이 책 속입니다.

원문의 예시 전체는 다음과 같습니다. # 뒤의 영어는 원문에 달린 설명이고, “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)
값해당 운영체제
macosmacOS (Darwin)
linuxLinux
windowsWindows
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 뒤에 적는 글은 “어느 출처의 어느 스킬인가”를 가리키는 주소입니다.

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

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

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

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

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

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

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

Install “skill-name”?

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

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

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

--force 는 “읽어 봤고 괜찮다”는 뜻일 때만 원문 예시에는 --force 가 붙은 설치 명령이 있습니다. 이것은 보안 검사의 가벼운 경고를 넘기는 옵션입니다. 무엇을 넘길 수 있고 무엇은 못 넘기는지 안전 소절에서 먼저 확인하세요.
웹사이트 설치 링크의 세부 (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-shskills.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 --forceskills.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 auditHub 스킬 전체를 보안 재검사
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예시설명
officialofficial/security/1passwordHermes 와 함께 제공되는 선택 스킬. Hermes 저장소(optional-skills/)에서 관리하며 내장 수준 신뢰로 설치됩니다.
skills-shskills-sh/vercel-labs/agent-skills/vercel-react-best-practicesVercel 의 공개 스킬 목록 skills.sh. 직접 검색하고, 상세 쪽을 살피고, 별칭 꼴 이름(목록의 이름과 저장소 폴더 이름이 다른 경우)을 풀어 원본 저장소에서 설치합니다.
well-knownwell-known:https://mintlify.com/docs/.well-known/skills/mintlify웹사이트가 /.well-known/skills/index.json 으로 직접 내주는 스킬. 중앙 Hub 하나가 아니라 “웹에서 찾는 약속”입니다. 사이트나 문서 주소로 검색합니다.
githubopenai/skills/k8sGitHub 저장소·경로에서 바로 설치, 그리고 내가 추가한 tap(스킬 출처로 등록한 GitHub 저장소).
clawhub출처별 주소ClawHub(clawhub.ai) — 커뮤니티 출처로 연결된 외부 스킬 장터.
lobehub출처별 주소LobeHub 공개 목록의 에이전트 항목을 찾아 설치 가능한 Hermes 스킬로 바꿉니다.
browse-shbrowse-sh/airbnb.com/search-listings-ddgioaBrowserbase 의 browse.sh — 사이트별 브라우저 자동화 SKILL.md 200개 이상(Airbnb, Amazon, arXiv, 12306.cn, Etsy, Xero 등). 주소 꼴은 browse-sh/<hostname>/<task-id>. 신뢰 등급 community.
urlhttps://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 로 설치한 스킬도 같은 원칙입니다 — 내가 고친 스킬은 update 가 건너뜁니다
딸려 오는 스킬은 설치할 때와 hermes update 때마다 이 판단을 거칩니다.
Hub 로 설치한 스킬딸려 오는 스킬 (bundled)
언제 갱신되나내가 실행할 때 — hermes skills check 로 확인, hermes skills update 로 갱신설치할 때와 hermes update 를 할 때마다 자동
내가 고쳤다면그 스킬은 건너뜀“내가 고친 것(user-modified)”으로 보고 계속 건너뜀
그래도 원본으로 바꾸려면hermes skills update react --forcehermes 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 도구 ④ 다음에 꺼내 다시 씁니다 관련 있는 일이 올 때만 불러옴 절차 기억 procedural memory 사실은 기억에, 일하는 순서는 스킬에 — 둘이 함께 Hermes 를 나아지게 합니다
한 바퀴 돌 때마다 선반에 설명서가 한 권 늘거나, 있던 설명서가 고쳐집니다.

시스템 프롬프트(대화 맨 앞에 깔리는 기본 지시문)가 에이전트에게 “간단하지 않은 일의 방법은 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 — 정해 둔 시간에 자동 실행) 모두).

같은 이름의 스킬이 여러 곳에 있으면 — 왼쪽이 이깁니다 ① 프로젝트 스킬 .hermes/skills/ 그 저장소 안에서만 적용 ② 내 기본 폴더 ~/.hermes/skills/ 모든 스킬의 기본 자리 ③ 새 스킬 저장 폴더 skills.create_dir 따로 정했을 때만 ④ 외부 스킬 폴더 skills.external_dirs 여러 도구가 함께 쓰는 폴더 ››› 우선순위 높음낮음 가려진 쪽 사본은 숨겨지고, 기록에 shadowed(가려짐)로 남습니다
②만 기본으로 쓰입니다. ①은 프로젝트를 신뢰했을 때, ③④는 설정 파일에 적었을 때만 생깁니다.
곳언제 쓰나
① 프로젝트 스킬저장소(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 refactor the auth middleware github-code-review test-driven-development github-pr-workflow 메시지 하나로 전달 세 스킬의 내용 + 내 부탁 번들은 별명일 뿐입니다 — 안에 적힌 스킬은 미리 설치되어 있어야 합니다
원문의 예시 번들 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 로 설치하는 스킬은 모두 거칩니다.

Hub 에서 받은 스킬 격리해 둔 채로 보안 검사 정보 빼돌리기 · 숨은 지시 파괴적 명령 · 공급망 신호 걸리는 것 없음 → 설치 스킬 폴더에 놓이고 설치 기록이 남습니다 주의·경고 수준으로 막힘 내가 읽어 본 뒤 --force 로 넘길 수 있음 위험(dangerous) 판정 → 막힘 --force 로도 넘길 수 없음
가운데 갈래가 얼마나 자주 막히는지는 출처의 신뢰 등급에 따라 다릅니다(아래 표).

검사기가 찾는 것으로 원문은 다음을 듭니다: 정보를 밖으로 빼돌리는 것(data exfiltration), 프롬프트 인젝션(prompt injection — 글 속에 숨긴 지시로 AI 를 속이는 수법), 파괴적인 명령, 공급망 위험 신호(supply-chain signals — 스킬이 끌어오는 외부 재료 쪽의 수상한 징후), 그 밖의 위협.

신뢰 등급어떤 출처인가적용되는 정책
builtinHermes 에 딸려 오는 스킬항상 신뢰
officialHermes 저장소의 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)

CHAPTER 07

예약 작업과 위임

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

이 장에서 배우는 것
  • 예약 작업이 무엇이고, 무엇이 켜져 있어야 도는지
  • 예약 작업을 만드는 세 가지 방법과 일정 적는 법
  • 결과를 어디로 받을지 정하는 법
  • 멈추고 · 고치고 · 지우는 법, 안 돌 때 살펴볼 곳
  • 위임이 무엇이고, 하위 에이전트가 무엇을 알고 무엇을 모르는지
  • 하위 에이전트를 지켜보고 멈추는 법과 위임의 한계
처음이라면 이것만

나머지는 필요할 때 찾아봅니다. 따라 하기는 활용편 실습 6(아침 브리핑 예약) · 실습 8(일을 나눠 맡기기).

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

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

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

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

한 번만 · 되풀이

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

멈춤 · 다시 시작 · 고치기

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

스킬 붙이기

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

결과 보낼 곳 고르기

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

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

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

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

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

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

확인 한 번(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장).

프롬프트는 등록 전에 검사됩니다 예약 작업 프롬프트는 만들 때와 고칠 때 검사를 거칩니다. 눈에 안 보이는 유니코드 문자를 쓴 속임수, SSH 뒷문을 만들려는 시도, 비밀 값을 빼돌리려는 뻔한 내용이 들어 있으면 등록이 막힙니다.
스킬을 붙인 예약 작업 · 프로젝트 폴더 안에서 실행하기
스킬 하나·여러 개도구 호출에서는 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 30m30분 뒤에 한 번
in 1d하루 뒤에 한 번
2026-03-15T09:00:002026년 3월 15일 오전 9시에 한 번 (날짜와 시각을 직접 적는 방식)
적는 말뜻
every 30m30분마다
every 2h2시간마다
every hour1시간마다 (숫자가 없으면 1)
30m30분마다 — in 없이 시간만 쓰면 되풀이입니다
in 30m 과 30m 은 다릅니다 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)에 전달됩니다. 에이전트가 스스로 메시지를 보내는 것이 아니므로, 프롬프트에 “보내 줘”를 처리할 방법을 따로 적을 필요가 없습니다. 받는 사람이 읽을 내용이 곧 마지막 답입니다.

예약 작업 실행 새 세션에서 끝까지 마지막 답 자동으로 전달됨 origin작업을 만든 바로 그 대화 — 메신저에서 만들면 기본 local내 컴퓨터 파일에만 저장 — CLI 에서 만들면 기본 telegram · discord · slack …그 메신저의 홈 채널(기본으로 받는 대화방) all홈 채널이 설정된 모든 메신저로 한꺼번에
받을 곳은 작업을 만들 때 정합니다. 어디로 보내든 결과는 내 컴퓨터의 ~/.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] 마지막 답에 [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 listhermes 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, 게이트웨이 재시작, 컴퓨터 재부팅을 거쳐도 작업은 사라지지 않습니다.

jobs.json 을 직접 고치지 않습니다 말로 부탁하거나 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 없이 돌리기 (no-agent) 예약 시각 스크립트 실행예: 메모리 확인 출력을 그대로 전달출력이 비면 조용히 지나감 AI 호출 없음 모델도 토큰도 쓰지 않음 ② 깨울지 먼저 확인하기 (wakeAgent) 예약 시각 확인 스크립트바뀐 것이 있나? 없음 → 이번에는 건너뜀 있음 → 에이전트 실행 결과 전달
①은 AI 를 아예 부르지 않습니다. ②는 값싼 확인을 먼저 하고, 할 일이 있을 때만 AI 를 부릅니다.

① 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 으로 앞 작업을 가리켜 두면, 다음 작업이 돌 때 앞 작업의 가장 최근 결과가 프롬프트 앞에 자동으로 붙습니다.

07:00 모으기 소식 10건을 모아 저장 결과 07:30 고르기 점수를 매겨 5건만 결과 08:00 글쓰기 짧은 글 초안 3개 Telegram 이어받는 것은 “이미 끝난 가장 최근 결과”입니다. 앞 작업이 끝나기를 기다려 주지는 않습니다. 원문 예시는 세 작업의 시각을 30분씩 띄워 두었습니다.
원문의 세 단계 예. 사슬은 몇 단계든 이을 수 있고, 여러 작업의 결과를 한 작업이 모아 받을 수도 있습니다.
기능무엇을 이어받나언제 쓰나
context_from다른 작업의 가장 최근 결과(여러 개면 적은 순서대로 이어 붙임)여러 단계로 나눈 일, 앞 단계 결과에 기대는 일, 여러 작업의 결과를 하나로 모으는 일
continuity자기 자신의 지난번 결과되풀이해 살펴보는 작업이 지난번에 알린 것을 또 알리지 않게 할 때
context_from · continuity 적는 법
가리키는 법context_from="a1b2c3d4" 또는 ["job_a", "job_b"]. 원문의 다른 대목은 작업 이름도 된다고 적습니다. 결과는 ~/.hermes/cron/output/{job_id}/*.md 에서 읽습니다.
continuity=True내용이 있는 가장 최근 결과가 “이미 보고한 것은 되풀이하지 말라”는 안내와 함께 붙습니다. 조용히 지나간 차례와 빈 결과는 건너뜁니다. 명령으로는 --continuity / --no-continuity.

예약 작업이 안 돌 때

대부분은 “게이트웨이가 꺼져 있다”, “설정이 빠졌다”, “일은 했는데 전달이 안 됐다” 셋 가운데 하나입니다. 먼저 아래 순서로 봅니다.

  1. hermes cron status스케줄러가 살아 있는지, 다음 실행이 언제인지 봅니다.
  2. hermes cron list작업마다 마지막 실행이 어땠는지 봅니다(대화 안에서는 /cron list).
  3. hermes cron doctor모든 작업을 한꺼번에 점검해 문제를 작업별로 묶어 보여 줍니다. 읽기만 하고 아무것도 바꾸지 않습니다.
  4. 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 — 모델이 한 번에 기억하며 볼 수 있는 글의 양)로 돌아옵니다.

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

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

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

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

여러 일을 동시에 합니다

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

대화가 막히지 않습니다

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

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

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

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

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

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

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

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

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

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

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

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

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

견줄 점위임 (delegate_task)코드 실행 (execute_code)
생각하는 힘AI 가 처음부터 끝까지 따져 가며 일함파이썬 코드만 실행
쓸 수 있는 도구막히지 않은 모든 도구도구 7개
동시에기본 10개까지(조절 가능)스크립트 하나
토큰 비용더 큼더 작음(출력만 돌아옴)
맞는 일판단이 필요한 복잡한 일기계적인 여러 단계 처리

여러 일을 한꺼번에 맡기기

일감을 여러 개 묶어 한 번에 맡기면 하위 에이전트들이 동시에 일합니다. 기본으로 최대 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 뿐입니다.

부모가 아는 것 ✕나와 나눈 지금까지의 대화 ✕앞서 쓴 도구와 그 결과 ✕위임 전에 의논한 모든 것 ✕ 표시는 넘어가지 않습니다 필요한 것은 쪽지에 옮겨 적어야 합니다 일감 쪽지 goal + context 넘어가는 것은 이것뿐 하위 에이전트가 받는 것 ✓goal — 해 달라는 일 ✓context — 필요한 배경 ✓작업 폴더의 맥락 파일 AGENTS.md 등 — 하나뿐인 예외 이것만 가지고 새 대화에서 시작합니다
하위 에이전트에게는 쪽지가 세상의 전부입니다. 쪽지에 없는 것은 없는 것입니다.

그래서 부모는 필요한 것을 전부 쪽지에 적어 넘겨야 합니다. 원문의 나쁜 예와 좋은 예입니다.

❌ 나쁜 예

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 키·제공자 설정. 터미널 세션은 물려받지 않고 자기 것을 새로 가집니다.
내가 할 일 쪽지는 부모 Hermes 가 씁니다. 부모가 아는 만큼만 적을 수 있으니, 큰 일을 맡길 때는 파일 위치·오류 글·지켜야 할 조건을 먼저 분명히 말해 둡니다. 하위 에이전트는 나에게 되물을 수 없습니다.
그림을 함께 넘기기 (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 로 멈춤 요청
TUICtrl+T 또는 /agents 로 나무 모양 목록. Enter/t 로 최근 기록, d 로 자세히e 로 방향 지시, x 로 그 하나만 멈춤, X 로 그 아래까지 멈춤
데스크톱 앱입력 칸 위 Subagents 를 펼쳐 하나를 고름Steer(방향 지시) · Stop(멈춤 요청)

기본 CLI 와 메신저(Telegram, Discord, Slack 등)에서는 /agents 를 넣으면 뒤에서 도는 위임이 글로 정리되어 나옵니다.

/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)를 만들 수 있고, 그 하위 에이전트는 다시 맡길 수 없습니다.

부모 에이전트깊이 0 하위 에이전트 (leaf)깊이 1 · 더 맡길 수 없음 하위 에이전트 (leaf)깊이 1 · 더 맡길 수 없음 orchestrator 역할깊이 1 · 다시 맡길 수 있음 깊이 2 (leaf) 깊이 2 (leaf) 깊이 2 는 기본값에서 막혀 있습니다 max_spawn_depth 를 2 로 올리고, 하위 에이전트를 orchestrator 역할로 만들어야 오른쪽 점선 상자가 열립니다. 단계가 늘 때마다 비용이 곱으로 붙습니다.
기본은 위의 두 줄까지(한 단계)입니다. 아래쪽 흐린 점선 상자는 설정을 일부러 바꿔야 열리는 부분입니다.

다음은 도구입니다. 하위 에이전트는 부모가 켜 둔 툴셋을 그대로 물려받습니다. 부모가 갖지 않은 능력을 하위 에이전트에게 줄 수는 없으므로, 맡길 일에 필요한 도구는 대화를 시작하기 전에 부모 쪽에 켜 두어야 합니다(툴셋은 4장). 거꾸로, 부모에게 있어도 하위 에이전트에게는 막히는 도구가 있습니다.

막힌 도구그래서 하위 에이전트는
delegate_task다시 맡길 수 없습니다(기본인 leaf 역할일 때).
clarify나에게 되물을 수 없습니다.
memory함께 쓰는 기억에 적을 수 없습니다.
send_message메신저로 메시지를 보낼 수 없습니다.
cronjob부모 이름으로 예약 작업을 만들 수 없습니다.

execute_code 는 막히지 않아, 하위 에이전트도 기계적인 일은 코드로 묶어 처리합니다. 기본 한도를 숫자로 보면 동시에 10개, 깊이 1단계, 하위 에이전트 하나가 도구를 쓰며 일하는 차례 250번입니다. 시간 제한은 기본으로 없습니다. 오래 걸린다는 이유만으로 끊지 않고, 완전히 멈춰 버린 하위 에이전트만 감지해 중단시킵니다.

위임한 일은 Hermes 가 꺼지면 이어지지 않습니다 Hermes 가 재시작되면 돌고 있던 하위 에이전트는 이어서 돌지 않고, /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 의 공식 문서)

CHAPTER 08

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

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

이 장에서 배우는 것
  • 게이트웨이가 하는 네 가지 일과, 왜 계속 켜 두어야 하는지
  • 쓸 수 있는 메신저 종류와 메신저마다 되는 기능의 차이
  • hermes gateway setup 한 줄로 시작하는 빠른 설정
  • Telegram 봇 만들기(BotFather) → 내 사용자 ID 알아내기 → Hermes 에 연결하기
  • 누가 내 봇에 말을 걸 수 있는지 정하는 허용 목록과 DM(1:1 대화) 페어링
  • 그룹 대화·홈 채널·음성 메시지, 그리고 게이트웨이를 서비스로 계속 켜 두는 방법
처음이라면 이것만

그룹 대화·음성·서비스 설치와 접힌 상자는 봇이 답하기 시작한 뒤에 읽어도 됩니다. 직접 따라 해 보려면 활용편 실습 7로 가세요.

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

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

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

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

① 메신저와 연결

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

② 세션 관리

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

③ 예약 작업 실행

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

④ 음성 메시지 전달

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

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

게이트웨이가 켜져 있을 때 ✓ 메신저로 보낸 말에 답이 옵니다 ✓ 예약 작업이 제시간에 실행됩니다 ✓ 그 결과가 홈 채널로 도착합니다 60초마다 실행할 예약 작업이 있는지 확인 꺼져 있을 때 ✗ 메시지를 받을 프로그램이 없습니다 ✗ 예약 작업 시계도 함께 멈춥니다 ✗ 꺼진 동안 온 Telegram 메시지는 다음에 켤 때 버려집니다 (기본값) 밤에 끄는 컴퓨터라면 설정으로 바꿀 수 있습니다
Telegram 은 게이트웨이가 꺼진 동안 온 메시지를 서버에 쌓아 두지만, Hermes 는 기본값으로 다음에 켜질 때 그 묶음을 버립니다. 바꾸는 설정은 봇 만들기의 접힌 표에 있습니다.
봇에게도 두뇌와 도구가 필요합니다 원문 안내: 봇에는 모델 제공자(provider — AI 모델을 빌려주는 서비스)와 도구 제공자(음성 읽어 주기 TTS, 웹 검색 등)가 모두 필요하며, Nous Portal 구독에는 이것들이 함께 들어 있습니다. 제공자를 아직 정하지 않았다면 1장부터 마치고 오세요.
원문 용어와 내부 구조 — 어댑터 · Hermes 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✅✅✅✅✅✅✅
WhatsApp—✅✅——✅✅
Signal—✅✅——✅—
Email—✅✅✅———
칸원문 이름뜻
음성VoiceHermes 가 음성으로 답하거나(TTS), 내가 보낸 음성 메시지를 글로 받아 적습니다
이미지Images이미지를 주고받습니다
파일Files첨부 파일을 주고받습니다
스레드Threads한 대화방 안에서 주제별로 갈라지는 대화 가닥을 지원합니다
반응Reactions메시지에 이모지 반응을 답니다
입력 중TypingHermes 가 처리하는 동안 “입력 중…” 표시가 뜹니다
실시간 갱신Streaming답을 다 쓴 뒤 한 번에 보내지 않고, 보낸 메시지를 고쳐 가며 글이 점점 늘어나게 보여 줍니다
이 가이드는 Telegram 만 자세히 다룹니다 메신저별 설정 방법은 공식 문서에 메신저마다 Setup 쪽이 따로 있습니다. 이 가이드가 받은 원문은 Telegram 쪽 하나이므로, 다른 메신저의 세부 설정은 쓰지 않습니다. 게이트웨이를 켜고 끄는 방법과 허용 목록의 원리는 어느 메신저든 같습니다.
비교표 전체(28줄) · 메신저별 툴셋 · 공식 문서의 메신저별 Setup 쪽 목록

Platform Comparison 전체 — 칸이 똑같은 플랫폼은 한 줄로 묶었습니다(원문은 28줄).

플랫폼음성이미지파일스레드반응입력 중실시간 갱신
Discord · Slack · Matrix · Feishu/Lark✅✅✅✅✅✅✅
Telegram · Mattermost✅✅✅✅—✅✅
Yuanbao (Labs plugin)✅✅✅——✅✅
WhatsApp—✅✅——✅✅
WhatsApp Cloud API · Weixin · QQ · SimpleX✅✅✅——✅—
Photon (iMessage)✅✅✅—✅✅—
BlueBubbles—✅✅—✅✅—
Google Chat—✅✅✅—✅—
Signal · LINE—✅✅——✅—
Email—✅✅✅———
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 APIhermes-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 Serverhermes-api-server전체 도구에서 clarify, text_to_speech 제외(마주 앉은 사람이 없는 창구)
Rafthermes-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 watchdogsystemd 가 관리하는 게이트웨이의 선택 기능. 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 을 아무것도 붙이지 않고 보내면 버튼으로 고르는 화면이 나옵니다.

Telegram — /model 을 보냈을 때 (흐름을 흉내 낸 그림)
/model
내 Hermes 봇(맨 위에 지금 쓰는 모델과 제공자가 표시됩니다)
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 서버(외부 도구를 내주는 프로그램) 다시 읽기
/updateHermes Agent 를 최신 버전으로 업데이트

Interactive Model Picker(Telegram) — 제공자 선택(예: “OpenAI (15)”, 현재 제공자는 “✓ Anthropic (12)”) → 모델 선택(Prev/Next 로 쪽 넘김, Back 은 제공자로, Cancel). /model <name> --global 은 세션이 바뀌어도 유지되게 저장합니다.

대화가 이어지는 방식 — 세션 · 끼어들기 · 백그라운드 · 승인

메신저 대화는 내가 새로 시작하기 전까지 한 세션으로 이어집니다. 원문 표현으로는 “에이전트가 대화 맥락을 기억”하며, 한동안 말이 없었다고 또는 날짜가 바뀌었다고 세션이 초기화되지 않습니다. 새 대화를 원하면 /new(또는 /reset)를 보냅니다. 대화가 길어지면 문맥 압축(오래된 대화를 줄여 요약해 두는 일)은 자동으로 됩니다.

일하는 중에 벌어지는 네 가지 상황을 탭으로 봅니다.

Hermes 가 일하는 도중에 메시지를 보내면, 기본값으로는 지금 하던 일의 방향을 고칩니다. 이미 끝낸 작업 결과는 그대로 남고, 돌고 있던 도구는 안전하게 끝난 뒤 다음 단계에서 내 말이 반영됩니다. 완전히 멈추려면 /stop 입니다.

Telegram (흐름을 흉내 낸 그림)
이 폴더 보고서들 요약해 줘
내 Hermes 봇(일하는 중 …)
아, 3월 것만 해 줘
두 번째 메시지가 새 일로 쌓이지 않고, 하던 일의 방향을 바꿉니다. 아예 그만두게 하려면 /stop.

/bg 뒤에 시킬 일을 적으면 별도의 세션에서 따로 진행됩니다. 그동안 원래 대화는 계속 쓸 수 있고, 끝나면 결과가 같은 대화방으로 옵니다.

Telegram (원문 예시)
/bg Check all servers in the cluster and report any that are down
내 Hermes 봇🔄 Background task started: "Check all servers in the cluster..."
Task ID: bg_143022_a1b2c3
내 Hermes 봇 · 나중에✅ Background task complete …
뜻: “클러스터의 모든 서버를 확인하고 꺼진 것을 알려 줘.” 실패하면 “❌ Background task failed” 와 오류가 옵니다.

주의: 백그라운드 세션은 지금 대화 내용을 모릅니다. /bg 뒤에 적은 글만 받으므로, 필요한 정보를 그 한 줄에 다 적어야 합니다.

에이전트가 위험할 수 있는 명령을 실행하려 하면 대화창에서 먼저 묻습니다. 승인(approval — 위험한 명령을 실행하기 전에 나에게 묻는 것)의 원리는 9장에서 다룹니다.

Telegram (원문 예시)
내 Hermes 봇⚠️ This command is potentially dangerous (recursive delete). Reply "yes" to approve.
no
뜻: “이 명령은 위험할 수 있습니다(하위 폴더까지 삭제). 승인하려면 yes 라고 답하세요.” — yes/y 로 승인, no/n 으로 거절합니다(원문 Exec Approval). /approve · /deny 명령도 있습니다.

에이전트가 어느 쪽으로 할지 물어야 할 때(원문: clarify 도구) Telegram 은 질문을 버튼으로 보여 줍니다.

Telegram (원문 예시)
내 Hermes 봇❓ Which framework should I use for the dashboard?
1. Next.js2. Remix3. Astro✏️ Other (type answer)
버튼을 누르거나, Other 를 누른 뒤 다음 메시지로 직접 답합니다. 기본 90초 안에 답하지 않으면 에이전트는 “답 없음”으로 알고 알아서 진행합니다. 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_progressoff | new | all | verbose | log. log 는 대화창 대신 ~/.hermes/logs/tool_calls.log 에 도구 호출을 한 줄씩 적습니다(5 MB × 백업 3개, 비밀 값은 가려서 기록).
display.tool_progress_commandtrue 면 메신저에서 /verbose 를 쓸 수 있습니다.
display.tool_progress_groupingaccumulate(기본 — 말풍선 하나를 고쳐 가며 표시) | 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 contextgateway.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 을 보냅니다

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

3. 표시 이름을 정합니다

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

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

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

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

5. API 토큰을 받습니다

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

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

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

봇 토큰은 비밀번호처럼 다룹니다 이 토큰을 가진 사람은 누구든 내 봇을 조종할 수 있습니다. 대화방·문서·화면 공유에 올리지 마세요. 새어 나갔다면 곧바로 BotFather 에서 /revoke 로 무효로 만듭니다.
더 쉬운 길 — QR 로 만들기 대시보드와 데스크톱 앱의 Messaging → Telegram(메신저 → Telegram) 쪽에는 Create with QR(QR 로 만들기) 버튼이 있습니다. Telegram 으로 코드를 찍으면(또는 링크를 열면) Hermes 가 봇을 만들고, 내 Telegram 사용자 ID 를 알아내고, 설정 파일에 두 값을 적고, 게이트웨이를 다시 시작합니다. 원문은 이 화면을 이 정도로만 적습니다. 봇을 직접 만들고 싶으면 위 다섯 단계를 따릅니다.
Step 2: 봇 꾸미기(선택) — BotFather 명령과 Hermes 쪽 선택 설정 7가지
BotFather 명령용도
/setdescription대화를 시작하기 전에 보이는 “이 봇은 무엇을 하나요?” 소개 글
/setabouttext봇 프로필 쪽의 짧은 글
/setuserpic봇 프로필 사진
/setcommands명령 메뉴(대화창의 / 버튼). 원문이 권하는 시작 묶음: help · new · sethome
/setprivacy봇이 그룹의 모든 메시지를 볼지(그룹 대화)

Hermes 쪽 선택 설정 — ~/.hermes/config.yaml 의 Telegram extra 아래에 둡니다.

원문 소제목무엇을 하나설정 키
Online/Offline status indicatorTelegram 봇에는 접속 중 초록 점이 없습니다. 켜 두면 게이트웨이가 연결될 때 봇의 짧은 소개 글을 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 같은 숫자입니다.

사용자 이름 (username) @my_name ✗ Hermes 가 찾는 값이 아닙니다 사용자 ID (user ID) 123456789 ✓ 이 숫자를 허용 목록에 넣습니다
둘은 다른 값입니다. 필요한 것은 오른쪽의 숫자입니다.

숫자는 알려 주는 봇에게 물으면 됩니다.

  1. 방법 1 (권장) — @userinfobot 에게 메시지 보내기Telegram 에서 @userinfobot 을 찾아 아무 메시지나 보내면 곧바로 내 사용자 ID 를 답해 줍니다.
  2. 방법 2 — @get_id_bot같은 일을 하는 또 다른 봇입니다.
  3. 숫자를 적어 둡니다다음 단계 Hermes 에 연결하기에서 씁니다.
대화방에도 ID 가 있습니다 봇과 나누는 1:1 대화(DM)의 대화방 ID 는 내 사용자 ID 와 같습니다. 그룹의 대화방 ID 는 -1001234567890 처럼 음수입니다. 홈 채널이나 그룹 허용 설정에서 이 숫자가 나옵니다.

Hermes 에 연결하고 켜기

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

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

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

hermes gateway setup

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

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

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

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

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

hermes gateway

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

Telegram — 내 Hermes 봇 (흐름을 흉내 낸 그림)
안녕, 들려?
내 Hermes 봇(Hermes 의 답이 오면 연결 성공입니다)
TELEGRAM_ALLOWED_USERS 는 꼭 넣습니다 이 값은 “누구의 말을 들을지”를 정하는 허용 목록입니다. 넣지 않으면 게이트웨이는 안전을 위해 모든 사용자를 거절합니다 — 나 자신도 포함됩니다. 봇이 터미널까지 쓸 수 있기 때문에 기본값이 이렇게 닫혀 있습니다.
이렇게 되면먼저 볼 것
봇이 아무 반응도 없다TELEGRAM_BOT_TOKEN 이 맞는지, 게이트웨이가 켜져 있는지 확인합니다
봇이 “unauthorized”(권한 없음)라고 답한다내 사용자 ID 가 TELEGRAM_ALLOWED_USERS 에 없습니다. @userinfobot 으로 숫자를 다시 확인합니다
봇을 늘 켜 두고 싶다hermes gateway 는 지금 창에서 실행하는 방식(foreground)입니다. 계속 켜 두려면 서비스로 설치합니다(hermes gateway install)

누가 내 봇에 말을 걸 수 있나 — 허용 목록

메신저 봇은 주소만 알면 누구나 말을 걸 수 있습니다. 그런데 Hermes 봇은 내 컴퓨터에서 명령을 실행할 수 있습니다. 그래서 게이트웨이의 기본값은 “허용 목록(allowlist — 통과시킬 사람을 적어 둔 명단)에 없고 DM 페어링도 하지 않은 사용자는 전부 거절”입니다. 원문은 이것을 “터미널을 쓸 수 있는 봇을 위한 안전한 기본값”이라고 부릅니다.

나ID 123456789 · 목록에 있음 가족 · 동료목록에 넣어 둔 ID 모르는 사람목록에 없는 ID 허용 목록 확인 TELEGRAM_ALLOWED_USERS 에 있는 ID 인가? 기본값: 전부 거절 Hermes 와 대화 터미널까지 쓸 수 있는 봇 거절 또는 1회용 페어링 코드 안내
허용 목록은 “이 사람이 봇에 닿을 수 있는가”를 정합니다. 닿은 뒤 위험한 명령을 실행해도 되는지는 따로 승인을 거칩니다.

문을 여는 방법은 세 가지이고, 원문은 첫 번째를 권합니다.

① 사람을 지정 (권장)

메신저별 허용 목록에 사용자 ID 를 적습니다. Telegram 은 TELEGRAM_ALLOWED_USERS=123456789,987654321 처럼 쉼표로 잇습니다.

② 모든 메신저 공통 목록

GATEWAY_ALLOWED_USERS=… 에 적습니다.

③ 모두 허용 (비권장)

GATEWAY_ALLOW_ALL_USERS=true. 원문은 터미널을 쓸 수 있는 봇에는 권하지 않는다고 못 박습니다.

DM 페어링(pairing — 1회용 코드로 사람을 짝지어 허용하는 방법)은 ID 를 미리 알아내 적어 두는 대신 쓰는 방법입니다.

  1. 모르는 사용자가 봇에게 DM 을 보냅니다그 사람에게 1회용 코드가 표시됩니다 — 원문 예: Pairing code: XKGH5N7P
  2. 그 사람이 코드를 나에게 알려 줍니다코드는 1시간 뒤 만료되고, 요청 횟수에 제한이 있으며, 암호학적으로 안전한 난수로 만들어집니다.
  3. 내가 터미널에서 승인합니다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 의 설정)가 기본으로 켜져 있고, 원문은 이것을 “그룹에서 봇을 쓸 때 가장 흔한 혼란의 원인”이라고 부릅니다.

개인 정보 보호 모드 켜짐 (기본값) /help 같은 / 명령✓ 보임 봇의 메시지에 단 답글✓ 보임 입장·퇴장·고정 같은 알림✓ 보임 그냥 나눈 대화✗ 안 보임 봇이 관리자인 채널의 메시지도 보입니다 모드 꺼짐 · 또는 봇이 그룹 관리자 /help 같은 / 명령✓ 보임 봇의 메시지에 단 답글✓ 보임 입장·퇴장·고정 같은 알림✓ 보임 그냥 나눈 대화✓ 보임 그룹의 모든 메시지를 받습니다
Telegram 이 봇에게 전해 주지 않은 메시지에는 Hermes 가 답할 수 없습니다. 그룹에서 봇이 조용하면 이것부터 봅니다.

평범한 그룹 대화에도 봇이 반응하게 하려면 개인 정보 보호 모드를 끕니다.

  1. @BotFather 에게 /mybots 를 보냅니다내 봇 목록이 나오면 봇을 고릅니다.
  2. Bot Settings → Group Privacy → Turn off(봇 설정 → 그룹 개인 정보 보호 → 끄기)
  3. 봇을 그룹에서 내보냈다가 다시 넣습니다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_patternsPython 정규식(글자 무늬를 적는 표기법), 대소문자 구분 없음, 글과 미디어 설명 글 모두에 적용. 잘못된 무늬는 경고만 남기고 무시됩니다. 맨 앞에서만 맞게 하려면 ^.
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 — 정해 둔 시간에 자동 실행)은 결과를 이 대화방으로 보냅니다. 내가 묻지 않았는데 오는 메시지이므로, 어디로 받을지를 미리 정해 두는 것입니다.

⏰ 예약 작업 정해 둔 시간 게이트웨이 60초마다 확인하고 실행 홈 채널 /sethome 으로 정한 대화방 결과 메시지가 여기로 옵니다
홈 채널은 1:1 대화든 그룹이든 될 수 있습니다.

정하는 방법은 간단합니다. 결과를 받고 싶은 Telegram 대화방(1:1 대화든 그룹이든)에서 /sethome 을 보냅니다.

Telegram — 내 Hermes 봇 (흐름을 흉내 낸 그림)
/sethome
내 Hermes 봇(이 대화방이 홈 채널로 지정됩니다)

예약 작업의 결과를 어디로 보낼지 고르는 방법 전체는 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 의 동그란 음성 말풍선으로 옵니다.

받을 때 🎤 내 음성 메시지 받아쓰기 (STT)local · groq · openai 글로 바뀌어 대화에 들어감 보낼 때 에이전트의 답 읽어 주기 (TTS)Edge TTS 는 ffmpeg 필요 🔊 동그란 음성 말풍선대화창에서 바로 재생
STT(speech-to-text)는 말을 글로, TTS(text-to-speech)는 글을 말로 바꾸는 기술입니다.

받을 때 — Hermes 에 설정된 받아쓰기 제공자가 음성을 글로 바꿉니다. 고를 수 있는 것은 세 가지입니다.

제공자어디서 받아쓰나필요한 것
localHermes 가 도는 컴퓨터에서 직접(faster-whisper)API 키(서비스 이용 열쇠) 필요 없음
groqGroq WhisperGROQ_API_KEY
openaiOpenAI WhisperVOICE_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 credentialsmy.telegram.org/apps 에서 앱을 만들고 api_id · api_hash 를 받습니다.
Step 2: Run the telegram-bot-api serveraiogram/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 serverconfig.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 it20 MB 넘는 음성을 보내고 ~/.hermes/logs/gateway.log 에 [Telegram] Cached user voice at … 줄이 나오는지 봅니다.

계속 켜 두기 — 서비스로 설치

hermes gateway 는 지금 연 터미널 창에서 게이트웨이를 돌립니다(원문: foreground). 연결이 잘 되는지 시험할 때 알맞습니다. 늘 켜 두려면 hermes gateway install 을 씁니다 — 이 명령은 게이트웨이를 운영체제의 서비스(컴퓨터가 알아서 켜고 지켜 주는 프로그램)로 등록합니다.

그냥 실행 — hermes gateway · 지금 연 터미널 창에서 실행 · 잘 되는지 시험해 볼 때 · 봇이 답하는지 바로 확인 원문: Run in foreground 서비스 — hermes gateway install · 운영체제가 알아서 켜 줍니다 · start · stop · status 로 관리 · 로그인·부팅 때 시작 (설정에 따라) macOS launchd · Linux systemd · Windows 작업 스케줄러
명령 이름은 세 운영체제에서 같고, 뒤에서 일하는 장치만 다릅니다.
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-inHermes 가 설치한 서비스 파일은 이미 깔끔하게 끄고 다시 켭니다. ExecStopPost=/bin/kill -9 $MAINPID 같은 덧설정을 넣으면 다시 시작할 때마다 새 프로세스를 죽여 무한 재시작이 됩니다(Telegram 에 재시작 알림이 쏟아짐). 넣었다면 systemctl --user edit hermes-gateway 로 지우고 systemctl --user daemon-reload.
Direct systemctl restart / stop exits cleanlysystemctl --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 installationsHERMES_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 installplist 는 고정 파일이라, 설치 뒤 새 도구(새 Node.js, ffmpeg 등)를 깔았으면 hermes gateway install 을 다시 실행합니다.
Installing without startinghermes gateway install --no-start-now(또는 마법사의 “Start the gateway now?” 에 No)는 파일만 쓰고, 게이트웨이는 다음 로그인 때 또는 hermes gateway start 때 시작됩니다.
Local Network accesslaunchd 로 뜬 게이트웨이가 집 안 네트워크 기기(Home Assistant, 로컬 모델 서버)에 닿지 못하고 No route to host 가 나던 문제를 피하려고, 게이트웨이를 /usr/bin/osascript 를 거쳐 실행합니다. 그래서 파일 접근 허락 창에는 Hermes 가 아니라 osascript 이름이 나옵니다. 예전 plist 는 hermes gateway install 로 갱신됩니다.
Picking up new credentialshermes 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 .envconfig.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 defaultsTelegram 기본값: 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 worksname(필수) · icon_color · icon_custom_emoji_id · skill · thread_id(자동으로 채워짐 — 직접 넣지 않음). 게이트웨이가 켜질 때 없는 토픽을 만들고 번호를 config.yaml 에 저장합니다. 토픽마다 세션 열쇠가 따로입니다(agent:main:telegram:dm:{chat_id}:{thread_id}).
Root DM handlingignore_root_dm: true 면 토픽을 설정한 사용자의 맨 위 대화는 로비가 되어 일반 메시지는 무시되고 /start·/help·/status 같은 명령만 됩니다.
Skill bindingskill 이 있는 토픽은 새 세션이 시작될 때 그 스킬을 자동으로 불러옵니다 — 대화 첫머리에 /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 modeextra.dm_topics 는 운영자가 설정 파일로 정한 고정 토픽, /topic 은 사용자가 마음대로 만들고 지우는 즉석 세션(맨 위 DM 이 로비가 되고 토픽 이름이 세션 제목을 따라 바뀜). 둘은 한 봇에서 함께 쓸 수 있습니다.
Prerequisites · Activation flowThreads 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_SECRETURL 을 설정했다면 필수. 요청 확인용 비밀 값이며 없으면 게이트웨이가 시작을 거부합니다(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 transportgateway.streaming.enabled: true 일 때 gateway.streaming.transport: auto(기본 — Telegram DM 에서는 글자 단위로 늘어나는 draft 미리 보기, 나머지는 메시지 고치기) · draft · edit(항상 메시지 고치기) · off(최종 답만). 미리 보기가 깜빡이면 edit. 그룹은 Telegram 제한으로 항상 edit 방식입니다.
Rendering: Rich Messages, Tables and Link Previewsrich_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 volumedisplay.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 의 공식 문서, 문서에 버전 표기 없음)

CHAPTER 09

안전장치와 되돌리기

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

이 장에서 배우는 것
  • Hermes 의 안전장치가 몇 겹이고, 각각 무엇을 막는지
  • 위험한 명령을 실행하기 전에 Hermes 가 나에게 어떻게 묻는지, 네 가지 선택지(once · session · always · deny)가 무슨 뜻인지
  • 메신저 봇을 누가 쓸 수 있는지 정하는 두 가지 방법 — 허용 목록과 페어링 코드
  • 명령을 Docker 같은 격리된 곳에서 실행하면 무엇이 달라지는지
  • 체크포인트가 언제 찍히고, /rollback 으로 어떻게 되돌리는지, 되돌릴 수 없는 경우는 언제인지
처음이라면 이것만

「개발자용 참고」로 접힌 상자는 설정 키·예외·관리자용 내용이라 처음에는 건너뛰어도 됩니다.

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

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

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

내가 그때그때 답하는 것

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

내가 미리 정해 두는 것

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

알아서 도는 것

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

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

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

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

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

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

o once — 이번 한 번만

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

s session — 이번 세션 동안

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

a always — 앞으로 계속

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

d deny — 거부 (기본값)

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

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

어떤 명령에서 묻나

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

통째로 지우기

rm -r, find -delete, xargs rm

권한을 활짝 열기

chmod 777, chown -R root

디스크 포맷·덮어쓰기

mkfs, dd if=, > /dev/sd

데이터베이스 지우기

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

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

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

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

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

내려받은 것을 바로 실행

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

명령 하나가 거치는 길

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

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

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

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

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

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

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

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

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

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

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

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

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

YOLO 모드 — 묻지 않고 실행

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

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

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

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

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

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

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

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

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

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

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

approvals 설정 키 전체

~/.hermes/config.yaml 의 approvals: 아래에 둡니다.

키기본값무엇을 정하나
modesmart위험한 셸 명령의 승인 방식 — smart · manual · off.
timeout300승인 답을 기다리는 시간(초).
discord_prompt_timeout300Discord 의 버튼(승인·되묻기·업데이트·슬래시 명령 확인)이 눌리는 시간(초). 최소 30.
cron_modedeny예약 작업이 위험 명령을 만났을 때. deny 는 막고, approve 는 예약 작업 안의 모든 것을 자동 승인.
single_query_modedenyhermes chat -q 한 번짜리 세션이 만났을 때. cron_mode 와 같은 방식.
unattended_modedeny사람 없는 프로그램용 플랫폼(webhook, msgraph_webhook, api_server) 세션이 만났을 때. 시간 초과를 기다리지 않고 바로 판정. 예외: 클라이언트가 승인 카드에 답할 수 있는 api_server 세션(/v1/runs, 스트리밍 chat completions — POST /v1/runs/{id}/approval)은 승인 요청을 그대로 받음.
mcp_reload_confirmtrue/reload-mcp 가 MCP 도구 묶음을 다시 만들기 전에 물음. 다시 만들면 제공자(provider — AI 모델을 빌려주는 서비스) 쪽 프롬프트 캐시가 무효가 되어 다음 메시지에서 입력 토큰을 전부 다시 보냄. Always Approve 를 누르면 false 로 바뀜.
destructive_slash_confirmtrue/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(장치에 직접 쓰기)
SQLDROP 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 오류를 돌려주고, 아무것도 실행되지 않습니다. 설정을 바꾸면 세션을 다시 시작하지 않아도 바로 적용됩니다.
한계(Threat model) 금지 규칙은 “셸 명령 글”에 대한 정책이지 완전한 셸 해석기나 운영체제 수준의 가두기가 아닙니다. 변수, 별칭, 함수, 이름을 바꾼 실행 파일, 스크립트, 인터프리터 프로그램, 모든 셸 문법까지 풀어 보지는 못합니다. 확실히 가두려면 운영체제 권한과, 마운트·자격 증명·네트워크를 알맞게 제한한 격리 백엔드를 쓰라고 원문은 적습니다.

절대 금지 목록은 셸 따옴표를 해석할 수 없는 명령(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 는 대상 경로를 금지 목록과(켜 두었다면) 쓰기 울타리에 대조합니다. 막힌 쓰기는 곧바로 오류로 돌아갑니다. 승인 창이 뜨지 않고, 대화 화면에서 풀 방법도 없습니다.

파일을 쓰려는 요청 write_file · patch 경로 검사 금지 목록 · 쓰기 울타리 보통 파일 → 그대로 씀 내 프로젝트의 문서·코드 등 ~/.ssh/config → 승인을 받고 씀 once · session · always 로 물음 비밀 저장소 → 바로 거절 ~/.ssh 열쇠 · ~/.hermes/.env 등 — 풀 수 없음
파일 쓰기 도구가 거치는 세 갈래. 가운데 갈래(~/.ssh/config)는 원문이 든 유일한 예외입니다.

언제나 막히는 곳은 크게 세 부류입니다.

부류예쉬운 말로
운영체제의 자격 증명(로그인 열쇠·비밀번호 같은 것) 보관 장소~/.ssh/, ~/.aws/, ~/.kube/, /etc/sudoers, ~/.netrc다른 서버·클라우드에 들어가는 열쇠가 있는 곳
Hermes 의 비밀 보관 장소.env, vault/, mcp-tokens/, pairing/ 등(Hermes 홈 폴더 아래)API 키(서비스를 쓸 때 내는 비밀 열쇠 글자)와 로그인 토큰, 페어링 기록
Windows 의 특수 장치 경로\??\..., \\.\... 등경로를 확인하는 것만으로도 로그인 정보가 새어 나갈 수 있는 특수 주소 — 읽기·쓰기 모두 거절
프로젝트 폴더의 .env 는 “쓸 수는 있지만 읽을 수는 없습니다” 프로젝트 안의 .env, .env.local, .env.production, .envrc 파일은 디스크 어디에 있든 파일 도구가 읽기를 거절합니다. 쓰기는 됩니다 — 에이전트가 나 대신 만들거나 고칠 수는 있지만, 안에 든 값을 다시 읽어 올 수는 없습니다.
“고쳤습니다”라는 말보다 확인 표시를 믿으세요 쓰기가 막혔는데도 모델(에이전트의 두뇌 역할을 하는 AI)이 수정에 성공했다고 말할 수 있습니다. 원문은 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. 그 플랫폼이 “모두 허용”인가 예: DISCORD_ALLOW_ALL_USERS=true 2. 페어링 코드로 승인받은 사람인가 DM 페어링 승인 목록 3. 그 플랫폼의 허용 목록에 있는가 예: TELEGRAM_ALLOWED_USERS=12345,67890 4. 공통 허용 목록에 있는가 GATEWAY_ALLOWED_USERS=12345,67890 5. 전체가 “모두 허용”인가 GATEWAY_ALLOW_ALL_USERS=true 6. 여기까지 모두 아니면 → 거절 (기본값) 하나라도 맞으면 통과 Hermes 와 대화 가능
허가 확인 순서(원문의 Authorization Check Order). 처음 쓰는 사람은 2번(페어링)이나 3번(플랫폼별 허용 목록) 가운데 하나만 준비하면 됩니다.

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

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

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

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

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

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

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

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

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

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

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

hermes pairing approve telegram ABC12DEF

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

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

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

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

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

값봇의 행동
pair페어링 코드로 답합니다. 대화형 DM 플랫폼의 기본값입니다.
ignore아무 답 없이 버립니다.
decline짧고 정중한 거절 한 번(“I can only chat with my owner” — 저는 주인하고만 대화할 수 있어요)을 보내고, 그 사람의 이후 메시지를 24시간 동안 무시합니다.
페어링 세부 — 플랫폼별 설정 · 보안 사양 · 저장 위치 · 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(요청 제한·잠금 기록).

Docker 사용자: 페어링 명령은 hermes 사용자로 실행 공식 Docker 이미지는 게이트웨이를 권한 없는 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 — 내 컴퓨터에서 바로 Hermes 명령 내 컴퓨터 파일 · 시스템 명령이 내 컴퓨터에 그대로 닿습니다 위험 명령 검사: 켜짐 위험한 명령은 승인으로 막습니다 알맞은 곳: 개발 · 믿을 수 있는 사용자 docker — 컨테이너 안에서 Hermes 컨테이너 명령은 이 안에서만 실행 안에서 무엇을 지워도 내 컴퓨터는 무사합니다 위험 명령 검사: 건너뜀 컨테이너 자체가 보안 경계이기 때문 알맞은 곳: 계속 켜 두는 메신저 봇
컨테이너(내 컴퓨터 안에 만든, 벽으로 둘러싼 작은 가상 컴퓨터) 안에서 실행하면 파괴적인 명령도 바깥(호스트)을 해칠 수 없어서, Hermes 는 위험 명령 검사를 건너뜁니다.

원문이 정리한 백엔드별 비교입니다.

백엔드격리위험 명령 검사알맞은 곳
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 에 두고 파일 권한을 제대로 겁니다.
5DM 페어링 켜기가능하면 ID 를 적어 두는 대신 페어링 코드를 씁니다.
6허용 명령 목록 점검config.yaml 의 command_allowlist 를 주기적으로 살펴봅니다.
7terminal.cwd 지정에이전트가 민감한 폴더에서 일하지 않게 합니다.
8root 가 아닌 사용자로 실행게이트웨이를 최고 관리자(root)로 돌리지 않습니다.
9기록 살피기~/.hermes/logs/ 에서 허가받지 않은 접근 시도를 확인합니다.
10최신으로 유지hermes update 로 보안 수정을 받습니다.

비밀 값 파일은 나만 읽고 쓸 수 있게 권한을 겁니다. 서비스마다 열쇠를 따로 쓰고, .env 파일을 버전 관리(git 등)에 올리지 않습니다.

chmod 600 ~/.hermes/.env

가장 단단하게 하려면 게이트웨이를 별도의 컴퓨터나 가상 머신에서 돌리고, 에이전트의 명령은 SSH(다른 컴퓨터에 안전하게 접속해 명령을 실행하는 방법)로 또 다른 컴퓨터에서 실행하게 합니다. 메신저 연결과 명령 실행이 서로 다른 곳에 놓입니다.

메신저 Telegram 등 게이트웨이 컴퓨터 Hermes · 메신저 연결 terminal.backend: ssh SSH 작업용 컴퓨터 에이전트의 명령이 실제로 실행되는 곳
네트워크 격리(Network Isolation). 접속 정보는 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 입니다.

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

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

checkpoints:
  enabled: true

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

언제 찍히나

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

파일 도구가 파일을 바꿀 때

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

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

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

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

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

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

체크포인트 설정 키와 동작 원리

~/.hermes/config.yaml 의 checkpoints: 아래에 둡니다.

키기본값뜻
enabledfalse주 스위치. false 면 아무 일도 하지 않고 git 작업을 시도하지도 않습니다.
max_snapshots20프로젝트당 보관하는 체크포인트 수의 상한.
max_total_size_mb500보관소 전체 크기의 상한. 넘으면 가장 오래된 것부터 버립니다.
max_file_size_mb10이보다 큰 파일은 사진에서 뺍니다.
auto_prunetrue자동 정리. 뒤에서(CLI 는 실행 직후, 게이트웨이는 정기 관리 주기에) 마지막 사용이 retention_days 보다 오래된 프로젝트 항목을 지웁니다. 프롬프트나 게이트웨이 시작을 막지 않습니다. false 면 직접 hermes checkpoints prune 을 돌릴 때까지 보관소가 커집니다.
retention_days7자동 정리가 남겨 두는 날 수.
min_interval_hours24자동 정리 사이의 최소 간격(시간).
  • 자동 정리는 “고아” 항목(작업 폴더를 찾을 수 없는 것)은 지우지 않습니다 — 지운 프로젝트인지 아직 연결되지 않은 외장 디스크·네트워크 공유인지 알 수 없기 때문입니다. 고아 정리는 확인 창이 뜨는 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 만 넣어 목록을 봅니다.

터미널 — /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 가 애초에 손대지 않은 파일이면 — 덮어쓰지 않고 건너뛴 뒤 이름을 알려 줍니다.

체크포인트 때 지금 /rollback N 뒤 report.md 원래 내용 Hermes 가 바꿈장부의 지문과 같음 원래 내용으로 복원Hermes 의 변경이 사라짐 notes.md 원래 내용 내가 손으로 고침장부의 지문과 다름 내 수정 그대로 유지건너뛰고 이름을 알려 줌 notes.md 까지 되돌리고 싶다면 → /rollback N --all (내 수정도 덮어씀) 장부가 비어 있으면(예전에 만든 보관소 등) 자동으로 전체 복원이 됩니다
기본 되돌리기는 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 NHermes 가 바꾼 파일을 복원마지막 턴 취소작업 전체를 그때로 돌릴 때
/undo건드리지 않음대화만 되감기방금 주고받은 말만 없던 일로 할 때

되돌리기 전에 미리 보기

/rollback diff 1

1번 체크포인트 이후 무엇이 달라졌는지 보여 줍니다. 먼저 어떤 파일이 얼마나 바뀌었는지 요약(git diff stat)이 나오고, 이어서 실제로 달라진 줄(diff(두 상태의 차이를 줄 단위로 보여 주는 것))이 나옵니다. 원문은 되돌리기 전에 이것으로 알맞은 체크포인트를 고르라고 권합니다.

파일 하나만 되돌리기

/rollback 1 src/broken_file.py

폴더의 나머지는 그대로 두고, 1번 체크포인트에서 그 파일 하나만 가져옵니다.

/undo 는 대화만 되감습니다

/undo 는 대화만 되감고 파일에는 손대지 않습니다. 체크포인트가 켜져 있고 되감은 턴에서 프로젝트 파일이 바뀌었다면, /undo 는 그 파일들의 이름과 함께 /rollback 을 안내하는 한 줄을 덧붙입니다.

터미널 — /undo
/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 백엔드는 영향이 없습니다.
폴더 안에 또 다른 git 저장소가 있다면 프로젝트 폴더 안에 별도의 git 저장소가 들어 있으면(중첩 저장소), 바깥 폴더의 체크포인트는 그 안쪽 파일을 담지 않아 커밋하지 않은 수정을 되살릴 수 없습니다. 이런 체크포인트는 목록에 [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 liststatus 의 다른 이름
hermes checkpoints prune강제 정리 — 고아·오래된 항목 삭제, GC, 크기 상한 적용
hermes checkpoints clear체크포인트 보관 폴더 전체 삭제(먼저 물음)
hermes checkpoints clear-legacyv1 에서 옮겨 온 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, 문서에 버전 표기 없음)

CHAPTER 10

문제 해결과 자주 묻는 질문

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

이 장에서 배우는 것
  • 증상만 보고 어느 소절을 펼칠지 고르는 법
  • 자주 묻는 질문 9가지 — 비용, 내 자료가 어디로 가는지, 인터넷 없이 쓸 수 있는지 등
  • 설치 직후 가장 흔한 hermes: command not found 를 푸는 순서
  • 모델·제공자 오류, 대화가 길어져 생기는 오류, 메신저 봇이 답하지 않을 때의 확인 순서
  • 프로필에 관한 질문 5가지와, 다른 컴퓨터로 옮기기 같은 활용 패턴
  • 그래도 안 풀릴 때 어디에 무엇을 적어 물어볼지
처음이라면 이것만

나머지 소절은 그 증상을 만났을 때 찾아보면 됩니다. 접힌 상자(▸)는 드문 경우와 관리자용 내용입니다.

어디가 막혔나 — 증상으로 소절 찾기

문제를 풀 때 가장 먼저 할 일은 “어디에서 막혔는가”를 가르는 것입니다. 원문은 문제를 설치 · 제공자와 모델 · 터미널 · 메신저 · 성능 · MCP · 스킬 일곱 묶음으로 나눕니다. 이 가이드는 그것을 아래 여섯 갈래로 묶었습니다. 오른쪽 상자를 누르면 그 소절로 갑니다.

어디에서 막혔나요? hermes 를 실행조차 못 한다 command not found · 권한 오류 · 첫 대화 400 설치·실행 문제 답 대신 오류가 온다 API 키 · 모델 이름 · 429 · 거절 문구 모델·제공자 문제 오래 쓰니 느리고 끊긴다 Context length exceeded · 느린 답 · 토큰 과다 긴 대화·속도 문제 명령이 실행되지 않는다 위험 명령 차단 · sudo · Docker 명령 실행 문제 메신저 봇이 조용하다 응답 없음 · 전달 안 됨 · 게이트웨이 시작 실패 메신저 봇 문제 연결한 도구·스킬이 안 보인다 MCP 연결 · 시간 초과 · Skills Hub 403 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 403MCP·스킬 문제
프로필끼리 무엇을 나눠 쓰는지 궁금함프로필 질문 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 PortalNous Research 의 구독형 창구. OAuth(비밀번호를 넘기지 않고 로그인으로 사용 권한을 주는 방식) 로그인 한 번으로 300개가 넘는 모델과 웹·이미지·TTS(글을 소리로 읽어 주는 기능)·브라우저 기능을 씁니다. 처음 쓰는 사람에게 추천
OpenRouterAPI 키(제공자가 나를 알아보는 비밀번호 같은 문자열) 하나로 수백 가지 모델을 씁니다. 여러 모델을 오가며 쓰려는 사람에게 추천
OpenAIGPT-5.4, GPT-5-codex, GPT-4.1, GPT-4o 등
AnthropicClaude 모델. 직접 API, hermes auth add anthropic 으로 하는 OAuth, OpenRouter, 또는 호환 프록시(중간에서 요청을 대신 전달해 주는 서버)
GoogleGemini 모델. gemini 제공자로 직접 API, OpenRouter, 또는 호환 프록시
z.ai / ZhipuAIGLM 모델
Kimi / Moonshot AIKimi 모델
MiniMax글로벌용과 중국용 접속 주소
로컬 모델Ollama, vLLM, llama.cpp, SGLang, 또는 OpenAI 호환 서버 아무것이나

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

내 자료는 어디로 가나요?

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

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

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

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

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

로컬 모델 — 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_ctxOllama 에서 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 로 이어 붙이는 방식을 권합니다.

  1. Hermes 는 WSL2 안에서 실행평소대로 씁니다.
  2. Chrome 은 Windows 의 것을 그대로이미 로그인해 둔 평소 Chrome 을 계속 씁니다.
  3. chrome-devtools-mcp 를 MCP 서버로 추가cmd.exe 나 powershell.exe 를 거쳐 실행되게 등록합니다.
  4. 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 에 추가합니다. 그런데 설치 전부터 열려 있던 터미널은 예전 목록을 그대로 들고 있습니다.

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

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

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

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

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

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

which hermes
ls ~/.local/bin/hermes

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

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

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

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

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

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

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

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

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

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

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

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

여기서 안 풀리면 설치 뒤 자주 나는 실패와 복구 순서는 1장의 「자주 나는 실패」와 「복구 순서」에도 정리되어 있습니다.
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   # 또는 키를 직접 저장
키와 제공자는 짝이 맞아야 합니다 OpenAI 의 키는 OpenRouter 에서 통하지 않고, 반대도 마찬가지입니다. ~/.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 은 하는 일이 다릅니다

대화 밖 — 터미널에서 hermes model 새 제공자 추가 · OAuth 로그인 API 키 입력·변경 · 접속 주소 설정 재료를 들여놓는 곳 대화 안 — 입력 칸에서 /model provider:model 이미 설정해 둔 제공자·모델 사이에서만 전환 설정한 제공자가 하나면 그것만 보임 들여놓은 재료 중에서 고르는 곳 새 제공자는 왼쪽에서 추가 → 새 대화를 시작 → 오른쪽 목록에 나타남
대화 중인 화면에서는 제공자를 새로 추가할 수 없습니다. 먼저 Ctrl+C 나 /quit 로 대화를 끝냅니다.
하고 싶은 일쓸 것
새 제공자 추가hermes model (터미널에서)
API 키 입력·변경hermes model (터미널에서)
대화 도중 모델 바꾸기/model <name> (대화 안에서)
설정해 둔 다른 제공자로 바꾸기/model provider:model (대화 안에서)

“Hermes 정책 때문에 못 한다”는 답을 들었을 때

에이전트가 “Hermes policy” 나 “Hermes guardrails” 때문에 요청을 거절한다고 말로만 답할 때가 있습니다. 원문의 설명은 이렇습니다. 모델은 자기가 왜 거절했는지를 믿을 만하게 알아내지 못합니다. 숨은 Hermes 정책 탓이라는 말은 모델이 지어낸 설명이거나, 고른 모델·제공자 쪽에서 건 제한일 수 있습니다.

Hermes 가 막았다면 — 흔적이 남습니다

  • 막힌 명령이나 경로의 이름이 적힌 도구 오류가 나옵니다.
  • 승인이 필요한 동작이면 승인을 묻는 창이 뜹니다.
  • Hermes 는 이런 실행 통제를 “내용을 이유로 한 거절”로 조용히 바꾸지 않습니다.

글로만 거절한다면 — 모델·제공자 쪽입니다

  • 도구 오류도 승인 창도 없이 문장으로만 거절합니다.
  • 모델을 바꾸면 거절이 달라집니다.
  • 제공자 쪽 통제(예: Amazon Bedrock Guardrails)는 설정되어 있으면 적용될 수 있습니다.
  1. /status 를 입력합니다지금 쓰는 모델과 제공자를 확인합니다.
  2. 거절에 도구 오류나 승인 창이 있는지 봅니다글뿐이라면 “Hermes 탓”이라는 모델의 말을 증거로 삼지 않습니다.
  3. 새 세션에서 다른 모델·제공자로 다시 해 봅니다모델에 따라 달라지는 거절은 모델·제공자의 동작이지 Hermes 의 실행 통제가 아닙니다.
  4. 도구 오류가 분명히 나왔다면문제를 알릴 때 그 문구를 한 글자도 바꾸지 말고 그대로 적습니다.

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 가 내 모델의 컨텍스트 길이를 잘못 알고 있거나.

컨텍스트 — 모델이 한 번에 볼 수 있는 글의 양 한도 대화와 도구 결과가 쌓일수록 차오릅니다 → 한도를 넘으면 Context length exceeded /compress 지금 대화를 요약해 줄이기 (막대가 줄어드는 순간) hermes chat 새 세션에서 다시 시작 (빈 막대에서 출발) 더 큰 모델로 컨텍스트가 큰 모델 고르기 (막대 자체가 길어짐) 원문이 권하는 세 가지 해결 방법
막대가 한도에 닿기 전에 줄이거나, 새로 시작하거나, 더 긴 막대를 가진 모델로 바꿉니다.
/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 를 틈틈이 /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 데몬(뒤에서 계속 돌며 일하는 프로그램)이 꺼져 있거나 내 사용자에게 권한이 없습니다.아래 접힌 상자의 세 단계
승인 물음은 의도된 동작입니다 Hermes 는 파괴적인 명령을 조용히 실행하지 않습니다. 승인 창에는 실제로 실행될 명령이 그대로 보입니다. 위험 명령의 전체 목록과 승인 방식은 9장 「승인」, sudo 다루기는 4장, 터미널 백엔드는 4장 「백엔드」에 있습니다.
Docker 백엔드가 연결되지 않을 때 확인 명령
docker info                       # Docker 가 돌고 있는지 확인
sudo usermod -aG docker $USER     # 내 사용자를 docker 그룹에 추가
newgrp docker
docker run hello-world            # 되는지 시험

메신저 봇 문제

Telegram 같은 메신저에서 Hermes 를 쓰려면 게이트웨이가 계속 켜져 있어야 합니다(8장 「설정」). 내 메시지는 메신저 → 게이트웨이 → Hermes → 모델 서비스를 차례로 거치므로, 어느 고리에서 끊겼는지에 따라 증상이 다릅니다.

나 Telegram 등 메신저 게이트웨이 계속 켜 둔 프로그램 Hermes 에이전트 AI 모델 서비스 제공자 아무 답이 없다 게이트웨이가 꺼져 있음 권한이 없음 · 허용 목록에 없음 hermes gateway status 보낸 글이 전달되지 않는다 네트워크 · 봇 토큰 만료 웹훅 설정 오류 hermes gateway setup 짧은 오류 문구가 답으로 온다 모델 서비스와의 연결 문제 문구 세 가지로 원인을 구분 /retry · hermes doctor
윗줄은 메시지가 지나는 길, 아랫줄은 끊긴 자리마다 보이는 증상과 먼저 쓸 명령입니다.

봇이 답하지 않을 때 — 세 단계

원인은 셋 중 하나입니다. 봇(게이트웨이)이 돌고 있지 않거나, 권한이 없거나, 내 사용자가 허용 목록에 없습니다.

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 를 써 보려면 켜져 있는지부터 확인합니다.

  1. /etc/wsl.conf 를 엽니다없으면 새로 만듭니다.
  2. 아래 두 줄을 넣습니다[boot] 와 그 아랫줄 systemd=true
  3. PowerShell 에서 wsl --shutdown그다음 WSL 터미널을 다시 엽니다.
  4. 확인: 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 서버가 요청 도중 죽으면 Hermes 는 그것을 시간 초과로 알립니다. 진짜 원인을 찾으려면 Hermes 기록만 보지 말고 그 서버 자체의 기록을 봅니다.

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 가 답하는 다섯 가지를 그림 하나로 먼저 봅니다.

컴퓨터 한 대 — hermes update 는 한 번이면 모든 프로필에 적용 프로필 A 기억 세션 스킬 봇 토큰 A — 이 프로필 전용 에이전트는 프로필 하나에 하나만 ✕ 공유 안 함 프로필 B 기억 세션 스킬 봇 토큰 B — 이 프로필 전용 에이전트는 프로필 하나에 하나만
프로필끼리는 기억·세션·스킬 폴더를 나눠 쓰지 않고, 메신저 봇 토큰도 하나씩 따로 가져야 합니다.
질문답
두 프로필이 같은 봇 토큰을 써도 되나요?안 됩니다. 메신저 플랫폼(Telegram, Discord 등)은 봇 토큰 하나를 한 곳에서만 쓰게 합니다. 두 프로필이 동시에 같은 토큰을 쓰면 두 번째 게이트웨이가 연결에 실패합니다. 프로필마다 봇을 따로 만듭니다 — Telegram 이라면 @BotFather 에게 말을 걸어 봇을 더 만듭니다(8장).
프로필끼리 기억이나 세션을 나눠 쓰나요?아닙니다. 프로필마다 자기 기억 저장소, 세션 데이터베이스, 스킬 폴더가 있고 완전히 분리되어 있습니다. 지금 프로필의 기억과 세션을 가지고 새 프로필을 시작하려면 hermes profile create newname --clone-all 로 전부 복사합니다. 특정 프로필에서 복사하려면 --clone-from <profile> 을 덧붙입니다.
hermes update 를 하면 어떻게 되나요?최신 코드를 받아 오고 필요한 구성 요소를 한 번만 다시 설치합니다(프로필마다 하지 않음). 그다음 갱신된 스킬을 모든 프로필에 자동으로 맞춥니다. 한 번 실행하면 그 컴퓨터의 모든 프로필에 적용됩니다.
프로필을 몇 개까지 돌릴 수 있나요?정해진 한도는 없습니다. 실제 한계는 디스크 공간과, 동시에 켜 둘 수 있는 게이트웨이 수입니다(게이트웨이 하나는 가벼운 Python 프로세스). 수십 개도 괜찮고, 쉬고 있는 프로필은 자원을 쓰지 않습니다.
그냥 HERMES_HOME 을 정하는 것과 무엇이 다른가요?프로필은 HERMES_HOME(Hermes 가 자료를 두는 폴더를 가리키는 설정값) 위에 얹은 관리 기능입니다. 손으로 해야 할 일을 대신 해 줍니다(자세한 것은 아래 접힌 상자).
프로필 하나에는 에이전트 하나만 같은 프로필(또는 같은 Hermes 홈 폴더)에 에이전트 둘을 동시에 붙이지 않습니다. 둘 다 기억을 자동으로 쓰고, 세션을 시작할 때 서로가 쓴 것을 읽어 들이기 때문에 세션을 거듭할수록 저장된 내용이 나빠집니다. 여러 에이전트가 정말로 기억을 함께 써야 한다면 원문은 외부 기억 제공자(external memory provider)를 쓰라고 합니다.
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                   # 되돌림
/model 을 자주 오가면 비용이 듭니다 모델을 바꿀 때마다 프롬프트 캐시(같은 앞부분을 다시 읽지 않게 해 주는 임시 저장)가 초기화됩니다. 바꾼 직후의 첫 메시지는 대화 전체를 제값의 입력 요금으로 다시 읽습니다. 긴 세션에서는 왔다 갔다 하기보다 위임(하위 에이전트는 자기만의 새 컨텍스트를 받음)이나 새 세션을 쓰라고 원문은 권합니다. 위임은 7장.

상황. 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 컴퓨터로 전부 옮기려 합니다.

  1. 새 컴퓨터에 Hermes 를 설치합니다curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
  2. 원래 컴퓨터에서 전체 백업을 만듭니다hermes backup — ~/hermes-backup-<timestamp>.zip 이 생깁니다. 설정, 인증 정보, 기억, 스킬, 세션, 프로필이 들어갑니다. 프로그램 자체나 실행 환경의 복사본은 아닙니다.
  3. zip 을 새 컴퓨터로 복사해 불러옵니다원래 컴퓨터에서 scp ~/hermes-backup-<timestamp>.zip newmachine:~/, 새 컴퓨터에서 hermes import ~/hermes-backup-<timestamp>.zip
  4. 새 컴퓨터에서 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 backuphermes profile export
쓰임새컴퓨터를 통째로 옮길 때프로필 하나를 옮기거나 나눠 줄 때
범위Hermes 자료 폴더 전체(일부 제외 — 아래 접힌 상자)프로필 폴더 하나
들어가는 것모든 프로필, 공통 설정, API 키, 세션그 프로필의 SOUL.md, 기억, 세션, 스킬
인증 정보포함 (.env 와 auth.json)제외 (안전하게 나눠 줄 수 있게 뺌)
파일 형식.zip.tar.gz
전체 백업 파일에는 내 API 키가 들어 있습니다 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 의 공식 문서)