Claude Code / Hermes → OpenClaw 2026: Mac mini M4에서 openclaw migrate를 사용한 완전 마이그레이션 가이드

2026년 4월 28일 출시된 OpenClaw v2026.4.26에는 많은 개발자들이 기다리던 기능이 포함되었습니다: openclaw migrate——Claude Code 또는 Hermes로 구축한 AI 코딩 에이전트 설정을 OpenClaw에 일괄 임포트하는 명령입니다. Claude Code 또는 Hermes에서 MCP 서버 연결, 커스텀 스킬, 워크플로 조정을 쌓아온 경우, 각 설정을 수동으로 재생성하지 않고 OpenClaw로 마이그레이션할 수 있습니다. 이 가이드는 VpsGona의 Mac mini M4 노드에서의 프로세스를 완전히 설명합니다——자동으로 마이그레이션되는 내용, 수동 작업이 필요한 내용, 가장 일반적인 6가지 마이그레이션 후 오류 수정 방법을 포함합니다.

2026년에 개발자들이 Claude Code와 Hermes에서 OpenClaw로 이동하는 이유

2026년 초부터 마이그레이션 트렌드가 가속화되었습니다. 이유는 마케팅이 아닌 구체적인 제품 격차입니다. 이를 이해하면 마이그레이션이 당신의 워크플로에 적합한지 판단하는 데 도움이 됩니다.

이유 1: 플러그인 해킹 없는 네이티브 멀티에이전트 오케스트레이션. Claude Code의 멀티에이전트 지원은 Anthropic의 호스트 모델 라우팅에 제한되며 우회 방법이 필요합니다. OpenClaw의 네이티브 멀티에이전트 프레임워크(ClawHub)는 Memory-Wiki 상태 레이어를 공유하는 독립적인 에이전트 프로세스를 모든 모델 프로바이더에서 오케스트레이션할 수 있습니다.

이유 2: OpenClaw의 OTEL 관찰성은 프로덕션 품질. v2026.4.25부터 OpenClaw는 모든 모델 호출, 도구 호출, 메모리 접근에 대해 구조화된 텔레메트리를 발행합니다. Claude Code와 Hermes에는 동등한 구조화 관찰성이 없습니다. 토큰 비용 귀속, 도구 루프 감지, 메모리 압박 알림이 필요한 팀——특히 무인 야간 자율 에이전트를 실행하는 팀——은 다른 도구에서 동등한 기능을 찾을 수 없습니다.

이유 3: 프로바이더 중립성과 번들 Cerebras 지원. OpenClaw v2026.4.26은 Cerebras를 번들 프로바이더로 추가하여 OpenAI, Anthropic, Gemini, DeepSeek, 로컬 Ollama 모델에 합류했습니다. Claude Code는 구조적으로 Anthropic의 API에 묶여 있습니다. Hermes는 프로바이더 유연성이 있지만 플러그인 SDK 성숙도에서 OpenClaw v2026 릴리스에 미치지 못합니다.

openclaw migrate가 v2026.4.26에서 실제로 하는 일

openclaw migrate 명령은 소스 도구의 설정 디렉토리를 구조화 스캔하고, 호환되는 설정을 추출하고, OpenClaw의 설정 형식으로 변환하여 씁니다. 대화 기록이나 세션 로그는 복사하지 않습니다——설정, 기능 정의, 연결 메타데이터만 마이그레이션합니다.

마이그레이션 프로세스는 세 단계로 나뉩니다:

1. 발견 단계: OpenClaw가 소스 설정 디렉토리(Claude Code의 경우 ~/.claude/, Hermes의 경우 ~/.hermes/)를 스캔하여 설치된 MCP 서버, 커스텀 스킬/도구, API 키 참조, 프로바이더 설정을 감지합니다.
2. 변환 단계: 감지된 각 항목이 OpenClaw의 동등 항목으로 매핑됩니다. MCP 서버 정의는 OpenClaw의 플러그인 매니페스트 형식으로 재표현되고, API 키 환경 변수명은 별칭화되며, 커스텀 도구 정의는 OpenClaw의 스킬 스키마로 래핑됩니다.
3. 보고 단계: ~/.openclaw/migrate-report.json에 JSON 마이그레이션 보고서가 작성되어 성공적으로 마이그레이션된 각 항목, 부분적으로 마이그레이션된(수동 완료 필요) 항목, 마이그레이션할 수 없는 항목이 나열됩니다.

