Hermes Agent 설치 및 명령어 운용 백서

목차

1. 제품 구조와 설치 전 이해

Hermes Agent는 단순 채팅 프로그램이 아니라, 대화형 CLI, 메시징 게이트웨이, 도구 실행 계층, 메모리 저장소, 스킬 시스템, 스케줄러를 하나의 운용 프레임워크로 통합한 자율형 에이전트 런타임입니다. 따라서 설치는 애플리케이션 하나를 올리는 작업이 아니라, 런타임 환경과 도구 권한, 모델 연결 지점, 저장 디렉터리 구조를 함께 정렬하는 작업으로 이해하는 편이 정확합니다.

이 구조의 핵심은 세 가지입니다. 첫째, 사용자는 터미널에서 직접 대화하거나 Telegram·Discord 같은 외부 채널을 통해 원격 제어할 수 있습니다. 둘째, 에이전트는 세션 기억, 사용자 특성, 스킬 재사용을 통해 장기적인 작업 일관성을 확보합니다. 셋째, 크론 자동화와 백그라운드 작업을 통해 “필요할 때만 호출하는 모델”이 아니라 “계속 돌아가며 업무를 수행하는 운영 단위”로 확장할 수 있습니다.

2. 시스템 요구사항과 사전 점검

Hermes Agent는 Linux, macOS, WSL2, Android Termux에서 설치할 수 있으며, Windows 네이티브 환경은 권장되지 않습니다. 운영 안정성과 패키지 호환성을 고려하면, 실제 배포는 Linux 또는 macOS를 기준으로 잡고, Windows 사용자는 WSL2를 표준 환경으로 보는 편이 적절합니다.

설치 전에는 Python 3.11 계열, uv 패키지 관리 도구, Node.js 계열 의존성, 셸 환경 파일 반영 여부를 함께 점검해야 합니다. 특히 macOS에서는 Xcode Command Line Tools가 없으면 일부 의존성 설치 단계에서 중단될 수 있으므로, 사전 준비가 중요합니다.

3. 설치 방식별 절차

3-1. 권장 설치 방식

가장 빠른 방법은 공식 설치 스크립트를 사용하는 방식입니다. 이 방식은 플랫폼을 감지한 뒤 필요한 패키지를 설치하고, Hermes 실행 파일과 사용자 홈 디렉터리 기반 구성을 준비하는 흐름으로 설계되어 있습니다.

설치가 끝난 뒤 셸을 다시 로드하는 이유는 실행 경로와 환경 변수가 현재 세션에 즉시 반영되지 않을 수 있기 때문입니다. 설치 후 바로 명령이 인식되지 않으면 대부분 이 단계가 누락된 경우가 많습니다.

3-2. 수동 설치 방식

설치 과정을 세밀하게 통제해야 하거나, 사내 표준 저장소 정책 때문에 원라인 스크립트 사용이 어려운 경우에는 수동 설치가 적합합니다. 수동 설치는 저장소 클론, uv 준비, 가상환경 생성, 편집 모드 설치, 사용자 디렉터리 링크 구성 순서로 진행합니다.

수동 설치의 장점은 패키지 버전과 설치 위치를 통제할 수 있다는 점입니다. 반면 단점은 의존성 누락, 경로 반영 오류, 플러그인 추가 설치 누락 같은 초기 장애가 상대적으로 많이 발생한다는 점입니다.

3-3. 선택형 설치 확장

Hermes Agent는 전체 기능을 한 번에 설치할 수도 있지만, 메시징·크론·음성·MCP 등 필요한 확장만 선별 설치하는 방식도 가능합니다. 이 구조는 서버 역할을 분리하거나 공격면을 줄여야 하는 환경에서 특히 유용합니다.

3-4. 업데이트와 마이그레이션

기존 OpenClaw 사용자는 데이터 이전 기능을 통해 설정, 메모리, 스킬, 일부 API 키를 가져올 수 있습니다. 전환 검증이 필요한 경우에는 실제 반영 전에 사전 시뮬레이션 방식으로 확인하는 것이 안전합니다.

