# OpenClaw Migration Guide

이 문서는 현재 `~/.openclaw` 환경을 다른 PC로 옮길 때 필요한 최소/권장 절차를 정리한다.

## 목표

- OpenClaw 본체를 새 PC에 안정적으로 재설치
- 기존 workspace / custom project / 설정을 복원
- KIS 자동화(`projects/kis-trader`)와 MCP 구성 재연결
- 크론 작업 복원
- 로컬 모델/포트/경로 차이로 인한 오류를 줄임

---

## 권장 전략

통폴더 복사보다 아래 방식이 더 안정적이다.

1. **새 PC에 OpenClaw 본체 재설치**
2. **`~/.openclaw`에서 필요한 설정/문서/프로젝트만 복원**
3. **언어 런타임/의존성 재설치**
4. **크론/서비스 재등록**
5. **로컬 경로/포트/모델 설정 보정**
6. **각 MCP / 자동화 / 백업 스크립트 개별 점검**

---

## 반드시 확인할 환경 차이

다른 PC에서 자주 깨지는 원인:

- 절대경로 차이 (`/home/arin/...`)
- Node / npm / dotnet / python 버전 차이
- OpenClaw 버전 차이
- 로컬 llama.cpp 서버 포트 차이
- 인증/토큰/세션 파일 차이
- GUI/헤드리스 환경 차이
- 크론/서비스 미복원
- 방화벽/로컬 네트워크 차이

---

## 이식 우선순위

### 1. 가장 중요한 파일/폴더

- `~/.openclaw/openclaw.json`
- `~/.openclaw/cron/crontab.backup`
- `~/.openclaw/cron/jobs.json`
- `~/.openclaw/workspace/AGENTS.md`
- `~/.openclaw/workspace/SOUL.md`
- `~/.openclaw/workspace/USER.md`
- `~/.openclaw/workspace/MEMORY.md`
- `~/.openclaw/workspace/memory/*.md`
- `~/.openclaw/workspace/acpx.json`
- `~/.openclaw/workspace/projects/kis-trader/`
- `~/.openclaw/workspace/projects/mcp_sshterminal/`
- `~/.openclaw/workspace/KIS_MCP_Server/`

### 2. 선택 복원

- `~/.openclaw/subagents/runs.json`
- `~/.openclaw/agents/main/agent/models.json`

### 3. 보통 재생성/재설정 권장

- `.venv`
- `__pycache__`
- `price_logs/`
- sqlite / 세션 transcript / 캐시류
- token/env 파일

---

## 새 PC 복원 절차

### Step 0. 압축 복사만으로 끝나지 않는 이유

`~/.openclaw`만 복사해도 다음은 자동으로 복구되지 않을 수 있다.

- 전역 npm 패키지 경로
- OpenClaw 본체 설치 경로
- OpenClaw 확장(plugin) 설치 경로
- Node / npm / dotnet / python 런타임
- 시스템 크론 등록 상태
- 로컬 GUI / 브라우저 실행 환경

즉, **압축 파일은 데이터/설정 복원용**이고, 실제 실행 가능 상태로 만들려면 아래 추가 셋업을 다시 해야 한다.

### Step 1. OpenClaw 설치

새 PC에서 OpenClaw를 먼저 설치한다.

- Node / npm 준비
- OpenClaw 설치
- 실행 파일/서비스 기본 동작 확인

권장 확인:

```bash
which openclaw
npm root -g
openclaw status
```

정상 응답이 먼저 나와야 한다.

---

### Step 2. `.openclaw` 기본 구조 복원

기존 백업에서 다음을 새 PC `~/.openclaw`로 복사:

- `openclaw.json`
- `cron/`
- `workspace/`
- `agents/main/agent/models.json` (선택)

주의:
- 통째로 덮어쓰기보다 필요한 파일/폴더를 선별 복사하는 편이 안전함

---

### Step 3. 경로 보정

현재 설정은 `/home/arin/...` 절대경로를 많이 사용한다.
새 PC 사용자명이 다르면 아래를 전부 점검해야 한다.

주요 위치:

- `~/.openclaw/openclaw.json`
- `~/.openclaw/workspace/acpx.json`
- `~/.openclaw/workspace/projects/kis-trader/*.sh`
- `~/.openclaw/workspace/projects/kis-trader/*.py`
- `~/.openclaw/cron/crontab.backup`

추천 검사:

```bash
grep -RIn '/home/arin' ~/.openclaw
```

---

### Step 3-1. 플러그인 / 확장 복원 (중요)

현재 환경은 OpenClaw 본체 외에 **ACPX 확장 플러그인**에 의존한다.
플러그인 오류가 많이 났다면 이 단계가 빠졌을 가능성이 높다.

현재 기준 경로:

- OpenClaw 전역 설치 경로 예시:
  - `/home/arin/.npm-global/lib/node_modules/openclaw`
- ACPX 확장 경로:
  - `/home/arin/.npm-global/lib/node_modules/openclaw/extensions/acpx`

