OpenClaw VPS 호스팅 — 서버 이전 가이드

기존 서버의 데이터를 새 서버로 이전하는 방법을 안내합니다. AI 에이전트에게 맡기는 방법과 직접 이전하는 방법 중 선택할 수 있습니다.

💡 요약 정리

이전 방법은 간편 이전(에이전트 위임)과 직접 이전(터미널 사용) 두 가지가 있습니다.
이전 전 기존 서버의 데이터를 반드시 별도로 백업해 주세요.
새 서버 접속 정보(IP, 비밀번호)가 필요하며, 양쪽 서버 간 SSH(포트 22) 통신이 가능해야 합니다.
이전 완료 후 새 서버의 비밀번호를 반드시 변경하세요.

안내 및 면책 사항

본 가이드는 고객님의 편의를 위해 제공되는 참고 자료이며, 실제 적용 여부와 진행 방식은 고객님의 운영 환경에 맞추어 신중히 검토해 주시기 바랍니다.

이전 작업 전에는 기존 서버의 데이터를 반드시 별도로 백업해 주시기 바랍니다. 이전 과정에서 예상하지 못한 문제가 발생할 수 있으며, 백업이 없는 경우 데이터 복구가 어려울 수 있습니다.
자동화 도구를 활용한 이전 방식(§2)은 서버 접속에 필요한 정보 입력이 수반될 수 있으므로, 진행 전 관련 정보의 관리와 보안 설정을 충분히 점검해 주시기 바랍니다. 보안상 주의가 필요한 환경에서는 §3(직접 이전) 방식으로 진행하시는 것을 권장드립니다.
자동화 도구를 활용한 이전은 사용 환경과 설정에 따라 예상과 다른 결과가 발생할 수 있어, 작업 전 충분한 사전 검토가 필요합니다.
또한 이전 과정 또는 이전 이후에는 환경에 따라 데이터 차이, 서비스 중단, 추가 비용이나 별도 설정 작업이 발생할 수 있으므로, 적용 전 영향 범위를 충분히 확인해 주시기 바랍니다.
본 가이드의 내용은 일반적인 기술 참고를 위한 안내이며, 모든 환경에 동일하게 적용되지 않을 수 있습니다.

섹션	내용	대상
§1	이전 전 안내 — 이전 대상, 사전 확인, 방법 선택	공통
§2	간편 이전 (에이전트 위임)	서버/터미널에 익숙하지 않은 분
§3	직접 이전 (터미널 사용)	서버 관리에 익숙한 분
§4	에이전트 지시서 — §2에서 복사하여 사용	§2 선택 시 참조
§5	문제 해결 및 대용량 이전 안내	공통

1. 이전 전 안내

1-1. 이전 대상 항목

이전이 정상적으로 완료되면, 아래 데이터들이 새 서버로 옮겨집니다.

항목	설명
대화 내역	AI 에이전트와 나눈 대화 기록
메모리	에이전트가 기억하고 있던 정보
워크스페이스	저장해둔 파일들
예약 작업	크론/스케줄 설정
텔레그램 연결 설정	메신저 봇 연동 정보
AI 모델 API 키	LLM 인증 정보

1-2. 이전 후 재설정 필요 여부

항목	간편 이전 (§2)	직접 이전 (§3)
텔레그램 봇 연동	재설정 불필요	재설정 불필요
LLM API 키	에이전트가 자동 재등록	수동 재등록 필요 (§3 Step 8)

1-3. 사전 확인

새 서버 접속 정보 확인

서비스 가입 시 안내받은 새 서버의 접속 정보가 필요합니다.

새 서버 IP 주소 (예: 123.456.789.10)
새 서버 비밀번호

서버 IP는 나의 서비스 관리 메뉴에서 확인할 수 있습니다. 계정은 root이며, 비밀번호는 서비스 신청 시 입력하신 root 비밀번호입니다.

SSH 통신 환경 확인

이전 과정에서 기존 서버와 새 서버 간 SSH(포트 22) 통신이 필요합니다. 아래 상황에 해당하면 사전 조치가 필요합니다.

방화벽: 기존 서버의 아웃바운드 또는 새 서버의 인바운드 방화벽에서 22번 포트가 차단되어 있으면 이전이 실패합니다. 양쪽 서버 모두 22번 포트 통신이 가능한지 사전에 점검해주세요.
SSH 접속 제한 설정: hosts.allow, hosts.deny, SSH 키 파일 인증 전용 설정 등 SSH 접속을 제한하는 커스텀 설정이 있는 경우, 기존 서버의 IP(또는 내 PC의 IP)를 허용하거나 해당 설정을 일시적으로 비활성화해야 합니다.
root 원격 접속: 본 가이드는 root 계정으로 SSH 원격 접속이 가능한 환경에서만 진행할 수 있습니다. PermitRootLogin이 비활성화되어 있으면 활성화가 필요합니다.

1-4. 이전 방법 선택

본인에게 맞는 방법을 선택하세요.

구분	간편 이전 — §2	직접 이전 — §3
대상	서버나 터미널에 익숙하지 않은 분	SSH, CLI 등 서버 관리에 익숙한 분
방식	텔레그램에서 에이전트에게 지시	터미널에서 명령어 직접 실행
난이도	쉬움 (메시지 전송 + 명령어 1개)	중간 (명령어 복사-붙여넣기)
소요 시간	약 10~30분	약 20~40분
필요한 것	텔레그램 앱, 새 서버 접속 정보	기존/새 서버 접속 정보, SSH 클라이언트
API 키	에이전트가 자동 재등록	수동 재등록 필요

2. 간편 이전 (에이전트 위임)

