OpenAI Codex 사용법 - CLI, VS Code, 웹에서 AI 코딩 에이전트 활용하기

⚠️ 이 문서는 생성형 AI를 통해 작성되었으며, 내용에 오류가 있을 수 있습니다.

⚠️ This article was drafted by an AI-assisted triage tool and may contain mistakes.

AI 요약 & 가이드

OpenAI Codex를 처음 접하는 분이 CLI, IDE, 웹 중 어떤 방식으로 시작할지 판단할 수 있도록 정리했습니다. 설치와 로그인 같은 기본 절차뿐 아니라, 어떤 프롬프트가 잘 먹히는지, 권한 모드를 어떻게 나눠 써야 하는지, 그리고 Codex가 특히 잘하는 작업이 무엇인지까지 한 흐름으로 설명합니다.

• Codex가 무엇인지: 일반 채팅형 AI와 구분되는 에이전트형 작업 방식을 설명합니다.
• 어디서 사용할 수 있는지: CLI, IDE 확장, 웹 각각의 사용 장면을 비교합니다.
• 시작 방법: 설치, 로그인, 첫 실행, 웹과 IDE 진입 방법까지 순서대로 따라갈 수 있습니다.
• 잘 쓰는 방법: 범위, 성공 기준, 검토 방식, 금지 조건을 어떻게 적을지 정리합니다.
• 권한과 주의점: 읽기 전용, 워크스페이스 쓰기, 전체 권한을 언제 써야 할지 설명합니다.

요즘 AI 코딩 도구를 이야기할 때 자동완성과 에이전트는 꽤 다른 범주로 봐야 합니다. 자동완성이 "다음 줄을 제안하는 도우미"에 가깝다면, Codex는 "작업을 맡기고 결과를 검토하는 협업 상대"에 더 가깝습니다.

예를 들어 "이 버그를 고쳐줘", "테스트를 추가해줘", "이 프로젝트 구조를 설명해줘" 같은 요청을 주면, Codex는 파일을 읽고, 필요한 명령을 실행하고, 실제 변경안까지 만들어낼 수 있습니다. 이번 글에서는 OpenAI Codex를 처음 접하는 분도 바로 감을 잡을 수 있도록 기본 개념부터 실제 사용 흐름까지 한 번에 정리해보겠습니다.

Codex는 무엇인가 #

Web – Codex | OpenAI Developers

Delegate to Codex in the cloud

developers.openai.com

OpenAI 공식 문서 기준으로 Codex는 코드를 읽고(edit), 수정하고(run), 실행할 수 있는 코딩 에이전트입니다. 즉, 단순히 질문에 답하는 것을 넘어서 실제 개발 작업 단위를 처리하도록 설계된 도구입니다.

이 점 때문에 Codex는 아래 같은 일에 특히 잘 맞습니다.

• 현재 프로젝트 구조 파악
• 버그 원인 분석
• 특정 파일 수정
• 테스트 코드 추가
• 리팩터링 초안 작성
• 반복적인 문서화 작업

중요한 점은 "결과를 바로 신뢰하는 도구"라기보다, 실행 가능한 초안과 변경안을 빠르게 만드는 도구라는 것입니다. 개발자가 검토하고 승인하는 흐름과 함께 써야 가장 효율이 좋습니다.

Codex는 어디서 사용할 수 있는가 #

Codex는 한 가지 인터페이스에만 묶여 있지 않습니다. 공식 문서 기준으로 크게 CLI, IDE 확장, 웹에서 사용할 수 있습니다.

1. Codex CLI #

Codex CLI는 터미널에서 직접 실행하는 방식입니다. 로컬 디렉터리 안에서 파일을 읽고, 수정하고, 명령을 실행하는 흐름에 가장 자연스럽습니다.

터미널 중심으로 일하는 개발자라면 가장 먼저 익히기 좋은 인터페이스입니다. 특히 아래 같은 작업과 궁합이 좋습니다.

• 현재 레포 구조 설명 요청
• 테스트 실행과 실패 원인 분석
• 작은 범위의 버그 수정
• 여러 파일을 건드리는 리팩터링 초안

2. Codex IDE 확장 #

IDE 확장은 VS Code 계열 에디터나 JetBrains 계열 IDE 안에서 Codex를 쓰는 방식입니다. 공식 문서에는 VS Code, Cursor, Windsurf, JetBrains IDE 지원이 안내되어 있습니다.

이 방식의 장점은 코드와 대화 창이 같은 화면에 있다는 점입니다. 파일을 열어둔 채 질문하고, 변경 사항을 바로 비교하고, 필요한 부분만 적용하기 편합니다.

3. Codex 웹 #

웹 버전은 chatgpt.com/codex에서 GitHub 저장소를 연결해 사용하는 흐름입니다. 공식 문서에 따르면 Codex cloud는 자체 클라우드 환경에서 백그라운드 작업도 수행할 수 있고, 병렬로 여러 작업을 맡기는 데도 강점이 있습니다.

