Codex CLI A to Z: 설치부터 모델·명령어·확장 기능까지

이 문서는 Windows용 입문 가이드입니다.

1. Codex CLI를 이해하기

Codex CLI는 터미널에서 실행하는 코딩 에이전트입니다. 단순히 코드를 생성하는 데서 끝나지 않고, 작업 폴더의 파일을 읽고 수정하며 명령 실행과 검증까지 이어갈 수 있습니다.

핵심 개념은 다음과 같습니다.

•

에이전트: 사용자의 목표를 이해하고 필요한 작업을 순서대로 수행합니다.

•

서브에이전트: 큰 작업을 여러 조사·구현 단위로 나눌 때 별도 작업 스레드로 실행됩니다.

•

스킬: 문서 작성, 디버깅, 프런트엔드 작업처럼 특정 업무를 수행하는 절차와 도구 모음입니다.

•

플러그인: 스킬, 훅, MCP 서버 등을 한 번에 추가하는 확장 패키지입니다.

•

MCP 서버: Codex가 외부 도구나 로컬 기능을 호출할 수 있게 연결하는 프로세스입니다.

서브에이전트는 작업을 병렬화할 수 있지만, 독립된 대화 문맥을 사용할 수 있습니다. 따라서 부모 에이전트가 결과를 수집하고 검증하는 과정이 중요합니다. 에이전트 팀과 서브에이전트의 차이를 단순히 "메모리 공유 여부" 하나로만 보기는 어렵고, 실제 동작은 사용 중인 Codex 버전과 협업 런타임에 따라 달라질 수 있습니다.

2. Windows에 Codex CLI 설치하기

2.1 사전 준비

•

Windows Terminal 또는 PowerShell

•

인터넷 연결

•

OpenAI 계정

•

OpenCodex도 사용할 경우 Node.js

2.2 Codex CLI 설치

PowerShell에서 다음 명령을 실행합니다.

powershell -ExecutionPolicy Bypass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

설치가 끝나면 새 터미널을 열고 버전을 확인합니다.

codex --version

2.3 작업 폴더에서 실행

CMD 또는 PowerShell에서 작업할 폴더로 이동한 뒤 실행합니다.

cd C:\path\to\project
codex

Codex는 현재 폴더를 작업 범위로 사용하므로, 프로젝트 루트에서 시작하는 편이 좋습니다.

2.4 --yolo 모드 주의

codex --yolo

--yolo는 승인 질문과 샌드박스 제한을 크게 줄여 작업을 빠르게 진행하는 모드입니다. 그만큼 파일 수정과 명령 실행 범위가 넓어지므로 다음 조건에서만 사용하는 편이 안전합니다.

•

중요한 파일을 별도로 백업했을 때

•

Git 등으로 변경 이력을 복구할 수 있을 때

•

실행할 작업과 대상 폴더를 명확히 알고 있을 때

처음 사용하는 저장소나 출처를 모르는 프로젝트에서는 기본 모드로 시작하는 것을 권장합니다.

3. Codex 실행과 모델 선택

Codex 실행 중 /model을 입력하면 사용할 모델과 추론 강도를 선택할 수 있습니다.

모델 선택의 기본 원칙은 다음과 같습니다.

처음 시도하는 복잡한 작업은 가장 성능이 높은 모델로 시작합니다.

작업 절차가 정리되고 결과가 반복 가능해지면 더 가벼운 모델로 낮춥니다.

단순 검색·형식 변경과 설계·디버깅 작업을 같은 모델로 처리할 필요는 없습니다.

모델뿐 아니라 reasoning effort도 속도, 비용, 정확도에 영향을 줍니다.

4. 권장 작업 흐름: 계획 → 실행 → 검증

Codex에 큰 작업을 맡길 때는 다음 흐름이 안정적입니다.

4.1 계획

•

목표와 완료 조건을 먼저 적습니다.

•

수정 가능한 파일과 건드리면 안 되는 범위를 구분합니다.

•

/plan 또는 /goal로 장기 작업의 방향을 명확히 합니다.

