Oh My Codex 사용법, Codex CLI를 더 체계적으로 쓰는 설치·활용 가이드

개발 테크

2시간 전

조회수

개발자가 코드를 수정하고 있는 화면입니다.

AI를 활용한 개발 작업이 복잡해질수록 사용자가 모든 과정을 일일이 따라가기 어려운 상황이 생깁니다. AI는 코드를 빠르게 분석하고 수정하지만, 작업 방향을 잘못 잡거나, 의도하지 않은 파일까지 수정하면 전체 작업 흐름이 흐트러져 버립니다.

이런 문제를 줄이기 위해 Codex용 오픈소스 작업 흐름 도구인 ‘Oh My Codex’가 등장했습니다. Codex용 에이전트 스킬로 AI가 바로 코드를 수정하는 대신, 먼저 작업 의도를 확인하고 계획을 세운 뒤 실행과 검증의 과정을 거치도록 돕습니다.

덕분에 사용자는 계획부터 실행, 검토까지 정해진 흐름에 따라 작업을 맡기고 확인할 수 있습니다.

이 글에서는 Oh My Codex가 무엇인지, 기존 Codex 사용 방식과 무엇이 다른지, 왜 개발자들 사이에서 주목받고 있는지, 그리고 실제로 어떻게 설치하고 사용하는지까지 정리해보겠습니다.

Oh My Codex 핵심 요약

Oh My Codex는 Codex CLI를 보조하는 작업 흐름 도구입니다. Codex가 코드 분석과 수정, 명령 실행을 담당한다면, 이를 분석 → 계획 → 실행 → 검토 단계로 나눠 진행하도록 돕습니다.
복잡한 AI 코딩 작업을 더 체계적으로 관리할 수 있습니다. 코드 수정 전에 계획을 먼저 세우고 검토하는 구조를 제공해, 작업 방향을 확인한 뒤 실행할 수 있게 합니다.
여러 에이전트가 역할을 나눠 병렬로 작업합니다. 이를 통해 API, 프런트엔드, 테스트처럼 영역이 나뉜 프로젝트를 팀처럼 분담해 처리할 수 있습니다.
사용 환경과 비용, 검토 과정에 주의해야 합니다. 팀 모드처럼 여러 에이전트를 병렬로 실행하면 토큰 사용량과 비용이 늘 수 있어, 예산에 맞춰 동시 실행 수를 조절해 사용하는 것이 좋습니다.

Oh My Codex란?

Oh-my-codex 깃허브 공식 저장소 캡처 이미지입니다. * 이미지 출처: Oh-my-codex 깃허브 공식 저장소

Oh My Codex, 줄여서 OMX는 개발자 허예찬(Yeachan Heo)이 만든 오픈소스 도구입니다. 로, OpenAI의 Codex CLI에 다중 에이전트 오케스트레이션과 작업 흐름을 더하는 계층입니다.

Codex CLI가 코드 분석과 수정, 명령 실행을 담당한다면, OMX는 그 과정을 분석 → 계획 → 실행 → 검토의 단계로 나누어 진행할 수 있게 도와줍니다.

OMX가 개발된 이유는 AI 코딩 도구를 실제 프로젝트에 사용할 때 생기는 문제 때문입니다. AI에게 바로 수정을 요청하면 충분한 분석 없이 코드가 변경되거나, 사용자가 의도하지 않은 방향으로 작업이 진행되는 경우가 종종 발생했습니다.

OMX는 이런 문제를 줄이기 위해 작업을 역할별로 나누고, 코드 수정 전에 계획을 먼저 확인할 수 있게 합니다. 덕분에 사용자는 AI가 어떤 방향으로 작업하려는지 확인한 뒤 실행할 수 있고, 수정 후에는 변경된 파일과 내용을 다시 검토할 수 있습니다.

Oh My Codex가 주목받는 이유

여러 에이전트가 병렬로 협업합니다.

AI는 코드를 빠르게 생성할 수 있지만, 프로젝트 규모가 커지면 하나의 AI가 모든 작업을 순서대로 처리하는 방식에는 한계가 있습니다.

OMX는 이런 문제를 줄이기 위해 작업을 여러 단위로 나누고, 각각의 에이전트가 동시에 처리하도록 설계되었습니다. 각 에이전트는 맡은 역할에 따라 독립적으로 작업을 진행하고, 이후 결과를 검토해 하나의 흐름으로 정리합니다.

덕분에 AI 작업을 하나의 팀처럼 운영할 수 있어, 큰 프로젝트에서도 작업을 더 빠르게 처리하며, 수정 범위와 담당 역할을 더 명확하게 관리할 수 있습니다.

