Claude Desktop

설치 직후 PATH 가 반영되지 않으면 새 터미널 창을 열어야 한다 — 이미 열려 있던 창에는 적용되지 않는다. "다른 설치가 진행 중"이라는 오류가 근거 없이 뜨면 설치 관리자를 관리자 권한으로 실행한다.

베타다. 업데이트는 패키지 관리자로 하고(자동 업데이트가 아니다), Computer Use 는 아직 Linux 앱에 없다.

설치 후 앱을 실행하고 Anthropic 계정으로 로그인한다. 세 탭 중 Code 탭을 클릭해서 소프트웨어 개발 기능을 사용한다. CLI와 세션과 설정을 공유한다.

CLI 와 같은 엔진에 그래픽 인터페이스를 얹은 것이라, 같은 기기·같은 프로젝트에서 둘을 동시에 돌려도 된다. 세션 이력만 각자 따로 남고 설정과 CLAUDE.md 는 공유한다.

버전 번호를 클릭하면 클립보드로 복사된다. 문제를 신고할 때는 앱 버전·OS·정확한 오류 메시지를 함께 넣는다. 패널 배치·터미널·파일 편집기·뷰 모드는 v1.2581.0 이상에서만 있다.

일반적인 텍스트 대화를 위한 탭. 코드 작성 없이 아이디어를 브레인스토밍하거나 설명을 요청할 때 사용한다.

장기 실행 작업과 에이전트 협업을 위한 탭. 백그라운드 작업을 관리하고 여러 에이전트가 같은 작업에 협력할 수 있다.

스킬·플러그인·커넥터의 출처가 Code 탭과 다르다 — Cowork 는 사이드바의 Customize 설정(claude.ai 계정으로 동기화)에서 가져오고, CLI 의 ~/.claude 디렉터리를 읽지 않는다. Dispatch 도 이 탭에 산다.

소프트웨어 개발을 위한 전용 탭. 파일 읽기·쓰기, 명령 실행, Git 작업 등 개발에 필요한 모든 기능이 여기에 있다. 이 치트시트는 주로 이 탭을 기준으로 작성되었다.

첫 메시지를 보내기 전에 정하는 값이고, 이후 기능 가용성의 대부분이 여기서 갈린다. @멘션·커넥터·플러그인·터미널·사이드 채팅이 환경에 따라 있거나 없다. Cloud 는 앱을 닫아도 계속 돌고, SSH 는 원격 머신에서 돌고, WSL 은 Windows 의 리눅스 쪽에서 돈다.

여기서 고른 폴더가 프리뷰 서버의 작업 디렉터리도 된다 — 부모 폴더를 고르면 하위 폴더의 dev 서버는 자동 감지되지 않는다. 클라우드 세션은 저장소를 여러 개 붙일 수 있다.

CLI 의 --model 과 ANTHROPIC_MODEL 환경변수에 대응한다. 세션 중간에 같은 드롭다운에서 바꿀 수 있고, 사용 가능한 모델 목록은 CLI 와 같다.

새 로컬 세션의 기본값은 설정 파일의 permissions.defaultMode 로 정한다. 선택기에서 고른 모드는 폴더별로 기억되고 그 폴더에서는 defaultMode 보다 우선한다 — Plan 만 예외로 현재 세션에만 적용된다.

키보드로는 Esc. 진행 중인 도구 호출까지 끊는다.

CLI 에는 없는 기능이다. 버그 스크린샷, 디자인 목업, 참고 문서를 그대로 넘길 때 쓴다. 첨부 버튼으로도 되고 입력창에 끌어다 놓아도 된다.

커넥터와 플러그인 항목은 로컬·SSH 세션에서만 뜬다(클라우드·WSL 에는 없다). 스킬은 / 를 직접 입력해 찾는 것과 같은 목록이다.

고르면 입력창에 강조된 채로 들어가고, 뒤에 할 일을 이어 적어 보낸다. Claude 가 작업 중일 때도 다른 메시지처럼 보낼 수 있다(v2.1.206+). 그 전 버전에서는 턴 중간에 보낸 명령이 세션을 실행 중 상태로 붙잡아 이후 메시지가 전달되지 않았다.

데스크톱은 컨텍스트가 차면 자동으로 요약하고 계속 진행한다 — /compact 는 그 시점을 앞당겨 직접 부르는 것이다. 사용량은 모델 선택기 옆 사용량 링에서도 볼 수 있다.

데스크톱에서는 diff 를 명령 없이도 볼 수 있다 — 변경 후 뜨는 +12 -1 표시를 클릭하거나 Cmd/Ctrl+Shift+D 로 diff 패널을 연다.

셋 다 UI 에 대응 메뉴가 있다 — Cmd/Ctrl+Shift+I(모델), Cmd/Ctrl+Shift+E(추론 강도), Cmd/Ctrl+Shift+M(권한 모드). 열린 메뉴에서는 1~9 로 바로 고른다.

이름 변경은 상단 툴바의 세션 제목을 클릭해서도 된다. 며칠 뒤 사이드바에서 찾을 때 이름이 붙어 있는지가 갈린다.

diff 뷰어 우상단의 Review code 버튼이 같은 성격의 UI 진입점이다. 그쪽은 컴파일 오류·명백한 논리 오류·보안 취약점·확실한 버그에 집중하고 스타일은 보지 않는다.

/tasks 가 여는 것과 같은 내용을 Views 메뉴의 Tasks 패널로 상시 띄워 둘 수 있다 — 서브에이전트·백그라운드 셸·동적 워크플로의 진행이 여기 모인다.

정기 반복은 데스크톱에는 Scheduled tasks 라는 별도 기능이 있다 — CLI 에서 cron·CI 로 하던 자리다. /insights 는 이 기기의 기록을 분석하므로 클라우드 세션에서는 못 쓴다.

Cmd/Ctrl+; 와 같은 것을 연다. 본 대화 컨텍스트는 읽지만 기록에는 남지 않는다.

터미널에서 실행하면 세션을 저장해 데스크톱 앱에서 열고 CLI 는 종료된다. macOS 와 x64 Windows, Claude 구독 로그인에서만 된다 — API 키 인증이나 Bedrock·Agent Platform·Foundry 에서는 쓸 수 없다.

MCP 는 데스크톱에서 Connectors UI 로도 관리된다. 사용량은 사용량 링이 같은 정보를 준다.

Code 탭 자체가 이 패널들을 임의 배치하는 구조로 되어 있다. CLI 와 데스크톱을 나누는 실질적인 차이가 이것이다 — 같은 엔진이지만 변경·미리보기·터미널을 한 화면에 나란히 둘 수 있다.

패널 배치·터미널·파일 편집기·뷰 모드는 Claude Desktop v1.2581.0 이상이 필요하다. macOS 는 Claude → Check for Updates, Windows 는 Help → Check for Updates.

세션 툴바의 Views 메뉴에서 패널을 추가한다. tasks·subagent 패널은 여기서만 열 수 있고, 이 둘이 백그라운드 작업의 진행과 출력을 보는 창구다.

세션 두 개를 분할해 보고 있을 때도 같은 키로 포커스된 쪽을 닫아 단일 세션으로 돌아온다.

기본값. 도구 호출은 요약으로 접히고 텍스트 응답은 전문이 보인다.

Claude 가 왜 그 행동을 했는지 따질 때 쓴다. 모든 도구 호출·파일 읽기·중간 단계가 보인다. CLI 의 --verbose 에 대응한다.

세션을 여러 개 돌리며 결과만 빠르게 훑을 때 쓴다. 최종 응답과 변경만 남는다.

전송 버튼 옆 Transcript view 드롭다운에서도 고른다. Ctrl+O 는 macOS·Windows 모두 Ctrl 이다(Cmd 가 아니다).

Code 탭에서 쓸 수 있는 단축키 전체를 앱 안에서 띄운다. 아래 표가 낡았을 때의 정본이다.

정확히는 Ctrl+Tab / Ctrl+Shift+Tab 이고, 세션 순환·터미널 토글·뷰 모드 토글은 모든 플랫폼에서 Ctrl 이다(macOS 에서도 Cmd 가 아니다).

Ctrl+Tab 이 터미널 에뮬레이터나 창 관리자에 먹히는 환경에서 쓸 수 있는 같은 동작의 키다.

Browser pane 에서 요소를 집어 대화에 넘긴다 — "이 버튼"을 말로 설명하는 대신 지목한다.

모델(Cmd/Ctrl+Shift+I)·권한 모드(Cmd/Ctrl+Shift+M)·추론 강도(Cmd/Ctrl+Shift+E) 메뉴를 열고 숫자만 눌러 고르는 흐름이 가장 빠르다.

설정 키는 default. 편집·명령 전에 매번 묻고, diff 를 보고 건별로 수락·거부한다. 예전 버전에서는 이 모드가 Ask permissions 라는 이름이었다.

설정 키는 acceptEdits. 파일 편집과 mkdir·touch·mv 같은 기본 파일시스템 명령은 자동 승인하고, 그 밖의 터미널 명령은 여전히 묻는다. 예전 이름은 Auto accept edits.

설정 키는 plan. 파일을 읽고 명령으로 탐색하되 소스는 고치지 않고 계획을 제시한다. 복잡한 작업은 Plan 으로 시작해 접근을 합의한 뒤 Accept edits 나 Manual 로 옮겨 실행하는 순서가 권장된다. 폴더별 기억 대상이 아니라 현재 세션에만 적용된다.

설정 키는 auto. 요청과의 정합성을 백그라운드 분류기가 검사하면서 대부분을 자동 실행한다 — 감독을 유지한 채 확인 횟수만 줄이는 쪽이다.

계정 조건을 만족하면 선택기에 나타나고 별도 설정 토글은 없다. Anthropic API 에서는 전체 사용자에게 열려 있고 Opus 4.6+ · Sonnet 4.6+ · Fable 5 가 필요하다. 조직은 disableAutoMode 로 끌 수 있다.

설정 키는 bypassPermissions, CLI 의 --dangerously-skip-permissions 와 같다. 그래도 예외는 남는다 — 어떤 모드도 자동 승인하지 않는 행위, 외부 사이트에서의 안전 분류기, 세션 보관처럼 데스크톱이 항상 먼저 묻는 조작.

클라우드 세션은 파일 편집을 미리 승인하므로 선택기에 Manual 대신 Accept edits 가 뜨고, 그것이 default 모드에 대응한다. Bypass permissions 는 없다. 엔터프라이즈 관리자는 어떤 모드를 쓸 수 있는지 제한할 수 있다.

두 숫자의 층이 다르다. 컨텍스트 사용량은 세션별이고, 플랜 사용량은 모든 Claude Code 서피스가 공유한다 — 터미널에서 쓴 것도 여기 합산된다.

컨텍스트가 차면 데스크톱은 자동으로 대화를 요약하고 계속 간다. 그 시점을 앞당기려면 /compact 를 직접 부른다.

클라우드 세션도 별도의 컴퓨트 요금이 붙지 않고 구독 플랜 한도에 들어간다. 앱을 닫아도 계속 도는 성질과 합치면, 오래 걸리는 작업을 로컬에 붙잡아 둘 이유가 적다.

사이드바의 + New session 과 같다. 세션마다 컨텍스트와 변경이 독립이다. 상단 컨트롤로 상태·프로젝트·환경별 필터와 프로젝트별 묶어 보기를 쓸 수 있고, 이름 변경은 활성 세션 툴바의 제목을 클릭해서 한다.

작업이 끝났는데 내가 그 세션을 보고 있지 않으면 OS 알림이 온다.

기본 위치는 <프로젝트 루트>/.claude/worktrees/ 이고, 설정 → Claude Code 의 Worktree location 에서 바꿀 수 있다. 브랜치 이름 앞에 붙일 접두어도 정할 수 있어 Claude 가 만든 브랜치를 묶어 두기 쉽다.

.env 처럼 gitignore 된 파일을 새 워크트리에 넣어야 하면 프로젝트 루트에 .worktreeinclude 파일을 만든다 — 이것을 모르면 새 세션마다 환경변수가 없어 서버가 안 뜬다.

분할 중에 사이드바의 다른 세션을 클릭하면 포커스가 있는 쪽이 교체된다. Cmd/Ctrl+\ 로 포커스된 패널을 닫으면 단일 세션으로 돌아온다.

앱이 내 셸 환경을 전부 물려받지는 않는다. macOS 에서 Dock·Finder 로 실행하면 ~/.zshrc·~/.bashrc 를 읽되 PATH 와 정해진 몇 개의 Claude Code 변수만 가져오고, 거기서 export 한 다른 변수는 오지 않는다. Windows 는 사용자·시스템 환경변수는 물려받지만 PowerShell 프로필은 읽지 않는다.

그래서 변수를 넣는 자리가 따로 있다 — 프롬프트 박스의 환경 드롭다운에서 Local 에 마우스를 올리고 톱니 아이콘을 누르면 로컬 환경변수 편집기가 열린다. 여기 넣은 값은 암호화되어 저장되고 모든 로컬 세션과 프리뷰 서버에 적용된다. ~/.claude/settings.json 의 env 키는 Claude 세션에만 닿고 dev 서버에는 닿지 않는다.

사용량은 구독 플랜 한도에 합산되고 별도 컴퓨트 과금은 없다. 네트워크 접근 수준과 환경변수가 다른 커스텀 클라우드 환경을 만들 수 있다 — 클라우드 세션을 시작할 때 환경 드롭다운에서 Add cloud environment.

제약도 함께 온다: @멘션·커넥터·플러그인 브라우저·터미널·파일 편집기·사이드 채팅이 없고, 권한 모드는 Accept edits·Plan·Auto 만 있다.

환경 드롭다운의 + Add SSH connection 으로 추가한다. 물어보는 값은 넷 — Name(표시용 이름), SSH Host(user@hostname 또는 ~/.ssh/config 의 호스트), SSH Port(비우면 22 또는 SSH 설정의 값), Identity File(비우면 기본 키·SSH 설정).

원격은 Linux 또는 macOS 여야 하고, 처음 붙을 때 Claude Code 를 자동으로 설치한다. 붙은 뒤에는 권한 모드·커넥터·플러그인·MCP 서버가 다 된다. 스킬은 원격 홈의 ~/.claude/skills/ 를 읽는다.

WSL 2 배포판 안에서 그쪽 리눅스 툴체인과 네이티브 경로를 쓴다. @멘션·커넥터·플러그인은 WSL 세션에 없다(사이드 채팅은 된다).

세션 툴바의 서버 드롭다운에서 시작·중지, 전체 중지, 그리고 Edit configuration 으로 .claude/launch.json 을 편집기에서 열 수 있다.

서버 드롭다운에서 켠다. 개발 중에 매번 다시 로그인하지 않아도 되는 것이 요점이다. 저장된 세션 데이터를 지우거나 Browser 를 아예 끄는 것은 설정 → Claude Code 쪽이다.

Browser pane 은 탭 브라우저다. 돌고 있는 앱 옆에 문서·이슈 트래커를 나란히 둘 수 있다. 채팅의 외부 링크를 클릭하면 앱 안에서 열지(Open in app) 기본 브라우저로 보낼지 묻고, Cmd(macOS)·Ctrl(Windows) 클릭은 곧바로 시스템 브라우저로 보낸다.

줄을 클릭하면 코멘트 상자가 열리고 Enter 로 코멘트가 붙는다. 여러 줄에 달아 두고 Cmd/Ctrl+Enter 로 한꺼번에 제출하면 Claude 가 그것들을 읽고 고친 결과를 새 diff 로 준다.

한 건씩 말로 지시하는 것보다 이쪽이 낫다 — 지적이 코드 위치에 붙어 있어 어디를 말하는지가 해석 대상이 되지 않는다.

diff 뷰어 우상단에 있다. 커밋 전에 변경을 평가하게 하고, 코멘트가 diff 뷰어 안에 달린다. 각 코멘트에 답하거나 수정을 요청할 수 있다.

보는 것: 컴파일 오류, 확실한 논리 오류, 보안 취약점, 명백한 버그. 보지 않는 것: 스타일·서식·기존 문제·린터가 잡을 것.

CI 상태 바의 토글로 켠다. 실패 출력을 읽고 고침을 반복한다 — 터미널 쪽 /autofix-pr 이 클라우드 세션으로 같은 일을 맡기는 형태다.

병합 방식은 squash 고정이다. GitHub 저장소 설정에서 auto-merge 를 먼저 켜 두지 않으면 Claude 가 병합할 수 없다 — 토글은 켜지지만 병합이 되지 않는 상태가 된다.

CI 가 끝나면 OS 알림이 온다. PR 이 병합·닫히면 세션까지 자동으로 보관하려면 설정 → Claude Code 의 auto-archive 를 켠다(로컬 세션 중 실행이 끝난 것에만 적용된다).

로컬·SSH 세션에서만 된다(클라우드 세션은 Claude 에게 고치라고 하는 편이 맞다). HTML·PDF·이미지·영상은 파일 패널이 아니라 Browser pane 으로 열린다.

열어 둔 사이에 디스크에서 파일이 바뀌면 경고가 뜨고 덮어쓰기·버리기를 고르게 한다. 패널 헤더의 경로를 클릭하면 절대경로가 복사된다.

한쪽 방향으로만 통한다 — 그 시점까지의 본 대화를 읽지만, 여기서 주고받은 것은 본 대화에 아무것도 남기지 않는다. 코드 한 조각을 이해하거나 가정을 확인하려고 본 작업의 방향을 틀지 않아도 되는 것이 요점이다.

끝나면 닫고 본 세션을 이어 간다. 디스크에 저장되지 않으므로 앱을 닫으면 돌아갈 수 없다 — 남겨야 하는 결론은 본 대화로 옮겨 적어야 한다.

데스크톱 앱이 직접 돌리는 세션만 보인다 — Code 탭의 로컬·SSH·WSL 세션. 클라우드 세션, 터미널 CLI 로 띄운 세션, VS Code 확장의 세션은 같은 프로젝트의 워크트리라도 보이지 않는다(터미널 워크트리 9개와 데스크톱 세션 2개가 열려 있으면, 한쪽에서 물었을 때 나머지 데스크톱 세션 1개만 답한다).

기본은 최근 활동 20개이고 보관된 것은 요청해야 포함된다. 지금 묻고 있는 세션 자신은 절대 목록에 넣지 않는다. 터미널 세션까지 메시지를 보내려면 교차 세션 메시징 쪽이다.

현재 작업 범위를 벗어나지만 고칠 만한 것을 발견하면 Claude 가 칩으로 제안한다. 누르면 자기 워크트리를 가진 새 세션에서 그 일이 시작되고, 지금 세션은 끊기지 않는다. 본 작업의 diff 를 부풀리지 않고 발견을 남기는 장치다.

클라우드 환경을 고른 뒤 저장소 칩 옆 + 로 추가하고, 저장소마다 브랜치 선택기가 따로 붙는다. 공용 라이브러리와 그것을 쓰는 쪽을 함께 고치는 작업에 쓴다. CLI 의 --add-dir 에 해당하는 자리다.

세션 툴바 오른쪽 아래의 VS Code 아이콘에서 연다.

웹으로 보내기 — 브랜치를 푸시하고 대화 요약을 만들어 전체 맥락을 가진 클라우드 세션을 새로 만든다. 로컬 세션은 보관하거나 남겨 둘 수 있다. 작업 트리가 깨끗해야 하고 SSH 세션에서는 쓸 수 없다.

IDE 로 열기 — 현재 작업 디렉터리에서 프로젝트를 지원 IDE 로 연다.

클라우드 세션은 내 기기에 없는 브랜치를 만들 수 있다. CLI 에서 열려다 "Branch doesn't exist yet" 이 나오면 세션 툴바의 브랜치 이름을 클릭해 복사한 뒤 가져온다.

터미널에서 떨어져 있을 때 쓰는 여러 방법 중 하나다 — 원격 제어(/remote-control)나 웹 세션과는 성격이 다르다. 이쪽은 일을 던져 두고 결과를 기다리는 형태다.

computer use 를 켜 두면 Dispatch 가 띄운 Code 세션도 화면 조작을 쓸 수 있는데, 이때 앱 승인이 30분마다 만료되고 다시 묻는다(일반 세션은 세션 내내 유지).

가장 넓고 가장 느린 수단이다. Claude 는 정밀한 것부터 시도한다 — 커넥터가 있으면 커넥터, 셸 명령이면 Bash, 브라우저 작업이고 Claude in Chrome 이 있으면 그것, iOS 앱 실행·테스트면 iOS 시뮬레이터 패널, 그 어느 것도 아닐 때 화면 조작이다.

그래서 화면 조작이 남는 자리는 다른 수단이 닿지 못하는 것 — 네이티브 앱, 하드웨어 제어판, API 없는 사내 도구다.

앱을 처음 쓸 때 세션에 카드가 뜨고 Allow for this session 또는 Deny 를 고른다.

설정 → General 에 두 가지가 더 있다 — Denied apps 는 묻지도 않고 거부할 앱 목록, Unhide apps when Claude finishes 는 작업 중 숨겨 둔 다른 창을 끝나고 되돌릴지 여부다 (작업 중에는 승인된 앱만 다루도록 나머지 창을 숨긴다).

iOS 앱을 돌리고 테스트할 때는 화면 조작이 아니라 전용 패널이 열린다. 이 패널은 computer use 를 켜지 않아도 쓸 수 있다. 조직은 disableMobileSimulatorTools 로 Claude 의 접근만 막을 수 있고(사람의 조작은 남는다).

커넥터는 그래픽 설정 흐름이 붙은 MCP 서버다. 목록에 있는 서비스는 이쪽이 빠르고, 없는 것은 설정 파일로 MCP 서버를 직접 붙인다. 세션 시작 전에도 중간에도 추가할 수 있다.

붙이면 캘린더를 읽고 메시지를 보내고 이슈를 만드는 일을 바로 시킬 수 있다. 지금 세션에 무엇이 붙어 있는지 Claude 에게 물어봐도 된다.

프롬프트 박스의 Connectors 메뉴에서 Manage connectors 로도 같은 화면에 간다. 클라우드·WSL 세션에는 + 버튼이 없고, 클라우드에서 커넥터가 필요하면 루틴을 만들 때 함께 지정한다.

사이드바의 Customize 에서 셋을 함께 관리한다. 주의할 점은 출처다 — Cowork 탭은 이 Customize 설정(claude.ai 계정 동기화)에서 스킬·플러그인·커넥터를 가져오고, CLI 의 ~/.claude 디렉터리를 읽지 않는다. Code 탭의 로컬 세션과 서로 다른 목록을 볼 수 있다.

어느 스킬이 보이는지가 환경에 따라 다르다. 로컬 세션은 ~/.claude/skills/ 의 개인 스킬, SSH 세션은 원격 호스트의 ~/.claude/skills/(내 기기가 아니다), 클라우드 세션은 claude.ai 계정에서 켠 스킬을 불러온다.

터미널 없이 설치할 수 있다. Add plugin 이 플러그인 브라우저를 열고 설정된 마켓 (공식 Anthropic 마켓 포함)의 목록을 보여준다. Manage plugins 로 활성·비활성·삭제. 스코프는 CLI 와 같이 user·project·local 중에서 고른다.

정확히는 플러그인 브라우저가 클라우드 세션에 없고, 데스크톱에서 설치한 플러그인도 클라우드 세션에서는 쓰이지 않는다. 클라우드에서 쓰려면 둘 중 하나다 — 저장소 .claude/settings.json 의 enabledPlugins 에 적어 세션 시작 때 설치되게 하거나, claude.ai 계정에서 켜서 동기화된 플러그인으로 불러오게 하는 것. WSL 세션에는 아예 없다.

runtimeExecutable 은 npm·yarn·node 처럼 실행할 명령이다. 파일은 세션을 시작할 때 고른 폴더의 루트에 저장되고 그 폴더가 프리뷰의 작업 디렉터리가 된다 — 부모 폴더로 세션을 열면 하위 폴더의 dev 서버는 자동 감지되지 않는다.

configurations 배열에 여러 개를 정의해 프런트엔드와 API 를 같이 띄울 수 있다.

runtimeArgs 는 runtimeExecutable 에 넘기는 인자(["run", "dev"]), args 는 program 을 쓸 때만 쓰이는 인자다.

비워 두면 3000 이다. Claude 가 다른 포트를 잡게 되면 PORT 환경변수로 그 값을 서버에 넘긴다 — 서버가 그 변수를 읽지 않으면 엉뚱한 포트를 계속 열게 된다.

cwd 는 프로젝트 루트 기준 상대 경로이고, 루트를 명시하려면 ${workspaceFolder} 를 쓴다. env 는 { "NODE_ENV": "development" } 같은 추가 환경변수다.

세 가지 상태가 있고 기본값이 "묻는다" 라는 점이 중요하다.

true — 빈 포트를 찾아 쓴다(대부분의 dev 서버에 적합). false — 오류로 실패한다. OAuth 콜백이나 CORS 허용 목록처럼 그 포트여야 하는 서버에 쓴다. 지정하지 않음 — 그 포트가 꼭 필요한지 한 번 묻고 답을 저장한다.

program 은 node 로 바로 돌릴 단독 스크립트다("program": "server.js" → node server.js). 패키지 매니저를 거쳐 띄우는 것은 runtimeExecutable 쪽이다.

url 은 http://localhost:<port> 대신 열 주소다 — 로컬 HTTPS, *.localhost 서브도메인, 리다이렉트로 로그인하는 앱이 여기 해당한다. localhost 주소는 오리진만 허용된다 (경로·쿼리 불가, 포트는 항목의 port 와 일치해야 한다). 특정 페이지를 보려면 프리뷰가 열린 뒤 이동을 요청한다.

명령 없이 url 만 두면 내가 이미 돌리고 있는 서버에 프리뷰를 붙인다.

autoVerify 는 configurations 안이 아니라 최상위에 둔다. 켜져 있으면 파일을 고칠 때마다 스크린샷을 찍고 오류를 확인하고 동작을 검증한 뒤 응답을 끝낸다.

끄더라도 프리뷰 도구는 남아 있어 언제든 검증을 요청할 수 있다 — 자동인지 수동인지의 차이다.

조직 단위로 SSO 를 필수화할 수 있다. SAML 설정은 지원 문서, OIDC 는 엔터프라이즈 관리자 가이드에 있다.

앱 코드와 사용자 콘텐츠를 Anthropic CDN 에서 받으므로 이들이 막히면 빈 화면이 된다. 와일드카드까지 포함한 목록에 *.claudemcpcontent.com 도 있다.

트래픽은 443 HTTPS 다 — OTLP 모니터링·LLM 게이트웨이·MCP 서버에 사용자 지정 포트를 쓰는 경우만 예외다.

api.anthropic.com · a-api.anthropic.com · a-cdn.anthropic.com · s-cdn.anthropic.com · assets-proxy.anthropic.com · a.claude.ai · a-cdn.claude.ai · assets.claude.ai · downloads.claude.ai · platform.claude.com 처럼 개별 호스트로 좁힐 수 있다.

와일드카드로 남겨야 하는 것: *.livepreview.claude.ai · *.livepreview.claude.app · *.claudeusercontent.com · *.claudemcpcontent.com.

정확히는 로컬·SSH 세션은 배포에 설정된 모델 공급자(기본은 Anthropic API)로 대화와 코드 컨텍스트를 보내고, 클라우드 세션은 Anthropic API 로 보낸다. 조직이 자체 호스팅 환경으로 라우팅하면 클라우드 세션의 실행 위치가 그쪽으로 바뀐다.

데스크톱은 세션이 사이드바에 상시 늘어서 있으므로 재개가 곧 클릭이다. 상태·프로젝트·환경으로 걸러 볼 수 있다.

Cmd/Ctrl+Shift+M 으로 열고 1~9 로 고른다. 고른 값은 폴더별로 기억된다.

Pro·Max 는 설정 → Claude Code 의 Allow bypass permissions mode 를 먼저 켜야 선택기에 나타나고, Team·Enterprise 는 개인 토글이 없고 조직 정책이 정한다.

클라우드 세션에만 있는 대응이다. 로컬 세션에서 다른 폴더를 붙이는 UI 는 없으므로, 필요하면 그 폴더에서 세션을 새로 시작하거나 CLI 를 쓴다.

세션 단위로 도구를 열고 닫는 UI 가 없다. 다만 설정 파일의 권한 규칙은 데스크톱 세션에도 그대로 적용된다 — ~/.claude/settings.json 이나 프로젝트 설정에 규칙으로 적는다.

데스크톱은 대화형 전용이다. 스크립팅·자동화는 CLI 의 --print 나 Agent SDK 쪽이고, 이 축은 데스크톱으로 옮겨오지 않는다.

환경변수로 모델을 고정하는 대신 드롭다운에서 고른다. 세션 중간에도 같은 곳에서 바꾼다.

확장 사고는 기본 켜짐이다. Anthropic API 에서 끄려면 로컬 환경변수 편집기에서 이 값을 0 으로 둔다 — 단, Fable 5 는 항상 확장 사고를 쓰므로 효과가 없다.

적응형 추론을 쓰는 모델에서는 0 이외의 값이 무시된다(추론 깊이를 적응형이 정한다). Opus 4.6·Sonnet 4.6 에서 고정 예산으로 돌리려면 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1. Fable 5·Sonnet 5·Opus 4.7 이상은 항상 적응형이고 고정 예산 모드가 없다.

데스크톱은 Manual·Accept edits·Plan·Auto 이고, Bypass permissions 는 조건을 만족하면 선택기에 추가된다. dontAsk(미리 승인한 도구만 허용)는 CLI 전용이다.

데스크톱을 Bedrock·Agent Platform·Foundry 나 자체 호스팅 LLM 게이트웨이로 돌리는 경로는 따로 있다(게이트웨이 연결·3P 배포 문서). 기본 구성에서는 Anthropic API 다.

Connectors UI 는 로컬·SSH 세션에서만 뜬다. 목록에 없는 서비스는 양쪽 모두 설정 파일로 직접 붙인다.

데스크톱을 쓸 이유가 가장 분명한 항목이다 — 세션이 한 창에 모이고, 두 개를 나란히 볼 수 있고, 각자 워크트리가 자동으로 붙는다.

데스크톱의 전용 패널은 computer use 를 켜지 않아도 동작한다 — 화면 조작을 켜야만 되는 CLI 쪽과 다른 점이다.

팀장이 공용 작업 목록에서 동료에게 일을 배분하는 방식은 CLI 에만 있다. 데스크톱에서 한 세션 안의 다중 에이전트가 필요하면 동적 워크플로를 쓰거나, Claude 에게 다른 세션을 확인·메시지하게 한다.

데스크톱은 편집기 자동완성 같은 제안을 하지 않는다. 대화로 지시하고 명시적으로 코드를 바꾸는 방식이다 — IDE 확장을 대체하는 물건이 아니라는 뜻이다.

설정에 정의한 훅과 스킬이 양쪽에 적용된다. 다만 Cowork 탭은 예외로, Customize(claude.ai 계정)에서 가져오므로 ~/.claude 를 읽지 않는다.

셋 다 화면을 넓게 쓰는 일이다. 세션 여러 개를 한 창에서 돌리고, 미리보기·터미널·diff 를 나란히 두고, diff 의 줄에 코멘트를 달아 한꺼번에 넘긴다. 여기에 데스크톱만 있는 것이 더 붙는다 — 파일 첨부, iOS 시뮬레이터 패널, Dispatch, Scheduled tasks, 앱·화면 조작.

--print·Agent SDK·dontAsk 모드·에이전트 팀은 CLI 에만 있다. 파이프로 잇거나 CI 에서 돌리는 것도 이쪽이다.

둘을 고르는 문제가 아니다 — 같은 엔진이고 설정을 공유하므로 같은 프로젝트에서 동시에 쓰다가 /desktop 으로 세션을 옮길 수도 있다.

순서가 있다 — ① 앱 메뉴에서 로그아웃·재로그인(가장 흔한 해결) ② Pro·Max·Team· Enterprise 구독이 살아 있는지 ③ CLI 는 되는데 앱만 안 되면 창을 닫는 것이 아니라 앱을 완전히 종료한 뒤 다시 열어 로그인 ④ 네트워크·프록시 설정.

앱이 셸 프로필을 전부 읽지 않기 때문에 생긴다. 일반 터미널에서 그 도구가 되는지 확인하고, 셸 프로필이 PATH 를 제대로 세우는지 보고, 앱을 재시작해 환경변수를 다시 읽게 한다. 로컬 세션·dev 서버에 확실히 넘기려면 로컬 환경변수 편집기에 적는다.

macOS 는 Cmd+Q, 반응이 없으면 Cmd+Option+Esc 로 강제 종료. Windows 는 Ctrl+Shift+Esc 작업 관리자에서 Claude 프로세스를 끝낸다.

앱 버전·OS·정확한 오류 메시지·관련 로그. macOS 는 Console.app, Windows 는 이벤트 뷰어 → Windows 로그 → 응용 프로그램. 독립 claude CLI 에서도 재현되는 문제는 GitHub Issues 로 간다.

Cowork 탭과 Dispatch 쪽. Code 탭과 스킬·플러그인·커넥터의 출처가 다르다는 점이 실무에서 가장 자주 걸리는 지점이다.

Windows 에서 리눅스 툴체인으로 작업할 때. 이 세션에서는 @멘션·커넥터·플러그인이 빠진다는 제약을 먼저 확인한다.

apt 로 설치·갱신한다. Computer Use 는 아직 없다.