logo

Claude Code Desktop 환경 구성

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

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

로컬 세션

데스크톱 앱이 항상 전체 셸 환경을 상속하지는 않습니다. macOS에서 Dock 또는 Finder에서 앱을 실행하면 ~/.zshrc 또는 ~/.bashrc와 같은 셸 프로필을 읽어 PATH 및 고정된 Claude Code 변수 집합을 추출하지만, 거기에 내보낸 다른 변수는 선택되지 않습니다. Windows에서 앱은 사용자 및 시스템 환경 변수를 상속하지만 PowerShell 프로필을 읽지 않습니다.

로컬 세션 및 개발 서버에 대한 환경 변수를 설정하려면 프롬프트 상자의 환경 드롭다운을 열고 Local 위에 마우스를 올린 다음 기어 아이콘을 클릭하여 로컬 환경 편집기를 엽니다. 여기에 저장한 변수는 머신에 암호화되어 저장되며 시작하는 모든 로컬 세션 및 미리보기 서버에 적용됩니다. ~/.claude/settings.json 파일의 env 키에 변수를 추가할 수도 있습니다. 단, 이는 Claude 세션에만 도달하고 개발 서버에는 도달하지 않습니다. 지원되는 변수의 전체 목록은 환경 변수를 참조하세요.

Extended thinking은 기본적으로 활성화되어 있으며, 복잡한 추론 작업의 성능을 향상시키지만 추가 토큰을 사용합니다. 생각을 완전히 비활성화하려면 로컬 환경 편집기에서 MAX_THINKING_TOKENS을 0으로 설정합니다. 적응형 추론이 있는 모델에서는 적응형 추론이 생각 깊이를 제어하기 때문에 다른 MAX_THINKING_TOKENS 값은 무시됩니다. Opus 4.6 및 Sonnet 4.6에서는 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING을 1로 설정하여 고정 생각 예산을 사용합니다. Opus 4.7은 항상 적응형 추론을 사용하며 고정 예산 모드가 없습니다.

원격 세션

원격 세션은 앱을 닫아도 백그라운드에서 계속됩니다. 사용량은 별도의 컴퓨팅 요금 없이 구독 계획 한도에 포함됩니다.

다양한 네트워크 액세스 수준 및 환경 변수를 가진 사용자 정의 클라우드 환경을 만들 수 있습니다. 원격 세션을 시작할 때 환경 드롭다운을 선택하고 환경 추가 를 선택합니다. 네트워크 액세스 및 환경 변수 구성에 대한 자세한 내용은 클라우드 환경을 참조하세요.

SSH 세션

SSH 세션을 사용하면 데스크톱 앱을 인터페이스로 사용하면서 원격 머신에서 Claude Code를 실행할 수 있습니다. 이는 클라우드 VM, 개발 컨테이너 또는 특정 하드웨어 또는 종속성이 있는 서버에 있는 코드베이스로 작업할 때 유용합니다.

SSH 연결을 추가하려면 세션을 시작하기 전에 환경 드롭다운을 클릭하고 + SSH 연결 추가 를 선택합니다. 대화 상자는 다음을 요청합니다:

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

추가되면 연결이 환경 드롭다운에 나타납니다. 이를 선택하여 해당 머신에서 세션을 시작합니다. Claude는 원격 머신에서 파일 및 도구에 액세스하여 실행됩니다.

원격 머신은 Linux 또는 macOS를 실행해야 합니다. 데스크톱은 처음 연결할 때 원격 머신에 Claude Code를 자동으로 설치합니다. 연결되면 SSH 세션은 권한 모드, 커넥터, 플러그인 및 MCP 서버를 지원합니다.

팀을 위해 SSH 연결을 미리 구성합니다

관리자는 관리되는 설정 파일에 sshConfigs를 추가하여 팀 멤버에게 SSH 연결을 배포할 수 있습니다. 이러한 방식으로 정의된 연결은 각 사용자의 환경 드롭다운에 자동으로 나타나며 관리되는 것으로 표시되므로 사용자는 이를 선택할 수 있지만 앱에서 편집하거나 삭제할 수 없습니다.

다음 예제는 원격 호스트의 ~/projects에서 열리는 단일 연결을 미리 구성합니다:

{
  "sshConfigs": [
    {
      "id": "shared-dev-vm",
      "name": "Shared Dev VM",
      "sshHost": "user@dev.example.com",
      "sshPort": 22,
      "sshIdentityFile": "~/.ssh/id_ed25519",
      "startDirectory": "~/projects"
    }
  ]
}

각 항목에는 id, name, sshHost가 필요합니다. sshPort, sshIdentityFile, startDirectory 필드는 선택 사항입니다. 사용자는 자신의 ~/.claude/settings.json에 sshConfigs를 추가할 수도 있습니다. 이는 대화 상자를 통해 추가된 연결이 저장되는 위치입니다.

SSH 호스트 연결을 제한하여 사용자가 연결할 수 있는 호스트를 제한합니다

관리자는 관리되는 설정 파일에 sshHostAllowlist를 추가하여 Desktop의 SSH 세션을 승인된 호스트 집합으로 제한할 수 있습니다. 설정되면 사용자는 확인된 호스트명이 패턴 중 하나와 일치하는 호스트에만 연결할 수 있습니다. SSH 세션을 완전히 비활성화하려면 빈 배열로 설정합니다.

다음 예제는 devboxes.example.com 아래의 모든 호스트 및 단일 명명된 bastion 호스트에 대한 연결을 허용합니다:

{
  "sshHostAllowlist": ["*.devboxes.example.com", "bastion.example.com"]
}

패턴은 대소문자를 구분하지 않습니다. *는 모든 호스트와 일치하고, *.example.com은 example.com 및 모든 하위 도메인과 일치합니다. 다른 모든 것은 정확한 일치입니다. 검사는 ssh -G를 통한 ~/.ssh/config 확인 후 호스트명에 대해 실행되므로 Host 별칭 및 ProxyCommand/ProxyJump 항목은 확인된 HostName이 일치하는 한 허용됩니다.

sshHostAllowlist는 관리되는 설정에서만 읽혀집니다. 사용자 또는 프로젝트 설정의 값은 무시됩니다. Claude Desktop 앱만 이 설정을 인식합니다. Claude Code CLI 및 IDE 확장은 이를 읽지 않으며, Bash 도구를 통해 실행되는 ssh 명령을 제한하지 않습니다. 이는 Desktop 앱이 연결하는 호스트를 제어하며, 네트워크 송신을 제어하지 않으므로 하드 경계가 필요한 경우 조직의 네트워크 또는 제로 트러스트 제어와 함께 사용합니다.

Previous
확장
Next
반복 작업 예약