라즈베리파이5 AI 머신 세팅 3: Hermes Agent 설치와 Discord Gateway 연결

2편의 마지막에는 라즈베리파이5가 다음 상태까지 준비됐습니다.

• NVMe SSD의 Ubuntu Server 24.04에서 부팅됩니다.
• 윈도우에서 Tailscale과 SSH 키로 원격 접속할 수 있습니다.
• OpenSSH 비밀번호 로그인과 root 로그인을 막았습니다.
• UFW는 Tailscale을 거친 SSH만 허용합니다.
• Node.js와 Codex CLI를 설치하고 ChatGPT 계정으로 로그인했습니다.

즉, SSH 터미널을 열면 AI 도구를 사용할 수 있는 원격 머신은 완성됐습니다. 이번 3편에서는 한 단계 더 나아가 Hermes Agent를 상시 Gateway로 실행하고 Discord에서 호출하는 구조를 만듭니다.

아직 2편까지 진행하지 않았다면 아래 글부터 완료하세요.

라즈베리파이5 AI 머신 세팅 · 2편 SSH·Tailscale 보안과 Codex 설치 Windows 원격 접속부터 SSH 잠금, UFW, Codex 로그인까지 먼저 준비합니다. 2편 먼저 보기 →

이번 3편에서 진행할 것

진행 순서는 다음과 같습니다.

1. 공식 설치 스크립트로 Hermes Agent를 설치합니다.
2. Blank Slate에서 OpenAI Codex OAuth와 기본 모델을 설정합니다.
3. 최소 설치가 끝나면 Gateway 사용자 서비스를 설치합니다.
4. Discord Developer Portal에서 Application과 Bot을 만듭니다.
5. Bot 권한과 Gateway Intents를 설정하고 서버에 초대합니다.
6. Bot 토큰과 허용 사용자 ID를 Hermes Gateway에 등록합니다.
7. Gateway를 재시작하고 Discord에서 실제 응답을 확인합니다.

완료하면 매번 SSH로 접속해 Hermes를 직접 실행하지 않아도 Discord에서 라즈베리파이의 Hermes Agent와 대화할 수 있습니다.

보안 주의: Discord Bot 토큰은 계정 비밀번호와 같은 비밀값입니다. 글, 캡처, Git 저장소, 채팅에 노출하지 마세요. 노출됐다면 가리는 것만으로 끝내지 말고 Developer Portal에서 토큰을 즉시 재발급해야 합니다.

시작 전 준비 사항

• 2편까지 완료한 Raspberry Pi 5
• Ubuntu Server 24.04 LTS 64-bit(arm64)
• 라즈베리파이에 접속할 SSH 터미널
• OpenAI Codex OAuth에 사용할 ChatGPT 계정
• Discord 계정과 Bot을 초대할 서버
• Discord Developer Portal을 열 윈도우 PC의 브라우저

설치 전 현재 아키텍처와 운영체제를 확인하려면 다음 명령을 실행합니다.

uname -m
cat /etc/os-release

이번 환경의 아키텍처는 aarch64이며 Ubuntu Server 24.04 LTS 계열입니다. 세부 유지보수 버전과 출력 줄은 설치 시점에 따라 달라질 수 있습니다.

1. 공식 스크립트로 Hermes Agent 설치하기

라즈베리파이 SSH 터미널에서 Hermes 공식 CLI 설치 스크립트를 실행합니다.

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

공식 문서 기준으로 이 스크립트는 Hermes 실행 환경과 필요한 의존성, 전역 hermes 명령을 준비합니다. 설치가 끝나면 설정 마법사가 자동으로 시작되며, 이번 환경에서 바로 이어진 실제 다음 화면은 아래 Blank Slate 선택 화면입니다.

설치 스크립트를 실행하기 전에 URL이 Hermes 공식 도메인인지 확인하세요. curl | bash 형태는 내려받은 내용을 바로 실행하므로, 비슷하게 생긴 비공식 주소를 복사해 실행하면 안 됩니다.

이 글에서는 기존 설정을 가져오지 않고 OpenAI Codex OAuth를 직접 구성할 것이므로 Blank Slate를 선택합니다. 이 화면에서 별도의 명령을 실행하지 않고 선택을 마치면 다음 모델 제공자 화면으로 이어집니다.

