상주하는 AI 에이전트 세우기 — Hermes 설치부터 Claude 연결·Discord 배선까지

상주하는 에이전트를 하나 갖는다는 건, 터미널을 여는 순간에만 존재하던 도구가 항상 켜져 있는 무언가로 바뀐다는 뜻이다. 폰에서 한 줄 던지면 받아 적고, 자정에 깨어나 돌아보고, 물어보면 답한다.

이 글은 그걸 실제로 세우는 순서다 — Hermes Agent 설치부터, 모델을 Claude 로 바꾸고, Discord 에 붙이는 것까지. 우리가 직접 세우면서 확인한 것만 적었고, 안 적힌 함정도 같이 적었다.

0. 무엇을 세우는가

Hermes Agent 는 Nous Research 가 만든 상주형 에이전트다. 특징 셋:

• 채널을 고를 수 있다 — Discord / Telegram / Slack / WhatsApp / Signal / Email / CLI
• 모델을 고를 수 있다 — Anthropic·OpenAI·Nous 등. 프로바이더가 교체 가능한 층으로 분리돼 있다
• 디스크에 상태를 남긴다 — 기억·스킬·크론·훅이 파일로 쌓인다. 이게 가장 과소평가된 부분이다

1. 설치 — 한 줄

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

Python 과 Node 를 알아서 챙긴다. 끝나면 두 군데가 생긴다.

~/.local/bin/hermes      실행 파일
~/.hermes/               데이터·설정 전부

확인:

hermes --version

⚠️ 홈 디렉토리에 깔린다. 프로젝트 레포 안이 아니다. 우리는 처음에 레포 안만 뒤지다 "설치가 안 됐다"고 오판했다. 설치 여부는 which hermes 로 본다.

2. 뭐가 깔렸는지 먼저 읽어라

대부분의 설치 가이드가 여기서 끝나지만, 실은 여기서 시작해야 한다. ~/.hermes/ 를 열어보면 이 에이전트가 무엇을 하는 물건인지가 그대로 드러난다.

기억(memories)과 스킬(skills)이 분리돼 있다는 게 설계의 핵심이다. 하나는 "무엇을 아는가", 다른 하나는 "어떻게 하는가"다. 이 구분은 상주 에이전트를 오래 굴려 보면 반드시 필요해진다 — 사실을 쌓는 것과 절차를 쌓는 것은 수명도 갱신 주기도 다르기 때문이다.

3. 모델을 Claude 로

기본 프로바이더는 Nous 의 무료 모델이다. 돌아는 가지만, 실제 작업을 시킬 거면 바꿔야 한다.

Hermes 의 Anthropic 프로바이더는 이렇게 정의돼 있다:

"anthropic": HermesOverlay(
    transport="anthropic_messages",
    extra_env_vars=("ANTHROPIC_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"),
)

인증 우선순위는 ANTHROPIC_API_KEY → ANTHROPIC_TOKEN → CLAUDE_CODE_OAUTH_TOKEN 순이다. 즉 길이 두 갈래다.

갈래 A — API 키 (권장)

Anthropic Console 에서 키를 발급받아 ~/.hermes/.env 에 넣는다.

ANTHROPIC_API_KEY=sk-ant-...

한도가 분리되고, 용도 문제가 없고, 사용량이 그대로 청구서로 보인다. 상주 에이전트에는 이쪽이 맞다 — 이유는 아래 §5.

갈래 B — Claude 구독 토큰

Claude Code 를 쓰고 있다면 구독으로 장기 토큰을 뽑을 수 있다.

claude setup-token

나온 값을 .env 에 CLAUDE_CODE_OAUTH_TOKEN 으로 넣으면 Hermes 가 집어서 쓴다. Hermes 는 이 변수를 샌드박스 환경변수 차단 목록에서도 명시적으로 예외 처리해 뒀을 만큼 의도적으로 지원한다.

⚠️ 다만 이건 용도 밖이다. claude setup-token 이 발급하는 건 헤드리스·CI 환경에서 Claude Code 를 돌리라고 있는 토큰이다. 다른 에이전트를 그걸로 구동하는 건 원래 의도가 아니며, 구독 약관 판단은 각자의 몫이다. "기술적으로 된다"와 "허용된다"는 다른 문장이다.

