OpenCodex란? 다양한 AI 모델을 하나로 연결하는 멀티 모델 프록시 사용법

AI 모델마다 서로 다른 특성을 가지고 있습니다. 어떤 모델은 복잡한 코드 구조를 이해하는 데 강하고, 어떤 모델은 긴 문맥을 처리하거나 반복 작업을 빠르게 수행하는 데 유리합니다. 하지만 모델마다 사용하는 환경과 인증 방식이 달라, 작업에 따라 도구를 바꿔야 하는 불편이 있었습니다.

이러한 문제를 줄이기 위해 오픈소스 도구가 등장했습니다. 바로 ‘OpenCodex’입니다. Codex와 Claude Code의 작업 환경은 그대로 유지하면서, 상황에 맞는 LLM을 연결해 사용할 수 있도록 지원합니다. 덕분에 성능과 비용, 작업 목적을 고려해 적합한 모델을 선택해 작업을 처리할 수 있습니다.

이번 글에서는 OpenCodex가 어떤 도구인지 살펴보고, 설치와 모델 연결 방법, 서브에이전트 활용법, 실제 사용 시 주의해야 할 내용까지 정리해보겠습니다.

OpenCodex 핵심 요약

• 다양한 LLM을 기존 코딩 환경에 연결합니다. Codex와 Claude Code의 작업 방식은 유지하면서 Claude, Gemini, DeepSeek, Ollama 등 원하는 모델을 연결해 사용할 수 있습니다.
• 서브에이전트별로 다른 모델을 배정합니다. Codex 환경에서는 최대 5개의 모델을 지정해 설계·구현·테스트 업무를 서로 다른 LLM에 나눠 맡길 수 있습니다.
• 외부 API와 로컬 모델을 함께 활용할 수 있습니다. Ollama, LM Studio, vLLM 같은 로컬 모델도 연결할 수 있어 보안·비용·작업 난도에 따라 모델을 선택할 수 있습니다.
• 인증과 모델 호환성을 반드시 확인합니다. Claude OAuth 계정 제한 가능성, 실제 과금 계정, 모델별 기능 차이, API 키와 로그 노출 여부를 사용 전에 점검해야 합니다.

OpenCodex란?

* 이미지 출처: OpenCodex Github 공식 저장소

OpenCodex는 OpenAI Codex와 Claude Code에서 원하는 AI 모델을 사용할 수 있도록 연결해 주는 오픈소스 로컬 프록시입니다. 

Codex나 Claude Code가 보내는 요청을 중간에서 받아 Anthropic, Google Gemini, xAI, DeepSeek, Kimi, Ollama 등 각 모델 제공업체에 맞는 API 형식으로 변환해 전달합니다.

이를 통해 사용자는 Codex 또는 Claude Code의 작업 환경과 도구, 프로젝트 규칙은 그대로 유지하면서 실제 추론을 담당하는 모델만 바꿀 수 있습니다. 

예를 들어 Codex에서는 Claude나 Gemini를 실행하고, Claude Code에서는 OpenAI 모델이나 Grok, 로컬 모델을 사용하는 방식으로 자유롭게 조합할 수 있습니다.

하나의 코딩 에이전트 환경에서 

다양한 LLM을 활용하기 위해 개발된 OpenCodex 

AI 모델마다 코드 분석, 긴 문맥 이해, 추론 속도, 비용 효율성 등 서로 다른 강점을 가지고 있습니다. 

예를 들면 Codex는 도구 호출과 코드 실행 환경에 최적화 되어 있고, Claude는 복잡한 코드 구조와 긴 맥락을 파악하는 작업에 강점을 보입니다. 

Gemini는 많은 자료를 한 번에 검토해야 하는 긴 컨텍스트 작업에 활용할 수 있고, 경량 모델이나 로컬 모델은 반복적인 수정이나 비용을 줄여야 하는 업무에 적합합니다.

작업에 따라 AI 모델의 특성에 맞춰 활용한다면 더 나은 결과를 얻을 텐데, 모델을 제공하는 환경과 사용 방식이 달라 그렇지 못하는 불편이 있었습니다. 

