OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Maintenance

Claude에서 마이그레이션하기

OpenClaw은 번들로 제공되는 Claude 마이그레이션 제공자를 통해 로컬 Claude 상태를 가져옵니다. 제공자는 상태를 변경하기 전에 모든 항목을 미리 보여 주고, 계획과 보고서에서 비밀 정보를 가리며, 적용 전에 검증된 백업을 생성합니다.

가져오는 두 가지 방법

온보딩 마법사

마법사는 로컬 Claude 상태를 감지하면 Claude 옵션을 제공합니다.

bash
openclaw onboard --flow import

또는 특정 소스를 지정하세요.

bash
openclaw onboard --import-from claude --import-source ~/.claude

CLI

스크립트로 실행하거나 반복 실행하려면 openclaw migrate를 사용하세요. 전체 참조는 openclaw migrate를 확인하세요.

bash
openclaw migrate claude --dry-runopenclaw migrate apply claude --yes

특정 Claude Code 홈 또는 프로젝트 루트를 가져오려면 --from <path>를 추가하세요.

가져오는 항목

지침과 메모리
  • 프로젝트의 CLAUDE.md 및 .claude/CLAUDE.md 콘텐츠는 OpenClaw 에이전트 워크스페이스의 AGENTS.md에 복사되거나 추가됩니다.
  • 사용자 ~/.claude/CLAUDE.md 콘텐츠는 워크스페이스의 USER.md에 추가됩니다.
MCP 서버

MCP 서버 정의가 있으면 프로젝트 .mcp.json, Claude Code ~/.claude.json, Claude Desktop claude_desktop_config.json에서 가져옵니다.

Skills 및 명령
  • SKILL.md 파일이 있는 Claude Skills는 OpenClaw 워크스페이스의 Skills 디렉터리로 복사됩니다.
  • .claude/commands/ 또는 ~/.claude/commands/ 아래의 Claude 명령 Markdown 파일은 disable-model-invocation: true가 설정된 OpenClaw Skills로 변환됩니다.

아카이브에만 보관되는 항목

제공자는 수동 검토를 위해 다음 항목을 마이그레이션 보고서에 복사하지만, 활성 OpenClaw 구성에는 로드하지 않습니다.

  • Claude 훅
  • Claude 권한 및 광범위한 도구 허용 목록
  • Claude 환경 기본값
  • CLAUDE.local.md
  • .claude/rules/
  • .claude/agents/ 또는 ~/.claude/agents/ 아래의 Claude 하위 에이전트
  • Claude Code 캐시, 계획, 프로젝트 기록 디렉터리
  • Claude Desktop 확장 기능 및 운영체제에 저장된 자격 증명

OpenClaw은 훅을 실행하거나, 권한 허용 목록을 신뢰하거나, 불투명한 OAuth 및 Desktop 자격 증명 상태를 자동으로 디코딩하지 않습니다. 아카이브를 검토한 후 필요한 항목을 수동으로 옮기세요.

소스 선택

--from을 지정하지 않으면 OpenClaw은 기본 Claude Code 홈인 ~/.claude, 표본 Claude Code ~/.claude.json 상태 파일, macOS의 Claude Desktop MCP 구성을 검사합니다.

--from이 프로젝트 루트를 가리키면 OpenClaw은 CLAUDE.md, .claude/settings.json, .claude/commands/, .claude/skills/, .mcp.json 등 해당 프로젝트의 Claude 파일만 가져옵니다. 프로젝트 루트 가져오기 중에는 전역 Claude 홈을 읽지 않습니다.

권장 절차

  • 계획 미리 보기

    bash
    openclaw migrate claude --dry-run

    계획에는 충돌, 건너뛴 항목, 중첩된 MCP env 또는 headers 필드에서 가려진 민감한 값을 포함하여 변경될 모든 항목이 나열됩니다.

  • 백업과 함께 적용

    bash
    openclaw migrate apply claude --yes

    OpenClaw은 적용 전에 백업을 생성하고 검증합니다.

  • Doctor 실행

    bash
    openclaw doctor

    Doctor는 가져오기 후 구성 또는 상태 문제를 확인합니다.

  • 재시작 및 확인

    bash
    openclaw gateway restartopenclaw status

    Gateway가 정상 상태이며 가져온 지침, MCP 서버, Skills가 로드되었는지 확인하세요.

    • 충돌 처리

    계획에서 충돌을 보고하면 대상에 파일 또는 구성 값이 이미 존재하는 것이므로 적용을 계속하지 않습니다.

    새로 설치한 OpenClaw에서는 충돌이 드뭅니다. 일반적으로 사용자 편집 내용이 이미 있는 설정에서 가져오기를 다시 실행할 때 발생합니다.

    자동화를 위한 JSON 출력

    bash
    openclaw migrate claude --dry-run --jsonopenclaw migrate apply claude --json --yes

    대화형 터미널 외부에서 migrate apply를 실행하려면 --yes가 필요합니다. 이를 지정하지 않으면 OpenClaw은 적용하는 대신 오류를 반환하므로 스크립트와 CI에서는 --yes를 명시적으로 전달해야 합니다. 먼저 --dry-run --json으로 미리 보고, 계획이 올바르면 --json --yes로 적용하세요.

    문제 해결

    Claude 상태가 ~/.claude 외부에 있는 경우

    --from /actual/path(CLI) 또는 --import-source /actual/path(온보딩)를 전달하세요.

    기존 설정에서 온보딩이 가져오기를 거부하는 경우

    온보딩 가져오기에는 새 설정이 필요합니다. 상태를 초기화하고 다시 온보딩하거나, --overwrite와 명시적 백업 제어를 지원하는 openclaw migrate apply claude를 직접 사용하세요.

    Claude Desktop의 MCP 서버를 가져오지 못한 경우

    Claude Desktop은 플랫폼별 경로에서 claude_desktop_config.json을 읽습니다. OpenClaw이 자동으로 감지하지 못했다면 --from으로 해당 파일의 디렉터리를 지정하세요.

    Claude 명령이 모델 호출이 비활성화된 Skills로 변환된 경우

    이는 의도된 동작입니다. Claude 명령은 사용자가 실행하므로 OpenClaw은 disable-model-invocation: true가 설정된 Skills로 가져옵니다. 에이전트가 자동으로 호출하게 하려면 각 Skill의 프런트매터를 편집하세요.

    관련 항목

    Was this useful?
    On this page

    On this page