Claude Code Mac 데스크톱 + 원격 제어: CLI 사용자를 위한 가이드

Claude Code Mac 데스크톱 앱과 claude remote-control 서브커맨드는 같은 문제를 정반대 방향에서 해결합니다. 데스크톱 앱은 세 개의 탭(Chat, Cowork, Code)이 있는 창과 코드 주변에 배치할 수 있는 작업 공간을 제공합니다. Remote Control은 정확히 그 반대입니다. 로컬 머신에는 창이 전혀 없고, 휴대폰의 Claude 앱이나 모든 브라우저의 claude.ai/code에 로컬 세션을 제공하는 프로세스만 있을 뿐입니다.¹

터미널의 claude로 시작한 사용자라면 두 표면 모두 처음에는 낯설게 보입니다. TUI가 충분한데 왜 GUI가 필요할까요? Mac이 바로 여기 있는데 왜 휴대폰으로 Mac을 조종해야 할까요? 두 질문에 대한 답은 같습니다. 로컬 환경은 옮길 수 없는 부분이기 때문입니다. 파일시스템, MCP 서버(Yurei, Cloudflare, GitHub), Xcode, 코드 서명 ID, Yurei 소켓, ~/.claude/projects/ 히스토리. 이 모든 것이 머신에 존재합니다. 데스크톱 앱과 Remote Control은 그 환경에 다른 곳에서 접근하는 두 가지 방법입니다. 다른 창, 다른 기기, 소파, 회의실에서요.

이 글은 제가 전환할 때 있었으면 했던 레퍼런스입니다. 세 가지 모드(로컬 CLI, 클라우드, 로컬 + Remote Control), 각각의 설정 방법, 어디서 어떤 슬래시 명령이 작동하는지, 푸시 알림 동작 방식, 그리고 데스크톱 앱이 터미널의 claude와 갈라지는 구체적인 지점들을 다룹니다. 한계에 대해서는 솔직하게 말씀드립니다. 군더더기는 없습니다.

TL;DR

• claude.ai/code에서는 비슷해 보이지만 실행 방식은 매우 다른 세 가지 모드: 로컬 CLI, 클라우드 세션(터미널에서 claude --remote, 데스크톱의 Remote 환경, 또는 claude.ai/code에서 새 세션 시작), 그리고 로컬 + Remote Control. 첫 번째와 세 번째만 파일시스템, MCP 서버, Xcode에 접근할 수 있습니다.¹²
• Mac 데스크톱 앱의 Code 탭은 그래픽 인터페이스를 가진 Claude Code 세션입니다. CLI과 동일한 엔진, 동일한 ~/.claude.json 설정, 동일한 CLAUDE.md, 동일한 MCP 서버를 사용합니다. 다만 자체적인 패널 레이아웃, 사이드 채팅, 세션 사이드바를 가지고 있습니다.²
• claude remote-control(서버 모드)은 프로세스를 로컬에서 계속 실행시키면서 모든 기기에서 연결할 수 있게 해줍니다. claude --remote-control은 Remote Control이 활성화된 대화형 세션입니다. /remote-control은 기존 세션 내부에서 실행하는 슬래시 명령으로 같은 기능을 수행합니다.¹
• iOS 앱 푸시 알림은 /config → “Push when Claude decides”(v2.1.110+)를 통해 작동합니다. Claude는 긴 작업이 끝나거나 입력이 필요할 때 푸시를 보냅니다.¹³
• 네이티브 macOS 또는 iOS 빌드의 경우, 로컬 CLI 또는 로컬 + Remote Control이 실제로 작동하는 유일한 환경입니다. 클라우드 세션은 Xcode를 실행할 수 없고, 서명할 수 없으며, 로컬 Yurei 소켓을 볼 수 없습니다.²

중요한 세 가지 모드

같은 claude.ai/code URL, 같은 iOS 앱 아이콘이지만, 그 뒤에는 완전히 다른 세 가지 런타임 환경이 있습니다.

1. 로컬 CLI

이것이 터미널의 claude입니다. 프로세스는 Mac에서 실행됩니다. 세션은 Anthropic 계정이 아니라 디스크의 ~/.claude/projects/<project-path>/<session-id>.jsonl에 저장됩니다.⁴ iPhone에서는 볼 수 없습니다. 원격 표면이 없습니다.

얻는 것:

• 전체 파일시스템 접근: ~/Projects, ~/.claude/, 사용자가 읽기/쓰기 권한을 가진 모든 곳
• 모든 MCP 서버: Yurei(/tmp/yurei.sock), Cloudflare, GitHub, Supabase, Playwright 등
• Xcode, 시뮬레이터(xcrun simctl), 코드 서명 ID, App Store Connect
• 로컬에 설치된 플러그인, 스킬, 훅
• 음성 모드(/voice)
• 모든 CLI 플래그(--worktree, --rc, --print, --output-format 등)

얻지 못하는 것: 다른 기기에서 세션을 보거나 조종할 수 있는 어떤 방법도 없습니다.

Mac 앱 빌드(Return, Get Bananas, Water, App Intents와 MCP 서버 글의 앱들)에서는 로컬 CLI이 완벽하게 작동합니다. 로컬 + Remote Control(아래 3절에서 다룹니다)도 마찬가지입니다. 둘 다 Claude 프로세스를 Mac에 유지하므로 둘 다 Xcode, 시뮬레이터, 서명에 접근할 수 있습니다. Apple 툴체인을 실행할 수 없는 것은 클라우드 세션입니다.

2. 클라우드 세션

이것은 터미널에서 claude --remote "task"를 실행하거나, 데스크톱 앱 세션을 시작할 때 Remote를 선택하거나, 웹에서 claude.ai/code에 방문해 새 세션을 시작하는 것입니다. Claude Code 프로세스는 Anthropic의 관리형 클라우드 인프라에서 실행되며, 사용자의 머신에서 실행되지 않습니다.² (이전 문서와 셸 습관에서는 같은 결과를 위한 약식으로 & task를 보여주기도 합니다. 명시적인 --remote 플래그를 정식 형태로 취급하세요.)

얻는 것:

• 머신과 기기 간 영속성: iPhone, iPad, 브라우저에서 볼 수 있음
• 앱을 닫거나 노트북을 종료한 후에도 계속 실행됨
• Anthropic 관리형 환경, 로컬 설정 불필요
• 다중 저장소 지원: 클라우드 세션은 여러 GitHub 저장소를 같은 작업 공간으로 클론할 수 있습니다²

얻지 못하는 것:

• ~/Projects에 대한 파일시스템 접근 없음
• 로컬 MCP 서버 없음(Yurei 소켓, 로컬 Cloudflare 캐시 스크립트, .mcp.json의 커스텀 MCP에 도달할 수 없음)
• Xcode 없음, 시뮬레이터 없음, 서명 없음
• ~/.claude/ 설정이나 스킬을 볼 수 없음(클론된 저장소의 .claude/에 있는 것만)
• 파일을 @mention할 수 없음(@-자동완성은 로컬 프로젝트에서 가져옴, 클라우드 세션은 로컬 프로젝트가 없음)²

사용 사례: Apple 툴체인 의존성이 없는 자족적인 코딩 작업. PR 리뷰 열기, 테스트 스위트 실행, 파일 리팩토링, Python 스크립트 작성. git + 표준 Linux + Python/Node만 필요한 모든 작업.

3. 로컬 + Remote Control

이것이 세 번째 옵션이며, 대부분의 CLI 사용자가 간과하는 옵션입니다. 활성화하는 방법은 세 가지입니다: claude remote-control(서버 모드), claude --remote-control(또는 --rc, Remote Control이 켜진 대화형 세션), 또는 기존 세션 내부에서의 /remote-control. Claude Code 프로세스는 전체 로컬 접근 권한을 가진 채로 Mac에서 계속 실행되지만, Anthropic API에도 등록되어 iPhone, iPad, 또는 브라우저에서 조종할 수 있습니다.¹

얻는 것: 로컬 CLI이 가진 모든 것에 더해 프롬프트를 보낼 수 있는 휴대폰. 대화는 연결된 모든 기기에서 동기화 상태를 유지합니다. Mac 터미널에서 메시지를 보내고, iPhone에서 보고, iPhone에서 후속 입력을 하고, 다시 터미널에서 볼 수 있습니다. 로컬 프로세스가 여전히 작업을 수행하고 있습니다. 휴대폰은 그저 창일 뿐입니다.

포기하는 것: 작고 특정한 슬래시 명령 세트. 문서는 /mcp, /plugin, /resume이 로컬 전용임을 명시적으로 언급합니다(각각 터미널이 필요한 대화형 선택기를 엽니다). 문서는 텍스트 출력을 생성하고 모바일과 웹에서 작동하는 명령들을 명시적으로 나열합니다: /compact, /clear, /context, /usage, /exit, /extra-usage, /recap, /reload-plugins.¹