4. 최초 실행과 기본 설정

설치 직후 권장되는 흐름은 진단, 모델 연결, 도구 확인, 세션 시작 순서입니다. 이 순서는 장애 원인을 빠르게 좁히는 데 유리하며, 실제로도 환경 이슈와 모델 연결 이슈를 분리해서 확인할 수 있게 해줍니다.

`hermes doctor`는 설치 상태, 설정 누락, 의존성 이상을 진단하는 명령입니다. `hermes model`은 사용할 LLM 제공자와 모델을 선택하는 설정 진입점입니다. `hermes tools`는 어떤 도구를 노출할지 제어하는 명령이며, 마지막 `hermes`는 실제 대화형 CLI를 시작합니다.

4-1. 모델 프로바이더 연결 원리

Hermes Agent는 특정 모델에 종속되지 않는 구조입니다. OpenAI 계열 엔드포인트, OpenRouter, Nous Portal, 자체 호스팅 API, 기타 호환 엔드포인트를 교체 가능한 추론 백엔드로 취급하기 때문에, 핵심은 모델 이름 자체보다도 프로바이더, 베이스 URL, 인증 키, 보조 모델 분리 전략을 어떻게 설정하느냐에 있습니다.

실무적으로는 메인 추론 모델과 보조 모델을 분리하는 전략이 중요합니다. 예를 들어 대규모 사고가 필요한 주 모델은 고성능 엔드포인트를 쓰고, 세션 검색, 요약 압축, 비전 추출처럼 상대적으로 가벼운 작업은 더 저렴하거나 빠른 모델로 분리하면 비용과 응답 속도를 동시에 최적화할 수 있습니다.

4-2. 설정 파일 운영 원칙

기본 원칙은 민감정보와 동작 설정을 분리하는 것입니다. API 키, 토큰, 비밀값은 환경 변수 또는 별도 비밀 저장 체계에 두고, 모델 라우팅이나 도구 활성화 같은 동작 설정은 `config.yaml` 중심으로 관리하는 편이 유지보수에 유리합니다.

이 방식은 금융권이나 내부감사 환경에서 특히 중요합니다. 운영 담당자와 보안 담당자의 권한을 분리할 수 있고, 설정 변경 이력과 비밀정보 접근 통제를 서로 다른 레이어에서 관리할 수 있기 때문입니다.

5. CLI 상위 명령 상세 해설

CLI 상위 명령은 Hermes Agent의 전역 설정과 실행 상태를 제어하는 관리 계층입니다. 즉, 아직 대화 세션에 들어가기 전 단계에서 시스템을 준비하고, 연결 구조를 조정하고, 상태를 확인하는 용도로 사용합니다.

5-1. 자주 쓰는 상위 명령 시퀀스

6. 세션 내부 슬래시 명령 전체 운용법

슬래시 명령은 대화 세션 안에서 즉시 동작하는 런타임 제어 계층입니다. 전역 명령이 시스템 설정과 시작을 담당한다면, 슬래시 명령은 현재 세션의 상태, 맥락, 도구, 표시 모드, 승인 정책을 실시간으로 바꾸는 제어 패널에 해당합니다.

6-1. 세션 관리 명령

6-2. 설정 명령

6-3. 퍼스널리티 명령

`/personality`는 응답 스타일을 프리셋으로 바꾸는 기능입니다. 간결형, 기술형, 교육형, 창의형 등 다양한 성격 프리셋이 제공되며, 실무 문서 작업에는 technical 또는 teacher 성향이 일반적으로 잘 맞습니다.

6-4. 도구 및 스킬 명령

6-5. 표시·상태·음성 명령

`/verbose`는 도구 실행 출력 레벨을 바꾸는 명령입니다. 운영 초기에는 verbose로 두어 내부 동작을 확인하고, 안정화 이후에는 new 또는 off로 낮춰 노이즈를 줄이는 방식이 효율적입니다.