4.2 실행

•

작은 단위로 파일을 수정합니다.

•

필요한 경우 서브에이전트에 조사나 검토를 나눕니다.

•

진행 중에는 /status, /diff, /ps로 현재 상태를 확인합니다.

4.3 검증

•

테스트, 빌드, 린트처럼 프로젝트가 제공하는 검증 명령을 실행합니다.

•

/review로 현재 변경사항의 문제를 다시 찾습니다.

•

체크리스트와 실제 실행 결과를 함께 확인합니다.

•

"코드가 작성됨"이 아니라 "원하는 동작이 실제로 확인됨"을 완료 기준으로 삼습니다.

긴 작업은 계획 → 실행 → 검증 → 수정의 루프로 반복할 수 있습니다. 자동 연구나 논문 작성처럼 반복 구조가 뚜렷한 작업은 전용 스킬이나 루프를 설계해 진행할 수도 있습니다.

5. OpenCodex로 여러 모델·계정 연결하기

OpenCodex는 여러 계정이나 모델 제공자를 연결해 Codex에서 사용할 수 있도록 돕는 별도 도구입니다. 예를 들어 GLM 계열 같은 외부 모델을 연결할 때 사용할 수 있습니다.

5.1 설치

Node.js가 설치된 터미널에서 실행합니다.

npm install -g @bitkyc08/opencodex

이미지 업로드 위치
파일: image-2.png
설명: OpenCodex 설치 화면
SlashPage 편집 화면에서 이 블록 아래로 해당 파일을 드래그한 뒤, 이 안내 블록을 삭제하세요.

5.2 프록시 시작

ocx start

터미널에 표시되는 프록시 관리 주소를 브라우저에서 엽니다.

5.3 모델과 API 키 추가

관리 화면에서 모델 제공자를 추가합니다.

필요한 API 키를 입력합니다.

API 키는 문서, 화면 캡처, Git 저장소에 포함하지 마세요.

5.4 설정 동기화

추가 결과가 터미널 로그에 나타나면 Ctrl+C로 프록시를 종료한 뒤 설정을 동기화합니다.

ocx sync

이후 Codex를 실행하고 /model에서 연결한 모델이 표시되는지 확인합니다.

모델이 보이지 않으면 한 터미널에서 ocx start를 계속 실행한 상태로 두고, 다른 터미널에서 Codex를 다시 시작합니다.

6. 기본 슬래시 명령어 모음

Codex 대화창에서 /를 입력하면 현재 버전에서 사용할 수 있는 명령 목록이 나타납니다. 아래 표는 이미지에 나온 명령을 중복 없이 분류한 것입니다.

6.1 모델·권한·입력 환경

작업 난이도에 맞춰 모델을 바꿀 때 사용합니다.

6.2 메모리·스킬·확장 기능

명령	기능	언제 사용하나
/memories	메모리 사용과 생성 방식을 설정합니다.	이전 작업의 맥락을 재사용하거나 메모리 사용을 조정할 때 사용합니다.
/skills	사용 가능한 스킬을 확인하고 활용합니다.	문서, 디버깅, UI 작업처럼 특화된 절차가 필요할 때 사용합니다.
/import	Claude Code의 설정, 현재 프로젝트, 최근 대화를 가져옵니다.	Claude Code에서 Codex로 환경을 옮길 때 사용합니다.
/hooks	라이프사이클 훅을 확인하고 관리합니다.	시작·도구 실행·종료 시 자동 실행되는 동작을 점검할 때 사용합니다.
/mcp	설정된 MCP 도구를 나열합니다.	외부 도구 연결 상태를 확인할 때 사용합니다. 자세한 정보가 필요하면 화면 안내에 따라 verbose 보기를 사용합니다.
/plugins	플러그인을 찾아봅니다.	새로운 스킬이나 MCP 기능을 설치할 때 사용합니다.

6.3 대화·세션 관리

