메인 콘텐츠로 건너뛰기

​
1. 제품 소개

Hermes Agent는 Nous Research의 오픈소스 셀프 호스팅 AI Agent입니다. 터미널 대화, 영구 메모리, 스킬, 메시징 연동을 지원합니다. GravitexAI 제공자를 설정하면 계정에서 사용할 수 있는 GPT, Claude, DeepSeek 등의 모델을 이용할 수 있습니다.

영구 메모리

세션 간 선호와 작업 맥락을 유지합니다.

스킬 재사용

작업 경험을 재사용 가능한 Skill로 정리합니다.

여러 채널

CLI 또는 메시지 게이트웨이로 같은 Agent를 사용합니다.

여러 프로토콜

모델에 맞게 Responses, Anthropic Messages, Chat Completions를 선택합니다.
2026년 10월 19일 확인한 공식 제공자 문서를 기준으로 업데이트했습니다. 이 페이지는 CLI와 파일 설정을 다룹니다. GUI는 Hermes Agent Desktop App을 참고하세요.

​
2. 실행 환경

  • Linux, macOS, Windows 네이티브 또는 WSL2. 지원 범위는 공식 설치 문서를 확인하세요.
  • POSIX 설치 스크립트에는 Git, curl, tar, SHA-256 도구가 필요합니다. 런타임 의존성은 설치 프로그램이 관리합니다.
  • Android / Termux는 별도 설치 안내를 사용하세요. 데스크톱/서버 스크립트를 그대로 적용하지 마세요.

​
3. 사전 조건

  • GravitexAI 콘솔에서 생성한 API 키(sk-xxxxxxxxxx).
  • 계정에서 사용 가능하고 도구 호출을 지원하는 모델. 모델 목록을 확인하세요.
컨텍스트 창은 64,000토큰 이상이어야 합니다. 모델과 채널의 실제 제한을 사용하고, 제한을 우회하려고 값을 부풀리지 마세요.

​
4. 설치

터미널을 다시 열거나 셸에 맞게 source ~/.zshrc 또는 source ~/.bashrc를 실행합니다.
기존 설치는 먼저 hermes update를 실행한 뒤 설정하세요.

​
5. GravitexAI 설정

​
1단계: 활성 설정 파일 확인

Linux/macOS 기본 데이터 경로는 ~/.hermes/, Windows 네이티브 스크립트 설치는 %LOCALAPPDATA%\hermes\입니다. HERMES_HOME이나 다른 설치 방식을 사용했다면 실제 경로를 따릅니다. hermes config edit로 활성 파일을 열 수 있습니다.

​
2단계: API 키 저장

자리표시자를 실제 키로 바꿉니다.
키는 활성 데이터 디렉터리의 .env에 저장됩니다. 아래 YAML은 key_env: GRAVITEX_API_KEY로 참조하므로 키를 YAML에 반복 입력할 필요가 없습니다.

​
3단계: 사용자 지정 제공자 추가

config.yaml에 다음을 추가하거나 병합합니다. 기존 providers 또는 model 블록이 있다면 그 블록을 수정하세요. 같은 최상위 키를 중복 생성하지 마세요.
모델 ID는 예시입니다. 계정에서 사용할 수 있는 ID로 바꾸세요. 불필요한 제공자는 삭제해도 되지만 기본 제공자를 지웠다면 model.provider와 model.default도 함께 수정합니다.
프로토콜과 모델은 일치해야 합니다. Claude 네이티브 주소에는 /v1이나 /anthropic을 붙이지 마세요. Claude를 Responses 제공자에 넣으면 안 됩니다. Hermes에서 Responses의 설정값은 codex_responses입니다.
새 형식은 providers 매핑입니다. 이전 custom_providers 목록도 호환되며 업데이트 시 마이그레이션됩니다. 제공자 항목에서는 base_url 대신 api(기존 이름도 허용), model 대신 default_model, api_mode 대신 transport를 사용합니다. 주 모델은 계속 model.default를 사용합니다.

​
4단계: 기본 제공자 명시적으로 선택