OpenCodex는 이 문제를 해결하기 위해 등장했습니다. 

OpenCodex가 주목받는 이유

원하는 코딩 에이전트 환경에서 다양한 LLM을 활용할 수 있습니다

OpenCodex는 OpenAI Codex와 Claude Code를 기반으로 작동하는 멀티 모델 프록시입니다. 사용자는 Codex 또는 Claude Code 중 익숙한 코딩 에이전트 환경을 선택하고, 그 안에서 Claude, Gemini, Grok, DeepSeek, Kimi, Ollama 등 작업에 적합한 LLM을 연결할 수 있습니다.

OpenCodex는 각 코딩 에이전트가 보내는 작업 지시와 도구 호출 요청을 모델 제공업체에 맞는 API 형식으로 변환합니다. 덕분에 사용자는 프로젝트 규칙과 파일 수정 방식, 터미널 실행 흐름은 그대로 유지하면서 실제 추론을 담당하는 모델만 바꿔 사용할 수 있습니다.

Codex의 서브에이전트를 통해 에이전트 별 LLM 모델을 선택할 수 있습니다. 

OpenCodex는 Codex의 서브에이전트를 통해 서로 다른 LLM을 선택해 사용할 수 있도록 지원합니다. 복잡한 설계와 추론은 성능이 높은 모델에 맡기고, 코드 검색이나 테스트 작성, 반복적인 수정은 속도가 빠르거나 비용이 낮은 모델에 배정하는 방식으로 작업을 나눌 수 있습니다. 

작업의 성격에 따라 적합한 모델을 구분해 활용하면 각 LLM의 강점을 더욱 효율적으로 살릴 수 있습니다. 덕분에 작업 속도와 토큰 활용 효율을 높이고, 불필요한 API 비용도 줄일 수 있습니다. 

로컬 모델도 동일한 코딩 환경에서 활용할 수 있습니다. 

OpenCodex는 Ollama, LM Studio, vLLM과 같은 로컬 모델도 연결할 수 있습니다. 별도의 코딩 도구로 이동하지 않고 현재 사용 중인 Codex 또는 Claude 환경에 연동해 작업을 이어갈 수 있어, 사용자는 작업 목적과 보안 · 비용 조건에 따라 더욱 폭넓은 모델을 선택해 활용할 수 있습니다.

OpenCodex 사용법

OpenCodex를 사용하려면 Node.js 18 이상의 버전이 필요합니다. macOS와 Linux, Windows를 지원하며, Windows에서도 WSL을 별도로 설치하지 않고 사용할 수 있습니다. 

OpenCodex를 설치하기

먼저 터미널이나 PowerShell에서 위의 명령어를 실행해 OpenCodex를 설치합니다. 

OpenCodex를 처음 사용할 때는 요청을 전달할 LLM 제공업체를 등록해야 합니다. 위 명령어를 실행하면 연결할 수 있는 모델 제공업체 목록이 표시됩니다.

사용할 항목의 번호를 입력한뒤 설명에 맞춰 아이디를 로그인하거나 API 키나 OAuth 인증 정보를 설정하면 OpenCodex에서 해당 모델을 사용할 수 있습니다. 

설정을 마치면 위의 명령어를 입력해 OpenCodex 프록시를 실행합니다.

opencodex proxy running on http://localhost:10100이라는 문구가 표시되면 정상적으로 실행된 상태입니다. 대시보드 주소를 클릭하면 OpenCodex 대시보드 화면이 나옵니다. OpenCodex를 사용하는 동안에는 해당 PowerShell 창을 닫지 않고 유지해야 합니다. 

OpenCodex 대시보드 조작법

* OpenCodex에서 프로바이더 추가하기

OpenCodex에서 사용할 모델은 대시보드에서도 간편하게 추가할 수 있습니다. 왼쪽 사이드 바에서 프로바이더를 선택하면 현재 연동된 제공 업체와 사용할 수 있는 모델을 확인할 수 있습니다.

새로운 모델을 추가하려면 오른쪽 상단의 프로바이더 추가 버튼을 클릭합니다. 

