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

Codex는 에디터의 조수 역할이 아니라 스스로 실행하는 주체입니다. 여러분이 작업을 말로 설명하면, 어떤 파일을 읽고 어떤 명령을 실행하며 무엇을 바꿀지 스스로 판단합니다. 그 손에는 약 열 가지 도구가 있습니다: 명령 실행, 파일 읽기, 작업 계획 관리, 사용자에게 확인 요청, 하위 작업을 위한 자식 에이전트 생성.

두 가지 작동 모드가 있습니다. 대화형 — 인자 없이 codex, 각 단계를 보여주며 터미널에서 대화. 비대화형 — codex exec "task", 결과까지 한 번에 실행. 스크립트와 CI에서 편리합니다.

보안은 내장되어 있습니다. 기본적으로 에이전트는 샌드박스에서 작동하며 변경 전에 확인을 요청합니다. 제어 수준은 설정에서 지정할 수 있습니다 — '모두 확인'부터 작업 디렉터리에 쓸 권한을 가진 완전 자율 실행까지.

또 하나의 특징은 대화 상태입니다. Codex는 서버에 아무것도 기억하도록 요청하지 않습니다. 전체 스레드를 자신이 보관하고 매 턴마다 그것을 통째로 전송합니다. 이는 곧 대화가 모델 프로바이더 쪽에 남지 않고, endpoint를 바꿔도 시작한 세션이 깨지지 않는다는 뜻입니다.

Claude Code와 다른 터미널 에이전트와의 차이는 바로 프로토콜입니다. Codex는 Responses API를 통해 모델과 통신하며, 여기서 대화는 평면적인 메시지 목록이 아니라 요소의 스레드로 기술됩니다: 텍스트, 도구 호출, 호출 결과, 추론 블록. 이는 도구에 더 엄격한 대화 모델을 제공하고, 여러분에게는 이 프로토콜을 이해하는 endpoint가 필요하다는 점을 의미합니다.

가장 빠른 길은 설치 프로그램입니다. npx @joingonka/setup --tool codex 명령이 ~/.codex/config.toml에 프로바이더 블록을 직접 써넣습니다(wire_api = "responses", 모델과 실제 컨텍스트 윈도우 포함). 여러분의 주석과 나머지 설정은 그대로 보존하고, 이후 라이브 요청으로 키와 모델을 검증합니다. 설정 파일에 이미 다른 프로바이더가 선택되어 있으면 설치 프로그램은 그것을 건드리지 않고 일회성 실행용 명령을 알려줍니다. 키는 파일에 바로 넣으며(권한 600), experimental_bearer_token 필드에 저장합니다 — Codex가 키를 리터럴로 보관할 수 있는 유일한 필드지만 Codex 자체는 이를 실험적 기능으로 취급합니다. 아래 수동 방식은 환경 변수로 해결합니다.

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 "Answer in one line: what is 17*3?"

Codex는 응답 상단에 어떤 대상과 통신하는지 출력합니다: model, provider: joingonka, 샌드박스 모드, 세션 ID. 여기에 여러분의 프로바이더가 표시되고 하단에 응답이 도착했다면 연결은 살아 있는 것입니다.

다음으로 확인해야 할 것은 Codex를 설치하는 가장 큰 이유인 파일 작업입니다. 명백한 버그가 있는 작은 파일을 디렉터리에 넣고 찾아보라고 요청하세요:

codex exec "Read calc.py and tell me in one sentence whether it has a bug."

에이전트가 스스로 읽기 도구를 호출하고, 파일을 열고, 줄 번호를 명시하여 핵심적으로 답해야 합니다. 이렇게 된다면 완전한 에이전트 사이클(요청 → 도구 호출 → 결과 → 응답)이 게이트웨이를 통해 올바르게 구성된 것입니다.

문제가 발생하면 진단은 보통 메시지에서 바로 읽을 수 있습니다:

세션의 첫 요청은 몇 초 걸릴 수 있습니다: Codex가 큰 시스템 프롬프트와 모든 도구 설명을 전송하고, 네트워크 노드가 작업을 받아들여야 하기 때문입니다. 이후 응답은 더 빠르게 도착합니다.

네트워크의 모든 모델이 동일한 가격으로 제공되므로 선택은 예산이 아닌 동작 방식에 달려 있습니다. 아래는 동일한 작업(파일 읽기 및 오류 찾기)을 Codex를 통해 DeepSeek V4 Flash와 MiniMax M2.7에서 수행한 실시간 결과입니다. GLM-5.3 Flash는 실행 후 네트워크에 추가되었으므로 해당 모델 특성을 기재합니다.

기본 추천 모델은 DeepSeek V4 Flash입니다. 에이전트 작업은 컨텍스트 용량 제한에 빨리 도달하기 때문에, 380K 토큰은 한 번에 많은 파일을 관리하는 데 유리합니다. 복잡한 로직의 추론이 필요한 작업은 GLM-5.3 Flash를 사용하되 max_tokens에 여유를 두십시오. 모델은 설정 파일의 model 줄을 수정하거나 파일 수정 없이 -c model=… 플래그를 사용하여 변경할 수 있습니다.

실시간 네트워크 모델 목록은 언제든지 GET https://gate.joingonka.ai/v1/models에서 확인할 수 있습니다.

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

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

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

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

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

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

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

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

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

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