Claude Code Remote Control CCR v2 워커 등록 404 에러, 원인과 해결법

AWS Lightsail 같은 원격 서버에서 claude remote-control(축약형 claude rc)을 실행하다 보면, 화면에는 분명 Connected 상태가 떠 있는데도 로그 맨 위에 알 수 없는 에러 메시지가 함께 찍히는 경우가 있습니다.

[00:20:32] Error: CCR v2 worker registration failed for session cse_01VU2bmHb7HkdBxwLUfJfemv: Request failed with status code 404
[00:20:34] Environment preserved. Restart `claude remote-control` to reconnect existing sessions.
·✔︎· Connected · today-bullstocks
    Capacity: 0/32 · New sessions will be created in an isolated worktree

겉보기엔 정상적으로 연결된 것 같아서 그냥 넘기기 쉽지만, 이 에러는 나중에 모바일 앱이나 claude.ai/code에서 새 세션을 만들 때 예상치 못한 실패로 이어질 수 있는 “조용한 실패(silent failure)” 패턴입니다. 이번 글에서는 이 에러가 왜 발생하는지, 그리고 어떻게 해결하면 되는지 정리합니다.

왜 404 에러가 발생할까

claude remote-control은 기본적으로 서버를 시작할 때 세션 하나를 미리 생성(pre-create) 해두는 옵션이 켜져 있습니다. 이 사전 생성 세션이 CCR(Claude Code Remote) v2 워커로 등록되는 과정에서 요청이 404로 실패하면서 크래시가 발생하는 것입니다.

문제는 이 크래시가 remote-control 서버 자체의 실패는 아니라는 점입니다. 서버는 정상적으로 기동되고 QR 코드나 접속 URL도 정상 출력되기 때문에, 화면상으로는 Connected로 보입니다. 하지만 실제로는 미리 만들어 둔 세션 하나가 죽은 상태로 남아 있고, 이 과정에서 생성된 워크트리(worktree) 디렉토리가 정리되지 않고 잔재로 남을 수 있습니다.

이 잔재가 남아 있으면, 이후 모바일 앱 등에서 새 세션을 spawn할 때 .claude/worktrees 디렉토리가 이미 존재한다는 이유로 EEXIST 에러가 발생하며 세션 생성 자체가 막힐 수 있습니다. 즉 지금 당장은 문제가 없어 보여도, 누적되면 원격 접속 워크플로우 전체가 막히는 상황으로 이어질 수 있는 것입니다.

해결 방법 1: 사전 세션 생성 자체를 끄기

가장 근본적인 대응은 시작 시 세션을 미리 만들지 않도록 옵션을 끄는 것입니다.

claude remote-control --spawn same-dir --no-create-session-in-dir

--no-create-session-in-dir 옵션을 붙이면 서버가 시작할 때 세션을 자동으로 미리 만들지 않기 때문에, 애초에 404 크래시가 발생할 여지가 없어집니다. 재시작 후에는 Capacity: 0/32로 시작하는 게 정상이며, 실제로 접속해서 세션을 만들 때 정상적으로 카운트가 올라가는지 확인하면 됩니다.

해결 방법 2: –spawn 모드 선택하기

--spawn 옵션은 새 세션이 어떤 방식으로 생성될지를 결정합니다.

--spawn worktree: 세션마다 별도의 git 워크트리를 생성합니다. 여러 세션이 동시에 같은 파일을 건드릴 걱정 없이 독립적으로 작업할 수 있어 팀 협업에 유리하지만, 워크트리 관리 부담이 생깁니다.
--spawn same-dir: 모든 세션이 같은 디렉토리를 공유합니다. 혼자 여러 기기(PC, 모바일)로 오가며 하나의 작업을 이어서 할 때는 워크트리를 따로 만들 필요가 없어 더 단순합니다. 다만 여러 세션이 동시에 같은 파일을 수정하면 충돌할 수 있다는 점은 유의해야 합니다.

솔로 개발자가 하나의 프로젝트를 PC와 모바일을 오가며 이어서 작업하는 워크플로우라면, 굳이 워크트리를 분리할 이유가 없기 때문에 --spawn same-dir 쪽이 더 실용적입니다.

해결 방법 3: 이미 남아있는 워크트리 잔재 정리

혹시 이미 여러 번 크래시를 겪었다면, 잔재가 남아있는지 먼저 확인하는 것이 안전합니다.

git worktree list

bridge-cse_... 형태의 이름으로 시작하는 항목이 보인다면 아래처럼 정리합니다.

git worktree remove --force .claude/worktrees/bridge-cse_xxxxx
git worktree prune

명령이 실패하거나 애매하다면, 디렉토리를 통째로 지우고 다시 시작하는 편이 더 확실합니다.

rm -rf .claude/worktrees
claude remote-control --spawn same-dir --no-create-session-in-dir

재발 방지를 위한 alias 설정

매번 옵션을 다 타이핑하기보다, ~/.bashrc에 alias를 하나 걸어두면 편합니다.

alias claude-rc='claude remote-control --spawn same-dir --no-create-session-in-dir'

이렇게 해두면 claude-rc 한 줄로 항상 같은 옵션 조합으로 원격 제어 서버를 띄울 수 있어, 같은 에러를 반복해서 마주칠 일이 줄어듭니다.

정리

CCR v2 worker registration failed ... 404 에러는 remote-control 서버 자체의 실패가 아니라, 시작 시 자동으로 미리 만들어지는 세션 하나가 등록에 실패하면서 나는 에러다.
화면에 Connected가 떠 있어도 안심할 수 없으며, 워크트리 잔재가 쌓이면 이후 세션 생성이 막힐 수 있다.
--no-create-session-in-dir 옵션으로 사전 생성 자체를 끄는 것이 근본적인 해결책이다.
혼자 작업하는 환경이라면 --spawn same-dir로 워크트리 분리 없이 단순하게 운영할 수 있다.
이미 잔재가 있다면 git worktree list로 확인 후 git worktree remove 또는 디렉토리 삭제로 정리한다.

AWS Lightsail에서 tmux로 Claude Code를 상시 구동하며 모바일로 이어서 작업하는 분들이라면, 위 옵션 조합을 기본값으로 alias에 걸어두는 것을 추천합니다.

Claude Code claude rc 404 에러 CCR v2 워커 등록 실패 해결법