텔레그램에서 AI 에이전트에게 이전 지시서를 보내면, 에이전트가 자동으로 이전 작업을 수행합니다.

2-1. 에이전트를 통한 이전, 알아두실 점

AI 에이전트는 사람이 아니라 인공지능이기 때문에, 아래와 같은 특성이 있습니다.

작업 방식이 매번 조금씩 다를 수 있습니다. 명령어 순서나 표현이 달라질 수 있으며, 결과가 다를 수도 있습니다. 이전 완료 후 반드시 데이터 수치를 직접 비교하여 확인해주세요.
중간에 질문을 할 수 있습니다. 에이전트가 확인이 필요한 사항을 물어보면 답변해주세요.
실패 시 스스로 다시 시도합니다. 한 번에 안 될 수도 있지만, 에이전트가 다른 방법으로 재시도합니다. 여러 번 반복 실패하면 §3 (직접 이전)을 이용해주세요.
과정보다 결과를 확인해주세요. 중간 과정이 어려워 보여도 괜찮습니다. 에이전트가 최종 보고하는 수치(작업 수, 파일 수, DB 크기)만 확인하시면 됩니다.
사용 중인 AI 모델에 따라 작업 품질이 달라질 수 있습니다. 상위 모델은 지시를 정확하게 수행하는 반면, 무료 또는 하위 모델은 단계를 빠뜨리거나 실수할 가능성이 높습니다. 이전 작업처럼 정확성이 중요한 작업에는 가능하면 상위 모델을 사용하시는 것을 권장합니다.
이전 작업 시 AI API 토큰이 소모됩니다. 에이전트가 이전 작업을 수행하는 과정에서 AI 모델 API를 호출하며, 이에 따른 토큰 사용 비용은 고객님의 API 키로 과금됩니다. 이전 작업의 특성상 여러 단계의 명령 실행과 검증이 포함되므로, 일반 대화보다 토큰 소모가 클 수 있습니다.

2-2. 전체 순서

① 에이전트에게 이전 지시서 + 새 서버 정보 보내기 (텔레그램)
     ↓
② 에이전트가 자동으로 이전 작업 수행 (기다리기)
     ↓
③ 에이전트의 완료 보고 확인하기
     ↓
④ 기존 서버 서비스 끄기 (명령어 1개)
     ↓
⑤ 텔레그램에서 에이전트 응답 확인 → 완료!

2-3. Step 1 — 에이전트에게 이전 요청하기

텔레그램에서 에이전트에게 이전 지시서 + 새 서버 접속 정보를 한 번에 보내주세요.

보내는 방법

§4. 에이전트 지시서의 내용을 전체 복사합니다.
복사한 내용을 텔레그램 채팅에 붙여넣되, 맨 아래에 새 서버 접속 정보를 추가합니다.
[새서버IP]와 [새서버비밀번호]를 실제 정보로 바꾼 후 전송합니다.

추가할 접속 정보

지시서 내용 맨 아래에 아래 내용을 붙여넣으세요:

새 서버 접속 정보입니다:
IP: [새서버IP]
계정: root
비밀번호: [새서버비밀번호]

위 지시서대로 이전을 진행해주세요.

예시: IP가 123.456.789.10이고 비밀번호가 MyPass123이라면:

IP: 123.456.789.10
계정: root
비밀번호: MyPass123

2-4. Step 2 — 에이전트의 작업 완료를 기다리기

에이전트가 이전 작업을 시작하면, 진행 상황을 텔레그램으로 알려줄 수 있습니다. (에이전트에 따라 중간 보고 없이 진행될 수도 있습니다)

일반적인 경우 10~20분 정도 소요됩니다.

데이터가 많은 경우 (1GB 이상): 백업 생성과 전송에 시간이 더 걸릴 수 있습니다. 30분~1시간 이상 소요될 수 있으니 여유를 가지고 기다려주세요. 대용량 이전 안내는 §5-2를 참고하세요.

완료 보고를 받은 경우

에이전트가 지시서대로 작업을 수행하면 아래와 같은 형식으로 완료 보고를 합니다:

===== 이전 결과 보고 =====
상태: 완료

[이전 전] 크론 작업: 3개
[이전 후] 크론 작업: 3개
...
===========================

이 보고를 받으면 이전 전/후 수치가 동일한지 확인하세요.

에이전트가 위 형식과 다르게 보고할 수 있습니다. 지시서에 보고 형식이 지정되어 있지만, AI 에이전트가 이를 정확히 따른다는 보장은 없습니다. 형식이 달라도 크론 작업 수, 파일 수, 메모리 DB 크기가 이전 전과 같은지 확인할 수 있다면 문제 없습니다.

완료 보고가 불분명하거나 오지 않는 경우

에이전트가 완료 보고를 하지 않거나, 보고 내용이 불분명하여 이전이 정상 완료되었는지 알 수 없는 경우, 새 서버에 직접 접속하여 확인할 수 있습니다.

충분한 시간(20~30분)을 기다린 후 아래 명령어를 실행하세요:

ssh root@[새서버IP]

서비스 동작 확인:

su - openclaw -c "podman ps --filter name=openclaw-svc"

→ STATUS에 Up이 표시되면 서비스는 동작 중입니다.

데이터 이전 확인:

su - openclaw -c "podman exec openclaw-svc runuser -u node -- ls /data/.openclaw/workspace/ | wc -l"

→ 숫자가 나오면 데이터가 이전된 것입니다.

API 키 등록 확인:

su - openclaw -c "podman exec openclaw-svc runuser -u node -- cat /data/.openclaw/agents/main/agent/auth-profiles.json"