2. Blank Slate에서 OpenAI Codex OAuth 설정하기

OpenAI 제공자 선택

모델 제공자 목록에서 OpenAI를 선택합니다.

이어서 OpenAI 인증 방식 중 OpenAI Codex를 선택합니다.

OpenAI API 키를 직접 입력하는 방식과 달리 OpenAI Codex 제공자는 브라우저의 기기 인증으로 ChatGPT 계정을 연결합니다. Hermes 공식 문서에 따르면 인증 정보는 Hermes의 인증 저장소에 보관되며, 기존 Codex CLI 인증이 있으면 가져올 수도 있습니다.

기존 Codex 인증을 가져올지 선택

기존 Codex CLI 자격 증명이 감지되면 가져올지 묻습니다. 캡처에서는 새로 인증 흐름을 확인하기 위해 n을 선택했습니다.

이미 정상 로그인된 Codex CLI 인증을 재사용하려면 안내에 따라 가져올 수 있습니다. 새 계정이나 별도 Hermes 인증을 사용할 때는 새 기기 인증으로 진행합니다.

브라우저에서 기기 코드 인증

터미널에 인증 주소와 일회용 코드가 표시됩니다.

1. 윈도우 브라우저에서 터미널에 표시된 공식 주소를 엽니다.
2. 사용할 ChatGPT 계정으로 로그인합니다.
3. 터미널의 일회용 코드를 입력합니다.
4. 인증 완료 메시지가 나올 때까지 SSH 터미널을 유지합니다.

일회용 코드는 짧은 시간만 유효해도 공개하면 안 됩니다. 게시 이미지에서는 실제 코드를 다시 가렸습니다.

기본 모델 선택

인증이 끝나면 기본으로 사용할 모델을 고릅니다. 모델 목록은 계정과 Hermes 버전에 따라 달라질 수 있으므로 화면의 현재 목록에서 사용할 모델을 선택하세요.

캡처에서는 당시 목록에 표시된 모델을 선택했습니다. 글의 화면과 독자의 목록이 다르더라도 오류라고 단정하지 말고, 사용 가능한 모델명과 제공자를 확인하면 됩니다.

3. 로컬 터미널과 최소 설치로 마무리하기

터미널 백엔드는 local 유지

Hermes가 라즈베리파이 자신의 파일과 명령을 다루게 할 것이므로 터미널 백엔드는 기본값인 local을 유지합니다.

• local: Hermes가 실행되는 라즈베리파이에서 명령 실행
• 원격·컨테이너 백엔드: 별도의 실행 환경을 연결할 때 사용

이번 목적은 Discord 요청을 라즈베리파이에서 처리하는 것이므로 다른 백엔드를 추가하지 않습니다.

최소 설치 완료

추가 도구나 연동을 한꺼번에 설정하지 않고 최소 구성으로 마칩니다.

완료 화면에는 선택한 제공자와 모델, 설정 파일 경로, 추가로 실행할 수 있는 명령이 표시됩니다.

설치 과정에서 hermes 실행 경로가 셸 설정 파일에 추가됩니다. 현재 열려 있는 SSH 터미널에 새 PATH 설정을 바로 반영하려면 다음 명령을 먼저 실행합니다.

source ~/.bashrc

이 명령을 실행하지 않으면 설치 직후 현재 터미널에서 hermes: command not found가 표시될 수 있습니다. SSH를 새로 접속하면 .bashrc가 다시 읽히지만, 같은 터미널에서 계속 진행할 때는 위 명령으로 반영하는 것이 빠릅니다.

이제 버전과 기본 상태를 확인합니다.

hermes --version
hermes doctor

hermes --version에는 설치된 버전이, hermes doctor에는 현재 환경과 설정 진단 결과가 표시되어야 합니다. 버전 번호와 진단 항목은 업데이트에 따라 달라질 수 있으므로 특정 줄 수보다 오류가 남아 있는지 확인합니다.

선택 안내: Nous Portal로 설정할 때