`/usage`는 현재 세션의 토큰 소비량을 확인하는 명령이며, 장시간 세션 비용 관리에 직접적입니다. `insights`는 기간별 사용 통계를 분석하는 용도로 적합하며, 운영비 가시화와 사용자별 사용 패턴 파악에 활용할 수 있습니다.

6-6. 백그라운드 작업과 시스템 명령

`/background` 또는 `/bg`는 현재 대화를 유지한 채 별도 서브에이전트 작업을 병렬로 실행하는 기능입니다. 이 기능의 핵심 가치는 메인 세션의 문맥을 보존한 상태에서 장시간 태스크를 분리해 처리할 수 있다는 데 있습니다.

`/yolo`는 위험 명령 승인을 자동화하는 세션 한정 토글입니다. 실험 환경에서는 편리하지만, 운영 환경에서는 명령 승인 절차를 우회할 수 있으므로 통제 범위를 엄격히 제한해야 합니다.

7. 모델, 도구, 메모리, 스킬 운용 구조

7-1. 모델 전환 원리

모델 관련 명령은 두 층으로 이해하는 것이 좋습니다. `hermes model`은 전역 설정 수준에서 새로운 모델 제공자와 모델을 연결하는 절차이며, 세션 내부의 모델 전환 명령은 이미 준비된 모델 사이를 빠르게 스위칭하는 운용 계층에 가깝습니다.

즉, 최초 설정과 운영 중 전환을 분리해서 이해하면 혼선이 줄어듭니다. 전자는 “연결 구축”, 후자는 “즉시 선택 변경”입니다.

7-2. 도구 최소화 원칙

Hermes Agent는 다양한 도구를 붙일 수 있는 구조이지만, 실무에서는 필요한 도구만 노출하는 것이 기본 원칙입니다. 도구가 많을수록 유연성은 높아지지만, 오작동 가능성과 승인 범위, 로그 검토 부담도 함께 증가하기 때문입니다.

예를 들어 문서 요약과 질의응답 위주의 사용이라면 파일·검색·기본 셸만으로도 충분할 수 있습니다. 반면 웹 자동화, 브라우저 제어, 메시징 전송, 배치 스케줄까지 함께 열어두면 사실상 소형 자동화 플랫폼과 같은 책임 범위가 발생합니다.

7-3. 메모리와 세션 검색

Hermes의 메모리 구조는 단순 로그 저장과 다릅니다. 장기 기억, 사용자 프로필, 과거 세션 검색, 맥락 압축을 조합해 “과거 작업의 재사용 가능성”을 높이는 방향으로 설계되어 있습니다. 이 때문에 장기 프로젝트에서는 세션 제목 관리와 주기적 압축이 매우 중요합니다.

7-4. 스킬의 실무적 의미

스킬은 반복 작업 절차를 재사용 가능한 형태로 외부화한 운영 자산입니다. 한 번 잘 정의된 스킬은 신규 세션에서도 재활용할 수 있으므로, 결과적으로 프롬프트 재작성 비용과 운영자 개입량을 크게 줄여줍니다.

예를 들어 “장애 티켓 요약”, “배포 전 체크리스트 검증”, “로그 샘플 분류”, “일일 인프라 리포트 생성” 같은 루틴은 스킬화 대상이 됩니다. 실무 관점에서는 스킬을 곧 표준운영절차의 AI 실행 버전으로 볼 수 있습니다.

8. 메시징 게이트웨이와 원격 운용

Hermes Agent는 CLI뿐 아니라 다양한 메시징 플랫폼에서 동일한 에이전트를 제어할 수 있도록 게이트웨이 구조를 제공합니다. 이 구조의 장점은 에이전트는 서버에서 계속 실행되고, 사용자는 휴대폰이나 메신저로 그 에이전트와 상호작용할 수 있다는 점입니다.