→ profiles 안에 API 키 정보가 있으면 등록된 것입니다. "profiles": \{\}처럼 비어 있으면 API 키가 아직 등록되지 않은 것이므로, 에이전트에게 "API 키 이전이 완료되었는지 확인해줘"라고 물어보세요.

비밀번호 파일 삭제 확인: 에이전트에게 비밀번호 파일(/tmp/.sshpw)이 삭제되었는지 직접 물어보세요. 확인이 안 되거나 불안하다면, 이전 완료 후 새 서버 비밀번호를 반드시 변경하세요. (§5-3. 보안 안내 참고)

에이전트가 오래 걸리거나 반복 실패하나요? 데이터 용량이 클수록 시간이 오래 걸리는 것은 정상입니다. 하지만 에이전트가 같은 에러로 3회 이상 반복 실패한다면, §3 (직접 이전)을 이용해주세요.

2-5. Step 3 — 기존 서버 서비스 끄기

반드시 Step 2의 완료 보고를 확인한 후에 진행하세요. 확인 전에 기존 서버를 끄면 양쪽 다 동작하지 않을 수 있습니다.

에이전트는 자기 자신이 동작하는 서비스를 직접 끌 수 없기 때문에, 이 단계만 고객님이 직접 해주셔야 합니다.

터미널(SSH) 접속 방법

Mac 사용자:

Spotlight (Cmd + Space)에서 "터미널" 검색 후 실행
아래 명령어 입력 (IP를 기존 서버 IP로 변경):

ssh root@[기존서버IP]

비밀번호 입력 (입력해도 화면에 표시되지 않는 것이 정상입니다)

Windows 사용자:

PuTTY 프로그램을 실행합니다 (없으면 putty.org에서 다운로드)
Host Name에 기존 서버 IP 입력
Open 클릭 후 비밀번호 입력

서비스 끄기

접속 후 아래 명령어를 입력하세요:

su - openclaw -c "podman stop openclaw-svc"

명령어 설명: su - openclaw은 서비스 관리 계정으로 전환하는 것이고, podman stop openclaw-svc는 OpenClaw 서비스를 안전하게 종료하는 명령입니다.

정상적으로 끝났는지 확인합니다:

su - openclaw -c "podman ps -a --filter name=openclaw-svc"

화면에 Exited라고 표시되면 정상적으로 종료된 것입니다.

2-6. Step 4 — 텔레그램에서 최종 확인하기

기존 서버를 껐으므로, 이제부터 에이전트는 새 서버에서 응답합니다.

텔레그램에서 에이전트에게 아무 메시지나 보내보세요:

안녕, 지금 몇 시야?

에이전트가 정상 응답하면 이전이 완료된 것입니다!

응답이 없다면 1~2분 기다려보세요. 새 서버에서 서비스가 초기화되는 데 시간이 걸릴 수 있습니다.

1~2분 후에도 응답이 없다면, 새 서버에 접속하여 서비스 상태를 확인하세요:

ssh root@[새서버IP]
su - openclaw -c "podman ps --filter name=openclaw-svc"

Up이라고 표시되면 서비스는 동작 중입니다. 잠시 더 기다려보세요. 서비스가 중단되어 있다면 아래 명령으로 시작합니다:

su - openclaw -c "podman start openclaw-svc"

2-7. 완료 체크리스트

에이전트에게 지시서 + 서버 정보 전달 완료
에이전트가 이전 완료 보고 (API 키 등록 포함)
데이터 수치 직접 비교 확인 (크론/파일/메모리)
기존 서버 서비스 종료 완료
텔레그램에서 에이전트 정상 응답 확인
새 서버 비밀번호 변경 완료 (§5-3. 보안 안내 참고)

3. 직접 이전 (터미널 사용)

터미널(SSH)에서 명령어를 직접 실행하여 이전합니다. 명령어를 복사해서 붙여넣기만 하면 됩니다.

3-1. 접속 정보 준비

아래 접속 정보를 준비해주세요. 서비스 가입 시 안내받은 정보입니다.

기존 서버 IP: _______________
기존 서버 비밀번호: _______________
새 서버 IP: _______________
새 서버 비밀번호: _______________

3-2. 전체 순서

① 기존 서버에 접속 → 현재 상태 확인
     ↓
② 백업 파일 만들기
     ↓
③ 백업 파일을 내 PC로 다운로드
     ↓
④ 내 PC에서 새 서버로 업로드
     ↓
⑤ 새 서버에서 복원 및 시작
     ↓
⑥ 정상 동작 확인
     ↓
⑦ LLM API 키 재등록
     ↓
⑧ 기존 서버 서비스 끄기
     ↓
⑨ 텔레그램에서 최종 확인 → 완료!

3-3. Step 1 — 기존 서버에 접속하기

서버에 접속하려면 터미널(SSH)이라는 프로그램을 사용합니다.

Mac 사용자:

Spotlight (Cmd + Space)에서 **"터미널"**을 검색하여 실행합니다
아래 명령어에서 [기존서버IP]를 실제 IP로 바꿔서 입력합니다:

ssh root@[기존서버IP]

비밀번호를 입력합니다

비밀번호를 입력할 때 화면에 아무것도 표시되지 않는 것이 정상입니다. 보이지 않아도 입력되고 있으니 끝까지 입력한 후 Enter를 누르세요.

Windows 사용자:

PuTTY 프로그램을 실행합니다 (없으면 putty.org에서 다운로드)
Host Name 칸에 기존 서버 IP를 입력합니다
Open 버튼을 누릅니다
login as: 에 root 입력, 이어서 비밀번호 입력

접속이 되었는지 확인합니다:

hostname

서버 이름이 출력되면 정상 접속된 것입니다.