hermes setup --portal은 위 curl 설치 후 자동으로 나타나는 Blank Slate 화면의 다음 단계가 아니라 별도의 설정 경로입니다. 지금처럼 Blank Slate에서 OpenAI Codex OAuth를 설정한 독자는 실행하지 않고 다음 Gateway 단계로 넘어가세요. 모델과 웹검색·이미지 생성·TTS·클라우드 브라우저를 Nous Portal OAuth로 함께 연결하려는 경우에만 Hermes 설치 후 아래 명령으로 Portal 설정을 시작합니다. 이 명령을 사용하면 기본 모델 제공자가 Nous로 설정됩니다.

hermes setup --portal

4. Hermes Gateway 사용자 서비스 설치하기

최소 설치 직후에는 Gateway가 아직 서비스로 설치되지 않은 상태일 수 있습니다. 다음 명령을 실행합니다.

hermes gateway install

Linux에서는 현재 사용자 계정의 systemd 사용자 서비스로 Gateway를 설치합니다. 설치 후 상태를 확인합니다.

hermes gateway status

SSH 연결을 끊은 뒤에도 사용자 서비스가 계속 실행돼야 하는 환경이라면 로그인 세션 종료 정책에 따라 linger 설정이 필요할 수 있습니다.

sudo loginctl enable-linger "$USER"

enable-linger는 해당 사용자의 사용자 서비스가 로그아웃 뒤에도 실행되도록 합니다. 무조건 실행하기보다 hermes gateway status와 재접속 테스트에서 Gateway가 종료되는 환경일 때 적용하세요.

5. Discord Application과 Bot 만들기

이제 브라우저에서 Discord Developer Portal을 엽니다.

기존 Application 목록 오른쪽 위의 New Application을 선택합니다.

Application 이름을 입력하고 Discord Developer Terms에 동의한 뒤 Create를 누릅니다.

이름은 서버에서 알아보기 쉬운 것으로 정하면 됩니다. Application 이름과 서버에 표시되는 Bot 이름은 나중에 수정할 수 있습니다.

6. Discord Bot 권한과 초대 URL 설정하기

Installation 또는 OAuth2에서 설치 권한 지정

Discord Developer Portal의 Installation 또는 OAuth2 → URL Generator에서 서버 설치에 사용할 범위와 권한을 정합니다. 먼저 Scopes에서 bot과 applications.commands를 선택합니다.

이어서 Installation 화면의 기본 설치 설정에서 Bot에 필요한 권한을 선택하고 저장합니다.

기본 대화와 파일 응답에 필요한 대표 권한은 다음과 같습니다.

• View Channels
• Send Messages
• Embed Links
• Attach Files
• Read Message History
• Use Application Commands

서버 전체를 관리하는 Administrator 권한은 선택하지 않습니다. Bot이 사용할 채널을 제한하고 싶다면 Discord 서버의 역할·채널 권한에서도 범위를 줄일 수 있습니다.

OAuth2 URL Generator 사용

Discord UI 버전에 따라 OAuth2 → URL Generator에서 초대 링크를 만들 수도 있습니다. Scopes에서 bot과 applications.commands를 선택하고, 아래 Bot Permissions에서 앞에서 정한 최소 권한을 선택하면 초대 URL이 생성됩니다.

생성된 URL을 브라우저에서 열고 Bot을 추가할 서버를 선택한 뒤 계속하기를 누릅니다.

서버를 선택할 권한이 없다면 해당 서버의 관리자에게 초대를 요청해야 합니다.

이제 왼쪽 메뉴의 Bot으로 이동해 Gateway Intents와 토큰을 설정합니다.

7. Gateway Intents와 Bot 토큰 준비하기

Privileged Gateway Intents 확인

Developer Portal의 Bot → Privileged Gateway Intents로 이동합니다.

캡처에서는 Presence, Server Members, Message Content 세 가지를 모두 켰습니다. 다만 기본 텍스트 Bot에서 핵심은 Message Content Intent입니다.

• Message Content Intent: 채널의 일반 메시지 내용을 읽기 위해 필요
• Server Members Intent: 허용 목록에서 사용자명을 숫자 ID로 해석해야 할 때 필요할 수 있음
• Presence Intent: 사용자 온라인 상태를 활용할 때 사용

이번 글처럼 허용 목록에 Discord의 숫자 사용자 ID를 직접 넣는다면 Server Members Intent를 끌 수 있습니다. Presence Intent도 기본 대화에는 필수가 아닙니다. 최소 권한으로 운영하려면 실제 사용하는 기능만 켜세요.

Bot 토큰 발급

