메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
소개

Codex CLI는 OpenAI가 공개한 오픈 소스 터미널 코딩 에이전트로, 커맨드라인에서 직접 파일을 읽고 쓰고 명령을 실행하며 버그를 수정하고 코딩 작업을 완수할 수 있습니다. APIMart에 연결하면 GPT, Claude를 비롯한 다양한 모델을 Codex CLI에서 자유롭게 사용할 수 있으며, 더 유연하고 합리적인 요금 체계의 혜택도 누릴 수 있습니다.

​
준비 사항

시작하기 전에 다음을 확인하세요:
  1. Node.js 설치 완료 Node.js 공식 사이트에서 다운로드하여 설치하세요 (최신 LTS, v20 이상 권장). npm으로 Codex CLI를 설치하기 위해 필요합니다
  2. APIMart API 키 획득 완료 APIMart 콘솔에 로그인하여 API 키를 받으세요 (sk-로 시작)
팁: APIMart 계정이 없으시다면 먼저 APIMart에서 가입하고 API 키를 받으세요.

​
1단계: Codex CLI 설치

다음 방법 중 하나를 선택해 설치하세요:
npm으로 전역 설치합니다. 모든 운영체제에 적용됩니다:
npm install -g @openai/codex
권한 문제가 발생하면 명령 앞에 sudo를 붙이세요 (macOS / Linux).

​
설치 확인

설치 후 다음 명령으로 정상 설치 여부를 확인합니다: 
codex --version
버전 번호가 출력되면 설치 성공입니다.

​
2단계: APIMart API 설정

Codex CLI는 ~/.codex/ 디렉터리의 설정 파일로 모델 공급자를 관리합니다. APIMart를 가리키는 커스텀 공급자 하나만 추가하면 됩니다.

​
2.1 설정 디렉터리 위치

  • macOS / Linux: ~/.codex/
  • Windows: C:\Users\<사용자명>\.codex\
디렉터리가 없다면 터미널에서 codex를 한 번 실행한 뒤 Ctrl + C로 종료하세요. 자동으로 생성됩니다.

​
2.2 API 키 설정

설정 디렉터리에 auth.json 파일을 만들거나 열어 APIMart 키를 입력합니다: 
{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxx"
}
필드설명
OPENAI_API_KEY본인의 APIMart API 키 (sk-로 시작)

​
2.3 모델 공급자 설정

설정 디렉터리에 config.toml 파일을 만들거나 열어 APIMart 공급자를 추가합니다: 
# 기본 사용 모델
model = "gpt-5.5"
# 기본 공급자 — 아래 [model_providers.apimart]와 매칭
model_provider = "apimart"

# APIMart 공급자 설정
[model_providers.apimart]
name = "APIMart"
base_url = "https://api.apimart.ai/v1"
wire_api = "responses"
requires_openai_auth = true
필드설명
model기본 모델 ID. 아래 모델 목록에서 선택
model_provider기본 공급자. [model_providers.xxx]의 ID와 일치해야 함
name공급자 표시 이름. 자유롭게 지정 가능
base_urlAPIMart의 OpenAI 호환 주소. https://api.apimart.ai/v1로 고정
wire_api통신 프로토콜. 최신 Codex는 responses (Responses API) 사용 필요
requires_openai_authtrue로 설정하면 auth.json의 키로 인증합니다
두 파일을 저장한 뒤 Codex CLI를 재시작하면 적용됩니다.
auth.json은 올바른 JSON 형식, config.toml은 올바른 TOML 형식이어야 합니다. 전각 따옴표를 사용하지 마세요. 그러지 않으면 설정이 적용되지 않습니다.

​
3단계: 시작하기

​
설정 확인

임의의 프로젝트 디렉터리에서 다음 명령을 실행해 설정이 올바른지 확인합니다: 
codex "한 문장으로 자신을 소개해 주세요"
AI 응답이 오면 설정 성공입니다. 로그인 화면이 뜨거나 401, 403 오류가 발생하면 아래 자주 묻는 질문을 참고하세요.

​
대화형 모드

codex를 그대로 실행하면 대화형 UI로 진입합니다. 본격적인 코딩 작업에 적합합니다: 
codex
진입한 뒤 자연어로 요구사항을 설명하세요. 예시: 
JSON을 반환하는 헬스 체크 엔드포인트를 포함한 Express.js 서버를 만들어 줘
Codex가 프로젝트를 분석해 코드를 생성하고, 명령을 실행하며, 민감한 작업 전에는 확인을 요청합니다.

​
승인 모드

처음 실행 시 Codex가 작업 승인 수준을 선택하라고 합니다:
모드설명
읽기 전용파일 읽기만 허용. 모든 수정과 명령은 확인 필요
자동작업 디렉터리 내에서 파일 읽기/쓰기와 명령 실행 자율 수행 (권장)
전체 접근확인 없이 모든 작업 수행. 신중히 사용
처음에는 자동 모드부터 시작하기를 권장합니다. 대화형 UI에서 /approvals를 입력하면 언제든 변경할 수 있습니다.