`openclaw.json`에 실제로 박혀 있는 설정도 다음을 기대한다.

- `plugins.allow = ["acpx", "telegram"]`
- `plugins.load.paths = ["/home/arin/.npm-global/lib/node_modules/openclaw/extensions/acpx"]`
- `plugins.entries.acpx.enabled = true`
- `plugins.entries.telegram.enabled = true`

즉 새 PC에서 사용자 홈/전역 npm 경로가 달라지면, 아래 둘 중 하나를 해야 한다.

1. **같은 경로 구조로 OpenClaw 재설치**
2. 또는 `openclaw.json`의 `plugins.load.paths`, `plugins.installs.acpx.*`를 새 경로로 수정

권장 확인:

```bash
npm root -g
ls -la $(npm root -g)/openclaw
ls -la $(npm root -g)/openclaw/extensions/acpx
```

만약 ACPX가 없다면, 새 PC에서 OpenClaw 설치가 불완전하거나 설치 경로가 달라진 것일 수 있다.

### Step 3-2. 추가 런타임/CLI 의존성

현재 구성은 다음 외부 런타임/도구를 기대한다.

- `node`, `npm`, `npx`
- `python3`
- `.NET 9 SDK`
- `git`
- `cron` (`crontab`)

그리고 MCP/브리지용으로 다음 npm 실행형이 실제로 사용된다.

- `@playwright/mcp`
- `mcp-remote`

이 둘은 `npx -y ...`로 실행하므로 전역 설치가 꼭 필요하진 않지만,
새 PC에서 네트워크/패키지 접근이 안 되면 최초 실행에 실패할 수 있다.

권장 확인:

```bash
node -v
npm -v
npx -y @playwright/mcp@latest --version || true
npx -y mcp-remote https://example.com/sse || true
python3 --version
dotnet --info
git --version
crontab -l || true
```

### Step 4. 로컬 모델 포트 점검

현재 로컬 llama.cpp 매핑은 다음 기준이다.

- `llamacpp-8080/qwen3-8b-q4km`
- `llamacpp-8081/qwen2.5-72b-q4km`
- `llamacpp-8082/qwen2.5-coder-32b-q4km`
- `llamacpp-8083/deepseek-r1_q4km`

새 PC에서 동일 포트/모델로 띄우지 않으면 `openclaw.json`의 모델 설정을 수정해야 한다.

점검:

```bash
curl http://llama:8080/v1/models
curl http://llama:8081/v1/models
curl http://llama:8082/v1/models
curl http://llama:8083/v1/models
```

현재 운영 환경에서는 로컬 모델 서버가 같은 머신의 `127.0.0.1`가 아니라,
호스트명 `llama`로 붙어 있는 별도 머신/서비스일 수 있다. 따라서 새 PC 복원 시에는
`openclaw.json`의 provider baseUrl이 실제 환경과 맞는지 함께 확인한다.

---

### Step 5. Python / .NET / Node 의존성 재설치

#### KIS_MCP_Server

```bash
cd ~/.openclaw/workspace/KIS_MCP_Server
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .
```

또는 프로젝트 문서 기준 재설치.

#### mcp_sshterminal

`.NET 9 SDK` 필요.

```bash
cd ~/.openclaw/workspace/projects/mcp_sshterminal
dotnet restore
dotnet build -c Release
```

#### Playwright MCP / mcp-remote

`npx` 기반이므로 Node/npm 동작만 정상이면 즉시 재사용 가능.

---

### Step 6. 크론 복원

현재 크론은 다음 계열 작업을 포함한다.

- `kis-trader` collector/watcher 자동 재시작
- 30분마다 git 자동 백업 push

백업된 crontab 확인:

```bash
cat ~/.openclaw/cron/crontab.backup
```

복원 예시:

```bash
crontab ~/.openclaw/cron/crontab.backup
crontab -l
```

주의:
- 경로가 달라졌다면 `crontab.backup` 내용을 먼저 수정한 뒤 등록할 것

---

### Step 7. KIS 자동화 점검

확인 항목:

- `projects/kis-trader/start_price_collector.sh`
- `projects/kis-trader/start_alert_watcher.sh`
- `strategy_config.json`
- `monitor_config.json`
- `acpx.json`의 KIS MCP 설정

수동 점검:

```bash
bash ~/.openclaw/workspace/projects/kis-trader/start_price_collector.sh
bash ~/.openclaw/workspace/projects/kis-trader/start_alert_watcher.sh
ps -ef | grep kis-trader
```

로그 확인:

```bash
tail -n 50 ~/.openclaw/workspace/projects/kis-trader/price_logs/collector.log
tail -n 50 ~/.openclaw/workspace/projects/kis-trader/price_logs/alert_watcher.log
```

---

### Step 8. MCP 서버 점검

현재 `workspace/acpx.json` 기준으로 등록되는 MCP는 다음 3개다.

