Codex CLI: 구독 대신 자체 키 사용

Codex는 에디터 내 제안 도구가 아니라 독립적인 실행자입니다. 사용자가 말로 작업을 정의하면, 어떤 파일을 읽고 어떤 명령을 실행하며 무엇을 수정할지 스스로 결정합니다. 명령 실행, 파일 읽기, 작업 계획 관리, 사용자에게 확인 요청, 하위 작업을 위한 자식 에이전트 생성 등 10여 가지 도구를 사용할 수 있습니다.

두 가지 실행 모드가 있습니다. 대화형 모드는 인자 없는 codex로, 각 단계를 표시하며 터미널에서 대화합니다. 비대화형 모드는 codex exec "작업"으로, 결과가 나올 때까지 한 번만 실행합니다. 스크립트나 CI에서 유용합니다.

보안이 내장되어 있습니다. 기본적으로 에이전트는 샌드박스에서 실행되며 변경 사항을 적용하기 전에 확인을 요청합니다. 제어 수준은 구성에서 설정할 수 있으며, "모두 확인"부터 작업 디렉토리에 대한 쓰기 권한이 있는 완전 자율 실행까지 선택 가능합니다.

또 다른 특징은 대화 상태입니다. Codex는 서버에 아무것도 저장하지 않습니다. 전체 대화 기록을 클라이언트에서 유지하고 매 단계마다 전체 내용을 전송합니다. 즉, 대화 내용이 모델 프로바이더 측에 남지 않으며 endpoint를 변경해도 세션이 끊기지 않습니다.

Claude Code 및 기타 터미널 에이전트와 다른 점은 바로 프로토콜입니다. Codex는 Responses API를 통해 모델과 통신하며, 대화는 단순한 메시지 리스트가 아니라 텍스트, 도구 호출, 호출 결과, 사고 블록과 같은 요소들의 스트림으로 기술됩니다. 이를 통해 도구는 더 엄격한 대화 모델을 얻을 수 있고, 사용자는 해당 프로토콜을 이해하는 endpoint를 준비해야 합니다.

Codex는 설정을 ~/.codex/config.toml에 저장합니다. 자체 프로바이더는 [model_providers.*] 블록으로 설명되며 여기서 핵심 필드는 wire_api입니다. 이 필드가 없으면 Codex는 Chat Completions으로 통신을 시도하여 에이전트 사이클을 구성할 수 없습니다.

# ~/.codex/config.toml
model_provider = "joingonka"
model = "deepseek-ai/DeepSeek-V4-Flash-0731"

[model_providers.joingonka]
name = "JoinGonka Gateway"
base_url = "https://gate.joingonka.ai/v1"
env_key = "JOINGONKA_API_KEY"
wire_api = "responses"

키는 파일에 직접 작성되지 않습니다. env_key는 Codex가 키를 가져올 환경 변수 이름을 지정합니다. 변수 이름은 OPENAI_API_KEY와 다르므로 OpenAI를 사용하는 다른 도구들과 간섭하지 않습니다.

export JOINGONKA_API_KEY=jg-your-key

model 필드는 기본 모델을 지정하고, model_provider는 사용할 블록을 지정합니다. 둘 다 실행 시점에 재정의할 수 있으므로 단일 설정으로 실용, 실험용, 백업용 등 여러 프로바이더를 관리할 수 있습니다.

키는 등록 후 마이페이지에서 발급되며, 잔액 및 사용량도 확인할 수 있습니다. 공통 설정을 수정하고 싶지 않다면 -c를 사용하여 동일한 블록을 한 번만 전달할 수도 있습니다: codex -c model_provider=joingonka …. 또한 여러 독립적인 설정을 유지하려면 환경 변수 CODEX_HOME으로 설정 디렉토리를 지정하십시오.

연동이 작동하는지 확인하는 가장 빠른 방법은 일회성 테스트를 실행하는 것입니다:

codex exec "17*3이 몇인지 한 줄로 답해줘"

응답 헤더에는 Codex가 누구와 작업하는지(model, provider: joingonka, 샌드박스 모드 및 세션 식별자)가 표시됩니다. 해당 항목에 제공자 정보가 있고 아래에 응답이 도착했다면 연결이 활성화된 상태입니다.

다음으로 Codex를 도입하는 주된 목적인 파일 작업을 확인해 봅시다. 디렉토리에 간단한 파일을 넣고 명백한 오류를 포함시킨 뒤 오류를 찾아달라고 요청하세요:

codex exec "calc.py를 읽고 오류가 있는지 한 문장으로 말해줘."