작업 맥락이 끊기지 않습니다

AI와 오래 작업하다 보면 대화가 길어지고, 앞에서 정리한 요구사항이나 작업 계획이 흐려지는 경우가 있습니다. 특히 여러 파일을 수정하거나 며칠에 걸쳐 작업을 이어가야 하는 프로젝트에서는 이전에 어떤 방향으로 진행했는지 다시 설명해야 하는 일이 생깁니다.

OMX는 이런 문제를 줄이기 위해 작업 계획과 기록, 메모리 정보를 .omx 폴더에 저장합니다. 세션이 끊기거나 새로 시작하더라도 이전에 정리한 내용과 작업 흐름을 다시 참고할 수 있는 구조입니다.

덕분에 긴 작업을 여러 번에 나눠 진행할 때도 맥락을 이어가기 쉽습니다. 사용자는 매번 처음부터 설명하지 않아도 되고, OMX는 이전 작업 기록을 바탕으로 다음 단계를 더 자연스럽게 이어갈 수 있습니다.

정해진 흐름으로 작업을 진행합니다

AI 코딩 도구를 사용할 때, 의도와 다른 방향으로 진행되어 수정 범위가 예상보다 커지는 문제가 종종 발생합니다.

OMX는 이런 문제를 줄이기 위해 작업을 의도 확인 → 계획 → 실행 → 검증의 흐름으로 나눠 진행합니다. 먼저 사용자가 원하는 작업을 정리하고, 수정 계획을 세운 뒤, 그 계획을 바탕으로 실행합니다. 실행이 끝난 뒤에는 결과를 다시 확인하는 단계까지 이어집니다.

덕분에 사용자는 코드가 수정되기 전에 AI가 올바른 방향으로 계획을 세웠는지,작업이 끝난 뒤에는 의도한 대로 수정이 반영됐는지, 원하는 결과물이 나왔는지도 더 쉽게 검토할 수 있습니다.

Oh My Codex 사용법

macOS·Linux에서 사용하기 전 확인 사항

Node.js 20 이상
Codex CLI 설치 및 로그인
tmux 설치

OMX를 실행하기 전에는 먼저 기본 환경을 확인해야 합니다. OMX를 사용하려면 Node.js 20 이상과 Codex CLI가 설치되어 있어야 하며, Codex CLI에 로그인까지 완료되어 있어야 합니다.

또한 팀 모드처럼 여러 작업을 병렬로 실행하는 기능을 사용하려면 tmux도 필요합니다. tmux는 터미널 화면을 여러 개로 나누거나, 여러 세션을 동시에 관리할 수 있게 해주는 도구입니다.

Windows에서 사용하기 전 확인 사항

WSL2 설치
WSL2 안에 Node.js 20 이상 설치
WSL2 안에 Codex CLI 설치 및 로그인
WSL2 안에 oh-my-codex 설치 필요 시 tmux 설치

Windows에서도 OMX를 사용할 수 있지만, 안정적인 실행을 위해서는 PowerShell보다 WSL2 환경에서 설치하고 실행하는 것이 좋습니다.

WSL2에서 OMX를 사용하려면 Windows에 설치된 Node.js나 Codex CLI를 그대로 사용하는 것이 아니라, WSL2 안에 Node.js, Codex CLI, oh-my-codex를 별도로 설치해야 합니다. PowerShell과 WSL2는 서로 다른 실행 환경이기 때문에, 각각 설치된 프로그램을 공유하지 않는다고 이해하면 쉽습니다.

▶ Codex CLI 설치 방법 보러가기

▶ WSL 설치 방법과 tmux 사용법 보러가기

Oh My Codex 설치하기

oh-my-codex mac OS과 Linux 환경에 최적화되어 개발되었습니다. Windows에서도 실행할 수 있지만, 경로 처리나 쉘 명령어 호환성 문제를 줄이려면 PowerShell보다 WSL2 환경에서 설치하고 실행하는 것이 좋습니다.

WSL에서 Node.js 설치하기

oh-my-codex와 Codex CLI는 Node.js 기반으로 실행되기 때문에, WSL 환경에 Node.js가 먼저 설치되어 있어야 합니다. PowerShell에 Node.js가 설치되어 있더라도 WSL에서는 별도로 설치해야 합니다.

sudo apt update

sudo apt install -y curl

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

sudo apt install -y nodejs

위의 명령어를 입력해 WSL에서 Node.js를 설치합니다.

npm install -g @openai/codex oh-my-codex

sudo npm install -g @openai/codex oh-my-codex

