시작 전 준비 — 설치하고, 제공자를 고르고, 대화가 되는지 확인하기
Hermes Agent 는 Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트(말만 하는 챗봇과 달리, 도구를 써서 내 대신 일을 해 주는 AI 프로그램)입니다. 실습 1~10 을 하기 전에 딱 세 가지만 끝냅니다. 설치하고, 두뇌가 될 모델을 빌려줄 곳을 고르고, 말을 걸어 답이 오는지 봅니다.
- 터미널(글자로 명령을 입력하는 창)에 명령 한 줄을 넣어 Hermes 를 설치합니다.
hermes model로 제공자(provider — AI 모델을 빌려주는 서비스)와 모델(에이전트의 두뇌 역할을 하는 AI)을 고릅니다.hermes로 첫 대화를 열고, 원문이 적은 성공 기준 네 가지로 확인합니다.
예상 소요 시간: 15~20분 (원문은 설치 자체는 2분 안쪽이라고 적습니다. 제공자 가입·로그인에 드는 시간은 따로입니다.)
준비물을 확인한 뒤 따라 하기 1~4단계를 순서대로 진행하세요. 막히면 막히면에서 같은 증상을 찾습니다. 원문의 원칙은 하나입니다 — 평범한 대화 한 번이 깨끗하게 되기 전에는 다른 기능을 얹지 않습니다.
준비물과 완료 기준
- macOS 또는 Linux 컴퓨터와 터미널. 이 실습은 터미널에서 설치하는 길을 따라갑니다. 터미널은 macOS 라면 기본 앱 터미널(Spotlight 에서 “터미널” 검색)을 열면 됩니다 — 이 안내는 Hermes 문서가 아니라 운영체제의 일반 사용법입니다. 데스크톱 앱 설치·Windows·Android 는 1단계의 접힌 상자에 원문이 적은 만큼만 옮겼습니다.
- 인터넷 연결. 설치 스크립트가 프로그램을 내려받고, 대화할 때도 제공자와 통신합니다.
- 제공자 계정 하나. 원문이 처음 쓰는 사람에게 권하는 길은 Nous Portal 구독입니다. 이미 쓰는 서비스(OpenRouter·Anthropic 등)가 있으면 그 계정이나 API 키(서비스가 나를 알아보는 비밀 문자열)를 준비합니다.
- 설치 스크립트가 쓰는 기본 프로그램 — Git, curl, tar, SHA-256 유틸리티. 원문은 macOS·Linux 스크립트에 이 넷이 필요하다고 적습니다.
① 배너에 내가 고른 모델·제공자가 보입니다. ② Hermes 가 오류 없이 답합니다. ③ 필요할 때 도구(tool — 터미널 실행·파일 읽기·웹 검색 같은 기능 하나)를 쓸 수 있습니다. ④ 대화가 한 번 넘게 정상으로 이어집니다. 원문은 여기까지 되면 "가장 어려운 고비를 넘었다"고 적습니다.
따라 하기
1단계 · 터미널에 설치 명령 한 줄 넣기
터미널을 열고 아래 한 줄을 그대로 붙여 넣은 뒤 Enter 를 누릅니다. macOS·Linux·WSL2 공통입니다.
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash뜻: 공식 설치 스크립트를 내려받아 바로 실행합니다. 스크립트는 프로그램을 내려받고, 필요한 부품(Python·Node.js 등)을 스스로 준비하고, hermes 라는 실행 명령을 만들고, 내 설정과 기록이 쌓일 데이터 폴더를 준비합니다.
- 진행 중에는 단계마다 상태 줄이 하나씩 나옵니다. 어떤 단계가 실패하면 그 단계의 마지막 줄들과 기록 파일(
logs/install.log) 위치를 알려 줍니다. - 터미널에서 직접 실행하면 설치 끝에 설정 질문이 바로 이어질 수 있습니다. 그때는 3단계 설명을 보며 답하면 됩니다.
원문은 설치 프로그램을 sudo(관리자 권한으로 실행하는 명령)와 함께 쓰지 말라고 적습니다. 실행 명령은 내 홈 폴더 아래 ~/.local/bin 에 놓이기 때문입니다. ~ 는 "내 홈 폴더"를 뜻하는 기호입니다.
확인: 실패했다는 줄 없이 스크립트가 끝났습니다. 실패 줄이 보이면 그 문구와 기록 파일 위치를 적어 두고 실습 9로 갑니다.
다른 설치 길 — 데스크톱 앱 · Windows · Android
| 환경 | 원문이 적은 방법 |
|---|---|
| 데스크톱 앱 (macOS) | Hermes 웹사이트에서 받은 DMG 를 열고 Hermes.app 을 Applications 로 복사합니다. 원문은 macOS 설치 파일이 Apple Silicon 전용이고, Intel 프로세서 Mac 은 지원 플랫폼이 아니라고 적습니다. |
| 데스크톱 앱 (Windows) | 내려받은 .appinstaller 를 Windows App Installer 로 엽니다. |
| Windows (명령 줄만) | PowerShell 에서 iex (irm https://hermes-agent.nousresearch.com/install.ps1) |
| Android | aarch64 기기에서 Termux APT 패키지를 씁니다. 위 스크립트는 Termux 용이 아닙니다. |
| 명령 줄 설치 뒤 데스크톱 앱도 쓰고 싶을 때 | hermes desktop |
데스크톱 앱의 화면 구성은 받은 원문에 설명이 거의 없어 이 실습은 터미널만 다룹니다. 설치 방법별 상세는 완전 가이드 1장 설치·미리 갖출 것.
2단계 · 터미널이 hermes 명령을 알아보게 하기
방금 만든 hermes 명령을 지금 열려 있는 터미널은 아직 모릅니다. 터미널의 설정을 다시 읽게 합니다.
source ~/.bashrc # or: source ~/.zshrc뜻: 셸(터미널 안에서 명령을 받아 실행하는 프로그램) 설정 파일을 다시 읽습니다. 쓰는 셸이 bash 면 앞의 것, zsh 면 source ~/.zshrc 를 넣습니다. 어느 쪽인지 모르겠으면 터미널 창을 닫고 새로 열어도 같은 효과입니다(원문: 새 터미널은 바뀐 경로를 자동으로 읽습니다).
which hermes
ls ~/.local/bin/hermes뜻: hermes 명령이 어디에 있는지 묻고, 설치 위치에 실제로 파일이 있는지 봅니다.
확인: which hermes 가 경로 한 줄을 내놓습니다. 설치 스크립트 기준으로 그 자리는 ~/.local/bin/hermes 입니다. hermes: command not found 가 나오면 막히면 첫 줄을 봅니다.
3단계 · 제공자와 모델 고르기
원문이 "가장 중요한 설정 단계"라고 부르는 곳입니다. Hermes 는 스스로 생각하는 두뇌가 없고, 제공자가 빌려주는 모델을 두뇌로 씁니다. 내 상황에 맞는 탭 하나를 고릅니다.
hermes setup --portal뜻: Nous Portal 에 로그인하고, Nous 를 제공자로 정하고, Tool Gateway(웹 검색·그림 만들기·음성·클라우드 브라우저 도구 묶음)까지 명령 하나로 켭니다. 원문은 구독 하나로 300개 넘는 모델과 Tool Gateway 를 함께 쓴다고 적습니다. API 키를 따로 관리하지 않아도 됩니다.
hermes model뜻: 제공자와 모델을 묻고 답하는 방식으로 차례차례 고릅니다. 제공자에 따라 브라우저 로그인(OAuth)이나 API 키 입력을 요구합니다. 원문의 조언은 "제공자를 고르고, 바꿔야 할 이유를 아는 것이 아니면 기본값을 그대로 받아들이라"입니다.
hermes setup뜻: 모든 설정을 한 번에 묻는 설정 마법사를 엽니다. 처음 설치한 상태라면 세 가지 방식 중 하나를 고르게 됩니다 — 아래 접힌 상자 참고.
컨텍스트(문맥 창 — 모델이 한 번에 기억하며 볼 수 있는 글의 양)가 64,000 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)보다 작은 모델은 시작할 때 거부됩니다. 원문은 Claude·GPT·Gemini·Qwen·DeepSeek 같은 대부분의 호스팅 모델은 이 기준을 쉽게 넘는다고 적습니다. 제공자는 나중에 hermes model 로 언제든 바꿀 수 있습니다.
hermes config show | head -20뜻: 지금 저장된 설정의 앞 20줄을 보여 줍니다. 어떤 모델과 제공자가 잡혀 있는지 확인하는 용도입니다.
확인: 설정 과정이 오류 없이 끝났고, 위 명령의 결과에 내가 고른 모델·제공자가 보입니다. 진짜 확인은 다음 단계의 배너와 첫 답입니다.
hermes setup 의 세 가지 방식과 다른 도구에서 옮겨 오기
| 방식 | 무엇을 하나 |
|---|---|
| Quick Setup (Nous Portal) | 브라우저 로그인만으로 모델과 Tool Gateway 도구를 설정합니다. 관리할 API 키가 없고 요금은 Nous Portal 구독으로 청구됩니다. 원문이 권하는 빠른 길입니다. |
| Full Setup | 제공자·도구·옵션을 하나씩 직접 고릅니다(내 키를 가져와 씁니다). |
| Blank Slate | 에이전트를 돌리는 최소한(제공자와 모델, 파일 작업·터미널 툴셋(toolset — 도구 꾸러미))만 켜고 나머지는 모두 끈 채 시작합니다. 필요한 것만 골라 켜려는 사람용입니다. 나중에 hermes tools 로 다시 켤 수 있습니다. |
OpenClaw·Claude Code·Codex CLI·Cursor 가 컴퓨터에 있으면, 처음 실행한 hermes setup 이 먼저 그 설정을 가져올지 묻습니다. 제공자 전체 목록은 완전 가이드 1장 제공자 고르기, 두 설정 파일은 설정이 저장되는 곳.
4단계 · 첫 대화 열고 말 걸어 보기
Hermes 는 터미널 화면이 두 가지입니다. 둘은 세션(대화 한 묶음)·슬래시 명령·설정을 똑같이 함께 씁니다.
hermes # classic CLI
hermes --tui # modern TUI (recommended)뜻: 첫 줄은 기본 화면인 클래식 CLI(터미널에서 글자로 쓰는 프로그램 화면), 둘째 줄은 새 터미널 화면인 TUI 를 엽니다. 원문은 TUI 를 권합니다. 이 실습도 hermes --tui 를 기준으로 삼습니다.
화면이 열리면 맨 위에 환영 배너가 나옵니다. 배너에는 내 모델, 쓸 수 있는 도구, 스킬(특정 일을 하는 방법을 적은 설명서)이 보입니다. 입력 칸에 아래처럼 넣고 Enter 를 누릅니다.
Hello뜻: 인사 한마디입니다. 답이 오는지만 보는 것이므로 한국어로 인사해도 됩니다.
확인: 배너에 3단계에서 고른 모델·제공자가 보이고, Hermes 가 오류 없이 답합니다. 답이 비어 있거나 깨져 보이면 막히면으로 갑니다.
5단계 · 한 번 더 주고받고 끝내기
대화가 이어지는지, 도구를 쓸 수 있는지 보려고 한 번 더 말을 겁니다. 원문이 "터미널 써 보기" 예시로 드는 문장입니다.
What's my disk usage? Show the top 5 largest directories.뜻: 내 디스크를 얼마나 쓰고 있어? 가장 큰 폴더 다섯 개를 보여 줘. — 에이전트가 내 대신 터미널 명령을 실행하고 결과를 보여 줍니다.
- 너무 오래 걸리면 새 메시지를 입력하고 Enter 를 누릅니다. 하던 일을 멈추고 새 지시로 넘어갑니다. Ctrl+C 도 됩니다.
- 입력 칸에
/를 치면 슬래시 명령(입력 칸에 /로 시작해 넣는 명령) 목록이 뜹니다./help는 쓸 수 있는 명령을 모두 보여 줍니다. - 끝낼 때는
/quit을 넣습니다.
확인: 두 번째 질문에도 오류 없이 답이 왔습니다. 완료 기준 네 가지가 모두 채워졌다면 준비 끝입니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
hermes: command not found | 셸이 바뀐 경로를 아직 읽지 않았습니다. source ~/.bashrc(zsh 는 source ~/.zshrc)를 넣거나 터미널을 새로 엽니다. 그래도 안 되면 which hermes·ls ~/.local/bin/hermes 로 설치 위치를 봅니다. |
설치 중 Permission denied | sudo 로 설치했는지 봅니다. 고치는 순서는 실습 9에 있습니다. |
API key not set | hermes model 로 제공자를 다시 설정합니다. 키를 직접 넣으려면 hermes config set OPENROUTER_API_KEY your_key 처럼 씁니다(your_key 자리에 내 키). |
| Hermes 는 열리는데 답이 비거나 깨짐 | 원문이 꼽는 원인은 제공자 로그인이나 모델 선택이 잘못된 것입니다. hermes model 을 다시 실행해 제공자·모델·로그인을 확인합니다. |
| 시작하자마자 모델이 거부됨 | 컨텍스트가 64K 토큰보다 작은 모델일 수 있습니다. hermes model 로 다른 모델을 고릅니다. |
슬래시 명령에 Unsupported gateway CLI command; use /help | 클래식 CLI 에서는 일부 슬래시 명령만 됩니다. 원문은 전체 명령을 쓰려면 hermes --tui 를 쓰라고 적습니다. |
| 무엇이 문제인지 모르겠음 | hermes doctor 를 실행합니다. 원문은 이 명령이 무엇이 빠졌고 어떻게 고치는지 정확히 알려 준다고 적습니다. 이어서 실습 9의 순서를 따릅니다. |
다음에 할 것
- 실습 1 — 내 폴더를 살펴보게 하고 요약을 받습니다. 첫 "쓸모 있는 결과"입니다.
- 실습 2 — 오늘 한 대화에 이름을 붙이고 다음 날 다시 불러옵니다.
- 메신저 연결·예약 작업·스킬 설치는 그다음입니다. 원문은 기본 대화가 되고 난 뒤에만 한 겹씩 얹으라고 적습니다. 무엇을 얹을 수 있는지는 완전 가이드 1장 다음에 얹을 것.
- 설치는 터미널에 명령 한 줄.
sudo는 붙이지 않습니다. - 설치 뒤
source ~/.bashrc(또는~/.zshrc)나 새 터미널로hermes명령을 알아보게 합니다. - 제공자는
hermes model, 가장 쉬운 길은hermes setup --portal. 모델은 컨텍스트 64K 토큰 이상. hermes --tui로 열어 말을 걸고, 성공 기준 네 가지를 확인합니다.- 평범한 대화가 되기 전에는 다른 기능을 얹지 않습니다. 모르겠으면
hermes doctor.
출처: hermes-agent.nousresearch.com/docs/getting-started/installation · getting-started/quickstart · user-guide/cli(Interface Layout 의 슬래시 명령 범위) · reference/faq(Installation Issues). 수집일 2026-11-09. 가이드 1장 설치·첫 대화·자주 겪는 실패. 예상 소요 시간은 이 활용편의 어림값입니다.
첫 결과 — 내 폴더를 살펴보게 하고 요약 받기
Hermes Agent 에게 첫 일을 맡깁니다. 내 컴퓨터의 폴더 하나를 직접 들여다보게 하고, 무엇이 들어 있는지 요약을 받습니다. 말만 하는 챗봇과 달리 도구를 써서 실제로 폴더를 읽는다는 점을 눈으로 확인하는 실습입니다.
- 살펴볼 폴더에서 Hermes 를 열고, 지금 어느 폴더를 보고 있는지 배너에서 확인합니다.
- 에이전트(도구를 써서 내 대신 일을 해 주는 AI 프로그램)가 도구를 쓰는 과정을 화면에서 읽습니다.
- 요약을 받고, 일이 길어지면 중간에 바로잡습니다.
예상 소요 시간: 10~15분
준비물과 완료 기준
- 시작 전 준비를 끝낸 상태 —
hermes로 대화가 됩니다. - 살펴볼 폴더 하나. 코드 저장소든 문서 폴더든 괜찮습니다. 이번 실습은 읽기만 부탁하지만, 처음에는 남에게 보여도 되는 내용의 폴더로 연습합니다 — 폴더 내용이 내가 고른 제공자(provider — AI 모델을 빌려주는 서비스)에게 전달되기 때문입니다(원문: API 호출은 내가 설정한 제공자에게만 갑니다).
- 그 폴더의 위치(경로). 터미널(글자로 명령을 입력하는 창)에서 그 폴더로 이동할 수 있어야 합니다.
Hermes 가 오류 없이 답했고, 답에 나온 파일 이름이 내 폴더에 실제로 있으며, 이어서 한 번 더 물었을 때도 정상으로 답하면 완료입니다. 원문이 첫 대화에 "구체적이고 확인하기 쉬운" 부탁을 쓰라고 하는 이유가 이 대조입니다.
따라 하기
1단계 · 살펴볼 폴더에서 Hermes 열기
Hermes 는 자기가 시작된 폴더를 "작업 폴더"로 삼습니다. 그래서 먼저 터미널에서 살펴볼 폴더로 이동한 다음 Hermes 를 엽니다.
cd 살펴볼-폴더-경로
hermes --tui뜻: 첫 줄은 터미널의 기본 명령으로, 그 폴더로 이동합니다(살펴볼-폴더-경로 자리에 실제 경로). 둘째 줄은 Hermes 를 TUI(hermes --tui 로 여는 새 터미널 화면)로 엽니다. hermes 만 넣어 기본 화면으로 열어도 이 실습은 똑같이 됩니다.
화면 맨 위 환영 배너를 읽습니다. 원문은 배너가 모델(에이전트의 두뇌 역할을 하는 AI), 터미널 백엔드(에이전트의 명령이 실제로 실행되는 곳), 작업 폴더, 쓸 수 있는 도구(tool — 터미널 실행·파일 읽기 같은 기능 하나), 설치된 스킬을 한눈에 보여 준다고 적습니다.
확인: 배너의 작업 폴더가 내가 살펴보려는 폴더입니다. 다르면 /quit 으로 나가 폴더를 옮긴 뒤 다시 엽니다 — 작업 폴더는 세션(대화 한 묶음)을 만들 때 정해지고 그 뒤로는 바뀌지 않습니다.
폴더를 옮기지 않고 여는 방법
원문은 --in <dir> 를 주면 시작하거나 이어 하기 전에 그 폴더로 들어간다고 적습니다. 원문의 예시는 이어 하기와 함께 쓴 hermes --tui --resume latest --in ./my-project(그 폴더의 가장 최근 세션을 이어서 열기)입니다. 실행 방법 전체는 완전 가이드 2장 실행하기.
2단계 · 폴더를 살펴보라고 부탁하기
입력 칸에 아래 문장을 넣고 Enter 를 누릅니다. 원문이 첫 대화 예시로 드는 문장입니다.
Check my current directory and tell me what looks like the main project file.뜻: 지금 폴더를 확인하고, 중심이 되는 파일이 무엇으로 보이는지 알려 줘. — 같은 뜻의 한국어로 물어도 됩니다.
Hermes 가 일하는 동안 화면에 진행 줄이 생깁니다. 원문은 에이전트가 터미널 명령을 내 대신 실행하고 결과를 보여 준다고 적습니다. 기본 화면(클래식 CLI 의 modern 배치)에서는 줄 맨 앞 기호로 종류를 구분합니다. TUI 의 줄 모양은 받은 원문에 따로 적혀 있지 않습니다. 기호가 조금 달라도 "내 말 → 도구가 한 일 → 답" 순서로 읽으면 됩니다.
확인: 오류 없이 답이 왔고, 답에 나온 파일·폴더 이름이 내 폴더에 실제로 있습니다. 파일 탐색기(Finder 등)로 폴더를 열어 한두 개만 대조해 봅니다.
진행 표시를 더 자세히 또는 덜 보기
원문이 보여 주는 도구 진행 줄 예시는 ┊ 💻 terminal `ls -la` (0.3s) 같은 모양입니다. /verbose 를 넣을 때마다 표시 단계가 off → new → all → verbose 순으로 바뀝니다. 화면 구성 전체는 완전 가이드 2장 화면 구성, 도구가 무엇인지는 4장 도구란.
3단계 · 다섯 줄 요약 받기
같은 대화에서 이어서 묻습니다. 새로 설명할 필요가 없습니다 — 앞에서 읽은 내용이 대화에 남아 있습니다.
Summarize this repo in 5 bullets and tell me what the main entrypoint is.뜻: 이 저장소를 다섯 줄로 요약하고, 시작점이 되는 파일이 무엇인지 알려 줘. — "저장소(repo)"는 코드를 모아 둔 폴더를 가리키는 말입니다. 문서 폴더라면 같은 뜻의 한국어로 "이 폴더를 다섯 줄로 요약해 줘"처럼 바꿔 물어도 됩니다.
답을 읽을 때는 세 가지를 봅니다. 다섯 줄이 맞는지, 각 줄이 내 폴더의 실제 내용과 맞는지, 모르는 것을 아는 척 채우지 않았는지입니다. 어긋난 줄이 있으면 몇 번째 줄이 어떻게 틀렸는지 그대로 짚고, 그 파일을 다시 읽어 고쳐 달라고 합니다.
확인: 요약이 왔고 내용이 폴더와 맞습니다. 이것으로 원문의 성공 기준 "대화가 한 번 넘게 정상으로 이어진다"까지 채웠습니다.
4단계 · 길어지거나 방향이 틀리면 중간에 바로잡기
에이전트가 너무 오래 걸리거나 엉뚱한 쪽으로 가면 끝나기를 기다릴 필요가 없습니다.
- 새 메시지를 입력하고 Enter진행 중인 일을 멈추고 새 지시로 방향을 바꿉니다. 이미 끝낸 도구 작업과 화면에 나온 생각은 대화에 그대로 남습니다.
- 또는 Ctrl+C입력 칸에 쓰던 글이 있으면 먼저 그 글을 지우고, 입력 칸이 비어 있으면 에이전트를 멈춥니다. 2초 안에 두 번 누르면 Hermes 가 강제로 끝납니다.
이 단계는 지금 꼭 해 보지 않아도 됩니다. 2·3단계가 금방 끝났다면 방법만 읽고 넘어갑니다.
확인: (해 봤다면) 새 메시지를 보낸 뒤 Hermes 가 그 지시에 맞춰 답했습니다.
Enter 가 하는 일을 바꾸기 — /busy
일하는 중에 Enter 를 눌렀을 때의 동작은 세 가지 가운데 고를 수 있습니다. 기본값 interrupt 는 지금 차례의 방향을 바꾸고, queue 는 지금 일이 끝난 뒤 다음 차례로 줄을 세우고, steer 는 멈추지 않고 다음 도구 호출 뒤에 끼워 넣습니다. 대화 안에서 /busy queue·/busy steer·/busy interrupt·/busy status 로 바꾸고 확인합니다. 지금 차례와 하던 작업을 아예 취소하려면 /stop. 자세한 것은 완전 가이드 2장 중간에 끼어들기.
5단계 · 상태 줄을 읽고 대화 끝내기
입력 칸 근처의 상태 줄에는 지금 쓰는 모델, 컨텍스트(문맥 창 — 모델이 한 번에 기억하며 볼 수 있는 글의 양)를 얼마나 썼는지, 작업 폴더가 보입니다. 폴더를 많이 읽을수록 컨텍스트 사용률이 올라갑니다.
다 봤으면 /quit 을 넣어 끝냅니다. 원문은 CLI 세션을 끝낼 때 hermes --resume … 로 시작하는 "이어 하기 명령"과 세션 ID 가 출력된다고 적습니다. 지우지 말고 그대로 둡니다 — 실습 2에서 씁니다.
확인: 상태 줄에서 모델 이름과 컨텍스트 사용률을 찾았고, 대화를 끝냈습니다.
컨텍스트 색이 뜻하는 것
| 색 | 사용률 | 뜻 |
|---|---|---|
| 초록 | 50% 미만 | 여유 있음 |
| 노랑 | 50~80% | 차고 있음 |
| 주황 | 80~95% | 한도에 가까움 |
| 빨강 | 95% 이상 | 넘치기 직전 — /compress(대화 압축)를 고려 |
숫자 앞의 ~ 는 어림값이 섞였다는 표시입니다. 자세한 내역은 /usage 로 봅니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| 답이 비어 있거나 깨져 보임 | 제공자 로그인이나 모델 선택이 잘못됐을 가능성이 큽니다. 나가서 hermes model 을 다시 실행합니다. 순서는 실습 9. |
| 엉뚱한 폴더를 살펴봄 | 배너의 작업 폴더를 확인합니다. 작업 폴더는 세션을 만들 때 정해지므로, /quit 으로 나가 원하는 폴더로 이동한 뒤 새로 엽니다. |
| 명령을 실행해도 되느냐고 물음 | 위험할 수 있는 명령(예: rm -rf)을 실행하기 전에 Hermes 가 먼저 묻는 승인 절차입니다. 화면에 실행될 명령이 그대로 보이니 읽고, 괜찮으면 y 로 승인합니다. 읽기만 부탁했는데 지우는 명령이 보이면 승인하지 말고 더 안전한 방법을 쓰라고 부탁합니다. 9장 승인. |
| 답이 너무 느림 | 4단계 방법으로 끼어들 수 있습니다. 원문이 꼽는 원인은 큰 모델, 먼 서버, 도구가 많아 무거워진 요청입니다. 더 빠른 모델로 바꾸거나 네트워크 상태를 확인합니다. |
| 429 오류(요청 한도 초과) | 제공자의 사용 한도를 넘은 것입니다. 잠시 기다렸다가 다시 보냅니다. |
슬래시 명령(입력 칸에 /로 시작해 넣는 명령)에 Unsupported gateway CLI command; use /help | 클래식 CLI 에서는 일부 슬래시 명령만 됩니다. hermes --tui 로 열면 전체를 쓸 수 있습니다. |
다음에 할 것
- 실습 2 — 방금 한 대화에 이름을 붙이고 다시 불러옵니다.
- 같은 방법으로 다른 폴더도 살펴보게 해 봅니다. 폴더마다 Hermes 를 새로 열면 됩니다.
- 파일을 고치는 일을 맡기기 전에는 실습 5(실수 되돌리기)를 먼저 해 두면 마음이 놓입니다.
- 입력 칸에서 쓸 수 있는 단축키와 명령은 완전 가이드 2장 단축키·슬래시 명령.
- 살펴볼 폴더로 이동한 뒤 Hermes 를 열고, 배너에서 작업 폴더를 확인합니다.
- 구체적이고 확인하기 쉬운 부탁을 하고, 답을 실제 폴더와 대조합니다.
- 줄 맨 앞 기호로 내 말(❯)·도구가 한 일(📖 💻)·답(☤)을 구분합니다.
- 길어지면 새 메시지 + Enter 나 Ctrl+C 로 끼어듭니다.
- 끝낼 때 나오는 이어 하기 명령은 실습 2에서 씁니다.
출처: hermes-agent.nousresearch.com/docs/getting-started/quickstart(3. Run Your First Chat · 5. Try Key Features) · user-guide/cli(Interface Layout · Status Bar · Redirecting the Agent Mid-Turn · Tool Progress Display · Session Management) · reference/faq(Is my data sent anywhere? · Terminal Issues · Performance Issues). 수집일 2026-11-09. 가이드 1장 첫 대화·써 보기. cd 는 터미널 기본 명령이고, 폴더 경로와 한국어로 바꿔 묻는 문장은 연습용 예시입니다.
이어서 하기 — 세션에 이름 붙이고 다시 불러오기
Hermes Agent 는 대화를 끝내도 내용을 버리지 않습니다. 대화 한 묶음을 세션이라고 부르고, 모든 세션을 내 컴퓨터에 저장해 둡니다. 세션에 이름을 붙여 두면 다음 날 그 이름으로 불러 하던 일을 그대로 이어 갈 수 있습니다.
- 대화 중에
/title로 세션에 알아보기 쉬운 이름을 붙입니다. hermes sessions list로 지난 세션을 찾습니다.- 가장 최근 것 · 이름 · 세션 ID, 세 가지 방법으로 다시 불러옵니다.
예상 소요 시간: 10분
준비물을 확인한 뒤 따라 하기를 순서대로 진행하세요. 급하면 1단계(이름 붙이기)와 4단계(이름으로 다시 열기)만 해도 됩니다. 막히면 막히면에서 같은 증상을 찾습니다.
준비물과 완료 기준
- 시작 전 준비를 끝낸 상태. 실습 1을 했다면 그때 쓴 폴더를 그대로 씁니다.
- 세션에 붙일 이름 하나. 이 실습은 원문 예시인
my project를 씁니다. 규칙은 셋입니다 — 다른 세션과 겹치지 않을 것, 100자 이하, 한글·이모지도 됨. - 터미널(글자로 명령을 입력하는 창) 창 하나. 처음부터 끝까지 같은 창에서 합니다.
이름 붙인 세션이 목록에 보이고, 그 이름으로 다시 열었을 때 지난 대화 요약이 나오며, 앞 내용을 다시 설명하지 않고 한 번 더 주고받으면 완료입니다.
따라 하기
1단계 · 대화를 열고 이름 붙이기
연습할 폴더에서 Hermes 를 열고, 대화에 내용이 생기도록 한마디 부탁합니다. 실습 1에서 쓴 문장을 그대로 써도 됩니다.
hermes --tui뜻: Hermes 를 TUI(hermes --tui 로 여는 새 터미널 화면)로 엽니다. 슬래시 명령(입력 칸에 /로 시작해 넣는 명령) 전체를 쓸 수 있는 화면이라 이 실습은 TUI 로 합니다.
Check my current directory and tell me what looks like the main project file.뜻: 지금 폴더를 확인하고, 중심이 되는 파일이 무엇으로 보이는지 알려 줘.
답이 오면 입력 칸에 아래처럼 넣습니다.
/title my project뜻: 지금 세션의 이름을 my project 로 정합니다. 원문은 이름이 바로 적용된다고 적습니다.
- 이름을 붙이지 않아도 첫 주고받기가 끝나면 Hermes 가 3~7 단어짜리 제목을 자동으로 만들어 붙입니다. 내가 직접 붙이면 자동 제목은 건너뜁니다.
- 자동 제목은 무슨 대화였는지는 알려 주지만 내가 기억하는 말이 아닐 수 있습니다. 다시 찾을 대화라면 직접 붙이는 편이 찾기 쉽습니다.
확인: 오류 문구 없이 명령이 받아들여졌습니다. 클래식 CLI 에서는 제목이 생기면 상태 표시줄 오른쪽 끝에 제목이 나타난다고 원문이 적습니다. 화면에서 찾지 못해도 괜찮습니다 — 3단계 목록에서 다시 확인합니다.
2단계 · 대화 끝내고 이어 하기 명령 받아 두기
입력 칸에 /quit 을 넣어 대화를 끝냅니다. 원문은 CLI 세션을 끝내면 아래와 같은 안내가 출력된다고 적습니다.
세션 ID 는 세션마다 하나씩 붙는 고유 번호입니다. 이름을 잊어도 이 번호로 다시 열 수 있으니 메모장에 복사해 둡니다.
확인: hermes --resume … 로 시작하는 줄을 찾아 복사해 두었습니다. 안내가 보이지 않았다면 건너뜁니다 — 다음 단계 목록에서도 ID 를 볼 수 있습니다.
3단계 · 목록에서 내 세션 찾기
터미널에 아래 명령을 넣습니다. Hermes 대화 안이 아니라 터미널에 넣는 명령입니다.
hermes sessions list뜻: 최근 세션을 보여 줍니다(기본 20개). 제목이 붙은 세션이 있으면 아래 같은 모양입니다 — 원문 예시입니다.
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읽는 법: Title(제목) · Preview(대화 미리 보기) · Last Active(마지막으로 쓴 때) · ID(세션 ID 앞부분). 제목이 없는 세션은 — 로 나옵니다.
확인: Title 칸에 my project 가 있습니다. 같은 줄의 Preview 와 Last Active 를 보고 방금 한 대화가 맞는지 대조합니다.
목록 좁히기 · 터미널에서 이름 바꾸기
| 명령 | 하는 일 |
|---|---|
hermes sessions list --limit 50 | 더 많이 봅니다. 다 못 보여 줬을 때는 목록 끝에 더 있다는 안내가 붙습니다. |
hermes sessions list --workspace my-project | 작업 폴더 이름(또는 경로 일부)이 맞는 세션만 봅니다. |
hermes sessions list --source telegram | 어디에서 한 대화인지로 거릅니다(예: Telegram). |
hermes sessions rename 20250305_091523_a1b2c3d4 "refactoring auth module" | 세션 ID 를 지정해 제목을 붙이거나 바꿉니다. 대화 안에서 /title 이 되지 않을 때도 이 방법을 씁니다. |
세션 관리 명령 전체는 완전 가이드 2장 세션·이름 붙이기.
4단계 · 세 가지 방법으로 다시 불러오기
다시 여는 방법은 세 가지입니다. 탭을 눌러 하나씩 읽고, 오늘은 이름으로를 해 봅니다.
hermes -c "my project"뜻: my project 라는 이름의 세션을 이어서 엽니다. 이름에 띄어쓰기가 있으므로 큰따옴표로 감쌉니다.
hermes --continue # Resume the most recent session
hermes -c # Short form뜻: 가장 최근 세션을 이어서 엽니다. 둘째 줄은 같은 명령의 짧은 꼴입니다. 방금 하던 일을 바로 이을 때 가장 빠릅니다.
hermes --resume 20260225_143052_a1b2c3뜻: 세션 ID 를 지정해 그 세션을 엽니다. 2단계에서 복사해 둔 줄을 그대로 붙여 넣으면 됩니다(숫자는 내 것으로). 짧은 꼴은 -r 입니다.
~ 는 내 홈 폴더, state.db 는 Hermes 가 세션을 모아 두는 파일입니다.다시 열면 입력 칸 위에 Previous Conversation(지난 대화) 패널이 나옵니다. 내가 한 말(금색 ●)과 Hermes 의 답(초록 ◆)을 최근 10번 주고받은 것까지 줄여 보여 주고, 도구 호출은 개수와 이름만 한 줄로 접어 보여 줍니다. 패널은 요약일 뿐이고, 에이전트(도구를 써서 내 대신 일을 해 주는 AI 프로그램)는 이전 메시지·도구 호출·응답을 전부 봅니다. 원문 표현으로는 "자리를 뜬 적이 없는 것처럼"입니다.
확인: 지난 대화 패널에 1단계에서 보낸 문장이 보입니다. ↪ restored workspace dir: … 줄이 나오면 그 세션의 작업 폴더로 돌아갔다는 뜻입니다.
이어 하기에서 알아 둘 세부
- 터미널마다 따로 기억합니다. 이름 없이 쓴
hermes -c는 같은 터미널 창(또는 칸)에서 마지막으로 하던 세션을 엽니다. 창 두 개에서 각각 다른 대화를 했다면 각자 자기 대화로 돌아갑니다. 그 터미널의 기록이 없으면 전체에서 가장 최근 세션을 엽니다.-c "이름"과--resume은 이 규칙과 무관합니다. - 작업 폴더도 돌아갑니다. 이어 하기는 그 세션이 기록해 둔 작업 폴더로 이동합니다. 원문 Sessions 쪽은 지금 폴더에 머물려면
--no-restore-cwd를 주라고 적고, CLI 쪽은 클래식 CLI 가 이 옵션을 거절할 수 있으며 거절 메시지가 대신 쓸 방법을 알려 준다고 적습니다. - ID 는 앞부분만 넣어도 됩니다. 다른 세션과 겹치지 않는 앞부분이면 됩니다.
latest는 "가장 최근"을 뜻하는 예약어라hermes --resume latest는hermes -c와 같습니다. - TUI 로 이어 열기. 원문의 예시는
hermes --tui --resume latest --in ./my-project(그 폴더의 가장 최근 세션을 TUI 로) 하나입니다. - 요약 패널을 끄고 한 줄만 보려면
~/.hermes/config.yaml의display:아래에resume_display: minimal을 둡니다(기본값full).
5단계 · 이어서 한마디 주고받기
다시 열린 대화에서 하던 이야기를 이어서 한마디 보냅니다. 폴더가 어디인지, 앞에서 무엇을 봤는지 다시 설명하지 않습니다. 그래도 답이 앞 내용과 이어지는지가 이 단계에서 볼 것입니다. 실습 1의 두 번째 문장을 써도 됩니다.
Summarize this repo in 5 bullets and tell me what the main entrypoint is.뜻: 이 저장소를 다섯 줄로 요약하고, 시작점이 되는 파일이 무엇인지 알려 줘.
확인: Hermes 가 폴더를 다시 묻지 않고 앞 대화에 이어서 답했습니다. 끝낼 때는 /quit — 이름은 그대로 남으므로 다음에도 hermes -c "my project" 로 엽니다.
참고로, 대화가 아주 길어지면 목록의 이름이 아래처럼 바뀌어 보일 수 있습니다. 고장이 아닙니다.
hermes -c "my project" 는 그중 가장 최근 것을 엽니다.막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
hermes --continue 가 지난 세션을 찾지 못함 | 원문이 꼽는 원인은 프로필(설정·기억·세션을 따로 쓰는 별도 Hermes 환경)을 바꿨거나 세션이 저장되지 않은 경우입니다. hermes sessions list 로 목록을 보고, 같은 프로필에서 실행했는지 확인합니다. |
hermes -c 가 다른 대화를 엶 | 이름 없는 -c 는 그 터미널 창에서 하던 세션을 엽니다. 원하는 세션을 이름(-c "이름")이나 ID(--resume)로 지정합니다. |
No session found matching '…' | 그 이름이나 ID 의 세션이 없다는 뜻입니다. hermes sessions list 에서 제목 철자를 확인합니다. |
/title 에 Unsupported gateway CLI command; use /help | 클래식 CLI 에서는 일부 슬래시 명령만 됩니다. hermes --tui 로 열어 다시 넣거나, 터미널에서 hermes sessions rename 으로 이름을 붙입니다(3단계 접힌 상자). |
| 이름이 이미 쓰이고 있다는 오류 | 제목은 세션마다 달라야 합니다. 날짜나 주제를 덧붙여 다른 이름을 씁니다. |
제목 뒤에 #2·#3 이 붙어 있음 | 정상입니다. 압축으로 이어진 세션입니다. 번호 없이 원래 이름으로 부르면 가장 최근 것이 열립니다. |
~/.hermes/sessions/sessions.json 을 열어 보니 내 세션이 없음 | 정상입니다. 그 파일은 메신저 연결용 기록이고 세션 목록이 아닙니다. 목록은 hermes sessions list 로 봅니다. |
| 목록에 정말로 세션이 없음 | Hermes 를 열 때 ⚠ Session store unavailable 경고가 나오는지 봅니다. 고치는 순서는 실습 10. |
다음에 할 것
- 실습 3 — 세션이 달라도 나를 기억하도록 말투와 취향을 남깁니다. 이어 하기는 "그 대화"를 되살리고, 기억은 "모든 대화"에 따라옵니다.
- 일을 시작할 때마다 이름을 먼저 붙이는 습관을 들입니다. 한 주제에 한 세션, 한 이름이 찾기 쉽습니다.
- 지난 세션을 내용으로 찾는 법과 저장 위치는 완전 가이드 2장 세션 검색·저장 위치.
- 세션은 대화 한 묶음이고, 끝내도 내 컴퓨터에 남습니다.
- 대화 중
/title 이름으로 이름을 붙입니다. 이름은 겹치지 않게, 100자 이하. hermes sessions list로 찾고,hermes -c "이름"으로 다시 엽니다.- 방금 하던 것은
hermes -c, 정확히 하나를 고를 때는hermes --resume ID. - 다시 열면 지난 대화 요약이 보이고, 에이전트는 앞 내용을 전부 압니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/sessions(How Sessions Work · CLI Session Resume · Session Naming · Session Management Commands · Storage Locations) · user-guide/cli(Interface Layout · Status Bar · Session Management) · getting-started/quickstart(4. Verify Sessions Work · Common Failure Modes). 수집일 2026-11-09. 가이드 1장 이어 하기 확인·2장 세션. 세션 ID·목록 출력은 원문 예시이고, 예상 소요 시간은 이 활용편의 어림값입니다.
나를 기억시키기 — 기억과 SOUL.md 로 말투·취향 남기기
Hermes Agent 에게 내 취향 한 가지를 기억시키고, 그것이 정말 파일에 적혔는지 눈으로 확인한 뒤, 새 대화에서도 기억하는지 봅니다. 이어서 SOUL.md 파일에 원하는 말투를 적어 Hermes 의 기본 성격을 정합니다.
- 취향 한 가지를 기억시키고, 기억 파일을 열어 실제로 저장됐는지 확인합니다.
- 방금 저장한 기억이 왜 새 세션에서야 보이는지 이해합니다.
SOUL.md로 기본 말투를 정하고,/personality로 잠깐만 다른 말투를 씁니다.
예상 소요 시간: 15~20분
준비물을 확인한 뒤 따라 하기 1~3단계(기억)만 먼저 해도 됩니다. 4~5단계(말투)는 이어서 하거나 나중에 합니다. 기억이 안 남은 것 같으면 막히면에서 같은 증상을 찾습니다.
준비물과 완료 기준
- 실습 0·실습 1을 마쳐 터미널(글자로 명령을 입력하는 창)에서
hermes로 대화가 되는 상태. - 터미널 창 2개 — 하나는 Hermes 와 대화하는 창, 다른 하나는 파일 내용을 확인하는 창입니다.
- 기억시킬 내용 한 가지. 오래 변하지 않는 취향이 좋습니다(예: 짧은 답을 좋아한다, 미터법 단위를 쓴다).
- 평소 쓰는 글 편집기(4단계에서
SOUL.md를 고칠 때 씁니다).
① 기억 파일(USER.md 또는 MEMORY.md)에 내가 말한 내용이 적혀 있고, ② 새 세션(대화 한 묶음 — 시작부터 끝까지의 기록)에서 다시 알려 주지 않아도 Hermes 가 그 내용을 알고 있으며, ③ ~/.hermes/SOUL.md 에 내가 쓴 말투 지침이 저장돼 있으면 완료입니다.
Hermes 는 작은 공책 두 권을 갖고 있습니다. 대화가 끝나면 머릿속은 비워지지만 공책은 남고, 다음 대화를 시작할 때 공책부터 읽습니다. 이 실습은 그 공책에 한 줄을 적게 하고, 정말 적혔는지 들여다보는 연습입니다.
따라 하기
1단계 · 기억시킬 내용을 말로 부탁하기
첫 번째 터미널 창에서 hermes 를 실행해 대화를 시작하고, 아래처럼 한 줄을 보냅니다.
Remember that I prefer metric units.
뜻: "나는 미터법 단위(m, kg)를 더 좋아한다는 걸 기억해 줘." 원문이 드는 요청 형식 Remember that …(…를 기억해 줘)에 원문의 기억 예시 User prefers metric units 를 넣은 연습 문장입니다. that 뒤를 내 취향으로 바꿉니다.
원문에 따르면 Hermes 는 부탁하지 않아도 취향·환경 사실·바로잡은 내용을 스스로 저장합니다. 다만 지나가듯 말한 것까지 다 남기지는 않으므로, 꼭 남길 것은 이렇게 분명히 부탁합니다.
확인: Hermes 가 오류 없이 답했습니다. "기억했다"는 말이 보여도 아직 믿지 않습니다 — 그 문장은 글일 뿐이고, 실제 저장은 다음 단계에서 파일로 확인합니다.
~/.hermes/memories/ 폴더의 두 파일입니다. 취향처럼 "나"에 대한 것은 USER.md, 환경·규칙처럼 "일"에 대한 것은 MEMORY.md 에 적힙니다.무엇이 기억되고 무엇은 안 되나 (원문 기준)
| 저장하는 것 | 저장하지 않는 것 |
|---|---|
| 사용자 취향, 환경 사실, 바로잡아 준 내용, 프로젝트 규칙, 끝낸 일, 분명히 부탁한 것 | 너무 뻔하거나 막연한 정보, 다시 찾기 쉬운 사실, 긴 코드·로그 같은 큰 자료, 그 세션에서만 쓰는 임시 정보, 이미 SOUL.md·AGENTS.md 에 있는 내용 |
글자 수 한도를 넘는 저장은 조용히 버려지지 않고 오류로 돌아오며, Hermes 가 낡은 항목을 줄이거나 지워 자리를 만든 뒤 다시 저장합니다. 자세한 내용은 완전 가이드 5장 · 두 가지 기억.
2단계 · 파일에 정말 적혔는지 확인하기
두 번째 터미널 창을 열고 아래 두 줄을 차례로 실행합니다. cat 은 파일 내용을 화면에 보여 주는 명령이고, ~ 는 내 홈 폴더를 뜻합니다.
cat ~/.hermes/memories/MEMORY.md
cat ~/.hermes/memories/USER.md
뜻: 에이전트의 메모장과 사용자 프로필을 차례로 보여 줍니다. 취향은 보통 USER.md 쪽에 적힙니다.
확인: 둘 중 한 파일에 내가 말한 내용(예: metric units)이 한 줄로 보입니다.
보이지 않는다면 Hermes 가 저장 도구를 쓰지 않고 말로만 답한 것입니다. 원문은 이럴 때 도구를 쓰라고 분명히 부탁하라고 합니다. 원문 예시는 아래와 같고, save 뒤를 내 내용으로 바꿔 보냅니다.
use the memory tool to save the vault path /srv/vault
뜻: "memory 도구를 써서 보관함 경로 /srv/vault 를 저장해 줘." 보낸 뒤 위의 cat 두 줄을 다시 실행해 확인합니다.
3단계 · 새 세션에서 기억하는지 확인하기
대화 창으로 돌아와 입력 칸에 슬래시 명령(/ 로 시작해 넣는 명령) /new 를 넣어 새 세션을 시작합니다. 지금 대화를 닫는 명령이라, 정말 진행할지 확인을 물을 수 있습니다.
/new
새 세션에서 기억시킨 내용이 드러날 만한 질문을 하나 합니다. 단위를 기억시켰다면 거리나 무게를 묻는 식입니다. 이번에는 취향을 다시 알려 주지 않습니다.
확인: 다시 말하지 않았는데도 답에 내 취향이 반영돼 있습니다.
원문은 같은 Hermes 홈 폴더에 에이전트 두 개를 동시에 붙이지 말라고 합니다. 기억이 자동으로 적히기 때문에 서로의 메모가 뒤섞입니다. 두 번째 창은 cat 확인에만 쓰고, 새 세션은 대화 창에서 /new 로 엽니다.
4단계 · SOUL.md 에 기본 말투 적기
기억이 "사실과 취향"을 적는 공책이라면, SOUL.md 는 Hermes 가 어떤 말투와 태도로 말할지를 정하는 파일입니다. Hermes 는 이 파일이 없으면 기본 파일을 자동으로 만들어 두고, 이미 있는 내 파일은 덮어쓰지 않습니다. 먼저 지금 내용을 봅니다.
cat ~/.hermes/SOUL.md
뜻: 지금의 성격 파일 내용을 보여 줍니다. 이제 평소 쓰는 글 편집기로 이 파일을 열어 원하는 말투를 적고 저장합니다. 아래는 원문 예시에서 고른 줄입니다.
# Personality
## Style
- Be direct without being cold
- Prefer substance over filler
- Admit uncertainty plainly
- Keep explanations compact unless depth is useful
## What to avoid
- Sycophancy
- Hype language
- Overexplaining obvious things
뜻: [말투] 차갑지 않게, 그러나 돌려 말하지 않기 · 군말보다 알맹이 · 모르는 것은 모른다고 말하기 · 깊이가 필요할 때가 아니면 설명은 짧게. [피할 것] 아첨 · 과장된 표현 · 뻔한 것을 길게 설명하기.
| SOUL.md 에 적을 것 | 적지 않을 것 (프로젝트 폴더의 AGENTS.md 로) |
|---|---|
| 어조, 말하는 방식, 얼마나 직설적일지, 피할 표현, 확실하지 않거나 의견이 다를 때의 태도 | 한 번뿐인 작업 지시, 파일 경로, 특정 프로젝트의 규칙, 잠깐 쓰는 작업 절차 |
원문의 구분법은 간단합니다. 어디서나 나를 따라와야 하면 SOUL.md, 한 프로젝트에만 해당하면 AGENTS.md 입니다.
저장한 뒤 대화 창에서 /new 로 새 세션을 열고 아무 질문이나 해 봅니다.
확인: cat ~/.hermes/SOUL.md 에 내가 쓴 줄이 보이고, 새 세션의 답이 적어 둔 말투에 가까워졌습니다.
SOUL.md 가 읽히는 규칙
- Hermes 는
~/.hermes/SOUL.md(정확히는 그 Hermes 의 홈 폴더$HERMES_HOME/SOUL.md)만 읽습니다. 지금 작업 중인 폴더에 둔SOUL.md는 읽지 않습니다 — 프로젝트를 옮길 때마다 성격이 바뀌지 않게 하기 위해서입니다. - 파일이 비어 있거나 읽을 수 없으면 Hermes 에 내장된 기본 성격으로 돌아갑니다.
- 내용은 보안 검사를 거치고, 너무 길면 잘린 뒤 그대로 들어갑니다. 성격·말투에 집중해 적습니다.
5단계 · 잠깐만 다른 말투 쓰기 — /personality
기본 말투는 그대로 두고 이번 대화에서만 분위기를 바꾸고 싶을 때는 /personality 를 씁니다. SOUL.md 가 평소 목소리라면 이것은 잠깐 켜는 모드입니다.
/personality
/personality concise
/personality none
뜻: 첫 줄은 고를 수 있는 말투 목록 보기, 둘째 줄은 concise(짧고 요점만) 말투 켜기, 셋째 줄은 덧씌운 말투를 끄고 SOUL.md 의 기본으로 돌아가기입니다. 한 줄씩 넣어 봅니다.
확인: /personality 만 넣으면 목록에 none 과 함께 고를 수 있는 이름이 나오고 지금 켜진 것이 표시됩니다. /personality none 을 넣으면 다음 메시지부터 기본 말투로 돌아옵니다.
기본으로 들어 있는 말투 14가지
helpful(친근한 도우미) · concise(짧게) · technical(자세하고 정확한 기술 전문가) · creative(틀 밖의 발상) · teacher(예시를 드는 참을성 있는 선생님) · kawaii · catgirl · pirate(해적 선장) · shakespeare · surfer · noir(탐정 소설풍) · uwu · philosopher · hype. 끌 때는 none·default·neutral 가운데 아무거나 씁니다. 나만의 말투를 설정 파일에 추가하는 방법은 완전 가이드 5장 · 성격 바꾸기.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| "기억했다"고 답했는데 새 세션에서 모름 | 2단계의 cat 으로 파일부터 봅니다. 줄이 없으면 저장이 일어나지 않은 것입니다. use the memory tool to save … 로 분명히 부탁하고 다시 확인합니다. 원문은 작은 로컬 모델(대략 30B 파라미터 미만)이나 도구 호출이 약한 모델에서 흔한 일이며, 계속되면 지시를 늘리기보다 더 강한 모델로 저장하라고 합니다. |
| 파일에는 있는데 지금 대화가 모름 | 기억은 세션 시작 때 한 번 읽힙니다. /new 로 새 세션을 연 뒤 다시 물어봅니다. |
| 파일이 비어 있거나 다른 내용임 | 기억은 프로필(설정·기억·세션을 따로 쓰는 별도 Hermes 환경)마다 따로입니다. hermes -p work 처럼 프로필을 지정해 썼다면 ~/.hermes/profiles/work/memories/ 를 봐야 합니다. hermes profile list 로 어떤 프로필이 있는지 확인합니다. |
| 저장이 대기 중인 것 같음 | 설정에서 write_approval: true 를 켰다면 저장 전에 내 허락이 필요합니다. 터미널 대화에서는 그 자리에서 묻고, 그 밖(메신저·백그라운드 검토)에서 생긴 저장은 대기 목록에 쌓여 승인 전에는 파일에 적히지 않습니다. /memory pending 으로 목록을 보고 /memory approve all 로 반영합니다. |
| 아무리 부탁해도 저장되지 않음 | 설정 memory.memory_enabled: false 이면 기억 도구가 아예 없습니다. ~/.hermes/config.yaml 을 확인합니다. .env 에 적은 값은 인증 정보·설정일 뿐 기억이 아닙니다. |
| SOUL.md 를 고쳤는데 말투가 그대로 | 고친 파일이 ~/.hermes/SOUL.md 인지(작업 폴더의 것은 읽지 않음), 비어 있지 않은지 봅니다. /personality 로 켜 둔 말투가 있으면 /personality none 으로 끄고, /new 로 새 세션에서 확인합니다. |
원문은 반복 작업마다 필요한 위치 정보 같은 것은 기억보다 스킬에 두라고 권합니다. 스킬은 필요할 때만 읽히고, 2,200자 한도를 차지하지 않습니다. 스킬은 실습 4에서 다룹니다.
다음에 할 것
- 실습 4 — 스킬을 찾아 설치하고 슬래시 명령으로 써 봅니다.
- 기억이 사라진 것 같은 문제가 계속되면 실습 10의 점검 순서를 따릅니다.
- 더 알고 싶다면: 5장 · 기억이란, 5장 · 기억했다더니 잊었을 때, 5장 · SOUL.md.
- 기억은
~/.hermes/memories/의MEMORY.md(에이전트 메모)와USER.md(나에 대한 것) 두 파일입니다. - "기억했다"는 말보다 파일을 믿습니다 —
cat으로 확인합니다. - 저장한 기억은 새 세션부터 보입니다.
/new로 경계를 만듭니다. - 기본 말투는
~/.hermes/SOUL.md, 잠깐 바꾸는 말투는/personality, 끄기는/personality none.
출처: hermes-agent.nousresearch.com/docs/user-guide/features/memory · user-guide/features/personality · user-guide/security(슬래시 명령 확인 물음). 가이드 5장 기억·5장 SOUL.md. 1단계 문장은 원문의 요청 형식과 기억 예시를 합친 연습용 문장입니다.
스킬 찾아 설치하고 슬래시 명령으로 써 보기
Skills Hub 에서 스킬 하나를 찾아 미리 본 뒤 설치하고, 대화 창에서 /이름 으로 불러 봅니다. 마지막에는 필요 없는 스킬을 지우는 것까지 해 봅니다.
- 지금 가진 스킬을 물어보고, Skills Hub 에서 새 스킬을 찾습니다.
- 설치 전에 미리 보고, 설치한 뒤 목록으로 확인합니다.
- 설치한 스킬을 슬래시 명령으로 부르고, 필요 없으면 지웁니다.
예상 소요 시간: 15~20분
준비물과 완료 기준
- 실습 0·실습 1을 마쳐 터미널(글자로 명령을 입력하는 창)에서
hermes로 대화가 되는 상태. - 인터넷 연결 — Skills Hub(스킬을 찾아 설치하는 곳)는 온라인 저장소에서 스킬을 가져옵니다.
- 스킬(skill — 특정 일을 하는 방법을 적은 설명서.
SKILL.md라는 파일)이 무엇인지 한 줄로만 알면 됩니다.
① hermes skills list --source hub 목록에 내가 설치한 스킬이 보이고, ② 대화 창에서 /k8s 처럼 스킬 이름을 슬래시 명령(/ 로 시작해 넣는 명령)으로 넣었을 때 Hermes 가 무엇이 필요한지 되물으면 완료입니다.
이 실습은 원문이 예로 드는 openai/skills/k8s 를 그대로 씁니다. k8s(Kubernetes)는 서버 프로그램을 배포하는 도구라 직접 쓸 일이 없을 수 있지만, 여기서는 "찾기 → 설치 → 부르기"만 연습하므로 괜찮습니다. 2단계 목록에서 마음에 드는 다른 스킬로 바꿔도 됩니다.
따라 하기
1단계 · 지금 가진 스킬 물어보기
Hermes Agent 는 설치할 때 기본 스킬 묶음을 ~/.hermes/skills/(~ 는 내 홈 폴더)에 넣어 둡니다. 무엇이 있는지 Hermes 에게 물어봅니다. 터미널에서 아래 한 줄을 실행합니다.
hermes chat --toolsets skills -q "What skills do you have?"
뜻: 스킬 툴셋(toolset — 도구 꾸러미)을 지정해 "어떤 스킬을 갖고 있어?"라고 한 번 묻는 명령입니다. -q 는 질문 하나만 하고 끝낸다는 뜻입니다.
확인: 답에 스킬 이름이 하나 이상 나옵니다.
2단계 · Skills Hub 에서 찾기
더 필요한 스킬은 Skills Hub 에서 찾습니다. 전체를 둘러보거나 낱말로 검색합니다.
hermes skills browse
hermes skills search kubernetes
뜻: 첫 줄은 Hub 의 스킬 전체 둘러보기(공식 스킬이 먼저 나옴), 둘째 줄은 kubernetes 라는 낱말로 검색하기입니다. 검색어는 찾고 싶은 일로 바꿉니다.
목록에서 볼 것은 설치할 때 그대로 쓰는 이름입니다. 원문은 이를 slug 라고 부르며 "출처/경로" 모양입니다. openai/skills/k8s 는 OpenAI 의 스킬 모음에 있는 k8s 스킬이라는 뜻입니다.
확인: 목록에서 설치하고 싶은 스킬의 slug 를 하나 골라 적어 두었습니다(이 실습의 예: openai/skills/k8s).
3단계 · 설치하기 전에 미리 보기
스킬은 Hermes 가 따라 할 지시문이므로, 설치 전에 어떤 스킬인지 먼저 봅니다.
hermes skills inspect openai/skills/k8s
뜻: 설치하지 않고 이 스킬의 정보를 미리 봅니다. 원문에 따르면 가능한 경우 저장소 주소, 설치 명령, 주간 설치 수, 원 저장소의 보안 점검 상태 같은 정보도 함께 보여 줍니다.
확인: 스킬이 무슨 일을 하는지, 어디서 온 것인지 읽고 내가 찾던 것이 맞는지 판단했습니다.
4단계 · 설치하고 목록으로 확인하기
hermes skills install openai/skills/k8s
뜻: 이 스킬을 설치합니다. 설치 전에 보안 검사가 자동으로 먼저 돌아갑니다. 설치된 스킬은 ~/.hermes/skills/ 에 들어갑니다.
hermes skills list --source hub
뜻: Hub 에서 설치한 스킬 목록을 보여 줍니다.
확인: 목록에 방금 설치한 스킬(k8s)이 있습니다.
출처에 따라 믿는 정도가 다릅니다 (신뢰 단계)
| 단계 | 어디서 온 스킬 | 다루는 방식 |
|---|---|---|
builtin | Hermes 에 기본으로 들어 있는 것 | 항상 신뢰 |
official | Hermes 가 제공하는 선택 스킬(official/…) | 기본 스킬처럼 신뢰, 외부 스킬 경고 없음 |
trusted | openai/skills, anthropics/skills 등 신뢰하는 저장소 | 커뮤니티 출처보다 너그러운 기준 |
community | 그 밖의 모든 곳(skills.sh, 개인 GitHub 저장소 등) | 위험하지 않은 지적은 --force 로 넘길 수 있고, 위험 판정은 계속 막힘 |
5단계 · 슬래시 명령으로 불러 쓰기
설치한 스킬은 모두 자동으로 슬래시 명령이 됩니다. hermes 로 대화를 시작하고 입력 칸에 스킬 이름을 넣습니다.
/k8s
뜻: 이름만 넣으면 스킬을 불러온 뒤 무엇이 필요한지 Hermes 가 묻습니다. 연습에서는 여기까지만 합니다.
확인: Hermes 가 이 스킬로 무엇을 도울지 되묻습니다.
실제로 일을 시킬 때는 이름 뒤에 요청을 붙입니다. 원문 예시는 아래와 같습니다(실제 Kubernetes 환경이 있을 때만 의미가 있으므로 따라 하지 않아도 됩니다).
/k8s deploy the staging manifest
뜻: "k8s 스킬로, 시험용(staging) 환경의 배포 설정을 배포해 줘."
원문에 따르면 평소 대화에서 일이 기본 스킬과 맞으면 Hermes 가 스스로 알맞은 스킬을 골라 씁니다. 슬래시 명령은 "이 스킬로 해 줘"라고 직접 지정하고 싶을 때 씁니다. 그래서 스킬을 미리 다 설치해 둘 필요는 없습니다.
대화 창을 열어 둔 채 설치했다면 · 여러 스킬을 한 번에
- 대화가 열려 있는 동안 스킬을 설치하면, 다음에 보내는 메시지에 새 스킬 이름과 설명을 알리는 짧은 쪽지가 함께 전달됩니다.
/스킬이름명령 목록을 새로 고치려면 대화 창에/reload-skills를 넣습니다. - 메시지 맨 앞에
/스킬을 여러 개(최대 5개) 이어 쓰면 모두 불러옵니다. 설치된 스킬이 아닌 첫 낱말부터는 지시문으로 읽습니다. 원문 예:/github-pr-workflow /test-driven-development fix issue #123 and open a PR - 대화 창 안에서도
/skills browse,/skills search …,/skills inspect …,/skills install …,/skills list처럼 같은 명령을 쓸 수 있습니다.
6단계 · 필요 없으면 지우기
연습용으로 설치한 스킬을 계속 쓸 생각이 없다면 지웁니다. 계속 쓸 것이라면 이 단계는 건너뜁니다.
hermes skills uninstall k8s
뜻: Hub 에서 설치한 k8s 스킬을 지웁니다. 지울 때는 slug 전체가 아니라 스킬 이름만 씁니다.
확인: hermes skills list --source hub 를 다시 실행하면 목록에서 사라져 있습니다.
설치한 스킬을 최신으로 유지하기
hermes skills check
hermes skills update뜻: 첫 줄은 설치한 Hub 스킬 가운데 원본이 바뀐 것이 있는지 알려 주고, 둘째 줄은 바뀐 것만 다시 설치합니다. 내가 직접 고친 스킬은 덮어쓰지 않도록 건너뜁니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| 설치가 보안 검사에서 막힘 | 처음이라면 그 스킬은 두고 다른 스킬을 고릅니다. 원문은 외부 스킬을 직접 검토한 뒤에만 --force 를 붙여 경고 수준의 차단을 넘기라고 하며, 위험(dangerous) 판정은 --force 로도 넘을 수 없습니다. |
| 검색·설치 중 요청 한도(rate limit) 오류 | Hub 는 GitHub 를 거치는데, 로그인하지 않은 사용은 한 시간에 60번까지입니다. 잠시 뒤 다시 하거나, ~/.hermes/.env(비밀 값을 두는 설정 파일)에 GITHUB_TOKEN 을 넣으면 한 시간 5,000번으로 늘어납니다. |
| 검색 결과에 원하는 것이 없음 | 검색어를 바꾸거나 줄입니다. hermes skills browse --source official 로 공식 선택 스킬만 보거나, hermes skills search react --source skills-sh 처럼 --source 로 찾을 곳을 지정합니다. |
/k8s 를 넣어도 스킬이 불리지 않음 | hermes skills list --source hub 로 설치됐는지, 이름이 정확한지 봅니다. 대화를 열어 둔 채 설치했다면 /reload-skills 를 넣고 다시 해 봅니다. |
| 웹사이트의 Install in Hermes 버튼이 듣지 않음 | 이 버튼은 Hermes Desktop 앱을 여는 방식이며 최신 Desktop 이 필요합니다. 앱이 없거나 링크를 알아보지 못하면, 원문 안내대로 카드를 펼쳐 CLI 설치 명령을 복사해 터미널에 넣습니다. |
다음에 할 것
- 실습 5 — Hermes 가 파일을 잘못 고쳤을 때 되돌리는 법을 연습합니다.
- 반복하는 내 일을 스킬로 만들고 싶다면 6장 · 스킬 배우게 하기(/learn)를 봅니다.
- 더 알고 싶다면: 6장 · 스킬이란, 6장 · Skills Hub, 6장 · 필요한 만큼만 읽기.
- 찾기
hermes skills browse·search→ 미리 보기inspect→ 설치install→ 확인list --source hub. - 설치할 때는 slug(
openai/skills/k8s), 부를 때와 지울 때는 스킬 이름(/k8s,uninstall k8s)을 씁니다. - Hub 스킬은 모두 보안 검사를 거치고, 위험 판정은
--force로도 설치되지 않습니다. - 스킬은 목록만 먼저 읽히고 본문은 필요할 때 읽힙니다. 미리 다 설치할 필요가 없습니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/features/skills · getting-started/quickstart(Skills). 가이드 6장 스킬 쓰기·6장 Skills Hub. 명령과 예시 스킬(openai/skills/k8s)은 원문 그대로입니다.
실수 되돌리기 — 체크포인트 확인하고 /rollback
Hermes Agent 가 파일을 바꾸기 직전에 자동으로 찍어 두는 체크포인트를 켜고, 연습용 파일을 일부러 고치게 한 뒤 /rollback 으로 되돌려 봅니다. 위험한 명령 앞에서 뜨는 승인 물음을 읽는 법도 함께 익힙니다.
- 체크포인트를 켠 채 대화를 시작합니다(기본은 꺼져 있습니다).
/rollback으로 목록을 보고, 차이를 미리 본 뒤, 원하는 시점으로 되돌립니다.- 위험한 명령의 승인 물음에서 네 가지 답을 구분합니다.
예상 소요 시간: 15~20분
준비물과 완료 기준
- 실습 0·실습 1을 마쳐 터미널(글자로 명령을 입력하는 창)에서
hermes로 대화가 되는 상태. - 연습용 폴더 — 내 홈 폴더 아래에 따로 만든 폴더여야 합니다. 홈 폴더 자체나 컴퓨터 맨 위 폴더(
/)에서는 범위가 너무 넓어 체크포인트를 찍지 않습니다. 중요한 파일이 없는 빈 폴더를 씁니다. - git 이 설치돼 있을 것 — 체크포인트는 git 이라는 버전 관리 프로그램으로 저장되며, 없으면 체크포인트가 조용히 꺼집니다. 터미널에
git --version을 넣어 버전이 나오면 설치된 것입니다. - 터미널 백엔드(에이전트의 명령이 실제로 실행되는 곳)를 Docker 같은 컨테이너로 바꿔 두지 않은 상태. 바꿨다면 막히면을 먼저 봅니다.
/rollback 목록에서 체크포인트(checkpoint — 파일을 바꾸기 전에 찍어 두는 자동 스냅샷)를 확인하고, /rollback 1 로 되돌린 뒤 연습 파일이 고치기 전 내용으로 돌아온 것을 직접 확인하면 완료입니다.
체크포인트는 게임의 자동 저장과 같습니다. Hermes 가 파일에 손대기 직전에 "지금 상태"를 사진처럼 찍어 두고, 결과가 마음에 들지 않으면 그 사진의 상태로 돌아갑니다.
따라 하기
1단계 · 연습용 폴더에서 체크포인트를 켜고 시작하기
터미널에서 아래 세 줄을 차례로 실행합니다. 폴더 이름 hermes-practice 는 예시이며, 이미 쓰는 연습용 폴더가 있다면 그 폴더로 이동해도 됩니다.
mkdir ~/hermes-practice
cd ~/hermes-practice
hermes chat --checkpoints
뜻: 홈 폴더(~) 아래에 연습용 폴더를 만들고, 그 폴더로 이동한 뒤, 체크포인트를 켠 채 Hermes 와 대화를 시작합니다. --checkpoints 는 이번 세션(대화 한 묶음)에만 적용됩니다.
체크포인트는 기본으로 꺼져 있습니다. 원문은 대부분의 사용자가 /rollback 을 쓰지 않고 스냅샷이 저장 공간을 차지하기 때문에, 필요할 때만 켜도록 했다고 설명합니다.
확인: 환영 화면과 입력 칸이 나타나 대화를 시작할 수 있습니다.
매번 옵션을 붙이지 않고 항상 켜 두려면
설정 파일 ~/.hermes/config.yaml 에 아래를 적습니다.
checkpoints:
enabled: true스냅샷은 ~/.hermes/checkpoints/store/ 한곳에 따로 보관되며, 내 프로젝트의 .git 폴더는 건드리지 않습니다. 프로젝트마다 최대 20개, 전체 500MB 까지 보관하고 오래된 것은 자동으로 정리됩니다. 설정값은 완전 가이드 9장 · 체크포인트.
2단계 · 파일을 만들게 하고, 이어서 고치게 하기
되돌릴 거리를 만듭니다. 아래 두 문장을 한 번에 하나씩 보냅니다. 첫 번째 답이 끝난 뒤에 두 번째를 보냅니다. (원문에 정해진 문장은 없습니다 — 파일을 만들고, 그다음 고치게 하는 연습용 예시입니다.)
notes.md 파일을 만들고 "첫 번째 줄"이라고 써 줘.
notes.md 의 내용을 "바뀐 줄"로 바꿔 줘.
두 번에 나눠 보내는 이유가 있습니다. 체크포인트는 한 차례(내가 한 번 말하고 Hermes 가 답을 마칠 때까지)에 폴더당 최대 하나만 찍힙니다. 나눠 보내야 "만들기 직전"과 "고치기 직전" 두 개가 남습니다.
확인: 다른 터미널 창에서 cat ~/hermes-practice/notes.md(파일 내용을 보여 주는 명령)를 실행하면 "바뀐 줄"이 보입니다.
어떤 때 체크포인트가 찍히나
- 파일 도구로 파일을 쓰거나(
write_file) 일부를 고치기(patch) 직전. - 파일을 지우거나 덮어쓸 수 있는 터미널 명령 직전 —
rm,rmdir,cp,install,mv,sed -i,truncate,dd,shred, 출력 덮어쓰기(>),git reset/clean/checkout. - 지난 스냅샷 뒤로 바뀐 것이 없으면 찍지 않습니다.
3단계 · /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)
확인: 번호가 붙은 줄이 하나 이상 보이고, 줄마다 before write_file·before patch 처럼 무엇을 하기 직전인지 적혀 있습니다.
4단계 · 되돌리기 전에 차이 미리 보기
원문은 되돌리기 전에 먼저 미리 보라고 권합니다. 어느 체크포인트가 맞는지 고르는 데 도움이 됩니다.
/rollback diff 1
뜻: 체크포인트 1 과 지금 상태 사이에 무엇이 달라졌는지 보여 줍니다. 바뀐 파일 요약이 먼저 나오고 실제로 달라진 줄이 이어집니다. 이 명령도 아무것도 바꾸지 않습니다.
확인: 차이에 notes.md 가 보이고, 그것이 내가 되돌리려는 변경이 맞습니다.
5단계 · /rollback 1 로 되돌리기
/rollback 1
뜻: 체크포인트 1 의 상태로 파일을 되돌립니다. 원문에 따르면 Hermes 는 이때 ① 그 체크포인트가 있는지 확인하고, ② 되돌리기 직전의 지금 상태도 스냅샷으로 남기고(되돌린 것을 다시 되돌릴 수 있게), ③ 파일을 복원하고, ④ 대화의 마지막 차례도 함께 취소해 Hermes 가 아는 내용과 파일 상태를 맞춥니다.
확인: 다른 터미널 창에서 cat ~/hermes-practice/notes.md 를 다시 실행하면 "첫 번째 줄"로 돌아와 있습니다. 원문 예시에서는 화면에 Restored to checkpoint … 로 시작하는 줄이 나옵니다.
Kept your hand-edits: … 줄로 알려 줍니다.한 파일만 되돌리기 · 전부 되돌리기 · /undo 와의 차이
| 명령 | 하는 일 |
|---|---|
/rollback 1 src/broken_file.py | 체크포인트 1 에서 그 파일 하나만 되돌립니다. 폴더의 나머지는 그대로입니다. |
/rollback 1 --all | 내가 손으로 고친 것까지 모두 덮어써 되돌립니다. |
/undo | 대화만 되감습니다. 파일은 건드리지 않습니다. 체크포인트가 켜져 있으면 되감은 차례에서 바뀐 파일 이름을 알려 주고 /rollback 을 안내합니다. |
6단계 · 승인 물음이 뜨면 — 네 가지 답 읽기
체크포인트가 "일이 벌어진 뒤"의 안전망이라면, 승인(approval — 위험한 명령을 실행하기 전에 나에게 묻는 것)은 "벌어지기 전"의 안전망입니다. Hermes 는 명령을 실행하기 전에 위험한 유형(폴더째 지우기 등)인지 살피고, 해당하면 실행 전에 묻습니다. 이 단계는 일부러 띄우지 않고 읽는 법만 익힙니다.
| 답 | 뜻 |
|---|---|
once | 이번 실행 한 번만 허용합니다. |
session | 이 세션이 끝날 때까지 같은 유형의 명령을 허용합니다. |
always | 영구 허용 목록에 넣습니다(config.yaml 에 저장). 신중하게 고릅니다. |
deny (기본값) | 명령을 막습니다. 무슨 명령인지 모르겠다면 이것을 고릅니다. |
기본 설정(smart)에서는 보조 AI 가 먼저 위험도를 가늠해, 위험이 낮으면 그 명령만 자동으로 허용하고, 정말 위험하면 자동으로 막고, 애매할 때만 나에게 묻습니다. 정해진 시간(기본 300초) 안에 답하지 않으면 막힌 것으로 처리됩니다.
확인: 네 가지 답 가운데 어느 것이 "이번 한 번만"이고 어느 것이 기본값인지 말할 수 있습니다.
/yolo 명령이나 hermes --yolo 로 시작하면 그 세션의 승인 물음을 모두 건너뜁니다. 원문은 명령을 완전히 믿을 수 있는, 버려도 되는 환경에서만 쓰라고 경고합니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
/rollback 목록이 비어 있음 | 차례로 봅니다. ① hermes chat --checkpoints 로 시작했는지(기본은 꺼짐). ② 지금 폴더가 홈 폴더 자체, /, 또는 홈 폴더를 품은 폴더(/Users·/home)가 아닌지. ③ git --version 이 되는지. ④ Hermes 가 실제로 파일을 바꿨는지 — 바뀐 것이 없으면 찍지 않습니다. 파일이 5만 개를 넘는 폴더와 10MB 를 넘는 파일도 건너뜁니다. |
| 되돌렸는데 어떤 파일은 그대로임 | Hermes 가 쓴 뒤 내가 손으로 고친 파일은 보존됩니다. 화면의 Kept your hand-edits 줄을 확인하고, 그것까지 되돌리려면 /rollback 1 --all 을 씁니다. |
| 잘못된 시점으로 되돌림 | 되돌리기 직전 상태도 스냅샷으로 남아 있습니다. /rollback 으로 목록을 다시 열고, /rollback diff 번호 로 확인한 뒤 그 항목으로 되돌립니다. |
| 미리 보기와 복원이 거부됨 | 터미널 백엔드가 컨테이너(docker 등)이면 파일이 격리된 공간에 있어 체크포인트를 찍지 않으며, 목록은 보여도 미리 보기·복원은 거부됩니다. 내 컴퓨터(local)와 SSH 백엔드는 해당하지 않습니다. 폴더 안에 또 다른 git 저장소가 들어 있을 때도 전체 복원은 거부되고, 그 저장소와 무관한 파일 하나씩은 되돌릴 수 있습니다. |
/undo 를 했는데 파일이 그대로임 | /undo 는 대화만 되감습니다. 파일은 /rollback 으로 되돌립니다. |
| 승인 물음에 답하기 전에 시간이 지남 | 시간이 지난 물음은 다시 열 수 없고 명령은 실행되지 않습니다. 그래도 실행하려면 새 메시지로 다시 부탁합니다(원문 예: go ahead and run that now — "이제 그걸 실행해 줘"). 새 승인 물음이 뜹니다. |
다음에 할 것
- 기본 순서(실습 1~5)를 마쳤습니다. 필요에 따라 실습 6(매일 아침 브리핑 예약), 실습 7(Telegram), 실습 8(일 나눠 맡기기) 가운데 골라 이어 갑니다.
- 연습이 끝났으면 연습용 폴더는 그대로 두거나 직접 지웁니다. 체크포인트 저장 공간이 궁금하면 터미널에서
hermes checkpoints로 전체 크기와 폴더별 현황을 봅니다. - 더 알고 싶다면: 9장 · 체크포인트, 9장 · 위험한 명령 승인, 9장 · 체크포인트가 찍히지 않는 경우.
- 체크포인트는 기본으로 꺼져 있습니다.
hermes chat --checkpoints로 켜고, 홈 폴더 아래의 폴더에서 씁니다. /rollback(목록) →/rollback diff 1(미리 보기) →/rollback 1(되돌리기) 순서로 합니다.- 되돌리기는 Hermes 가 바꾼 파일만 되돌리고 내 손 수정은 남깁니다. 전부는
--all. /undo는 대화만,/rollback은 파일을 되돌립니다.- 승인 물음의 기본값은
deny(막기)입니다. 모르면 막습니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/checkpoints-and-rollback · user-guide/security(Dangerous Command Approval). 가이드 9장 체크포인트·9장 승인. 폴더 이름(hermes-practice)과 2단계의 두 문장, mkdir·cd·cat·git --version 은 연습을 위한 일반 터미널 명령·예시로 원문에 없습니다.
매일 아침 브리핑 예약하기
정해 둔 시간에 Hermes 가 혼자 소식을 살펴 요약을 남기게 합니다. 예약을 하나 만들고, 아침까지 기다리지 않고 한 번 시험 실행해 결과가 어디에 남는지 확인합니다.
- 매일 아침 9시에 실행되는 예약 작업(cron — 정해 둔 시간에 자동 실행) 하나를 만듭니다.
- 기다리지 않고 한 번 실행해 보고, 결과 파일을 찾아 읽습니다.
- 일정을 바꾸고, 잠시 멈추고, 지울 수 있습니다.
예상 소요 시간: 15~20분
준비물과 완료 기준
- 시작 전 준비를 마쳐 Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 에이전트는 도구를 써서 내 대신 일을 해 주는 AI 프로그램)와 대화가 되는 상태. 이 뒤로는 Hermes 라고 부릅니다.
- 터미널(글자로 명령을 입력하는 창) 창 2개. 하나는 게이트웨이(gateway — 계속 켜 두는 Hermes 프로그램. 메신저 연결과 예약 실행을 맡습니다)를 켜 두는 데 쓰고, 다른 하나에 명령을 입력합니다.
- 아침마다 받고 싶은 소식 한 가지. 이 실습은 공식 문서의 예시대로 "Hacker News 의 AI 소식"을 씁니다.
- (선택) 결과를 Telegram 으로 받고 싶다면 실습 7을 먼저 마칩니다. 이 실습은 Telegram 없이도 끝낼 수 있습니다.
hermes cron list 에 내가 만든 예약이 보이고, 한 번 시험 실행한 뒤 ~/.hermes/cron/output/ 폴더 아래에 생긴 결과 파일에서 요약을 읽으면 완료입니다. ~ 는 내 홈 폴더를 뜻합니다.
따라 하기
1단계 · 게이트웨이를 켜 두기
예약 작업은 만들어 두기만 해서는 실행되지 않습니다. 공식 문서는 예약 실행을 게이트웨이가 맡고, 게이트웨이가 60초마다 한 번씩 실행할 때가 된 예약이 있는지 점검한다고 적습니다. 그래서 가장 먼저 게이트웨이를 켭니다.
hermes gateway # 지금 이 창에서 바로 켜기
hermes gateway install # 또는 사용자 서비스로 설치해 두기
처음 연습할 때는 첫 번째 터미널 창에 hermes gateway 를 입력하고 그 창을 그대로 둡니다. 그다음 두 번째 창에서 아래 명령으로 상태를 봅니다.
hermes cron status
이 명령은 스케줄러(예약 시간을 점검하는 부분)가 살아 있는지 — 게이트웨이 프로세스, 점검 신호, 마지막으로 성공한 점검 — 와 가장 가까운 다음 실행을 알려 줍니다. 확인: hermes cron status 가 스케줄러가 살아 있다고 알려 줍니다. 정확한 출력 문구는 받은 원문에 없으므로, 게이트웨이가 꺼져 있다는 경고가 없는지를 봅니다.
계속 켜 두려면: 서비스로 설치
hermes gateway install 은 게이트웨이를 사용자 서비스로 설치합니다. Linux 서버에서 부팅할 때부터 켜 두려면 sudo hermes gateway install --system 을 씁니다. 8장 게이트웨이 설정 · 서비스로 켜 두기.
2단계 · 혼자 읽어도 알 수 있는 프롬프트 쓰기
예약 작업은 실행될 때마다 완전히 새로운 세션(대화 한 묶음)에서 시작합니다. 지금 나와 나눈 대화를 전혀 모릅니다. 그래서 프롬프트 한 장에 필요한 것이 모두 들어 있어야 합니다. 공식 문서의 나쁜 예와 좋은 예는 이렇습니다.
BAD: "Check on that server issue"
GOOD: "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."
뜻: 나쁜 예는 "그 서버 문제 확인해 줘"입니다. 새 세션은 "그 서버"가 무엇인지 모릅니다. 좋은 예는 어느 서버에 누구로 들어가 무엇을 확인할지를 전부 적었습니다.
이 실습에서 쓸 브리핑 프롬프트는 아래 한 줄입니다.
Check Hacker News for AI news and give me a summary
뜻: Hacker News 에서 AI 소식을 확인하고 요약해 줘. 공식 문서의 예시 문장("Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.")에서 시간과 보낼 곳을 뺀 연습용 문장입니다. 시간은 일정 칸에, 보낼 곳은 전달 대상 설정에 따로 적기 때문입니다. 에이전트의 마지막 답이 정해 둔 전달 대상으로 자동으로 보내지므로, 프롬프트 안에서 "보내라"고 시킬 일은 없습니다.
확인: 프롬프트만 따로 떼어 읽어도 어디에서, 무엇을 확인해, 무엇을 내놓을지 알 수 있습니다. "그거", "어제 말한" 같은 말이 없습니다.
3단계 · 예약 만들기
두 번째 터미널 창에 아래 명령을 입력합니다. 첫 따옴표 안이 일정, 둘째 따옴표 안이 프롬프트, --name 뒤가 이 예약의 이름입니다.
hermes cron create "every day at 9am" "Check Hacker News for AI news and give me a summary" --name "morning-briefing"
뜻: 매일 오전 9시에 위 프롬프트를 실행하는 예약을 morning-briefing 이라는 이름으로 만듭니다. 이름을 붙여 두면 뒤에서 긴 ID 대신 이름으로 이 예약을 가리킬 수 있습니다(대소문자는 가리지 않습니다).
예약을 만드는 방법은 세 가지입니다. 어느 쪽으로 만들어도 같은 예약 목록에 들어갑니다.
hermes cron create "every 2h" "Check server status"뜻: 2시간마다 서버 상태를 확인. Hermes 대화를 열지 않고 터미널에서 바로 만듭니다. 이 실습이 쓰는 방법입니다.
/cron add "every 2h" "Check server status"
/cron add "in 30m" "Remind me to check the build"뜻: 대화 입력 칸에 넣는 슬래시 명령(/ 로 시작하는 명령)입니다. 둘째 줄은 30분 뒤에 한 번만 "빌드 확인하라고 알려 줘"를 실행합니다.
Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.뜻: 매일 아침 9시에 Hacker News 에서 AI 소식을 확인해 Telegram 으로 요약을 보내 줘. 평소처럼 말하면 Hermes 가 예약 관리 도구를 스스로 써서 만듭니다. 이 문장대로 받으려면 Telegram 연결(실습 7)이 먼저 필요합니다.
확인: hermes cron list 를 입력하면 목록에 morning-briefing 이 보입니다.
일정을 적는 다른 방법
| 적는 말 | 뜻 |
|---|---|
every day at 9am · daily at 7am | 매일 오전 9시 · 매일 오전 7시 |
weekdays at 9am | 평일 오전 9시 |
every 2h · every 30m | 2시간마다 · 30분마다 (지울 때까지 반복) |
in 30m · in 1d | 30분 뒤 · 하루 뒤에 한 번만 |
0 9 * * * · 0 9 * * 1-5 | cron 표현식으로 매일 9시 · 평일 9시 |
시간은 9am, 9:30pm, 14:00, noon(정오), midnight(자정)처럼 적을 수 있습니다. 전체 형식은 7장 일정 형식에 있습니다.
4단계 · 기다리지 않고 한 번 실행해 보기
내일 아침까지 기다리지 않고 지금 한 번 돌려 봅니다.
hermes cron run morning-briefing
뜻: 이 예약을 다음 스케줄러 점검 때 실행하도록 요청합니다. 손으로 돌린 실행은 "추가 실행"입니다. 정해 둔 9시 실행은 그대로 일어나고, 반복 횟수도 줄지 않습니다.
실행이 어떻게 끝났는지는 실행 기록으로 봅니다.
hermes cron runs --limit 20
뜻: 최근 실행 시도 20개를 보여 줍니다. 공식 문서에 따르면 시도 하나는 claimed(접수) → running(실행 중)을 거쳐 completed(끝남) · failed(실패) · unknown(알 수 없음) 가운데 하나로 끝납니다. 확인: 방금 돌린 시도가 completed 로 끝나 있습니다. 아직 running 이면 조금 뒤에 다시 봅니다.
5단계 · 결과 파일 읽기
터미널에서 만든 예약은 결과를 어디로 보낼지 따로 정하지 않으면 local — 내 컴퓨터 파일로만 저장합니다. 저장 위치는 아래와 같습니다.
~/.hermes/cron/output/{job_id}/{timestamp}.md
뜻: 예약 ID 이름의 폴더 안에, 실행 시각이 이름인 .md 파일이 실행할 때마다 하나씩 쌓입니다. 파일을 여는 방법은 원문에 없으므로 평소 쓰는 파일 탐색기나 편집기로 엽니다.
확인: 가장 최근 .md 파일을 열면 AI 소식 요약이 들어 있습니다.
Telegram 으로 받고 싶다면
공식 문서의 전달 대상 표에서 telegram 은 Telegram 홈 채널(TELEGRAM_HOME_CHANNEL 로 정한 곳)로 보낸다는 뜻이고, 원문의 스크립트 예약 예시는 만들 때 --deliver telegram 을 붙입니다. Telegram 대화 안에서 예약을 만들면 기본 전달 대상이 origin — 예약을 만든 그 대화입니다. 여러 곳에 보내려면 telegram,discord 처럼 쉼표로 잇습니다. 먼저 실습 7로 Telegram 을 연결하고, 홈 채널은 8장 홈 채널, 전달 대상 전체는 7장 결과 전달을 봅니다.
6단계 · 일정 바꾸기 · 잠시 멈추기 · 지우기
예약을 바꾸려고 지우고 다시 만들 필요는 없습니다. 주말에는 받고 싶지 않다면 일정만 고칩니다.
hermes cron edit morning-briefing --schedule "weekdays at 9am"
뜻: 일정을 평일 오전 9시로 바꿉니다. 프롬프트를 고칠 때는 --prompt "새 프롬프트" 를 씁니다.
hermes cron pause morning-briefing # 예약은 두고 실행만 멈춤
hermes cron resume morning-briefing # 다시 켜기
hermes cron remove morning-briefing # 완전히 지우기
휴가 동안은 pause 로 멈춰 두고 돌아와서 resume 합니다. 대화 안에서는 같은 일을 /cron list, /cron pause, /cron resume, /cron remove 로 합니다. 확인: 명령을 실행한 뒤 hermes cron list 로 바뀐 일정이나 상태가 반영됐는지 봅니다. 연습만 하고 끝낼 생각이면 remove 로 지워 둡니다. 지우지 않으면 매일 아침 계속 실행됩니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| 시간이 지났는데 실행되지 않음 | 게이트웨이가 꺼져 있을 가능성이 큽니다. hermes cron status 가 OVERDUE(이미 지남) 경고를 내거나 hermes cron list 가 그 줄에 Overdue: 를 붙이면 스케줄러가 멈춘 것입니다. hermes gateway restart 로 게이트웨이를 다시 켜거나 hermes cron run morning-briefing 으로 바로 돌립니다. |
| 실행은 됐는데 결과가 메신저에 오지 않음 | 실행과 전달은 따로 기록됩니다. hermes cron list 에 delivery_failed: 이유 가 보이면 답은 만들어졌지만 전달에 실패한 것입니다. 답 자체는 ~/.hermes/cron/output/ 아래 파일에 남아 있습니다. |
| 요약이 엉뚱하거나 "무엇을 말하는지 모르겠다"는 답 | 프롬프트가 혼자 읽어서는 알 수 없는 문장인지 봅니다. 2단계의 좋은 예처럼 대상과 할 일을 모두 적고 hermes cron edit morning-briefing --prompt "…" 로 고칩니다. |
| 소식을 가져오지 못함 | 예약 작업은 기본으로 hermes tools 에서 cron 플랫폼에 켜 둔 툴셋(toolset — 도구 꾸러미)을 씁니다. 대화에서 쓰던 도구가 전부 켜져 있는 것이 아닙니다. 4장 툴셋을 보고 필요한 도구를 켭니다. |
| 무엇이 문제인지 모르겠음 | hermes cron doctor 를 돌립니다. 켜져 있는 모든 예약을 읽기만 하며 점검해, 마지막 실행 실패·전달 실패·늦은 실행 같은 문제를 예약별로 알려 줍니다. 더 많은 증상은 7장 예약 작업 문제 해결에 있습니다. |
게이트웨이가 꺼져 있는 동안에는 예약이 실행되지 않습니다. 공식 문서는 게이트웨이가 다시 켜지면 지나간 반복 예약을 한 번만 따라잡아 실행한다고 적습니다(여러 번 놓쳤어도 한 번). 늦은 브리핑이 필요 없다면 만들 때 --catch-up off 를 붙입니다. 자세한 조건은 7장 예약 관리를 봅니다.
다음에 할 것
- 결과를 휴대폰으로 받으려면 실습 7로 Telegram 을 연결한 뒤 5단계의 접힌 상자를 다시 봅니다.
- 예약 작업의 원리는 7장 예약 작업이란, 만드는 방법 전체는 예약 만들기에서 읽습니다.
- 한 번에 여러 가지를 조사시키고 싶다면 실습 8로 넘어갑니다.
예약이 끝없이 늘어나는 일을 막으려고, 예약으로 실행된 세션에서는 예약 관리 도구가 꺼져 있습니다. 반복은 프롬프트가 아니라 일정으로 정합니다.
- 예약은 게이트웨이가 켜져 있어야 실행됩니다.
hermes cron status로 확인합니다. hermes cron create "일정" "프롬프트" --name "이름"으로 만들고, 프롬프트는 혼자 읽어도 알 수 있게 씁니다.hermes cron run 이름으로 기다리지 않고 시험하며, 예약된 실행은 그대로 남습니다.- 터미널에서 만든 예약의 결과는
~/.hermes/cron/output/아래 파일로 쌓입니다. edit·pause·resume·remove로 고치고, 멈추고, 지웁니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/features/cron (수집본 sources/raw/user-guide_features_cron.md). 가이드 7장 예약 작업과 위임. 예약 이름 morning-briefing 과 브리핑 프롬프트는 원문 예시 문장을 옮긴 연습용입니다.
Telegram 으로 Hermes 와 대화하기
컴퓨터 앞에 없어도 휴대폰 메신저로 Hermes 에게 일을 맡길 수 있게 만듭니다. 내 전용 봇을 하나 만들고, 나만 쓸 수 있게 잠근 뒤, 첫 메시지에 답이 오는지 확인합니다.
- Telegram 에서 내 봇을 만들고 Hermes Agent 에 연결합니다.
- 허용한 사람만 봇을 쓸 수 있게 내 사용자 ID 를 등록합니다.
- 게이트웨이를 켜서 휴대폰으로 대화하고, 계속 켜 두는 방법을 압니다.
예상 소요 시간: 20~30분
준비물과 완료 기준
- 시작 전 준비를 마쳐서 터미널(글자로 명령을 입력하는 창)에서 Hermes 와 대화가 되는 컴퓨터.
- Telegram 앱과 내 계정. 휴대폰이든 컴퓨터든 상관없습니다.
- 봇 토큰과 내 사용자 ID 를 잠깐 적어 둘 메모장. 토큰은 비밀번호처럼 다룹니다.
이 실습의 주인공은 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)입니다. Telegram 에 보낸 메시지를 게이트웨이가 받아 그 대화방의 세션(대화 한 묶음)을 찾고, Hermes 에게 넘긴 뒤 답을 다시 Telegram 으로 돌려보냅니다.
Telegram 에서 내 봇에게 메시지를 보냈을 때 Hermes 의 답이 돌아오면 완료입니다. 원문도 "게이트웨이를 켜면 봇이 몇 초 안에 접속하니, 메시지를 보내 확인하라"고만 적습니다.
따라 하기
1단계 · BotFather 에게서 봇과 토큰 받기
Telegram 의 모든 봇은 @BotFather(Telegram 공식 봇 관리 도구)가 발급하는 API 토큰(봇을 조종할 수 있는 긴 비밀 문자열)이 있어야 합니다.
- Telegram 에서 @BotFather 검색검색해서 대화방을 엽니다. 주소
t.me/BotFather로 열어도 됩니다. /newbot보내기새 봇을 만들겠다는 명령입니다.- 표시 이름 정하기사람들에게 보이는 이름입니다. 아무 이름이나 됩니다(예: Hermes Agent).
- 사용자 이름 정하기남과 겹치지 않아야 하고 반드시
bot으로 끝나야 합니다(예:my_hermes_bot).
BotFather 가 아래와 같은 모양의 토큰을 답으로 줍니다. 메모장에 옮겨 둡니다.
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
이 토큰을 가진 사람은 누구나 내 봇을 조종할 수 있습니다. 새어 나갔다면 곧바로 BotFather 에게 /revoke 를 보내 무효로 만듭니다. 대화방·문서·화면 공유에 붙여 넣지 않습니다.
확인: 숫자, 쌍점(:), 긴 글자가 이어진 토큰 한 줄을 받아 적었습니다.
2단계 · 내 사용자 ID 알아내기
Hermes 는 누가 봇을 쓸 수 있는지를 숫자로 된 Telegram 사용자 ID 로 가려냅니다. @ 로 시작하는 사용자 이름이 아니라 123456789 같은 숫자입니다.
- @userinfobot 에게 메시지 보내기원문이 권하는 방법입니다. 바로 내 사용자 ID 를 답해 줍니다.
- 안 되면 @get_id_bot같은 일을 하는 다른 봇입니다.
확인: 숫자만으로 된 내 ID 를 토큰 옆에 적어 두었습니다.
3단계 · 설정 마법사에 토큰과 ID 넣기
터미널에 아래 명령을 넣습니다. 메신저 연결을 차례로 물어보며 대신 적어 주는 설정 마법사입니다.
hermes gateway setup
뜻: 메신저 플랫폼을 대화식으로 설정합니다. 화살표 키로 고르는 방식이며, 이미 설정된 플랫폼이 무엇인지도 보여 줍니다.
- Telegram 고르기플랫폼을 묻는 곳에서 Telegram 을 선택합니다.
- 봇 토큰 넣기1단계에서 받은 토큰을 붙여 넣습니다.
- 허용할 사용자 ID 넣기2단계의 숫자를 넣습니다. 마법사가 설정을 대신 기록합니다.
- 끝에서 게이트웨이를 시작할지 묻습니다여기서 시작해도 되고, 4단계에서 직접 켜도 됩니다.
~ 는 내 홈 폴더를 뜻합니다.확인: 마법사가 끝까지 진행됐고, hermes gateway setup 을 다시 열면 Telegram 이 이미 설정된 플랫폼으로 표시됩니다.
마법사 대신 파일에 직접 적는 방법 · 앱에서 QR 로 만드는 방법
비밀 값을 두는 파일 ~/.hermes/.env 에 아래 두 줄을 넣어도 같은 결과입니다. 여러 사람을 허용하려면 ID 를 쉼표로 이어 적습니다.
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789 # Comma-separated for multiple users뜻: 첫 줄은 봇 토큰, 둘째 줄은 허용할 사용자 ID 입니다. 원문은 또 대시보드와 데스크톱 앱의 Messaging → Telegram 화면에 Create with QR 버튼이 있어, QR 을 찍으면 봇 생성·ID 확인·.env 기록·게이트웨이 재시작을 대신 해 준다고만 적습니다. ID 를 일일이 적지 않고 승인하는 방식(DM 페어링)은 9장 누가 쓸 수 있나를 봅니다.
4단계 · 게이트웨이를 켜고 첫 메시지 보내기
마법사에서 시작하지 않았다면 터미널에 아래 명령을 넣습니다.
hermes gateway
뜻: 게이트웨이를 지금 이 터미널에서 바로 실행합니다(foreground — 앞에서 실행). 이 창을 연 채로 둡니다.
- Telegram 에서 내 봇 찾기1단계에서 정한 사용자 이름(
bot으로 끝나는 이름)으로 검색해 대화방을 엽니다. - 아무 메시지나 보내기평소 터미널에서 부탁하던 것처럼 한 문장을 보냅니다.
- 답 기다리기Hermes 가 일하는 동안 대화방에 "입력 중…" 표시가 뜹니다.
확인: 봇이 몇 초 안에 접속하고, 보낸 메시지에 Hermes 의 답이 돌아옵니다. 여기까지 되면 이 실습의 완료 기준을 채웠습니다.
Hermes 가 위험할 수 있는 명령을 실행하려 하면 대화방에서 승인을 요청합니다. yes(또는 y)로 허락하고 no(또는 n)로 거절합니다. 뜻을 모르면 거절하고 무슨 일인지 먼저 물어봅니다. 9장 승인.
5단계 · 대화방에서 슬래시 명령 써 보기
메신저에서도 슬래시 명령(/ 로 시작하는 명령)을 씁니다. 아래 네 개를 하나씩 보내 봅니다.
| 보낼 명령 | 하는 일 |
|---|---|
/help | 쓸 수 있는 명령을 보여 줍니다. |
/status | 지금 세션의 정보를 보여 줍니다. |
/new | 새 대화를 시작합니다(/reset 도 같음). |
/sethome | 이 대화방을 홈 채널로 정합니다. 예약 작업의 결과가 이곳으로 옵니다. |
메신저의 대화는 쉬었다 와도, 날이 바뀌어도 저절로 새로 시작되지 않습니다. 일 하나나 주제 하나가 끝나면 /new 로 직접 끊어 주는 것이 좋습니다. 대화가 짧아져 비용이 줄고, Hermes 가 새로 저장한 기억도 새 세션부터 반영됩니다.
확인: /status 를 보내면 세션 정보가 답으로 옵니다. /sethome 을 보냈다면 실습 6의 브리핑을 이 대화방으로 받을 준비가 됐습니다.
6단계 · 터미널을 닫아도 돌게 서비스로 설치하기 (선택)
4단계 방식은 터미널에서 직접 실행한 것입니다. 늘 켜 두려면 게이트웨이를 서비스(운영체제가 뒤에서 대신 돌려 주는 프로그램)로 설치합니다. 원문은 같은 봇 토큰을 두 게이트웨이가 동시에 쓰면 나중 것이 연결에 실패한다고 적으니, 4단계에서 켠 게이트웨이를 먼저 끝낸 뒤 진행합니다(직접 켠 게이트웨이를 끄는 방법은 받은 원문에 따로 적혀 있지 않습니다).
hermes gateway install
hermes gateway start
hermes gateway status
뜻: 차례로 서비스로 설치(macOS 는 launchd, Linux 는 사용자 서비스) · 서비스 시작 · 상태 확인입니다. 멈출 때는 hermes gateway stop 입니다.
기록(로그)은 tail -f ~/.hermes/logs/gateway.log 로 봅니다. 서비스를 설치한 뒤에 새 도구(예: ffmpeg)를 깔았다면 hermes gateway install 을 한 번 더 실행해야 게이트웨이가 그 도구를 찾습니다.
기록은 journalctl --user -u hermes-gateway -f 로 봅니다. 로그아웃한 뒤에도 돌게 하려면 sudo loginctl enable-linger $USER 를 실행합니다. 원문은 노트북·개발용 컴퓨터에는 사용자 서비스를 권합니다.
확인: hermes gateway status 로 서비스 상태를 본 뒤, 터미널 창을 닫고 Telegram 에서 메시지를 보내도 답이 옵니다. 컴퓨터가 꺼져 있으면 답하지 못합니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| 봇이 전혀 답하지 않음 | 게이트웨이가 켜져 있는지 hermes gateway status 로 봅니다. TELEGRAM_BOT_TOKEN 이 맞는지 확인하고 게이트웨이 기록에서 오류를 찾습니다. 차례대로 점검하는 길은 실습 10에 있습니다. |
| 봇이 "unauthorized"(권한 없음)라고 답함 | 내 사용자 ID 가 TELEGRAM_ALLOWED_USERS 에 없습니다. @userinfobot 으로 숫자를 다시 확인해 3단계를 다시 합니다. |
| 토큰이 새어 나갔거나 무효가 됨 | BotFather 에서 /revoke 로 무효로 만든 뒤 /newbot 또는 /token 으로 새 토큰을 받아 .env 를 고칩니다. |
| 1:1 대화는 되는데 그룹에서는 조용함 | Telegram 봇은 기본으로 privacy mode(사생활 보호 모드)가 켜져 있어 그룹의 일반 메시지를 받지 못합니다. 아래 접힌 상자를 봅니다. |
| 음성 메시지가 글로 바뀌지 않음 | 음성 인식 준비가 필요합니다. 8장 음성을 봅니다. |
그룹 대화방에서 쓰려면: privacy mode
privacy mode 가 켜져 있으면 봇은 / 명령, 봇의 메시지에 단 답장, 입장·퇴장 같은 알림, 봇이 관리자인 채널의 메시지만 봅니다. 끄려면 @BotFather 에게 /mybots 를 보내 내 봇을 고르고 Bot Settings → Group Privacy → Turn off(봇 설정 → 그룹 사생활 보호 → 끄기)를 누릅니다. 바꾼 뒤에는 봇을 그룹에서 내보냈다가 다시 넣어야 적용됩니다. 끄는 대신 봇을 그룹 관리자로 올려도 모든 메시지를 받습니다. 그룹에서도 허용 목록은 그대로 적용됩니다. 8장 그룹에서 쓰기.
다음에 할 것
- 정해 둔 시간에 결과를 이 대화방으로 받기 — 실습 6. 홈 채널은 8장 홈 채널.
- 봇이 답하지 않거나 기억을 못 하는 것 같을 때 — 실습 10.
- 메신저 안에서 쓰는 명령 전체 — 8장 대화방 명령. 서비스로 계속 켜 두기 — 8장 서비스.
- BotFather 에게
/newbot으로 봇과 토큰을 받고, @userinfobot 으로 내 숫자 ID 를 알아냅니다. hermes gateway setup에 두 값을 넣고hermes gateway로 켠 뒤 봇에게 메시지를 보냅니다.- 토큰은 비밀이고, 허용 목록에 없는 사람은 기본으로 거절됩니다.
- 메신저 대화는 저절로 끊기지 않으니 일이 끝나면
/new로 끊습니다. - 늘 켜 두려면
hermes gateway install로 서비스로 설치합니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram, /docs/user-guide/messaging (수집일 2026-11-09). 가이드 8장 봇 만들기·8장 Telegram 설정. 토큰·ID 숫자와 봇 이름은 원문의 예시 값입니다.
일을 나눠 맡기기 — 세 가지를 동시에 조사시키기
서로 상관없는 조사 세 가지를 Hermes 가 하위 에이전트 셋에게 나눠 주고, 요약만 모아 돌려받게 합니다. 지켜보는 방법과 멈추는 방법도 익힙니다.
- 조사 세 가지를 하위 에이전트(subagent — 일을 나눠 받은 별도 에이전트) 셋에게 동시에 맡깁니다.
- 맡긴 일이 진행되는 모습을 보고, 필요하면 멈춥니다.
- 하위 에이전트가 무엇을 모르는지 알고, 맡길 말을 빠짐없이 씁니다.
예상 소요 시간: 15~25분
준비물과 완료 기준
- 시작 전 준비와 실습 1을 마쳐, Hermes Agent(Nous Research 가 만든, 쓸수록 스스로 배우는 AI 에이전트 — 에이전트는 도구를 써서 내 대신 일을 해 주는 AI 프로그램)가 도구를 써서 결과를 내는 것을 본 상태. 이 뒤로는 Hermes 라고 부릅니다.
- 평소처럼
hermes로 연 대화 화면. - 조사에 필요한 도구가 켜져 있는 상태. 하위 에이전트는 부모가 켜 둔 툴셋(toolset — 도구 꾸러미)만 물려받습니다. 웹 조사가 필요하면 대화를 시작하기 전에 4장 툴셋을 보고 켜 둡니다.
- 서로의 결과를 기다릴 필요가 없는 조사 주제 3개. 이 실습은 공식 문서의 예시(WebAssembly · RISC-V · 양자 컴퓨팅)를 씁니다. 내 주제로 바꿔도 됩니다.
하위 에이전트는 저마다 모델(에이전트의 두뇌 역할을 하는 AI)을 처음부터 따로 돌립니다. 공식 문서도 위임의 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위) 비용이 "더 높다"고 적습니다. 처음에는 3개로만 연습합니다.
세 조사의 요약이 대화에 돌아오고, 그 안에 세 주제가 모두 들어 있는지 읽어 확인하면 완료입니다.
따라 하기
1단계 · 동시에 맡겨도 되는 일인지 가르기
위임(delegation — 일을 하위 에이전트에게 나눠 맡기는 것)으로 한꺼번에 보낸 일은 모두 동시에 실행됩니다. 그래서 서로의 결과를 기다릴 필요가 없는 일만 한 번에 묶습니다. 공식 문서는 "B 가 A 의 결과를 필요로 하면 A 를 먼저 맡기고, A 가 돌아온 뒤 그 결과를 넣어 B 를 맡기라"고 적습니다.
확인: 세 주제 가운데 어느 것도 다른 주제의 조사 결과가 있어야 시작할 수 있는 것이 아닙니다.
2단계 · 맡길 말을 빠짐없이 쓰기
하위 에이전트는 완전히 빈 대화에서 시작합니다. 내가 Hermes 와 지금까지 나눈 이야기, 앞서 쓴 도구의 결과를 하나도 모릅니다. 아는 것은 부모가 넘겨준 두 가지 — 목표(goal)와 배경(context) — 뿐입니다. 공식 문서의 나쁜 예와 좋은 예입니다.
# BAD - subagent has no idea what "the error" is
delegate_task(goal="Fix the error")
# GOOD - subagent has all context it needs
delegate_task(
goal="Fix the TypeError in api/handlers.py",
context="""The file api/handlers.py has a TypeError on line 47: ...
The project is at /home/user/myproject and uses Python 3.11."""
)
뜻(가운데는 줄였습니다): 나쁜 예는 "그 오류 고쳐 줘"입니다. 하위 에이전트는 "그 오류"가 무엇인지 모릅니다. 좋은 예는 어느 파일의 어떤 오류인지, 프로젝트가 어디에 있는지를 모두 적었습니다. 이 호출은 Hermes 가 만드는 것이고, 나는 Hermes 가 그렇게 쓸 수 있도록 재료를 말로 주면 됩니다.
이 실습에서 보낼 문장은 아래와 같습니다. 주제와 초점은 공식 문서의 "Parallel Research" 예시에서 가져왔고, 문장으로 옮긴 것은 연습용입니다.
Research these three topics in parallel using delegate_task, one subagent per topic, then give me one combined summary.
1. The current state of WebAssembly in 2025. Focus on: browser support, non-browser runtimes, language support
2. The current state of RISC-V adoption in 2025. Focus on: server chips, embedded systems, software ecosystem
3. Quantum computing progress in 2025. Focus on: error correction breakthroughs, practical applications, key players
뜻: 아래 세 주제를 delegate_task 로, 주제마다 하위 에이전트 하나씩 동시에 조사하고 요약을 하나로 묶어 줘. ① 2025년 WebAssembly 현황 — 브라우저 지원, 브라우저 밖 실행 환경, 언어 지원 ② 2025년 RISC-V 도입 현황 — 서버 칩, 임베디드 기기, 소프트웨어 생태계 ③ 2025년 양자 컴퓨팅 진전 — 오류 정정의 돌파구, 실제 쓰임새, 주요 참여자.
확인: 주제마다 "무엇을 조사할지"와 "어디에 초점을 둘지"가 한 줄 안에 다 있습니다. "아까 말한 그것" 같은 표현이 없습니다.
한 번에 몇 개까지 맡길 수 있나
Hermes 는 안에서 delegate_task 도구의 tasks 목록에 일을 여러 개 담아 보냅니다. 기본으로 10개까지 동시에 돌 수 있고(설정으로 바꿀 수 있음), 한도를 넘는 묶음은 조용히 잘리지 않고 도구 오류로 돌아옵니다. 7장 여러 일을 한 번에 맡기기 · 하위 에이전트가 아는 것.
3단계 · 보내고, 대화가 바로 돌아오는지 보기
2단계의 문장을 Hermes 대화에 보냅니다. 위임은 백그라운드(뒤에서 따로 도는 것)에서 실행됩니다. Hermes 는 접수했다는 표시만 바로 돌려주고 대화를 계속할 수 있게 하며, 결과는 나중에 새 메시지로 대화에 들어옵니다.
하위 에이전트가 일하는 동안에는 입력 칸 위에 살아 있는 하위 에이전트가 자동으로 표시됩니다. 공식 문서에 따르면 여기에 개수, 작업 이름, 지난 시간, 가장 최근 활동이 보이고, 보는 동안에도 글을 계속 쓸 수 있습니다.
확인: 입력 칸 위에 하위 에이전트가 표시되고, 입력 칸에 글을 쓸 수 있습니다. 표시가 없이 Hermes 가 혼자 차례로 조사한다면 "delegate_task 로 나눠서 해 줘"라는 뜻이 문장에 들어갔는지 다시 봅니다.
4단계 · 일하는 모습 지켜보기
더 자세히 보고 싶으면 명단 화면을 엽니다.
기본 CLI(터미널에서 글자로 쓰는 프로그램 화면)에서는 Ctrl+T(또는 F6)로 전체 화면 명단을 엽니다. 화살표로 하위 에이전트를 고르고 Enter 로 그 에이전트의 최근 기록을 보며, PgUp/PgDn 으로 넘깁니다.
글자로 된 요약만 보려면 /agents(또는 /tasks)를 입력합니다. 공식 문서가 보여 주는 출력 예시는 이런 모양입니다.
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건 실행 중. 하위 1번은 API 호출 4번(모델에 보낸 요청 수), 지금 웹 검색 도구를 쓰는 중, 12초 전에 움직임이라는 뜻입니다.
TUI(hermes --tui 로 여는 새 터미널 화면)에서는 Ctrl+T 또는 /agents 로 나무 모양 명단을 열고, Enter 로 최근 기록을 봅니다.
"최근 활동"은 지금 무엇을 하고 있는지 보여 줄 뿐, 몇 퍼센트 끝났는지를 뜻하지 않습니다. 확인: 명단에서 세 작업이 각각 보이고, 최근 활동 시각이 계속 바뀝니다.
더 깊이 보기 · 도중에 방향 바꾸기
위임마다 사람이 읽을 수 있는 실시간 기록 파일이 작업당 하나씩 생깁니다. 원문 예시는 tail -f ~/.hermes/cache/delegation/live/deleg_ab12cd34/task-0.log 입니다(deleg_… 는 내 위임의 ID, ~ 는 내 홈 폴더). 멈추지 않고 방향만 바꾸려면 명단에서 고른 뒤 기본 CLI 는 s, TUI 는 e 로 안내 글을 보냅니다. 글은 "대기 중"으로 접수되고 하위 에이전트가 다음 확인 지점에서 읽습니다. 7장 하위 에이전트 지켜보기.
5단계 · 묶음 결과 받기
기본 설정에서는 세 작업이 모두 끝난 뒤 결과가 메시지 하나로 묶여 돌아옵니다. 먼저 끝난 것부터가 아니라 내가 적은 순서(1·2·3)대로 정리됩니다. 부모의 대화에는 하위 에이전트가 거친 긴 과정이 아니라 마지막 요약만 들어옵니다. 그래서 부모의 컨텍스트(모델이 한 번에 기억하며 볼 수 있는 글의 양)가 조사 과정으로 가득 차지 않습니다.
끝날 때는 Subagent Task Completed: … 처럼 작업 이름이 앞에 붙은 완료 알림이 뜹니다. 실패한 작업은 조용히 사라지지 않고, 제공자(provider — AI 모델을 빌려주는 서비스) 오류나 시간 초과 같은 이유 한 줄이 붙습니다. 공식 문서의 예시입니다.
⚠️ Subagent failed — "your goal": HTTP 404: model not found (after 12s)
뜻: 하위 에이전트 실패 — "맡긴 목표": 모델을 찾지 못함(12초 뒤). 여러 개를 맡겼을 때는 작업별 완료 줄의 ✗ 표시 옆에 이유가 붙습니다.
확인: 돌아온 답에 세 주제의 요약이 모두 들어 있습니다. ✗ 가 붙은 작업이 있으면 이유를 읽고, 그 주제만 다시 맡깁니다.
6단계 · 필요할 때 멈추기
잘못 맡겼다면 멈출 수 있습니다. Ctrl+C 나 Esc 는 Hermes 의 지금 차례만 멈추고, 백그라운드에서 도는 하위 에이전트는 멈추지 않습니다. 이어서 메시지를 보내는 것도 마찬가지입니다.
/stop
뜻: 이 세션(대화 한 묶음)의 백그라운드 위임을 끝냅니다. 세션을 닫거나 /new 로 새로 시작해도 끝납니다. 하나만 멈추려면 4단계의 명단에서 고른 뒤 멈춤 키를 누릅니다(기본 CLI 는 x 다음 y, TUI 는 x). 다른 하위 에이전트는 계속 일합니다.
/stop 의 범위가 다릅니다.멈춘 하위 에이전트도 빈손으로 끝나지 않습니다. 멈추기 직전까지 쓴 내용이 interrupted(중단됨) 상태의 결과로 돌아옵니다. 확인: 멈췄다면 Subagent Task Interrupted: … 알림과 함께 부분 결과가 대화에 들어옵니다. 멈출 일이 없었다면 이 단계는 읽기만 하고 넘어갑니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| 조사가 엉뚱한 방향으로 감 | 하위 에이전트는 앞선 대화를 모릅니다. 2단계처럼 주제마다 초점을 적어 다시 맡깁니다. |
| 하위 에이전트가 나에게 되묻지 않음 · 기억에 남기지 않음 | 정해진 동작입니다. 하위 에이전트는 사용자에게 되묻기(clarify), 기억 쓰기(memory), 메시지 보내기(send_message), 예약 만들기(cronjob), 다시 위임하기(delegate_task)를 쓸 수 없습니다. 판단에 필요한 것은 처음부터 적어 줍니다. |
| 웹 조사를 하지 못함 | 하위 에이전트는 부모의 툴셋만 물려받습니다. 필요한 도구를 켜고(4장 툴셋) 새 대화에서 다시 맡깁니다. |
| 한참 조용함 | /agents 로 마지막 활동 시각을 봅니다. 움직이고 있으면 기다립니다 — 기본으로 시간제한이 없습니다. 진행이 완전히 멈춘 채 450초(도구 안에서는 1200초)가 지나면 Hermes 가 스스로 중단시키고, 목록에 stalling · no progress 450s — interrupting 으로 표시합니다. |
| Hermes 를 껐다 켰더니 하던 조사가 사라짐 | Hermes 프로세스가 다시 시작되면 실행 중이던 하위 에이전트는 이어지지 않습니다. 세션을 닫거나 Hermes 가 다시 시작돼도 끝까지 돌아야 하는 일은 예약 작업(실습 6)으로 만듭니다. |
한도와 설정 — 숫자로 보기
| 항목 | 기본값과 뜻 |
|---|---|
| 하위 에이전트 하나의 작업 횟수 | 도구를 쓰는 차례 250번(delegation.max_iterations). 다 쓰면 횟수 한도로 멈췄다는 표시와 함께 돌아옵니다. |
| 한 번 묻고 끝나는 실행 | hermes chat -q 같은 실행은 하위 에이전트를 합쳐 2개까지. |
다음에 할 것
- 주제 세 개를 내 조사 거리로 바꿔 봅니다. 주제마다 초점 한 줄을 꼭 붙입니다.
- 위임이 무엇이고 언제 쓰는지는 7장 위임이란에서 읽습니다.
- 같은 조사를 매일 받고 싶다면 실습 6, 휴대폰에서 맡기고 싶다면 실습 7을 봅니다.
하위 에이전트는 기본으로 부모와 같은 작업 폴더를 씁니다. 읽기만 하는 조사는 괜찮지만, 여럿이 같은 파일을 동시에 고치면 부딪칠 수 있습니다. 고치는 일은 7장 위임의 한도와 설정을 읽은 뒤에 맡깁니다.
- 서로의 결과를 기다리지 않는 일만 한 번에 묶어 맡깁니다.
- 하위 에이전트는 앞선 대화를 모릅니다. 주제마다 무엇을, 어디에 초점을 둘지 적습니다.
- 위임은 뒤에서 돌고, 결과는 모두 끝난 뒤 요약 묶음 하나로 돌아옵니다.
- Ctrl+T 나
/agents로 지켜보고, 멈출 때는/stop을 씁니다. - 하위 에이전트마다 모델을 따로 돌리므로 토큰이 더 듭니다.
출처: hermes-agent.nousresearch.com/docs/user-guide/features/delegation (수집본 sources/raw/user-guide_features_delegation.md). 가이드 7장 예약 작업과 위임. 2단계의 부탁 문장은 원문 예시의 주제·초점을 문장으로 옮긴 연습용입니다.
막힘 해결 ① — 설치가 안 되거나 답이 이상할 때
Hermes Agent 가 설치되지 않거나, 열리긴 하는데 답이 비어 있거나 엉뚱할 때 따라가는 순서입니다. 이것저것 한꺼번에 건드리지 않습니다. 증상을 한 줄로 적고, 원문이 정해 둔 순서대로 하나씩 확인한 뒤, 평범한 대화 한 번으로 고쳐졌는지 봅니다.
- 증상을 세 갈래 — 명령을 못 찾음 · 열리는데 답이 이상함 · 오류 문구가 나옴 — 로 나눕니다.
hermes doctor와hermes model로 설정을 알려진 상태로 되돌립니다.- 그래도 안 될 때 도움을 청하는 데 필요한 정보를 모읍니다.
예상 소요 시간: 10~20분
화면의 오류 문구를 지우지 말고 따라 하기 1단계부터 시작하세요. 오류 문구가 또렷하면 막히면의 표에서 같은 문구를 먼저 찾아도 됩니다. 메신저 봇이 답하지 않거나 기억·세션이 사라진 것 같을 때는 실습 10입니다.
준비물과 완료 기준
- 터미널(글자로 명령을 입력하는 창). 이 실습의 명령은 대부분 Hermes 대화 안이 아니라 터미널에 넣습니다.
- 화면에 나온 오류 문구 그대로. 메모장에 복사해 둡니다. 요약하지 말고 글자 그대로가 중요합니다.
- 내가 고른 제공자(provider — AI 모델을 빌려주는 서비스)의 로그인 정보나 API 키(서비스가 나를 알아보는 비밀 문자열).
평범한 대화 한 번이 오류 없이 답을 받으면 완료입니다. 원문의 원칙은 "설정을 고쳤으면 기능을 더 얹기 전에 평범한 대화부터 다시 시험한다"입니다.
따라 하기
1단계 · 증상을 한 줄로 적고 갈래 고르기
고치기 전에 무엇이 이상한지부터 적습니다. 화면의 오류 문구를 그대로 복사하고, 그 앞에 "무엇을 하다가"를 한 줄 붙입니다. 예: "설치 명령을 넣었더니 …", "hermes 를 열고 인사를 보냈더니 …".
그다음 위 그림에서 갈래를 고릅니다. 원문은 무언가 이상하게 느껴질 때 아래 순서로 확인하라고 적습니다. 이 실습은 ①~③을 다룹니다.
확인: 오류 문구를 복사해 두었고, 세 갈래 가운데 내 증상이 어디인지 골랐습니다.
2단계 · hermes 명령을 못 찾을 때
hermes: command not found 는 대부분 설치 실패가 아닙니다. 터미널이 새로 생긴 명령의 위치를 아직 읽지 않은 것입니다.
source ~/.bashrc # bash
source ~/.zshrc # zsh뜻: 셸(터미널 안에서 명령을 받아 실행하는 프로그램) 설정 파일을 다시 읽습니다. 내 셸에 맞는 한 줄만 넣습니다. 터미널 창을 새로 열어도 됩니다.
which hermes
ls ~/.local/bin/hermes뜻: hermes 명령의 위치를 묻고, 설치 자리에 파일이 있는지 봅니다. ~ 는 내 홈 폴더입니다.
- 파일은 있는데 명령을 못 찾는다면 — 셸 설정에 경로 한 줄이 빠진 것입니다. zsh 를 쓴다면 아래 줄을 넣은 뒤 터미널을 새로 엽니다.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc뜻: "명령을 찾을 때 ~/.local/bin 도 보라"는 한 줄을 zsh 설정 파일 끝에 덧붙입니다.
확인: which hermes 가 경로 한 줄을 내놓습니다.
권한 오류(Permission denied)가 날 때
| 언제 | 원문의 해결 |
|---|---|
| 설치 도중 | 설치 프로그램은 sudo(관리자 권한으로 실행하는 명령) 없이 실행합니다(~/.local/bin 에 설치됨). 전에 sudo 로 설치한 적이 있다면 sudo rm /usr/local/bin/hermes 로 그때 만들어진 파일을 지운 뒤 보통 설치 명령을 다시 실행합니다. |
source ~/.zshrc 를 넣었을 때 | Hermes 문제가 아니라 셸 설정 파일의 권한 문제입니다. ls -la ~/.zshrc 로 권한을 보고, chmod 644 ~/.zshrc 로 고친 뒤 source ~/.zshrc 를 다시 넣습니다. 또는 터미널을 새로 엽니다. |
3단계 · hermes doctor 로 진단하기
명령은 찾는데 무언가 이상하다면 진단부터 합니다.
hermes doctor뜻: 설치와 설정을 점검합니다. 원문은 이 명령이 "무엇이 빠졌고 어떻게 고치는지 정확히 알려 준다"고 적습니다. 결과에 나온 항목을 위에서부터 읽고, 안내된 방법대로 하나씩 고칩니다.
업데이트 뒤 설정 항목이 빠졌다는 문제에는 원문이 두 명령을 차례로 실행하라고 적습니다 — hermes config check(설정 점검), 그다음 hermes config migrate(설정을 새 형식으로 옮기기).
확인: doctor 가 짚은 항목과 고치는 방법을 읽었고, 안내대로 고쳤습니다. 짚은 것이 없거나 고친 뒤에도 답이 이상하면 다음 단계로 갑니다.
doctor 가 저장 위치(storage) 문제를 알릴 때
Hermes 데이터 폴더나 그 안의 폴더를 다른 저장 장치(외장 디스크·NAS)로 연결해 둔 경우입니다. 연결 대상이 없거나 접근할 수 없으면 Hermes 는 시작을 멈추고 경로를 알려 줍니다. 원문은 이때 config.yaml 을 그대로 두라고 적습니다 — hermes setup 은 이 문제의 해결책이 아닙니다. 저장 장치를 다시 연결하거나 연결 대상을 바로잡은 뒤 다시 시도합니다.
4단계 · 제공자와 모델 다시 확인하기
"열리는데 답이 비거나 깨진다"에 대해 원문이 꼽는 원인은 제공자 로그인이나 모델 선택이 잘못된 것입니다. 지금 설정을 본 뒤 다시 고릅니다.
hermes config show | head -20
hermes model뜻: 첫 줄은 저장된 설정의 앞 20줄을 보여 줍니다 — 어떤 모델(에이전트의 두뇌 역할을 하는 AI)과 제공자가 잡혀 있는지 봅니다. 둘째 줄은 제공자·모델·로그인을 처음부터 다시 고릅니다.
- 키와 제공자가 짝이 맞는지 봅니다. 키가 없거나, 기한이 지났거나, 잘못 붙여 넣었거나, 다른 제공자의 키일 때 생기는 문제입니다.
- 모델 이름은 손으로 치지 말고
hermes model이 보여 주는 목록에서 고릅니다. 이름에 오타가 있거나 그 제공자에 없는 모델이면 "찾을 수 없음"·400 오류가 납니다. - 모델 크기 — 컨텍스트(문맥 창 — 모델이 한 번에 기억하며 볼 수 있는 글의 양)가 64,000 토큰(AI 가 읽고 쓰는 글의 양을 세는 단위)보다 작은 모델은 시작할 때 거부됩니다.
확인: hermes model 을 끝까지 마쳤고, hermes config show | head -20 에 방금 고른 모델·제공자가 보입니다.
키를 직접 넣기 · 여전히 꼬여 있을 때
- 키를 명령으로 직접 넣는 원문 예시:
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx— 뒤쪽 자리에 내 키를 넣습니다. 비밀 값은~/.hermes/.env에 저장됩니다. - 원문은
~/.hermes/.env에 서로 부딪치는 항목이 없는지 보라고 적습니다. 예전에 넣은 다른 제공자의 키가 남아 있는 경우입니다. - 모델을 명령으로 정하는 원문 예시:
hermes config set model.default anthropic/claude-opus-4.7 hermes model로도 정리되지 않으면 복구 순서의 ③hermes setup(설정 마법사 전체)으로 넘어갑니다.- 직접 운영하는 모델 서버(custom endpoint)가 엉뚱한 답을 낸다면 주소(base URL)·모델 이름이 틀렸거나 호환되지 않는 서버일 수 있습니다. 원문은 다른 프로그램에서 그 서버가 제대로 답하는지 먼저 확인하라고 적습니다.
5단계 · 평범한 대화 한 번으로 다시 시험하기
고쳤으면 가장 단순한 대화로 시험합니다. 아래 명령은 화면을 열지 않고 한 번 묻고 답을 받은 뒤 끝납니다.
hermes chat -q "Hello"뜻: Hermes 에게 "Hello" 한마디를 보내고 답을 받습니다.
답이 오면 고쳐진 것입니다. 원문의 원칙을 한 번 더 적습니다 — 평범한 대화가 되기 전에는 메신저 연결·예약 작업·스킬 같은 기능을 얹지 않습니다. 여러 제공자를 오가게 하는 설정(routing·fallback)도 기본 제공자가 안정된 뒤에 켭니다.
확인: hermes chat -q "Hello" 가 오류 없이 답을 내놓았습니다. 이어서 hermes 로 대화 화면도 정상으로 열립니다.
잘 되는 것으로 알려진 모델로 시험하기
모델 이름이 의심스러울 때 원문은 모델을 지정해 시험하는 예시를 듭니다: hermes chat -q "hello" --model anthropic/claude-opus-4.7. 이 모델로는 되고 내 설정으로는 안 된다면 저장된 모델 이름이 원인입니다. 내 제공자가 이 모델을 제공하지 않으면 이 시험도 실패하니, 그때는 hermes model 목록에 있는 이름으로 바꿔 넣습니다.
6단계 · 그래도 안 되면 — 도움 청할 정보 모으기
여기까지 해도 안 되면 혼자 더 붙잡지 않습니다. 원문은 문제를 알릴 때 네 가지를 함께 적으라고 합니다.
hermes --version
python3 --version뜻: Hermes 버전과 Python(Hermes 가 돌아가는 데 쓰는 프로그래밍 언어 실행기) 버전을 보여 줍니다.
- 운영체제macOS·Linux·Windows 가운데 무엇이고 어떤 버전인지.
- Python 버전과 Hermes 버전위 두 명령의 결과.
- 오류 문구 전체1단계에서 복사해 둔 것. 줄이지 않습니다.
원문이 안내하는 곳은 세 군데입니다 — 이미 올라온 문제 찾아보기(GitHub Issues), 커뮤니티에 묻기(Nous Research Discord), 버그 신고. 올리기 전에 문구 안에 API 키가 섞여 있지 않은지 꼭 봅니다.
확인: 운영체제 · 두 버전 · 오류 문구 전체, 네 가지를 한곳에 모았습니다.
막히면 — 오류 문구로 찾기
| 보이는 문구·증상 | 뜻과 해 볼 것 |
|---|---|
hermes: command not found | 셸이 새 경로를 읽지 않았습니다. 2단계. |
API key not set · 키가 통하지 않음 | hermes model 로 제공자를 다시 설정합니다. 키와 제공자가 짝이 맞는지 봅니다. 4단계. |
| 첫 대화에서 HTTP 400 | 대개 모델 이름이 맞지 않는 것입니다 — 설정된 모델이 그 제공자에 없거나 내 키로는 쓸 수 없습니다. 4단계. OpenRouter 라면 키에 크레딧이 있는지도 봅니다. |
| Model not found · not available | 모델 이름이 틀렸거나 내 제공자에 없습니다. hermes model 목록에서 다시 고릅니다. |
| 429 (rate limit) | 제공자의 사용 한도를 넘었습니다. 잠시 기다렸다 다시 보냅니다. 자주 나면 요금제를 올리거나 다른 모델·제공자를 씁니다. |
| Context length exceeded | 대화가 모델이 감당하는 길이를 넘었습니다. 대화 안에서 /compress(대화 압축)를 넣거나, hermes chat 으로 새 세션(대화 한 묶음)을 시작합니다. |
/model 에 제공자가 하나만 보임 | 대화 안의 /model 은 이미 설정한 제공자끼리만 바꿉니다. /quit 으로 나가 터미널에서 hermes model 로 제공자를 추가한 뒤 새 대화를 엽니다. |
| 답이 "Hermes 정책(policy·guardrails) 때문에 거절한다"고 말함 | 글로만 된 거절은 Hermes 가 막았다는 증거가 아닙니다. 원문은 Hermes 가 막을 때는 막힌 명령·경로를 적은 도구 오류나 승인 요청이 따로 보인다고 적습니다. /status 로 모델·제공자를 확인하고, 새 세션에서 다른 모델로 다시 해 봅니다. 모델을 바꾸면 달라지는 거절은 모델·제공자 쪽 동작입니다. |
…refused this request because of a policy on your account | 제공자가 계정 사정으로 거절한 것이라 다시 보내도 같습니다. 문구에 나온 제공자에서 계정 상태와 개인정보 설정을 확인하거나 /model 로 다른 모델·제공자로 바꿉니다. |
Could not open a stream to <host> after N attempts (request X KB) | 그 주소로 연결이 한 번도 되지 않았습니다(요금은 나가지 않음). 요청 크기가 수백 KB 로 크고 짧은 새 대화는 된다면 /compress 로 줄입니다. 작다면 서버에 닿지 않는 것이니 주소 설정을 확인한 뒤 /retry. |
| 답이 너무 느림 | 원문이 꼽는 원인은 큰 모델, 먼 서버, 도구가 많아 무거워진 요청입니다. 더 빠른 모델로 바꾸거나, hermes chat -t "terminal" 처럼 쓸 툴셋(toolset — 도구 꾸러미)을 줄여 열어 봅니다. |
드물게 만나는 설치·환경 문제
| 문구 | 원문의 설명 |
|---|---|
uv: command not found | 패키지 관리 도구 uv 가 없거나 경로에 없습니다. 원문의 해결: curl -LsSf https://astral.sh/uv/install.sh | sh 뒤 source ~/.bashrc. |
| Unsupported Python version | 지금 설치본은 Python 3.14 로 돌아갑니다. 설치 프로그램과 묶음 설치본이 맞는 Python 을 함께 제공하므로 설치된 앱 안의 Python 을 바꿔 끼우지 않습니다. hermes doctor 를 실행하고 그 설치 방식의 업데이트 방법을 씁니다. |
에이전트가 실행한 명령이 node: command not found(또는 nvm·pyenv 등) | Hermes 가 터미널 환경을 준비할 때 내 셸 설정 일부를 읽지 못한 경우입니다. ~/.hermes/config.yaml 의 terminal: 아래 shell_init_files: 목록에 읽을 파일(예: ~/.zshrc)을 적습니다. |
| Context length exceeded 가 첫 긴 대화에서 바로 남 | Hermes 가 모델의 컨텍스트 길이를 잘못 알고 있을 수 있습니다. 시작할 때 나오는 줄(예: 📊 Context limit: 128000 tokens)이나 /usage 로 확인하고, config.yaml 의 model: 아래 context_length: 에 실제 값을 적습니다. 직접 돌리는 모델 서버에서 주로 생깁니다. |
다음에 할 것
- 고쳐졌다면 하던 실습으로 돌아갑니다. 처음이라면 실습 1.
- 이어 하기가 안 되거나 세션이 안 보이면 실습 2의 「막히면」, 메신저 봇·기억 문제는 실습 10.
- 증상별 설명 전체는 완전 가이드 10장 자주 묻는 질문·그래도 안 될 때, 원문의 실패 유형 표는 1장 자주 겪는 실패·복구 순서.
- 오류 문구를 그대로 복사하고, 세 갈래 가운데 어디인지부터 고릅니다.
- 명령을 못 찾으면 셸 설정을 다시 읽거나 터미널을 새로 엽니다. 설치에
sudo는 쓰지 않습니다. - 순서는
hermes doctor→hermes model→hermes setup. - 답이 비거나 깨지면 제공자·모델·키의 짝부터 의심합니다.
- 고칠 때마다
hermes chat -q "Hello"로 시험하고, 되기 전에는 기능을 얹지 않습니다.
출처: hermes-agent.nousresearch.com/docs/reference/faq(Troubleshooting — Installation Issues · Provider & Model Issues · Performance Issues · Permission denied when reloading shell after install · Error 400 on first agent run · Still Stuck?) · getting-started/quickstart(Common Failure Modes · Recovery Toolkit) · getting-started/installation(Troubleshooting · Symlinked home directories) · user-guide/cli(Running the CLI). 수집일 2026-11-09. 예상 소요 시간과 "무엇을 하다가" 예문은 이 활용편의 것입니다.
막힘 해결 ② — 봇이 답하지 않거나, 기억·세션이 사라진 것 같을 때
"고장 났다"고 느껴지는 세 가지 증상을 차례대로 좁혀 봅니다. 대부분은 고장이 아니라 게이트웨이가 꺼져 있거나, 저장이 실제로는 안 됐거나, 다른 곳을 보고 있는 경우입니다.
- 증상을 보고 어느 길로 점검할지 고릅니다.
- 봇이 답하지 않을 때 게이트웨이 → 토큰 → 허용 목록 순서로 확인합니다.
- "기억해 둘게요"라고 했는데 잊은 것 같을 때 기억 파일을 직접 열어 봅니다.
- 사라진 것 같은 지난 대화를 세션 목록에서 찾아 이어 합니다.
예상 소요 시간: 증상 하나에 10~15분
준비물과 완료 기준
- Hermes Agent 를 설치한 컴퓨터의 터미널(글자로 명령을 입력하는 창). 설치나 첫 대화부터 안 된다면 실습 9가 먼저입니다.
- 봇 증상이라면 실습 7에서 만든 Telegram 봇과 내 사용자 ID.
- 증상 메모 한 줄 — 무엇을 했고, 무엇을 기대했고, 실제로 무슨 일이 있었는지.
고른 길의 끝에 있는 확인을 통과하면 완료입니다. 봇이 다시 답하거나, 기억 파일에서 내 항목을 눈으로 확인하거나, 세션 목록에서 찾던 대화를 발견하는 것입니다.
따라 하기
1단계 · [A] 게이트웨이가 켜져 있는지 보기
봇의 답은 내 컴퓨터에서 도는 게이트웨이(gateway — 메신저와 Hermes 를 이어 주는, 계속 켜 두는 프로그램)가 만듭니다. 원문은 봇이 답하지 않는 원인을 "봇이 돌고 있지 않거나, 권한이 없거나, 내가 허용 목록에 없다"로 꼽습니다. 가장 흔한 첫 번째부터 봅니다.
# Check if the gateway is running
hermes gateway status
# Start the gateway
hermes gateway start
# Check logs for errors
cat ~/.hermes/logs/gateway.log | tail -50
뜻: 차례로 게이트웨이가 도는지 확인 · 게이트웨이 시작 · 기록(로그)의 마지막 50줄 보기입니다. ~ 는 내 홈 폴더입니다. 서비스로 설치하지 않았다면 hermes gateway 로 터미널에서 직접 켭니다(실습 7의 4단계).
확인: 게이트웨이를 켠 뒤 Telegram 에서 메시지를 보내면 답이 옵니다. 그래도 조용하면 기록 마지막 줄의 오류 문장을 메모하고 2단계로 갑니다.
게이트웨이가 아예 켜지지 않을 때 · 켜져 있는데 멈춘 것 같을 때
원문이 꼽는 원인은 필요한 부품 누락, 포트 충돌, 잘못된 토큰입니다. 아래 순서로 봅니다.
cd ~/.hermes/hermes-agent && python -c "import pm; pm.sync_venv(['messaging'], explicit=True)"
lsof -i :8080
hermes config show뜻: 메신저 게이트웨이에 필요한 부품 설치 · 8080 포트를 다른 프로그램이 쓰는지 확인 · 지금 설정 보기입니다. hermes gateway status 에 Gateway heartbeat stale 경고가 보이면 "돌고는 있는데 아무 일도 안 하는" 상태이니 게이트웨이를 다시 시작합니다. Windows 의 WSL 에서는 서비스 방식이 불안정하다고 원문이 적습니다 — hermes gateway run 으로 터미널에서 직접 켭니다. 자세한 것은 10장 게이트웨이 문제.
2단계 · [A] 토큰과 허용 목록 확인하기
게이트웨이가 켜져 있는데도 안 된다면, 메시지가 어느 문에서 막혔는지 증상으로 가릅니다.
| 증상 | 확인할 것 |
|---|---|
| 전혀 답이 없음 | TELEGRAM_BOT_TOKEN 이 맞는지 봅니다. hermes gateway setup 을 다시 열어 토큰을 확인·재입력하는 것이 가장 쉽습니다. 토큰이 무효가 됐다면 BotFather 에서 /revoke 뒤 /newbot 또는 /token 으로 새로 받아 .env 를 고칩니다. |
| "unauthorized"(권한 없음) | 내 사용자 ID 가 TELEGRAM_ALLOWED_USERS 에 없습니다. @userinfobot 으로 숫자를 다시 확인합니다. 이 값을 비워 두면 게이트웨이는 안전을 위해 모든 사람을 거절합니다. |
| 1:1 은 되는데 그룹만 조용 | privacy mode(사생활 보호 모드)가 켜져 있을 가능성이 큽니다. BotFather 에서 끄거나 봇을 그룹 관리자로 올리고, 바꾼 뒤에는 봇을 그룹에서 내보냈다가 다시 넣습니다. 방법은 실습 7 막히면. |
확인: 고친 뒤 게이트웨이를 다시 시작하고 메시지를 보내면 Hermes 의 답이 옵니다.
3단계 · [B] 기억이 실제로 저장됐는지 파일 열어 보기
가장 흔한 사연은 이렇습니다. 무언가의 위치를 알려 주자 Hermes 가 "기억해 두겠습니다"라고 답했는데, 새 세션(대화 한 묶음)에서는 전혀 모릅니다. 원문은 이 순서로 확인하라고 하며, 첫 번째가 대부분을 설명한다고 적습니다.
기억(memory — 세션이 끝나도 남는 메모)은 모델이 memory 도구를 실제로 썼을 때만 남습니다. "기억에 추가했습니다"라는 문장은 그냥 글일 뿐입니다. 파일을 직접 엽니다.
cat ~/.hermes/memories/MEMORY.md
cat ~/.hermes/memories/USER.md
뜻: 기억 파일 두 개의 내용을 화면에 보여 줍니다. MEMORY.md 는 Hermes 가 적는 메모, USER.md 는 나에 대한 정보입니다.
찾는 내용이 없다면 저장한 척만 한 것입니다. 작은 로컬 모델(대략 30B 파라미터 미만)이나 도구 호출이 약한 모델에서 자주 생깁니다. 이럴 때는 도구를 쓰라고 콕 집어 말합니다.
use the memory tool to save the vault path /srv/vault
뜻: "memory 도구를 써서 보관함 경로 /srv/vault 를 저장해 줘." 경로는 내 것으로 바꿉니다. 계속 반복되면 지시를 늘릴 것이 아니라, 저장하는 동안만이라도 더 강한 모델을 쓰는 것이 해결책이라고 원문은 적습니다.
확인: cat 명령을 다시 실행했을 때 방금 부탁한 내용이 파일에 보입니다.
4단계 · [B] 파일에는 있는데 모른다면 — 새 세션에서 다시 묻기
기억은 세션이 시작될 때 한 번 읽혀 그 세션 내내 그대로 쓰입니다. 세션 도중에 저장한 내용은 파일에는 바로 적히지만, 이미 진행 중인 세션에는 보이지 않고 다음 세션부터 보입니다.
/new 로 직접 경계를 만들어야 합니다.- 새 세션 시작하기대화 중이라면
/new를 보냅니다. 터미널에서는hermes를 새로 실행해도 새 세션입니다. - Telegram 이라면 특히
/new메신저의 대화는 일부러 하나로 이어지게 만들어져 있어, 컴퓨터를 밤새 껐다 켜도 같은 세션입니다. 다시 시작한 것은 경계가 되지 않습니다. - 저장한 내용을 물어보기저장을 부탁했던 것(예: 보관함 경로)을 새 세션에서 물어봅니다.
확인: 새 세션에서 Hermes 가 저장한 내용을 알고 답합니다.
그래도 모른다면: 원문의 나머지 점검 항목
| 원인 | 확인 방법 |
|---|---|
| 저장이 승인 대기 중 | write_approval: true 설정이면 터미널 대화 밖(메신저 등)의 저장은 승인 전까지 파일에 적히지 않습니다. /memory pending 으로 보고 /memory approve all 로 승인합니다. |
| 다른 프로필을 보고 있음 | 기억은 프로필(설정·기억·세션을 따로 쓰는 별도 Hermes 환경)마다 따로입니다. hermes -p work 는 ~/.hermes/profiles/work/memories/ 를 읽습니다. 기본 프로필의 터미널 대화와 다른 프로필의 Telegram 봇은 기억을 나누지 않습니다. hermes profile list 로 무엇이 있는지 봅니다. |
| 기억 기능이 꺼져 있음 | memory.memory_enabled: false 이거나 agent.disabled_toolsets 에 memory 가 있으면 도구 자체가 없어 저장할 수 없습니다. |
| 기억이 아닌 곳에 적음 | .env 에 적은 값은 비밀 값·설정이지 기억이 아닙니다. 저장을 부탁하지 않고 지나가며 말한 사실도 남지 않습니다. |
반복 작업마다 필요한 위치 정보는 기억보다 스킬에 두는 편이 낫다고 원문은 권합니다. 5장 기억했다더니 잊었을 때.
5단계 · [C] 사라진 것 같은 대화를 세션 목록에서 찾기
터미널·TUI·메신저의 모든 대화는 ~/.hermes/state.db 한 곳에 세션으로 저장됩니다. 자동 정리는 기본으로 꺼져 있고, 켜더라도 끝난 세션만 지웁니다. 그러니 "안 보인다"는 대개 "아직 못 찾았다"입니다.
hermes sessions list
hermes sessions list --source telegram
hermes sessions list --limit 50
뜻: 최근 세션 20개 보기 · Telegram 에서 한 대화만 보기 · 50개까지 늘려 보기입니다. 목록 끝에 "more not shown" 이라는 줄이 있으면 더 있다는 뜻이니 --limit 숫자를 키웁니다.
hermes --continue
hermes --resume 20250305_091523_a1b2c3d4
hermes --resume "refactoring auth"뜻: 가장 최근 세션 이어 하기 · 목록의 ID 로 이어 하기 · 제목으로 이어 하기입니다. ID 와 제목은 원문의 예시이니 내 목록에 보이는 값으로 바꿉니다.
대화방에서 /sessions 를 보내면 이 대화방의 지난 세션이 나오고, 지금 세션에는 (current) 표시가 붙습니다. 많으면 /sessions search <찾을 말> 로 제목·ID 를 걸러 냅니다. /resume <이름> 으로 그 세션을 다시 엽니다.
~/.hermes/sessions/sessions.json 파일에는 메신저 항목만 있는데, 이 파일은 세션 목록이 아니므로 터미널 대화가 없어 보여도 정상입니다.확인: 목록에서 찾던 대화의 미리 보기 문장이나 제목을 발견했고, 이어 한 뒤 Hermes 가 지난 내용을 알고 있습니다.
목록에 정말 없을 때
프로필마다 세션 저장소가 따로이니 다른 프로필에서 한 대화가 아닌지 먼저 봅니다. 보관(archive) 처리한 세션은 hermes sessions list 와 /resume 에서 숨겨질 뿐 지워지지 않으며, 원문은 데스크톱 앱·대시보드의 세션 목록에서 보관을 풀 수 있다고만 적습니다. 터미널 대화가 정말로 목록에 들어오지 않는다면 hermes sessions repair 를 실행하고, 시작할 때 ⚠ Session store unavailable 경고가 뜨는지 봅니다. 세션을 지우는 명령(hermes sessions prune·hermes sessions delete)을 쓰기 전에는 hermes sessions export backup.jsonl 로 먼저 내보내 둡니다. 2장 세션이 저장되는 곳.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| 답이 두 번 왔고 "♻️ Recovered reply" 로 시작함 | 고장이 아닙니다. 게이트웨이가 답을 보내던 중 멈췄다가 다시 켜지면, 답을 잃지 않으려고 저장해 둔 답을 다시 보내며 중복일 수 있다고 표시합니다. |
| 다시 켠 뒤 "아무 메시지나 보내면 이어 하겠다"는 안내가 옴 | 작업 도중에 게이트웨이가 꺼졌던 세션입니다. 아무 메시지나 답하면 마지막으로 저장된 지점부터 이어 갑니다. |
| 어제 Telegram 대화가 오늘도 그대로 이어짐 | 정상입니다. 메신저 대화는 쉬어도, 날이 바뀌어도 초기화되지 않습니다. 새로 시작하려면 /new 를 보냅니다. |
| 오래 쓴 대화방이 느리고 비용이 큼 | 세션 하나를 몇 주씩 쓰면 대화가 길어져 비용이 늘고 기억도 제 역할을 못 합니다. 일이나 주제가 끝날 때 /new 로 끊습니다. 끊기 전에 "remember anything worth keeping"(뜻: 남길 만한 것은 기억해 줘)이라고 부탁하면 도움이 됩니다. |
| macOS 에서 게이트웨이가 ffmpeg 같은 도구를 못 찾음 | 서비스는 설치할 때의 경로 정보만 압니다. 도구를 나중에 깔았다면 hermes gateway install 을 다시 실행한 뒤 hermes gateway start 를 실행합니다. |
| 여기까지 해도 안 됨 | 증상 메모와 게이트웨이 기록의 오류 문장을 챙겨 10장 그래도 막힐 때를 봅니다. |
다음에 할 것
- 기억이 어떻게 저장되고 언제 읽히는지 — 5장 기억이란. 직접 남겨 보기는 실습 3.
- 세션에 이름을 붙여 두면 다음에 찾기 쉽습니다 — 실습 2, 2장 세션 이름.
- 게이트웨이를 서비스로 늘 켜 두기 — 실습 7의 6단계, 8장 서비스.
- 설치·모델 쪽 문제 — 실습 9.
- 봇이 조용하면
hermes gateway status부터, 그다음 토큰과 허용 목록을 봅니다. - "기억할게요"는 글일 뿐입니다.
~/.hermes/memories/의 파일에 있어야 저장된 것입니다. - 저장한 기억은 다음 세션부터 보입니다. 메신저에서는
/new로 직접 끊습니다. - 대화는
state.db에 남아 있습니다.hermes sessions list와/sessions로 찾아 이어 합니다.
출처: hermes-agent.nousresearch.com/docs/reference/faq (Messaging Issues · Profiles), /docs/user-guide/messaging, /docs/user-guide/messaging/telegram (Troubleshooting · Security), /docs/user-guide/features/memory (Memory Needs Session Boundaries · Troubleshooting), /docs/user-guide/sessions (수집일 2026-11-09). 가이드 8장 문제 해결·2장 이어 하기. 세션 ID·제목·경로는 원문의 예시 값입니다.