설정 항목	Claude Code에서 마이그레이션	Hermes에서 마이그레이션	비고
MCP 서버 엔드포인트 정의	✓ 자동	✓ 자동	연결 URI와 인증 헤더 보존
커스텀 스킬/도구 정의	✓ 자동	✓ 자동	OpenClaw 스킬 스키마로 래핑; 마이그레이션 후 테스트 필요
API 키 환경 변수 참조	✓ 자동 별칭	✓ 자동 별칭	실제 키 값은 읽히지 않음; .env에 별칭 생성
시스템 프롬프트 커스터마이징	⚠ 부분(확인 필요)	⚠ 부분(확인 필요)	오퍼레이터 ID 형식이 도구 간에 다름
모델 프로바이더 설정	⚠ 부분(Anthropic만)	✓ 자동(멀티프로바이더)	Claude Code의 비Anthropic 프로바이더는 마이그레이션 불가
메모리/지식베이스 컨텐츠	✗ 마이그레이션 안 됨	✗ 마이그레이션 안 됨	OpenClaw Memory-Wiki에 수동으로 재인제스트 필요
대화/세션 기록	✗ 마이그레이션 안 됨	✗ 마이그레이션 안 됨	설계상——OpenClaw 세션 형식은 비호환
TaskFlow/Webhook 정의	✗ 해당 없음(Claude Code에 없음)	⚠ 부분	Hermes 워크플로는 TaskFlow로 수동 매핑 필요

마이그레이션 전 체크리스트: 명령 실행 전 확인할 7가지 항목

준비 없이 openclaw migrate를 실행하면 대부분의 마이그레이션 후 문제의 원인이 됩니다. 마이그레이션 명령을 실행하기 전에 다음 7가지 항목을 모두 확인하세요.

1. OpenClaw 버전이 ≥ 2026.4.26인지 확인. migrate 서브커맨드는 이전 버전에 없습니다. openclaw --version으로 확인하고, npx openclaw@latest update 또는 에이전트 내 /update로 업데이트하세요.
2. 소스 도구 설정 디렉토리 백업. cp -r ~/.claude/ ~/claude-backup-$(date +%Y%m%d)/(Claude Code) 또는 Hermes의 동등 명령을 실행하세요. 마이그레이션 명령은 읽기 전용이지만 날짜가 있는 백업이 있으면 문제 발생 시 안심입니다.
3. 활성 MCP 서버 목록 작성. Claude Code 내에서 /mcp를 실행하여 연결된 MCP 서버의 이름과 연결 유형을 메모하세요. 나중에 마이그레이션 보고서의 커버리지를 확인하는 데 이 목록을 사용합니다.
4. 커스텀 시스템 프롬프트 커스터마이징 기록. 오퍼레이터 ID, 페르소나 지시, 안전 재정의를 변경한 경우 일반 텍스트 파일에 복사하세요. 마이그레이션 후 수동 확인이 필요할 가능성이 가장 높은 항목입니다.
5. Mac mini M4 노드에서 Node.js ≥ 20 확인. migrate는 Node 20+가 필요한 Node.js 네이티브 fetch API를 사용합니다. node --version으로 확인하세요.
6. 현재 사용 중인 API 프로바이더 확인. Hermes에서 여러 프로바이더(OpenAI + Gemini + Cerebras 등)를 설정한 경우, 마이그레이션 전에 모두 OpenClaw의 번들 프로바이더 목록에 있는지 확인하세요. 없는 프로바이더는 보고서에서 "manual-required"로 표시됩니다.
7. Mac mini M4 노드에 충분한 디스크 공간 확인. 마이그레이션 프로세스는 ~/.openclaw/에 보고서와 변환된 설정 파일을 씁니다. 대부분의 설정에서 500MB 여유 공간으로 충분합니다.

