---
name: claude-code-session
description: Claude Code Remote Control 세션을 다중 인스턴스로 관리. 프로필(이름↔workdir)을 등록해두고 자연어로 세션을 열고 닫고 목록을 본다. Use when the owner says "클로드 세션 열어줘"·"X 세션 열어줘"·"openclaw-2 닫아줘"·"세션 목록"·"프로필 추가/삭제/수정", or whenever a request needs a new Python script / debugging / refactoring that 클로 cannot safely do itself — queue a spec under `~/.openclaw/dev-requests/` then open a session so the owner can connect from a phone and have Claude Code handle it.
---

# Claude Code Remote Control 세션 (다중 세션 + 프로필)

## 데이터 모델

- **프로필**: 이름 ↔ workdir 매핑. `~/.openclaw/state/claude_sessions.json`에 JSON으로 저장. 첫 실행 시 `openclaw → ~/.openclaw` 자동 시드.
- **세션**: 프로필을 기반으로 떠있는 클로드 데몬. 기본 프로필은 라벨 `ai.claude-session.YYMMDD-<N>`로 생성한다. plist 파일 존재 = 등록됨, `launchctl print state=running` = 떠있음. 2026-05-20 이전 구형 `<profile>-<N>`, `openclaw-YYYYMMDD-<N>`, `oc-YY-MM-DD-<N>` 세션도 조회·종료 가능.
- **번호링**: `open` 호출 시 해당 프로필·날짜에서 빈 번호(1부터) 자동 할당. 닫으면 그 번호 재사용 가능.

## 툴

`scripts/session_tool.py` (Python) — 모든 동작은 이 툴 한 개로 처리. 클로는 자연어 요청을 아래 매핑으로 라우팅.

### 자연어 매핑

| 관리자님 발화 | 툴 호출 |
|---|---|
| "클로드 세션 열어줘" / "세션 열어줘" | `session_tool.py session open` (default profile=openclaw, `YYMMDD-N` 자동) |
| "X 세션 열어줘" | `session_tool.py session open X` (프로필 X 등록 전이면 안내, 오늘 날짜 + 빈 번호 자동) |
| "260520-2 닫아줘" / "클로드2 닫아줘" | `session_tool.py session close 260520-2` |
| "세션 목록" / "안 닫힌 세션" | `session_tool.py session list` |
| "260520-1 상태" | `session_tool.py session status 260520-1` |
| "프로필 목록" / "등록된 폴더" | `session_tool.py profile list` |
| "프로필 추가 X /path/to/X" | `session_tool.py profile add X /path/to/X` |
| "프로필 삭제 X" | `session_tool.py profile remove X` (활성 세션 있으면 거부) |
| "프로필 X 폴더 변경 /new/path" | `session_tool.py profile edit X /new/path` (활성 세션 있으면 거부) |

이름 매핑 주의: 관리자님이 "클로드N", "openclawN", "openclaw N" 등 다양하게 부르더라도 내부적으로는 오늘 날짜를 넣은 `YYMMDD-<N>` 형식으로 변환해서 호출 (예: 2026-05-20에 "클로드3" → `260520-3`). 단, 기존 구형 `<profile>-<N>`, `openclaw-YYYYMMDD-<N>`, `oc-YY-MM-DD-<N>` 세션명은 그대로 close/status 가능.

## 운영 메모

- 세션 plist는 ephemeral — `open` 시 `~/Library/LaunchAgents/ai.claude-session.YYMMDD-<N>.plist` 생성·bootstrap, `close` 시 bootout·plist 삭제. 따라서 LaunchAgents 폴더 스캔이 곧 활성 세션 목록.
- 모든 세션 `RunAtLoad=false`, `KeepAlive=false` (on-demand). 자동 종료 옵션은 미구현 (`claude remote-control` 본체가 idle timeout 미지원). 작업 끝나면 `close` 권장.
- 로그: `~/.openclaw/logs/claude-session-<session-name>.{log,err.log}`

## 레거시 세션과의 관계

- 기존 `ai.openclaw.claude-remote-control` (라벨: `openclaw`, plist: `ai.openclaw.claude-remote-control.plist`)는 본 툴이 건드리지 않음 — `ensure_session.sh`가 그대로 관리.
- `session_tool.py session list`에는 참고용으로 `openclaw (legacy)` 줄이 함께 표시됨 (running/stopped 상태만).
- 새로 다중 세션 운영하려면 본 툴(`session_tool.py`)만 쓰면 충분. 레거시 세션은 단일 세션으로 유지하거나 `ensure_session.sh close`로 정리해도 무방.

## 보안

- Remote Control 접속은 관리자님 Claude 구독 계정 인증 필수 — 외부망 노출 자동 차단
- 세션 workdir 안의 자격증명은 그 세션을 통해 모두 노출 가능 — 외부 프로젝트 디렉터리를 프로필로 등록할 때 그 디렉터리에 민감 자료가 있는지 확인 후 등록
- 작업 끝나면 `close` 권장 (분실·탈취 시 노출 창 최소화)

## 개발 요청 큐와의 연계

추가 진입점 신규 .py 작성·디버깅·리팩토링이 필요한 요청이 들어왔을 때(클로 본인이 직접 처리하면 검증·디버깅 사이클이 부족해 위험): 명세를 `~/.openclaw/dev-requests/<id>.md`에 큐잉한 뒤 `session open openclaw`로 정비공 세션을 띄우고, 관리자님께 "폰/웹에서 접속해서 dev-requests 처리 부탁드립니다" 안내. 또한 응답 안내 시 `~/.openclaw/dev-requests/`에 미처리 명세가 있으면 "대기 중인 개발 요청 N건" 함께 안내.
