Windows

Windows에서는 native Codex 앱, CLI, IDE 확장으로 Codex를 사용할 수 있습니다.

Windows용 Codex 앱은 병렬 에이전트 스레드, worktree, 자동화, Git 기능, 앱 내 브라우저, artifact 미리보기, 플러그인, 스킬 같은 핵심 워크플로를 지원합니다.

Windows에서 Codex는 표면과 설정에 따라 세 가지 실용적인 방식으로 실행될 수 있습니다.

• 더 강한 elevated 샌드박스와 함께 Windows에서 native 실행
• fallback unelevated 샌드박스와 함께 Windows에서 native 실행
• Linux 샌드박스 구현을 사용하는 Windows Subsystem for Linux 2(WSL2) 안에서 실행

Windows 샌드박스

Windows에서 Codex를 native로 실행하면 agent mode는 Windows 샌드박스를 사용해 작업 폴더 밖의 파일 시스템 쓰기를 차단하고, 명시적 승인 없는 네트워크 접근을 방지합니다.

Native Windows 샌드박스는 config.toml에서 구성할 수 있는 두 가지 모드를 지원합니다.

[windows]
sandbox = "elevated" # 또는 "unelevated"

elevated는 권장 native Windows 샌드박스입니다. 샌드박스 안에서 실행되는 명령을 위해 dedicated lower-privilege sandbox user, 파일 시스템 권한 경계, firewall rule, local policy 변경을 사용합니다.

unelevated는 fallback native Windows 샌드박스입니다. 현재 사용자에서 파생된 restricted Windows token으로 명령을 실행하고, ACL 기반 파일 시스템 경계를 적용하며, dedicated offline-user firewall rule 대신 environment-level offline control을 사용합니다. elevated보다 약하지만 local 또는 enterprise policy가 administrator-approved setup을 막을 때 여전히 유용합니다.

두 모드 모두 사용할 수 있다면 elevated를 사용합니다. 기본 native sandbox가 환경에서 작동하지 않으면 설정을 troubleshooting하는 동안 unelevated를 fallback으로 사용합니다.

기본적으로 두 샌드박스 모드 모두 더 강한 UI isolation을 위해 private desktop도 사용합니다. compatibility를 위해 이전 Winsta0\\Default 동작이 필요할 때만 windows.sandbox_private_desktop = false를 설정합니다.

샌드박스 권한

full access 모드로 Codex를 실행하면 Codex가 프로젝트 디렉터리로 제한되지 않으며 데이터 손실로 이어질 수 있는 의도치 않은 파괴적 action을 수행할 수 있습니다. 더 안전한 자동화를 위해 샌드박스 경계를 유지하고 특정 예외에는 규칙을 사용하십시오. 또는 승인과 보안 설정에 따라 Codex가 escalated permission을 묻지 않고 문제 해결을 시도하게 하려면 approval policy를 never로 설정할 수 있습니다.

Windows 버전 matrix

추가 환경 가정:

• winget을 사용할 수 있어야 합니다. 없으면 Codex 설정 전에 Windows를 업데이트하거나 Windows Package Manager를 설치합니다.
• 권장 native sandbox는 administrator-approved setup에 의존합니다.
• 일부 enterprise 관리 기기는 OS version 자체가 적합하더라도 필요한 설정 단계를 차단합니다.

샌드박스 read access 부여

Windows 샌드박스가 디렉터리를 읽을 수 없어 명령이 실패하면 다음을 사용합니다.

/sandbox-add-read-dir C:\absolute\directory\path

경로는 존재하는 절대 디렉터리여야 합니다. 명령이 성공하면 이후 샌드박스에서 실행되는 명령은 현재 세션 동안 해당 디렉터리를 읽을 수 있습니다.

기본적으로 native Windows 샌드박스를 사용하십시오. native Windows 샌드박스는 같은 보안을 유지하면서 최고의 성능과 속도를 제공합니다. Windows에서 Linux-native 환경이 필요하거나, workflow가 이미 WSL2에 있거나, 두 native Windows sandbox mode 모두 필요를 충족하지 못할 때 WSL2를 선택합니다.

Windows Subsystem for Linux

WSL2를 선택하면 Codex는 native Windows 샌드박스를 사용하지 않고 Linux 환경 안에서 실행됩니다. Windows에서 Linux-native tooling이 필요하거나, 저장소와 개발자 workflow가 이미 WSL2에 있거나, 두 native Windows sandbox mode 모두 환경에서 작동하지 않을 때 유용합니다.

WSL1은 Codex 0.114까지 지원되었습니다. Codex 0.115부터 Linux 샌드박스가 bubblewrap으로 이동했으므로 WSL1은 더 이상 지원되지 않습니다.