3-4. Step 2 — 현재 상태 확인하기

이전 전 데이터 상태를 기록해둡니다. 나중에 이전이 잘 되었는지 비교할 때 사용합니다.

아래 명령어들을 하나씩 복사해서 붙여넣고 Enter를 누르세요.

예약 작업(크론) 확인:

su - openclaw -c "podman exec openclaw-svc runuser -u node -- openclaw cron list"

명령어가 길고 어려워 보이나요? 이해하지 않아도 괜찮습니다. 그대로 복사해서 붙여넣기만 하면 됩니다. 이 명령어는 "서비스 안에 들어가서 예약 작업 목록을 보여줘"라는 뜻입니다.

→ 화면에 예약 작업 목록이 나옵니다. 작업 수를 메모하세요: ___개

워크스페이스 파일 수 확인:

su - openclaw -c "podman exec openclaw-svc runuser -u node -- ls /data/.openclaw/workspace/ | wc -l"

→ 숫자가 나옵니다. 파일 수를 메모하세요: ___개

메모리 DB 크기 확인:

su - openclaw -c "podman exec openclaw-svc runuser -u node -- ls -lh /data/.openclaw/memory/main.sqlite"

→ 68K 또는 1.2M 같은 크기가 나옵니다. 크기를 메모하세요: ___

전체 데이터 크기 확인:

du -sh /opt/openclaw/data/.openclaw/

→ 전체 데이터 크기가 나옵니다. 메모하세요: ___

크기 읽는 법: K는 킬로바이트, M은 메가바이트, G는 기가바이트입니다. 예: 648K = 약 0.6MB, 150M = 150MB, 2.3G = 2.3GB

3-5. Step 3 — 백업 파일 만들기

기존 서버의 데이터를 하나의 압축 파일로 만듭니다.

tar -czf /tmp/openclaw-backup.tar.gz -C /opt/openclaw/data .openclaw/

이 명령어의 의미: tar -czf = 여러 파일을 하나로 묶어서 압축하기 / /tmp/openclaw-backup.tar.gz = 만들어질 파일 이름 / -C /opt/openclaw/data .openclaw/ = 이 폴더를 압축 대상으로 지정

데이터가 많은 경우 (1GB 이상): 압축에 수 분~수십 분이 걸릴 수 있습니다. 명령어 실행 후 커서가 다시 나타날 때까지 기다려주세요.

완료되면 파일을 확인합니다:

ls -lh /tmp/openclaw-backup.tar.gz

파일 크기가 표시되어야 합니다. 아무것도 안 나오면 백업이 실패한 것이니 명령어를 다시 실행해주세요.

파일 검증용 해시값을 확인합니다:

md5sum /tmp/openclaw-backup.tar.gz

해시값이란? 파일의 "지문" 같은 것입니다. 나중에 파일을 다운로드/업로드한 후 이 값이 같으면 파일이 손상되지 않은 것입니다.

→ 해시값을 메모하세요 (영문+숫자 조합): _______________

3-6. Step 4 — 백업 파일을 내 PC로 다운로드하기

기존 서버 터미널 창은 그대로 두세요. 닫지 마세요!

서버에서 파일을 다운로드하는 방법은 여러 가지가 있습니다. scp, sftp, FileZilla, WinSCP 등 편하신 방법을 사용하시면 됩니다.

Mac/Linux (scp 사용):

내 PC에서 새 터미널 창을 하나 더 열어주세요. (Mac: Cmd+N)

scp root@[기존서버IP]:/tmp/openclaw-backup.tar.gz ~/Desktop/

비밀번호를 입력하면 바탕화면에 파일이 다운로드됩니다.

Windows (WinSCP 또는 FileZilla 사용):

WinSCP(winscp.net) 또는 FileZilla(filezilla-project.org) 등 SFTP 클라이언트를 실행합니다
프로토콜: SFTP, 호스트: 기존 서버 IP, 사용자: root, 비밀번호 입력 후 접속
서버의 /tmp/ 폴더에서 openclaw-backup.tar.gz 파일을 내 PC 바탕화면으로 드래그합니다

데이터가 클 경우 예상 소요 시간:

100MB 이하: 1분 이내

100MB~~1GB: 수 분~~10분

1GB 이상: 10분 이상 소요될 수 있습니다

다운로드 중에는 터미널을 닫지 마세요. 진행률이 표시됩니다.

3-7. Step 5 — 새 서버로 업로드하기

Step 4에서 사용한 것과 같은 방법으로 새 서버에 파일을 업로드합니다.

Mac/Linux (scp 사용):

scp ~/Desktop/openclaw-backup.tar.gz root@[새서버IP]:/tmp/

Windows (WinSCP 또는 FileZilla 사용):

새 서버에 접속하여 바탕화면의 openclaw-backup.tar.gz 파일을 서버의 /tmp/ 폴더로 업로드합니다.

대용량 파일 업로드 시:

업로드 시간은 다운로드와 비슷하거나 더 오래 걸릴 수 있습니다

진행 중 네트워크가 끊기면 처음부터 다시 해야 합니다

안정적인 네트워크(유선 LAN 또는 안정적인 Wi-Fi)에서 진행하세요

업로드가 끝나면, 파일이 제대로 전송되었는지 확인합니다:

ssh root@[새서버IP] "md5sum /tmp/openclaw-backup.tar.gz"

→ 출력된 해시값이 Step 3에서 메모한 값과 같아야 합니다. 다르면 파일이 전송 중 손상된 것이므로 Step 4부터 다시 해주세요.

해시값 비교 방법: 해시값 전체를 비교하세요. 값이 완전히 동일하면 파일이 손상되지 않은 것입니다.