같은 Bot 화면의 Token 영역에서 Reset Token 또는 토큰 생성 버튼을 눌러 새 토큰을 발급하고 복사합니다.

토큰은 다시 확인할 수 없을 수 있으므로 안전한 암호 관리 도구에 임시 보관합니다. 캡처, 메모장 공유 파일, Git 저장소에는 넣지 않습니다.

토큰이 노출되면 기존 토큰을 계속 사용하지 마세요. Developer Portal에서 즉시 Reset Token을 실행하고 Hermes Gateway 설정도 새 토큰으로 바꿔야 합니다.

8. Discord 사용자 ID 확인하기

Bot을 아무나 호출하지 못하도록 Hermes Gateway에 허용할 Discord 사용자 ID를 등록합니다. Discord에서 먼저 사용자 설정 → 고급 → 개발자 모드를 켭니다. 그다음 자신의 프로필을 마우스 오른쪽 버튼으로 눌러 사용자 ID 복사를 선택합니다.

숫자로 된 사용자 ID는 Bot 토큰과 달리 인증 비밀값은 아니지만, 계정 식별 정보이므로 공개 캡처에서는 가리는 편이 좋습니다.

9. hermes gateway setup에서 Discord 연결하기

라즈베리파이 SSH 터미널에서 설정 마법사를 실행합니다.

hermes gateway setup

플랫폼 목록에서 Discord를 선택합니다.

Developer Portal에서 복사한 Bot 토큰을 붙여 넣습니다. 화면에는 별표처럼 가려져 표시됩니다.

이어서 허용할 Discord 사용자 ID를 입력합니다. 여러 사용자를 허용할 때는 화면 안내 형식에 맞춰 쉼표로 구분합니다.

허용 목록을 비워 모든 사용자에게 열어 두는 방식은 개인 서버 테스트에서도 권장하지 않습니다. 먼저 자신의 숫자 사용자 ID만 등록하고 필요한 경우 한 명씩 추가하세요.

설정 항목을 모두 확인하면 완료 화면이 표시됩니다.

마지막에 Gateway를 시작하거나 재시작할지 묻는다면 Yes를 선택합니다. Home channel ID는 특정 채널을 기본 전달 대상으로 고정할 때 사용하며, 이번 캡처에서는 비워 두고 Enter를 눌렀습니다.

설정 후 상태를 다시 확인합니다.

hermes gateway status

설정을 수정했는데 반영되지 않으면 다음 명령으로 재시작합니다.

hermes gateway restart

10. Discord에서 Hermes Bot 테스트하기

Discord 서버의 멤버 목록에서 Bot이 온라인 상태인지 확인합니다.

Bot을 허용한 채널에서 멘션과 함께 간단한 메시지를 보냅니다.

@봇이름 안녕하세요. 현재 실행 중인 시스템을 한 문장으로 알려줘.

Bot이 메시지를 읽고 응답하면 다음 연결이 모두 동작한 것입니다.

Discord 채널
→ Discord Bot
→ Hermes Gateway 서비스
→ OpenAI Codex 모델
→ Discord 채널 응답

처음에는 파일 삭제나 시스템 변경을 요청하기보다 인사, 현재 경로 확인, 버전 확인처럼 읽기 위주의 요청으로 테스트하세요.

Bot이 응답하지 않을 때 확인 순서

1. Gateway 실행 상태

hermes gateway status

실행 중이 아니라면 시작하거나 재시작합니다.

hermes gateway start
hermes gateway restart

2. Discord Message Content Intent

Developer Portal의 Bot 화면에서 Message Content Intent가 켜져 있는지 확인합니다. 바꾼 뒤에는 Gateway를 재시작합니다.

3. 서버와 채널 권한

Bot 역할에 다음 권한이 있는지 확인합니다.

• 채널 보기
• 메시지 보내기
• 메시지 기록 읽기
• 필요한 경우 링크 삽입과 파일 첨부

특정 채널에서만 안 된다면 서버 전체 권한보다 그 채널의 역할 덮어쓰기를 먼저 확인합니다.

4. 허용 사용자 ID

hermes gateway setup에서 등록한 숫자 ID가 실제 메시지를 보내는 Discord 계정과 같은지 확인합니다. 사용자명이나 표시 이름은 바뀔 수 있으므로 숫자 ID가 더 안정적입니다.