​
모델 전환

대화형 UI에서 /model 명령으로 빠르게 전환하거나, config.toml의 model 필드를 수정한 뒤 재시작하세요.

​
지원 모델

Codex CLI에서는 다음 GPT-5 시리즈 모델을 권장합니다:
모델 ID특징추천 시나리오
gpt-5.5최신 플래그십, 코딩 능력 최상Codex 1순위, 복잡한 엔지니어링 작업
gpt-5.4이전 세대 플래그십, 강력한 성능복잡한 코딩, 아키텍처 설계
gpt-5.4-mini경량 버전, 빠르고 가성비 좋음일상 코딩, 빠른 반복
gpt-5.3-codexCodex에 최적화된 코딩 모델에이전트형 코딩 작업
gpt-5.2안정적이고 균형 잡힌 성능일반 코딩 작업
모델 선택 가이드: 위의 GPT-5 시리즈가 Codex CLI와 가장 잘 맞습니다. 최고의 경험을 원한다면 gpt-5.5를 우선 고려하세요. gpt-5.3-codex는 Codex의 에이전트형 코딩 시나리오에 특화되어 있습니다.

​
자주 쓰는 명령

Codex CLI에서 자주 쓰는 명령과 단축키:
명령설명
codex대화형 UI 실행
codex "작업 내용"초기 명령과 함께 시작
codex exec "작업 내용"비대화 모드. 실행 후 즉시 종료
codex --model gpt-5.4지정한 모델로 시작
codex --version버전 번호 확인
/model대화형 UI에서 모델 전환
/approvals대화형 UI에서 승인 모드 조정
Ctrl + C대화형 UI 종료

​
자주 묻는 질문

​
Q1: 실행 후 ChatGPT 로그인 화면이 떠요?

실행 후 “Sign in with ChatGPT” 같은 로그인 안내가 보인다면 설정이 적용되지 않은 것입니다. 점검 절차:
  1. config.toml과 auth.json이 모두 ~/.codex/ 안에 있는지 확인
  2. config.toml의 model_provider가 apimart로 설정되어 있는지 확인
  3. auth.json의 JSON 형식이 정확하고 키가 완전히 입력되었는지 확인

​
Q2: 401 / 403 오류가 발생해요?

상태 코드의미해결 방법
401 UnauthorizedAPI 키가 없거나 무효auth.json의 키가 올바르고 sk-로 시작하는지 확인
403 Forbidden권한 부족 또는 키 만료콘솔에서 키 상태 확인
또한 base_url이 https://api.apimart.ai/v1로 설정되어 있는지, OpenAI 공식 URL이 아닌지 확인하세요.

​
Q3: 연결이 실패해요?

  1. 네트워크 연결 상태 확인
  2. config.toml의 base_url 설정이 올바른지 확인
  3. 프록시를 사용 중이라면 api.apimart.ai 접근이 허용되어 있는지 확인

​
Q4: wire_api = "chat"이 더 이상 지원되지 않는다고 떠요?

최신 Codex CLI (0.84.0 이상)에서는 chat 프로토콜이 제거되었습니다. config.toml의 wire_api를 responses로 변경하세요: 
wire_api = "responses"
APIMart는 이미 Responses API를 제공하므로, 수정 후 Codex를 재시작하기만 하면 됩니다.

​
Q5: 도구 호출이나 실행이 실패해요?

config.toml의 wire_api가 responses로 설정되어 있는지 확인하세요. 호환성 이슈를 만나면 추천 GPT-5 시리즈 모델(예: gpt-5.5, gpt-5.3-codex)로 전환하는 것을 권장합니다. Codex CLI와의 궁합이 더 안정적입니다.

​
Q6: auth.json 대신 환경 변수를 쓰고 싶어요?

환경 변수로도 키를 설정할 수 있습니다. config.toml의 공급자 설정을 다음과 같이 바꾸세요: 
[model_providers.apimart]
name = "APIMart"
base_url = "https://api.apimart.ai/v1"
wire_api = "responses"
env_key = "APIMART_API_KEY"
그리고 환경 변수 APIMART_API_KEY를 APIMart 키로 설정하면 됩니다. 이 경우 auth.json은 필요 없습니다.

​
Q7: 모델은 어떻게 전환하나요?

두 가지 방법이 있습니다:
  1. 대화형 UI에서: /model 명령으로 전환
  2. 설정 수정: config.toml의 model 필드를 변경한 후 Codex CLI 재시작

​
Q8: 사용량과 비용은 어떻게 확인하나요?

APIMart 콘솔에 로그인하여 API 호출 통계, 토큰 소비 내역, 비용 추이를 확인하세요.

​
지원

사용 중 문제가 발생하면:

APIMart 시작하기

지금 바로 APIMart에 가입하고 API 키를 받아, Codex CLI에서 다중 모델 프로그래밍 어시스턴트를 경험해 보세요!