macOS GUI Shell Env 미상속

• macOS GUI 앱의 Shell Env 미상속은 macOS가 GUI 앱을 launchd로 직접 실행할 때 사용자 쉘 설정(~/.zshrc)을 로드하지 않아 사용자 정의 환경변수가 전달되지 않는 OS 레벨 동작
• 터미널을 통한 실행과 달리 Dock/더블클릭 실행에서만 발생하는 실행 경로(부모 프로세스)의 차이
• Electron, Swift, Objective-C 등 모든 macOS GUI 앱이 공통적으로 겪는 현상이며, Electron 고유 버그가 아님

해당 개념이 필요한 이유

• 개발 환경(터미널 실행)에서는 정상 동작하지만 prod 빌드(GUI 실행)에서 API 키, 커스텀 PATH 등이 사라져 인증 실패나 커맨드 not found가 발생
• ~/.zshrc에 env를 아무리 잘 설정해도 prod 앱에는 도달하지 않는다는 사실을 모르면 원인 파악에 큰 어려움

AS-IS (수정 전 실행 경로)

sequenceDiagram
    autonumber
    participant T as 터미널(dev)
    participant L as launchd(prod)
    participant Z as ~/.zshrc
    participant E as Electron App

    Note over T,E: dev 실행 경로
    T->>Z: 로그인 쉘 생성 → ~/.zshrc 로드
    Z-->>T: OPENAI_API_KEY, PATH 등 env 설정됨
    T->>E: npm run dev (자식 프로세스 → env 상속 ✅)

    Note over L,E: prod 실행 경로 (수정 전)
    L->>E: Dock 더블클릭 → launchd가 직접 실행
    Note over E: ~/.zshrc 로드 없음<br/>env = 시스템 기본값만<br/>OPENAI_API_KEY ❌<br/>PATH = /usr/bin:/bin만 ❌

TO-BE (수정 후)

sequenceDiagram
    autonumber
    participant L as launchd
    participant E as Electron (Main)
    participant Z as /bin/zsh
    participant B as Backend Process

    L->>E: 앱 실행 (env = 시스템 기본값)
    E->>Z: app.whenReady() → spawn("/bin/zsh", ["-ilc", "env"])
    Z-->>E: stdout: OPENAI_API_KEY=...\nPATH=...50개 env
    E->>E: Object.assign(process.env, parsedEnv)
    E->>B: startBackend({ ...process.env })
    Note over B: 쉘 env 포함된 상태로 실행 ✅

launchd vs 터미널 실행의 차이

macOS 프로세스 계층에서 누가 앱을 실행(spawn)하느냐가 핵심이다.

항목	터미널 실행 (dev)	launchd 실행 (prod)
부모 프로세스	사용자 쉘 (zsh/bash)	launchd (PID 1)
~/.zshrc 로드	✅	❌
사용자 정의 env	전부 상속	시스템 기본값만
PATH	/opt/homebrew/bin 등 포함	/usr/bin:/bin:/usr/sbin:/sbin
API 키	있음	없음

유닉스 env 상속 원칙: 자식 프로세스는 부모의 env를 그대로 복사해 시작한다. launchd는 사용자 쉘이 아니므로, 사용자가 쉘에 정의한 env를 알 수 없다.

실제 경험한 현상 (Electron + Codex CLI 케이스)

[prod 빌드, 수정 전]
checkCodexAuth() 호출
→ codex exec probe 실행
→ OPENAI_CODEX_API_KEY 없음 → not-authenticated ❌

에러 로그 (에러 핸들링 추가 후 확인):
Command failed: codex exec --model gpt-5.2-codex say ok
Not inside a trusted directory and --skip-git-repo-check was not specified.

이 케이스에는 2개의 독립된 문제가 숨겨져 있었다:

관문	문제	원인
1차	env 미상속 → API 키 없음	macOS launchd 설계
2차	trusted directory 거부	codex CLI 보안 정책 (앱 번들 내부는 git repo 아님)

1차에서 이미 실패하므로 2차 문제가 prod에서 숨겨져 있었고, catch(() => false)가 에러를 삼켜서 원인 파악이 더 늦어졌다.

해결 패턴: Login Shell Spawn

VS Code(resolveShellEnv()), JetBrains IDE, shell-env npm 패키지 등 모든 주요 GUI 앱이 동일하게 사용하는 업계 표준 패턴이다.

// electron/services/shell-env.service.ts
async function loadShellEnv(): Promise<void> {
  const shell = os.userInfo().shell ?? '/bin/zsh'
  // -i: interactive, -l: login (~/.zshrc 로드), -c: command
  const child = spawn(shell, ['-ilc', 'echo DELIM; env; echo DELIM; exit'])
 
  // stdout 파싱 → key=value 추출
  const parsed = parseEnvOutput(stdout)  // ~50개 env 변수
 
  Object.assign(process.env, parsed)  // process.env에 merge
  // 이후 startBackend({ ...process.env }) → 자동 전파
}
 
// app.whenReady() 시점에 호출 (백엔드 시작 전)
app.whenReady().then(async () => {
  await loadShellEnv()   // 300-400ms 소요
  await startBackend()
})

쉘 fallback 체인: 감지된 쉘 → /bin/zsh → /bin/bash → process.env 그대로 사용

Edge case:

• nushell 등 비표준 쉘 → /bin/zsh로 fallback
• ~/.zshrc 문법 오류 → /bin/bash로 fallback
• 5초 내 응답 없음 → timeout 후 앱 정상 시작 (env 없이)

참고 문서

• Electron #550 — PATH missing in packaged app
• electron-builder #3363 — env missing in built app
• shell-env npm package
• Apple Developer Forums — launchd env