프로바이더 목록이 열리면 검색창에서 원하는 제공업체를 찾은 뒤, 해당 서비스가 요구하는 방식에 따라 API 키를 입력하거나 계정 로그인을 진행합니다.

연동이 완료되면 해당 프로바이더가 목록에 추가되고, 사용할 수 있는 LLM 모델이 추가되어, 원하는 LLM을 OpenCodex에서 선택해 사용할 수 있습니다. 

서브 에이전트 모델 추가하기

OpenCodex에서는 서브에이전트가 사용할 모델을 최대 5개까지 미리 지정할 수 있습니다. 먼저 왼쪽 사이드바에서 모델 메뉴를 선택합니다. 

화면 하단의 모델 목록에서 서브에이전트에 사용할 모델을 최대 5개까지 선택한 뒤 저장 버튼을 누릅니다. 설정이 저장되면 선택한 모델이 Codex의 서브에이전트 모델 목록에 추가되며, 이후 작업을 나눌 때 에이전트별로 필요한 LLM을 선택해 활용할 수 있습니다. 

Codex에서 OpenCodex를 사용해 작업 진행하기

이제 OpenCodex가 적용된 상태에서 Codex를 실행해 작업을 처리해보겠습니다. Codex 사용을 위해 별도의 터미널을 열고 Codex를 실행합니다.

Codex를 실행하면 OpenCodex에 등록한 설정과 모델 목록이 반영됩니다. /model 메뉴를 열면 기존 OpenAI 모델뿐 아니라 OpenCodex를 통해 연결한 Gemini, Claude, 로컬 모델 등 선택할 수 있는 LLM이 추가된 것을 확인할 수 있습니다.

* OpenCodex 서브에이전트 테스트

서브 에이전트에서 각각의 LLM 모델을 사용해 작업을 처리하는 것을 테스트하기 위해 테스트 시뮬레이션을 진행했습니다. 작업은 세 단계로 나눴습니다. 

• 먼저 Gemini 모델을 사용하는 기획·분석 에이전트가 기능 요구사항과 파일 구조를 설계합니다.
• 다음으로 OpenAI 모델을 사용하는 구현 에이전트가 설계안을 바탕으로 실제 앱을 제작합니다.
• 마지막으로 Gemini 모델을 사용하는 테스트 에이전트가 기능이 정상적으로 작동하는지 점검하고 테스트를 작성합니다.

메인 에이전트는 각 서브에이전트의 결과를 취합하고, 발견된 문제를 다시 수정하도록 조율한 뒤 최종 실행 방법과 테스트 결과를 정리합니다. 

이를 통해 하나의 작업 안에서 서로 다른 LLM이 역할별로 나뉘어 동작하는지 확인해보도록 작업을 요청했습니다.

테스트 작업 결과 요청한 대로 서브에이전트를 활용해 작업이 진행된 것을 확인할 수 있습니다. 기획과 분석, 테스트에는 Gemini 3.1 Pro를 사용하고, 실제 기능 구현에는 GPT-5.5를 배정해 역할별로 작업을 처리했습니다.

파일 탐색과 수정, 명령어 실행을 담당하는 Codex 에이전트 환경은 그대로 유지하면서, 각 작업의 판단과 코드 생성을 담당하는 LLM만 외부 모델로 나누어 적용한 것입니다.

OpenCodex, 이렇게 활용해보세요

작업 성격에 따라 모델을 바꿔보세요.

대규모 코드 구조 분석과 복잡한 리팩터링에는 고성능 추론 모델을 선택하고, 테스트 생성이나 문서 정리처럼 반복성이 높은 작업에는 빠르고 저렴한 모델을 사용할 수 있습니다.

Codex의 사용법과 프로젝트 설정은 유지되기 때문에 모델을 바꿀 때마다 새로운 코딩 도구를 익힐 필요가 없습니다. 모델별 성능과 비용을 비교하면서 팀에 맞는 조합을 찾을 때 특히 유용합니다.

유료 API와 로컬 모델을 함께 운영해보세요.