단계별: Mac mini M4에서 Claude Code에서 마이그레이션

다음 단계는 Claude Code와 OpenClaw v2026.4.26+가 모두 설치된 활성 VpsGona Mac mini M4 세션이 있다고 가정합니다. 노드에 SSH 연결하고 다음을 실행하세요:

1. 두 도구가 올바른 버전으로 존재하는지 확인:

   openclaw --version # ≥ 2026.4.26이어야 함 claude --version # Claude Code 설치 확인

2. Claude Code를 지정하여 마이그레이션 명령 실행:

   openclaw migrate --from claude-code

   OpenClaw는 자동으로 ~/.claude/를 감지합니다. Claude Code 설정이 비표준 위치에 있는 경우 --source로 명시적으로 지정:

   openclaw migrate --from claude-code --source /커스텀경로/.claude/

3. 마이그레이션 출력 확인. CLI는 실시간으로 각 감지 항목을 출력합니다. ✓ 접두사는 성공적인 마이그레이션, ⚠는 확인 필요, ✗는 마이그레이션 불가를 나타냅니다:

   Discovered: 8 MCP servers, 12 custom tools, 3 system prompt blocks, 1 provider config ✓ MCP server: filesystem-mcp → migrated ✓ MCP server: github-mcp → migrated ⚠ System prompt block 'persona' → manual-required (format differs) ⚠ Provider: anthropic → partial ✗ Memory content → not migrated (re-ingest manually) Migration complete. Report: ~/.openclaw/migrate-report.json

4. 전체 마이그레이션 보고서 확인:

   cat ~/.openclaw/migrate-report.json | python3 -m json.tool | head -80

5. OpenClaw를 시작하고 MCP 연결 확인:

   openclaw start /mcp status

   마이그레이션된 각 MCP 서버는 녹색 연결 상태를 표시해야 합니다. 연결되지 않은 것이 있으면 아래의 트러블슈팅 섹션을 참고하세요.

단계별: Hermes에서 OpenClaw로 마이그레이션

Hermes 마이그레이션은 동일한 패턴을 따르지만 다른 --from 플래그와 Hermes 특유의 고려 사항이 있습니다. Hermes는 기본적으로 ~/.hermes/에 설정을 저장하며 OpenClaw 마이그레이션 도구가 직접 읽을 수 있는 YAML 형식을 사용합니다.

1. Hermes 마이그레이션 실행:

   openclaw migrate --from hermes

   Hermes 워크스페이스(프로젝트 범위 설정)의 경우 워크스페이스 디렉토리 지정:

   openclaw migrate --from hermes --source /path/to/hermes-workspace/

2. Hermes 워크플로 정의를 수동으로 처리. Hermes의 "워크플로" 구조는 OpenClaw의 TaskFlows에 부분적으로 매핑됩니다. 마이그레이션 도구는 트리거와 단계 구조를 변환하지만 조건 분기 로직을 자동으로 복제할 수 없습니다. 마이그레이션 후, OpenClaw의 TaskFlow 에디터에서 각 플래그된 워크플로를 열어 분기 조건이 올바르게 표현되었는지 확인하세요.
3. 멀티프로바이더 설정 재구성. Hermes에서 여러 모델 프로바이더를 사용했다면 각 프로바이더가 OpenClaw 설정에서 활성화되어 있는지 확인:

   openclaw config list-providers

   누락된 프로바이더 추가:

   openclaw config add-provider cerebras --api-key $CEREBRAS_API_KEY

4. Memory-Wiki 컨텐츠 재인제스트. Hermes의 메모리 컨텐츠는 OpenClaw의 Memory-Wiki에 재인제스트가 필요합니다. 소규모 지식 베이스(50개 문서 미만)에는 /learn 명령을 대화형으로 사용. 더 큰 베이스에는 배치 인제스트 API 사용:

   openclaw memory ingest --dir /path/to/hermes/knowledge/ --format markdown

