Codex Mobile 개념과 설치 완전 가이드 1편: 폰으로 AI 코딩 에이전트를 원격 조종한다

에이전트가 리팩토링을 돌리는 15분 동안 책상에 묶여있을 필요가 없어졌다. OpenAI가 5월 14일 출시한 Codex Mobile은 Mac에서 돌아가는 Codex 세션에 iPhone·Android를 컨트롤 패널로 붙이는 기능이다. 코드를 폰에서 타이핑하는 게 아니다. 에이전트가 장시간 작업하는 동안 승인·리다이렉트·모니터링을 어디서든 할 수 있다. 구조와 설치법을 완전히 정리했다.

---

핵심 요약

→ Codex Mobile은 모바일 코드 에디터가 아닌 macOS 데스크탑 Codex 인스턴스의 원격 오케스트레이션 허브 — 코드·자격증명·권한은 호스트 머신에 그대로 유지
→ 별도 앱 없음 — 기존 ChatGPT 앱 업데이트만으로 사용 가능, iOS·Android 모두 지원
→ Free·Go·Plus·Enterprise 모든 플랜 포함 — 무료 사용자도 접근 가능
→ 설치 방법: Mac Codex 앱에서 QR코드 생성 → 폰으로 스캔 → 완료
→ 폰에서 할 수 있는 것: 새 작업 시작, 진행 중인 스레드 모니터링, 커맨드 승인, diff 검토, 다음 단계 지시
→ 현재 Mac 호스트만 지원 — Windows 호스트 연결은 출시 예정
→ CLI나 IDE 익스텐션으로는 모바일 설정 불가 — 반드시 Codex 데스크탑 앱에서 시작
→ 핵심 개념: Codex는 Mac에서 계속 실행, 폰은 컨트롤 서페이스 — 에이전트가 멈추면 폰으로 알림이 온다

---

1. Codex Mobile이 왜 필요한가

기존 AI 코딩 에이전트의 가장 큰 문제는 이것이다.

# 기존 Codex 워크플로우의 병목

[개발자]  책상에 앉아서 태스크 시작
    ↓
[Codex]   15~30분간 리팩토링·테스트 실행
    ↓
[개발자]  컴퓨터 앞에서 계속 대기 ← 비효율
    ↓
[Codex]   breaking change 발견 → 승인 요청
    ↓
[개발자]  응답 못 하면 에이전트 멈춤 or 잘못된 방향으로 진행

리팩토링을 시작하고 Codex가 15분 후 공유 유틸리티에서 breaking change를 발견해 판단을 요청할 때 — 5월 14일 이전엔 키보드에 묶여있거나 모멘텀을 잃는 것 중 하나를 선택해야 했다.

Codex Mobile이 이 구조를 바꾼다.

# Codex Mobile 워크플로우

[개발자]  Mac에서 태스크 시작 → 카페로 이동
    ↓
[Codex]   Mac에서 계속 실행 (폰 잠금과 무관)
    ↓
[폰 알림] "Breaking change 발견, 승인 필요"
    ↓
[개발자]  폰에서 diff 확인 → 승인 또는 새 지시
    ↓
[Codex]   Mac에서 이어서 실행

---

2. 아키텍처 — 어떻게 작동하나

# Codex Mobile 통신 구조

[iPhone/Android]
  ChatGPT 앱 (Codex 섹션)
        ↕ OpenAI Secure Relay
[Mac 호스트]
  Codex 데스크탑 앱
  ├── 프로젝트 파일 (로컬 유지)
  ├── 터미널·테스트 실행
  ├── 자격증명·권한 (폰에 전송 안 됨)
  └── Computer Use, 브라우저, 플러그인

모바일 앱은 OpenAI의 Secure Relay 레이어를 통해 태스크 상태·출력·승인 프롬프트를 기기 간에 동기화 — Codex Mobile은 호스트 머신의 로컬 파일을 직접 접근하거나 수정할 수 없다. 이는 무단 데이터 노출을 방지하기 위한 의도적인 보안 설계다.

핵심: 폰은 뷰어·컨트롤러, Mac은 실행 엔진. 코드와 데이터는 Mac을 떠나지 않는다.

---

3. 사전 요구사항 확인

# 필수 체크리스트

✅ ChatGPT 계정 (Free 포함 모든 플랜)
✅ macOS — Codex 데스크탑 앱 최신 버전 설치
✅ iOS/Android — ChatGPT 앱 2026년 5월 13일 이후 버전
✅ Mac과 폰이 동일한 ChatGPT 계정으로 로그인
✅ Mac이 켜져 있고 인터넷 연결 상태

❌ CLI(터미널)만으론 설정 불가
❌ IDE 익스텐션(VS Code 등)으론 설정 불가
❌ Windows 호스트 — 아직 미지원 (출시 예정)

# Mac에서 Codex 앱 버전 확인
# Codex 앱 메뉴 → About Codex → 버전 확인
# 최신 버전으로 업데이트 필요 시:
# developers.openai.com/codex → Download 클릭

# ChatGPT 모바일 앱 버전 확인
# iOS: App Store → 프로필 → 구매 항목에서 ChatGPT 확인
# Android: Play Store → 내 앱 → ChatGPT

---

4. 설치 — QR코드 스캔 5분 완성

1단계: Mac에서 Codex 모바일 설정 시작

Codex 데스크탑 앱 실행
  → 왼쪽 사이드바 하단 "Set up Codex mobile" 클릭
  → QR코드 화면 표시됨

⚠️ 이 화면이 안 보이면:
  - Codex 앱이 최신 버전인지 확인
  - Settings → Connections에서 Remote Control 활성화

2단계: 폰에서 QR코드 스캔

