11. Windows에서의 사용 포인트

이 페이지에서 배우는 것

• 1 PowerShell이 무엇인지, WSL이 무엇인지 쉬운 말로 이해하기
• 2 내 상황에 맞는 모드 선택 방법 (PowerShell Native vs WSL)
• 3 Windows에서 Codex app을 처음부터 끝까지 설치하는 방법
• 4 Sandbox(샌드박스)가 무엇이고 왜 중요한지 이해하기
• 5 Execution Policy 오류를 직접 해결하는 방법
• 6 Windows와 WSL의 파일 경로 차이를 이해하기
• 7 초보자가 자주 겪는 문제와 해결법 (FAQ)

Windows에서 Codex 시작하기

"Codex는 macOS 전용 아닌가요?" 라는 질문을 많이 받습니다. 아닙니다. Codex app은 Windows에서도 훌륭하게 동작합니다.

Windows 사용자에게는 두 가지 실행 모드가 제공됩니다:

PowerShell이란?

컴퓨터에게 명령을 내리는 방법은 크게 두 가지가 있습니다. 하나는 마우스로 아이콘을 클릭하는 것(GUI), 다른 하나는 글자를 입력해서 명령하는 것(CLI)입니다.

PowerShell은 Windows에 기본으로 포함된 CLI 도구입니다. macOS의 "터미널(Terminal)"과 같은 역할을 합니다. 파일을 복사하거나, 프로그램을 설치하거나, 개발 도구를 실행하는 등 다양한 작업을 글자 명령으로 할 수 있습니다.

Codex app은 이 PowerShell을 통해 여러분의 컴퓨터에서 코드를 실행하고, 파일을 수정하고, Git 명령을 수행합니다. 쉽게 말해, Codex가 여러분 대신 PowerShell에 명령을 타이핑해주는 것이라고 생각하면 됩니다.

# PowerShell을 여는 방법
# 1. Windows 키를 누르고 "PowerShell"을 검색합니다
# 2. "Windows PowerShell"을 클릭합니다
# 3. 파란 배경의 창이 열리면 성공!

# 간단한 테스트: 현재 위치 확인하기
Get-Location

WSL이란?

WSL은 Windows Subsystem for Linux의 약자입니다. 한마디로, Windows 안에서 Linux를 실행할 수 있게 해주는 기능입니다.

왜 이런 게 필요할까요? 많은 개발 도구(Node.js, Python, Docker 등)가 원래 Linux용으로 만들어졌기 때문입니다. Windows에서도 이런 도구를 쓸 수 있지만, Linux에서 쓸 때와 약간 다르게 동작하는 경우가 있습니다. WSL을 사용하면 Windows를 벗어나지 않으면서도 진짜 Linux 환경을 쓸 수 있습니다.

비유하자면, Windows 컴퓨터 안에 작은 Linux 컴퓨터가 하나 더 들어있는 것과 비슷합니다. 두 컴퓨터는 파일도 공유할 수 있고, 서로 전환도 쉽습니다.

# WSL 설치 방법 (PowerShell을 관리자 권한으로 실행)
wsl --install

# 설치 후 컴퓨터를 재시작하면 Ubuntu Linux가 자동으로 설정됩니다
# 사용자 이름과 비밀번호를 설정하라는 메시지가 나옵니다

어떤 모드를 선택해야 하나요?

아래 표를 보고 자신의 상황에 맞는 모드를 선택하세요. 확실하지 않으면 PowerShell Native로 시작하는 것을 추천합니다. 기본값이라 설정이 가장 간단합니다.

PowerShell Native vs WSL 모드 상세 비교

두 모드의 기술적 차이를 좀 더 자세히 살펴보겠습니다.

Windows 설정 흐름

Windows에서 Codex app을 사용하기까지의 과정은 아래 4단계로 요약됩니다.

Windows 설치 완전 가이드

Codex app을 설치하는 방법은 두 가지가 있습니다. 둘 중 편한 방법을 선택하세요.

방법 1: Microsoft Store에서 설치하기 (가장 쉬움)

• 1 Windows에서 Microsoft Store 앱을 엽니다 (작업표시줄의 쇼핑백 아이콘 또는 시작 메뉴에서 검색).
• 2 검색창에 "Codex"를 입력하고 검색합니다.
• 3 "설치" 버튼을 클릭합니다. 다운로드와 설치가 자동으로 진행됩니다.
• 4 설치가 완료되면 "열기"를 클릭하거나, 시작 메뉴에서 Codex를 찾아 실행합니다.

방법 2: winget 명령어로 설치하기 (개발자 추천)

winget은 Windows용 패키지 관리자입니다. macOS의 brew, Linux의 apt와 비슷합니다. PowerShell에서 명령어 한 줄로 프로그램을 설치할 수 있습니다.

# PowerShell을 열고 아래 명령어를 입력하세요
winget install Codex -s msstore

필수 개발 도구 한 번에 설치하기

Codex 에이전트가 원활하게 동작하려면 아래 도구들이 시스템에 설치되어 있어야 합니다. PowerShell을 관리자 권한으로 실행한 뒤 아래 명령어를 하나씩 입력합니다.

# Git - 코드 버전 관리 (거의 모든 프로젝트에 필수)
winget install Git.Git

# Node.js - JavaScript/TypeScript 실행 환경
winget install OpenJS.NodeJS.LTS

# Python - 데이터 분석, AI, 웹 개발 등 다양한 용도
winget install Python.Python.3.12

# .NET SDK - C# 개발자만 필요 (아니면 건너뛰세요)
winget install Microsoft.DotNet.SDK.8

