기업 런처로 Claude Code 프로세스 감싸기

기준일: 2026-07-26
공식 기준: Run Claude Code behind a corporate launcher

개요

일부 조직은 워크스테이션의 모든 프로세스가 필수 런처를 통해 시작되어야 합니다. 런처가 샌드박스·네트워크 제어·자격 증명 주입을 적용하고, 없이 시작되는 바이너리는 정책 위반입니다.

CLAUDE_CODE_PROCESS_WRAPPER는 Claude Code가 자체 바이너리에서 기동하는 모든 프로세스를 런처로 시작합니다: 백그라운드 서비스, agent view의 모든 세션, 업데이트 후 재기동. 값을 런처 절대 경로로 두면 Claude Code는 런처를 실행하고 인자로 Claude Code 명령을 넘깁니다.

PATH의 claude만 감싸는 래퍼는 이 프로세스들에 도달하지 못합니다. 바이너리 직접 경로로 시작하며 claude PATH 조회를 하지 않기 때문입니다.

• CLAUDE_CODE_PROCESS_WRAPPER: v2.1.208+ (이전 버전은 무시, 언랩 기동)
• 동등 설정 processWrapper: v2.1.210+ (이전은 알 수 없는 키로 무시, 오류 없음)
• 배포 후 아래 Verify 단계로 적용 확인

핵심 개념

항목	내용
목적	Claude Code 자기 기동 프로세스를 기업 런처로 강제
Windows	변수 무시 (exec 계약 미지원). 언랩 동작 + debug 로그 경고
설정 위치	settings env 또는 top-level processWrapper (managed 권장)
프로젝트 설정	.claude/settings.json 등에서는 무시 (머신 전체 바이너리 삽입 방지)
vs SHELL_PREFIX	PROCESS_WRAPPER = Claude 자체 프로세스 argv exec / SHELL_PREFIX = Bash 등 셸 명령 $1 재평가

상세

런처가 덮는 프로세스

• claude agents·백그라운드 세션이 필요 시 띄우는 백그라운드 서비스
• agent view 각 행의 터미널 호스트·Claude Code 세션 (warm standby 포함)
• 업데이트·크래시 후 서비스가 재생성하는 세션
• 업데이트 완료를 위한 Claude Code 자체 재기동 (agent view restart-for-update 포함)
• v2.1.210+: 백그라운드 서비스가 관리하는 Remote Control 워커
• v2.1.210+: agent teams가 tmux/iTerm2에서 띄우는 split-pane 팀메이트 세션 (인터랙티브이지만 바이너리에서 시작)

Windows에서는 변수가 무시되어 항상 언랩입니다. Windows 정책 준수에는 이 변수만으로 부족합니다.

런처 밖 프로세스

• 런처 설정 전 쓰인 단위의 installed background service: launchd/systemd가 unit에서 시작. /status·claude daemon status가 불일치 경고. 서비스 재시작 후 생성 세션은 런처 경유
• 터미널에서 직접 연 세션: 호출 방식 그대로. PATH 앞쪽 claude 스크립트로 런처 호출 가능(관리 symlink 교체 금지). self-spawn은 PATH를 안 보므로 두 런처가 겹치지 않음
• claude-cli:// deep link 첫 프로세스: OS 프로토콜 핸들러. 이후 백그라운드는 런처. 완전 차단은 disableDeepLinkRegistration (deep links)
• --worktree + --tmux 재기동 페인: 멀티플렉서가 시작
• Claude in Chrome native-messaging host: 브라우저가 시작

프로세스 모니터 표시 이름

런처 사용 시 ps/Activity Monitor가 claude bg-pty-host 등 라벨 대신 버전 바이너리 이름을 보여줄 수 있습니다 (exec가 argv 재구성). 은닉이 아니라 부수 효과이며 Claude Code는 표시 이름이 아니라 바이너리 경로로 식별합니다.

설정 단계

1. 런처 스크립트

절대 경로 실행 파일 (예: /opt/corp/launcher). 끝은 반드시 exec "$@":

#!/bin/sh
# 샌드박스 진입, 네트워크 제어, 자격 증명 주입 등
exec "$@"

chmod +x. 이전에 ~/.local/bin/claude symlink를 런처로 바꿨다면 원본 symlink 복구. 교체된 symlink는 첫 랩 세션이 백그라운드 서비스를 이중 런처로 띄우고, 설치를 externally managed 상태로 만들어 /doctor 보고·auto-update 비정상·구버전 cleanup 비활성으로 이어집니다.

2. settings에 설정

detached 백그라운드 서비스가 상속하도록 settings env에 둡니다. 셸 export만으로는 부족합니다.

