빠른 답변
모델 제공업체에 연결하고, 도구를 사용하고, Telegram 같은 메시징 게이트웨이를 통해 소통할 수 있는 AI 에이전트를 원한다면 홈 서버에서 Hermes Agent를 셀프 호스팅할 수 있습니다. 대부분의 초보자에게 가장 어려운 점은 앱을 실행하는 것만이 아닙니다. 각 작업이 호스트 서버, 컨테이너 내부, 앱 환경 또는 메시징 플랫폼 중 어디에서 이루어지는지 파악하는 것입니다.
안전한 셀프 호스팅 환경이라면 문제를 해결하기 전에 다음 여섯 가지 질문에 답할 수 있어야 합니다.
- 호스트에서 작업 중인가요, 아니면 컨테이너 안에서 작업 중인가요?
- 앱 설정, 로그, 다운로드, 런타임 데이터는 어디에 저장되나요?
- 누가 파일을 소유하고 앱을 실행하나요?
- 앱이 모델 제공업체 및 메시징 API에 접속할 수 있나요?
- API 키, 봇 토큰, 허용 목록은 안전하게 보호되나요?
- 재시작 후에도 에이전트가 작동하는지 어떻게 확인하나요?
이러한 경계를 명확히 해두면 Hermes Agent 설정을 훨씬 쉽게 이해하고, 확인하고, 문제를 해결할 수 있습니다.
셀프 호스팅 홈 서버 구성에서 Hermes Agent란?
Hermes Agent는 모델 제공업체에 연결하고 도구를 사용하며 터미널이나 메시징 채널을 통해 상호작용할 수 있는 셀프 호스팅 AI 에이전트 워크플로입니다. 홈 서버에서는 흔히 AI 모델, 서버 환경, 웹 대시보드나 봇 게이트웨이 같은 통신 인터페이스 사이에서 작동합니다.
중요한 점은 셀프 호스팅 에이전트가 단순한 챗봇이 아니라는 것입니다. 설정에 따라 파일, 터미널 도구, 모델 API, 메시징 플랫폼, 런타임 데이터와 상호작용할 수 있습니다. 따라서 경로, 권한, 접근 경계를 관리하는 것이 중요합니다.
AI 상호작용 및 메시징에서 Hermes Agent의 역할
Hermes Agent는 모델 제공업체에 연결하고, 대화를 시작하고, 도구를 사용하고, 메시징 게이트웨이를 연결하도록 설정할 수 있습니다. Hermes Agent 빠른 시작 절차에서는 Hermes 설치, 모델 제공업체 설정, 첫 대화 시작, 터미널 도구 사용, 이후 게이트웨이를 통해 메시징 플랫폼 연결 방법을 설명합니다.
홈 서버 사용자에게 이는 Hermes를 직접 관리하는 기기에서 지속적으로 실행되는 AI 어시스턴트로 사용할 수 있다는 뜻입니다. 모델 인증 정보, 앱 런타임, 게이트웨이 설정, 접근 권한 등 설정 단계가 추가될 수도 있습니다.
WebUI 설정만으로 충분한 경우
앱이 대시보드에서 필요한 모든 설정을 바로 제공한다면 일반적으로 WebUI 설정만으로 충분합니다. 이 방법은 누락되거나 문제가 발생한 항목이 없는 한 컨테이너 터미널에 들어갈 필요가 없어 대부분의 사용자에게 가장 안전합니다.
다음과 같은 경우에는 WebUI 우선 방식이 적합합니다.
- 앱이 문제없이 설치됩니다.
- 인터페이스에서 모델 제공업체를 설정할 수 있습니다.
- 셸에 접속하지 않고 메시징 게이트웨이를 연결할 수 있습니다.
- 대시보드에 상태가 명확하게 표시됩니다.
- 로그에 권한 또는 네트워크 오류가 표시되지 않습니다.
대시보드에서 필요한 옵션을 제공한다면 먼저 해당 옵션을 사용하세요. 컨테이너 터미널 설정은 모든 사용자가 처음부터 기본으로 사용하는 방법이 아니라, 대체 방법이나 고급 방법으로 고려해야 합니다.
컨테이너 터미널 설정이 필요한 경우
대시보드에서 필요한 옵션을 제공하지 않거나, 앱에서 컨테이너 내부의 설정 마법사를 실행해야 하거나, 문제 해결을 위해 로그, 런타임 환경 또는 앱별 명령에 접근해야 할 때 컨테이너 터미널을 설정해야 할 수 있습니다.
여기서 많은 사용자가 혼란을 겪습니다. 호스트 셸에서 실행한 명령은 컨테이너 내부의 앱에 영향을 주지 않을 수 있습니다. 컨테이너 내부에서 보이는 파일이 호스트의 같은 경로에는 없을 수 있습니다. 권한 오류는 모델 제공업체나 봇 토큰이 아니라 앱을 실행하는 사용자 때문에 발생할 수도 있습니다.
컨테이너 터미널을 사용하기 전에 현재 어떤 셸에 있는지, 어떤 사용자로 실행 중인지 정확히 확인하세요.
시작하기 전에 필요한 항목
셀프 호스팅 에이전트를 설정하려면 서버를 실행하는 것만으로는 부족합니다. 작동하는 네트워크 경로, 모델 접속 권한, 메시징 자격 증명, 그리고 실수로 엉뚱한 파일을 변경하지 않으면서 앱을 관리할 수 있는 충분한 권한이 필요합니다.
인터넷에 접속할 수 있는 홈 서버
클라우드 모델 제공업체나 메시징 API를 사용할 계획이라면 홈 서버가 인터넷에 접속할 수 있어야 합니다. 로컬 모델 엔드포인트를 사용하는 경우에도 서버가 로컬 네트워크나 컨테이너 네트워크를 통해 해당 엔드포인트에 접속할 수 있어야 합니다.
에이전트가 제대로 설치된 것처럼 보여도 응답하지 않을 수 있으므로 네트워크 접속이 중요합니다. 예를 들어 모델 제공업체 연결, 메시징 게이트웨이, 대시보드는 각각 서로 다른 네트워크 경로를 사용할 수 있습니다.
먼저 다음을 확인하세요.
- 서버에 안정적인 LAN 연결이 있습니다.
- 서버가 모델 엔드포인트 또는 제공업체에 접속할 수 있습니다.
- 서버가 메시징 API에 접속할 수 있습니다.
- 브라우저에서 대시보드 포트에 접속할 수 있습니다.
- 게이트웨이를 차단하는 방화벽 규칙이 없습니다.
모델 제공업체 또는 로컬 모델 엔드포인트
유용한 응답을 생성하려면 Hermes를 먼저 모델에 연결해야 합니다. 클라우드 제공업체, API 키 또는 OpenAI 호환 엔드포인트를 사용할 수 있습니다. 하드웨어와 모델 스택이 지원되는 경우 로컬 모델 서비스에 연결할 수도 있습니다.
중요한 설정 사항은 모델 구성과 메시징 구성이 서로 별개라는 점입니다. 봇이 제대로 연결되어 있어도 모델 제공업체가 잘못 설정되었을 수 있고, 모델 제공업체가 작동해도 봇 게이트웨이가 작동하지 않을 수 있습니다.
설정을 시작하기 전에 모델 기본 URL, API 키, 모델 이름, 컨텍스트 설정을 정리해 두세요.
메시징 계정 및 봇 토큰
텔레그램이나 다른 메시지 플랫폼을 통해 에이전트와 대화하려면 메시징 계정과 봇 또는 게이트웨이 자격 증명이 필요합니다. 텔레그램의 경우 보통 봇을 만들고 토큰을 저장해야 합니다.
봇 토큰은 비밀번호처럼 취급해야 합니다. Telegram에 따르면 각 봇은 Bot API 요청을 인증하는 데 사용되는 고유한 토큰을 받으며, 요청에는 Telegram 봇 토큰 인증 모델에 따라 API 경로에 토큰이 포함됩니다.
봇 토큰을 공개 채팅, 스크린샷, 로그, GitHub 이슈 또는 공유 문서에 붙여넣지 마세요. 토큰이 노출되면 메시징 플랫폼의 공식 절차를 통해 새로 발급하세요.
호스트 IP 주소, 로그인 권한 및 컨테이너 권한
서버 대시보드에 액세스하거나 SSH로 연결하려면 호스트 IP 주소가 필요합니다. 또한 앱을 안전하게 관리할 수 있는 로그인 권한이 필요합니다.
컨테이너 기반 설정에서는 권한이 여러 계층으로 나뉘는 경우가 많습니다.
| 권한 계층 | 제어 대상 | 흔한 실수 | 안전한 확인 방법 |
|---|---|---|---|
| 호스트 사용자 / SSH 계정 | 홈 서버 파일 시스템, Docker 명령 및 서버 대시보드에 대한 접근 권한. | 호스트 권한이 컨테이너 내부에도 자동으로 적용된다고 가정하는 문제. | 어떤 계정으로 로그인했는지, 서버 수준에서 어떤 작업을 수행할 수 있는지 확인하세요. |
| 컨테이너 사용자 | 컨테이너 내부에서 앱 프로세스를 실행하고 앱 파일을 쓰는 사용자. | 앱은 일반적으로 루트가 아닌 사용자로 실행되는데 설정을 root로 실행하는 문제. | 앱 데이터를 만들거나 편집하기 전에 의도된 컨테이너 사용자를 확인하세요. |
| 마운트된 호스트 폴더 | 컨테이너에 노출된 호스트 폴더 또는 Docker 볼륨. | 앱이 읽는 경로에 마운트되지 않은 호스트 폴더를 편집하는 문제. | 호스트 원본 경로와 컨테이너 대상 경로를 확인하세요. |
| 앱 런타임 경로 | 구성 파일, 로그, 다운로드, 세션 및 임시 데이터가 저장되는 위치. | 잘못된 계층의 파일을 변경하거나 다시 시작한 뒤 설정이 사라지는 문제. | 다시 시작한 뒤에도 경로가 유지되고 앱 사용자가 쓸 수 있는지 확인하세요. |
항상 root가 정답이라고 가정하지 마세요. 잘못된 시점에 root를 사용하면 앱 사용자가 나중에 수정할 수 없는 root 소유 파일이 만들어질 수 있습니다.
호스트 경로와 컨테이너 경로, 앱 데이터 경로
이 글에서 가장 중요한 개념입니다. Hermes Agent 설정 문제의 상당수는 호스트 경로, 컨테이너 경로, 앱 데이터 경로, 로그, 다운로드 및 마운트된 볼륨을 혼동해서 발생합니다.
명령을 실행하거나 디버깅하기 전에 에이전트 컨테이너 제어 맵을 사용하세요.
| 계층 | 답해야 할 질문 | 검증 신호 | 일반적인 실패 |
|---|---|---|---|
| 호스트 시스템 | 서버, 대시보드, SSH 세션 및 컨테이너 관리 도구에 연결할 수 있나요? | 대시보드 또는 SSH 세션이 열리고 컨테이너가 실행 중으로 표시됩니다. | 앱이 설치된 것처럼 보이지만 서버 또는 컨테이너에 실제로 연결할 수 없습니다. |
| 컨테이너 런타임 | 올바른 컨테이너 안에서 예상된 사용자를 사용하고 있나요? | 셸, 작업 디렉터리 및 사용자가 앱 설정 경로와 일치합니다. | 명령은 호스트 셸에서 실행되며 컨테이너 내부의 앱에는 영향을 주지 않습니다. |
| 앱 데이터 경로 | 구성 파일, 로그, 다운로드 및 런타임 파일은 어디에 있나요? | 설정과 로그는 다시 시작한 뒤에도 유지되며 앱 사용자가 쓸 수 있습니다. | 재시작 후 설정이 사라지거나 앱에 권한 거부 오류가 표시됩니다. |
| 네트워크 경로 | 컨테이너가 모델 제공업체, 로컬 엔드포인트 및 메시징 API에 연결할 수 있나요? | 제공업체 확인, 게이트웨이 호출 및 대시보드 액세스가 예상한 계층에서 작동합니다. | 앱이 제대로 설치된 것처럼 보여도 모델이나 봇이 작동하지 않습니다. |
| 인증 정보 및 액세스 | API 키, 봇 토큰 및 허용 목록에 등록된 사용자가 안전하게 설정되어 있나요? | 비공개 테스트 메시지가 정상적으로 전송되고 로그에 토큰 또는 액세스 오류가 표시되지 않습니다. | 봇 토큰이 유효하지 않거나 노출되었거나 허용된 사용자 ID가 잘못되었습니다. |
| 재시작 확인 | 게이트웨이나 서비스를 재시작한 후에도 설정이 계속 작동하나요? | 봇이 응답하고, 대시보드가 정상 작동하며, 재시작 후에도 로그에 문제가 없습니다. | 이전 구성이 계속 적용되거나 새 설정이 저장되지 않습니다. |
호스트 시스템에서 볼 수 있는 항목
호스트 시스템은 실제 홈 서버 운영체제입니다. 호스트 폴더, Docker 컨테이너, 네트워크 인터페이스, 저장 장치 및 시스템 수준 서비스를 볼 수 있습니다.
앱이 Docker에서 실행 중이라면 호스트는 컨테이너가 보는 방식과 같은 방식으로 앱의 내부 경로를 볼 수 없을 수도 있습니다. 호스트에는 대신 Docker 볼륨, 바인드 마운트된 폴더 또는 컨테이너 메타데이터가 표시될 수 있습니다.
이 때문에 /opt/data나 /app/config 같은 경로는 호스트와 컨테이너 내부에서 서로 다른 의미일 수 있습니다.
컨테이너에서 볼 수 있는 항목
컨테이너는 자체 파일 시스템을 볼 수 있습니다. 컨테이너에 마운트된 호스트 폴더도 볼 수 있습니다. 컨테이너 경로는 앱의 관점에서 본 경로입니다.
Docker에 따르면 바인드 마운트는 호스트 시스템의 파일이나 디렉터리를 컨테이너에 마운트하는 방식인 반면, Docker 볼륨은 호스트의 Docker 저장소 디렉터리 안에 생성되고 Docker에서 관리합니다. 자세한 내용은 Docker 바인드 마운트 저장 모델을 참조하세요.
컨테이너는 마운트된 호스트 경로에만 액세스할 수 있으므로 이 구분은 중요합니다. 앱이 파일을 찾지 못한다면, 파일은 호스트에 있지만 예상한 컨테이너 경로에 마운트되지 않았을 수 있습니다.
앱 구성 및 런타임 데이터가 주로 저장되는 위치
앱 구성, 로그, 다운로드 및 런타임 데이터는 앱의 패키징 방식에 따라 서로 다른 위치에 있을 수 있습니다. 일부 데이터는 컨테이너 안에, 일부는 Docker 볼륨에, 나머지는 호스트에서 바인드 마운트된 위치에 있을 수 있습니다.
셀프 호스팅 에이전트의 일반적인 데이터 유형은 다음과 같습니다.
- 모델 제공업체 설정;
- 게이트웨이 구성;
- 봇 토큰 또는 메시징 설정;
- 로그 및 세션 상태;
- 임시 다운로드;
- 도구 출력;
- 앱별 런타임 데이터.
중요한 질문은 단지 “파일이 어디에 있는가?”가 아니라 “이 파일을 소유한 계층은 어디이며 어떤 사용자가 수정할 수 있는가?”입니다.