WSL 안에서 VS Code 시작

단계별 지침은 공식 VS Code WSL tutorial을 참고하십시오.

사전 요구 사항

• WSL이 설치된 Windows입니다. WSL을 설치하려면 PowerShell을 administrator로 열고 wsl --install을 실행합니다. Ubuntu가 일반적인 선택입니다.
• WSL 확장이 설치된 VS Code입니다.

WSL 터미널에서 VS Code 열기

# WSL shell에서 실행
cd ~/code/your-project
code .

이 명령은 WSL remote window를 열고, 필요하면 VS Code Server를 설치하며, 통합 터미널이 Linux에서 실행되도록 합니다.

WSL에 연결되었는지 확인

• WSL: {distro}를 표시하는 녹색 상태 표시줄을 찾습니다.

• 통합 터미널은 C:\ 대신 /home/... 같은 Linux path를 표시해야 합니다.

• 다음으로 확인할 수 있습니다.

  echo $WSL_DISTRO_NAME
  

  배포판 이름이 출력됩니다.

상태 표시줄에 "WSL: ..."이 보이지 않으면 Ctrl+Shift+P를 누르고 WSL: Reopen Folder in WSL을 선택한 뒤, 최적의 성능을 위해 저장소를 C:\가 아니라 /home/... 아래에 둡니다.

Windows 앱이나 project picker가 WSL 저장소를 표시하지 않으면 file picker 또는 Explorer에 \\wsl$를 입력한 뒤 배포판의 home directory로 이동합니다.

WSL에서 Codex CLI 사용

elevated PowerShell 또는 Windows Terminal에서 다음을 실행합니다.

# 기본 Linux 배포판 설치. 예: Ubuntu
wsl --install

# Windows Subsystem for Linux 안에서 shell 시작
wsl

그런 다음 WSL shell에서 다음을 실행합니다.

# https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl
# WSL에 Node.js 설치(nvm 사용)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# 새 탭에서 또는 종료 후 `wsl`을 다시 실행한 뒤 Node.js 설치
nvm install 22

# WSL에서 Codex 설치 및 실행
npm i -g @openai/codex
codex

WSL 안의 코드에서 작업

• /mnt/c/... 같은 Windows-mounted path에서 작업하면 Windows-native path보다 느릴 수 있습니다. 더 빠른 I/O와 symlink 및 permission 문제 감소를 위해 저장소를 ~/code/my-app 같은 Linux home directory 아래에 둡니다.

  mkdir -p ~/code && cd ~/code
  git clone https://github.com/your/repo.git
  cd repo
  

• Windows에서 파일에 접근해야 하면 Explorer의 \\wsl$\Ubuntu\home\{user} 아래에서 찾을 수 있습니다.

문제 해결과 FAQ

관리형 Windows 기기를 troubleshooting한다면 native sandbox mode, Windows version, Codex가 표시한 policy error부터 확인하십시오. 대부분의 native Windows 지원 문제는 editor 자체보다 sandbox setup, logon right, filesystem permission에서 발생합니다.

native sandbox 설정이 실패했습니다

Codex가 elevated sandbox 설정을 완료할 수 없는 가장 흔한 원인은 다음과 같습니다.

• Windows UAC 또는 administrator prompt를 거절했습니다.
• 컴퓨터가 local user 또는 group 생성을 허용하지 않습니다.
• 컴퓨터가 firewall rule 변경을 허용하지 않습니다.
• 컴퓨터가 sandbox user에 필요한 logon right를 차단합니다.
• 다른 enterprise policy가 setup flow의 일부를 차단합니다.

시도할 것:

1. 환경에서 허용한다면 elevated sandbox 설정을 다시 시도하고 administrator prompt를 승인합니다.
2. 회사 노트북이 이를 차단한다면 IT 팀에 local user/group 생성, firewall configuration, 필요한 sandbox-user logon right에 대한 administrator-approved setup을 허용하는지 문의합니다.
3. 기본 설정이 계속 실패하면 조사 중에도 계속 작업할 수 있도록 unelevated sandbox를 사용합니다.

Codex가 unelevated sandbox로 전환했습니다

이는 Codex가 컴퓨터에서 더 강한 elevated sandbox 설정을 완료할 수 없었다는 의미입니다.

• Codex는 여전히 sandboxed mode에서 실행될 수 있습니다.
• ACL 기반 파일 시스템 경계를 계속 적용하지만, elevated의 별도 sandbox-user 경계는 사용하지 않으며 네트워크 isolation도 더 약합니다.
• 유용한 fallback이지만 장기 enterprise 구성으로는 권장되지 않습니다.

