Claude Code·Codex에서 Hermes로 옮기기 (import-agent)

기준일: 2026-11-04
문서 반영 버전: v0.22.6
난이도: 입문
공식 기준: Import from Other Agents, Migrate from OpenClaw

개요

hermes import-agent는 Claude Code, OpenAI Codex CLI, Cursor, OpenClaw, Grok Bot, OpenBot에서 쓰던 설정을 명령 하나로 Hermes에 가져옵니다. v0.20.0에서 Claude Code·Codex 이전용으로 처음 들어왔고, 지금은 대상이 늘었습니다.

Claude Code를 오래 써서 CLAUDE.md, 권한 규칙, MCP 서버, 스킬이 쌓여 있다면 Hermes를 처음부터 다시 꾸밀 필요가 없습니다. 가져오기 전에 항목별 계획을 먼저 보여 주고, --dry-run은 디스크를 전혀 건드리지 않습니다.

하나 알아 둘 점이 있습니다. 이 명령은 이제 Hermes core가 아니라 공식 agent-importers 플러그인에 들어 있습니다(Nous Research가 관리, 플러그인 카탈로그 항목). 플러그인이 없을 때 hermes import-agent를 실행하면 설치 명령을 알려 줍니다.

언제 쓰나

• Claude Code나 Codex를 쓰다가 Hermes를 같이 써 보고 싶을 때
• 두 에이전트를 나란히 쓰면서 지시문·MCP 설정을 한쪽에서만 관리하고 싶을 때(--sync)
• 새 PC에 Hermes를 깔면서 기존 Claude Code 환경을 그대로 옮기고 싶을 때

가장 쉬운 방법: hermes setup

새로 설치했다면 hermes setup이 먼저 ~/.claude, ~/.codex, ~/.cursor, ~/.openclaw 등을 찾아봅니다. 찾으면 "Import your setup from Claude Code?"처럼 묻고, 여러 개면 체크리스트에서 고르게 합니다. 예라고 하면 agent-importers 플러그인을 설치하고 아래 가져오기를 미리보기와 확인까지 포함해 실행합니다.

OpenClaw만은 다르게 처리합니다. hermes setup이 OpenClaw를 가져올 때는 --migrate-secrets를 자동으로 넘기므로 API key와 봇 토큰도 같이 옮겨지고, 이어지는 provider·메시징 설정 단계가 미리 채워집니다. 비밀값을 옮기고 싶지 않다면 setup 제안을 거절하고 아래처럼 직접 가져오세요.

이미 설정을 끝냈다면 이렇게 합니다.

hermes migrate              # 같은 제안을 다시 받기
hermes migrate claude-code  # 한 에이전트만. 플러그인이 없으면 설치까지

hermes migrate에 쓸 수 있는 이름은 openclaw, claude-code, codex, cursor, grok-bot, openbot입니다.

직접 하는 순서

1단계: 플러그인 설치 (프로필마다 한 번)

hermes plugins install agent-importers

2단계: 미리보기

hermes import-agent claude-code --dry-run

먼저 이것부터 돌려 보세요. 무엇이 어디로 가는지, 무엇이 충돌하는지, 무엇이 옮겨지지 않는지 계획만 나옵니다.

3단계: 가져오기

hermes import-agent                    # ~/.openclaw, ~/.claude, ~/.codex, ~/.cursor 자동 감지
hermes import-agent claude-code        # ~/.claude에서
hermes import-agent codex              # ~/.codex에서
hermes import-agent codex --source /path/to/.codex   # 다른 위치
hermes import-agent claude-code --overwrite --yes    # 충돌 항목 덮어쓰기, 확인 생략

비대화형 세션에서는 --yes가 없으면 미리보기에서 멈춥니다.

Claude Code에서 무엇이 옮겨지나

Claude Code	Hermes
CLAUDE.md (전역 지시)	~/.hermes/memories/MEMORY.md의 메모리 항목
settings.json → permissions.allow (Bash(...) 규칙)	config.yaml의 command_allowlist
settings.json → permissions.deny (Bash(...) 규칙)	config.yaml의 approvals.deny
mcpServers (~/.claude.json, settings.json)	config.yaml의 mcp_servers
skills/<name>/ (SKILL.md가 있는 폴더)	~/.hermes/skills/claude-code-imports/<name>/
commands/*.md (슬래시 명령)	건너뜀. 스킬로 바꾸라는 메모만 남는다

Claude Code를 쓰던 사람이 헷갈리기 쉬운 부분입니다.

• Bash(npm run test:*) 같은 접두 규칙은 npm run test* glob으로 바뀝니다.
• Read(...), WebFetch처럼 Bash가 아닌 권한 규칙은 옮겨지지 않습니다. Claude Code 전용 도구를 막는 규칙이라 "unmapped"로 보고만 됩니다. Hermes 쪽 파일 쓰기 보호는 보안과 승인에서 따로 정해야 합니다.
• 표의 대상은 ~/.claude 아래의 전역 CLAUDE.md입니다. 프로젝트별 CLAUDE.md는 공식 표에 없습니다.
• 슬래시 명령은 직접 스킬로 옮겨야 합니다. Hermes 스킬 구조는 스킬을 보세요.

Claude Code 쪽 원래 설정이 기억나지 않으면 이 사이트의 CLAUDE.md 설정, 권한 규칙, MCP 통합, 스킬 시스템을 같이 보면 대응 관계가 잘 보입니다.

Codex CLI·Cursor에서 무엇이 옮겨지나

Codex CLI	Hermes
AGENTS.md (전역 지시)	MEMORY.md 메모리 항목
config.toml → [mcp_servers.*]	mcp_servers
memories/*.md	MEMORY.md 메모리 항목
skills/<name>/	~/.hermes/skills/codex-imports/<name>/

Cursor	Hermes
AGENTS.md	MEMORY.md 메모리 항목
rules/*.md, rules/*.mdc (User Rules)	MEMORY.md 메모리 항목 (.mdc frontmatter는 떼고 본문만)
mcp.json → mcpServers	mcp_servers
skills/**/<name>/	~/.hermes/skills/cursor-imports/<name>/