WSL에서 Node.js 설치를 완료한 이미지입니다. Node.js의 설치가 끝났다면 omx를 설치합니다. 권한 문제로 error가 발생할 경우에는 앞에 sudo를 입력해 설치합니다.

omx

Codex Cli의 GPT 계정 연동 화면입니다. omx 설치가 완료되었다면 위의 명령어를 입력해 omx를 실행합니다. 실행 화면으로 들어가기 전 GPT 계정 연동 화면이 나옵니다. 원하는 옵션을 선택해 계정을 연동합니다.

Codex가 새로 추가되거나 변경된 hooks를 신뢰할지 확인하는 보안 확인 화면이 나옵니다.

Review hooks: 어떤 hooks가 추가됐는지 먼저 확인
Trust all and continue: 모든 hooks를 신뢰하고 계속 진행
Continue without trusting: hooks를 신뢰하지 않고 계속 진행, hooks는 실행되지 않음

처음 설치한 oh-my-codex 설정을 그대로 사용할 목적이라면 1번, 문제가 없어 보이면 2번 Trust all and continue로 진행하면 됩니다.

OMX의 설정이 끝나고 나온 Codex CLI 화면입니다. oh-my-codex 설정이 적용된 Codex CLI 화면으로 진입합니다. 화면 상단에 OpenAI Codex 버전, 사용 모델, 현재 작업 디렉터리, 권한 모드가 표시되면 실행이 정상적으로 완료된 상태로 볼 수 있습니다.

Oh My Codex 성능 테스트

OMX의 핵심은 Codex를 단순 실행하는 것이 아니라, 역할별 프롬프트를 사용해 작업을 나눠 진행할 수 있다는 점입니다.

따라서 작은 프로젝트를 만든 뒤 분석 → 계획 → 실행 → 검토 흐름으로 테스트를 해 omx의 성능을 테스트해보겠습니다.

OMX의 분석 테스트

프롬프트는 아래와 같습니다.

$architect

현재 프로젝트를 분석해줘.

index.html, style.css, script.js가 각각 어떤 역할을 하는지 설명하고, 현재 Todo 앱에서 개선할 수 있는 부분을 정리해줘.

OMX의 분석 테스트의 결과 화면입니다.

첫 번째 테스트에서는 $architect 프롬프트를 사용해 OMX가 프로젝트 구조를 제대로 분석하는지 확인했습니다.

테스트 결과 OMX는 index.html, style.css, script.js의 역할을 구분했고, 현재 Todo 앱이 할 일 추가 기능만 가진 최소 기능 프로젝트라는 점을 파악했습니다.

또한 빈 입력 방지, Enter 키 입력, 삭제 기능, 완료 처리, localStorage 저장처럼 개선할 수 있는 항목도 함께 제안했습니다.

OMX의 계획 테스트

프롬프트는 아래와 같습니다.

$plan 이 Todo 앱에 할 일 추가, 삭제, 완료 표시 기능을 넣으려고 해.

바로 수정하지 말고, 어떤 파일을 어떤 순서로 수정할지 먼저 계획을 세워줘

OMX의 계획 테스트의 결과 화면입니다.

두 번째 테스트에서는 $plan 프롬프트를 사용해 OMX가 바로 코드를 수정하지 않고 작업 계획을 먼저 세우는지 확인했습니다.

테스트 결과 OMX는 index.html, style.css, script.js 중 어떤 파일을 어떤 순서로 수정해야 하는지 정리했고, 완료 표시, 삭제 기능, 최종 동작 검증까지 단계별로 제안했습니다.

OMX의 실행 테스트

프롬프트는 아래와 같습니다.

$executor

방금 세운 계획에 따라 실제 파일을 수정해줘.

할 일 추가, 삭제, 완료 표시 기능을 구현하고, 빈 값은 추가되지 않게 해줘.

수정이 끝나면 어떤 파일을 어떻게 바꿨는지 요약해줘.

OMX의 실행 테스트의 결과 화면입니다. $executor 프롬프트를 입력하자 OMX는 앞서 세운 계획에 따라 실제 파일을 수정했습니다.

테스트 결과 할 일 추가, 빈 값 방지, Enter 키 입력, 완료 표시, 삭제 기능이 구현되었고, 마지막에는 수정된 파일과 변경 내용을 요약했습니다.

이를 통해 OMX가 단순 분석뿐 아니라 계획을 바탕으로 실제 코드 수정까지 이어갈 수 있다는 점을 확인할 수 있었습니다.

이제 OMX가 요청에 따라 만든 TODO List가 브라우저 화면에서 제대로 작동하는지 확인해보겠습니다.