이것이 네이티브 macOS 또는 iOS 앱 빌드를 위한 답입니다. Xcode를 얻고, MCP를 얻고, Yurei 소켓을 얻고, 그리고 휴대폰 가시성도 얻습니다.

Mac 데스크톱 앱 설정하기

데스크톱 앱과 CLI은 대안이 아닙니다. 같은 엔진의 두 클라이언트입니다. 같은 머신에서, 심지어 같은 프로젝트에서도 둘을 동시에 실행할 수 있습니다. 각각 자체 세션 히스토리를 추적하지만, CLAUDE.md, ~/.claude.json, MCP 서버, 훅, 스킬은 공유합니다.²

claude.com/download에서 다운로드하세요. 설치하세요. claude.ai 계정으로 로그인하세요. 앱에는 세 개의 탭이 있습니다:²

• 일반 Claude 대화를 위한 Chat
• Dispatch(장기 실행 작업, 선택적으로 휴대폰에서 메시지 가능)를 위한 Cowork
• 그래픽 인터페이스가 있는 Claude Code를 위한 Code

우리가 관심을 가질 것은 Code 탭입니다. 사이드바의 + New session을 클릭하세요. 프롬프트 영역에서 네 가지를 구성합니다:²

1. Environment: Local(이 Mac), Remote(Anthropic 클라우드), 또는 SSH(직접 관리하는 원격 머신)
2. Project folder: Claude가 작업할 디렉토리
3. Model: Sonnet 4.6, Opus 4.6, Opus 4.7 등
4. Permission mode: Ask, Auto-accept edits, Plan, Auto, 또는 Bypass permissions

프롬프트를 입력하고 Enter를 누르세요. 여기서부터는 채팅 앱처럼 느껴집니다. 메시지가 쌓이고, 도구 호출이 접을 수 있는 카드로 렌더링되며, 파일이 변경되면 차이 통계 표시기(+12 -1)가 나타납니다. 표시기를 클릭하면 파일별 리뷰와 라인 단위 코멘트가 가능한 diff 뷰어가 열립니다.²

로컬 세션의 경우, 프롬프트 박스의 @ 키는 프로젝트의 파일 경로를 자동완성합니다. CLI의 @ 멘션과 동일합니다. 원격 세션의 경우, 클라우드 프로세스가 로컬 파일을 볼 수 없기 때문에 @가 비활성화됩니다.²

시작하기 전 요구사항

Remote Control 세션의 네 가지 사전 조건:¹

• Claude Code v2.1.51 이상(claude --version으로 확인).
• 구독: Pro, Max, Team, 또는 Enterprise. API 키는 지원되지 않습니다. Team과 Enterprise에서는 관리자가 먼저 claude.ai/admin-settings/claude-code의 Remote Control 토글을 활성화해야 합니다.
• 인증: 아직 하지 않았다면 claude를 실행하고 /login(claude.ai 옵션)을 사용하세요. claude setup-token이나 CLAUDE_CODE_OAUTH_TOKEN 환경 변수의 추론 전용 토큰은 작동하지 않습니다.
• 워크스페이스 신뢰: 프로젝트 디렉토리에서 claude를 최소 한 번 실행하고 워크스페이스 신뢰 대화상자를 수락하세요.

Remote Control 세션을 시작하는 네 가지 방법

현재 문서는 네 가지 호출 표면을 나열합니다(CLI에서 세 가지와 VS Code 명령). Mac 데스크톱 앱은 Remote Control 호스트가 아닙니다. Remote Control은 claude(CLI) 또는 VS Code 확장에 의해 호스팅됩니다.¹

서버 모드: claude remote-control

cd ~/Projects/blakecrosley.com
claude remote-control

터미널이 서버가 됩니다. 대화형 프롬프트는 없습니다. 세션 URL과 (스페이스바를 누르면) QR 코드가 표시됩니다. URL을 열거나 QR을 스캔하여 다른 기기에서 연결하세요. 세션이 활성화되어 있는 동안 터미널은 연결 상태와 도구 활동을 보여줍니다.

유용한 플래그:¹