3-8. Step 6 — 새 서버에서 데이터 복원하기

새 서버에 접속합니다:

ssh root@[새서버IP]

반드시 기존 서버 터미널 창은 열어두세요! 문제가 생기면 기존 서버로 돌아가야 합니다. 터미널 창을 2개 열어놓은 상태가 됩니다.

아래 명령어를 순서대로 하나씩 실행하세요.

6-1. 서비스 잠시 멈추기

su - openclaw -c "podman stop openclaw-svc"

새 서버에서 돌아가고 있는 서비스를 잠시 멈추는 것입니다. 데이터를 교체하는 동안 충돌이 나지 않도록 하기 위함입니다.

6-2. 기존 데이터 보관하기 (안전장치)

[ -d /opt/openclaw/data/.openclaw ] && \
  mv /opt/openclaw/data/.openclaw /opt/openclaw/data/.openclaw.backup

혹시 모를 상황을 대비해서 새 서버에 있던 초기 데이터를 백업해둡니다.

6-3. 백업 데이터 복원하기

tar -xzf /tmp/openclaw-backup.tar.gz -C /opt/openclaw/data/

tar -xzf는 압축 파일을 풀어서 원래대로 복원하는 명령입니다.

"Cannot change mode" 경고가 나오나요? 정상입니다. 새 서버의 보안 설정 때문에 나타나는 메시지이며, 실제 파일 내용에는 전혀 영향 없습니다. 무시하고 다음으로 진행하세요.

6-4. 복원 확인하기

ls /opt/openclaw/data/.openclaw/

openclaw.json과 workspace라는 항목이 보이면 정상입니다. (표시되는 항목은 사용 상태에 따라 다를 수 있습니다)

6-5. 서비스 다시 시작하기

su - openclaw -c "podman start openclaw-svc"

10~20초 기다린 후 상태를 확인합니다:

su - openclaw -c "podman ps --filter name=openclaw-svc"

STATUS 열에 Up이라고 표시되면 정상입니다.

3-9. Step 7 — 새 서버가 제대로 동작하는지 확인하기

Step 2에서 메모한 값과 비교합니다. 아래 명령어를 하나씩 실행하세요.

예약 작업(크론) 확인:

su - openclaw -c "podman exec openclaw-svc runuser -u node -- openclaw cron list"

→ Step 2에서 메모한 작업 수와 같은가요?

워크스페이스 파일 수 확인:

su - openclaw -c "podman exec openclaw-svc runuser -u node -- ls /data/.openclaw/workspace/ | wc -l"

→ Step 2에서 메모한 파일 수와 같은가요?

메모리 DB 크기 확인:

su - openclaw -c "podman exec openclaw-svc runuser -u node -- ls -lh /data/.openclaw/memory/main.sqlite"

→ Step 2에서 메모한 크기와 같은가요?

3개 모두 일치하면 이전이 성공한 것입니다. 다음 단계로 진행하세요.

수치가 다르다면? 파일 전송 중 손상되었을 수 있습니다. Step 5에서 MD5 해시값이 일치했는지 확인 후, Step 4로 돌아가서 다시 진행해주세요.

3-10. Step 8 — LLM API 키 재등록하기

이전 후 AI 모델 API 키가 새 서버에서 인식되지 않을 수 있습니다. 새 서버 터미널 창에서 아래 명령을 실행하여 API 키를 다시 등록해주세요.

su - openclaw -c "podman exec -it openclaw-svc runuser -u node -- openclaw models auth paste-token --provider anthropic --agent main"

명령어 설명: 새 서버의 에이전트에 Anthropic API 키를 등록하는 명령입니다. 실행하면 API 키를 입력하라는 화면이 나옵니다. 기존에 사용하던 API 키를 붙여넣고 Enter를 누르세요.

기존 API 키를 모르시나요? 기존 서버 터미널 창에서 아래 명령으로 확인할 수 있습니다:

su - openclaw -c "podman exec openclaw-svc cat /data/.openclaw/api-keys.json"

다른 AI 제공사(OpenAI 등)를 사용하시는 경우: --provider anthropic 부분을 해당 제공사 이름으로 바꿔서 같은 방식으로 등록하세요.

3-11. Step 9 — 기존 서버 서비스 끄기

Step 7에서 3개 항목이 모두 일치하고, Step 8에서 API 키 등록을 완료한 후에만 이 단계를 수행하세요! 확인하지 않고 기존 서버를 끄면, 양쪽 다 동작하지 않을 수 있습니다.

기존 서버 터미널 창으로 돌아가서 아래 명령어를 실행합니다:

su - openclaw -c "podman stop openclaw-svc"

확인:

su - openclaw -c "podman ps -a --filter name=openclaw-svc"

STATUS에 Exited라고 표시되면 정상적으로 종료된 것입니다.

3-12. Step 10 — 텔레그램에서 최종 확인하기

기존 서버를 껐으므로, 이제 에이전트는 새 서버에서 응답합니다.

텔레그램에서 에이전트에게 아무 메시지나 보내보세요:

안녕, 지금 몇 시야?

에이전트가 정상 응답하면 이전이 완료된 것입니다!

응답이 없다면 1~2분 기다려보세요. 새 서버에서 서비스가 초기화되는 데 시간이 걸릴 수 있습니다.

3-13. Step 11 — 정리하기

이전에 사용한 임시 파일들을 삭제합니다. (선택사항이지만, 깔끔하게 정리하는 것을 권장합니다)

기존 서버 터미널 창에서 실행:

rm -f /tmp/openclaw-backup.tar.gz

새 서버 터미널 창에서 실행:

rm -f /tmp/openclaw-backup.tar.gz

내 PC 바탕화면의 백업 파일도 삭제합니다:

Mac: 바탕화면에서 openclaw-backup.tar.gz 파일을 휴지통에 넣기
Windows: 바탕화면에서 파일을 삭제

3-14. 완료 체크리스트

기존 서버 상태 메모 완료
백업 파일 생성 완료
내 PC로 다운로드 완료
새 서버로 업로드 완료
MD5 해시값 일치 확인
새 서버에 데이터 복원 완료
새 서버 서비스 정상 동작 (STATUS: Up)
예약 작업(크론) 수 일치
워크스페이스 파일 수 일치
메모리 DB 크기 일치
LLM API 키 재등록 완료
기존 서버 서비스 종료 완료
텔레그램 에이전트 정상 응답

3-15. 자주 하는 실수

실수	어떻게 되나요?	이렇게 하세요
Step 7 확인 전에 기존 서버를 끔	양쪽 다 안 될 수 있음	반드시 Step 7 완료 후 Step 9 수행
MD5 해시값 확인을 건너뜀	파일이 깨진 줄 모르고 복원	Step 5에서 반드시 해시값 비교
기존 서버 터미널을 닫아버림	문제 시 되돌리기 어려움	이전이 끝날 때까지 터미널 유지
불안정한 Wi-Fi에서 대용량 전송	전송 중단, 처음부터 다시	유선 LAN 또는 안정적인 네트워크 사용
노트북 절전 모드 진입	전송/접속 끊김	전원 연결 + 절전 해제

4. 에이전트 지시서

§2(간편 이전)에서 에이전트에게 보낼 지시서입니다. 아래 내용을 전체 복사하여 텔레그램에 붙여넣으세요.

이 지시서는 사람이 읽기 위한 것이 아니라, AI 에이전트가 읽고 수행하기 위한 것입니다. 내용이 어려워 보여도 괜찮습니다.

# OpenClaw 서버 이전 지시서 (에이전트용)

> 이 문서는 OpenClaw 에이전트가 서버 이전을 수행하기 위한 지시서입니다.
> 사용자가 이 문서와 함께 새 서버 접속 정보를 전달하면 아래 절차를 수행하세요.

---

## 필요한 정보

아래 정보가 모두 있는지 확인하세요. 하나라도 빠지면 사용자에게 요청하세요.

- 새 서버 IP
- 새 서버 root 계정 비밀번호

---

## 작업 규칙

1. **새 서버에서의 모든 데이터 작업은 반드시 `podman exec openclaw-svc` 를 통해 컨테이너 내부에서만 수행하세요.** 호스트 서버에서 직접 파일을 수정하거나 삭제하지 마세요.
2. 비밀번호는 파일로 저장하여 `sshpass -f` 로 사용하고, 작업 완료 후 즉시 삭제하세요.
3. 각 단계의 결과를 사용자에게 알기 쉽게 보고하세요.
4. 에러 발생 시 사용자에게 상황을 설명하고 재시도하거나 대안을 제시하세요.

---

## 절차

### 1단계: SSH 도구 설치

```
which ssh && which scp && which sshpass
```

없는 경우:

```
/usr/bin/apt-get update -qq
/usr/bin/apt-get install -y -qq openssh-client sshpass
```

### 2단계: 현재 데이터 상태 기록

이전 전 상태를 기록하세요. 이전 후 검증에 사용합니다.

```
echo "=== 크론 작업 ==="
openclaw cron list

echo "=== 워크스페이스 파일 ==="
ls -la /data/.openclaw/workspace/

echo "=== 메모리 DB ==="
ls -lh /data/.openclaw/memory/main.sqlite

echo "=== 전체 크기 ==="
du -sh /data/.openclaw/
```

결과를 사용자에게 보고하세요.

**전체 크기가 5GB를 초과하는 경우**, 사용자에게 아래를 안내하세요:
- 백업 및 전송에 상당한 시간이 소요될 수 있습니다
- 네트워크 상태에 따라 전송이 중단될 수 있으므로, 직접 이전(수동 이전)을 권장합니다

### 3단계: 백업 생성

```
tar -czf /tmp/openclaw-backup.tar.gz -C /data .openclaw/
ls -lh /tmp/openclaw-backup.tar.gz
md5sum /tmp/openclaw-backup.tar.gz
```

> **대용량 데이터인 경우:**
> - /tmp 공간이 부족할 수 있습니다. `df -h /tmp` 로 여유 공간을 먼저 확인하세요.
> - 여유 공간이 데이터 크기보다 작으면, 사용자에게 직접 이전(수동 이전)을 안내하세요.

### 4단계: 새 서버로 백업 전송

비밀번호를 파일에 저장한 후 SCP로 전송하세요.
전송 대상 경로는 반드시 `/opt/openclaw/data/` 입니다 (컨테이너 볼륨 마운트 경로).

```
echo "[비밀번호]" > /tmp/.sshpw
sshpass -f /tmp/.sshpw scp -o StrictHostKeyChecking=no \
  /tmp/openclaw-backup.tar.gz root@[새서버IP]:/opt/openclaw/data/
```

> **대용량 데이터 전송 시:**
> - 전송 진행률을 사용자에게 알려줄 수 없으므로, 미리 예상 소요 시간을 안내하세요.
> - 전송이 실패하면 재시도하세요. 반복 실패 시 사용자에게 직접 이전을 안내하세요.

### 5단계: 새 서버 컨테이너 내부에서 데이터 복원

SSH로 새 서버에 접속하되, 데이터 작업은 반드시 `podman exec`를 통해 컨테이너 내부에서 수행하세요.

