5.1. Hermes 설정¶

Hermes는 Backend.AI GO의 컨테이너 기반 자율 에이전트 런타임입니다. 설정 마법사는 에이전트를 실행하기까지 7단계를 안내합니다. Hermes는 컨테이너 내에서 실행되므로 호스트에는 아무것도 설치되지 않습니다.

사전 요구 사항¶

• Docker Desktop (macOS, Windows, Linux) 또는 Apple Container (macOS arm64)
• Backend.AI GO에 최소 하나의 모델이 로드되어 있어야 합니다 (5단계 — LLM 브리지에서 필요).
• 첫 실행 시 Hermes 이미지를 가져오기 위한 인터넷 연결

마법사 열기¶

1. Backend.AI GO를 엽니다.
2. 왼쪽 사이드바에서 Autonomous Agents를 클릭합니다.
3. Set up Hermes를 클릭합니다 (Hermes가 이미 목록에 있는 경우 프로바이더 카드 클릭).

마법사가 열리고 1단계부터 시작합니다. 도중에 닫더라도 다시 열면 동일한 단계에서 재개됩니다.

마법사 단계¶

1단계 — 런타임 확인¶

마법사가 지원되는 컨테이너 런타임(Docker 또는 Apple Container)이 설치되어 있고 응답하는지 확인합니다. 런타임이 없는 경우 Docker Desktop 다운로드 페이지 링크가 표시됩니다.

이 단계에서 오류가 표시되면:

• Docker Desktop이 실행 중인지 확인합니다 (메뉴 바 또는 작업 표시줄의 고래 아이콘 확인).
• Linux에서는 사용자가 docker 그룹에 속해 있는지 확인합니다 (sudo usermod -aG docker $USER, 이후 로그아웃 후 재로그인).
• Apple Silicon에서는 Docker Desktop 대신 Apple Container를 설치할 수도 있습니다.

2단계 — 이미지 가져오기¶

레지스트리에서 Hermes 컨테이너 이미지를 가져옵니다. 레이어별 다운로드 진행 상황을 나타내는 프로그레스 바가 표시됩니다.

이 단계는 멱등성이 있습니다 — 이미지가 이미 최신 상태라면 재다운로드 없이 즉시 완료됩니다.

가져오기가 실패하면:

• 인터넷 연결을 확인합니다.
• 기업 프록시를 사용하는 경우 Docker Desktop → 설정 → 리소스 → 프록시에서 Docker의 프록시 설정을 구성합니다.

3단계 — 프로필 생성¶

Hermes는 각 에이전트의 설정, 메모리, 채널을 프로필이라는 이름의 단위로 관리합니다. 여기에 프로필 이름을 입력합니다.

이름 규칙: 소문자, 숫자, 하이픈, 밑줄; 1~64자; 문자 또는 숫자로 시작. 예: my-assistant.

마법사가 <앱 데이터>/hermes/profiles/<이름>/ 아래에 프로필 디렉토리를 생성합니다.

4단계 — 채널 선택¶

이 프로필이 연결할 메시징 플랫폼(Slack, Telegram 등)을 선택합니다. 모두 선택하지 않고 나중에 Hermes 대시보드에서 채널을 추가할 수도 있습니다.

5단계 — LLM 브리지¶

LLM 브리지는 Hermes가 추론에 사용할 모델을 알려줍니다. 마법사가 Backend.AI GO에 현재 로드된 모델을 Hermes 데몬에 자동으로 동기화합니다.

마법사는 Hermes가 호출할 라우터 기본 URL을 표시하고 각 모델에 동기됨/대기 중 배지를 표시합니다. 동기화가 성공하면 모든 배지가 녹색으로 바뀝니다.

모델 목록이 비어 있으면 Models 페이지로 이동하여 최소 하나의 모델을 로드한 후 마법사로 돌아옵니다.

6단계 — Claw 마이그레이션 (선택 사항, 자동으로 건너뛸 수 있음)¶

~/.openclaw에 기존 Claw 설정이 있는 경우 이 단계에서 메모리, 스킬, 채널 바인딩을 새 Hermes 프로필로 마이그레이션할 수 있습니다.

마법사가 먼저 드라이 런(dry-run) 을 실행하여 마이그레이션될 항목을 미리 보여줍니다. 미리 보기를 검토하고 Apply를 클릭하여 확인합니다.

다음 조건이 모두 충족되면 이 단계는 자동으로 건너뜁니다.

• Claw 게이트웨이가 실행 중이지 않고,
• Claw 설정 디렉토리가 감지되지 않으며,
• Claw 프로바이더에 관리되는 채널이 없는 경우

마이그레이션은 비파괴적입니다. Claw 설정은 읽기 전용으로 마운트되며 Claw 쪽에서는 아무것도 삭제되지 않습니다.

7단계 — 완료¶

마법사가 설정된 내용을 요약하고 Hermes 에이전트 대시보드로 이동하는 Open dashboard 버튼을 제공합니다.

설정 후¶

• Hermes 게이트웨이는 Backend.AI GO가 시작될 때 자동으로 시작됩니다.
• Autonomous Agents 페이지를 열어 게이트웨이 상태, 채널, 연결된 모델을 확인합니다.
• 채널 자격 증명이나 모델 할당을 변경하려면 Hermes 대시보드를 사용하거나 관련 마법사 단계를 다시 실행합니다.

문제 해결¶

마법사가 "런타임 확인" 단계에서 멈춤¶

컨테이너 런타임에 접근할 수 없습니다. 일반적인 원인:

• Docker Desktop이 실행 중이지 않습니다. 응용 프로그램 폴더(macOS/Windows)에서 시작하거나 systemctl start docker(Linux)를 실행합니다.
• Linux에서 /var/run/docker.sock 소켓에 접근할 수 없습니다. 임시 수정으로 sudo chmod 666 /var/run/docker.sock을 실행하거나, 영구 수정으로 docker 그룹에 자신을 추가합니다.

이미지 가져오기가 "manifest unknown" 오류로 실패¶

고정된 Hermes 이미지 태그가 레지스트리에서 제거되었을 수 있습니다. Backend.AI GO를 최신 버전으로 업그레이드하면 올바른 태그가 참조됩니다.

프로필 생성이 "invalid name" 오류로 실패¶

프로필 이름은 ^[a-z0-9][a-z0-9_-]{0,63}$ 형식이어야 합니다. 대문자, 공백, -와 _ 이외의 특수 문자는 사용할 수 없습니다.

LLM 브리지에 "No models loaded"가 표시됨¶

5단계에 도달하기 전에 Models 페이지에서 최소 하나의 모델을 로드합니다. 브리지는 단계가 표시될 당시 로드된 모델을 동기화합니다.

마이그레이션 단계에서 설정 없음 오류가 표시됨¶

마법사가 CLAW_CONFIG_NOT_FOUND를 보고했습니다. 이는 ~/.openclaw 경로가 존재하지 않거나 디렉토리가 아님을 의미합니다. Claw를 사용해 본 적이 없다면 Skip을 클릭하여 마이그레이션 없이 진행합니다.