마이그레이션 범위: 자동 마이그레이션 vs 수동 설정이 필요한 것

항목 카테고리	자동 마이그레이션?	필요한 수동 작업
MCP 서버 엔드포인트와 인증	✓ 예	연결 성공이면 불필요; 토큰 만료 시 재인증
커스텀 도구/스킬 정의	✓ 예	스키마 변환 후 각 도구를 수동으로 실행하여 동작 확인
API 키 환경 변수 별칭	✓ 예(별칭만)	실제 키가 ~/.openclaw/.env 또는 시스템 환경에 있는지 확인
시스템 프롬프트 오퍼레이터 ID	⚠ 부분	OpenClaw의 오퍼레이터 형식에 맞게 확인·수정
모델 프로바이더 설정	⚠ 부분	Claude Code 마이그레이션 시 비Anthropic 프로바이더 수동 추가
Hermes 워크플로 조건	⚠ 부분	조건 분기를 TaskFlow 스키마로 수동 변환
메모리/지식베이스 컨텐츠	✗ 없음	/learn 또는 배치 인제스트로 모든 문서 재인제스트
대화 기록	✗ 없음	불필요——기록은 도구별로 이식 불가
Matrix E2EE 설정(v2026.4.26 신기능)	✗ 해당 없음(신기능)	처음부터 설정: openclaw security matrix --setup

마이그레이션 후 트러블슈팅: 6가지 일반적인 오류와 수정 방법

오류 1: 마이그레이션 후 MCP 서버가 "연결 끊김"으로 표시됩니다. 가장 일반적인 원인은 인증 토큰 만료입니다. MCP 서버는 토큰 참조를 저장하지만 실제 토큰 값은 저장하지 않습니다——토큰은 만료됩니다. 해결책: OpenClaw의 컨트롤 패널에서 MCP 서버의 인증 설정을 열고 재인증하세요.

오류 2: openclaw migrate: source directory not found. Claude Code가 비표준 위치에 설치된 경우가 있습니다. find ~ -name ".claude" -type d 2>/dev/null로 찾고 --source로 명시적으로 지정하세요.

오류 3: 커스텀 도구 호출 시 schema validation error 발생. 마이그레이션 도구는 OpenClaw의 스킬 스키마로 도구를 래핑하지만, 일부 도구의 파라미터 타입에는 정확한 동등물이 없습니다. ~/.openclaw/skills/의 도구 파라미터 정의를 확인하고 타입 선언을 OpenClaw의 스키마(string, number, boolean, array, object)에 맞추세요.

오류 4: 마이그레이션 후 시작 시 멈춤(v2026.4.26 알려진 문제). 많은 MCP 서버가 설정된 경우 v2026.4.26 업데이트 후 시작 지연을 보고하는 사용자가 있습니다. 연결 초기화가 동기적인 것이 원인인 알려진 문제입니다. 해결책: openclaw.config.js에서 필수가 아닌 MCP 서버를 일시적으로 비활성화하고 시작 완료 후 단계적으로 재활성화하세요.

오류 5: ENOENT: no such file or directory, open '~/.openclaw/.env'. 마이그레이션 도구는 .env가 존재한다고 가정합니다. 수동으로 생성하고 실제 키를 입력하세요:

touch ~/.openclaw/.env echo "ANTHROPIC_API_KEY=your-key-here" >> ~/.openclaw/.env echo "OPENAI_API_KEY=your-key-here" >> ~/.openclaw/.env

오류 6: 마이그레이션 후 Ollama 연결 실패. OpenClaw v2026.4.26은 Qwen과 Gemma 4 모델에 대한 Ollama의 신뢰성을 특히 개선했습니다. Hermes에서 작동했던 Ollama 연결이 OpenClaw에서 실패하는 경우, Ollama 0.22.0 이상을 실행 중인지 확인하세요:

ollama --version # ≥ 0.22.0이어야 함 ollama serve # OpenClaw 시작 전에 Ollama가 실행 중인지 확인

Mac mini M4에서 마이그레이션된 OpenClaw 설정 최적화