실무적으로는 이 기능이 매우 중요합니다. 서버실이나 VPN 접속이 어려운 순간에도 Telegram 또는 Discord를 통해 상태를 확인하고, 정기 작업 결과를 수신하고, 필요한 승인만 원격으로 수행할 수 있기 때문입니다.

9. 크론 자동화와 정기 작업 설계

Hermes Agent의 크론 기능은 “정해진 시간에 프롬프트를 실행하는 AI 작업 스케줄러”로 이해하면 됩니다. 전통적인 crontab이 셸 명령을 예약 실행한다면, Hermes의 크론은 자연어 지시와 도구 조합을 예약 실행하는 형태에 가깝습니다.

이 구조는 매일 아침 장애 요약, 전일 로그 이상치 분석, 주간 리포트, 배포 후 상태 점검처럼 정기적으로 같은 사고 패턴이 필요한 업무에 특히 유리합니다. 결과는 파일로 저장하거나 메시징 플랫폼 채널로 보낼 수 있어 보고 체계 자동화에 적합합니다.

9-1. 금융권형 활용 예시

10. 실전 시나리오별 사용 예시

10-1. 설치 직후 점검 시나리오

목표는 정상 실행 여부와 모델 연결 여부를 최소 단계로 확인하는 것입니다. 가장 중요한 포인트는 장애 범위를 설치 문제와 모델 문제로 분리하는 것입니다.

이 흐름의 결과가 정상이라면, 설치와 추론 연결은 기본적으로 성립한 것입니다. 반대로 `doctor`는 정상인데 대화가 실패하면 모델 API, 인증 키, 베이스 URL 계층을 먼저 의심하는 것이 맞습니다.

10-2. 긴 프로젝트 분석 시나리오

장시간 분석에서는 세션을 무작정 이어가기보다, 제목 지정과 중간 저장, 컨텍스트 압축을 조합해야 합니다. 그래야 맥락이 길어져도 비용과 응답 왜곡을 관리할 수 있습니다.

10-3. 병렬 태스크 시나리오

메인 세션에서는 운영 전략을 정리하고, 백그라운드에서는 로그 분류 작업을 동시에 돌릴 수 있습니다. 이 패턴은 운영자가 한 화면에서 판단과 실행을 병행할 수 있게 해 준다는 점에서 효율이 높습니다.

10-4. Quick Commands 시나리오

Quick Commands는 LLM을 거치지 않고 즉시 셸 명령을 실행하는 기능입니다. 이 기능의 실무적 가치는 토큰을 소모하지 않고, 운영자가 자주 쓰는 점검 명령을 짧은 인터페이스로 표준화할 수 있다는 데 있습니다.

서버 관리, 서비스 상태 확인, 최근 로그 조회 같은 반복 작업은 Quick Commands로 표준화하면 매우 효율적입니다. 다만 재시작, 파일 삭제, 권한 변경처럼 영향도가 높은 명령은 승인 체계와 함께 설계하는 편이 필요합니다.

11. 장애 대응, 보안 통제, 운영 체크리스트

11-1. 대표 장애 유형

11-2. 운영 통제 원칙

첫째, 도구 최소화 원칙을 적용해야 합니다. 실제 업무에 필요하지 않은 도구는 비활성화하여 공격면과 오작동 범위를 줄여야 합니다. 둘째, 민감정보는 설정 파일과 분리해야 합니다. 셋째, 메시징 승인 플로우를 유지하여 원격 채널이 무제한 실행 경로가 되지 않도록 해야 합니다.

넷째, Quick Commands와 스킬은 표준운영절차 수준으로 검토한 뒤 배포해야 합니다. 다섯째, 크론 작업은 단순 반복만 맡기고, 파괴적 작업은 승인 단계를 둬야 합니다. 여섯째, 업데이트 전후에는 반드시 `doctor`와 핵심 시나리오 테스트를 수행해야 합니다.

11-3. 권장 운영 체크리스트