경로 혼동으로 권한 및 데이터 문제가 발생하는 이유
경로를 혼동하면 두 가지 문제가 흔히 발생합니다. 첫째, 호스트에서 파일을 편집하지만 컨테이너는 컨테이너 내부의 다른 경로에 있는 파일을 읽습니다. 둘째, 사용자가 루트 권한으로 설정을 실행해 앱 사용자가 나중에 수정할 수 없는 파일을 만듭니다.
호스트 폴더를 비어 있지 않은 컨테이너 디렉터리에 마운트하면 바인드 마운트가 기존 컨테이너 파일을 가릴 수도 있습니다. 이 경우 파일이 사라진 것처럼 보이지만 실제로는 마운트에 가려져 있을 뿐입니다.
앱 데이터 문제를 해결하기 전에 런타임 계층, 마운트된 경로, 파일 소유자, 컨테이너 사용자를 확인하세요.
셀프 호스팅 에이전트를 단계별로 구성하는 방법
셀프 호스팅 에이전트 설정은 위험도가 낮은 확인부터 구성, 검증 순으로 진행해야 합니다. 어느 계층에서 문제가 발생했는지 파악하기 전에는 권한을 변경하거나 서비스를 다시 시작하지 마세요.
1단계: 서버 대시보드에서 앱 설치 또는 열기
홈 서버에서 지원하는 가장 간단한 설치 또는 앱 실행 방법부터 시작하세요. 서버에 앱 대시보드가 있다면 이를 통해 Hermes Agent가 설치되어 표시되고 실행 중인지 확인하세요.
이 단계에서는 앱에서 요구하지 않는 한 컨테이너에 들어가지 마세요. 먼저 대시보드 상태와 표시되는 경우 앱 버전, 구성 페이지를 사용할 수 있는지 확인하세요.
앱이 아예 시작되지 않으면 구성 파일을 변경하기 전에 로그를 확인하세요.
2단계: 호스트 IP 및 네트워크 연결 확인
호스트 IP 주소를 확인하고 브라우저나 터미널에서 서버에 연결할 수 있는지 확인하세요. 설정에 따라 대시보드, SSH 또는 로컬 게이트웨이 접속에 같은 IP를 사용할 수 있습니다.
그런 다음 외부 네트워크에 연결할 수 있는지 확인하세요. 컨테이너가 메시징 API에 연결할 수 없으면 메시징 봇이 응답하지 않고, 서버가 모델 엔드포인트에 연결할 수 없으면 모델 제공업체도 작동하지 않습니다.
이 확인을 통해 ‘앱 구성 실패’와 ‘네트워크 연결 실패’를 구분할 수 있습니다.
3단계: 올바른 사용자로 컨테이너에 들어가기
컨테이너 터미널 설정이 필요하면 앱에서 지정한 사용자로 컨테이너에 들어가세요. 잘못된 사용자로 만든 파일은 나중에 권한 오류를 일으킬 수 있으므로 중요합니다.
호스트 셸과 컨테이너 셸을 같은 환경으로 취급하지 마세요. 호스트에서 작동하는 명령이 컨테이너에는 없을 수 있고, 컨테이너 내부의 파일 경로가 호스트에는 없을 수 있습니다.
설정 명령을 실행하기 전에 다음을 확인하세요.
- 올바른 컨테이너 내부에 있습니다.
- 의도한 컨테이너 사용자로 실행 중입니다.
- 예상한 작업 디렉터리에 있습니다.
- 필요한 앱 명령을 사용할 수 있습니다.
- 컨테이너에서 나갔다가 다시 들어오는 방법을 알고 있습니다.
4단계: 설정 명령을 실행하기 전에 앱 환경 활성화
일부 셀프 호스팅 앱은 가상 환경이나 앱별 셸 설정을 사용합니다. 환경이 활성화되지 않으면 앱 명령을 찾을 수 없거나 잘못된 종속 항목으로 실행될 수 있습니다.
이 단계는 단순한 형식 절차가 아닙니다. 설정 마법사, 게이트웨이 명령, 모델 설정 명령이 앱과 동일한 런타임 환경에서 실행되도록 보장합니다.
명령이 예상치 못하게 실패하면, 무언가를 다시 설치하기 전에 올바른 컨테이너에 있는지, 앱 환경이 활성화되어 있는지 확인하세요.
5단계: 모델 공급자 또는 로컬 모델 서비스 연결하기
모델 공급자, 사용자 지정 엔드포인트 또는 로컬 모델 서비스를 설정하세요. 기본 URL, API 키, 모델 이름, 컨텍스트 관련 설정이 사용하는 공급자의 설정과 일치하도록 하세요.
모델 설정이 실패하면 다음 순서로 확인하세요.
- API 키가 올바른가요?
- 컨테이너에서 기본 URL에 연결할 수 있나요?
- 엔드포인트에서 해당 모델 이름을 지원하나요?
- 앱에 긴 컨텍스트 모델이 필요한가요?
- 컨테이너 내부에 네트워크 또는 DNS 문제가 있나요?
모델 오류와 메시징 오류를 혼동하지 마세요. 텔레그램 봇이 응답하지 않는 문제와 모델 공급자 오류는 에이전트가 작업 흐름을 완료하려면 둘 다 필요하다는 점에서만 관련이 있습니다.
6단계: 메시징 게이트웨이 설정하기
메시징 게이트웨이는 에이전트 런타임을 메시징 플랫폼에 연결합니다. 텔레그램의 경우 일반적으로 봇 토큰과 허용된 사용자 ID가 필요합니다.
올바른 게이트웨이 설정에서는 에이전트에게 메시지를 보낼 수 있는 사용자, 사용할 봇 토큰, 봇을 개인 채팅, 그룹 채팅 중 어디에 사용할지 또는 둘 다에 사용할지를 지정해야 합니다.
메시징 봇을 기본적으로 공개 인터페이스라고 생각하지 마세요. 셀프 호스팅 에이전트는 도구, 로컬 데이터 또는 봇에 접근할 수 있는 모든 사용자에게 공개해서는 안 되는 작업에 접근할 수 있습니다.
7단계: 게이트웨이를 재시작하고 새 설정 적용하기
모델이나 메시징 게이트웨이를 변경한 후에는 새 설정을 적용하기 위해 게이트웨이를 재시작해야 할 수 있습니다. 설정을 완료한 것처럼 보여도 이전 설정으로 실행되고 있을 수 있으므로 재시작 동작을 확인해야 합니다.
재시작 후 사용자 측과 서버 측에서 확인하세요. 테스트 메시지를 보내고, 대시보드 상태를 확인하고, 로그에서 권한, 토큰 또는 네트워크 오류를 살펴보세요.
재시작 후에도 재구성한 설정이 유지되지 않으면 데이터 경로와 권한 경계를 다시 확인하세요.