마이그레이션이 안정되고 모든 MCP 서버가 연결되면 Mac mini M4 배포에 특히 유익한 4가지 최적화를 실시할 수 있습니다:

• 실제로 사용하는 모델에 기반하여 maxContextTokens 설정. 마이그레이션된 설정은 일반적인 컨텍스트 윈도우 크기를 상속합니다. 16GB 통합 메모리의 Mac mini M4에서 Claude 3.7 Sonnet의 200K 컨텍스트 윈도우는 메모리 집약적입니다. 일반적인 코딩 작업에서는 openclaw.config.js에서 maxContextTokens: 32768로 설정하면 메모리 압박을 크게 줄이면서 거의 모든 실제 코딩 세션을 커버할 수 있습니다.
• 새로운 JSON5 보류 중인 변경사항 차이 패널 활성화. v2026.4.26의 신기능으로 에이전트가 파일 변경사항을 커밋하기 전에 구조화된 차이를 표시합니다. 원격 Mac mini M4 세션에서 실시간으로 작업 디렉토리를 확인할 수 없을 때 특히 유용합니다:

  // openclaw.config.js에서 ui: { pendingChangesDiff: true, diffFormat: 'json5' }

• 속도 우선 작업에 Cerebras 프로바이더 설정. Cerebras는 v2026.4.26에서 번들 프로바이더가 되었습니다. 응답 속도가 출력 길이보다 중요한 작업——빠른 코드 설명, 타입 어노테이션 제안, 테스트 케이스 생성——에서 Cerebras 모델이 유사한 품질 수준에서 Anthropic이나 OpenAI보다 훨씬 낮은 첫 번째 토큰 도달 시간을 제공합니다.
• 안전한 원격 세션을 위한 Matrix E2EE 설정. Claude Code와 Hermes 모두에 없는 신기능입니다. VpsGona 노드에서 OpenClaw를 실행하는 경우 모든 데이터는 이미 SSH를 통해 전송되지만 Matrix E2EE를 추가하면 애플리케이션 레이어에서 엔드투엔드 암호화가 추가됩니다:

  openclaw security matrix --setup

VpsGona의 Mac mini M4가 OpenClaw 마이그레이션의 이상적인 대상 환경인 이유

OpenClaw로의 마이그레이션은 설정 변경입니다; OpenClaw를 어디서 실행하느냐가 마이그레이션이 완전한 가치를 발휘하는지를 결정합니다. 개인 노트북이나 데스크톱에서 Claude Code 또는 Hermes를 실행했던 개발자에게 VpsGona의 Mac mini M4 노드에서 OpenClaw로 마이그레이션은 몇 가지 구체적인 점에서 상황을 바꿉니다.

첫째, Mac mini M4의 Apple Silicon 아키텍처는 Claude Code 사용자가 구축한 모든 macOS 전용 MCP 서버와 도구와 네이티브로 호환됩니다. 파일 시스템 접근, Xcode 통합, AppleScript 또는 단축어를 통한 macOS 자동화, CoreML 기반 로컬 모델 추론——모두 M4 칩에서 설계대로 작동합니다. MCP 서버 설정을 마이그레이션하면 설계된 환경과 완전히 동일한 OS와 칩 아키텍처의 환경에 도달합니다.

둘째, VpsGona의 최소 약정 없는 렌탈 모델은 OpenClaw의 사용 패턴과 자연스럽게 일치합니다. OpenClaw의 가장 강력한 기능——ClawHub를 통한 멀티에이전트 오케스트레이션, OTEL 관찰성, 무인 야간 에이전트——은 개인 머신에서 간헐적으로 사용하는 것이 아닌 전용 노드에서 지속적으로 실행할 때 가장 가치가 있습니다. OpenClaw 워크로드 전용의 Mac mini M4 노드를 프로젝트 사이클마다 렌탈함으로써 전용 서버 대안의 비용의 일부로 네이티브 Apple Silicon 성능을 실현할 수 있습니다. 현재 노드 설정은 VpsGona 요금 페이지에서, OpenClaw 환경 설정은 배포 문서에서 확인하세요.