로컬 환경을 바로 건드리고 싶지 않거나, GitHub 중심으로 위임형 작업을 돌리고 싶을 때 잘 맞습니다.

Codex 시작하기 #

Codex를 시작하는 가장 쉬운 방법은 IDE 확장 또는 CLI입니다. 둘 다 ChatGPT 계정이나 OpenAI API 키로 로그인할 수 있습니다.

1. CLI 설치와 실행 #

공식 문서 기준으로 CLI는 아래처럼 설치합니다.

npm i -g @openai/codex

설치 후에는 아래처럼 실행합니다.

codex

처음 실행하면 로그인 과정을 진행하게 됩니다. 이후 현재 디렉터리를 기준으로 Codex가 프로젝트를 읽고 작업할 수 있습니다.

2. IDE 확장 설치 #

공식 문서 기준으로 Codex 확장은 VS Code Marketplace에서 설치할 수 있고, VS Code 계열 에디터와 JetBrains IDE도 지원합니다.

설치 후에는 보통 사이드바에 Codex 패널이 나타납니다. 로그인만 끝나면 바로 첫 작업을 보낼 수 있습니다.

공식 Quickstart 문서에는 IDE에서 Codex가 기본적으로 Agent mode로 시작하며, 이 모드에서는 프로젝트 디렉터리 안의 파일 읽기, 명령 실행, 코드 변경이 가능하다고 설명합니다.

3. 웹에서 시작하기 #

웹에서는 chatgpt.com/codex로 이동한 뒤 GitHub 계정을 연결하면 됩니다. 이후 저장소를 선택하고 클라우드 환경에서 작업을 맡길 수 있습니다.

로컬에서 바로 실행하지 않고도 작업을 위임할 수 있다는 점이 웹 버전의 큰 장점입니다.

처음 보낼 만한 요청 예시 #

처음부터 너무 큰 작업을 주면 결과 검토가 오히려 어려워질 수 있습니다. 아래처럼 작고 검증 가능한 요청부터 시작하는 편이 좋습니다.

- 이 프로젝트 구조를 10줄 안으로 요약해줘.
- 테스트가 없는 핵심 함수 3개를 찾아줘.
- 이 에러 로그의 원인을 추정하고 수정 후보를 제안해줘.
- docs 폴더만 읽고 README 개선안을 작성해줘.
- 현재 동작은 유지하면서 이 함수만 리팩터링해줘.

핵심은 작업 범위와 검토 기준이 명확해야 한다는 점입니다. 처음에는 "전부 고쳐줘"보다 "이 파일만", "테스트 포함", "동작 유지"처럼 제약을 주는 것이 훨씬 좋습니다.

Codex 프롬프트 잘 쓰는 방법 #

Codex는 단순 질의응답보다 작업 수행에 강한 도구라서, 프롬프트를 쓸 때도 "무엇을", "어디까지", "어떤 기준으로" 할지 적어주는 편이 결과 품질이 좋습니다.

1. 범위를 먼저 제한하기 #

좋지 않은 예시:

버그를 고쳐줘.

더 좋은 예시:

로그인 실패 시 500이 나는 문제를 찾아줘.
수정 범위는 auth 모듈 안으로 제한하고, 공개 API 응답 형식은 바꾸지 마.

이렇게 쓰면 Codex가 불필요하게 넓은 범위를 건드릴 가능성이 줄어듭니다.

2. 성공 기준을 함께 적기 #

이 함수의 동작은 유지하면서 가독성을 개선해줘.
중첩 조건문을 줄이고, 기존 테스트가 통과하도록 해줘.

성공 기준이 없으면 결과가 "보기엔 그럴듯하지만 의도와 어긋난 변경"이 되기 쉽습니다.

3. 검토 방식을 요청하기 #

바로 수정하지 말고,
먼저 원인 분석 -> 수정 계획 -> 실제 변경 순서로 진행해줘.

Codex는 꽤 적극적으로 움직이는 편이기 때문에, 중요한 작업에서는 이런 식으로 중간 점검 단계를 요구하는 것이 유용합니다.

4. 변경 금지 조건을 적기 #

다른 파일은 수정하지 말고,
새 패키지는 추가하지 말고,
테스트 파일만 새로 만들어줘.

실무에서는 이 제약이 생각보다 중요합니다. AI 에이전트는 할 수 있는 일이 많을수록 넓게 움직이기 쉬워서, 금지 조건이 있어야 검토 비용이 줄어듭니다.

권한 설정과 주의할 점 #

Permissions – Codex | OpenAI Developers

Configure beta Codex permission profiles for filesystem and network access

developers.openai.com