명령	기능	주의점
/new	현재 대화 도중 새 채팅을 시작합니다.	기존 대화와 분리된 새 작업을 시작할 때 사용합니다.
/archive	현재 세션을 보관하고 종료합니다.	나중에 참고할 세션을 정리할 때 사용합니다.
/delete	현재 세션을 영구 삭제하고 종료합니다.	되돌리기 어려울 수 있으므로 삭제 대상을 확인해야 합니다.
/resume	저장된 채팅을 다시 엽니다.	이전 작업을 이어서 진행할 때 사용합니다.
/fork	현재 채팅을 분기합니다.	같은 맥락에서 서로 다른 해결책을 시험할 때 사용합니다.
/side	임시 포크에서 보조 대화를 시작합니다.	본 대화 흐름을 유지하면서 짧은 확인이나 탐색을 할 때 사용합니다.
/rename	현재 스레드의 이름을 바꿉니다.	세션을 나중에 쉽게 찾도록 정리할 때 사용합니다.
/clear	터미널을 지우고 새 채팅을 시작합니다.	화면만 지우는 명령이 아니라 새 채팅까지 시작한다는 점에 주의합니다.
/compact	대화를 요약해 컨텍스트 한도 초과를 방지합니다.	긴 대화에서 핵심 맥락을 남기고 토큰 사용을 줄일 때 사용합니다.
/app	현재 세션을 데스크톱 앱에서 이어갑니다.	CLI 작업을 GUI에서 계속 보고 싶을 때 사용합니다.

6.4 계획·에이전트·검토

명령	기능	언제 사용하나
/init	Codex용 지침 파일 AGENTS.md를 만듭니다.	프로젝트 규칙과 검증 방법을 저장소에 명시할 때 사용합니다. 기존 파일이 있다면 먼저 내용을 확인합니다.
/plan	Plan 모드로 전환합니다.	구현 전에 요구사항과 실행 순서를 정리할 때 사용합니다.
/goal	장기 실행 작업의 목표를 설정하거나 확인합니다.	여러 턴에 걸친 작업의 완료 조건을 유지할 때 사용합니다.
/agent	활성 에이전트 스레드를 전환합니다.	부모·자식 에이전트의 작업 화면을 오갈 때 사용합니다.
/subagents	활성 서브에이전트 스레드로 전환합니다.	병렬 작업 진행 상태와 결과를 확인할 때 사용합니다.
/review	현재 변경사항을 검토하고 문제를 찾습니다.	구현 후 버그, 누락, 위험을 점검할 때 사용합니다.

6.5 변경사항·파일·출력 확인

명령	기능	언제 사용하나
/diff	추적되지 않은 파일을 포함한 Git diff를 보여줍니다.	Codex가 실제로 무엇을 바꿨는지 확인할 때 사용합니다.
/mention	대화에서 파일을 언급합니다.	특정 파일을 문맥에 포함하거나 집중해서 질문할 때 사용합니다.
/copy	마지막 응답을 Markdown 형식으로 복사합니다.	답변을 문서나 이슈에 옮길 때 사용합니다.
/raw	복사하기 쉬운 원시 스크롤백 모드를 켜거나 끕니다.	터미널 출력의 서식을 최소화해 선택·복사할 때 사용합니다.

6.6 상태·화면 사용자화

명령	기능	언제 사용하나
/status	현재 세션 설정과 토큰 사용량을 보여줍니다.	모델, 권한, 토큰 상태를 점검할 때 사용합니다.
/usage	계정 사용량이나 사용량 제한 초기화 정보를 확인합니다.	한도와 남은 사용량을 확인할 때 사용합니다.
/title	터미널 제목에 표시할 항목을 설정합니다.	여러 Codex 창을 구분할 때 사용합니다.
/statusline	상태 표시줄의 항목을 설정합니다.	필요한 상태 정보만 표시하고 싶을 때 사용합니다.
/theme	구문 강조 테마를 선택합니다.	터미널 색상과 가독성을 조정할 때 사용합니다.
/personality	Codex의 커뮤니케이션 스타일을 선택합니다.	답변의 말투와 설명 방식을 조정할 때 사용합니다.
/pets	터미널 펫을 선택하거나 숨깁니다.	화면 장식 설정을 바꿀 때 사용합니다.

