이메일 설정

Hermes는 표준 IMAP 및 SMTP 프로토콜을 사용하여 이메일을 수신하고 회신할 수 있습니다. 에이전트의 이메일 주소로 이메일을 보내면 스레드 내에서 회신합니다 — 특별한 클라이언트나 봇 API가 필요하지 않습니다. Gmail, Outlook, Yahoo, Fastmail 또는 IMAP/SMTP를 지원하는 모든 제공업체와 함께 작동합니다.

No External Dependencies

이메일 어댑터는 Python의 내장 imaplib, smtplib, email 모듈을 사용합니다. 추가 패키지나 외부 서비스가 필요하지 않습니다.

전제 조건

Hermes 에이전트를 위한 전용 이메일 계정 (개인 이메일 사용 금지)
이메일 계정에서 IMAP 활성화
앱 비밀번호 (Gmail이나 2단계 인증이 있는 다른 제공업체를 사용하는 경우)

지메일 설정

Google 계정에서 2단계 인증을 활성화하세요
앱 비밀번호로 이동
새 앱 비밀번호 만들기 ("메일" 또는 "기타" 선택)
16자리 비밀번호를 복사하세요 — 일반 비밀번호 대신 이것을 사용하게 됩니다

아웃룩 / 마이크로소프트 365

보안 설정으로 이동
가 아직 활성화되어 있지 않다면 활성화하세요
"추가 보안 옵션"에서 앱 비밀번호를 생성하세요
IMAP 호스트: outlook.office365.com, SMTP 호스트: smtp.office365.com

기타 제공자

대부분의 이메일 제공업체는 IMAP/SMTP를 지원합니다. 제공업체의 문서를 확인하세요:

IMAP 호스트와 포트 (보통 SSL 사용 시 포트 993)
SMTP 호스트와 포트(보통 STARTTLS를 사용하는 포트 587)
앱 비밀번호가 필요한지 여부

1단계: Hermes 구성

가장 쉬운 방법:

hermes gateway setup

플랫폼 메뉴에서 이메일을 선택하세요. 마법사가 이메일 주소, 비밀번호, IMAP/SMTP 호스트 및 허용된 발신자를 요청합니다.

수동 설정

~/.hermes/.env에 추가:

# Required
EMAIL_ADDRESS=hermes@gmail.com
EMAIL_PASSWORD=abcd efgh ijkl mnop    # App password (not your regular password)
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com

# Security (recommended)
EMAIL_ALLOWED_USERS=your@email.com,colleague@work.com

# Optional
EMAIL_IMAP_PORT=993                    # Default: 993 (IMAP SSL)
EMAIL_SMTP_PORT=587                    # Default: 587 (SMTP STARTTLS)
EMAIL_POLL_INTERVAL=15                 # Seconds between inbox checks (default: 15)
EMAIL_HOME_ADDRESS=your@email.com      # Default delivery target for cron jobs

2단계: 게이트웨이 시작

hermes gateway              # Run in foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

시작 시, 어댑터:

IMAP 및 SMTP 연결을 테스트합니다
기존 받은편지함 메시지를 모두 '읽음'으로 표시합니다 (새 이메일만 처리됨)
새 메시지 수신을 확인하기 시작합니다

작동 원리

메시지 수신

어댑터는 구성 가능한 간격(기본값: 15초)으로 IMAP 받은편지함에서 읽지 않은 메시지를 확인합니다. 새로운 이메일마다:

제목 줄은 문맥으로 포함됩니다(예: [Subject: Deploy to production])
회신 이메일 (Re:로 시작하는 제목)은 제목 접두사를 생략하세요 — 스레드 맥락은 이미 설정되어 있습니다
첨부 파일은 로컬에 캐시됩니다:
- 이미지 (JPEG, PNG, GIF, WebP) → 비전 도구에서 사용 가능
- 문서(PDF, ZIP 등) → 파일 접근 가능
HTML 전용 이메일은 일반 텍스트 추출을 위해 태그가 제거됩니다
자기 메시지는 답장 루프를 방지하기 위해 필터링됩니다
자동화/회신 금지 발신자는 조용히 무시됩니다 — noreply@, mailer-daemon@, bounce@, no-reply@, 그리고 Auto-Submitted, Precedence: bulk, 또는 List-Unsubscribe 헤더가 있는 이메일

응답 보내기

회신은 적절한 이메일 스레딩과 함께 SMTP를 통해 전송됩니다:

In-Reply-To와 References 헤더는 스레드를 유지합니다
제목 줄 Re: 접두사 유지 (이중 Re: Re: 없음)
Message-ID 에이전트의 도메인으로 생성됨
응답은 일반 텍스트(UTF-8)로 전송됩니다

파일 첨부

에이전트는 답장에 파일 첨부를 보낼 수 있습니다. 응답에 MEDIA:/path/to/file를 포함하면 파일이 발신 이메일에 첨부됩니다.

첨부 파일 건너뛰기