제공자 등록만으로 주 모델이 선택되지는 않습니다. 기존 값이 model.provider: auto라면 실행합니다.
Claude를 기본값으로 사용하려면 다음과 같이 설정합니다.
기존 model 블록에서 다른 제공자를 가리키는 base_url, api_mode, api_key 재정의 값을 정리하세요. 키는 제공자의 key_env로 참조합니다. 저장 후 새 세션을 시작합니다.

​
대화형 설정 방법

터미널에서 hermes model을 실행하고 Custom endpoint를 선택합니다. 위 표에 맞게 URL, 키, 모델, API mode를 입력합니다. 컨텍스트 길이는 자동 감지를 위해 비워 둘 수 있으며 직접 지정할 때는 채널의 실제 값을 사용해야 합니다. hermes model은 제공자 추가/설정용, 세션 안의 /model은 이미 설정된 모델 전환용입니다. 공식 제공자 안내를 참고하세요.

​
6. 시작 및 검증

먼저 간단한 메시지로 인증, 모델, 프로토콜 오류가 없는지 확인한 뒤 도구 작업을 시도합니다. 세션에서 제공자와 모델을 전환하는 예시입니다.
원하는 모델이 선택되고 응답이 오며 간단한 도구 호출까지 성공해야 합니다. hermes doctor는 설정과 의존성 진단용이며 실제 API 검증을 대신하지 않습니다.

​
7. 보조 모델

컨텍스트 압축, 이미지 분석, 제목 생성 등에 별도 모델을 지정할 수 있습니다. 기본 auto는 주 모델을 우선 사용하므로 처음에는 유지해도 됩니다. 다른 제공자를 지정하려면 추가합니다.
보조 모델도 해당 작업을 지원해야 합니다. 이미지 분석에는 시각 입력 모델을 선택하세요. 자세한 내용은 공식 모델 설정을 참고하세요.

​
8. 메시징 연결

터미널 검증 후 Telegram, Discord, Slack 등을 설정합니다.
run은 포그라운드 실행으로 초기 확인이나 WSL2에 적합합니다. Linux/macOS에서 백그라운드 서비스를 설치하려면 다음을 사용합니다.
플랫폼 토큰과 권한은 마법사에서 설정합니다. 공식 메시징 문서를 참고하세요.

​
9. 자주 사용하는 명령

스킬, MCP, 실행 백엔드는 공식 설정 문서를 참고하세요. 터미널 백엔드는 terminal.backend로 설정합니다.

​
10. 문제 해결

활성 데이터 폴더의 .env에 유효한 GRAVITEX_API_KEY가 있는지, 제공자의 key_env와 정확히 일치하는지 확인하세요. 계정의 키 상태와 모델 권한도 확인합니다.
GPT는 codex_responses + https://api.gravitex.ai/v1, Claude는 anthropic_messages + https://api.gravitex.ai, Chat Completions는 chat_completions + https://api.gravitex.ai/v1입니다. 기본 주소에 전체 요청 경로를 덧붙이지 마세요.
모델 목록에서 정확한 ID를 복사하세요. 프로토콜이 바뀌면 모델 이름뿐 아니라 제공자도 함께 바꿉니다.
실제로 64,000토큰 이상을 지원하는지 확인하세요. 감지가 틀리면 model.context_length 또는 제공자의 모델별 context_length를 채널 실제 값으로 설정합니다. 이는 컨텍스트 창이며 단일 응답 출력 한도가 아닙니다.
키나 providers 항목 저장만으로 제공자가 선택되지는 않습니다. 4단계에 따라 auto를 custom:gravitex-gpt 또는 custom:gravitex-claude로 바꾸고 model.default도 설정한 뒤 새 세션을 만드세요.
hermes config edit로 활성 파일, HERMES_HOME, 프로필을 확인합니다. 충돌하는 model.base_url, model.api_mode를 정리하고 hermes model로 제공자를 선택한 뒤 새 세션을 시작하세요. 메시징 게이트웨이는 hermes gateway restart로 재시작합니다.

​
11. 관련 자료