logo

윈도용 Codex

Windows용 Codex 앱은 프로젝트 전반에서 작업하고, 병렬 에이전트 스레드를 실행하고, 결과를 검토하기 위한 하나의 인터페이스를 제공합니다. Windows 앱은 worktree, 자동화, Git 기능, 앱 내 브라우저, artifact 미리보기, 플러그인, 스킬 같은 핵심 워크플로를 지원합니다.

Codex 앱 다운로드와 업데이트

Microsoft Store에서 Codex 앱을 다운로드합니다.

그런 다음 설치 따라 시작합니다.

앱을 업데이트하려면 Microsoft Store를 열고 Downloads로 이동한 뒤 Check for updates를 클릭합니다. 이후 Store가 최신 버전을 설치합니다.

Enterprise에서는 관리자가 enterprise management tool을 통해 Microsoft Store 앱 배포로 앱을 배포할 수 있습니다.

명령줄 설치 경로를 선호하거나 Microsoft Store UI를 열 수 없는 경우 다음을 실행합니다.

winget install Codex -s msstore

native sandbox

Windows용 Codex 앱은 에이전트가 PowerShell에서 실행될 때 native Windows 샌드박스를 지원하고, Windows Subsystem for Linux 2(WSL2)에서 에이전트를 실행할 때 Linux 샌드박싱을 사용합니다. 어느 모드에서든 샌드박스 보호를 적용하려면 Codex에 메시지를 보내기 전에 Composer에서 sandbox permission을 Default permissions로 설정합니다.

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

개발 설정에 맞게 사용자화

선호 에디터

Open에 사용할 기본 앱을 선택합니다. Visual Studio, VS Code 또는 다른 에디터를 선택할 수 있습니다. 프로젝트별로 이 선택을 override할 수 있습니다. 이미 프로젝트의 Open 메뉴에서 다른 앱을 선택했다면 해당 프로젝트별 선택이 우선합니다.

통합 터미널

기본 통합 터미널도 선택할 수 있습니다. 설치된 항목에 따라 옵션은 다음을 포함합니다.

  • PowerShell
  • Command Prompt
  • Git Bash
  • WSL

이 변경은 새 터미널 세션에만 적용됩니다. 이미 통합 터미널이 열려 있다면 새 기본 터미널이 표시되기를 기대하기 전에 앱을 다시 시작하거나 새 스레드를 시작합니다.

Windows Subsystem for Linux(WSL)

기본적으로 Codex 앱은 Windows-native agent를 사용합니다. 즉 에이전트가 PowerShell에서 명령을 실행합니다. 앱은 필요할 때 wsl CLI를 사용해 Windows Subsystem for Linux 2(WSL2)에 있는 프로젝트와도 작업할 수 있습니다.

WSL 파일 시스템에서 프로젝트를 추가하려면 Add new project를 클릭하거나 Ctrl+O를 누른 뒤 File Explorer 창에 \\wsl$\를 입력합니다. 그런 다음 Linux 배포판과 열 폴더를 선택합니다.

Windows-native agent를 계속 사용할 계획이라면 프로젝트를 Windows 파일 시스템에 저장하고 WSL에서는 /mnt/{drive}/...를 통해 접근하는 방식을 선호하십시오. 이 설정은 WSL 파일 시스템에서 직접 프로젝트를 여는 것보다 안정적입니다.

에이전트 자체를 WSL2에서 실행하려면 **Settings**를 열고 agent를 Windows native에서 WSL로 전환한 뒤 앱을 다시 시작합니다. 변경은 다시 시작하기 전까지 적용되지 않습니다. 재시작 후에도 프로젝트는 그대로 유지되어야 합니다.

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

통합 터미널은 에이전트와 별도로 구성합니다. 워크플로에 따라 에이전트는 WSL에 두고 터미널은 PowerShell을 사용할 수도 있고, 둘 다 WSL을 사용할 수도 있습니다.

유용한 개발자 도구

Codex는 몇 가지 일반 개발자 도구가 미리 설치되어 있을 때 가장 잘 작동합니다.

  • Git: Codex 앱의 리뷰 패널을 구동하고 변경 사항을 검사하거나 revert할 수 있게 합니다.
  • Node.js: 에이전트가 작업을 더 효율적으로 수행하는 데 사용하는 일반 도구입니다.
  • Python: 에이전트가 작업을 더 효율적으로 수행하는 데 사용하는 일반 도구입니다.
  • .NET SDK: native Windows 앱을 빌드하려는 경우 유용합니다.
  • GitHub CLI: Codex 앱에서 GitHub 관련 기능을 구동합니다.