• --name "My Project": claude.ai/code에서 보이는 커스텀 세션 제목
• --remote-control-session-name-prefix <prefix>: 자동 이름을 재정의(기본값은 머신의 호스트 이름으로, myhost-graceful-unicorn 같은 이름을 생성)
• --spawn same-dir(기본): 모든 세션이 현재 작업 디렉토리를 공유
• --spawn worktree: 각 세션이 자체 git worktree를 받음(git 저장소 필요), 런타임에서 w를 눌러 same-dir와 worktree 사이를 전환
• --spawn session: 단일 세션 모드, 추가 연결을 거부, 시작 시에만 설정
• --capacity N: 최대 동시 세션 수(기본값 32, --spawn=session과 결합 불가)
• --sandbox / --no-sandbox: 파일시스템과 네트워크 격리 토글(기본적으로 꺼져 있음)

서버 모드는 세션을 시작하고 떠나고 싶을 때 올바른 선택입니다. 이제 터미널은 작업 공간이 아니라 데몬입니다.

대화형: claude --remote-control

claude --remote-control
# 또는 짧게
claude --rc

일반 대화형 세션과 같지만 Remote Control이 켜져 있습니다. 메시지를 로컬에서 그리고 claude.ai/code 또는 iOS 앱에서 입력할 수 있습니다. 대화는 동기화 상태를 유지합니다. 선택사항: claude --rc "Project Name".

터미널에서 계속 작업하면서 휴대폰 가시성도 원할 때 사용하세요. 가장 일반적인 경우입니다.

슬래시 명령: /remote-control

이미 세션에 있고 이 대화에 특별히 Remote Control을 활성화하고 싶나요? /remote-control(또는 /rc)을 입력하세요. 현재 대화 히스토리가 이어지고 세션 URL + QR이 나타납니다. 이름을 전달하세요: /remote-control My Project.

--verbose, --sandbox, --no-sandbox 플래그는 슬래시 형태로는 작동하지 않습니다. claude remote-control(서버 모드)에서만 작동합니다.

VS Code 확장

Claude Code VS Code 확장에서 프롬프트 박스에 /remote-control(또는 /rc)을 입력하거나, /로 명령 메뉴를 열어 선택하세요. Claude Code v2.1.79 이상이 필요합니다.¹ 프롬프트 박스 위에 연결 상태를 보여주는 배너가 나타납니다. Open in browser를 클릭하여 세션으로 바로 이동하거나, claude.ai/code의 세션 목록에서 찾으세요. 배너의 닫기 아이콘을 클릭하거나 /remote-control을 다시 실행하여 연결을 끊으세요.

VS Code 명령은 이름 인수를 받지 않으며 QR 코드를 표시하지 않습니다. 세션 제목은 대화 히스토리 또는 첫 번째 프롬프트에서 파생됩니다.

항상 켜기: /config → “Enable Remote Control for all sessions”

모든 대화형 claude 세션이 기본적으로 원격 세션을 등록하도록 하려면, /config를 실행하고 Enable Remote Control for all sessions를 true로 토글하세요.¹ 각 대화형 프로세스는 하나의 원격 세션을 받습니다. 여러 인스턴스 → 여러 세션. 단일 프로세스에서 여러 동시 세션을 원한다면, 서버 모드가 여전히 올바른 도구입니다.

푸시 알림 동작 방식

흥미로운 일이 일어날 때 휴대폰으로 푸시. 설정은 네 단계입니다:¹³

1. iOS 또는 Android용 Claude 앱을 설치하세요. Claude Code 내부에서 /mobile은 아직 없다면 다운로드 QR 코드를 보여줍니다.
2. 터미널의 Claude Code에 사용하는 것과 같은 Claude 계정으로 로그인하세요.
3. OS 알림 권한 프롬프트를 수락하세요.
4. 터미널에서 /config를 실행하고 Push when Claude decides(v2.1.110+)를 활성화하세요.

그 후, Claude가 언제 푸시할지 결정합니다. 두 가지 경우가 트리거합니다: 장기 실행 작업이 끝나거나, Claude가 계속하기 위해 입력이 필요한 경우. 프롬프트에서 명시적으로 요청할 수도 있습니다: notify me when the tests finish. 이벤트별 구성은 없습니다. 켜져 있거나 꺼져 있을 뿐입니다.

설정을 켰지만 알림이 보이지 않는다면, 가장 일반적인 해결 방법은 휴대폰의 Claude 앱을 열어 푸시 토큰을 새로고침할 수 있게 하는 것입니다. /config 화면은 그런 일이 발생할 때까지 No mobile registered를 표시합니다. iOS 집중 모드와 Android 배터리 최적화도 전송을 지연시키거나 억제할 수 있습니다. iOS에서는 설정 → 알림 → Claude를 확인하거나, Android에서는 Claude 앱을 배터리 최적화에서 제외하세요.¹