```
sshpass -f /tmp/.sshpw ssh -o StrictHostKeyChecking=no root@[새서버IP] \
  'su - openclaw -c "podman exec openclaw-svc bash -c \"
    mv /data/.openclaw /data/.openclaw.backup 2>/dev/null;
    tar -xzf /data/openclaw-backup.tar.gz -C /data/;
    rm -f /data/openclaw-backup.tar.gz;
    echo RESTORE_COMPLETE
  \""'
```

> `Cannot change mode` 경고가 나올 수 있습니다. 이것은 새 서버의 보안 설정 때문이며, 파일 데이터 자체는 정상 복원됩니다. 무시하세요.

### 6단계: 새 서버 컨테이너 재시작

```
sshpass -f /tmp/.sshpw ssh -o StrictHostKeyChecking=no root@[새서버IP] \
  'su - openclaw -c "podman restart openclaw-svc"'
```

30초 정도 기다리세요.

### 7단계: 새 서버 검증

`podman exec`로 컨테이너 내부에서 데이터를 확인하세요.

```
sshpass -f /tmp/.sshpw ssh -o StrictHostKeyChecking=no root@[새서버IP] \
  'su - openclaw -c "podman exec openclaw-svc runuser -u node -- openclaw cron list"'

sshpass -f /tmp/.sshpw ssh -o StrictHostKeyChecking=no root@[새서버IP] \
  'su - openclaw -c "podman exec openclaw-svc runuser -u node -- ls /data/.openclaw/workspace/ | wc -l"'

sshpass -f /tmp/.sshpw ssh -o StrictHostKeyChecking=no root@[새서버IP] \
  'su - openclaw -c "podman exec openclaw-svc runuser -u node -- ls -lh /data/.openclaw/memory/main.sqlite"'
```

2단계에서 기록한 값과 비교하여 결과를 사용자에게 보고하세요.

### 8단계: API 키 이전

기존 서버의 `api-keys.json`에서 API 키를 읽어, 새 서버의 에이전트 인증 파일에 등록하세요.

```
# 1. 기존 서버(현재 컨테이너)에서 API 키 읽기
cat /data/.openclaw/api-keys.json
```

읽어온 API 키를 새 서버의 `auth-profiles.json`에 등록하세요.

`openclaw models auth` 명령은 권한 에러가 발생할 수 있으므로, 아래와 같이 Node.js로 직접 파일을 작성하세요.

```
sshpass -f /tmp/.sshpw ssh -o StrictHostKeyChecking=no root@[새서버IP] \
  'su - openclaw -c "podman exec openclaw-svc runuser -u node -- node -e \"
    const fs = require(\"fs\");
    const p = \"/data/.openclaw/agents/main/agent/auth-profiles.json\";
    const d = \{version:1, profiles:\{anthropic:\{token:\"[API_KEY]\"\}\}\};
    fs.writeFileSync(p, JSON.stringify(d, null, 2));
    console.log(\"API_KEY_REGISTERED\");
  \""'
```

> `[API_KEY]` 부분을 1번에서 읽어온 실제 API 키로 교체하세요.
> 다른 AI 제공사(OpenAI 등)도 사용하는 경우, profiles 안에 해당 제공사를 추가하세요.

등록 후 새 서버 컨테이너를 재시작하세요:

```
sshpass -f /tmp/.sshpw ssh -o StrictHostKeyChecking=no root@[새서버IP] \
  'su - openclaw -c "podman restart openclaw-svc"'
```

30초 정도 기다리세요.

### 9단계: 정리

```
rm -f /tmp/.sshpw
rm -f /tmp/openclaw-backup.tar.gz
```

### 10단계: 결과 보고

사용자에게 반드시 아래 형식으로 보고하세요. 형식을 정확히 지켜주세요:

```
===== 이전 결과 보고 =====
상태: 완료 (또는 실패)

[이전 전] 크론 작업: X개
[이전 후] 크론 작업: X개

[이전 전] 워크스페이스 파일: X개
[이전 후] 워크스페이스 파일: X개

[이전 전] 메모리 DB: XK
[이전 후] 메모리 DB: XK

API 키 등록: 완료 (또는 실패)
비밀번호 파일 삭제: 완료 (또는 실패)
===========================
```

보고 후 사용자에게 안내하세요:

**"이전이 완료되었습니다. 기존 서버의 서비스를 중단하려면 기존 서버에 SSH로 접속하여 아래 명령을 실행해주세요:**

```
su - openclaw -c "podman stop openclaw-svc"
```

**기존 서버를 끄기 전까지는 양쪽 서버 모두 동작하고 있으므로, 여유를 가지고 확인하신 후 끄셔도 됩니다."**

5. 문제 해결 및 대용량 이전 안내

5-1. 문제 해결

"Cannot change mode" 경고가 나왔습니다

정상입니다. 새 서버의 보안 설정 때문에 나타나는 메시지이며, 실제 데이터에는 영향이 없습니다. 무시하셔도 됩니다.

"podman: command not found" 에러가 나는 경우

root 계정에서는 podman 명령을 직접 사용할 수 없습니다. 반드시 su - openclaw -c "..." 형태로 실행해야 합니다. 명령어를 다시 확인하고, 가이드에 나온 형태 그대로 복사해서 사용해주세요.

에이전트가 새 서버에 접속하지 못합니다 (§2)

새 서버 IP와 비밀번호가 정확한지 다시 확인해주세요. 오타가 있을 수 있으니 한 글자씩 비교해보세요. 그래도 안 되면 §3 (직접 이전)을 이용해주세요.

텔레그램에서 에이전트가 응답하지 않습니다 (기존 서버 종료 후)