6.7 백그라운드 작업과 종료

명령	기능	주의점
/ps	백그라운드 터미널 목록을 보여줍니다.	장시간 실행 중인 서버나 테스트를 확인할 때 사용합니다.
/stop	모든 백그라운드 터미널을 중지합니다.	필요한 서버나 빌드 작업까지 함께 종료될 수 있습니다.
/feedback	유지관리자에게 로그와 피드백을 보냅니다.	버그를 재현한 직후 사용하면 진단에 도움이 됩니다. 민감정보 포함 여부를 먼저 확인합니다.
/logout	Codex 계정에서 로그아웃합니다.	계정을 바꾸거나 인증을 초기화할 때 사용합니다.
/exit	Codex를 종료합니다.	현재 세션을 끝내고 터미널로 돌아갑니다.

7. 스킬·플러그인 사용하기

슬래시 명령은 Codex 자체 기능을 제어하고, $는 설치된 스킬이나 플러그인 워크플로우를 직접 호출할 때 사용합니다.

$스킬이름 작업 요청

예를 들어 설치된 플러그인이 제공하는 스킬은 $omo:ulw-plan처럼 네임스페이스가 붙을 수 있습니다. 정확한 이름은 /skills 또는 /plugins에서 확인합니다.

스킬을 사용할 때는 다음을 확인하세요.

•

어떤 파일이나 설정을 변경하는지

•

서브에이전트나 MCP 서버를 실행하는지

•

장기 실행이나 반복 루프를 시작하는지

•

취소·복구 방법이 있는지

8. LazyCodex와 Ouroboros

8.1 LazyCodex 설치

저장소: https://github.com/code-yeongyu/lazycodex

npx lazycodex-ai install

LazyCodex는 Codex에 작업 규칙, 스킬, 훅, MCP 도구와 서브에이전트 역할을 추가합니다. 설치 후에는 /plugins, /skills, /mcp로 로드 상태를 확인합니다.

9. 문제 해결 체크리스트

Codex 명령이 인식되지 않을 때

codex --version
Get-Command codex

•

설치 후 터미널을 새로 열었는지 확인합니다.

•

PATH에 Codex 실행 파일이 포함됐는지 확인합니다.

OpenCodex 모델이 보이지 않을 때

ocx start가 실행 중인지 확인합니다.

모델과 API 키를 추가했는지 확인합니다.

Ctrl+C로 종료한 뒤 ocx sync를 실행합니다.

Codex를 완전히 종료하고 다시 시작합니다.

/model에서 모델 목록을 다시 확인합니다.

MCP 때문에 세션이 멈출 때

codex mcp list
codex plugin list

•

멈추기 직전에 호출한 MCP 이름을 확인합니다.

•

같은 기능을 제공하는 전역 MCP와 플러그인 MCP가 중복됐는지 확인합니다.

•

플러그인이 MCP를 제공하는 경우 codex mcp remove <name>만으로는 목록에서 사라지지 않을 수 있습니다.

•

문제가 있는 플러그인을 비활성화한 뒤 Codex를 재시작해 비교합니다.

백그라운드 작업이 끝나지 않을 때

/ps로 실행 중인 터미널을 확인합니다.

더 이상 필요하지 않다면 /stop으로 모두 종료합니다.

중요한 서버가 있다면 /stop 전에 종료 영향을 확인합니다.

빠른 시작 요약

# 1. 프로젝트 폴더로 이동
cd C:\path\to\project

# 2. Codex 시작
codex

Codex 안에서는 다음 순서로 시작해 보세요.

/model       # 모델 선택
/permissions # 권한 확인
/plan        # 큰 작업 계획
/status      # 현재 상태 확인
/diff        # 변경사항 확인
/review      # 구현 결과 검토

안전한 기본 원칙은 간단합니다. 처음에는 권한을 좁게, 작업은 작게, 검증은 실제 실행으로 진행하세요.

Made with Slashpage