배경 컨텍스트: 별도의 push-notification 도구(역시 v2.1.110+)는 Claude 자체가 작업 종료 시점뿐만 아니라 세션 중에도 알림을 보낼지 결정할 수 있게 해줍니다. 같은 Remote Control 표면과 짝을 이루며, 추가 설정이 필요 없습니다.³

원격으로 작동하는 슬래시 명령

이것이 대부분의 CLI 사용자가 신경 쓰는 부분입니다. 터미널 대신 휴대폰에서 입력할 때 무엇이 작동할까요?

연결된 모든 클라이언트(터미널, 브라우저, iOS 앱)에서 작동:¹

• /compact, /clear: 컨텍스트 관리
• /context, /usage, /extra-usage: 사용량과 컨텍스트 검사(v2.1.113+은 /extra-usage에 Remote Control 지원 추가)
• /exit, /recap, /reload-plugins
• 모든 비-선택기 텍스트 입력(일반 프롬프트, 텍스트 출력을 생성하는 일반 슬래시 명령)

로컬 전용(터미널만):¹

• /mcp: 대화형 선택기를 엽니다
• /plugin: 대화형 선택기를 엽니다
• /resume: 선택 UI가 있는 세션 목록을 렌더링해야 합니다

패턴: 터미널에서 키보드 선택이 있는 목록을 필요로 하는 모든 것은 로컬에 머무릅니다. 텍스트 입력 / 텍스트 출력인 모든 것은 모바일이나 웹에서 작동합니다.

일부 명령은 버전별 Remote Control 지원이 있습니다. /extra-usage는 v2.1.113 이상의 Remote Control 클라이언트에서만 작동합니다. 이전 버전은 조용히 실패했습니다.⁵ 명령이 휴대폰과 Mac에서 다르게 동작한다면 claude --version을 확인할 가치가 있습니다.

권한 모드는 약간 다릅니다

데스크톱 앱은 다섯 가지 권한 모드를 가지고 있습니다. CLI은 그 다섯 가지에 dontAsk을 더한 것을 가지고 있습니다:²

dontAsk은 CLI 전용입니다. 나머지 모두는 전송 버튼 옆의 UI 컨트롤로 매핑됩니다. CLI 플래그 --dangerously-skip-permissions는 Bypass permissions에 해당하며, 설정 → Claude Code → “Allow bypass permissions mode”를 통해 옵트인해야 합니다.²

Auto 모드는 Team/Enterprise/API에서 Claude Sonnet 4.6, Opus 4.6, 또는 Opus 4.7이 필요하고, Max에서는 Opus 4.7이 필요합니다. Pro 플랜이나 타사 제공자에서는 사용할 수 없습니다.²

Cowork 탭과 Dispatch (인접하지만 다름)

데스크톱 앱의 Cowork 탭은 사용성이 겹치는 다른 기능입니다. Dispatch는 “휴대폰에서 Claude에 작업을 메시지로 보내면, Claude가 작업을 직접 처리할지 아니면 Mac에서 Code 세션을 생성할지 결정합니다”입니다.²

페어링은 한 번만 일어납니다: Claude 모바일 앱을 설치하고, Cowork 탭을 통해 Mac에 연결하세요. 그 후, Dispatch에 작업을 텍스트로 보낼 수 있습니다(“로그인 버그를 수정하고, PR을 열어줘”) 그러면 작업을 라우팅합니다. 버그 수정, 의존성 업데이트, 테스트 실행, PR 생성은 일반적으로 사이드바에 Dispatch 배지가 있는 Mac의 Code 세션으로 끝납니다. 리서치, 문서 편집, 스프레드시트 작업은 Cowork에 머무릅니다.

Dispatch에서 생성된 Code 세션의 앱 승인 권한은 30분 후에 만료됩니다(일반 Code 세션의 경우 세션 동안 지속되는 것과 비교). 그래서 장기 실행 Dispatch 작업은 이미 승인한 앱 권한을 다시 묻을 수 있습니다.²

Dispatch는 Pro 또는 Max가 필요합니다. Team 또는 Enterprise에서는 사용할 수 없습니다.

