라즈베리파이5 AI 머신 세팅 4: Hermes Plugins·Tools·Skills 확장 설정

3편에서는 라즈베리파이5 Ubuntu Server에 Hermes Agent를 설치하고 OpenAI Codex OAuth 모델을 연결했습니다. 이어서 Gateway를 사용자 서비스로 설치하고 Discord Bot과 연결해 실제 메시지 응답까지 확인했습니다.

즉, 지금 시작점은 Discord에서 Hermes와 기본 대화를 나눌 수 있는 최소 구성입니다. 아직 3편을 완료하지 않았다면 아래 글부터 진행하세요.

라즈베리파이5 AI 머신 세팅 · 3편 Hermes Agent 설치와 Discord Gateway 연결 OpenAI Codex OAuth부터 Discord Bot 생성, Gateway 등록과 실제 응답까지 먼저 진행합니다. 3편 먼저 보기 →

이번 4편에서 진행할 것

이번에는 새 프로그램 하나를 설치하는 것이 아니라 Hermes가 사용할 수 있는 기능 범위를 정리합니다.

1. API 키가 필요 없는 일반 플러그인 두 개를 활성화합니다.
2. hermes tools에서 모든 플랫폼의 공통 도구를 선택합니다.
3. Web Search 제공자로 Tavily 또는 Brave Search를 설정합니다.
4. Image Generation 제공자로 OpenAI Codex OAuth를 연결합니다.
5. 기본 Skills가 충분한 이유를 확인하고 개발용 Skills 세 개만 추가합니다.
6. 플러그인·도구 상태를 확인한 뒤 Gateway를 재시작합니다.

완료하면 Discord에서 대화만 하던 Hermes가 웹 검색, 이미지 생성, 개발 절차 같은 기능을 실제 작업에 활용할 준비를 갖춥니다.

중요: 플러그인과 Skill은 수가 많다고 성능이 무조건 좋아지지 않습니다. 사용하지 않는 기능까지 한꺼번에 켜면 에이전트가 선택해야 할 도구가 늘고, 외부 서비스의 권한·비용·데이터 전송 범위도 커질 수 있습니다. 이번 글에서는 실제로 사용할 항목만 추가합니다.

Plugins, Tools, Skills 차이부터 이해하기

이 세 용어는 비슷해 보이지만 역할이 다릅니다.

구분	역할	이번 글의 예시
Plugins	Hermes 자체 기능과 동작 확장	security-guidance, disk-cleanup
Tools	에이전트가 실제로 호출하는 실행 기능	Web Search, Image Generation, Terminal, File
Skills	특정 작업을 수행하는 절차와 판단 기준	subagent-driven-development, code-wiki

쉽게 말하면 Plugin은 Hermes에 기능을 붙이고, Tool은 그 기능을 실행할 손발을 제공하며, Skill은 어떤 순서와 기준으로 일할지 알려주는 작업 설명서에 가깝습니다.

1. API 키가 필요 없는 일반 플러그인 활성화

먼저 설치된 플러그인 목록을 확인할 수 있습니다.

hermes plugins list

목록이 길다면 글 마지막의 --plain 명령으로 간단한 텍스트 상태만 확인하는 편이 읽기 쉽습니다.

이번에는 별도의 외부 API 키가 필요 없는 두 플러그인을 활성화합니다.

hermes plugins enable security-guidance
hermes plugins enable disk-cleanup