새 서버에 접속하여 서비스 상태를 확인합니다:

ssh root@[새서버IP]
su - openclaw -c "podman ps --filter name=openclaw-svc"

Up이라고 표시되면 서비스는 정상 동작 중입니다. 1~2분 후 다시 시도해주세요. 서비스가 중단되어 있다면 아래 명령으로 시작합니다:

su - openclaw -c "podman start openclaw-svc"

서비스가 시작되지 않는 경우 (STATUS가 Up이 아닌 경우)

아래 명령으로 로그를 확인합니다:

su - openclaw -c "podman logs --tail 30 openclaw-svc"

에러 내용을 확인한 후, 아래 이전을 취소하고 원래대로 돌아가고 싶은 경우를 참고하여 기존 서버로 복구한 뒤 다시 시도해주세요.

수치가 달라서 이전이 제대로 안 된 것 같은 경우 (§3)

Step 5에서 MD5 해시값이 일치했는지 확인해주세요. 해시값이 달랐다면 파일이 전송 중 손상된 것이므로 Step 3부터 다시 진행합니다. 해시값이 같았는데도 수치가 다르면 Step 6부터 다시 진행해주세요.

이전을 취소하고 원래대로 돌아가고 싶습니다

기존 서버를 아직 끄지 않았다면: 아무 조치도 필요 없습니다. 기존 서버가 계속 정상 동작 중입니다.

기존 서버를 이미 껐다면: 아래 명령으로 다시 시작할 수 있습니다:

ssh root@[기존서버IP]
su - openclaw -c "podman start openclaw-svc"

새 서버를 처음 상태로 되돌리려면:

주의: 아래 명령은 새 서버에 복원한 이전 데이터를 삭제합니다. 경로를 정확히 확인한 후 실행하세요. 잘못된 경로를 입력하면 복구할 수 없는 데이터 손실이 발생할 수 있습니다.

su - openclaw -c "podman stop openclaw-svc"
rm -rf /opt/openclaw/data/.openclaw
[ -d /opt/openclaw/data/.openclaw.backup ] && \
  mv /opt/openclaw/data/.openclaw.backup /opt/openclaw/data/.openclaw
su - openclaw -c "podman start openclaw-svc"

위 방법으로도 해결이 안 되는 경우: 나의 서비스 관리 > OS 재설치를 신청하면 서버가 초기 세팅 상태로 완전히 복구됩니다. (서비스 신청 후 7일 이내 무료 / 이후 유료 — 비용은 나의 서비스 관리에서 확인하세요) 단, OS 재설치 시 백업하지 않은 모든 데이터가 삭제되므로 반드시 백업 후 진행하세요.

5-2. 대용량 이전 안내

워크스페이스에 파일을 많이 저장해두셨거나, 오랫동안 사용하여 대화 기록이 많은 경우 데이터 용량이 클 수 있습니다.

데이터 크기	간편 이전 (§2) 예상 소요	직접 이전 (§3) 예상 소요	주의사항
100MB 미만	10~20분	20~30분	일반적인 경우. 특별한 조치 불필요
100MB ~ 1GB	20~40분	30분~1시간	전송 중 네트워크 끊김에 주의
1GB ~ 5GB	40분~2시간	1~3시간	유선 LAN 권장. 중간에 끊기지 않도록 주의
5GB 이상	§3 권장	3시간 이상	안정적인 유선 네트워크 필수

대용량 이전 시 주의사항:

안정적인 네트워크를 사용하세요. 카페 Wi-Fi 등 불안정한 환경에서는 전송이 중단될 수 있습니다.
노트북을 사용 중이라면 전원을 연결하세요. 전송 중 절전 모드에 들어가면 중단됩니다.
이전 중에는 기존 서버의 서비스를 끄지 마세요. 전송이 실패하더라도 기존 서버에는 영향이 없으니 안심하세요.
에이전트가 중간에 멈춘 것처럼 보여도, 대용량 파일 전송 중일 수 있으니 충분히 기다려주세요.
전송이 중단되면? §3의 경우 Step 3부터 다시 시작하면 됩니다. 기존 데이터는 그대로 있습니다.
5GB를 초과하는 경우, 에이전트(§2)가 시간 내에 전송을 완료하지 못할 수 있습니다. §3 (직접 이전)을 이용해주세요.
/tmp 공간이 부족하다는 메시지가 나오면? 기존 서버에서 불필요한 임시 파일을 삭제하거나, 백업 경로를 /tmp 대신 여유 공간이 있는 경로로 변경하세요.

5-3. 보안 안내

지시서에는 에이전트가 서비스 내부 영역에서만 작업하도록 안내되어 있으나, AI 에이전트의 행동을 100% 보장할 수는 없습니다. 에이전트가 예상과 다른 작업을 시도하거나 에러를 일으킬 가능성이 있습니다.
비밀번호 삭제도 지시서에 포함되어 있으나, 에이전트가 반드시 삭제한다고 보장할 수 없습니다.
따라서 이전 완료 후 새 서버의 비밀번호를 반드시 변경해주세요:

ssh root@[새서버IP]
passwd

(새 비밀번호를 2번 입력하면 변경됩니다)

이전 과정에서 예상과 다른 동작이 의심되면, 즉시 작업을 중단하고 §3 (직접 이전)을 이용해주세요.

지원 채널

이 가이드로 해결되지 않는 문제가 있다면 아래 채널로 문의해 주세요.

채널	연락처
카페24 고객센터 (전화)	1588-3284
카페24 고객센터 (온라인)	help.cafe24.com 내 1:1 문의
운영 시간	평일 09:00 ~ 18:00 (공휴일 제외)

목차