5. Bot 토큰

토큰을 재발급했다면 예전 토큰은 즉시 무효가 됩니다. 새 토큰을 Hermes 설정에 다시 입력하고 Gateway를 재시작해야 합니다.

AI에게 맡기더라도 사람이 확인할 항목

Discord에서 라즈베리파이에 명령을 보낼 수 있게 됐다는 것은 편리하지만, 메시지 한 줄이 실제 파일 수정과 명령 실행으로 이어질 수 있다는 뜻이기도 합니다.

AI에게 작업을 요청할 때는 다음처럼 검증 조건을 함께 적는 편이 안전합니다.

현재 상태를 먼저 확인하고, 변경할 파일과 명령을 보여줘.
삭제·덮어쓰기·권한 변경은 실행하지 말고 승인을 기다려.
작업 후에는 상태 확인 명령과 실제 결과를 알려줘.

기본적인 24시간 Hermes Gateway 서버 준비 완료

이번 3편에서는 라즈베리파이5 Ubuntu Server arm64에 Hermes Agent를 설치하고, Blank Slate에서 OpenAI Codex OAuth와 기본 모델을 연결했습니다. 최소 설치를 끝낸 뒤 Gateway를 사용자 서비스로 설치하고 Discord Application과 Bot을 만들었습니다.

Discord에는 필요한 메시지 권한만 부여하고 Message Content Intent를 확인했습니다. Bot 토큰과 숫자 사용자 ID를 hermes gateway setup에 등록한 뒤 Gateway를 재시작했고, Discord에서 실제 첫 응답까지 확인했습니다.

이제 Hermes 최소 설치, 모델 연결, Gateway 연결, Discord 호출 테스트가 모두 끝났습니다. 라즈베리파이의 전원과 네트워크가 유지되고 Gateway 사용자 서비스가 실행되는 동안에는 SSH 터미널을 매번 열지 않아도 Discord를 통해 Hermes를 호출할 수 있습니다. 이 단계로 Gateway를 통한 기본적인 24시간 서버 사용 준비가 완료됐습니다.

다음 글: Hermes Plugins·Tools·Skills 확장 설정

현재 상태만으로도 기본적인 Discord Gateway 사용은 가능합니다. 4편에서는 여기서 기능을 확장하기 위해 보안·디스크 정리 Plugin, 웹 검색·이미지 생성 Tool, 개발 작업용 Skill을 설정하는 방법을 진행합니다.

• security-guidance, disk-cleanup 활성화
• Tavily·Brave Search와 OpenAI Codex OAuth 이미지 제공자 설정
• 개발용 공식 Skills 세 개 설치
• 설정 상태 확인과 Gateway 재시작

라즈베리파이5 AI 머신 세팅 · 4편 Hermes Plugins·Tools·Skills 확장 설정 보안·디스크 정리 Plugin부터 검색·이미지 Tool, 개발용 Skill과 Gateway 반영까지 진행합니다. 4편 이어서 보기 →

공식 자료

• Hermes Agent 설치 공식 문서
• Hermes Agent 모델 제공자 공식 문서
• Hermes Agent Messaging Gateway 공식 문서
• Hermes Agent Discord 공식 문서
• Hermes Agent CLI 명령 공식 문서
• Discord Developer Portal
• Discord Gateway Intents 공식 문서

정리

핵심 흐름은 모델 인증 → Gateway 서비스 설치 → Discord Bot 최소 권한 설정 → 토큰과 허용 사용자 등록 → 실제 메시지 검증입니다.

설치 명령 한 줄보다 중요한 것은 연결 경계를 확인하는 일입니다. OpenAI Codex OAuth는 모델을 연결하고, Hermes Gateway는 상시 메시징 프로세스를 실행하며, Discord Bot 토큰과 권한은 외부 채널의 접근 범위를 결정합니다. 이 세 부분을 분리해서 이해하면 Bot이 응답하지 않을 때도 원인을 좁히기 쉽습니다.

마지막으로 Bot이 온라인이라는 표시만 보지 말고, 허용한 계정으로 실제 메시지를 보내고 응답까지 돌아오는지 확인하세요. 그 왕복이 성공해야 라즈베리파이5 AI 머신 세팅 3편이 완료된 것입니다.