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

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

## 목차

1. Codex CLI를 이해하기

2. Windows에 Codex CLI 설치하기

3. Codex 실행과 모델 선택

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

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

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

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

8. LazyCodex와 Ouroboros

9. 문제 해결 체크리스트

## 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
powershell -ExecutionPolicy Bypass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

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

```powershell
codex --version
```

### 2.3 작업 폴더에서 실행

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

```powershell
cd C:\path\to\project
codex
```

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

### 2.4 `--yolo` 모드 주의

```powershell
codex --yolo
```

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

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

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

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

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

## 3. Codex 실행과 모델 선택

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

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151003_29bENl3CLRoa2Mv2Ah?q=80&s=1280x180&t=outside&f=webp)

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151034_qXfKgKJgZUsgIpLxPj?q=80&s=1280x180&t=outside&f=webp)

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

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

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

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

4. 모델뿐 아니라 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가 설치된 터미널에서 실행합니다.

```powershell
npm install -g @bitkyc08/opencodex
```

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

### 5.2 프록시 시작

```powershell
ocx start
```

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

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151052_aGlfUSgaQYbcmd2dEu?q=80&s=1280x180&t=outside&f=webp)

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151113_7UOlE2waDkPtTmRm5z?q=80&s=1280x180&t=outside&f=webp)

### 5.3 모델과 API 키 추가

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

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151130_M3WDZHWj8tHECH6K67?q=80&s=1280x180&t=outside&f=webp)

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151200_NgXF7IOXdreBR46QzL?q=80&s=1280x180&t=outside&f=webp)

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151212_8hNN2yXjPC9mDKFMUA?q=80&s=1280x180&t=outside&f=webp)

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

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

### 5.4 설정 동기화

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

```powershell
ocx sync
```

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151233_CaSSNFaF6FtVHABpVp?q=80&s=1280x180&t=outside&f=webp)

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

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151308_opnDUfPQmZU9Ih1bxC?q=80&s=1280x180&t=outside&f=webp)

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

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151313_D6YyVjzRJuktJvB5fr?q=80&s=1280x180&t=outside&f=webp)

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

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

### 6.1 모델·권한·입력 환경

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

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

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151432_qNSWmsRPyaUgqMzEAt?q=80&s=1280x180&t=outside&f=webp)

### 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 자체 기능을 제어하고, `$`는 설치된 스킬이나 플러그인 워크플로우를 직접 호출할 때 사용합니다.

```text
$스킬이름 작업 요청
```

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

![Image](https://upload.cafenono.com/image/slashpageHome/20260806/151535_n6OxSUpZ1x1tMGgY8j?q=80&s=1280x180&t=outside&f=webp)

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

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

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

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

- 취소·복구 방법이 있는지

## 8. LazyCodex와 Ouroboros

### 8.1 LazyCodex 설치

저장소: [https://github.com/code-yeongyu/lazycodex](https://github.com/code-yeongyu/lazycodex)

```powershell
npx lazycodex-ai install
```

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

## 9. 문제 해결 체크리스트

### Codex 명령이 인식되지 않을 때

```powershell
codex --version
Get-Command codex
```

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

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

### OpenCodex 모델이 보이지 않을 때

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

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

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

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

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

### MCP 때문에 세션이 멈출 때

```powershell
codex mcp list
codex plugin list
```

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

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

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

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

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

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

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

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

## 빠른 시작 요약

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

# 2. Codex 시작
codex
```

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

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

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

For the site tree, see the [root Markdown](https://slashpage.com/conanssam.md).