Field Log · Entry

Hermes Agent 사용법: 설치보다 먼저 첫 작업 계약을 만든다 (1/7)

검증 가능한 작업 계약이 Hermes Agent의 모델 도구 세션 프로젝트 문맥을 통과해 결과와 증거를 만드는 첫 사용 흐름

이번 글의 결론

여기서 Hermes는 Hermes 4 모델이 아니라 Nous Research의 오픈소스 Hermes Agent입니다.

첫 성공 기준은 “대화가 된다”가 아니라 읽기 전용 작업 하나를 끝내고, 결과를 사람이 5분 안에 검증할 수 있는가입니다.

hermes setup 뒤에 Gateway·Cron·여러 스킬을 한꺼번에 붙이지 않습니다. CLI 한 세션, 한 모델, 한 작업부터 고정합니다.

AGENTS.md는 프로젝트 규칙, SOUL.md는 전역 성격, Memory는 지속할 사실, Skill은 필요할 때만 불러올 절차입니다.

모델을 바꾸기 전에 도구 범위·작업 계약·검증 기준을 먼저 고쳐야 개선 원인을 알 수 있습니다.

이 글은 2026년 7월 21일, Hermes Agent v0.19.0을 기준으로 작성했습니다. Hermes는 변화가 빠르므로 설치 전에 공식 릴리스와 Quickstart를 함께 확인하세요.

Hermes와 OpenClaw의 사용 구축 최적화를 거쳐 Block의 자율 엔지니어링 조직으로 이어지는 7편 학습 경로

1. Hermes Agent를 한 문장으로 정의한다

Hermes Agent는 모델 그 자체가 아닙니다. 여러 LLM provider 중 하나를 골라 호출하고, 파일·터미널·웹·MCP 같은 도구를 연결하며, 세션·기억·스킬을 유지하는 개인용 에이전트 런타임입니다.

공식 아키텍처를 사용자의 시선으로 줄이면 다음과 같습니다.

CLI / TUI / Messaging Gateway / API
                ↓
           Agent loop
   prompt · provider · tool dispatch
                ↓
  session DB · memory · skill · backend

따라서 “Hermes가 Claude보다 좋은가?”만 묻는 것은 층위를 섞은 질문입니다. Hermes 안에서도 Claude·GPT·Gemini·Qwen·로컬 OpenAI-compatible endpoint 등을 선택할 수 있습니다. 먼저 물어야 할 것은 이것입니다.

내가 계속 맡길 작업은 무엇이며, 그 작업에 필요한 모델·도구·기억·권한은 어디까지인가?

2. 설치 전에 첫 작업 계약을 쓴다

처음부터 “내 일을 전부 도와줘”라고 하면 성공과 실패를 구분할 수 없습니다. 이 블로그 저장소를 예로 들면 첫 작업을 다음처럼 자릅니다.

task: 최근 글 3개의 frontmatter 점검
input:
  - src/content.config.ts
  - src/content/posts 아래 최근 Markdown 3개
allowed_actions:
  - 파일 읽기
  - 검색
forbidden_actions:
  - 파일 수정
  - 패키지 설치
  - 네트워크 전송
output:
  - 파일별 위반 항목 표
  - 근거가 된 schema 필드
done_when:
  - 각 지적에 파일 경로와 실제 값이 있음
  - 문제가 없으면 "없음"이라고 명시함

이 계약은 작지만 중요한 네 가지를 고정합니다.

입력 범위
허용 행동
산출물 형식
사람이 확인할 완료 조건

첫 작업은 읽기 전용·짧은 시간·정답 확인 가능이어야 합니다. 이메일 발송, Git push, 결제, 운영 서버 변경은 첫 실험에 맞지 않습니다.

3. 설치하고 한 모델만 연결한다

Linux·macOS·WSL2에서는 공식 installer를 사용합니다.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc  # zsh라면 source ~/.zshrc

Windows native PowerShell 경로도 별도로 지원됩니다.

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

그다음 설정 wizard를 실행합니다.

hermes setup

Nous Portal을 쓸 계획이라면 model과 Tool Gateway를 한 번에 연결하는 경로가 가장 짧습니다.

hermes setup --portal

별도 API key나 로컬 모델을 쓰려면 provider 선택부터 고정합니다.

hermes model

공식 Quickstart는 agent tool-calling에 최소 64K context를 요구합니다. 로컬 endpoint가 HTTP 응답만 잘 돌려준다고 끝이 아닙니다. 실제 model name, context length, tool-call 호환성을 각각 확인해야 합니다.

설정은 둘로 나뉩니다.

~/.hermes/config.yaml   # 일반 설정
~/.hermes/.env          # token과 secret

설정 파일에 API key를 직접 섞기보다 CLI를 통하면 값의 성격에 맞는 위치로 저장됩니다.

hermes config set model anthropic/claude-sonnet-4.6
hermes config set terminal.backend docker

실제 model ID는 provider catalog에서 바뀔 수 있으므로 hermes model이 보여 주는 현재 목록을 우선합니다.

4. 첫 대화는 기능 시연이 아니라 진단이다

프로젝트 root로 이동한 뒤 TUI를 엽니다.

cd /path/to/project
hermes --tui

