Claude Code Desktop 사용하기

Claude Desktop 앱 내의 Code 탭을 사용하면 터미널 대신 그래픽 인터페이스를 통해 Claude Code를 사용할 수 있습니다. Desktop은 표준 Claude Code 경험 위에 다음과 같은 기능을 추가합니다:

시각적 diff 검토 (인라인 댓글 포함)
라이브 앱 미리보기 (개발 서버 포함)
컴퓨터 사용 (macOS에서 앱을 열고 화면을 제어)
GitHub PR 모니터링 (자동 수정 및 자동 병합)
병렬 세션 (자동 Git worktree 격리)
Dispatch 통합: 휴대폰에서 작업을 보내고 여기서 세션을 받습니다
예약된 작업 (Claude를 반복 일정으로 실행)
커넥터 (GitHub, Slack, Linear 등)
로컬, SSH, 클라우드 환경

Desktop을 처음 사용하시나요? 시작하기에서 앱을 설치하고 첫 번째 편집을 해보세요.

이 페이지는 코드 작업, 컴퓨터 사용, 세션 관리, Claude Code 확장, 예약된 작업, 구성을 다룹니다. 또한 CLI 비교와 문제 해결도 포함되어 있습니다.

세션 시작하기

첫 번째 메시지를 보내기 전에 프롬프트 영역에서 네 가지를 구성하세요:

환경: Claude가 실행되는 위치를 선택합니다. 자신의 머신의 경우 Local, Anthropic 호스팅 클라우드 세션의 경우 Remote, 관리하는 원격 머신의 경우 SSH 연결을 선택합니다. 환경 구성을 참조하세요.
프로젝트 폴더: Claude가 작업할 폴더 또는 저장소를 선택합니다. 원격 세션의 경우 여러 저장소를 추가할 수 있습니다.
모델: 전송 버튼 옆의 드롭다운에서 모델을 선택합니다. 세션이 시작되면 모델이 잠깁니다.
권한 모드: 모드 선택기에서 Claude가 가질 자율성을 선택합니다. 세션 중에 이를 변경할 수 있습니다.

작업을 입력하고 Enter를 눌러 시작합니다. 각 세션은 자신의 컨텍스트와 변경 사항을 독립적으로 추적합니다.

코드 작업하기

Claude에게 올바른 컨텍스트를 제공하고, 자동으로 수행할 작업의 양을 제어하고, 변경 사항을 검토합니다.

프롬프트 상자 사용하기

Claude가 수행할 작업을 입력하고 Enter를 눌러 보냅니다. Claude는 프로젝트 파일을 읽고, 변경 사항을 만들고, 권한 모드에 따라 명령을 실행합니다. 언제든지 Claude를 중단할 수 있습니다: 중지 버튼을 클릭하거나 수정 사항을 입력하고 Enter를 누릅니다. Claude는 작업을 중지하고 입력에 따라 조정합니다. 프롬프트 상자 옆의 + 버튼을 클릭하면 파일 첨부, skills, 커넥터, 플러그인에 액세스할 수 있습니다.

프롬프트에 파일 및 컨텍스트 추가하기

프롬프트 상자는 외부 컨텍스트를 가져오는 두 가지 방법을 지원합니다:

@mention 파일: @ 다음에 파일 이름을 입력하여 파일을 대화 컨텍스트에 추가합니다. Claude는 그 파일을 읽고 참조할 수 있습니다. @mention은 원격 세션에서 사용할 수 없습니다.
파일 첨부: 첨부 버튼을 사용하여 이미지, PDF 및 기타 파일을 프롬프트에 첨부하거나, 파일을 프롬프트에 직접 드래그 앤 드롭합니다. 이는 버그 스크린샷, 디자인 목업 또는 참고 문서를 공유하는 데 유용합니다.

권한 모드 선택하기

권한 모드는 세션 중에 Claude가 가질 자율성을 제어합니다: 파일 편집, 명령 실행 또는 둘 다 전에 묻는지 여부입니다. 전송 버튼 옆의 모드 선택기를 사용하여 언제든지 모드를 전환할 수 있습니다. Claude가 수행하는 작업을 정확히 보기 위해 권한 요청으로 시작한 다음, 편하면 자동 수락 편집 또는 Plan mode로 이동합니다.

모드	설정 키	동작
권한 요청	`default`	Claude는 파일을 편집하거나 명령을 실행하기 전에 요청합니다. diff를 보고 각 변경 사항을 수락하거나 거부할 수 있습니다. 새 사용자에게 권장됩니다.
자동 수락 편집	`acceptEdits`	Claude는 파일 편집을 자동으로 수락하지만 터미널 명령 실행 전에는 여전히 요청합니다. 파일 변경을 신뢰하고 더 빠른 반복을 원할 때 사용합니다.
Plan mode	`plan`	Claude는 코드를 분석하고 파일을 수정하거나 명령을 실행하지 않고 계획을 만듭니다. 먼저 접근 방식을 검토하려는 복잡한 작업에 좋습니다.
Auto	`auto`	Claude는 요청과의 정렬을 확인하는 백그라운드 안전 검사를 통해 모든 작업을 실행합니다. 감시를 유지하면서 권한 프롬프트를 줄입니다. 현재 연구 미리보기입니다. Team 계획에서 사용 가능합니다 (Enterprise는 곧 출시). Claude Sonnet 4.6 또는 Opus 4.6이 필요합니다. Settings → Claude Code에서 활성화합니다.
권한 무시	`bypassPermissions`	Claude는 권한 프롬프트 없이 실행되며, CLI의 `--dangerously-skip-permissions`와 동일합니다. Settings → Claude Code에서 “권한 무시 모드 허용”에서 활성화합니다. 샌드박스 컨테이너 또는 VM에서만 사용합니다. 엔터프라이즈 관리자는 이 옵션을 비활성화할 수 있습니다.

dontAsk 권한 모드는 CLI에서만 사용 가능합니다.

복잡한 작업을 Plan mode에서 시작하여 Claude가 변경하기 전에 접근 방식을 매핑하도록 합니다. 계획을 승인한 후 자동 수락 편집 또는 권한 요청으로 전환하여 실행합니다. 이 워크플로우에 대한 자세한 내용은 먼저 탐색, 그 다음 계획, 그 다음 코드를 참조하세요.

원격 세션은 자동 수락 편집 및 Plan mode를 지원합니다. 권한 요청은 원격 세션이 기본적으로 파일 편집을 자동으로 수락하기 때문에 사용할 수 없으며, 권한 무시는 원격 환경이 이미 샌드박스되어 있기 때문에 사용할 수 없습니다. 엔터프라이즈 관리자는 사용 가능한 권한 모드를 제한할 수 있습니다. 자세한 내용은 엔터프라이즈 구성을 참조하세요.

앱 미리보기

Claude는 개발 서버를 시작하고 임베드된 브라우저를 열어 변경 사항을 확인할 수 있습니다. 이는 프론트엔드 웹 앱뿐만 아니라 백엔드 서버에도 작동합니다: Claude는 API 엔드포인트를 테스트하고, 서버 로그를 보고, 발견한 문제를 반복할 수 있습니다. 대부분의 경우 Claude는 프로젝트 파일을 편집한 후 자동으로 서버를 시작합니다. 언제든지 Claude에게 미리보기를 요청할 수도 있습니다. 기본적으로 Claude는 모든 편집 후 자동으로 변경 사항을 확인합니다. 미리보기 패널에서 다음을 수행할 수 있습니다:

임베드된 브라우저에서 실행 중인 앱과 직접 상호작용
Claude가 자동으로 자신의 변경 사항을 확인하는 것을 봅니다: 스크린샷을 찍고, DOM을 검사하고, 요소를 클릭하고, 양식을 채우고, 발견한 문제를 수정합니다
세션 도구 모음의 Preview 드롭다운에서 서버 시작 또는 중지
Persist sessions을 드롭다운에서 선택하여 서버 재시작 시 쿠키 및 로컬 스토리지를 유지하므로 개발 중에 다시 로그인할 필요가 없습니다
서버 구성을 편집하거나 모든 서버를 한 번에 중지