ChatGPT 앱 실행 (iOS/Android)
  → 하단 탭에서 "Codex" 섹션 찾기
  → "Connect to Mac" 또는 QR 스캔 버튼 탭
  → Mac 화면의 QR코드 스캔
  → 연결 완료 알림 확인

3단계: 연결 상태 확인

# Mac에서 확인
Codex 앱 → Settings → Connections
→ 연결된 기기 목록에 폰이 표시되어야 함
→ "Keep computer awake" 옵션 — Mac 슬립 방지 (장시간 에이전트 실행 시 필수)
→ "Computer Use" 옵션 — 에이전트가 데스크탑 앱 조작 허용 여부

# 폰에서 확인
ChatGPT 앱 Codex 섹션
→ Mac 호스트의 프로젝트 목록이 로드되면 성공

---

5. 폰에서 할 수 있는 것

원격 접속은 호스트의 프로젝트·스레드·파일·자격증명·권한·플러그인·Computer Use·브라우저 설정·로컬 툴을 그대로 사용 — 호스트의 프로젝트에서 새 스레드를 시작하거나 기존 스레드를 이어갈 수 있다.

# 폰에서 가능한 작업

✅ 새 태스크 시작
   "이 함수 전체 테스트 코드 작성해줘"
   → Mac의 Codex가 실제 파일에 접근해서 실행

✅ 진행 중인 스레드 모니터링
   → 터미널 출력, 테스트 결과, diff 실시간 확인

✅ 커맨드 승인
   → "rm -rf 실행할까요?" 같은 위험 명령 폰에서 승인/거부

✅ diff 검토 및 피드백
   → 코드 변경사항 확인 후 "좋아 계속해" 또는 "이 부분 다시 해줘"

✅ 다음 단계 지시
   → "테스트 통과했으면 PR 설명 초안 작성해줘"

✅ 호스트·스레드 전환
   → 여러 Mac에 연결된 경우 폰에서 호스트 선택

❌ 폰에서 불가능한 것
   → 로컬 파일 직접 수정
   → 새 플러그인 설치
   → 초기 모바일 연결 설정 (Mac 앱에서만 가능)

---

6. 첫 번째 원격 세션 실행

# 실전 시나리오: 집에서 태스크 시작 → 이동 중 폰으로 관리

# 1. Mac에서 시작 (출발 전)
Codex 앱에서 프로젝트 열기
→ "src/api/payment.ts의 에러 핸들링 개선하고 테스트도 추가해줘"
→ Codex가 파일 분석 시작

# 2. 이동 (Mac은 계속 실행 중)
ChatGPT 앱 → Codex 섹션 → 진행 상황 확인
→ 터미널 출력 스크롤: "Analyzing payment.ts..."
→ 5분 후 알림: "Codex가 입력을 기다리고 있어요"

# 3. 폰에서 승인
diff 화면:
+ try {
+   await stripe.refund(chargeId);
+ } catch (StripeError e) {
+   logger.error('Refund failed', { chargeId, error: e });
+   throw new PaymentError(e.message);
+ }
→ "승인" 탭 → Codex 계속 실행

# 4. 완료 알림 수신
"테스트 3개 추가됨, 모두 통과"
→ "좋아, 이제 CHANGELOG.md 업데이트해줘" 입력
→ Mac에서 이어서 실행

---

7. 자주 발생하는 문제

# 문제 1: ChatGPT 앱에 Codex 섹션이 안 보임
원인: 앱 버전이 구버전 또는 지역 미지원
해결:
→ App Store/Play Store에서 ChatGPT 강제 업데이트
→ 앱 종료 후 재시작
→ 계정 플랜 및 지원 지역 확인 (일부 국가 미지원)

# 문제 2: QR코드 스캔 후 연결 실패
원인: Mac과 폰이 다른 계정으로 로그인됨
해결:
→ Codex 앱 Settings → 로그인 계정 확인
→ ChatGPT 앱 → 프로필 → 계정 확인
→ 두 기기 모두 동일 계정인지 대조

# 문제 3: 폰에서 Mac 프로젝트가 로드 안 됨
원인: Mac이 슬립 상태 또는 오프라인
해결:
→ Codex 앱 → Settings → Connections → "Keep computer awake" 활성화
→ Mac 전원 설정에서 슬립 타임아웃 늘리기

# 문제 4: 엔터프라이즈 워크스페이스에서 연결 불가
원인: 관리자가 Remote Control 비활성화
해결:
→ IT 관리자에게 Codex 클라우드 설정에서
  remote_computer_use = true 설정 요청
→ OpenAI 관리자 콘솔 → Policies & Configurations → Codex

# 문제 5: 알림이 안 옴
원인: iOS/Android 알림 권한 미부여
해결:
→ 기기 설정 → ChatGPT → 알림 → 허용

---

✅ 결론

✅ 별도 앱 없이 ChatGPT 앱 업데이트만으로 사용 가능
✅ QR코드 스캔으로 5분 안에 연결 완료
✅ 모든 플랜 무료 포함 접근 가능
✅ 코드·자격증명은 Mac에서 절대 떠나지 않는 보안 구조
✅ 장시간 에이전트 작업에서 책상에 묶이지 않아도 됨

❌ Mac 전용 (Windows 호스트 미지원, 출시 예정)
❌ 폰에서 직접 코드 편집은 불가
❌ CLI·IDE 익스텐션으로는 설정 불가

2편에서는 Hooks 자동 승인 규칙과 Goal Mode로 진짜 장시간 에이전트 루프를 만드는 법을 다룬다.

---

관련 글

• Codex Mobile 1편 — 설치와 연결
• Codex Mobile 2편 — Hooks와 Goal Mode 실전

• Codex Mobile 3편 — vs Claude Code Remote Control