모든 수신 첨부 파일을 무시하려면(멀웨어 보호 또는 대역폭 절약을 위해), config.yaml에 다음을 추가하세요:

platforms:
  email:
    skip_attachments: true

활성화되면 페이로드 디코딩 전에 첨부 파일과 인라인 부분이 건너뛰어집니다. 이메일 본문 텍스트는 여전히 정상적으로 처리됩니다.

접근 제어

이메일 접근은 다른 모든 Hermes 플랫폼과 동일한 패턴을 따릅니다:

EMAIL_ALLOWED_USERS 설정됨 → 해당 주소에서 온 이메일만 처리됩니다
허용 목록 설정 없음 → 알 수 없는 발신자는 페어링 코드를 받습니다
EMAIL_ALLOW_ALL_USERS=true → 모든 발신자가 허용됨 (주의해서 사용)

경고

항상 EMAIL_ALLOWED_USERS를 구성하세요. 이를 설정하지 않으면 에이전트의 이메일 주소를 아는 누구나 명령을 보낼 수 있습니다. 에이전트는 기본적으로 터미널 접근 권한을 가지고 있습니다.

문제 해결

문제	해결책
시작 시 'IMAP 연결 실패'	`EMAIL_IMAP_HOST`와 `EMAIL_IMAP_PORT`을 확인하세요. 계정에서 IMAP이 활성화되어 있는지 확인하세요. Gmail의 경우 설정 → 전달 및 POP/IMAP에서 활성화하세요.
"SMTP 연결 실패" 시작 시	`EMAIL_SMTP_HOST`와 `EMAIL_SMTP_PORT`을 확인하세요. 비밀번호가 올바른지 확인하세요 (Gmail의 경우 앱 비밀번호 사용).
메시지를 받지 못함	발신자의 이메일을 포함하고 있는지 `EMAIL_ALLOWED_USERS` 을 확인하세요. 일부 제공업체는 자동 응답을 스팸으로 표시하므로 스팸 폴더도 확인하세요.
인증 실패	Gmail의 경우 일반 비밀번호가 아니라 앱 비밀번호를 사용해야 합니다. 먼저 2단계 인증이 활성화되어 있는지 확인하세요.
중복 답변	게이트웨이 인스턴스가 하나만 실행되고 있는지 확인하세요. `hermes gateway status`를 확인하세요.
느린 응답	기본 폴링 간격은 15초입니다. 더 빠른 응답을 위해 `EMAIL_POLL_INTERVAL=5`로 줄이세요(하지만 IMAP 연결이 더 많아집니다).
답글이 스레드되지 않음	어댑터는 In-Reply-To 헤더를 사용합니다. 일부 이메일 클라이언트(특히 웹 기반)는 자동화된 메시지와 올바르게 스레딩되지 않을 수 있습니다.

보안

{#security}

전용 이메일 계정을 사용하세요. 개인 이메일을 사용하지 마세요 — 에이전트는 비밀번호를 .env에 저장하며 IMAP을 통해 전체 받은편지함에 접근할 수 있습니다.

주요 비밀번호 대신 앱 비밀번호를 사용하세요 (2단계 인증이 설정된 Gmail에 필요)
EMAIL_ALLOWED_USERS을 설정하여 에이전트와 상호작용할 수 있는 사람을 제한하세요
비밀번호는 ~/.hermes/.env에 저장됩니다 — 이 파일(chmod 600)을 보호하세요
IMAP는 기본적으로 SSL(포트 993)을 사용하고, SMTP는 STARTTLS(포트 587)를 사용합니다 — 연결은 암호화됩니다

환경 변수 참조

변수	필수	기본값	설명
`EMAIL_ADDRESS`	예	—	에이전트의 이메일 주소
`EMAIL_PASSWORD`	예	—	이메일 비밀번호 또는 앱 비밀번호
`EMAIL_IMAP_HOST`	예	—	IMAP 서버 호스트(예: `imap.gmail.com`)
`EMAIL_SMTP_HOST`	예	—	SMTP 서버 호스트 (예: `smtp.gmail.com`)
`EMAIL_IMAP_PORT`	No	`993`	IMAP 서버 포트
`EMAIL_SMTP_PORT`	No	`587`	SMTP 서버 포트
`EMAIL_POLL_INTERVAL`	No	`15`	받은 편지함 확인 간격(초)
`EMAIL_ALLOWED_USERS`	No	—	쉼표로 구분된 허용 발신자 주소
`EMAIL_HOME_ADDRESS`	No	—	크론 작업의 기본 배달 대상
`EMAIL_ALLOW_ALL_USERS`	No	`false`	모든 발신자 허용 (권장되지 않음)

전제 조건​

지메일 설정​

아웃룩 / 마이크로소프트 365​

기타 제공자​

1단계: Hermes 구성​

수동 설정​

2단계: 게이트웨이 시작​

작동 원리​

메시지 수신​

응답 보내기​

파일 첨부​

첨부 파일 건너뛰기​

접근 제어​

문제 해결​

보안​

환경 변수 참조​