이것은 Remote Control이 아닙니다. Dispatch는 “Claude에게 자율적으로 실행할 작업을 보내기”이고, Remote Control은 “이미 실행 중인 세션을 조종하기”입니다. 둘은 독립된 표면으로 문서화되어 있습니다: Remote Control은 CLI 또는 VS Code에 의해 호스팅되고, Dispatch는 데스크톱 Code 세션을 생성합니다. 그리고 문서는 현재 둘을 결합하는 것을 설명하지 않습니다. 위임하고 싶은지(Dispatch) 조종하고 싶은지(Remote Control)에 따라 하나를 선택하세요.

CLI에서 가져오는 것

데스크톱 앱은 CLI과 같은 구성 파일을 읽습니다:²

• 프로젝트의 CLAUDE.md와 CLAUDE.local.md
• MCP 서버를 위한 ~/.claude.json(전역)와 .mcp.json(프로젝트별)
• ~/.claude/settings.json 또는 .claude/settings.json에 정의된 훅과 스킬
• settings.json의 권한 규칙
• 사용 가능한 모든 모델

CLI 플래그 → 데스크톱 동등물:²

플래그할 가치가 있는 한 가지 구성 함정: Claude Desktop 채팅 앱(claude_desktop_config.json의 채팅 전용 클라이언트)과 Claude Code Desktop(우리가 이야기하는 개발자 클라이언트)은 다른 제품입니다. 채팅 앱용으로 구성된 MCP 서버는 Code 탭에 나타나지 않습니다. Code는 claude_desktop_config.json이 아니라 ~/.claude.json과 .mcp.json을 읽습니다.²

CLI → 데스크톱: 언제 옮길 것인가

데스크톱 앱은 CLI이 잘하지 못하는 세 가지에서 빛납니다:²

1. 나란히 있는 병렬 세션: 각 Code 탭 세션은 <project-root>/.claude/worktrees/에 자체 Git worktree를 가집니다. Ctrl+Tab / Ctrl+Shift+Tab으로 순환하세요. 다른 세션에서 테스트 스위트가 실행되는 동안 한 세션에서 리팩토링을 실행하고, ANSI 이스케이프 코드가 아니라 시각적으로 검토하세요.
2. 시각적 diff 리뷰: +12 -1 표시기를 클릭하세요. 라인에 코멘트를 다세요. Cmd+Enter로 Claude에게 코멘트를 다시 제출하세요. 터미널에서 인라인 diff를 읽는 것보다 낫습니다.
3. 임베디드 미리보기 패널: Claude는 dev 서버를 시작하고 임베디드 브라우저에서 실행 중인 앱을 열고, 스크린샷을 찍고, 클릭하고, 자체 변경사항을 검증할 수 있습니다. Auto-verify는 프로젝트별로 기본적으로 켜져 있습니다(.claude/launch.json에서 또는 Preview 드롭다운을 통해 토글).²

CLI은 여전히 다음에서 우위를 점합니다: 스크립팅(--print, --output-format), 자동화(cron 작업, CI), tmux/screen 워크플로우, 그리고 dontAsk 권한 모드가 필요한 모든 것.

컨텍스트를 잃지 않고 CLI 세션을 데스크톱으로 옮기려면, 터미널에서 /desktop을 실행하세요. 세션을 저장하고, 데스크톱 앱에서 열고, CLI을 종료합니다.²

한계와 함정

문서에서 가져온 실제 사항들:¹

• 대화형 프로세스당 하나의 원격 세션. 서버 모드 외부에서는 각 claude 호출이 하나의 원격 세션을 지원합니다. 여러 개가 필요하다면? claude remote-control(서버 모드)을 사용하세요.
• 로컬 프로세스가 계속 실행되어야 합니다. Remote Control은 claude CLI 프로세스 또는 VS Code 확장에 의해 호스팅됩니다. 터미널을 닫거나, VS Code를 종료하거나, claude 프로세스를 종료하면 원격 세션이 끝납니다. 터미널에서 분리된 모드는 없습니다.¹
• 10분 이상의 네트워크 중단은 세션을 종료시킵니다. Mac이 깨어 있어도 10분 동안 네트워크에 도달할 수 없을 수 있습니다. 그러면 프로세스가 종료되고 다시 시작해야 합니다.
• Ultraplan은 Remote Control 연결을 끊습니다. 둘 다 claude.ai/code 표면을 차지하며 한 번에 하나만 연결될 수 있습니다.
• Auto 모드는 최신 모델이 필요합니다. Max에서 Opus 4.7, Team/Enterprise/API에서 Sonnet 4.6, Opus 4.6, 또는 Opus 4.7. Pro에서는 안 됩니다.
• API 키와 추론 전용 토큰은 작동하지 않습니다. Remote Control은 전체 범위 claude.ai OAuth 로그인이 필요합니다. ANTHROPIC_API_KEY가 설정되어 있다면, 해제하세요. claude setup-token이나 CLAUDE_CODE_OAUTH_TOKEN로 인증했다면, claude auth login을 실행하여 새로고침하세요.
• Team과 Enterprise 관리자가 활성화해야 합니다. 기본적으로 꺼져 있습니다. 토글은 claude.ai/admin-settings/claude-code → Remote Control에 있습니다. 일부 데이터 보존 구성은 토글을 사용할 수 없게 만듭니다.