한 머신: ~/.claude/settings.json. 조직 전체: managed settings.

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

여러 소스가 설정하면 managed가 ~/.claude/settings.json·셸 export를 덮어 self-spawn 런처 변경을 막습니다.

이름 있는 키:

{
  "processWrapper": "/opt/corp/launcher"
}

v2.1.210+. 둘 다 있으면 시 CLAUDE_CODE_PROCESS_WRAPPER 우선. remote managed settings로 전달되면 security approval dialog에 관리자 실행 파일 설정과 함께 표시됩니다.

프로젝트/local settings는 런처를 설정할 수 없습니다. CLAUDE_CODE_PROCESS_WRAPPER는 .claude/settings.json / .claude/settings.local.json에서 무시( debug 로그 경고), processWrapper 키는 읽지 않습니다.

3. 백그라운드 서비스·세션 재시작

실행 중 서비스·세션은 시작 시 한 번만 변수를 읽습니다. claude daemon stop --any로 on-demand 서비스 중지 후 claude agents 등으로 다시 시작. installed service는 claude daemon stop ( --any 없이). 열린 claude 세션도 재시작.

수동 재시작 불가 머신: 설정 푸시 후 첫 새 세션이 남은 언랩 on-demand 서비스를 자동 정리. 새 세션이 없으면 언랩 유지. installed service는 항상 이 단계 재시작 필요.

4. Verify

세션 /status: Self-exec 항목에 resolved launch command, 백그라운드 서비스 불일치 시 경고. claude daemon status도 동일 정보(변수 해제 후에도 /status에 항목이 없을 때 유용).

런처 계약

런처를 실행할 수 없으면 Claude Code는 언랩으로 시작하지 않고 거부합니다 (Windows 제외).

• 끝은 exec "$@" — fork 후 종료하면 추적 불가 orphan. agent view는 런처 이름을 담은 실패 표시, 서비스가 잔여 정리
• 인자 재배열·흡수·앞에 붙이기 금지 — 첫 인자 = Claude Code 바이너리, 이후 argv
• 상속 환경 변수 전부 전달 — 추가(자격 증명 주입)는 OK, 상속 제거 금지. 세션 인증 토큰·모델/공급자·CLAUDE_CODE_PROCESS_WRAPPER 자체가 상속 env. allow list로 재구성하면 세션 깨짐·/status mismatch. namespace/sandbox가 env를 리셋하면 안에서 상속 env를 그대로 재export
• 약 3초 안에 exec — cold background dispatch는 첫 출력 전 런처를 연속 2회 실행. SSO 등 느린 작업은 lazy/캐시. 예산 초과는 stalled start로 재시작
• 자기 자신 안에서의 재진입 허용 — nested self-spawn마다 런처 적용. 배타 자원은 이미 보유 중 감지
• Claude Code 시작 전 터미널 출력 금지 — exec 전 출력이 초기화 전 크래시 원인으로 보고됨

값 형식

절대 경로 예: /opt/corp/launcher. 런처 자체 인자가 필요하면 경로 뒤에 공백 구분 토큰 (큰따옴표로 공백 포함 토큰). [로 시작하면 JSON 문자열 배열: ["/opt/corp/launcher", "--profile", "cc"]. 셸 확장·glob 없음. unquoted ; | & $( 등은 설정 오류. 사용 불가 시 프로세스 시작 거부 및 오류 레퍼런스.

CLAUDE_CODE_SHELL_PREFIX와의 관계

CLAUDE_CODE_PROCESS_WRAPPER는 Claude Code 자체 프로세스를 분리 argv로 exec. CLAUDE_CODE_SHELL_PREFIX는 Bash 도구·hooks·stdio MCP 시작 등 사용자 대신 도는 셸 명령을 $1 한 문자열로 재평가. 한쪽 런처를 다른 쪽에 그대로 쓰면 안 됩니다.

체크리스트

• v2.1.208+ (processWrapper면 2.1.210+) 확인
• 런처가 exec "$@"로 끝나고 상속 env를 유지한다
• settings env 또는 managed processWrapper에 절대 경로를 넣었다 (셸 export만 쓰지 않음)
• 프로젝트 settings에 런처를 두지 않았다
• daemon·세션을 재시작하고 /status / claude daemon status로 검증했다
• Windows는 언랩으로 남는 것을 롤아웃 계획에 반영했다

다음 단계

• Agent view
• Environment variables
• Managed settings
• Launcher errors

기준일

• 문서 작성·동기화 기준일: 2026-07-26
• 원문: https://code.claude.com/docs/en/corporate-launcher