에이전트가 스스로 읽기 도구를 호출하여 파일을 열고, 해당 행을 명시하며 적절하게 답변해야 합니다. 이 과정이 수행된다면 게이트웨이를 통한 전체 에이전트 루프(요청 → 도구 호출 → 결과 → 응답)가 올바르게 구성된 것입니다.

문제가 발생했다면 보통 메시지에서 진단 결과를 확인할 수 있습니다:

세션의 첫 번째 요청은 몇 초 정도 걸릴 수 있습니다. Codex가 큰 시스템 프롬프트와 모든 도구 설명을 전송하고 네트워크 노드가 작업을 수락해야 하기 때문입니다. 이후의 응답은 더 빠르게 처리됩니다.

모든 네트워크 모델은 동일한 가격으로 제공되므로, 선택 기준은 예산이 아니라 동작 특성에 달려 있습니다. 다음은 동일한 작업(파일 읽기 및 오류 찾기)을 각 모델에서 Codex를 통해 실행했을 때의 결과입니다.

기본적으로 추천하는 모델은 DeepSeek V4 Flash입니다. 에이전트 작업은 금방 컨텍스트 용량 한계에 도달하는데, 380K 토큰은 한 번에 많은 파일을 관리할 수 있는 여유를 줍니다. 극도로 짧은 응답을 원한다면 Kimi K2.6을 선택하세요. 모델 변경은 설정 파일의 model 줄을 수정하거나, 파일 수정 없이 -c model=… 플래그를 추가하는 것만으로 간단히 완료됩니다.

최신 모델 목록은 항상 GET https://gate.joingonka.ai/v1/models에서 확인할 수 있습니다.

에이전트 도구는 일반 챗봇과 다르게 토큰을 소비합니다. Codex는 사용자의 각 문장에 시스템 프롬프트와 모든 도구 설명을 추가하고 모델과 다단계 대화를 이어가기 때문입니다. 실측 결과, 간단한 작업인 '파일 읽기 및 오류 찾기'에 약 18,000~20,000 토큰이 소비되었습니다. 이는 자율성을 위한 필수 비용이며, 토큰 단가가 중요한 이유입니다.

JoinGonka Gateway를 통한 토큰 가격은 입력 100만 토큰당 $0.0047, 출력 100만 토큰당 $0.014이며, 네트워크 내 모든 모델에 공통으로 적용됩니다. 가격은 이 페이지에서 실시간 소스를 통해 가져옵니다.

참고로, Codex 및 타 서비스들의 유료 결제 구조는 다음과 같습니다:

실제 소비량에 대해서만 결제하며 월간 구독이나 요청 횟수 제한이 없습니다. 5시간 단위 제한, 프롬프트 한도, 피크 시간대 배율 적용 등도 없습니다. 잔액은 암호화폐로 충전하며 소비 내역은 개인 계정에서 확인 가능합니다. 상세 경제 분석은 가장 저렴한 API 관련 문서를 참조하세요.

대화 기록은 Codex 자체가 유지합니다. 각 요청 시 전체 기록을 전송하며 서버에 아무것도 저장하지 않도록 요청합니다. 저희 또한 대화 내용을 저장하지 않습니다. 사용자의 코드와 프롬프트는 응답 후 게이트웨이에 남지 않습니다.

웹 검색이 작동합니다. Codex는 매 요청마다 검색 도구를 선언하며 게이트웨이가 이를 수락합니다. 검색은 저희 측에서 수행되고 결과는 모델의 응답에 포함됩니다.

도구는 클라우드가 아닌 로컬용입니다. Codex는 명령을 실행하고 파일을 로컬(사용자의 기기)에서 읽으므로 프로젝트 접근 권한이 모델 제공업체에 의존하지 않습니다.

샌드박스. Linux에서 Codex는 실행되는 명령을 격리하기 위해 bubblewrap을 사용합니다. 시스템에 bubblewrap이 없으면 Codex가 경고를 표시하고 내장 복사본을 사용합니다. 작업에는 영향이 없지만 시스템 패키지 관리자를 통해 설치하는 것이 더 편리합니다.

이미지 작업이 필요한 경우(인터페이스 스크린샷, 사진 속 다이어그램 등) 시각 인식 능력이 있는 모델 도구를 사용하세요. Gonka 네트워크의 모델은 텍스트 전용입니다. 코드, 명령, 파일 작업에는 아무런 제약이 없습니다.

Codex가 적합하지 않은 경우 다른 터미널 에이전트를 사용해보세요: 빠른 시작 API 가이드에서 호환되는 도구를 몇 분 만에 연결하는 방법을 확인할 수 있습니다.