관리형 enterprise 노트북을 사용 중이라면 장기적으로는 IT 팀의 도움을 받아 elevated sandbox가 작동하게 하는 것이 보통 가장 좋은 해결책입니다.

Windows error 1385가 보입니다

sandboxed command가 error 1385로 실패하면 Windows가 sandbox user가 명령을 시작하는 데 필요한 logon type을 거부하고 있는 것입니다.

실제로는 Codex가 sandbox user를 성공적으로 만들었지만 Windows policy가 여전히 해당 user의 sandboxed command 실행을 막고 있다는 뜻인 경우가 많습니다.

해야 할 일:

1. IT 팀에 device policy가 Codex가 만든 sandbox user에 필요한 logon right를 부여하는지 문의합니다.
2. 일부 컴퓨터나 팀에만 문제가 발생한다면 group policy 또는 OU 차이를 비교합니다.
3. 즉시 계속 작업해야 하면 policy 문제를 조사하는 동안 unelevated sandbox를 사용합니다.
4. Windows version과 실패에 대한 짧은 설명과 함께 CODEX_HOME/.sandbox/sandbox.log를 보냅니다.

일부 폴더가 Everyone에게 writable하다는 경고

Codex는 일부 폴더가 Everyone에게 writable하다고 경고할 수 있습니다. 이 경고가 표시되면 해당 폴더의 Windows permission이 너무 넓어 샌드박스가 완전히 보호하기 어렵습니다.

해야 할 일:

1. 경고에 나열된 폴더를 검토합니다.
2. 환경에 적절하다면 해당 폴더에서 Everyone write access를 제거합니다.
3. 권한을 수정한 뒤 Codex를 다시 시작하거나 sandbox setup을 다시 실행합니다.

권한 변경 방법이 확실하지 않다면 IT 팀에 도움을 요청합니다.

sandboxed command가 네트워크에 접근할 수 없음

일부 Codex 작업은 사용 중인 permission mode에 따라 outbound network access 없이 실행되도록 의도되어 있습니다.

작업이 네트워크에 접근할 수 없어 실패한다면:

1. 작업이 network disabled 상태로 실행되어야 했는지 확인합니다.
2. 네트워크 접근을 기대했다면 Codex를 다시 시작하고 다시 시도합니다.
3. 문제가 계속되면 sandbox log를 수집해 컴퓨터가 partial 또는 broken sandbox state인지 확인할 수 있게 합니다.

샌드박스가 전에는 작동했지만 이제 멈췄습니다

다음 이후에 발생할 수 있습니다.

• repo 또는 workspace 이동
• machine permission 변경
• Windows policy 변경
• 기타 system configuration 변경

시도할 것:

1. Codex를 다시 시작합니다.
2. elevated sandbox 설정을 다시 시도합니다.
3. 해결되지 않으면 임시 fallback으로 unelevated sandbox를 사용합니다.
4. 검토를 위해 sandbox log를 수집합니다.

OpenAI에 진단 정보를 보내야 합니다

문제가 계속되면 다음을 보냅니다.

• CODEX_HOME/.sandbox/sandbox.log

다음 정보도 도움이 됩니다.

• 수행하려던 작업에 대한 짧은 설명
• elevated sandbox가 실패했는지 또는 unelevated sandbox가 사용되었는지
• 앱에 표시된 오류 메시지
• 1385 또는 다른 Windows/PowerShell 오류를 보았는지
• Windows 11인지 Windows 10인지

다음은 보내지 마십시오.

• CODEX_HOME/.sandbox-secrets/의 내용

IDE 확장이 설치되어 있지만 반응하지 않습니다

일부 native dependency에 필요한 C++ 개발 도구가 시스템에 없을 수 있습니다.

• Visual Studio Build Tools(C++ workload)
• Microsoft Visual C++ Redistributable(x64)
• winget을 사용하는 경우 winget install --id Microsoft.VisualStudio.2022.BuildTools -e 실행

설치 후 VS Code를 완전히 다시 시작합니다.

큰 저장소가 WSL에서 느립니다

• /mnt/c 아래에서 작업하지 않는지 확인합니다. 저장소를 WSL로 옮깁니다. 예: ~/code/....

• 필요하면 WSL의 메모리와 CPU를 늘립니다. WSL을 최신 버전으로 업데이트합니다.

  wsl --update
  wsl --shutdown
  

WSL의 VS Code가 codex를 찾지 못합니다

binary가 WSL 안에 있고 PATH에 있는지 확인합니다.

which codex || echo "codex not found"

binary를 찾지 못하면 위의 WSL에서 Codex CLI 사용 지침에 따라 설치합니다.