전환

손으로 config.yaml 을 고쳐도 되지만 CLI 가 있다.

hermes model

그리고 이건 꼭 같이 걸어라:

hermes fallback

주 모델이 실패했을 때 떨어질 곳을 정한다. 한도에 닿거나 장애가 나도 에이전트가 죽지 않는다. 상주형은 죽는 순간이 곧 신뢰를 잃는 순간이다.

4. Discord 에 붙이기

채널은 .env 세 줄로 결정된다.

DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=<디스코드 유저 ID>
DISCORD_HOME_CHANNEL=<채널 ID>

토큰은 Discord Developer Portal 에서 앱을 만들어 받는다. ID 두 개는 Discord 설정에서 개발자 모드를 켜면 우클릭으로 복사할 수 있다.

DISCORD_ALLOWED_USERS 를 비워 두지 마라.** 이게 유일한 1차 방어선이다. 상주 에이전트는 채널에 있는 누구나 말을 걸 수 있는 상태가 기본값인데, allowlist 가 그걸 막는다. 처음엔 본인 ID 하나만 넣는 걸 권한다.

기동하면 게이트웨이가 뜨고 채널을 인덱싱한다. 확인:

hermes status

~/.hermes/channel_directory.json 에 채널 목록이 잡혀 있으면 연결된 것이다.

5. 지불하는 값 — 세우기 전에 알 것

여기가 이 글에서 제일 중요한 부분이다. 상주형은 공짜가 아니다.

① 비용에 상한이 없다. 배치로 돌리면 "하루 N회"라는 천장이 있지만, 상주는 없다. 감시 작업까지 붙이면 조용히 샌다. 계측을 먼저 붙이고 기능을 붙여라 — 하루 토큰/요청 수가 보이는 곳 하나면 된다. 구독 토큰(갈래 B)으로 갈 경우엔 더 직접적이다: 에이전트가 쓰는 만큼 본인이 Claude 를 쓸 몫이 줄어든다. 같은 한도를 나눠 쓰기 때문이다.

② 토큰이 평문으로 남는다. ~/.hermes/.env 는 암호화되지 않는다. 이 파일이 백업·동기화·git 에 딸려 들어가지 않는지 확인하라.

③ 읽기 경계를 먼저 정하라. 상주 에이전트에게 파일 접근을 주는 순간, 그 에이전트에 말을 걸 수 있는 사람은 그 파일들에 간접 접근하는 것과 같다. 비밀키가 있는 경로는 명시적으로 차단하고, 차단이 문서가 아니라 실제로 동작하는지 한 번 확인하라. 우리는 이걸 별도 체크 항목으로 잡았다 — "막았다고 적었다"와 "막혔다"는 다르다.

④ 틀린 답도 로그로 남는다. 채널에 남은 확률적 응답은 나중에 사실처럼 읽힌다. 사람이 보는 채널이라면 더 그렇다.

6. 점검 명령 몇 개

hermes status      상태
hermes doctor      설치 진단
hermes model       모델·프로바이더 선택
hermes fallback    대체 프로바이더
hermes auth        인증 상태
hermes gateway     상주 프로세스 제어
hermes cron        일정
hermes memory      기억 확인

막히면 hermes doctor 가 대체로 먼저 답을 준다.

마치며

상주 에이전트를 세우는 기술적 난이도는 낮다 — 설치 한 줄, 환경변수 몇 개, 명령 두 개다. 어려운 건 경계를 정하는 쪽이다. 무엇을 읽게 할지, 누가 말을 걸 수 있게 할지, 얼마까지 쓰게 할지.

우리 순서는 이랬다: 경계 먼저, 기능 나중. 토큰과 채널을 세우기 전에 allowlist 와 deny 목록을 먼저 정했고, 캡처 기능을 붙이기 전에 계측을 붙였다. 재미있는 순서는 아니지만, 되돌리기 어려운 쪽을 먼저 잠그는 게 결국 빠르다.

이 글은 실제 구축 기록에서 뽑았다. 더 깊은 이야기나 막힌 지점은 커뮤니티에서 이어서 나누자.