권한, 토큰 및 접근 제어
셀프 호스팅 에이전트는 로컬 런타임 권한과 외부 인증 정보를 함께 사용합니다. 따라서 토큰, 허용 목록 또는 사용자 경계가 잘못되면 설정이 기술적으로 작동하더라도 안전하지 않을 수 있습니다.
컨테이너 사용자가 중요한 이유
컨테이너 사용자는 컨테이너 안에서 앱이 어떤 파일을 읽고 쓸 수 있는지 결정합니다. 설정 명령을 root로 실행한 다음 앱을 일반 사용자로 실행하면 앱 데이터에 접근할 수 없게 될 수 있습니다.
이 문제는 앱 데이터 경로에서 권한 오류로 나타나는 경우가 많습니다. 해결 방법이 항상 root 권한으로 계속 실행하는 것은 아닙니다. 대부분 올바른 소유권을 복구하고 앱을 지정된 사용자로 실행하는 것이 더 나은 방법입니다.
특정 복구 단계에 필요한 경우에만 root를 사용하고, 일반적인 앱 파일을 root로 만들지 마세요.
API 키와 봇 토큰을 보호해야 하는 이유
API 키와 봇 토큰은 자격 증명입니다. 모델 API 키는 모델 제공업체에 대한 액세스 권한을 부여할 수 있습니다. 봇 토큰은 봇으로 요청을 보낼 권한을 부여할 수 있습니다.
이 값을 공개 저장소, 스크린샷, 공유 로그 또는 지원 요청 메시지에 넣지 마세요. 문제를 해결할 때 구성이나 로그를 공유하기 전에 토큰을 가리세요.
토큰이 노출되었다면 누군가 사용하지 않기를 바라기보다 토큰을 교체하세요.
사용자 허용 목록으로 비공개 액세스를 제어하는 방법
허용 목록은 메시징 게이트웨이를 통해 에이전트와 상호작용할 수 있는 사용자를 제한합니다. 메시징 봇에 예상보다 많은 사람이 접근할 수 있으므로 중요합니다.
비공개 AI 채팅에는 합리적인 범위에서 최소한의 허용 목록을 사용하세요. 허용된 사용자 ID가 올바른지, 테스트 메시지가 해당 계정에서 전송되는지 확인하세요.
여러 사람이 액세스해야 한다면 봇을 개방 상태로 두지 말고 필요한 사람을 명시적으로 추가하세요.
메시징 봇을 공개 인터페이스로 취급하면 안 되는 이유
메시징 봇은 일반적인 채팅 인터페이스처럼 보일 수 있지만, 그 뒤에는 모델 액세스, 도구, 세션, 로컬 런타임 권한을 가진 자체 호스팅 에이전트가 있을 수 있습니다.
따라서 단순한 알림 봇과는 다릅니다. 명확한 액세스 규칙, 안전하게 보호된 토큰, 통제된 네트워크 경로가 필요합니다.
그룹 채팅에서는 신중하게 설정하세요. 그룹 권한, 개인정보 보호 모드, 봇의 관리자 여부에 따라 봇이 볼 수 있거나 응답할 수 있는 메시지가 달라질 수 있습니다.
흔한 설정 문제와 해결 방법
대부분의 설정 문제는 런타임, 데이터 경로, 권한, 게이트웨이, 시크릿 또는 검증 중 여섯 가지 계층에서 원인을 찾을 수 있습니다.
앱 데이터 경로 내부의 권한 오류
권한 오류는 보통 현재 앱 사용자가 필요한 파일이나 폴더를 읽거나 쓸 수 없다는 뜻입니다. 이전 설정 명령이 root로 파일을 만들었거나 마운트된 폴더의 소유권이 잘못된 경우 발생할 수 있습니다.
먼저 다음을 확인하세요:
- 컨테이너 안에 있나요, 아니면 호스트에 있나요?
- 앱은 어떤 사용자로 실행되고 있나요?
- 앱 데이터 폴더의 소유자는 누구인가요?
- 앱 데이터 경로가 호스트에서 마운트되어 있나요?
- 이전에 설정 명령을 root로 실행한 적이 있나요?
대상을 이해하지 못한 채 상위 폴더 전체의 권한을 재귀적으로 변경하지 마세요. 필요한 최소한의 특정 경로만 수정하세요.
설정 후 봇이 응답하지 않음
Hermes Agent 자체는 실행 중이어도 봇이 응답하지 않을 수 있습니다. 문제는 토큰, 사용자 허용 목록, 메시징 게이트웨이, 네트워크 액세스 또는 그룹 권한에 있을 수 있습니다.
다음 순서대로 확인하세요:
- 봇 토큰이 올바른지 확인하세요.
- 사용자 ID가 허용 목록에 있는지 확인하세요.
- 구성을 변경한 후 게이트웨이를 재시작했는지 확인하세요.
- 컨테이너에서 메시징 API에 연결할 수 있는지 확인하세요.
- 토큰, 네트워크 또는 권한 오류가 있는지 앱 로그를 확인하세요.
- 그룹 채팅 동작을 점검하기 전에 비공개 채팅을 테스트하세요.
그룹 채팅은 권한이라는 변수가 추가되므로 비공개 채팅 테스트보다 대체로 더 복잡합니다.
모델 제공업체 설정이 올바르지 않음
메시징 봇은 응답하지만 모델 답변이 실패한다면 모델 제공업체가 문제일 수 있습니다. 기본 URL, API 키, 모델 이름, 엔드포인트 호환성을 확인하세요.
로컬 모델 엔드포인트의 경우 모델 서비스가 실행 중이며 컨테이너에서 접속 가능한지도 확인하세요. 네트워크 구성이 다르면 호스트에서는 접속할 수 있어도 컨테이너 안에서는 접속할 수 없을 수 있습니다.
제공업체 문제 해결과 메시징 문제 해결은 별도로 진행하세요. 이렇게 하면 실제 원인이 모델 연결 문제인데 봇 설정을 변경하는 일을 방지할 수 있습니다.
컨테이너가 메시징 API에 연결할 수 없음
컨테이너가 메시징 API에 연결할 수 없으면 게이트웨이가 메시지를 제대로 수신하거나 전송할 수 없습니다. DNS 문제, 방화벽 규칙, 프록시 설정 또는 아웃바운드 인터넷 접속 불가가 원인일 수 있습니다.
호스트와 컨테이너가 모두 인터넷에 접속할 수 있는지 확인하세요. 두 접속 상태가 항상 같지는 않습니다.
홈 서버에서 VPN, 프록시 또는 제한된 네트워크를 사용하는 경우 컨테이너가 아웃바운드 HTTPS 요청을 보낼 수 있는지 확인하세요.
그룹 채팅 권한 또는 개인정보 보호 모드로 인해 응답이 차단됨
그룹 채팅은 비공개 채팅보다 동작이 복잡합니다. 봇이 비공개 채팅에는 응답하지만 그룹에서는 응답하지 않을 수 있습니다. 메시지를 볼 수 없거나, 적절한 권한이 없거나, 개인정보 보호 설정의 영향을 받을 수 있기 때문입니다.
비공개 채팅부터 확인하세요. 그런 다음 그룹 채팅을 별도로 테스트하세요.
그룹에서 사용할 때는 봇을 직접 멘션해야 하는지, 관리자 권한이 필요한지, 개인정보 보호 설정상 필요한 메시지를 받을 수 있는지 확인하세요.
Hermes Agent가 제대로 작동하는지 확인하는 방법
설치가 끝났다고 해서 설정이 완료된 것은 아닙니다. 모델, 게이트웨이, 권한, 대시보드, 로그, 재구성 동작이 모두 기본 점검을 통과해야 완료된 것입니다.
설정 마법사가 오류 없이 완료됨
설정 마법사가 명령어 누락, 제공업체 또는 권한 오류 없이 완료되어야 합니다. 실패하면 다시 시도하기 전에 어느 계층에서 문제가 발생했는지 기록하세요.
설정 마법사 오류는 대개 다음 범주 중 하나에 해당합니다.
- 모델 제공업체 인증 정보;
- 런타임 환경;
- 컨테이너 권한;
- 앱 명령어 누락;
- 네트워크 액세스;
- 게이트웨이 구성.
이 범주를 기준으로 다음에 확인할 항목을 정하세요.
봇이 비공개 테스트 메시지에 응답함
가장 간단한 메시징 확인 방법은 비공개 테스트 메시지를 보내는 것입니다. 기본 메시지를 보내고 봇이 응답하는지 확인하세요.
비공개 채팅이 작동한다면 토큰, 허용 목록, 게이트웨이, 모델 연결은 대체로 올바르게 설정되었을 가능성이 높습니다. 그룹 채팅이 여전히 작동하지 않는다면 앱을 재설치하기보다 그룹 권한과 개인정보 보호 동작을 확인하세요.
첫 번째 메시징 테스트는 비공개 채팅으로 진행하세요.
대시보드에 에이전트가 실행 중으로 표시됨
시스템에 따라 대시보드에는 에이전트 또는 게이트웨이가 실행 중이라고 표시되어야 합니다. 대시보드 상태는 메시징 앱에만 의존하지 않고 서버 측 상태를 확인할 수 있어 유용합니다.
대시보드에 중지됨 또는 비정상 상태가 표시되면 토큰이나 모델 설정을 변경하기 전에 로그를 확인하세요.
대시보드 상태와 봇 응답은 서로 일치해야 합니다. 한쪽은 작동하고 다른 쪽은 실패한다면, 그 차이를 통해 문제가 발생한 계층을 파악할 수 있습니다.
로그에 권한 또는 네트워크 오류가 표시되지 않음
로그에 permission denied, token invalid, provider unreachable, gateway failed 또는 network timeout 오류가 반복해서 표시되지 않아야 합니다.
로그를 확인해 다음 조치를 판단하세요. 권한 오류는 파일 소유권 또는 컨테이너 사용자를 점검해야 한다는 뜻입니다. 네트워크 오류는 API 연결 가능성을 점검해야 한다는 뜻입니다. 토큰 오류는 자격 증명 구성을 점검해야 한다는 뜻입니다.
모든 계층을 한 번에 수정하지 마세요. 변수 하나를 변경하고, 필요하면 재시작한 다음 다시 테스트하세요.
재시작 후에도 재구성 유지
안정적인 설정은 재시작이나 재구성 후에도 유지되어야 합니다. 모델 또는 게이트웨이 설정을 변경한 후 필요한 서비스나 게이트웨이를 재시작하고 새 설정이 계속 적용되는지 확인하세요.
재시작 후 설정이 사라지면 구성이 어디에 저장되는지, 앱 데이터 경로가 영구 저장되는지 확인하세요.
호스트 경로, 컨테이너 경로, 마운트된 볼륨에 대한 지식은 이때 실질적인 도움이 됩니다.
실제 홈 서버 환경에서 작동하는 방식
실제 홈 서버 환경에서도 기본 설정 방식은 동일합니다. 런타임 계층을 확인하고, 데이터 경로를 점검하고, 자격 증명을 보호하고, 게이트웨이 액세스를 구성한 다음, 로그와 대시보드 상태로 검증합니다.
기기별 설정 가이드에서는 정확한 명령어 경로를 안내할 수 있습니다. 예를 들어 ZimaOS Hermes Agent 구성 워크플로에서는 모델 제공자 구성, Telegram 봇 연결, 앱 사용자로 Hermes 컨테이너에 진입, 앱 환경 활성화, 설정 명령 실행, 대시보드 상태 확인, 권한 또는 봇 응답 오류 해결을 포함하는 Hermes Agent 설정 경로를 설명합니다.
셀프 호스팅 앱, 메시징 게이트웨이, 가벼운 에이전트 워크플로를 소형 상시 가동 서버에서 운영하는 사용자에게 ZimaBoard 2 홈 AI 서버는 Docker 앱, 터미널 액세스, 로컬 서비스, 앱별 데이터 경로를 함께 파악해야 하는 환경에 적합합니다. 에이전트를 호스팅하는 유일한 방법은 아니지만, 이 문서에서 설명하는 홈 서버 워크플로의 좋은 예입니다.
핵심 교훈은 어디서나 적용할 수 있습니다. 설정 명령어 하나만 외우지 마세요. 어떤 계층에서 작업하고 있는지, 결과를 어떻게 검증할지 이해해야 합니다.
자주 묻는 질문
Hermes Agent를 웹 대시보드에서만 설정할 수 있나요?
대시보드에서 모델 및 게이트웨이 설정을 제공한다면 기본 설정에는 웹 대시보드만으로도 충분할 수 있습니다. 대시보드에서 필요한 옵션을 제공하지 않거나 문제 해결을 위해 앱 수준의 명령어가 필요한 경우에는 컨테이너 터미널에서 설정해야 합니다. 가능하면 WebUI부터 사용하고, 설정 과정에서 필요한 경우에만 컨테이너 터미널을 사용하세요.
호스트 셸 대신 컨테이너에 접속해야 하는 이유는 무엇인가요?
일부 앱 명령어는 앱 런타임과 종속 항목이 있는 컨테이너 내부에서만 사용할 수 있습니다. 같은 명령어를 호스트에서 실행하면 실패하거나 잘못된 환경에 영향을 줄 수 있습니다. 올바른 사용자로 컨테이너에 접속하면 설정 변경이 앱 자체에 적용되도록 할 수 있습니다.
호스트 데이터와 컨테이너 앱 데이터의 차이는 무엇인가요?
호스트 데이터는 홈 서버의 파일 시스템에 저장됩니다. 컨테이너 앱 데이터는 컨테이너 내부, Docker 관리 볼륨 또는 컨테이너에 마운트된 호스트 폴더에 저장될 수 있습니다. 화면에 표시되는 폴더 경로가 호스트와 컨테이너 계층에서 같은 위치를 뜻하는 것은 아니므로, 파일을 수정하기 전에 마운트와 앱 데이터 위치를 확인해야 합니다.
Hermes Agent에 권한 오류가 표시되는 이유는 무엇인가요?
권한 오류는 앱 사용자에게 필요한 파일이나 폴더를 읽거나 쓸 권한이 없다는 뜻인 경우가 많습니다. 파일이 root 사용자로 생성되었거나, 마운트된 폴더의 소유자가 잘못 설정되었거나, 컨테이너가 예상과 다른 사용자로 실행 중일 때 이런 문제가 발생할 수 있습니다. 광범위하게 권한을 변경하기 전에 런타임 계층, 컨테이너 사용자, 앱 데이터 경로, 파일 소유권을 확인하세요.
Telegram 봇이 응답하지 않는 이유는 무엇인가요?
Telegram 봇이 응답하지 않는 이유는 토큰이 잘못되었거나, 사용자 ID가 허용되지 않았거나, 게이트웨이를 다시 시작하지 않았거나, 컨테이너가 Telegram API에 연결할 수 없거나, 그룹 채팅 권한이 메시지를 차단하기 때문일 수 있습니다. 그룹 채팅과 관련된 변수를 줄일 수 있도록 먼저 비공개 채팅에서 테스트하세요. 그런 다음 로그에서 토큰, 네트워크 또는 권한 오류를 확인하세요.
Hermes Agent를 인터넷에 직접 노출해도 되나요?
셀프 호스팅 에이전트를 공개 인터넷에 직접 노출하는 것이 기본적으로 최선의 방법은 아닙니다. 메시징 봇이나 게이트웨이는 도구, 모델 접근 권한, 경우에 따라 로컬 런타임 작업까지 연결할 수 있으므로 접근을 제한해야 합니다. 공개 노출을 고려하기 전에 비공개 접근 방식을 사용하고, 강력한 인증 정보를 설정하고, 허용 목록을 적용하며, 권한을 보수적으로 설정하세요.
지원 및 팁
더 읽어보기

Transformers에서 커뮤니티 모델을 불러오기 전에 확인할 사항
Transformers Jinja 샌드박스 업데이트를 활용해 모델의 출처, 채팅 템플릿, 원격 코드, 직렬화된 가중치, 격리된 첫 실행을 검토하세요.

Mirage를 로컬에서 실행: 한 장의 이미지로 OCR 및 객체 감지
Cactus Compute의 소형 로컬 비전 모델을 사용해 보고, 실제 입력으로 OCR 및 객체 추출을 검증하며, 메모리, 언어 및 개인정보 보호의 한계를 파악해 보세요.

홈 서버에서 Open WebUI 코딩 에이전트 예약 실행하는 방법
Open WebUI에서 보고 전용 코딩 에이전트 자동화를 설정하고, 터미널과 작업 공간을 선택한 다음 권한, 로그 및 오류 복구를 확인하세요.