가장 일반적인 “왜 작동하지 않을까” 실패: 사용자가 추론 전용 토큰으로 로그인되어 있는 것입니다. “Remote Control requires a full-scope login token” 오류가 그 경우에 매핑됩니다. 해결: claude auth login하고 claude.ai 옵션을 선택하세요.¹

알아둘 가치가 있는 다른 문제 해결 사례

공식 문서는 초보자에게 실제 시간이 드는 몇 가지 다른 실패 모드를 다룹니다. 정리하자면:¹

• “Remote Control requires a claude.ai subscription”: claude.ai로 인증되지 않았습니다. ANTHROPIC_API_KEY가 설정되어 있다면, 먼저 해제한 다음 claude auth login하세요.
• “Unable to determine your organization for Remote Control eligibility”: 캐시된 계정 정보가 오래되었습니다. claude auth login을 실행하여 새로고침하세요.
• “Remote Control is not yet enabled for your account”: 환경에 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, 또는 CLAUDE_CODE_USE_FOUNDRY가 있는지 확인하세요. Remote Control은 claude.ai 인증이 필요합니다. 타사 제공자는 작동하지 않습니다. 해제하고 /logout 후 /login하세요.
• “Remote Control is disabled by your organization’s policy”: 문서에 따르면 세 가지 원인이 있습니다: (a) API 키나 Console 계정에 있음(claude.ai OAuth 사용), (b) Team/Enterprise 관리자가 토글을 활성화하지 않음, (c) 관리자 토글이 Remote Control과 호환되지 않는 데이터 보존 구성으로 인해 회색으로 표시됨(Anthropic 지원에 문의).
• “Remote credentials fetch failed”: 기본 오류를 보려면 --verbose로 다시 실행하세요: claude remote-control --verbose. 보통 로그인되지 않은 경우, 443에서 Anthropic API으로의 아웃바운드 HTTPS를 차단하는 방화벽, 또는 이전 세션 생성 실패(Session creation failed: see debug log를 찾으세요)입니다.
• 워크스페이스 신뢰 대화상자: Remote Control이 명확한 오류 없이 시작에 실패한다면, 프로젝트 디렉토리에서 claude를 최소 한 번 실행하고 워크스페이스 신뢰 대화상자를 수락하세요. Remote Control이 세션을 등록하기 전에 이 단계가 필요합니다.

CLI 사용자를 위한 결정 트리

실제 작업에 직면했을 때, 작업이 필요로 하는 것에 따라 모드를 선택하세요:

작업이 Apple 툴체인(Xcode, 시뮬레이터, 서명)을 필요로 하는가?
├── 예 → 로컬 CLI 또는 로컬 + Remote Control
│         (클라우드는 툴체인에 도달할 수 없음)
│
└── 아니오 → 로컬 MCP 서버(Yurei, Cloudflare 등)가 필요한가?
         ├── 예 → 로컬 CLI 또는 로컬 + Remote Control
         │
         └── 아니오 → 휴대폰에서 모니터링하거나 조종해야 하는가?
                  ├── 예 → 로컬 + Remote Control, 또는 클라우드 세션
                  │         (작업이 여러 시간 걸린다면 클라우드가 더 좋음)
                  │
                  └── 아니오 → 로컬 CLI이 적합

Mac/iOS 앱 개발은 내 앱들 대부분이 하는 일이며, 매번 맨 위 분기에 해당합니다. 클라우드 세션은 xcodebuild할 수 없고, 시뮬레이터와 통신할 수 없으며, 서명할 수 없습니다. Get Bananas의 MCP 확장, Yurei 기반 인구조사 스크립트, 또는 Apple 생태계 클러스터 작업의 경우, Apple 툴체인 의존성은 피할 수 없습니다. 로컬 + Remote Control은 그 툴체인과 휴대폰에서 보이는 표면을 모두 제공하는 유일한 경로입니다.

FAQ