첫 prompt는 다음처럼 씁니다.

현재 저장소를 수정하지 마세요.
src/content.config.ts와 최근 Markdown 글 3개를 읽고,
frontmatter schema 위반 가능성을 표로 정리하세요.
각 행에는 파일 경로, 실제 값, 근거 schema를 포함하세요.
확실하지 않은 내용은 추정이라고 표시하세요.

여기서 확인할 것은 답변의 유창함이 아닙니다.

시작 banner의 provider와 model이 의도한 값인가
파일 읽기 외의 도구를 시도하지 않았는가
존재하지 않는 경로나 규칙을 만들지 않았는가
각 결론에 검증 가능한 근거가 있는가
같은 대화의 후속 질문에서 앞선 범위를 유지하는가

세션이 실제로 저장되는지도 바로 확인합니다.

hermes --continue
hermes sessions list

세션 복구가 안 되는데 Telegram·Cron부터 붙이면 나중에 실패 지점을 찾기 더 어렵습니다.

5. 도구는 “많이”가 아니라 “필요한 것만” 켠다

대화 안에서는 /tools, CLI에서는 hermes tools로 현재 도구를 확인하고 platform별로 조정할 수 있습니다.

첫 읽기 전용 점검에 필요한 것은 대체로 다음뿐입니다.

필요: file read · file search
선택: safe terminal commands
불필요: browser · email · cron · delegation · file write

격리가 필요하면 terminal backend를 Docker나 SSH로 바꿀 수 있습니다.

hermes config set terminal.backend docker
# 또는 별도 작업 서버
hermes config set terminal.backend ssh

중요한 차이가 있습니다. 명령 승인 규칙은 정직하지만 실수할 수 있는 agent를 막는 guardrail이고, container는 agent process가 host에 미치는 영향을 줄이는 security boundary입니다. 승인창을 많이 띄운다고 sandbox가 생기지는 않습니다. 자세한 경계는 Hermes Security 문서를 참고하세요.

6. 프로젝트 문맥과 전역 성격을 섞지 않는다

현재 Hermes의 Context Files 규칙은 다음 우선순위를 사용합니다.

project instructions
.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules
첫 일치 파일만 사용

global identity
$HERMES_HOME/SOUL.md

AGENTS.md에는 검증 가능한 작업 정보만 둡니다.

# Repository Guide

## Commands
- Build: npm run build
- Dev: npm run dev

## Content contract
- Frontmatter schema: src/content.config.ts
- Published posts: src/content/posts/**/*.md

## Guardrails
- Do not edit dist/
- Never commit .env files
- Site changes must pass npm run build

말투나 성격은 전역 SOUL.md에 둡니다. “테스트 명령은 무엇인가”와 “어떤 어조로 대답하는가”를 한 파일에 섞으면 프로젝트를 바꿀 때도 불필요한 성격 지시가 따라옵니다.

Hermes는 하위 폴더로 이동할 때 그 위치의 AGENTS.md 등을 점진적으로 발견합니다. 큰 저장소에서 모든 규칙을 root prompt에 넣지 않아도 되는 이유입니다.

7. 반복이 확인된 뒤에만 Skill로 만든다

Skill은 매번 system prompt에 전부 넣는 지식이 아니라, 작업이 맞을 때 불러오는 절차입니다. Hermes는 ~/.hermes/skills/의 SKILL.md를 읽고 slash command로 노출합니다.

대화 1회 성공
  → 같은 작업 3회 반복
  → 달라진 입력과 실패 기록
  → 안정된 절차를 Skill로 저장

공식 기능인 /learn으로 방금 수행한 절차를 skill 초안으로 만들 수도 있습니다.

/learn how I just audited Astro post frontmatter

하지만 “agent가 스스로 배웠다”는 말이 자동으로 올바른 절차가 됐다는 뜻은 아닙니다. Skills System에는 agent의 skill write를 review queue로 보내는 skills.write_approval 설정이 있습니다. 운영 환경에서는 초안을 diff로 검토한 뒤 승인하는 편이 안전합니다.

8. 첫날 완료 체크리스트

기준 version과 설치 출처를 기록했다.
provider와 model 하나만 연결했다.
읽기 전용 작업 계약을 먼저 썼다.
필요한 tool만 노출했다.
결과의 경로·값·근거를 사람이 확인했다.
hermes --continue로 session 복구를 확인했다.
AGENTS.md와 전역 SOUL.md의 역할을 분리했다.
실패하면 hermes doctor부터 실행할 수 있다.

마무리

Hermes의 장점은 처음부터 많은 일을 시키는 데 있지 않습니다. 한 작업을 마친 경험에서 기억할 사실과 재사용할 절차를 분리하고, 다음 실행에 다시 쓰는 학습 loop에 있습니다. 그래서 첫날의 핵심 산출물은 화려한 bot이 아니라 다음 세 가지입니다.

작업 계약 1개
검증 기록 1개
다음 반복에서 바꿀 변수 1개

다음 글에서는 이 CLI 실험을 항상 켜진 VPS로 옮깁니다. Gateway와 Telegram을 연결하되, host 전체를 내주는 대신 service 계정·Docker backend·allowlist로 실행 경계를 먼저 만들겠습니다.