Codex의 강점 중 하나는 실제로 명령을 실행하고 파일을 바꿀 수 있다는 점입니다. 반대로 말하면, 권한 설정을 이해하지 않고 쓰면 부담스럽게 느껴질 수 있다는 뜻이기도 합니다.

공식 권한 문서에는 기본적으로 아래 3가지 빌트인 프로필이 소개됩니다.

• :read-only : 읽기 전용
• :workspace : 현재 워크스페이스 안에서 쓰기 허용
• :danger-full-access : 로컬 샌드박스 제한 해제

처음에는 read-only 또는 워크스페이스 제한 모드에 가깝게 시작하는 것을 추천합니다. 특히 아래 원칙을 지키면 훨씬 안전합니다.

1. 처음에는 읽기와 분석 위주 작업부터 맡기기
2. 코드 수정은 작은 범위로 제한하기
3. 실행 전후 diff와 테스트 결과를 직접 확인하기
4. 민감한 파일, 환경 변수, 배포 설정은 별도로 관리하기

Codex를 잘 쓴다는 것은 "무조건 많이 맡긴다"가 아니라 "적절한 권한 안에서 검토 가능한 작업을 위임한다"에 더 가깝습니다.

이런 상황에서 특히 유용하다 #

제가 보기엔 Codex는 아래처럼 작업 단위가 분명한 개발 일에서 특히 장점이 큽니다.

레거시 코드 파악 #

낯선 프로젝트를 처음 열었을 때 "엔트리포인트가 어디인지", "핵심 비즈니스 로직이 어느 파일에 있는지", "테스트가 어느 수준까지 깔려 있는지"를 빠르게 파악하는 데 유용합니다.

작은 버그 수정 #

재현 가능한 에러 메시지와 수정 범위를 같이 주면 원인 후보를 좁히고 패치를 제안받는 흐름이 꽤 효율적입니다.

테스트 코드 보완 #

기존 함수에 대한 테스트 초안을 만들고, 빠진 엣지 케이스를 함께 정리하는 데 시간을 많이 줄여줍니다.

반복 문서화 #

README 보완, 함수 설명 추가, 변경사항 요약처럼 형식은 정해져 있지만 손이 자주 가는 작업에도 잘 맞습니다.

한계도 분명히 있다 #

Codex가 강력한 도구인 것은 맞지만, 아래 부분은 여전히 사람이 직접 판단해야 합니다.

1. 그럴듯하지만 틀린 수정 #

컴파일은 되지만 요구사항을 어기는 변경, 테스트는 통과하지만 장기적으로 유지보수성이 떨어지는 수정이 나올 수 있습니다.

2. 프로젝트의 숨은 맥락은 완전히 알지 못함 #

팀 규칙, 배포 관례, 비즈니스 우선순위, 문서에 없는 제약까지 Codex가 스스로 완전히 이해한다고 기대하면 곤란합니다.

3. 큰 작업은 오히려 쪼개야 잘 된다 #

"서비스 전체 구조를 개선해줘" 같은 요청보다 "API 레이어 중복 제거", "이 함수 테스트 추가", "이 경고 수정"처럼 작업을 분할했을 때 훨씬 안정적으로 결과가 나옵니다.

추천 사용 흐름 #

처음 Codex를 도입한다면 저는 아래 순서를 추천합니다.

1. 프로젝트 요약과 구조 설명부터 시켜보기
2. 읽기 전용으로 버그 원인 분석 맡기기
3. 작은 파일 한두 개만 수정하게 해보기
4. 테스트 추가나 리팩터링 초안 작성 맡기기
5. 익숙해지면 CLI, IDE, 웹 중 자신의 작업 방식에 맞는 인터페이스로 고정하기

특히 IDE 안에서 바로 대화하며 수정하는 흐름이 편한 사람도 있고, 터미널에서 빠르게 지시하고 결과를 보는 CLI가 더 잘 맞는 사람도 있습니다. 본인 작업 스타일에 맞는 인터페이스를 찾는 것이 중요합니다.

마무리 #

Codex는 "코드를 대신 써주는 자동완성"보다 한 단계 더 나아간 도구입니다. 읽고, 실행하고, 수정하고, 경우에 따라 작업을 위임하는 흐름까지 포함하는 AI 코딩 에이전트라고 보는 편이 더 정확합니다.

처음에는 거창한 자동화보다, "이 프로젝트를 설명해줘", "이 함수만 수정해줘", "테스트 초안을 만들어줘"처럼 작은 작업부터 맡겨보는 것이 좋습니다. 그렇게 써보면 Codex의 핵심은 마법 같은 정답 생성보다, 개발자가 검토 가능한 속도로 작업을 앞당겨주는 것이라는 점이 꽤 분명하게 보입니다.

공식 문서 기준으로 2026년 5월 현재 Codex는 CLI, IDE 확장, 웹 환경을 모두 지원하므로, 자신의 개발 습관에 가장 잘 맞는 진입점을 골라 시작하면 됩니다.