튜토리얼 7: 설정 파일

돌아오신 것을 환영합니다, 에이전트 조련사 여러분! 이번 튜토리얼에서는 Hermes의 핵심인 설정 파일에 대해 깊이 파고들어 보겠습니다. YAML과 환경 변수의 바다에서 길을 잃은 적이 있다면 걱정 마세요—최대한 고통 없이 만들어 드리겠습니다.

Hermes의 본거지

모든 것은 ~/.hermes/에 저장됩니다. 에이전트의 아파트라고 생각하면 됩니다. 내부 구조는 다음과 같습니다:

~/.hermes/
├── config.yaml     # 설정 (모델, 터미널, TTS, 압축 등)
├── .env            # API 키와 비밀 정보
├── auth.json       # OAuth 제공업체 자격 증명 (Nous Portal 등)
├── SOUL.md         # 기본 에이전트 정체성 (시스템 프롬프트의 슬롯 #1)
├── memories/       # 영구 메모리 (MEMORY.md, USER.md)
├── skills/         # 에이전트가 만든 스킬 (skill_manage 도구로 관리)
├── cron/           # 예약 작업
├── sessions/       # 게이트웨이 세션
└── logs/           # 로그 (errors.log, gateway.log — 비밀 정보는 자동 삭제 처리)

가장 쉬운 방법: 원커맨드 설정

자세한 내용에 들어가기 전에, 프로 팁을 하나 드리겠습니다: hermes setup --portal을 실행하세요. OAuth 한 번으로 모델 제공업체와 Tool Gateway 도구 4개를 모두 얻을 수 있으며, YAML 파일 하나도 건드릴 필요가 없습니다. Portal 구독자는 토큰 과금 제공업체에서 10% 할인도 받을 수 있습니다. 게으른 방법으로 시작하기에 딱 좋고, 우리는 그 방법을 사랑합니다.

설정 관리하기

Hermes는 설정 관리를 위한 완전한 도구 모음을 제공합니다. 매일 사용하게 될 명령어는 다음과 같습니다:

hermes config              # 현재 설정 보기
hermes config edit         # 편집기에서 config.yaml 열기
hermes config get KEY      # 해석된 값 출력
hermes config set KEY VAL  # 특정 값 설정
hermes config unset KEY    # 사용자가 설정한 값 제거
hermes config check        # 누락된 옵션 확인 (업데이트 후)
hermes config migrate      # 누락된 옵션을 대화형으로 추가

실용적인 예시를 몇 가지 보여드리겠습니다:

hermes config get model
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config unset terminal.backend
hermes config set OPENROUTER_API_KEY sk-or-...  # .env에 저장됨

마법 같은 기능: hermes config set은 값을 자동으로 올바른 파일에 라우팅합니다. API 키는 .env로, 나머지는 모두 config.yaml로 이동합니다. 더 이상 헷갈릴 필요가 없습니다!

충돌이 발생하면 무엇이 우선할까요?

Hermes는 다음 순서로 설정을 해석합니다 (높은 우선순위부터):

CLI 인자 — hermes chat --model anthropic/claude-sonnet-4 같은 것
~/.hermes/config.yaml — 기본 설정 파일
~/.hermes/.env — 비밀 정보용 (API 키, 토큰, 비밀번호)
내장 기본값 — 안전한 하드코딩 값

경험 법칙: 비밀 정보는 .env에 넣으세요. 나머지는 모두 config.yaml에 넣습니다. 둘 다 설정된 경우, 비밀 정보가 아닌 설정은 config.yaml이 우선합니다.

환경 변수 치환

config.yaml에서 ${VAR_NAME} 구문을 사용하여 환경 변수를 참조할 수 있습니다:

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

여러 참조도 가능합니다: url: "${HOST}:${PORT}". 변수가 설정되지 않은 경우, 플레이스홀더는 그대로 유지되고 경고가 로그에 기록됩니다. Cursor 스타일의 ${env:VAR_NAME} 구문도 작동하므로, Cursor나 Claude 설정에서 스니펫을 수정 없이 복사할 수 있습니다.

제공업체 타임아웃

제공업체별, 모델별로 타임아웃을 설정할 수 있습니다:

providers:
  some-provider:
    request_timeout_seconds: 600
    models:
      some-model:
        timeout_seconds: 300

또한 스트리밍이 아닌 오래된 호출을 감지하기 위한 stale_timeout_seconds도 있습니다. 이러한 설정은 기존의 HERMES_API_TIMEOUT 및 HERMES_API_CALL_STALE_TIMEOUT 환경 변수를 재정의합니다.

런타임 제한

장기 실행 서버 표면(게이트웨이, hermes serve --isolated)의 경우 파일 디스크립터 제한을 설정할 수 있습니다:

runtime:
  nofile_soft_limit: 4096

기본값은 4096입니다. 0, false 또는 null로 설정하면 조정이 비활성화됩니다.

업데이트 동작

업데이트 설정은 config.yaml의 updates 아래에 있습니다:

updates:
  pre_update_backup: quick

마무리

설정 투어는 여기까지입니다! 기억하세요: 쉬운 길은 hermes setup --portal, 빠른 변경은 hermes config set, 비밀 정보는 .env에 보관. 에이전트가 감사할 것입니다.

다음 튜토리얼에서는 AI 제공업체와 좋아하는 모델을 연결하는 방법을 살펴보겠습니다. 계속 지켜봐 주세요!