OpenClaw는 옮길 항목이 훨씬 많아 공식 Migrate from OpenClaw 가이드가 따로 있습니다.

절대 옮겨지지 않는 것: 비밀값

API key와 자격 증명은 가져오지 않습니다. (예외는 OpenClaw뿐이고, --migrate-secrets를 줄 때만 허용 목록의 키와 봇 토큰을 옮깁니다. 위에서 말했듯 hermes setup 경로는 이 옵션을 자동으로 넘깁니다.)

• ~/.claude/.credentials.json, ~/.codex/auth.json, ~/.cursor/cli-config.json은 아예 읽지 않습니다.
• MCP 서버의 환경 변수나 헤더 중 *_TOKEN, *_API_KEY, Authorization처럼 비밀처럼 보이는 항목은 지우고, 보고서에는 이름만 남깁니다. 값은 남지 않습니다.

그래서 가져온 뒤 MCP 서버가 인증 오류를 내는 건 정상입니다. 보고서에 나온 이름으로 값을 ~/.hermes/.env에 직접 넣고, config.yaml의 해당 서버 env(또는 headers)에서 ${VAR}로 참조하세요. MCP Config Reference 기준으로 서버 항목의 문자열 값은 ${VAR}를 활성 프로필의 .env에서 읽어 채웁니다.

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"   # 값은 ~/.hermes/.env에

모델 provider의 API key는 이와 별개로 hermes setup에서 설정합니다.

가져오기 동작 방식

• 바꾸지 않고 합친다. 메모리 항목은 기존 MEMORY.md와 중복을 걸러 합치고, 허용·거부 패턴도 기존 config.yaml에 합칩니다.
• 충돌은 기본으로 건너뛴다. 이미 있는 MCP 서버나 스킬은 충돌로 보고만 합니다. 바꾸려면 --overwrite.
• 깨진 파일이 있어도 멈추지 않는다. settings.json이 망가져 있으면 그 항목만 오류로 남기고 나머지는 가져옵니다.

계속 맞춰 두기: --sync

Claude Code·Codex·Cursor를 계속 같이 쓴다면 동기화가 편합니다. 가져오기가 성공할 때마다 원본과 읽은 내용의 digest가 ~/.hermes/import-sync.json에 기록됩니다.

hermes import-agent --sync            # 바뀐 원본만 다시 가져오기
hermes import-agent --sync --dry-run  # 무엇이 바뀔지 미리보기

• 바뀌지 않은 원본은 digest 비교로 건너뛰므로 cron으로 매일 돌려도 부담이 적습니다.
• 예전에 가져온 스킬은 원본이 바뀌면 그 자리에서 갱신됩니다. 사용자가 직접 만들거나 고친 스킬은 덮어쓰지 않습니다.
• ~/.claude/.credentials.json 같은 자격 증명 파일의 토큰 갱신은 동기화를 일으키지 않습니다.

이 기록은 프로필별입니다. hermes profile create <name> --clone --sync-imports로 만든 프로필은 같은 원본을 이어서 동기화합니다.

예전 버전에서 업데이트했다면

hermes import-agent와 hermes claw는 원래 Hermes core에 있었습니다. 플러그인으로 옮겨진 뒤에도 명령, 옵션, import-sync.json은 그대로입니다.

• import-sync.json이 있는 프로필은 hermes update나 업데이트 후 첫 실행 때 플러그인이 자동 설치됩니다(security.allow_lazy_installs 설정을 따름).
• 그 밖에는 필요할 때 설치하면 됩니다.

체크리스트

• hermes plugins install agent-importers를 했거나 hermes setup/hermes migrate로 진행했다
• --dry-run으로 계획을 먼저 확인했다
• 옮겨지지 않은 Read(...) 같은 권한 규칙과 슬래시 명령을 따로 정리했다
• 보고서에 이름만 남은 MCP 비밀값을 ~/.hermes/.env에 넣고 mcp_servers.<name>.env에서 ${VAR}로 참조했다
• 계속 같이 쓸 거라면 --sync를 일정에 걸었다

다음 단계

• Hermes Agent 소개: Hermes가 Claude Code와 어떻게 다른지
• Claude/OpenClaw와 비교: 어떤 일을 어느 도구에 맡길지
• MCP와 도구: 가져온 mcp_servers 확인
• 보안과 승인: command_allowlist와 approvals.deny의 의미