같은 프로젝트에서 같은 머신에 CLI과 데스크톱 앱을 동시에 실행할 수 있나요?

네. 그들은 구성(CLAUDE.md, ~/.claude.json, MCP 서버, 훅, 스킬)을 공유하지만 별도의 세션 히스토리를 유지합니다.² iTerm에서 claude 세션을 가질 수 있고 데스크톱 앱에서 Code 탭 세션을 가질 수 있으며, 둘 다 같은 ~/Projects/blakecrosley.com을 가리키고, 둘 다 git에 쓸 수 있습니다. worktree를 사용하지 않는다면 병렬 쓰기에 주의하세요.

Mac이 절전 상태가 되면 Remote Control 세션은 어떻게 되나요?

머신이 다시 온라인 상태가 되면 세션이 자동으로 다시 연결됩니다. Mac이 깨어 있지만 약 10분 이상 네트워크에 도달할 수 없으면, 세션이 시간 초과되고 claude remote-control로 새 세션을 시작해야 합니다.¹

Remote Control은 & task(백그라운드) 구문과 함께 작동하나요?

& task와 Remote Control은 다른 표면입니다. & task는 클라우드 세션으로 작업을 보냅니다. Remote Control은 다른 기기에서 로컬 세션에 연결합니다. 둘 다 claude.ai/code의 세션 목록에 표시될 수 있지만, 클라우드 것은 Anthropic 인프라에서 실행되고 Remote Control 것은 사용자의 머신에서 실행됩니다.¹

타사 제공자(Bedrock, Vertex, Foundry)와 함께 Remote Control을 사용할 수 있나요?

아니요. Remote Control은 claude.ai 인증이 필요합니다. CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, 또는 CLAUDE_CODE_USE_FOUNDRY가 설정되어 있다면, 자격 검사가 “Remote Control is not yet enabled for your account”로 실패합니다. 해제하고 다시 실행하세요.¹

--remote-control과 claude remote-control의 차이점은 무엇인가요?

claude --remote-control(또는 --rc)은 Remote Control이 활성화된 일반 대화형 세션을 터미널에서 시작합니다. 로컬에서 그리고 다른 기기에서 입력할 수 있습니다. claude remote-control(플래그가 아닌 서브커맨드)은 서버 모드입니다: 터미널이 로컬 프롬프트 없이 서버가 되며, 연결 상태만 보여줍니다. 둘 다 기본적으로 하나의 원격 세션을 만들지만, 서버 모드는 --capacity나 --spawn을 통해 여러 개를 제공할 수 있습니다.¹

데스크톱 앱은 CLI처럼 스킬, 플러그인, 훅을 가지고 있나요?

네. 같은 스킬, 플러그인, 훅입니다. 데스크톱 앱은 CLI처럼 ~/.claude/settings.json과 프로젝트 수준의 .claude/settings.json을 읽습니다. 프롬프트 박스 옆의 + 버튼을 클릭하여 설치된 플러그인과 스킬을 탐색하세요. 플러그인은 원격(클라우드) 세션에서는 사용할 수 없지만 로컬 데스크톱 세션에서는 잘 작동합니다.²

왜 /mcp가 휴대폰에서 작동하지 않나요?

/mcp는 선택을 위한 터미널 전용 UI가 필요한 대화형 선택기를 엽니다. 로컬 전용입니다. /plugin과 /resume도 마찬가지입니다.¹ 텍스트 출력을 생성하는 모든 것(/compact, /clear, /context, /usage, /extra-usage, /exit, /recap, /reload-plugins)은 모바일과 웹에서 작동합니다.

무료 티어가 있나요, 아니면 모두 구독이 필요한가요?

Remote Control은 Pro, Max, Team, Enterprise 플랜에서 사용할 수 있습니다. API 키는 지원되지 않습니다. Team과 Enterprise에서는 사용자가 기능을 보기 전에 관리자가 claude.ai 관리자 설정에서 Remote Control 토글을 활성화해야 합니다.¹ 데스크톱 앱 자체는 무료로 다운로드할 수 있지만 사용하려면 claude.ai 로그인이 필요합니다.

가장 짧은 버전: 로컬 CLI이 기반입니다. 데스크톱 앱은 같은 기반을 위한 그래픽 클라이언트입니다. /remote-control은 그 기반을 휴대폰에서 도달할 수 있게 만드는 다리입니다. 작업이 필요로 하는 것과 사용자가 있는 곳에 따라 선택하세요.

참고 자료