OpenClaw·Hermes 마이그레이션 (11/13) — 마이그레이션 체크리스트: hermes claw migrate 옵션

-

공식 --dry-run, --preset, --skill-conflict, --workspace-target verbatim + 사전 백업·사후 검증

핵심 요약

  • 대상 독자: OpenClaw 운영 중이고 Hermes Agent로 갈아타려는 사용자. 또는 "두 도구를 비교한 뒤 결정"하고 싶은 사용자.
  • 얻을 것: 공식 hermes claw migrate 옵션 8개 verbatim, 무엇이 이관되고 무엇이 안 되는지, 5단계 안전 절차(백업 → dry-run → partial → full → 검증), 이관 후 점검 체크리스트, 롤백 전략.
  • 선행 조건: OpenClaw 동작, Hermes 설치 완료(#12), 기본 명령 익숙함(#13).

1. 이 도구가 존재하는 이유

Hermes Agent는 OpenClaw 사용자가 바로 갈아탈 수 있도록 공식 마이그레이션 커맨드를 제공한다.

hermes claw migrate [options]

공식 repo의 skills/openclaw-imports/ 디렉터리와 짝을 이뤄 동작 — 이관된 스킬은 여기에 정리된다.

중요: 마이그레이션은 복사이지 이동이 아니다. 성공해도 OpenClaw 쪽 데이터는 그대로 남는다. 롤백이 가능하다는 뜻이고, 동시에 디스크 용량을 2배로 먹을 수 있다는 뜻.

2. hermes claw migrate 옵션 — 전체 (공식 verbatim)

옵션 동작
--dry-run 실제 쓰기 없이 미리보기만
--preset <name> full (시크릿 포함) 또는 user-data (시크릿 제외)
--overwrite 기존 Hermes 파일을 덮어씀
--migrate-secrets API 키 포함해서 이관
--source <path> 커스텀 OpenClaw 디렉터리 지정
--workspace-target <path> AGENTS.md가 놓일 타겟 경로
--skill-conflict <mode> skip / overwrite / rename
--yes 확인 프롬프트 스킵

2.1 --preset 차이

  • full — OpenClaw의 설정, 메모리, 스킬, 시크릿(API 키·토큰) 전부 이관.
  • user-data — 시크릿 제외. 사용자 메모리·스킬·AGENTS.md만.

공유 서버·팀 컨텍스트에서는 user-data 권장. 개인 단일 머신이면 full이 편하다.

2.2 --skill-conflict 차이

OpenClaw 스킬 이름이 Hermes 기본 스킬·이전에 이관한 스킬과 충돌할 때 처리 방식.

모드 동작
skip 기존 것 유지, 새 것 버림
overwrite 새 것으로 덮어씀
rename 새 것에 suffix 붙여서 둘 다 보존

처음 이관 시 rename을 권장 — 나중에 비교한 뒤 삭제 결정.

2.3 --source / --workspace-target

비표준 경로를 쓴다면:

  • --source /custom/openclaw/path: OpenClaw ~/.openclaw/ 외 위치에 있으면 명시.
  • --workspace-target ~/projects/my-app: 이관 완료 시 프로젝트 루트의 AGENTS.md에 OpenClaw workspace 내용을 병합.

3. 무엇이 이관되고 무엇이 안 되는가

공식 문서가 전부 명시하지 않으므로 관찰 + 공식 커맨드 의도에서 유추.

3.1 이관되는 것 (확인)

  • 사용자 메모리 — OpenClaw의 MEMORY.md·USER.md는 Hermes의 ~/.hermes/memories/로.
  • 스킬 — ~/.openclaw/workspace/skills/ → ~/.hermes/skills/openclaw-imports/.
  • AGENTS.md — --workspace-target 지정 시 해당 경로로. 미지정 시 개별 workspace 루트.
  • (선택) 시크릿 — --preset full 또는 --migrate-secrets 플래그 시 API 키·토큰.

3.2 이관 안 되는 것 (주의)

  • OpenClaw 게이트웨이 상태 — 실행 중인 OpenClaw 데몬은 별도 종료. Hermes는 자체 gateway.
  • 채널 페어링 상태 — Discord·Slack·Telegram 봇 토큰은 이관되지만 페어링된 사용자 리스트는 재확인 필요할 수 있음.
  • SQLite 세션 DB — OpenClaw와 Hermes의 세션 저장 스키마는 다르다. 과거 대화 로그는 read-only 형태로 참조만 가능(자동 이관 대상 아님).
  • pairing approve 기록 — Hermes에서 다시 승인 필요.
  • 크론·훅 — OpenClaw의 cron·hooks는 Hermes의 hermes cron·hermes webhook으로 수동 재구성 필요.

4. 실전 5단계 — 안전하게 이관하기

4.1 단계 1: OpenClaw 상태 스냅샷

OpenClaw 쪽에서:

openclaw doctor
openclaw channels status --probe

cp -r ~/.openclaw ~/.openclaw.bak-$(date +%Y%m%d)

기존 OpenClaw 디렉터리 전체를 복사. hermes claw migrate가 실패해도 원복 가능.

4.2 단계 2: Hermes 쪽 현재 상태 보존

이미 Hermes를 쓰고 있었다면:

hermes backup -o ~/hermes-pre-migrate-$(date +%Y%m%d).zip

이관 후 덮어쓰기 / 스킬 충돌이 예상대로 동작 안 하면 이 zip에서 hermes import로 복원.

4.3 단계 3: --dry-run으로 미리보기

hermes claw migrate --dry-run

이 명령은 쓰기 없이 이관 계획을 출력. 확인 포인트: - 몇 개의 스킬이 이관되는가 - AGENTS.md가 어디에 쓰일 예정인가 - 메모리 파일이 충돌하는 지점이 있는가

출력을 읽고 예상과 맞는지 확인.

4.4 단계 4: 부분 이관 (user-data + rename)

시크릿 없이, 충돌 시 rename으로 안전하게:

hermes claw migrate \
  --preset user-data \
  --skill-conflict rename

이관 완료 후 확인:

ls ~/.hermes/skills/openclaw-imports/    # 이관된 스킬
cat ~/.hermes/memories/MEMORY.md          # 병합된 메모리
cat ~/.hermes/memories/USER.md            # 병합된 사용자 프로필

hermes skills list                        # 전체 스킬 인벤토리
hermes status --deep                      # 전체 상태

4.5 단계 5: 시크릿 이관 (개인 머신만)

개인 랩톱/홈서버에서만:

hermes claw migrate \
  --preset full \
  --migrate-secrets \
  --overwrite \
  --yes

--overwrite는 앞 단계에서 user-data로 만든 것을 시크릿 포함으로 새로 엎어쓴다. 개인 환경 + 이미 백업 완료 전제.

공유 서버에서 절대 금지. --migrate-secrets는 ~/.hermes/ 안에 API 키 파일을 쓴다 — 다른 사용자가 접근 가능하면 토큰 유출.

5. 이관 후 검증 체크리스트

hermes doctor
hermes status --all

hermes skills list
ls ~/.hermes/skills/openclaw-imports/

cat ~/.hermes/memories/MEMORY.md
cat ~/.hermes/memories/USER.md

hermes auth list

hermes gateway setup
hermes pairing list    # 페어링 재승인 필요한 것 확인

hermes chat -q "이관 후 첫 테스트. 내 이름 기억해?"

USER.md에 이름이 있었다면 자연스럽게 답해야 한다. 이름을 모른다고 나오면 MEMORY/USER 이관이 제대로 안 된 것.

6. 스킬 충돌 실전 예

6.1 rename 후 인벤토리

openclaw-imports/ 안에 memory-guardian이라는 스킬이 있고, Hermes 기본 중에도 비슷한 이름이 있다면 rename 모드에서 다음과 같이 될 수 있다:

~/.hermes/skills/
├── memory-guardian/         # Hermes 기본
└── openclaw-imports/
    └── memory-guardian-openclaw/   # 이관된 버전 (suffix)

두 스킬을 비교:

hermes skills inspect memory-guardian
hermes skills inspect memory-guardian-openclaw

inspect는 설치 없이 미리보기. 더 나은 쪽 유지, 나머지 제거:

hermes skills uninstall memory-guardian-openclaw

6.2 --overwrite 사용 시점

OpenClaw에서 엄청난 정성으로 튜닝한 커스텀 스킬을 그대로 유지하고 싶을 때만:

hermes claw migrate --preset user-data --skill-conflict overwrite

Hermes 기본 스킬이 OpenClaw 버전으로 덮인다. 이후 Hermes 업데이트가 해당 기본 스킬을 개선해도 그 효과를 받지 못할 수 있으니, 이 결정은 의식적으로.

7. 메모리 병합 — 주의점

7.1 토큰 상한

Hermes active 메모리는 #14에서 다룬 대로 MEMORY.md 2200자 / USER.md 1375자. OpenClaw 쪽이 이보다 컸다면 잘린다.

이관 후 반드시:

wc -c ~/.hermes/memories/MEMORY.md
wc -c ~/.hermes/memories/USER.md

캡에 가까우면 정제가 필요. 긴 과거 기록은 세션 DB로 내려야 한다(한 번의 대화에서 agent에게 "이 내용을 기억해"로 지시하면 agent가 FTS5에 유의미하게 저장).

7.2 중복 정리

OpenClaw와 Hermes에서 양쪽 모두 같은 팩트를 배운 경우 중복 가능성. 수동 확인 후 중복 제거.

8. AGENTS.md 이관

OpenClaw의 ~/.openclaw/workspace/skills/<skill>/AGENTS.md는 스킬 단위. Hermes의 AGENTS.md는 프로젝트 단위(git root).

공식 --workspace-target 옵션으로 병합:

hermes claw migrate \
  --workspace-target ~/projects/my-app \
  --preset user-data

이 경우 ~/projects/my-app/AGENTS.md에 OpenClaw의 workspace 지침이 병합 추가. 기존 AGENTS.md가 있으면 concat 처리.

9. 채널 재연결 — 수동 단계

이관이 자동으로 해주지 않는 부분:

9.1 Discord / Slack / Telegram 봇

hermes gateway setup

실행 후 각 채널에 대해: 1. 기존 OpenClaw 봇 토큰 재입력 (또는 hermes auth add로 환경변수 참조) 2. 새 페어링 (Hermes gateway가 붙으면 사용자가 봇과 대화 시 pending 발생) 3. hermes pairing list → hermes pairing approve <CODE>

기존 Discord/Slack 서버의 봇 자체는 유지되므로 Discord Developer Portal에서 재설정 필요 없다. 단지 실행 위치가 OpenClaw → Hermes로 바뀌는 것.

9.2 이전 OpenClaw 봇 중단

두 에이전트가 동시에 같은 봇 토큰을 쓰면 둘 다 응답하는 혼란 발생. OpenClaw를 반드시 먼저 stop:

launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist
systemctl --user stop openclaw

9.3 크론·훅 재생성

OpenClaw에서 운영 중이던 크론·훅은 Hermes로 수동 이식.

cat ~/.openclaw/openclaw.json | jq .cron
cat ~/.openclaw/openclaw.json | jq .hooks

hermes cron create ...
hermes webhook subscribe ...

10. 롤백 전략

이관 후 문제가 심각하면:

10.1 Hermes만 롤백

hermes import ~/hermes-pre-migrate-$(date +%Y%m%d).zip

hermes backup/hermes import로 왕복 가능.

10.2 OpenClaw로 복귀

OpenClaw 쪽은 건드리지 않았으므로 그대로 켜면 됨.

hermes gateway stop
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist
systemctl --user start openclaw

Hermes를 완전 삭제하려면:

hermes uninstall --full --yes

10.3 하이브리드 운영

둘 다 유지하되 다른 채널에 분산: - OpenClaw: Telegram (과거 긴 세션 아카이브 용) - Hermes: Discord + Slack (신규 워크플로)

양쪽이 같은 채널에 동시 연결되지만 않으면 공존 가능. 단 메모리·스킬 동기화는 없다.

11. 의사결정 가이드 — 옮길 것인가

간단 체크:

조건 권장
자기 학습 스킬·FTS5 메모리에 가치 느낌 Hermes 이동
메신저 채널 22+ 종 지원 전부 필요 OpenClaw 유지
Rust 네이티브 속도 선호 둘 다 아님 → Codex
Windows 네이티브 필수 OpenClaw 유지 (Hermes는 WSL2 필수)
40+ 내장 도구·SOUL.md 기반 페르소나 필요 Hermes 이동
SOC2 / 엔터프라이즈 감사 필요 둘 다 아직 초기 단계 → 신중

12. 반대 시나리오 — 이관하지 말아야 할 때

  • 프로덕션 봇이 안정 동작 중 → 이관의 ROI 검증 전에 옮기지 말 것. 먼저 Hermes를 별도 채널에서 실험.
  • OpenClaw 커스텀 스킬에 많은 투자 → overwrite 위험. rename 이관 후 장기 비교.
  • 팀 운영 → 팀원 전원 이관 준비 되기 전에 옮기면 사용자 경험 분리. 공유 타임라인 필요.
  • Windows 네이티브 환경 → Hermes 공식 지원 부족. WSL2 없이는 불가.

13. 마이그레이션 전/중/후 체크리스트 (인쇄용)

전 - [ ] openclaw doctor 정상 - [ ] ~/.openclaw 백업 (cp -r) - [ ] Hermes 백업 (hermes backup -o ...) - [ ] 현재 OpenClaw가 어떤 채널·스킬·크론을 가지는지 문서화

중 - [ ] hermes claw migrate --dry-run으로 계획 확인 - [ ] hermes claw migrate --preset user-data --skill-conflict rename - [ ] 출력 메시지에서 에러 없음 확인

후 - [ ] hermes doctor - [ ] hermes skills list에 OpenClaw 스킬 등장 - [ ] MEMORY.md / USER.md 내용 확인 - [ ] OpenClaw 데몬 중단 - [ ] hermes gateway setup → 채널 재연결 - [ ] 페어링 재승인 - [ ] 테스트 메시지 1개 보내서 정상 동작 확인 - [ ] 크론·훅 수동 이식 - [ ] 1주일 안정 후 OpenClaw 완전 제거 판단

14. 시리즈 총정리

이 글로 "AI 코딩 CLI 진입 가이드" 시리즈 15편이 모두 마무리된다.

Claude Code (#1~#5)

  1. 설치 완전판
  2. 슬래시 커맨드 총정리
  3. CLAUDE.md 작성 가이드
  4. 훅 완전 가이드
  5. 토큰·캐시 비용 해부

Codex (#6~#8)

  1. 설치 완전판
  2. config.toml 고급 설정
  3. Codex + Claude Code 병행 워크플로우

OpenClaw (#9~#11)

  1. 설치 + Discord 30분
  2. 프로덕션 운영
  3. OpenClaw ↔ Claude Code 브릿지

Hermes Agent (#12~#15)

  1. 설치 완전판 + SOUL.md
  2. 명령어 완전 치트시트
  3. 영속 메모리 FTS5 실전
  4. (이 글) 마이그레이션 체크리스트

참고

이 글은 "AI 코딩 CLI 진입 가이드" 시리즈의 15/15 편이자 마지막 편입니다. last verified: 2026-04-25 (hermes-agent.nousresearch.com 공식 문서 기준).

시리즈 전체 안내: 시리즈 목차

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »