기업 런처 뒤에서 Claude Code 실행

​

런처가 포함하는 것

• claude agents와 백그라운드 세션이 필요에 따라 시작하는 백그라운드 서비스입니다.
• 모든 에이전트 뷰 행 내의 터미널 호스트 및 Claude Code 세션(서비스가 준비해 두는 웜 스탠바이 세션 포함).
• 업데이트 또는 충돌 후 서비스가 다시 생성하는 세션입니다.
• 업데이트 설치를 완료하기 위해 Claude Code가 자신을 재시작하는 것(에이전트 뷰의 업데이트를 위한 재시작 작업 포함).

​

런처 외부에서 시작되는 프로세스

• 설치된 백그라운드 서비스: launchd 또는 systemd가 해당 프로세스를 단위 파일에서 시작합니다. /status와 claude daemon status는 이것이 적용될 때 경고하며, 서비스가 변수를 설정한 상태로 재시작되면 서비스가 생성하는 세션은 여전히 런처를 통해 시작됩니다.
• 터미널에서 직접 시작하는 세션으로, 호출한 방식대로 실행됩니다. 이러한 세션을 포함하려면 PATH의 이전 디렉토리에 claude라는 스크립트를 배치하여 실제 바이너리로 런처를 실행합니다. 관리되는 심볼릭 링크를 교체하지 마십시오. 자체 생성은 PATH를 참조하지 않으므로 두 런처는 절대 스택되지 않습니다.
• claude-cli:// 딥 링크의 첫 번째 프로세스로, 운영 체제의 프로토콜 핸들러가 직접 시작합니다. 해당 세션이 백그라운드에서 시작하는 모든 것은 런처를 통해 실행됩니다. 이 경로를 완전히 닫으려면 disableDeepLinkRegistration 설정으로 핸들러 등록을 방지합니다.

​

프로세스 모니터의 헬퍼 프로세스 이름

​

런처 설정

#!/bin/sh
# Your organization's setup: enter the sandbox, apply
# network controls, or inject credentials.
exec "$@"

{
  "env": {
    "CLAUDE_CODE_PROCESS_WRAPPER": "/opt/corp/launcher"
  }
}

​

런처 계약

• exec "$@"로 끝냅니다. 자식을 포크하고 종료하는 런처는 백그라운드 서비스가 추적할 수 없는 고아 Claude Code 프로세스를 남깁니다. 에이전트 뷰는 런처 이름을 지정하는 메시지와 함께 이러한 세션을 실패로 표시하며, 서비스는 런처가 남긴 것을 수거합니다.
• 인수를 재정렬, 흡수 또는 앞에 추가하지 마십시오. 첫 번째 인수는 Claude Code 바이너리이고 그 이후의 모든 것은 해당 argv입니다.
• 상속된 모든 환경 변수를 exec를 통해 전달합니다. 주입된 자격 증명과 같은 변수를 추가하는 것은 괜찮습니다. 상속된 변수를 삭제하는 것은 아닙니다.
  • 세션별 인증 토큰, 모델 및 공급자 선택, 그리고 CLAUDE_CODE_PROCESS_WRAPPER 자체는 모두 상속된 환경에서 이동하므로 허용 목록에서 재구성하는 런처는 시작하는 세션을 중단하며, /status는 런처 불일치를 보고합니다.
  • 런처가 환경을 재설정하는 네임스페이스 또는 샌드박스에 들어가야 하는 경우, 상속된 환경을 그 안에서 그대로 다시 내보냅니다.
• 런처가 실행될 때마다 약 3초 이내에 exec에 도달합니다. 콜드 백그라운드 디스패치는 첫 번째 출력 바이트 전에 런처를 두 번 연속으로 실행하므로 단일 사인온 교환과 같은 느린 작업을 게으르게 또는 캐시에서 수행합니다.
  • 예산을 훨씬 초과하여 실행되는 런처는 정지된 시작으로 취급되고 재시작됩니다.
• 자신 내부에서 호출되는 것을 허용합니다. Claude Code는 모든 중첩된 자체 생성에 런처를 적용하므로 배타적 리소스를 획득하는 런처는 이미 보유하고 있음을 감지해야 합니다.
• Claude Code가 시작되기 전에 터미널에 쓰지 마십시오. exec 전에 인쇄된 모든 것은 세션이 초기화 전에 종료되면 충돌 원인으로 보고됩니다.

​

CLAUDE_CODE_PROCESS_WRAPPER 값의 형식

• 공백은 토큰을 분리하고 큰따옴표는 공백을 포함하는 토큰을 그룹화합니다.
• [로 시작하는 값은 ["/opt/corp/launcher", "--profile", "cc"]와 같은 JSON 문자열 배열로 읽혀집니다.
• 셸 구문은 작동하지 않습니다: 변수 확장이나 글로빙이 없으며, ;, |, & 또는 $(와 같은 인용되지 않은 연산자는 재해석되지 않고 구성 오류로 거부됩니다.

​

CLAUDE_CODE_SHELL_PREFIX와의 관계

​

관련 리소스

• 에이전트 뷰: 런처가 포함하는 백그라운드 세션 및 감독자 프로세스
• 환경 변수: CLAUDE_CODE_PROCESS_WRAPPER 참조 항목
• 관리되는 설정: 전체 플릿에 env 블록 전달
• 런처 오류 참조: 거부 메시지 및 복구 방법