민감하거나 반복적인 코드 처리는 로컬 Ollama 모델로 보내고, 로컬 모델이 해결하기 어려운 복잡한 문제만 외부 고성능 모델에 맡기는 방식으로 구성할 수 있습니다.

모든 작업을 비싼 모델에 보내지 않아도 되므로 API 비용을 조절하기 쉽고, 코드의 민감도와 작업 난도에 따라 처리 경로를 나눌 수 있습니다.

멀티에이전트마다 다른 모델을 배정해보세요.

설계와 최종 검토에는 높은 추론 성능을 가진 모델을 사용하고, 코드 검색과 테스트 생성은 빠른 모델에 맡길 수 있습니다. 하나의 모델이 모든 작업을 처리하도록 구성하는 것보다 각 모델의 강점을 역할별로 활용할 수 있습니다.

다만 모델을 많이 섞을수록 출력 형식과 지시 해석, 도구 호출 방식의 차이가 커질 수 있습니다. 처음에는 두 개 정도의 모델로 시작해 결과를 비교한 뒤 점차 역할을 나누는 편이 안정적입니다.

OpenCodex 사용 시 주의사항

1) Claude 구독 계정 연결은 신중하게 진행하세요.

Claude Pro · Max 계정의 OAuth 인증을 OpenCodex 같은 제3자 프록시에 연결하면 인증이 중단되거나 계정 사용이 제한될 가능성이 있습니다. 

안정적으로 사용하려면 Anthropic API 키 방식을 우선 고려해야 하며, 이 경우 구독료와 별도로 API 비용이 발생합니다.

2) 실제로 어떤 모델과 계정이 사용됐는지 확인하세요.

여러 프로바이더와 API 키를 등록하면 예상과 다른 모델이나 과금 계정으로 요청이 전달될 수 있습니다. 중요한 작업 전에는 모델을 명확히 지정하고, 대시보드의 로그와 사용량에서 실제 요청 경로를 확인하는 것이 좋습니다.

3) 연결한 모델이 모든 기능을 동일하게 지원하지는 않습니다.

모델마다 도구 호출, 이미지 입력, 긴 문맥 처리, 서브에이전트 위임 능력이 다릅니다. 모델 목록에 표시되더라도 Codex 전용 모델과 똑같이 작동한다고 볼 수 없으므로, 작은 수정과 테스트부터 확인한 뒤 작업 범위를 넓혀야 합니다.

4) API 키와 대시보드를 외부에 노출하지 마세요.

대시보드와 로그에는 API 키, 인증 상태, 파일 경로, 요청 내용이 포함될 수 있습니다. 기본 로컬 접속 설정을 유지하고, 화면을 공유할 때는 민감한 정보가 보이지 않는지 확인해야 합니다.

오직 나만의 AI 활용 방법이 궁금하다면

Orca 사용법, 여러 AI 코딩 에이전트 한눈에 관리하기

ChatGPT Work 사용법: 플러그인 연동으로 AI 에이전트 확장하기

OpenWiki 사용법: 코드베이스를 AI 에이전트의 지식 저장소로 만들기

AI 에이전트 기반 개발 환경 구축,

검증된 IT 프리랜서와 시작하세요.

대한민국 최대 IT 프리랜서 매칭 플랫폼 이랜서

이랜서는 27년간 삼성 · 현대 · SK · 카카오 등 주요 기업에 매칭하며 축적한 8만 건 이상의 IT 프리랜서 매칭 데이터를 바탕으로, AI 에이전트 시스템 구축 경험과 클라우드 실무 역량을 갖춘 검증된 전문가를 매칭합니다.

단순 이력서 연결이 아닌, 프로젝트 성격과 기술 스택, 활용 모델, 협업 방식까지 고려한 정밀 매칭으 98%의 재의뢰율을 달성하고 있습니다.

AI 에이전트 기반 개발 환경을 기획부터 구축, 운영 자동화까지 안정적으로 추진하세요. 프로젝트에 적합한 AI 전문 프리랜서를 24시간 내, 매칭해 드립니다.