- `KIS MCP Server`
- `Playwright MCP`
- `SSH Terminal MCP`

#### KIS MCP

실행 기대값:

- Python venv 존재:
  - `~/.openclaw/workspace/KIS_MCP_Server/.venv/bin/python`
- 엔트리포인트:
  - `~/.openclaw/workspace/KIS_MCP_Server/server.py`

확인:

```bash
ls -l ~/.openclaw/workspace/KIS_MCP_Server/.venv/bin/python
python3 -m py_compile ~/.openclaw/workspace/KIS_MCP_Server/server.py
```

주의:
- 해외주식 현재가 조회는 나스닥 시장코드 `NAS` 사용 권장
- 현재 로컬 수정으로 `NASD`도 내부 alias 처리되지만, 새 PC에서 파일이 최신인지 확인할 것

#### Playwright MCP

등록 형식:
- `npx -y @playwright/mcp@latest --isolated --output-dir ...`

주의:
- GUI 환경에서 화면이 보여야 하면 headless 옵션 제거 상태인지 확인
- Linux에서 실제 창이 보여야 한다면 X/Wayland GUI 세션이 살아 있어야 함
- 단순 서버 기동만으로는 충분하지 않고, **MCP 클라이언트 세션이 살아 있어야 브라우저 창이 유지**된다

#### SSH Terminal MCP

이 프로젝트는 **직접 stdio MCP가 아니라 HTTP MCP 서버**다.
따라서 `acpx.json`에는 서버 실행 명령 자체가 아니라, `mcp-remote` 브리지를 통해 등록한다.

실서버:
- `http://127.0.0.1:5057/mcp`

실행 프로젝트:
- `~/.openclaw/workspace/projects/mcp_sshterminal/McpSshTerminal.App`

서버 수동 실행 예시:

```bash
cd ~/.openclaw/workspace/projects/mcp_sshterminal/McpSshTerminal.App
dotnet build -c Release
dotnet run -c Release
```

확인:

```bash
curl http://127.0.0.1:5057/api/config-path
```

OpenClaw 등록:
- `npx -y mcp-remote http://127.0.0.1:5057/mcp --allow-http`

중요:
- 왜 `dotnet run ...`이 아니라 `npx mcp-remote ...`가 `acpx.json`에 들어가 있는지 혼동하기 쉬움
- 이유는 `acpx.json`의 `mcpServers`가 사실상 **로컬 stdio command 형식**을 기대하고, `mcp_sshterminal`은 **HTTP MCP 서버**이기 때문
- 즉:
  - `dotnet run ...` = 실제 HTTP MCP 서버 실행
  - `mcp-remote ...` = OpenClaw가 붙기 위한 stdio 브리지

---

## 이식 후 추천 점검 순서

1. `openclaw status`
2. `npm root -g` / OpenClaw 설치 경로 확인
3. `openclaw.json` 안의 `plugins.load.paths` / `plugins.installs.acpx.sourcePath` 경로 확인
4. 로컬 모델 포트 확인
5. `acpx.json` JSON 문법 확인
6. KIS MCP 수동 호출 확인
7. Playwright MCP initialize / tools/list 확인
8. `mcp_sshterminal` HTTP MCP 확인
9. 크론 등록 확인
10. git backup 스크립트 수동 실행 확인

---

## 문제 발생 시 우선 로그

- `~/.openclaw/openclaw.json`
- `~/.openclaw/cron/crontab.backup`
- `~/.openclaw/workspace/projects/kis-trader/price_logs/collector.log`
- `~/.openclaw/workspace/projects/kis-trader/price_logs/alert_watcher.log`
- `~/.openclaw/workspace/projects/mcp_sshterminal/mcp_sshterminal.log`

그리고 다음을 같이 확인:

```bash
openclaw status
npm root -g
crontab -l
ps -ef | grep -E 'kis-trader|McpSshTerminal.App|playwright|mcp-remote'
grep -RIn 'plugins' ~/.openclaw/openclaw.json
```

플러그인 관련 오류가 많이 난다면 특히 아래를 먼저 의심할 것:

1. OpenClaw 본체 설치 경로가 달라짐
2. `extensions/acpx`가 실제로 존재하지 않음
3. `openclaw.json`의 `plugins.load.paths`가 옛 PC 경로를 가리킴
4. `npx`/`node`가 새 PC에서 안 잡힘
5. `dotnet`이 없어 `mcp_sshterminal`이 안 뜸
6. GUI가 없어 Playwright headed 브라우저가 표시되지 않음

---

## 운영 원칙

- 통복사보다 **재설치 + 설정/프로젝트 복원**이 더 안정적
- 절대경로는 이식 시 항상 재검토
- 토큰/세션/캐시는 되도록 재생성
- 커스텀은 `workspace/projects/` 기준으로 분리 유지
- KIS 원본 repo와 커스텀 자동화는 개념적으로 분리하되, 이제 backup git에는 둘 다 포함 가능