초보자를 위한 AI 에이전트 서버 운영 가이드
리눅스를 몰라도 VPS에 Hermes를 설치하고 Codex로 운영하는 방법
이 글의 목표는 “리눅스 명령어를 잘 모르는 사람도” Hostinger VPS에 Hermes 에이전트를 설치하고, Codex를 이용해 SSH로 접속해 운영, 모니터링, 오류 해결까지 할 수 있게 만드는 것입니다.
1. 이 글은 누구를 위한 글인가
VPS, SSH, Docker, Linux라는 단어가 낯선 분들도 많습니다. 하지만 AI 에이전트를 제대로 운영하려면 결국 “내 컴퓨터가 꺼져 있어도 계속 일하는 원격 작업자”가 필요합니다. 그 원격 작업자가 Hermes이고, 그 Hermes가 사는 집이 VPS입니다.
이 글은 서버 전문가를 위한 글이 아닙니다. 오히려 서버를 잘 모르는 분들이 Codex를 조력자로 삼아 원격 서버에 Hermes를 설치하고 운영하는 흐름을 이해하도록 돕는 글입니다.
2. 왜 Codex가 필요한가
VPS를 구매하면 보통 이런 정보를 받습니다.
- 서버 IP 주소
- SSH 사용자 이름, 보통
root - root 비밀번호 또는 SSH key
- 운영체제, 예를 들어 Ubuntu 24.04
문제는 그 다음입니다. 접속은 했는데 무엇을 입력해야 할지 모릅니다. Docker 설치, Hermes 설치, 환경변수 설정, Telegram bot token 등록, 로그 확인, 재시작 같은 작업이 모두 리눅스 명령어로 보이기 때문입니다.
Codex가 필요한 이유는 여기에 있습니다. Codex는 단순한 챗봇이 아니라, SSH로 원격 VPS에 접속해 명령을 실행하고 결과를 읽고 다음 조치를 판단할 수 있는 운영 파트너가 됩니다.
기존 방식
사용자가 명령어를 검색하고, 복사하고, 실패하면 다시 검색합니다.
Codex 방식
사용자가 목표를 말하면 Codex가 필요한 명령어를 실행하고 결과를 분석합니다.
내 Hostinger VPS는 Ubuntu 서버입니다.
SSH 접속 정보는 root@서버IP 입니다.
이 VPS에 Hermes를 Docker 기반으로 설치하고,
Telegram bot으로 사용할 수 있게 설정해 주세요.
설치 후에는 상태 확인, 로그 확인, smoke test까지 해 주세요.3. 준비물은 딱 세 가지
초보자에게 가장 중요한 것은 준비물을 단순하게 이해하는 것입니다. Hermes 설치를 시작하기 전에 아래 세 가지만 있으면 됩니다.
| 준비물 | 설명 | 예시 |
|---|---|---|
| VPS 서버 | Hostinger에서 만든 Ubuntu VPS | Ubuntu 24.04 |
| SSH 접속 정보 | Codex가 서버에 들어가기 위한 주소 | ssh root@123.123.123.123 |
| Telegram bot token | Hermes가 Telegram 메시지를 받기 위한 토큰 | 123456:ABC... |
4. VPS에 SSH로 접속하는 방법
Hostinger VPS 화면에는 보통 ssh root@서버IP 형식의 접속 정보가 표시됩니다. 이 정보만 있으면 Codex에게 접속을 맡길 수 있습니다.
비밀번호 접속
처음에는 root 비밀번호로 접속할 수 있습니다. 하지만 장기 운영에는 SSH key 방식이 더 안전합니다.
아래 VPS에 SSH로 접속 가능한지 확인해 주세요.
서버: root@서버IP
운영체제: Ubuntu
접속 방식: root password
접속에 성공하면 hostname, uptime, docker 설치 여부를 확인해 주세요.SSH key 접속
Hostinger의 SSH keys 화면에 내 Mac의 공개키를 등록하면 이후에는 비밀번호 없이 접속할 수 있습니다. Codex 입장에서는 이 방식이 훨씬 안정적입니다.
내 Mac의 SSH 공개키를 확인해서 알려주세요.
Hostinger VPS의 SSH keys 메뉴에 등록할 수 있는 형식으로 보여주세요.5. Codex에게 Hermes 설치를 맡기는 방법
초보자는 설치 명령어를 모두 알 필요가 없습니다. 대신 Codex에게 설치 기준을 명확히 알려주면 됩니다. 중요한 기준은 Docker 기반 설치, 데이터 볼륨 보존, systemd 자동 실행입니다.
Hostinger VPS에 Hermes를 Docker 기반으로 설치해 주세요.
조건:
1. Ubuntu 서버에 Docker와 Docker Compose가 없으면 설치해 주세요.
2. Hermes 데이터는 /docker/hermes-agent/data 에 보존되게 해 주세요.
3. Hermes workspace는 /docker/hermes-agent/data/workspace 로 만들어 주세요.
4. 컨테이너 내부에서는 /opt/data/workspace 로 접근되게 해 주세요.
5. Hermes gateway는 systemd 서비스로 자동 실행되게 해 주세요.
6. 설치 후 docker ps, systemctl status, 로그 확인, smoke test를 실행해 주세요.
7. 설치 과정과 결과를 초보자도 이해할 수 있게 요약해 주세요.이 요청을 받은 Codex는 서버 상태를 확인하고, 필요한 패키지를 설치하고, Docker compose 파일을 만들고, 컨테이너를 띄운 뒤 상태를 점검할 수 있습니다.
Docker를 쓰는 이유
Docker는 Hermes를 서버 전체와 분리된 실행 환경 안에 넣어줍니다. 직접 설치보다 재설치, 이전, 복구, 격리가 쉽습니다.
VPS
└── Docker
└── Hermes container
└── /opt/data/workspace6. Telegram 설정을 맡기는 방법
Hermes를 실사용하려면 Telegram bot token과 home channel 설정이 필요합니다. Telegram bot token은 BotFather에서 만들고, Hermes 설정에 넣어야 합니다.
Hermes가 Telegram bot으로 동작하도록 설정해 주세요.
Telegram bot token은 제가 따로 입력하겠습니다.
home channel 또는 내 Telegram chat id도 확인해 주세요.
설정 후에는 Hermes gateway를 재시작하고,
Telegram 연결 로그가 정상인지 확인해 주세요.설정이 끝난 뒤에는 로그에서 다음과 같은 흐름이 보여야 합니다.
Connecting to telegram...
Telegram menu registered
Connected to Telegram
Gateway running7. LLM 모델 설정 변경하기
Hermes는 내부 설정에 따라 어떤 LLM 모델을 사용할지 결정합니다. 모델을 바꾸고 싶을 때도 사용자가 설정 파일 위치를 몰라도 됩니다. Codex에게 현재 설정을 찾아서 변경해 달라고 요청하면 됩니다.
현재 Hermes가 어떤 LLM provider와 model을 쓰는지 확인해 주세요.
설정 파일 위치를 찾아서 보여주고,
모델을 원하는 값으로 바꿔 주세요.
원하는 모델:
provider: openai 또는 사용 중인 provider
model: 원하는_모델명
변경 후 Hermes gateway를 재시작하고 smoke test까지 해 주세요.모델 변경 후에는 반드시 smoke test를 해야 합니다. 모델 이름이 틀렸거나 인증 정보가 잘못되어 있으면 Hermes가 메시지를 받아도 답을 못할 수 있습니다.
hermes -z "Reply with exactly ok"8. 상태 확인과 모니터링
설치보다 중요한 것은 운영입니다. AI 에이전트가 멈췄는지, Telegram 연결이 살아 있는지, 디스크가 꽉 차지는 않았는지 확인할 수 있어야 합니다.
VPS Hermes 상태를 점검해 주세요.
확인할 항목:
1. docker ps
2. hermes gateway systemd 상태
3. workspace preview 서버 상태
4. 최근 gateway.log 오류
5. 디스크 사용량
6. 메모리 사용량
7. Hermes smoke test
문제가 있으면 원인과 조치 방법을 알려주세요.Codex가 내부적으로 확인하는 대표 명령은 아래와 같습니다. 사용자가 외울 필요는 없지만, 무엇을 확인하는지 이해하면 운영 감각이 생깁니다.
docker ps
systemctl is-active hermes-gateway.service
tail -120 /opt/data/logs/gateway.log
df -h
free -h9. 오류가 났을 때 Codex로 해결하기
Hermes 운영 중 가장 자주 만나는 문제는 Telegram 연결 문제, LLM API 오류, 컨테이너 중단, 파일 권한 문제, 브라우저 렌더링 도구 누락입니다. 이때도 “어떤 명령어를 쳐야 하지?”가 아니라 Codex에게 증상 중심으로 말하면 됩니다.
상황 1: Telegram 메시지에 답이 없다
Hermes가 Telegram 메시지에 답하지 않습니다.
Telegram 연결 상태, gateway 로그, polling conflict 여부,
bot token 설정 문제를 확인해 주세요.
필요하면 Hermes gateway를 안전하게 재시작해 주세요.상황 2: LLM API 오류가 난다
Hermes 로그에서 LLM API 호출 오류를 찾아주세요.
provider, model 이름, 인증 정보, rate limit, timeout 문제 중 무엇인지 구분해 주세요.
설정 변경이 필요하면 변경 전후 차이를 설명하고 적용해 주세요.상황 3: 파일 생성은 됐는데 다운로드가 안 된다
Hermes가 만든 파일 다운로드가 안 됩니다.
/opt/data/workspace 안에 파일이 있는지,
VPS 호스트의 workspace 경로와 연결되어 있는지,
preview 서버가 8090 포트에서 실행 중인지 확인해 주세요.상황 4: 브라우저 렌더링이 안 된다
Hermes 작업 중 Chrome 또는 Chromium이 없어서 브라우저 렌더링이 실패했습니다.
VPS 호스트와 Hermes Docker 컨테이너 내부에 브라우저가 설치되어 있는지 확인해 주세요.
없으면 headless 렌더링이 가능하도록 설치하고,
HTML 렌더링과 screenshot 생성 테스트까지 해 주세요.상황 5: 컨테이너가 죽었다
Hermes 컨테이너가 중단된 것 같습니다.
docker ps -a, docker logs, systemctl status를 확인해서
왜 중단됐는지 분석하고, 데이터 손실 없이 복구해 주세요.10. 파일 공유 폴더 운영
Telegram으로 파일을 계속 보내고 받는 것은 번거롭습니다. 그래서 Mac의 로컬 폴더와 VPS의 Hermes workspace를 동기화하면 훨씬 편합니다.
Mac에서 보는 폴더:
~/Desktop/HermesShared
Hermes에게 알려줄 폴더:
/opt/data/workspace
VPS 호스트 실제 폴더:
/docker/hermes-agent-zte3/data/workspace중요한 점은 Hermes에게 Mac 경로를 알려주면 안 된다는 것입니다. Hermes는 Docker 컨테이너 안에서 실행되므로 /opt/data/workspace만 이해합니다.
공유 폴더에 있는 h-docx 폴더의 파일들을 확인해줘.
Hermes 기준 경로는 /opt/data/workspace/h-docx 이야.
작업 결과도 /opt/data/workspace에 저장해줘.동기화가 자동으로 돌고 있지 않다면 Mac에서 아래 동기화 명령을 실행하면 됩니다.
cd /Users/사용자이름/Desktop/vps
./hermes-shared-sync.sh once11. 보안과 운영 원칙
AI 에이전트는 파일을 만들고 명령을 실행할 수 있습니다. 그래서 편리하지만, 권한 관리가 중요합니다.
- 처음 접속 후에는 비밀번호보다 SSH key 방식을 사용합니다.
- root 비밀번호, Telegram bot token, API key는 절대 공개하지 않습니다.
- 공유 폴더 동기화에서 삭제 자동 전파는 신중하게 사용합니다.
- Hermes 데이터는 Docker 볼륨 또는 호스트 폴더에 보존되게 합니다.
- 문제가 생기면 바로 재설치하지 말고 로그부터 확인합니다.
- 설정 변경 후에는 항상 smoke test를 실행합니다.
마무리: AI 에이전트는 설치보다 운영이 중요하다
Hostinger VPS에 Hermes를 설치하는 일은 시작일 뿐입니다. 진짜 가치는 Codex를 통해 Hermes를 지속적으로 모니터링하고, 문제가 생겼을 때 로그를 읽고, 모델 설정을 바꾸고, Telegram 연결을 복구하고, 파일 공유 구조를 개선하는 운영 과정에서 나옵니다.
리눅스 명령어를 모두 외울 필요는 없습니다. 대신 Codex에게 정확히 요청하는 방법을 익히면 됩니다. 앞으로의 AI 활용은 단순히 “AI에게 질문하는 것”에서 “내 AI 작업 인프라를 운영하는 것”으로 이동할 것입니다.
감사합니다. 좋은 하루 되세요.
답글삭제