• security-guidance: pickle.load, eval(, os.system, verify=False처럼 알려진 위험 패턴이 새 파일 내용에서 감지되면 파일 쓰기 Tool 결과에 경고를 덧붙입니다. 쓰기를 막지는 않으므로 경고를 확인하고 코드를 수정해야 합니다.
• disk-cleanup: Hermes 세션에서 만들어진 테스트 스크립트, 임시 출력, cron 로그 같은 일시적 파일을 플러그인 hook으로 추적하고 정리합니다. 별도의 에이전트 명령 없이 동작합니다. 이번 라즈베리파이5에서는 이런 임시 파일이 계속 쌓이는 것을 줄여 제한된 디스크 용량을 효율적으로 사용하기 위해 활성화했습니다.

disk-cleanup은 일반적인 디스크 분석·수동 삭제 Tool이 아니라 Hermes가 만든 임시 파일의 수명 주기를 관리하는 플러그인입니다. 프로젝트에 남겨야 할 결과물을 임시 경로에만 저장하지 말고, 필요한 파일은 작업 폴더의 명확한 경로로 옮겨 두세요.

2. hermes tools에서 모든 플랫폼 공통 도구 선택

이제 대화 채널에서 사용할 Tool을 설정합니다.

hermes tools

첫 화면에서 Configure all platforms (global)을 선택합니다.

여기서 global은 CLI, Discord 등 여러 플랫폼에 공통으로 적용할 기본 도구 구성을 뜻합니다. 특정 플랫폼만 따로 제한하고 싶다면 나중에 해당 플랫폼 메뉴에서 설정을 덮어쓸 수 있습니다.

도구 목록에서는 다음 키를 사용합니다.

• 위·아래 방향키: 항목 이동
• Space: 현재 항목 선택 또는 해제
• Enter: 선택 내용 저장
• Esc: 이전 화면으로 이동

캡처에서는 Core, File Operations, Web & Search, Media, Agent, Automation, Communication 등 사용할 Tool을 체크했습니다. 화면의 체크 상태를 참고하되, 외부 서비스가 필요한 Tool은 다음 단계에서 제공자와 인증을 별도로 설정해야 합니다.

권한 주의: terminal, file, browser, messaging처럼 실제 시스템이나 외부 서비스에 영향을 주는 Tool은 필요한 플랫폼에서만 켜는 편이 안전합니다. Discord Bot을 여러 사람이 사용할 수 있다면 허용 사용자 목록과 채널 권한을 먼저 제한하세요.

3. 기존 Tool의 제공자와 API 키 다시 설정

Tool 종류를 켰다면 각 Tool이 어떤 제공자를 사용할지 연결합니다. hermes tools 첫 화면으로 돌아가 Reconfigure an existing tool’s provider or API Key를 선택합니다.

이 메뉴는 이미 활성화된 Tool의 제공자를 바꾸거나 API 키와 OAuth 인증을 다시 연결할 때 사용합니다.

4. Web Search에 Tavily 또는 Brave Search 연결

재설정할 Tool 목록에서 Web Search를 선택합니다.

이어서 검색 제공자를 선택합니다.

캡처에는 Tavily와 Brave Search가 보입니다.

• Tavily: 에이전트가 읽기 좋은 검색 결과와 본문 추출 중심
• Brave Search: 일반 웹 검색 결과를 빠르게 가져오는 방식

화면은 한 번에 사용할 기본 제공자 하나를 선택하는 구조입니다. 두 서비스의 API 키를 모두 준비해 둘 수는 있지만, Web Search가 실제로 사용할 기본 제공자는 현재 선택한 항목입니다. 필요하면 같은 Reconfigure 메뉴로 돌아와 다른 제공자로 변경합니다.

Tavily API 키 무료 발급 방법

2026년 7월 Tavily 공식 가격 페이지 기준으로 Researcher 무료 플랜은 매월 1,000 API credits를 제공하며 신용카드 등록이 필요하지 않습니다. 검색 방식에 따라 한 번의 요청이 사용하는 credit 수가 달라질 수 있으므로 Dashboard의 사용량을 함께 확인하세요.

1. Tavily API Key Dashboard를 엽니다.
2. 이메일 또는 화면에 표시되는 계정 방식으로 회원가입하고 로그인합니다.
3. Dashboard의 API Key 영역에서 기본으로 발급된 키를 확인합니다.
4. 복사 버튼을 눌러 tvly-로 시작하는 키를 복사합니다.
5. 키는 메신저나 문서에 저장하지 말고 바로 Hermes의 Tavily API Key 입력 화면에 붙여 넣습니다.

무료 사용량은 Tavily 공식 가격 페이지에서 다시 확인할 수 있습니다. 요금제와 credit 계산 기준은 변경될 수 있으므로 가입 시점의 표시가 우선입니다.

Brave Search API 키 무료 발급 방법

Brave Search API는 현재 Search 사용료가 1,000 requests당 5달러로 표시되지만, 매월 5달러 무료 크레딧이 자동 적용됩니다. 따라서 무료 크레딧 범위에서는 약 1,000회의 Search 요청을 사용할 수 있습니다.

1. Brave Search API 회원가입 페이지에서 계정을 만듭니다.
2. 이메일 인증 후 Dashboard에 로그인합니다.
3. My subscriptions 또는 Plans에서 Search 플랜을 선택합니다.
4. 왼쪽 메뉴의 API keys로 이동해 Add API Key를 누릅니다.
5. 키 이름을 입력하고 앞에서 구독한 Search 플랜을 연결해 생성합니다.
6. 생성된 키를 복사해 Hermes에서 Brave Search를 선택했을 때 표시되는 API Key 입력란에 붙여 넣습니다.

Brave 공식 안내에 따르면 무료 플랜에서도 부정 사용 방지를 위한 카드 등록을 요구할 수 있습니다. 이 카드는 본인 확인에 사용되며 무료 플랜에서는 결제하지 않는다고 설명되어 있습니다. 다만 무료 크레딧을 넘는 사용과 결제 방식은 바뀔 수 있으므로 Dashboard의 Usage·Subscriptions에서 현재 사용량과 과금 조건을 확인하세요.

API 키 보관: Tavily와 Brave Search 키는 비밀번호처럼 취급합니다. Git 저장소, 블로그 캡처, Discord 채팅에 올리지 마세요. 노출됐다면 해당 Dashboard에서 기존 키를 폐기하고 새 키를 발급한 뒤 Hermes 설정도 교체합니다.

Tavily를 선택할 때

Tavily를 선택하면 API 키 입력 화면이 표시됩니다.

Tavily 계정에서 발급받은 키를 붙여 넣고 Enter를 누릅니다. 입력한 키는 화면에서 별표로 가려집니다.

Brave Search를 선택할 때

같은 Web Search 제공자 목록에서 Brave Search를 선택하고 Brave Search API에서 발급받은 키를 입력합니다. 이번 캡처에는 Tavily 키 입력 화면만 있으므로 Brave 키 화면이 별도로 있는 것처럼 표현하지 않습니다.

API 키 보안: 터미널에서 별표로 보이더라도 키가 안전하게 폐기됐다는 뜻은 아닙니다. 원본 캡처, 셸 기록, 공유 문서, Git 저장소에 실제 값이 남지 않았는지 확인하세요. 노출된 키는 이미지에서 가리는 것으로 끝내지 말고 해당 서비스에서 폐기 후 재발급해야 합니다.

5. Image Generation을 OpenAI Codex OAuth로 설정

다시 Reconfigure an existing tool’s provider or API Key로 들어가 Image Generation을 선택합니다. 제공자 목록에서 OpenAI Codex (OAuth)를 선택합니다.

이번 환경은 이미 ChatGPT 구독 계정으로 OpenAI Codex OAuth를 연결했기 때문에 이 경로를 사용했습니다. 별도의 OpenAI API 키를 직접 입력하는 방식과 다릅니다.

OpenAI Codex OAuth를 선택한 뒤 기기 인증이 필요하다는 안내가 나오면 화면의 공식 주소와 일회용 코드를 이용해 ChatGPT 계정으로 인증합니다. 기존 인증이 유효하면 다시 로그인하지 않고 연결될 수도 있습니다.

• ChatGPT 구독이나 계정 사용 한도는 API 종량제 키와 별개입니다.
• 계정 종류와 Hermes 버전에 따라 표시되는 제공자나 사용 가능한 이미지 기능이 달라질 수 있습니다.
• OAuth 연결이 모델·검색·모든 외부 Tool을 자동으로 한꺼번에 설정해 주는 것은 아닙니다.

6. 기본 Skills만으로도 충분한 이유

Hermes에는 파일 읽기·쓰기, 웹 조사, 디버깅, 계획, 테스트, 문서 작업 등 자주 쓰는 기본 Skills가 이미 포함되어 있습니다. 처음부터 많은 Skill을 설치하지 않아도 일반적인 대화와 시스템 작업은 충분히 진행할 수 있습니다.

Skill은 모델의 능력을 새로 구매하는 기능이라기보다, 특정 작업의 검증된 절차와 주의사항을 필요할 때 불러오는 지침입니다. 따라서 다음 기준으로 추가하는 편이 좋습니다.

• 실제로 반복할 작업인지
• 현재 프로젝트와 운영체제에 맞는지
• 요구하는 외부 도구와 권한을 이해했는지
• 기본 Skill과 역할이 겹치지 않는지

설치된 Skill은 다음 명령으로 확인할 수 있습니다.

hermes skills list

새 Skill을 설치하기 전에는 inspect로 내용을 먼저 볼 수도 있습니다.

hermes skills inspect official/software-development/code-wiki

7. 개발 작업용 Skills 세 개 추가

이번 라즈베리파이 AI 머신에서는 코드 작업을 맡길 때 유용한 세 가지 공식 Skill을 추가합니다.

hermes skills install official/software-development/subagent-driven-development
hermes skills install official/software-development/code-wiki
hermes skills install official/software-development/rest-graphql-debug

각 Skill의 용도는 다음과 같습니다.

subagent-driven-development

큰 작업을 여러 하위 작업으로 나누고, 별도의 subagent에 맡긴 뒤 결과를 단계적으로 검토하는 개발 흐름을 제공합니다. 구현 계획이 있고 작업 단위가 비교적 독립적일 때 유용합니다.

code-wiki

코드 저장소를 분석해 개요, 모듈 설명, Mermaid 다이어그램이 포함된 Wiki 문서를 만드는 절차를 제공합니다. 처음 보는 프로젝트를 파악하거나 문서화를 맡길 때 사용할 수 있습니다.

rest-graphql-debug

REST·GraphQL API 문제를 상태 코드, 인증, 요청 본문, 스키마, 재현 명령 순서로 좁히는 디버깅 절차입니다. API가 401·403·500을 반환하거나 Postman에서는 되는데 코드에서 실패할 때 도움이 됩니다.

Skill 설치가 끝난 뒤 목록에서 이름을 확인합니다.

hermes skills list

추가로 살펴볼 만한 Plugins와 Skills

지금 설치한 항목만으로도 검색·이미지·개발 작업을 시작할 수 있습니다. 아래 항목은 모든 사용자에게 필수는 아니지만, 실제 운영 방식과 맞는다면 추가로 살펴볼 만합니다.

운영 상태와 알림에 유용한 Plugins

Langfuse observability

대화, LLM 호출, Tool 사용을 Langfuse에서 추적하고 싶을 때 사용하는 관측 Plugin입니다. 호출이 어느 단계에서 오래 걸렸는지, 어떤 Tool이 사용됐는지 확인해야 하는 운영 환경에 유용합니다.

hermes plugins enable observability/langfuse

Langfuse 계정과 인증 정보가 필요하므로 개인 테스트 단계에서는 건너뛰어도 됩니다. 대화 내용과 Tool 사용 기록이 외부 관측 서비스로 전달될 수 있어 기록 범위도 먼저 확인해야 합니다.

ntfy-platform

작업 완료나 장애 알림을 휴대전화로 간단히 받고 싶을 때 사용할 수 있는 경량 Push Gateway Plugin입니다. ntfy.sh 또는 직접 운영하는 ntfy 서버의 topic을 구독하고 메시지를 주고받습니다.

hermes plugins enable ntfy-platform

ntfy topic 이름만으로는 사용자 신원을 안전하게 구분할 수 없습니다. 실제 운영에서는 추측하기 어려운 private topic과 read token을 사용해야 합니다.

web-ddgs

별도의 검색 API 키 없이 DuckDuckGo 검색을 예비 경로로 사용하고 싶을 때 살펴볼 수 있습니다. Tavily나 Brave Search의 무료 사용량을 모두 썼을 때 무조건 같은 품질을 보장하는 대체재는 아니지만, 간단한 검색용 보조 경로로 유용합니다.

hermes plugins enable web-ddgs

이 Plugin은 ddgs Python 패키지가 필요합니다. 활성화 과정이나 상태 확인에서 설치 안내가 나오면 해당 안내를 확인한 뒤 진행하세요.

개발 품질을 높이는 선택 Skills

아래 Skills는 이번에 설치한 세 개와 역할이 겹치지 않으면서 개발 작업의 검증 단계를 강화합니다.

• systematic-debugging: 증상에 바로 패치를 붙이기보다 재현, 로그 수집, 원인 분리 후 수정하는 절차
• test-driven-development: 동작 변경 전에 실패하는 테스트를 만들고 최소 구현으로 통과시키는 TDD 절차
• requesting-code-review: 큰 기능 완료나 병합 전에 별도 검토 단계로 요구사항·품질 문제를 찾는 절차

Skill Registry의 출처와 신뢰 등급은 검색 시점에 따라 달라질 수 있습니다. 바로 설치하기보다 먼저 내용을 확인합니다.

hermes skills inspect systematic-debugging
hermes skills inspect test-driven-development
hermes skills inspect requesting-code-review

내용과 출처가 목적에 맞으면 필요한 항목만 설치합니다.

hermes skills install systematic-debugging
hermes skills install test-driven-development
hermes skills install requesting-code-review

Plugin과 Skill을 추가한 뒤에도 hermes plugins list --plain, hermes skills list로 실제 활성화·설치 상태를 확인하세요. 사용하지 않는 항목은 켜 둔 채 방치하기보다 비활성화하거나 제거하는 편이 관리하기 쉽습니다.

8. 설정 상태 확인하기

설정을 마친 뒤 플러그인과 Tool 상태를 각각 확인합니다.

hermes plugins list --plain
hermes tools --summary

hermes plugins list --plain 출력에는 다음 플러그인이 enabled 상태로 포함되어야 합니다.

security-guidance
disk-cleanup

버전과 출력 순서, 다른 플러그인 줄은 설치 시점과 구성에 따라 달라질 수 있습니다.

hermes tools --summary에서는 global 설정과 Discord 등 각 플랫폼에서 활성화된 Tool 요약을 확인합니다. 다음 항목을 중심으로 봅니다.

• Web Search가 활성화됐는지
• Image Generation이 활성화됐는지
• Discord에서 필요한 Tool이 허용됐는지
• 의도하지 않은 위험 Tool이 모든 플랫폼에 열려 있지 않은지

제공자 인증이 실패한다면 hermes tools의 Reconfigure 메뉴에서 해당 Tool을 다시 선택합니다. API 키 앞뒤에 공백이 들어가지 않았는지, OAuth 인증이 완료됐는지도 확인하세요.

9. Gateway 재시작으로 Discord에 반영

실행 중인 Gateway는 시작할 때 읽은 Tool과 Plugin 구성을 유지할 수 있습니다. 설정을 마쳤다면 재시작합니다.

hermes gateway restart

재시작 후 상태를 확인합니다.

hermes gateway status

Discord에서는 기존 대화를 계속 사용하기보다 새 세션을 시작한 뒤 간단한 읽기 작업으로 시험합니다.

웹에서 Hermes Agent 공식 문서의 Tools 페이지를 찾아 핵심만 요약해줘.

이미지 Tool은 처음부터 복잡한 편집을 맡기기보다 작은 테스트 이미지를 한 장 요청해 연결 여부와 계정 한도를 확인합니다.

Tool 설정은 실행 중인 대화의 도구 목록에 즉시 추가되지 않을 수 있습니다. Gateway 재시작 후에도 기존 세션에서 보이지 않으면 새 세션을 시작해 다시 확인하세요.

기능 확장 완료 체크리스트

AI에게 Tool 사용을 맡길 때 확인할 것

검색과 이미지 생성 기능이 연결됐다고 해서 모든 요청을 자동 실행하게 둘 필요는 없습니다.

먼저 사용할 Tool과 외부로 전송될 정보를 알려줘.
비밀값과 개인 파일은 전송하지 마.
유료 호출 가능성이 있으면 실행 전에 알려줘.
작업 후에는 사용한 출처와 생성된 파일 경로를 보여줘.

특히 웹 검색에는 검색어가 외부 서비스로 전달되고, 이미지 생성에는 프롬프트와 입력 이미지가 제공자에게 전송될 수 있습니다. 회사 코드, API 키, 개인 사진을 그대로 넣기 전에 데이터 범위를 확인하세요.

다음 글: Hermes Google OAuth 연결

이번 4편에서는 Hermes 자체의 Plugins, Tools, Skills를 정리했습니다. 5편에서는 실제 업무 자료에 접근할 수 있도록 Google Cloud OAuth 클라이언트를 만들고 Gmail, Calendar, Drive, Sheets, Docs를 Hermes에 연결하는 과정을 진행합니다.

진행할 내용은 다음과 같습니다.

1. Google Cloud 프로젝트에서 Gmail·Calendar·Drive·Sheets·Docs·People API를 활성화합니다.
2. Google Auth Platform의 앱 정보와 External 대상을 설정합니다.
3. Desktop app OAuth 클라이언트를 만들고 JSON을 다운로드합니다.
4. PowerShell의 scp로 JSON을 pi-office에 복사합니다.
5. Discord에서 Hermes에게 전체 Workspace 서비스 등록을 요청합니다.
6. 브라우저 승인과 localhost 리디렉션 URL 전달을 거쳐 실제 API 호출까지 검증합니다.

Gmail 전송, Calendar 일정 생성, Drive 공유·삭제, Sheets·Docs 수정은 외부에 실제 결과를 남깁니다. 5편에서도 읽기 요청부터 연결을 검증하고, 쓰기 작업은 대상과 내용을 확인한 뒤 한 단계씩 진행합니다.

라즈베리파이5 AI 머신 세팅 · 5편 Hermes Google OAuth 연결 API 6개 활성화부터 OAuth JSON 전송, 브라우저 승인과 실제 Google API 호출 검증까지 진행합니다. 5편 이어서 보기 →

공식 자료

• Hermes Agent Tools 공식 문서
• Hermes Agent Skills 공식 문서
• Hermes Agent CLI 명령 공식 문서
• Hermes Agent Gateway 공식 문서
• Tavily API Key Dashboard
• Tavily 공식 가격 페이지
• Tavily 공식 사이트
• Brave Search API Quickstart
• Brave Search API 회원가입
• Brave Search API 공식 문서

정리

이번 4편에서는 Hermes 최소 설치 상태에 Plugins, Tools, Skills를 필요한 만큼 추가했습니다. API 키가 필요 없는 security-guidance와 disk-cleanup을 켜고, hermes tools에서 모든 플랫폼의 공통 Tool을 선택했습니다.

Web Search는 Tavily 또는 Brave Search 중 현재 사용할 기본 제공자를 설정하고 API 키를 연결했습니다. Image Generation은 이미 사용 중인 ChatGPT 계정의 OpenAI Codex OAuth 경로를 선택했습니다. 기본 Skills만으로도 일반 작업은 충분하지만, 개발 계획 실행·코드 문서화·API 디버깅에 쓸 세 개의 공식 Skill을 추가했습니다.

마지막으로 hermes plugins list --plain과 hermes tools --summary로 상태를 확인하고 Gateway를 재시작했습니다. 이제 라즈베리파이5의 Hermes는 Discord 대화를 넘어 검색, 이미지, 개발 절차를 실제 작업에 활용할 수 있는 확장 구성을 갖췄습니다.