Claude는 프로젝트를 기반으로 초기 서버 구성을 만듭니다. 앱이 사용자 정의 개발 명령을 사용하는 경우 .claude/launch.json을 편집하여 설정과 일치시킵니다. 전체 참조는 미리보기 서버 구성을 참조하세요. 저장된 세션 데이터를 지우려면 Settings → Claude Code에서 Persist preview sessions을 토글 해제합니다. 미리보기를 완전히 비활성화하려면 Settings → Claude Code에서 Preview를 토글 해제합니다.

diff 보기로 변경 사항 검토하기

Claude가 코드를 변경한 후 diff 보기를 사용하면 pull request를 만들기 전에 파일별로 수정 사항을 검토할 수 있습니다. Claude가 파일을 변경하면 +12 -1과 같이 추가 및 제거된 줄 수를 표시하는 diff 통계 표시기가 나타납니다. 이 표시기를 클릭하여 diff 뷰어를 열면 왼쪽에 파일 목록이 표시되고 오른쪽에 각 파일의 변경 사항이 표시됩니다. 특정 줄에 댓글을 달려면 diff의 모든 줄을 클릭하여 댓글 상자를 엽니다. 피드백을 입력하고 Enter를 눌러 댓글을 추가합니다. 여러 줄에 댓글을 추가한 후 모든 댓글을 한 번에 제출합니다:

macOS: Cmd+Enter 누르기
Windows: Ctrl+Enter 누르기

Claude는 댓글을 읽고 요청된 변경 사항을 만들며, 이는 검토할 수 있는 새로운 diff로 나타납니다.

코드 검토하기

diff 보기에서 오른쪽 상단 도구 모음의 Review code를 클릭하여 Claude에게 커밋하기 전에 변경 사항을 평가하도록 요청합니다. Claude는 현재 diff를 검토하고 diff 보기에 직접 댓글을 남깁니다. 모든 댓글에 응답하거나 Claude에게 수정을 요청할 수 있습니다. 검토는 높은 신호 문제에 중점을 둡니다: 컴파일 오류, 명확한 논리 오류, 보안 취약점, 명백한 버그입니다. 스타일, 형식, 기존 문제 또는 linter가 포착할 수 있는 것은 플래그하지 않습니다.

pull request 상태 모니터링하기

pull request를 연 후 CI 상태 표시줄이 세션에 나타납니다. Claude Code는 GitHub CLI를 사용하여 확인 결과를 폴링하고 실패를 표시합니다.

자동 수정: 활성화되면 Claude는 실패 출력을 읽고 반복하여 실패한 CI 확인을 자동으로 수정하려고 시도합니다.
자동 병합: 활성화되면 모든 확인이 통과하면 Claude가 PR을 병합합니다. 병합 방법은 squash입니다. 자동 병합은 이 작업을 수행하기 위해 GitHub 저장소 설정에서 활성화되어야 합니다.

CI 상태 표시줄의 Auto-fix 및 Auto-merge 토글을 사용하여 옵션을 활성화합니다. Claude Code는 CI가 완료되면 데스크톱 알림도 보냅니다.

PR 모니터링에는 GitHub CLI (gh)가 머신에 설치되고 인증되어야 합니다. gh가 설치되지 않은 경우 Desktop은 처음으로 PR을 만들려고 할 때 설치하도록 요청합니다.

Claude가 컴퓨터를 사용하도록 하기

컴퓨터 사용을 통해 Claude는 앱을 열고, 화면을 제어하고, 사용자가 하는 방식으로 머신에서 직접 작업할 수 있습니다. Claude에게 iOS 시뮬레이터에서 네이티브 앱을 테스트하거나, CLI가 없는 데스크톱 도구와 상호작용하거나, GUI를 통해서만 작동하는 것을 자동화하도록 요청합니다.

컴퓨터 사용은 Pro 또는 Max 계획이 필요한 macOS의 연구 미리보기입니다. Team 또는 Enterprise 계획에서는 사용할 수 없습니다. Claude Desktop 앱이 실행 중이어야 합니다.

컴퓨터 사용은 기본적으로 꺼져 있습니다. Settings에서 활성화하고 Claude가 화면을 제어하기 전에 필요한 macOS 권한을 부여합니다.

샌드박스 Bash 도구와 달리 컴퓨터 사용은 승인한 모든 것에 액세스할 수 있는 실제 데스크톱에서 실행됩니다. Claude는 각 작업을 확인하고 화면 콘텐츠에서 잠재적 프롬프트 주입을 플래그하지만 신뢰 경계가 다릅니다. 모범 사례는 컴퓨터 사용 안전 가이드를 참조하세요.

컴퓨터 사용이 적용되는 경우

Claude는 앱 또는 서비스와 상호작용하는 여러 방법을 가지고 있으며 컴퓨터 사용이 가장 광범위하고 느립니다. 가장 정확한 도구를 먼저 시도합니다:

서비스에 대한 커넥터가 있으면 Claude는 커넥터를 사용합니다.
작업이 셸 명령이면 Claude는 Bash를 사용합니다.
작업이 브라우저 작업이고 Claude in Chrome이 설정되어 있으면 Claude는 그것을 사용합니다.
위의 어느 것도 적용되지 않으면 Claude는 컴퓨터 사용을 사용합니다.

앱별 액세스 계층은 이를 강화합니다: 브라우저는 보기 전용으로 제한되고, 터미널 및 IDE는 클릭 전용으로 제한되어 컴퓨터 사용이 활성화되어 있어도 Claude를 전용 도구로 유도합니다. 화면 제어는 네이티브 앱, 하드웨어 제어판, iOS 시뮬레이터 또는 API가 없는 독점 도구와 같이 다른 것이 도달할 수 없는 것을 위해 예약되어 있습니다.

컴퓨터 사용 활성화하기

컴퓨터 사용은 기본적으로 꺼져 있습니다. Claude가 필요한 작업을 하도록 요청하는데 꺼져 있으면 Claude는 Settings에서 컴퓨터 사용을 활성화하면 작업을 수행할 수 있다고 알려줍니다. 활성화하려면 Settings > Desktop app > General을 열고 Computer use를 켭니다. 토글이 적용되기 전에 두 가지 macOS 시스템 권한을 부여해야 합니다:

Accessibility: Claude가 클릭, 입력, 스크롤할 수 있게 합니다
Screen Recording: Claude가 화면에 있는 것을 볼 수 있게 합니다

Settings 페이지는 각 권한의 현재 상태를 표시합니다. 둘 중 하나가 거부되면 배지를 클릭하여 관련 System Settings 창을 엽니다.

앱 권한

Claude가 처음 앱을 사용해야 할 때 세션에 프롬프트가 나타납니다. Allow for this session 또는 Deny를 클릭합니다. 승인은 현재 세션 또는 Dispatch 생성 세션에서 30분 동안 지속됩니다. 프롬프트는 또한 Claude가 해당 앱에 대해 얻는 제어 수준을 표시합니다. 이러한 계층은 앱 카테고리별로 고정되며 변경할 수 없습니다:

계층	Claude가 할 수 있는 것	적용 대상
보기 전용	스크린샷에서 앱 보기	브라우저, 거래 플랫폼
클릭 전용	클릭 및 스크롤하지만 입력 또는 키보드 단축키 사용 불가	터미널, IDE
전체 제어	클릭, 입력, 드래그, 키보드 단축키 사용	기타 모든 것

Terminal, Finder, System Settings와 같이 광범위한 영향을 미치는 앱은 승인이 부여하는 것을 알 수 있도록 프롬프트에 추가 경고를 표시합니다. Settings > Desktop app > General에서 두 가지 설정을 구성할 수 있습니다:

Denied apps: 프롬프트 없이 거부하려면 여기에 앱을 추가합니다. Claude는 허용된 앱의 작업을 통해 거부된 앱에 간접적으로 영향을 미칠 수 있지만 거부된 앱과 직접 상호작용할 수 없습니다.
Unhide apps when Claude finishes: Claude가 작업하는 동안 다른 창이 숨겨져 승인된 앱하고만 상호작용합니다. Claude가 완료되면 이 설정을 끄지 않는 한 숨겨진 창이 복원됩니다.

세션 관리하기

각 세션은 자신의 컨텍스트와 변경 사항을 가진 독립적인 대화입니다. 여러 세션을 병렬로 실행하거나 작업을 클라우드로 보내거나 Dispatch가 휴대폰에서 세션을 시작하도록 할 수 있습니다.

세션으로 병렬 작업하기

사이드바에서 + New session을 클릭하여 여러 작업을 병렬로 작업합니다. Git 저장소의 경우 각 세션은 Git worktrees를 사용하여 프로젝트의 자신의 격리된 복사본을 가져오므로 한 세션의 변경 사항이 커밋할 때까지 다른 세션에 영향을 주지 않습니다. Worktrees는 기본적으로 <project-root>/.claude/worktrees/에 저장됩니다. Settings → Claude Code의 “Worktree location”에서 사용자 정의 디렉토리로 변경할 수 있습니다. 또한 모든 worktree 브랜치 이름 앞에 추가되는 브랜치 접두사를 설정할 수 있으며, 이는 Claude가 만든 브랜치를 정리하는 데 유용합니다. 완료되면 사이드바의 세션 위에 마우스를 올리고 아카이브 아이콘을 클릭하여 worktree를 제거합니다.

세션 격리에는 Git이 필요합니다. 대부분의 Mac에는 기본적으로 Git이 포함되어 있습니다. Terminal에서 git --version을 실행하여 확인합니다. Windows에서는 Code 탭이 작동하려면 Git이 필요합니다: Windows용 Git 다운로드, 설치 및 앱 재시작. Git 오류가 발생하면 Cowork 세션을 시도하여 설정을 문제 해결하세요.

사이드바 상단의 필터 아이콘을 사용하여 상태(Active, Archived) 및 환경(Local, Cloud)별로 세션을 필터링합니다. 세션 이름을 바꾸거나 컨텍스트 사용량을 확인하려면 활성 세션 상단의 도구 모음에서 세션 제목을 클릭합니다. 컨텍스트가 가득 차면 Claude는 자동으로 대화를 요약하고 계속 작업합니다. /compact를 입력하여 요약을 더 일찍 트리거하고 컨텍스트 공간을 확보할 수도 있습니다. 컨텍스트 윈도우에서 압축이 작동하는 방식에 대한 자세한 내용을 참조하세요.

원격으로 장기 실행 작업 실행하기

대규모 리팩토링, 테스트 스위트, 마이그레이션 또는 기타 장기 실행 작업의 경우 세션을 시작할 때 Local 대신 Remote를 선택합니다. 원격 세션은 Anthropic의 클라우드 인프라에서 실행되며 앱을 닫거나 컴퓨터를 종료해도 계속됩니다. 언제든지 돌아와서 진행 상황을 보거나 Claude를 다른 방향으로 조종할 수 있습니다. claude.ai/code에서 또는 Claude iOS 앱에서 원격 세션을 모니터링할 수도 있습니다. 원격 세션은 또한 여러 저장소를 지원합니다. 클라우드 환경을 선택한 후 저장소 pill 옆의 + 버튼을 클릭하여 세션에 추가 저장소를 추가합니다. 각 저장소는 자신의 브랜치 선택기를 가집니다. 이는 공유 라이브러리와 그 소비자를 업데이트하는 것과 같이 여러 코드베이스에 걸친 작업에 유용합니다. 원격 세션이 작동하는 방식에 대한 자세한 내용은 웹의 Claude Code를 참조하세요.

다른 표면에서 계속하기

세션 도구 모음의 오른쪽 아래에 있는 VS Code 아이콘에서 액세스할 수 있는 Continue in 메뉴를 사용하면 세션을 다른 표면으로 이동할 수 있습니다:

Claude Code on the Web: 로컬 세션을 원격으로 계속 실행하도록 보냅니다. Desktop은 브랜치를 푸시하고, 대화 요약을 생성하고, 전체 컨텍스트를 사용하여 새 원격 세션을 만듭니다. 그 후 로컬 세션을 아카이브하거나 유지하도록 선택할 수 있습니다. 이는 깨끗한 작업 트리가 필요하며 SSH 세션에는 사용할 수 없습니다.
Your IDE: 현재 작업 디렉토리에서 지원되는 IDE에서 프로젝트를 엽니다.

Dispatch에서 세션

Dispatch는 Cowork 탭에 있는 Claude와의 지속적인 대화입니다. Dispatch에 작업을 메시지하면 처리 방법을 결정합니다. 작업은 두 가지 방법으로 Code 세션이 될 수 있습니다: 직접 요청하는 경우 (예: “Claude Code 세션을 열고 로그인 버그를 수정하세요”) 또는 Dispatch가 작업이 개발 작업이라고 결정하고 자동으로 하나를 생성하는 경우입니다. 일반적으로 Code로 라우팅되는 작업에는 버그 수정, 종속성 업데이트, 테스트 실행 또는 pull request 열기가 포함됩니다. 연구, 문서 편집, 스프레드시트 작업은 Cowork에 남아 있습니다. 어느 쪽이든 Code 세션은 Dispatch 배지가 있는 Code 탭의 사이드바에 나타납니다. 완료되거나 승인이 필요할 때 휴대폰에서 푸시 알림을 받습니다. 컴퓨터 사용이 활성화되어 있으면 Dispatch 생성 Code 세션도 사용할 수 있습니다. 이러한 세션의 앱 승인은 30분 후 만료되고 다시 프롬프트하며, 일반 Code 세션처럼 전체 세션 동안 지속되지 않습니다. 설정, 페어링, Dispatch 설정은 Dispatch 도움말 문서를 참조하세요. Dispatch는 Pro 또는 Max 계획이 필요하며 Team 또는 Enterprise 계획에서는 사용할 수 없습니다. Dispatch는 터미널에서 멀리 떨어져 있을 때 Claude와 작업하는 여러 방법 중 하나입니다. 플랫폼 및 통합을 참조하여 Remote Control, Channels, Slack, 예약된 작업과 비교하세요.

Claude Code 확장하기

외부 서비스를 연결하고, 재사용 가능한 워크플로우를 추가하고, Claude의 동작을 사용자 정의하고, 미리보기 서버를 구성합니다.

외부 도구 연결하기

로컬 및 SSH 세션의 경우 프롬프트 상자 옆의 + 버튼을 클릭하고 Connectors를 선택하여 Google Calendar, Slack, GitHub, Linear, Notion 등과 같은 통합을 추가합니다. 세션 전이나 중에 커넥터를 추가할 수 있습니다. + 버튼은 원격 세션에서 사용할 수 없지만 예약된 작업은 작업 생성 시 커넥터를 구성합니다. 커넥터를 관리하거나 연결을 해제하려면 데스크톱 앱의 Settings → Connectors로 이동하거나 프롬프트 상자의 Connectors 메뉴에서 Manage connectors를 선택합니다. 연결되면 Claude는 캘린더를 읽고, 메시지를 보내고, 문제를 만들고, 도구와 직접 상호작용할 수 있습니다. Claude에게 세션에 구성된 커넥터가 무엇인지 물어볼 수 있습니다. 커넥터는 그래픽 설정 흐름이 있는 MCP servers입니다. 지원되는 서비스와의 빠른 통합을 위해 사용합니다. Connectors에 나열되지 않은 통합의 경우 설정 파일을 통해 MCP 서버를 수동으로 추가합니다. 사용자 정의 커넥터를 만들 수도 있습니다.

skills 사용하기

Skills는 Claude가 할 수 있는 것을 확장합니다. Claude는 관련이 있을 때 자동으로 로드하거나 직접 호출할 수 있습니다: 프롬프트 상자에서 /를 입력하거나 + 버튼을 클릭하고 Slash commands를 선택하여 사용 가능한 것을 찾아봅니다. 여기에는 내장 명령, 사용자 정의 skills, 코드베이스의 프로젝트 skills, 설치된 플러그인의 skills가 포함됩니다. 하나를 선택하면 입력 필드에 강조 표시됩니다. 그 후 작업을 입력하고 평소대로 보냅니다.

플러그인 설치하기

Plugins는 Claude Code에 skills, agents, hooks, MCP servers, LSP 구성을 추가하는 재사용 가능한 패키지입니다. 터미널을 사용하지 않고 데스크톱 앱에서 플러그인을 설치할 수 있습니다. 로컬 및 SSH 세션의 경우 프롬프트 상자 옆의 + 버튼을 클릭하고 Plugins를 선택하여 설치된 플러그인과 해당 명령을 봅니다. 플러그인을 추가하려면 서브메뉴에서 Add plugin을 선택하여 플러그인 브라우저를 열면 공식 Anthropic marketplace를 포함한 구성된 marketplaces의 사용 가능한 플러그인이 표시됩니다. Manage plugins를 선택하여 플러그인을 활성화, 비활성화 또는 제거합니다. 플러그인은 사용자 계정, 특정 프로젝트 또는 로컬 전용으로 범위를 지정할 수 있습니다. 플러그인은 원격 세션에는 사용할 수 없습니다. 자신의 플러그인을 만드는 것을 포함한 전체 플러그인 참조는 plugins를 참조하세요.

미리보기 서버 구성하기

Claude는 개발 서버 설정을 자동으로 감지하고 세션을 시작할 때 선택한 폴더의 루트에 있는 .claude/launch.json에 구성을 저장합니다. Preview는 이 폴더를 작업 디렉토리로 사용하므로 부모 폴더를 선택한 경우 자신의 개발 서버가 있는 하위 폴더는 자동으로 감지되지 않습니다. 하위 폴더의 서버로 작업하려면 해당 폴더에서 직접 세션을 시작하거나 구성을 수동으로 추가합니다. 예를 들어 npm run dev 대신 yarn dev를 사용하거나 포트를 변경하도록 서버가 시작되는 방식을 사용자 정의하려면 파일을 수동으로 편집하거나 Preview 드롭다운에서 Edit configuration을 클릭하여 코드 편집기에서 엽니다. 파일은 주석이 있는 JSON을 지원합니다.

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

동일한 프로젝트에서 프론트엔드 및 API와 같은 다양한 서버를 실행하도록 여러 구성을 정의할 수 있습니다. 아래의 예제를 참조하세요.

자동 변경 사항 확인

autoVerify가 활성화되면 Claude는 파일을 편집한 후 자동으로 코드 변경 사항을 확인합니다. 스크린샷을 찍고, 오류를 확인하고, 응답을 완료하기 전에 변경 사항이 작동하는지 확인합니다. 자동 확인은 기본적으로 켜져 있습니다. .claude/launch.json에 "autoVerify": false를 추가하여 프로젝트별로 비활성화하거나 Preview 드롭다운 메뉴에서 토글합니다.

{
  "version": "0.0.1",
  "autoVerify": false,
  "configurations": [...]
}

비활성화되면 미리보기 도구는 여전히 사용 가능하며 언제든지 Claude에게 확인을 요청할 수 있습니다. 자동 확인은 모든 편집 후 자동으로 만듭니다.

구성 필드

configurations 배열의 각 항목은 다음 필드를 허용합니다:

필드	유형	설명
`name`	string	이 서버의 고유 식별자
`runtimeExecutable`	string	실행할 명령 (예: `npm`, `yarn`, `node`)
`runtimeArgs`	string[]	`runtimeExecutable`에 전달되는 인수 (예: `["run", "dev"]`)
`port`	number	서버가 수신하는 포트. 기본값은 3000
`cwd`	string	프로젝트 루트에 상대적인 작업 디렉토리. 기본값은 프로젝트 루트입니다. 프로젝트 루트를 명시적으로 참조하려면 `${workspaceFolder}`를 사용합니다
`env`	object	`{ "NODE_ENV": "development" }`와 같은 키-값 쌍으로 추가 환경 변수. 이 파일이 저장소에 커밋되므로 여기에 비밀을 넣지 마세요. 셸 프로필에 설정된 비밀은 자동으로 상속됩니다.
`autoPort`	boolean	포트 충돌을 처리하는 방법. 아래를 참조하세요
`program`	string	`node`로 실행할 스크립트. 언제 `program` vs `runtimeExecutable`을 사용할지 참조
`args`	string[]	`program`에 전달되는 인수. `program`이 설정된 경우에만 사용됨

`program` vs `runtimeExecutable` 사용 시기

패키지 관리자를 통해 개발 서버를 시작하려면 runtimeExecutable을 runtimeArgs와 함께 사용합니다. 예를 들어 "runtimeExecutable": "npm"과 "runtimeArgs": ["run", "dev"]는 npm run dev를 실행합니다. node로 직접 실행하려는 독립 실행형 스크립트가 있을 때 program을 사용합니다. 예를 들어 "program": "server.js"는 node server.js를 실행합니다. args로 추가 플래그를 전달합니다.

포트 충돌

autoPort 필드는 선호하는 포트가 이미 사용 중일 때 발생하는 상황을 제어합니다:

true: Claude는 자동으로 사용 가능한 포트를 찾아 사용합니다. 대부분의 개발 서버에 적합합니다.
false: Claude는 오류로 실패합니다. OAuth 콜백 또는 CORS allowlists와 같이 서버가 특정 포트를 사용해야 할 때 사용합니다.
설정되지 않음 (기본값): Claude는 서버가 정확한 포트가 필요한지 묻고 답변을 저장합니다.

Claude가 다른 포트를 선택하면 할당된 포트를 PORT 환경 변수를 통해 서버에 전달합니다.

예제

이러한 구성은 다양한 프로젝트 유형에 대한 일반적인 설정을 보여줍니다:

Next.js
Multiple servers
Node.js script

이 구성은 Yarn을 사용하여 포트 3000에서 Next.js 앱을 실행합니다:

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "web",
      "runtimeExecutable": "yarn",
      "runtimeArgs": ["dev"],
      "port": 3000
    }
  ]
}

프론트엔드 및 API 서버가 있는 monorepo의 경우 여러 구성을 정의합니다. 프론트엔드는 autoPort: true를 사용하므로 3000이 사용 중이면 사용 가능한 포트를 선택하고, API 서버는 포트 8080을 정확히 요구합니다:

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "frontend",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "cwd": "apps/web",
      "port": 3000,
      "autoPort": true
    },
    {
      "name": "api",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "start"],
      "cwd": "server",
      "port": 8080,
      "env": { "NODE_ENV": "development" },
      "autoPort": false
    }
  ]
}

패키지 관리자 명령 대신 Node.js 스크립트를 직접 실행하려면 program 필드를 사용합니다:

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "server",
      "program": "server.js",
      "args": ["--verbose"],
      "port": 4000
    }
  ]
}

반복 작업 예약하기

기본적으로 예약된 작업은 선택한 시간과 빈도에 자동으로 새 세션을 시작합니다. 일일 코드 검토, 종속성 업데이트 확인 또는 캘린더 및 받은 편지함에서 가져오는 아침 브리핑과 같은 반복 작업에 사용합니다.

예약 옵션 비교

Claude Code offers three ways to schedule recurring work:

	Cloud	Desktop	`/loop`
Runs on	Anthropic cloud	Your machine	Your machine
Requires machine on	No	Yes	Yes
Requires open session	No	No	Yes
Persistent across restarts	Yes	Yes	No (session-scoped)
Access to local files	No (fresh clone)	Yes	Yes
MCP servers	Connectors configured per task	Config files and connectors	Inherits from session
Permission prompts	No (runs autonomously)	Configurable per task	Inherits from session
Customizable schedule	Via `/schedule` in the CLI	Yes	Yes
Minimum interval	1 hour	1 minute	1 minute

Use cloud tasks for work that should run reliably without your machine. Use Desktop tasks when you need access to local files and tools. Use /loop for quick polling during a session.

Schedule 페이지는 두 가지 종류의 작업을 지원합니다:

로컬 작업: 머신에서 실행됩니다. 로컬 파일 및 도구에 직접 액세스할 수 있지만 데스크톱 앱이 열려 있고 컴퓨터가 깨어 있어야 실행됩니다.
원격 작업: Anthropic 관리 클라우드 인프라에서 실행됩니다. 컴퓨터가 꺼져 있어도 계속 실행되지만 로컬 체크아웃이 아닌 저장소의 새로운 복제본에 대해 작동합니다.

두 종류 모두 동일한 작업 그리드에 나타납니다. New task를 클릭하여 만들 종류를 선택합니다. 이 섹션의 나머지는 로컬 작업을 다룹니다. 원격 작업은 클라우드 예약된 작업을 참조하세요. 예약된 작업이 실행되는 방식에 대한 자세한 내용은 예약된 작업이 실행되는 방식을 참조하세요.

기본적으로 로컬 예약된 작업은 커밋되지 않은 변경 사항을 포함한 작업 디렉토리의 현재 상태에 대해 실행됩니다. 프롬프트 입력에서 worktree 토글을 활성화하여 각 실행에 자신의 격리된 Git worktree를 제공합니다. 병렬 세션과 동일한 방식입니다.

로컬 예약된 작업을 만들려면 사이드바에서 Schedule을 클릭하고 New task를 클릭한 다음 New local task를 선택합니다. 다음 필드를 구성합니다:

필드	설명
Name	작업의 식별자. 소문자 kebab-case로 변환되고 디스크의 폴더 이름으로 사용됩니다. 작업 전체에서 고유해야 합니다.
Description	작업 목록에 표시되는 짧은 요약.
Prompt	작업이 실행될 때 Claude에게 전송되는 지침. 프롬프트 상자에서 메시지를 작성하는 것과 동일한 방식으로 작성합니다. 프롬프트 입력에는 모델, 권한 모드, 작업 폴더, worktree에 대한 컨트롤도 포함됩니다.
Frequency	작업이 실행되는 빈도. 아래의 빈도 옵션을 참조하세요.

모든 세션에서 원하는 것을 설명하여 작업을 만들 수도 있습니다. 예를 들어 “매일 아침 9시에 실행되는 일일 코드 검토를 설정합니다.”

빈도 옵션

Manual: 일정 없음, Run now를 클릭할 때만 실행됩니다. 온디맨드로 트리거하는 프롬프트를 저장하는 데 유용합니다
Hourly: 매시간 실행됩니다. 각 작업은 API 트래픽을 분산하기 위해 시간 상단에서 최대 10분의 고정 오프셋을 가집니다
Daily: 시간 선택기를 표시하고 기본값은 오전 9:00 현지 시간입니다
Weekdays: Daily와 동일하지만 토요일과 일요일을 건너뜁니다
Weekly: 시간 선택기와 요일 선택기를 표시합니다

선택기가 제공하지 않는 간격(15분마다, 매월 첫 번째 등)의 경우 Desktop 세션에서 Claude에게 일정을 설정하도록 요청합니다. 일반 언어를 사용합니다. 예를 들어 “6시간마다 모든 테스트를 실행하는 작업을 예약합니다.”

예약된 작업이 실행되는 방식

로컬 예약된 작업은 머신에서 실행됩니다. Desktop은 앱이 열려 있는 동안 매분 일정을 확인하고 열려 있는 수동 세션과 독립적으로 작업이 만료되면 새 세션을 시작합니다. 각 작업은 API 트래픽을 분산하기 위해 예약된 시간 후 최대 10분의 고정 지연을 가집니다. 지연은 결정적입니다: 동일한 작업은 항상 동일한 오프셋에서 시작됩니다. 작업이 실행되면 데스크톱 알림을 받고 새 세션이 사이드바의 Scheduled 섹션 아래에 나타납니다. 이를 열어 Claude가 수행한 작업을 보고, 변경 사항을 검토하거나, 권한 프롬프트에 응답합니다. 세션은 다른 것처럼 작동합니다: Claude는 파일을 편집하고, 명령을 실행하고, 커밋을 만들고, pull request를 열 수 있습니다. 작업은 데스크톱 앱이 실행 중이고 컴퓨터가 깨어 있을 때만 실행됩니다. 컴퓨터가 예약된 시간을 통해 절전 모드로 전환되면 실행이 건너뜁니다. 유휴 절전을 방지하려면 Settings의 Desktop app → General 아래에서 Keep computer awake를 활성화합니다. 노트북 뚜껑을 닫으면 여전히 절전 모드로 전환됩니다. 컴퓨터가 꺼져 있어도 실행해야 하는 작업의 경우 원격 작업을 대신 사용합니다.

놓친 실행

앱이 시작되거나 컴퓨터가 깨어나면 Desktop은 지난 7일 동안 각 작업이 놓친 실행이 있는지 확인합니다. 그렇다면 Desktop은 가장 최근에 놓친 시간에 대해 정확히 하나의 따라잡기 실행을 시작하고 더 오래된 것은 버립니다. 6일을 놓친 일일 작업은 한 번 깨어날 때 실행됩니다. Desktop은 따라잡기 실행이 시작될 때 알림을 표시합니다. 프롬프트를 작성할 때 이를 염두에 두세요. 오전 9시에 예약된 작업은 컴퓨터가 하루 종일 절전 모드였다면 오후 11시에 실행될 수 있습니다. 타이밍이 중요하면 프롬프트 자체에 가드레일을 추가합니다. 예를 들어 “오늘의 커밋만 검토합니다. 오후 5시 이후라면 검토를 건너뛰고 놓친 것의 요약만 게시합니다.”

예약된 작업에 대한 권한

각 작업은 자신의 권한 모드를 가지며, 작업을 만들거나 편집할 때 설정합니다. ~/.claude/settings.json의 규칙 허용도 예약된 작업 세션에 적용됩니다. 작업이 Ask 모드에서 실행되고 권한이 없는 도구를 실행해야 하면 실행이 승인할 때까지 정지됩니다. 세션은 사이드바에 열려 있으므로 나중에 답변할 수 있습니다. 정지를 방지하려면 작업을 만든 후 Run now를 클릭하고 권한 프롬프트를 확인하고 각각에 대해 “항상 허용”을 선택합니다. 해당 작업의 향후 실행은 프롬프트 없이 동일한 도구를 자동으로 승인합니다. 작업의 세부 정보 페이지에서 이러한 승인을 검토하고 취소할 수 있습니다.

예약된 작업 관리하기

Schedule 목록의 작업을 클릭하여 세부 정보 페이지를 엽니다. 여기에서 다음을 수행할 수 있습니다:

Run now: 다음 예약된 시간을 기다리지 않고 즉시 작업을 시작합니다
Toggle repeats: 작업을 삭제하지 않고 예약된 실행을 일시 중지하거나 재개합니다
Edit: 프롬프트, 빈도, 폴더 또는 기타 설정을 변경합니다
Review history: 컴퓨터가 절전 모드였기 때문에 건너뛴 것을 포함한 모든 과거 실행을 봅니다
Review allowed permissions: Always allowed 패널에서 이 작업에 대해 저장된 도구 승인을 보고 취소합니다
Delete: 작업을 제거하고 생성한 모든 세션을 아카이브합니다

Desktop 세션에서 Claude에게 요청하여 작업을 관리할 수도 있습니다. 예를 들어 “내 dependency-audit 작업을 일시 중지합니다”, “standup-prep 작업을 삭제합니다” 또는 “예약된 작업을 보여줍니다.” 디스크에서 작업의 프롬프트를 편집하려면 ~/.claude/scheduled-tasks/<task-name>/SKILL.md를 엽니다 (설정된 경우 CLAUDE_CONFIG_DIR 아래). 파일은 name 및 description에 대한 YAML frontmatter를 사용하고 프롬프트를 본문으로 사용합니다. 변경 사항은 다음 실행에 적용됩니다. 일정, 폴더, 모델, 활성화 상태는 이 파일에 없습니다: Edit 양식을 통해 또는 Claude에게 요청하여 변경합니다.

환경 구성

세션을 시작할 때 선택하는 환경은 Claude가 실행되는 위치와 연결 방식을 결정합니다:

Local: 머신에서 실행되며 파일에 직접 액세스합니다
Remote: Anthropic의 클라우드 인프라에서 실행됩니다. 앱을 닫아도 세션이 계속됩니다.
SSH: SSH를 통해 연결하는 원격 머신 (예: 자신의 서버, 클라우드 VM 또는 개발 컨테이너)에서 실행됩니다

로컬 세션

로컬 세션은 셸에서 환경 변수를 상속합니다. 추가 변수가 필요하면 ~/.zshrc 또는 ~/.bashrc와 같은 셸 프로필에 설정하고 데스크톱 앱을 재시작합니다. 지원되는 변수의 전체 목록은 환경 변수를 참조하세요. Extended thinking은 기본적으로 활성화되어 있으며, 복잡한 추론 작업의 성능을 향상시키지만 추가 토큰을 사용합니다. 생각을 완전히 비활성화하려면 셸 프로필에서 MAX_THINKING_TOKENS=0을 설정합니다. Opus에서는 적응형 추론이 생각 깊이를 제어하기 때문에 0을 제외하고 MAX_THINKING_TOKENS이 무시됩니다.

원격 세션

원격 세션은 앱을 닫아도 백그라운드에서 계속됩니다. 사용량은 별도의 컴퓨팅 요금 없이 구독 계획 한도에 포함됩니다. 다양한 네트워크 액세스 수준 및 환경 변수를 가진 사용자 정의 클라우드 환경을 만들 수 있습니다. 원격 세션을 시작할 때 환경 드롭다운을 선택하고 Add environment를 선택합니다. 네트워크 액세스 및 환경 변수 구성에 대한 자세한 내용은 클라우드 환경을 참조하세요.

SSH 세션

SSH 세션을 사용하면 데스크톱 앱을 인터페이스로 사용하면서 원격 머신에서 Claude Code를 실행할 수 있습니다. 이는 클라우드 VM, 개발 컨테이너 또는 특정 하드웨어 또는 종속성이 있는 서버에 있는 코드베이스로 작업할 때 유용합니다. SSH 연결을 추가하려면 세션을 시작하기 전에 환경 드롭다운을 클릭하고 + Add SSH connection을 선택합니다. 대화 상자는 다음을 요청합니다:

Name: 이 연결의 친화적인 레이블
SSH Host: user@hostname 또는 ~/.ssh/config에 정의된 호스트
SSH Port: 비워두면 기본값은 22이거나 SSH 구성의 포트를 사용합니다
Identity File: ~/.ssh/id_rsa와 같은 개인 키의 경로. 기본 키 또는 SSH 구성을 사용하려면 비워둡니다.

추가되면 연결이 환경 드롭다운에 나타납니다. 이를 선택하여 해당 머신에서 세션을 시작합니다. Claude는 원격 머신에서 파일 및 도구에 액세스하여 실행됩니다. Claude Code는 원격 머신에 설치되어야 합니다. 연결되면 SSH 세션은 권한 모드, 커넥터, 플러그인, MCP 서버를 지원합니다.

엔터프라이즈 구성

Teams 또는 Enterprise 계획의 조직은 관리 콘솔 컨트롤, 관리 설정 파일, 장치 관리 정책을 통해 데스크톱 앱 동작을 관리할 수 있습니다.

관리 콘솔 컨트롤

이러한 설정은 관리 설정 콘솔을 통해 구성됩니다:

데스크톱의 Code: 조직의 사용자가 데스크톱 앱에서 Claude Code에 액세스할 수 있는지 제어합니다
웹의 Code: 조직의 웹 세션을 활성화 또는 비활성화합니다
Remote Control: 조직의 Remote Control을 활성화 또는 비활성화합니다
권한 무시 모드 비활성화: 조직의 사용자가 권한 무시 모드를 활성화하지 못하도록 방지합니다

관리 설정

관리 설정은 프로젝트 및 사용자 설정을 재정의하고 Desktop이 CLI 세션을 생성할 때 적용됩니다. 조직의 관리 설정 파일에서 이러한 키를 설정하거나 관리 콘솔을 통해 원격으로 푸시할 수 있습니다.

키	설명
`permissions.disableBypassPermissionsMode`	사용자가 권한 무시 모드를 활성화하지 못하도록 하려면 `"disable"`로 설정합니다.
`disableAutoMode`	사용자가 Auto 모드를 활성화하지 못하도록 하려면 `"disable"`로 설정합니다. 모드 선택기에서 Auto를 제거합니다. `permissions` 아래에서도 허용됩니다.
`autoMode`	조직 전체에서 auto mode 분류기가 신뢰하고 차단하는 것을 사용자 정의합니다. auto mode 분류기 구성을 참조하세요.

permissions.disableBypassPermissionsMode 및 disableAutoMode는 사용자 및 프로젝트 설정에서도 작동하지만 관리 설정에 배치하면 사용자가 재정의하지 못하도록 방지합니다. autoMode는 사용자 설정, .claude/settings.local.json, 관리 설정에서 읽혀지지만 체크인된 .claude/settings.json에서는 읽혀지지 않습니다: 복제된 저장소는 자신의 분류기 규칙을 주입할 수 없습니다. allowManagedPermissionRulesOnly 및 allowManagedHooksOnly를 포함한 관리 전용 설정의 전체 목록은 관리 전용 설정을 참조하세요. 관리 콘솔을 통해 업로드된 원격 관리 설정은 현재 CLI 및 IDE 세션에만 적용됩니다. Desktop 특정 제한의 경우 위의 관리 콘솔 컨트롤을 사용합니다.

장치 관리 정책

IT 팀은 macOS의 MDM 또는 Windows의 그룹 정책을 통해 데스크톱 앱을 관리할 수 있습니다. 사용 가능한 정책에는 Claude Code 기능 활성화 또는 비활성화, 자동 업데이트 제어, 사용자 정의 배포 URL 설정이 포함됩니다.

macOS: Jamf 또는 Kandji와 같은 도구를 사용하여 com.anthropic.Claude 기본 설정 도메인을 통해 구성합니다
Windows: SOFTWARE\Policies\Claude의 레지스트리를 통해 구성합니다

인증 및 SSO

엔터프라이즈 조직은 모든 사용자에게 SSO를 요구할 수 있습니다. 계획 수준 세부 정보는 인증을 참조하고 SAML 및 OIDC 구성은 SSO 설정을 참조하세요.

데이터 처리

Claude Code는 로컬 세션에서 코드를 로컬로 처리하거나 원격 세션에서 Anthropic의 클라우드 인프라에서 처리합니다. 대화 및 코드 컨텍스트는 처리를 위해 Anthropic의 API로 전송됩니다. 데이터 보존, 개인 정보 보호, 규정 준수에 대한 자세한 내용은 데이터 처리를 참조하세요.

배포

Desktop은 엔터프라이즈 배포 도구를 통해 배포할 수 있습니다:

macOS: Jamf 또는 Kandji와 같은 MDM을 통해 .dmg 설치 프로그램을 사용하여 배포합니다
Windows: MSIX 패키지 또는 .exe 설치 프로그램을 통해 배포합니다. 자동 설치를 포함한 엔터프라이즈 배포 옵션은 Windows용 Claude Desktop 배포를 참조하세요

프록시 설정, 방화벽 허용 목록, LLM 게이트웨이와 같은 네트워크 구성은 네트워크 구성을 참조하세요. 전체 엔터프라이즈 구성 참조는 엔터프라이즈 구성 가이드를 참조하세요.

CLI에서 오셨나요?

이미 Claude Code CLI를 사용하는 경우 Desktop은 그래픽 인터페이스를 사용하여 동일한 기본 엔진을 실행합니다. 동일한 머신에서 동일한 프로젝트에서도 동시에 둘 다 실행할 수 있습니다. 각각은 별도의 세션 기록을 유지하지만 CLAUDE.md 파일을 통해 구성 및 프로젝트 메모리를 공유합니다. CLI 세션을 Desktop으로 이동하려면 터미널에서 /desktop을 실행합니다. Claude는 세션을 저장하고 데스크톱 앱에서 열고 CLI를 종료합니다. 이 명령은 macOS 및 Windows에서만 사용 가능합니다.

Desktop vs CLI를 사용할 때: 시각적 diff 검토, 파일 첨부 또는 사이드바의 세션 관리를 원할 때 Desktop을 사용합니다. 스크립팅, 자동화, 타사 공급자 또는 터미널 워크플로우를 선호할 때 CLI를 사용합니다.

CLI 플래그 동등물

이 표는 일반적인 CLI 플래그에 대한 데스크톱 앱 동등물을 보여줍니다. 나열되지 않은 플래그는 스크립팅 또는 자동화를 위해 설계되었기 때문에 데스크톱 동등물이 없습니다.

CLI	Desktop 동등물
`--model sonnet`	세션을 시작하기 전에 전송 버튼 옆의 모델 드롭다운
`--resume`, `--continue`	사이드바의 세션을 클릭합니다
`--permission-mode`	전송 버튼 옆의 모드 선택기
`--dangerously-skip-permissions`	권한 무시 모드. Settings → Claude Code → “권한 무시 모드 허용”에서 활성화합니다. 엔터프라이즈 관리자는 이 설정을 비활성화할 수 있습니다.
`--add-dir`	원격 세션에서 + 버튼으로 여러 저장소 추가
`--allowedTools`, `--disallowedTools`	Desktop에서 사용할 수 없음
`--verbose`	사용할 수 없음. 시스템 로그 확인: macOS의 Console.app, Windows의 Event Viewer → Windows Logs → Application
`--print`, `--output-format`	사용할 수 없음. Desktop은 대화형만 가능합니다.
`ANTHROPIC_MODEL` env var	세션을 시작하기 전에 전송 버튼 옆의 모델 드롭다운
`MAX_THINKING_TOKENS` env var	셸 프로필에 설정; 로컬 세션에 적용됩니다. 환경 구성을 참조하세요.

공유 구성

Desktop과 CLI는 동일한 구성 파일을 읽으므로 설정이 이월됩니다:

CLAUDE.md 프로젝트의 파일은 둘 다에서 사용됩니다
MCP servers ~/.claude.json 또는 .mcp.json에 구성된 것은 둘 다에서 작동합니다
Hooks 및 skills 설정에 정의된 것은 둘 다에 적용됩니다
Settings ~/.claude.json 및 ~/.claude/settings.json에서 공유됩니다. settings.json의 권한 규칙, 허용된 도구 및 기타 설정은 Desktop 세션에 적용됩니다.
Models: Sonnet, Opus, Haiku는 둘 다에서 사용 가능합니다. Desktop에서 세션을 시작하기 전에 전송 버튼 옆의 드롭다운에서 모델을 선택합니다. 활성 세션 중에는 모델을 변경할 수 없습니다.

MCP servers: desktop chat app vs Claude Code: Claude Desktop chat 앱의 claude_desktop_config.json에 구성된 MCP 서버는 Claude Code와 별개이며 Code 탭에 나타나지 않습니다. Claude Code에서 MCP 서버를 사용하려면 ~/.claude.json 또는 프로젝트의 .mcp.json 파일에 구성합니다. 자세한 내용은 MCP 구성을 참조하세요.

기능 비교

이 표는 CLI와 Desktop 간의 핵심 기능을 비교합니다. CLI 플래그의 전체 목록은 CLI 참조를 참조하세요.

기능	CLI	Desktop
권한 모드	`dontAsk`를 포함한 모든 모드	권한 요청, 자동 수락 편집, Plan mode, Auto, Settings를 통한 권한 무시
`--dangerously-skip-permissions`	CLI 플래그	권한 무시 모드. Settings → Claude Code → “권한 무시 모드 허용”에서 활성화합니다
Third-party providers	Bedrock, Vertex, Foundry	사용할 수 없음. Desktop은 Anthropic의 API에 직접 연결됩니다.
MCP servers	설정 파일에 구성	로컬 및 SSH 세션의 Connectors UI 또는 설정 파일
Plugins	`/plugin` 명령	플러그인 관리자 UI
@mention 파일	텍스트 기반	자동 완성 포함
파일 첨부	사용할 수 없음	이미지, PDF
세션 격리	`--worktree` 플래그	자동 worktrees
여러 세션	별도 터미널	사이드바 탭
반복 작업	cron 작업, CI 파이프라인	예약된 작업
컴퓨터 사용	사용할 수 없음	macOS의 앱 및 화면 제어
Dispatch 통합	사용할 수 없음	사이드바의 Dispatch 세션
스크립팅 및 자동화	`--print`, Agent SDK	사용할 수 없음

Desktop에서 사용할 수 없는 것

다음 기능은 CLI 또는 VS Code 확장에서만 사용 가능합니다:

Third-party providers: Desktop은 Anthropic의 API에 직접 연결됩니다. 대신 Bedrock, Vertex 또는 Foundry와 함께 CLI를 사용합니다.
Linux: 데스크톱 앱은 macOS 및 Windows에서만 사용 가능합니다.
Inline code suggestions: Desktop은 자동 완성 스타일 제안을 제공하지 않습니다. 대화형 프롬프트 및 명시적 코드 변경을 통해 작동합니다.
Agent teams: 다중 에이전트 오케스트레이션은 CLI 및 Agent SDK를 통해 사용 가능하며 Desktop에서는 사용할 수 없습니다.

문제 해결

버전 확인하기

실행 중인 데스크톱 앱의 버전을 보려면:

macOS: 메뉴 모음에서 Claude를 클릭한 다음 About Claude를 클릭합니다
Windows: Help를 클릭한 다음 About을 클릭합니다

버전 번호를 클릭하여 클립보드에 복사합니다.

Code 탭의 403 또는 인증 오류

Code 탭을 사용할 때 Error 403: Forbidden 또는 기타 인증 실패가 표시되면:

앱 메뉴에서 로그아웃했다가 다시 로그인합니다. 이것이 가장 일반적인 수정입니다.
활성 유료 구독이 있는지 확인합니다: Pro, Max, Teams 또는 Enterprise.
CLI는 작동하지만 Desktop은 작동하지 않으면 데스크톱 앱을 완전히 종료하고 (창만 닫지 말고) 다시 열고 로그인합니다.
인터넷 연결 및 프록시 설정을 확인합니다.

시작 시 빈 화면 또는 정지된 화면

앱이 열리지만 빈 화면이나 응답하지 않는 화면이 표시되면:

앱을 다시 시작합니다.
보류 중인 업데이트를 확인합니다. 앱은 시작 시 자동으로 업데이트됩니다.
Windows에서 Event Viewer의 Windows Logs → Application 아래에서 충돌 로그를 확인합니다.

”Failed to load session”

Failed to load session이 표시되면 선택한 폴더가 더 이상 존재하지 않거나, Git 저장소에 설치되지 않은 Git LFS가 필요하거나, 파일 권한이 액세스를 방지할 수 있습니다. 다른 폴더를 선택하거나 앱을 다시 시작해 보세요.

세션이 설치된 도구를 찾지 못함

Claude가 npm, node 또는 기타 CLI 명령과 같은 도구를 찾을 수 없으면 도구가 일반 터미널에서 작동하는지 확인하고, 셸 프로필이 PATH를 올바르게 설정하는지 확인하고, 데스크톱 앱을 다시 시작하여 환경 변수를 다시 로드합니다.

Git 및 Git LFS 오류

Windows에서 Git은 로컬 세션을 시작하기 위해 Code 탭에 필요합니다. “Git is required”가 표시되면 Windows용 Git을 설치하고 앱을 다시 시작합니다. “Git LFS is required by this repository but is not installed”가 표시되면 git-lfs.com에서 Git LFS를 설치하고 git lfs install을 실행한 다음 앱을 다시 시작합니다.

Windows에서 MCP 서버가 작동하지 않음

MCP 서버 토글이 응답하지 않거나 Windows에서 서버가 연결되지 않으면 서버가 설정에 올바르게 구성되었는지 확인하고, 앱을 다시 시작하고, Task Manager에서 서버 프로세스가 실행 중인지 확인하고, 연결 오류에 대한 서버 로그를 검토합니다.

앱이 종료되지 않음

macOS: Cmd+Q를 누릅니다. 앱이 응답하지 않으면 Cmd+Option+Esc로 강제 종료를 사용하고 Claude를 선택한 다음 Force Quit를 클릭합니다.
Windows: Ctrl+Shift+Esc로 Task Manager를 사용하여 Claude 프로세스를 종료합니다.

Windows 특정 문제

설치 후 PATH가 업데이트되지 않음: 새 터미널 창을 엽니다. PATH 업데이트는 새 터미널 세션에만 적용됩니다.
동시 설치 오류: 진행 중인 다른 설치에 대한 오류가 표시되지만 없으면 관리자로 설치 프로그램을 실행해 보세요.
ARM64: Windows ARM64 장치는 완전히 지원됩니다.

Intel Mac에서 Cowork 탭을 사용할 수 없음

Cowork 탭은 macOS에서 Apple Silicon (M1 이상)이 필요합니다. Windows에서는 Cowork를 모든 지원되는 하드웨어에서 사용할 수 있습니다. Chat 및 Code 탭은 Intel Mac에서 정상적으로 작동합니다.

CLI에서 열 때 “Branch doesn’t exist yet”

원격 세션은 로컬 머신에 존재하지 않는 브랜치를 만들 수 있습니다. 세션 도구 모음의 브랜치 이름을 클릭하여 복사한 다음 로컬로 가져옵니다:

git fetch origin <branch-name>
git checkout <branch-name>

여전히 막혔나요?

GitHub Issues에서 검색하거나 버그를 제출합니다
Claude 지원 센터를 방문합니다

버그를 제출할 때 데스크톱 앱 버전, 운영 체제, 정확한 오류 메시지, 관련 로그를 포함합니다. macOS에서는 Console.app을 확인합니다. Windows에서는 Event Viewer → Windows Logs → Application을 확인합니다.

시작하기

핵심 개념

Claude Code 사용하기

플랫폼 및 통합

​세션 시작하기

​코드 작업하기

​프롬프트 상자 사용하기

​프롬프트에 파일 및 컨텍스트 추가하기

​권한 모드 선택하기

​앱 미리보기

​diff 보기로 변경 사항 검토하기

​코드 검토하기

​pull request 상태 모니터링하기

​Claude가 컴퓨터를 사용하도록 하기

​컴퓨터 사용이 적용되는 경우

​컴퓨터 사용 활성화하기

​앱 권한

​세션 관리하기

​세션으로 병렬 작업하기

​원격으로 장기 실행 작업 실행하기

​다른 표면에서 계속하기

​Dispatch에서 세션

​Claude Code 확장하기

​외부 도구 연결하기

​skills 사용하기

​플러그인 설치하기

​미리보기 서버 구성하기

​자동 변경 사항 확인

​구성 필드

program vs runtimeExecutable 사용 시기

​포트 충돌

​예제

​반복 작업 예약하기

​예약 옵션 비교

​빈도 옵션

​예약된 작업이 실행되는 방식

​놓친 실행

​예약된 작업에 대한 권한

​예약된 작업 관리하기

​환경 구성

​로컬 세션

​원격 세션

​SSH 세션

​엔터프라이즈 구성

​관리 콘솔 컨트롤

​관리 설정

​장치 관리 정책

​인증 및 SSO

​데이터 처리

​배포

​CLI에서 오셨나요?

​CLI 플래그 동등물

​공유 구성

​기능 비교

​Desktop에서 사용할 수 없는 것

​문제 해결

​버전 확인하기

​Code 탭의 403 또는 인증 오류

​시작 시 빈 화면 또는 정지된 화면

​”Failed to load session”

​세션이 설치된 도구를 찾지 못함

​Git 및 Git LFS 오류

​Windows에서 MCP 서버가 작동하지 않음

​앱이 종료되지 않음

​Windows 특정 문제

​Intel Mac에서 Cowork 탭을 사용할 수 없음

​CLI에서 열 때 “Branch doesn’t exist yet”

​여전히 막혔나요?

세션 시작하기

코드 작업하기

프롬프트 상자 사용하기

프롬프트에 파일 및 컨텍스트 추가하기

권한 모드 선택하기

앱 미리보기

diff 보기로 변경 사항 검토하기

코드 검토하기

pull request 상태 모니터링하기

Claude가 컴퓨터를 사용하도록 하기

컴퓨터 사용이 적용되는 경우

컴퓨터 사용 활성화하기

앱 권한

세션 관리하기

세션으로 병렬 작업하기

원격으로 장기 실행 작업 실행하기

다른 표면에서 계속하기

Dispatch에서 세션

Claude Code 확장하기

외부 도구 연결하기

skills 사용하기

플러그인 설치하기

미리보기 서버 구성하기

자동 변경 사항 확인

구성 필드

`program` vs `runtimeExecutable` 사용 시기

포트 충돌

예제

반복 작업 예약하기

예약 옵션 비교

빈도 옵션

예약된 작업이 실행되는 방식

놓친 실행

예약된 작업에 대한 권한

예약된 작업 관리하기

환경 구성

로컬 세션

원격 세션

SSH 세션

엔터프라이즈 구성

관리 콘솔 컨트롤

관리 설정

장치 관리 정책

인증 및 SSO

데이터 처리

배포

CLI에서 오셨나요?

CLI 플래그 동등물

공유 구성

기능 비교

Desktop에서 사용할 수 없는 것

문제 해결

버전 확인하기

Code 탭의 403 또는 인증 오류

시작 시 빈 화면 또는 정지된 화면

”Failed to load session”

세션이 설치된 도구를 찾지 못함

Git 및 Git LFS 오류

Windows에서 MCP 서버가 작동하지 않음

앱이 종료되지 않음

Windows 특정 문제

Intel Mac에서 Cowork 탭을 사용할 수 없음

CLI에서 열 때 “Branch doesn’t exist yet”

여전히 막혔나요?