기본 Windows package manager인 winget으로 설치하려면 통합 터미널에 다음을 붙여 넣거나 Codex에게 설치를 요청합니다.

winget install --id Git.Git
winget install --id OpenJS.NodeJS.LTS
winget install --id Python.Python.3.14
winget install --id Microsoft.DotNet.SDK.10
winget install --id GitHub.cli

GitHub CLI를 설치한 뒤에는 gh auth login을 실행해 앱의 GitHub 기능을 활성화합니다.

다른 Python 또는 .NET 버전이 필요하면 package ID를 원하는 버전으로 바꿉니다.

문제 해결과 FAQ

elevated permission으로 명령 실행

Codex가 elevated permission으로 명령을 실행해야 한다면 Codex 앱 자체를 administrator로 시작합니다. 설치 후 Start 메뉴를 열고 Codex를 찾은 뒤 Run as administrator를 선택합니다. Codex 에이전트는 그 권한 수준을 상속합니다.

PowerShell execution policy가 명령을 차단함

PowerShell에서 Node.js나 npm 같은 도구를 사용해 본 적이 없다면 Codex 에이전트나 통합 터미널이 execution policy 오류를 만날 수 있습니다.

Codex가 PowerShell script를 생성한 경우에도 이런 문제가 발생할 수 있습니다. 이 경우 PowerShell이 실행하기 전에 덜 제한적인 execution policy가 필요할 수 있습니다.

오류는 다음과 비슷할 수 있습니다.

npm.ps1 cannot be loaded because running scripts is disabled on this system.

일반적인 수정 방법은 execution policy를 RemoteSigned로 설정하는 것입니다.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

정책을 변경하기 전에 자세한 내용과 다른 옵션은 Microsoft의 execution policy guide를 확인하십시오.

Windows의 로컬 환경 스크립트

로컬 환경이 npm script 같은 cross-platform 명령을 사용한다면 모든 플랫폼에 하나의 공유 설정 스크립트나 action set을 유지할 수 있습니다.

Windows-specific 동작이 필요하면 Windows-specific 설정 스크립트 또는 Windows-specific action을 만듭니다.

action은 통합 터미널이 사용하는 환경에서 실행됩니다. 개발 설정에 맞게 사용자화를 참고하십시오.

로컬 설정 스크립트는 에이전트 환경에서 실행됩니다. 에이전트가 WSL을 사용하면 WSL에서, 그렇지 않으면 PowerShell에서 실행됩니다.

WSL과 config, auth, session 공유

Windows 앱은 Windows native Codex와 같은 Codex 홈 디렉터리인 %USERPROFILE%\.codex를 사용합니다.

WSL 안에서도 Codex CLI를 실행한다면 CLI는 기본적으로 Linux home directory를 사용하므로 Windows 앱과 구성, cached auth, session history를 자동으로 공유하지 않습니다.

공유하려면 다음 중 하나를 사용합니다.

  • 파일 시스템에서 WSL ~/.codex를 %USERPROFILE%\.codex와 동기화합니다.
  • CODEX_HOME을 설정해 WSL이 Windows Codex 홈 디렉터리를 가리키게 합니다.
export CODEX_HOME=/mnt/c/Users/{windows-user}/.codex

모든 셸에서 이 설정을 원한다면 ~/.bashrc 또는 ~/.zshrc 같은 WSL 셸 profile에 추가합니다.

Git 기능을 사용할 수 없음

Windows에 Git이 네이티브로 설치되어 있지 않으면 앱이 일부 기능을 사용할 수 없습니다. PowerShell 또는 cmd.exe에서 winget install Git.Git으로 설치합니다.

\\wsl$에서 연 프로젝트에서 Git이 감지되지 않음

현재 Windows-native agent로 WSL에서도 접근 가능한 프로젝트를 사용하려면, 가장 안정적인 workaround는 프로젝트를 native Windows drive에 저장하고 WSL에서는 /mnt/{drive}/...를 통해 접근하는 것입니다.

open dialog에 Cmder가 표시되지 않음

Cmder가 설치되어 있지만 Codex open dialog에 표시되지 않는다면 Windows Start Menu에 추가합니다. Cmder를 오른쪽 클릭하고 Add to Start를 선택한 뒤 Codex를 다시 시작하거나 reboot합니다.

Previous
명령
Next
개요