Hermes 설정¶

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

사전 요구 사항¶

• Docker: macOS와 Windows에서는 Docker Desktop, Linux에서는 기본 브리지를 사용하는 rootful Docker Engine. Apple Container는 아직 지원하지 않습니다. Apple Container에서 실행한 Hermes 컨테이너는 Backend.AI GO의 라우터에 연결할 수 없으므로 게이트웨이가 시작되지 않습니다.
• Backend.AI GO에 최소 하나의 모델이 실행 중이어야 합니다 (5단계 — LLM 브리지에서 필요).
• 첫 실행 시 Hermes 이미지를 다운로드하기 위한 인터넷 연결

마법사 열기¶

1. Backend.AI GO를 엽니다.
2. 왼쪽 사이드바에서 자율 에이전트를 클릭합니다.
3. Hermes Agent 프로바이더 카드를 클릭합니다.

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

마법사 단계¶

1단계 — 런타임 확인¶

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

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

• Docker Desktop이 실행 중인지 확인합니다 (메뉴 바 또는 작업 표시줄의 고래 아이콘 확인).
• Linux에서는 사용자가 docker 그룹에 속해 있는지 확인합니다 (sudo usermod -aG docker $USER, 이후 로그아웃 후 재로그인).
• Apple Silicon에서는 Hermes용으로 Docker Desktop을 사용하세요. Apple Container가 감지되어도 Hermes에서 지원하는 것은 아닙니다.

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 데몬에 자동으로 동기화합니다. 동기화할 때마다 게이트웨이의 현재 경로를 프로필의 config.yml에 기록하므로, 동기화하려면 Hermes 게이트웨이가 실행 중이어야 합니다.

Hermes는 라우터에 직접 연결하지 않고 자격 증명 프록시의 라우터 경로인 http://host.docker.internal:<proxy port>/router(기본 포트 3001)로 모델을 호출합니다. 게이트웨이를 시작하면 프록시가 실행 중이 아닐 때 프록시를 시작하고, 컨테이너의 AIGO_ROUTER_API_KEY에 cpt_ 토큰을 넣습니다. 프록시는 이 토큰을 모델 목록 조회와 채팅 완성 요청에만 받아들이며, 요청을 앱 자체의 라우터 키와 함께 로컬 소켓으로 라우터에 전달합니다. 따라서 라우터 리스너 설정을 기본값으로 두어도 Hermes가 동작하고, 라우터 키는 컨테이너에 들어가지 않습니다. 게이트웨이를 재시작하면 토큰이 새로 발급되고, 게이트웨이를 중지하면 토큰이 폐기됩니다. 컨테이너가 예기치 않게 종료되면 게이트웨이를 중지하거나 재시작하여 토큰을 폐기하세요. Windows처럼 소켓을 사용하지 않는 환경에서 라우터 포트가 바뀌면 게이트웨이를 재시작하세요.

마법사는 각 모델에 동기화됨/대기 중 배지를 표시합니다. 동기화가 성공하면 모든 배지가 녹색으로 바뀝니다.

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

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

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

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

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

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

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

7단계 — 완료¶

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

설정 후¶

• Hermes 게이트웨이는 Backend.AI GO가 시작될 때 자동으로 시작됩니다.
• 자율 에이전트 페이지를 열어 게이트웨이 상태, 채널, 연결된 모델을 확인합니다.
• 채널 자격 증명이나 모델 할당을 변경하려면 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}$ 형식이어야 합니다. 대문자, 공백, -와 _ 이외의 특수 문자는 사용할 수 없습니다.

게이트웨이가 시작되지 않음¶

Hermes가 모델에 연결할 경로가 없으면 게이트웨이 시작이 실패하고 컨테이너도 실행되지 않습니다.

모델 동기화에서 게이트웨이가 실행 중이 아니라고 표시됨¶

Hermes gateway is not running; start it before syncing models 오류는 게이트웨이가 실행 중이 아닐 때 동기화했다는 뜻입니다. 게이트웨이를 시작한 후 다시 동기화합니다.

LLM 브리지에 "실행 중인 모델이 없습니다"가 표시됨¶

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

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

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