테스트 결과, 새로운 할 일 추가, 빈칸 입력 방지, 삭제, 완료 처리 기능이 모두 정상적으로 작동했습니다.

OMX는 전달받은 프롬프트를 바탕으로 프로젝트를 분석하고, 수정 계획을 세운 뒤 실제 코드를 변경했으며, 마지막에는 변경 내용을 요약했습니다.

이를 통해 OMX가 분석 → 계획 → 실행 → 검토의 흐름으로 작업을 수행할 수 있다는 점을 확인할 수 있었습니다.

Oh My Codex의 주요 스킬

의도를 명확히 할 때 - $deep-interview

작업 요청이 아직 모호할 때 씁니다. AI가 먼저 질문을 던져 무엇을 원하는지, 어디까지가 범위인지 정리합니다. 코드를 짜기 전에 방향을 맞추는 단계라, 엉뚱한 결과가 나올 가능성을 줄여줍니다.

계획을 만들고 검토할 때 - $ralplan

정리된 요청을 실제 구현 계획으로 바꿉니다. 어떤 구조로 만들지, 어떤 선택지가 있는지, 무엇을 검증해야 하는지를 정리하고 사람이 검토할 수 있게 합니다. 다만 $ralplan 자체가 코드를 바로 수정하는 단계는 아닙니다.

기본 실행 흐름으로 이어갈 때 - $ultragoal

승인된 계획을 여러 목표와 체크포인트로 나눠 이어가는 기본 실행 흐름입니다. 긴 작업에서 진행 상황을 놓치지 않고, 단계별로 확인하며 밀고 가야 할 때 사용합니다.

병렬로 나눠 실행할 때 - $team

작업이 크고 여러 부분으로 나눌 수 있을 때 씁니다. 여러 작업자가 각자 맡은 부분을 동시에 처리해 속도를 높이는 방식입니다. 예를 들어 3:executor처럼 지정하면 실행자 3명이 병렬로 작업합니다.

한 작업자가 끝까지 밀어붙일 때 - $ralph

병렬로 나누기보다 한 작업자가 계속 붙잡고 끝까지 처리하는 편이 나을 때 씁니다. 완료와 검증이 확인될 때까지 작업을 이어가는 흐름에 가깝습니다.

정리하면, 일반적인 흐름은 $deep-interview로 의도를 분명히 하고, $ralplan으로 계획을 세운 뒤, 기본적으로 $ultragoal로 실행을 이어가는 방식입니다. 작업이 병렬 처리에 적합하면 $team, 한 명의 지속 실행자가 더 적합하면 $ralph를 선택하면 됩니다.

Oh My Codex 사용 시 주의사항 4가지

작은 작업에는 필요하지 않습니다.

OMX는 크고 복잡한 작업을 위한 도구입니다. 한 파일만 고치는 단순 작업이라면, OMX의 계획·검증 단계가 오히려 번거로울 수 있습니다. 공식 문서도 별도 작업 흐름이 필요 없다면 그냥 Codex를 쓰라고 안내합니다. 여러 파일이 얽히거나 오래 걸리는 작업일 때 쓰는 것이 좋습니다.

운영체제 환경을 확인해야 합니다.

OMX는 macOS나 리눅스에서 가장 안정적으로 작동하며, 특히 팀 모드의 병렬 실행은 tmux에 기댑니다. 윈도우는 공식적으로 권장되지 않고 작동이 불안정할 수 있어, 윈도우 사용자는 WSL2 환경에서 쓰는 것이 안전합니다. 도입 전에 자신의 환경을 먼저 확인해야 합니다.

여러 에이전트를 돌리는 만큼 비용이 늘 수 있습니다.

OMX의 팀 모드는 여러 작업자를 동시에 돌립니다. 그만큼 여러 AI 세션이 병렬로 작동하므로, 토큰 사용량과 비용이 함께 늘어날 수 있습니다. 특히 높은 동시 실행 옵션을 쓰면 자원 소모가 큽니다. 비용에 민감하다면 작업 규모에 맞게 동시 실행 수를 조절하는 것이 좋습니다.

결과는 사람이 검토해야 합니다.

OMX가 검증 단계를 두긴 하지만, AI가 만든 코드와 병렬 작업의 결과가 항상 완벽한 것은 아닙니다. 오케스트레이션은 실패를 더 빨리 발견하게 해줄 뿐, 실패 자체를 없애지는 못합니다. 여러 작업자가 만든 결과를 합치기 전에, 최종 결과를 사람이 확인하는 과정이 필요합니다.