# GitHub CLI - GitHub에서 PR, Issue를 명령어로 관리
winget install GitHub.cli

Sandbox(샌드박스)란?

Sandbox는 "모래놀이 상자"라는 뜻입니다. 아이들이 모래 상자 안에서 놀듯이, Codex가 안전한 울타리 안에서만 작업하도록 제한하는 보호 장치입니다.

왜 필요할까요? Codex는 AI 에이전트이기 때문에 파일을 수정하거나 명령어를 실행할 수 있습니다. 만약 실수로 잘못된 명령을 실행하면 시스템에 문제가 생길 수도 있겠죠. Sandbox는 이런 위험을 방지합니다.

PowerShell Native 모드에서는 native Windows 샌드박스(Codex가 PowerShell 실행 시 자체적으로 적용하는 보호)가, WSL 모드에서는 WSL 내부 격리가 사용됩니다. 어떤 모드를 선택하든 보호 기능이 동작하므로 안심하세요. 주의: 여기서 말하는 "native Windows 샌드박스"는 Codex 앱 내부 보호를 의미하며, Microsoft가 Windows Pro/Enterprise에 제공하는 별도 기능인 "Windows Sandbox"(Hyper-V 기반 가상 머신)와는 다릅니다 — Codex 사용에 Windows Pro 에디션은 필요하지 않습니다.

PowerShell Execution Policy 이해하기

Windows에서 Codex를 처음 실행할 때 가장 많이 겪는 오류가 바로 Execution Policy(실행 정책) 관련 오류입니다. 이것이 무엇인지, 왜 생기는지, 어떻게 해결하는지 차근차근 알아보겠습니다.

Execution Policy가 뭔가요?

Windows는 보안을 위해 PowerShell 스크립트(자동 실행 파일)의 실행을 기본적으로 차단합니다. 인터넷에서 다운로드한 악성 스크립트가 함부로 실행되는 것을 막기 위해서입니다. 하지만 Codex는 정상적인 도구이므로, 이 제한을 적절히 풀어줘야 합니다.

단계별 해결 방법

# 1단계: 현재 정책 확인하기
Get-ExecutionPolicy
# "Restricted"라고 나오면 스크립트 실행이 차단된 상태입니다

# 2단계: 정책 변경하기 (관리자 권한 PowerShell에서 실행)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# "RemoteSigned"는 안전한 설정입니다:
# - 내 컴퓨터에서 만든 스크립트: 실행 허용
# - 인터넷에서 다운로드한 스크립트: 서명이 있어야만 실행 허용

# 3단계: 변경 확인하기
Get-ExecutionPolicy
# "RemoteSigned"라고 나오면 성공!

파일시스템 위치가 왜 중요한가요?

WSL을 사용하면 컴퓨터 안에 두 개의 파일 저장소가 생깁니다. 하나는 Windows의 파일 시스템, 다른 하나는 Linux의 파일 시스템입니다. 프로젝트 파일을 어디에 저장하느냐에 따라 속도 차이가 크게 날 수 있습니다.

핵심 포인트 요약

• 1 Microsoft Store 또는 winget install Codex -s msstore로 설치합니다.
• 2 잘 모르겠으면 PowerShell Native 모드로 시작하세요. 기본값이라 추가 설정이 필요 없습니다.
• 3 Sandbox 보호를 최대한 활용하려면 Codex의 기본 권한을 유지하세요.
• 4 Execution Policy 오류가 나오면 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser를 실행하세요.
• 5 프로젝트 파일은 사용하는 모드와 같은 파일시스템에 저장해야 속도가 빠릅니다.

실전 팁

자주 묻는 질문 (FAQ)

WSL · 환경 변수 주의사항

• ✓경로 권장사항 — 프로젝트는 가능한 한 Windows 쪽 디스크(C:\)에 두고 WSL에서는 /mnt/c/<path>로 접근하세요. \\wsl$\<Distro>\... UNC 경로는 일부 git/도구가 저장소 루트를 잘못 인식할 수 있습니다.
• ✓WSL ↔ Windows 동기화 — WSL 셸에서 다음을 추가하면 Codex가 Windows 쪽 설정/세션과 같은 디렉터리를 공유합니다.
  export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex
• ✓GitHub 통합 — PR 체크아웃과 Review Pane을 사용하려면 한 번 gh auth login으로 인증해야 합니다(WSL과 Windows 양쪽 셸에서 모두 인증 권장).

Settings — 에디터·셸 선택

• ✓Preferred Editor — Visual Studio, VS Code 등 "파일 열기" 동작에 사용할 외부 에디터를 선택할 수 있고, 프로젝트별로 override됩니다.
• ✓기본 셸 — PowerShell / Command Prompt / Git Bash / WSL 중 하나를 선택. 변경 후에는 Codex 앱을 재시작해야 적용됩니다.
• ✓새 프로젝트 추가 — Windows에서는 Ctrl+O 단축키로 사이드바의 "Add new project" 다이얼로그를 즉시 엽니다.

다음 단계

Windows 설정이 완료되었으면 아래 가이드를 이어서 살펴보세요.

• 설치와 첫 메시지 - Codex app을 처음 열고 첫 번째 작업을 시작하는 방법을 배웁니다.
• 프로젝트와 멀티태스킹 - 여러 프로젝트를 동시에 관리하는 방법을 알아봅니다.
• Local Environment와 Setup Script - 프로젝트별 개발 환경을 설정하는 방법을 배웁니다.
• 자주 막히는 문제 - 문제가 생겼을 때 해결 방법을 찾아보세요.

장점 / 단점 / 한계점