클라우드 네이티브 Codex CLI 빠른 시작 가이드

클라우드 네이티브 Codex CLI에 오신 것을 환영합니다! 이것은 공식 Codex 구성 구독 서비스를 기반으로 한 강력한 AI 프로그래밍 어시스턴트입니다.

시스템 요구사항

요구사항	세부사항
운영체제	macOS 12+, Ubuntu 20.04+/Debian 10+ 또는 WSL2를 통한 Windows 11
Git (선택사항, 권장)	2.23+ 내장 PR 도우미
메모리	최소 4 GB (8 GB 권장)

1. Codex CLI 설치

다음 중 하나를 선택:

npm(범용)

npm i -g @openai/codex
# 때때로 필요한 네이티브 패키지명:
# npm i -g @openai/codex@native
codex --version

Homebrew(macOS)

brew update
brew install codex
codex --version

codex가 실행되지 않거나 Node 버전이 오래된 경우 Node를 업그레이드(일반적으로 Node 22+ 필요)하거나 Homebrew 설치를 사용하세요.

---

2. GPTMeta Pro API 키 준비 및 Codex 설정

GPTMeta Pro API 계정 등록

1단계: 등록 페이지 방문

1. https://coultra.blueshirtmap.com에 방문
2. 등록 버튼을 클릭하여 새 계정 생성
3. 필요한 등록 정보 입력

2단계: API 키 생성

1. 로그인 성공 후 API 키 관리 페이지로 이동
2. 새 API 키 그룹 생성

3. 그룹 이름으로 "고속 안정 채널" 선택 4. API 키 생성 및 복사

Codex 설정

Codex는 시작 시 ~/.codex/에서 config.toml을 읽습니다. 없으면 새로 만듭니다:

mkdir -p ~/.codex
nano ~/.codex/config.toml

config.toml에 다음을 추가(필요에 따라 수정):

# 상위 기본값
model = "gpt-4o"            # GPTMeta Pro API에서 실제 사용 가능한 모델로 기입
model_provider = "coultra"  # 기본 provider 설정

[model_providers.coultra]
name = "GPTMeta Pro API (OpenAI-compatible)"
base_url = "https://coultra.blueshirtmap.com/v1"
env_key = "GPTMeta_Pro_API_키"    # API 키를 직접 입력
wire_api = "chat"           # OpenAI Chat Completions 프로토콜 사용

# 선택: 명령행에서 빠르게 전환할 수 있도록 profile 정의
[profiles.coultra]
model_provider = "coultra"
model = "gpt-4o"
approval_policy = "on-request"      # 필요 시 실행 여부 질문
sandbox_mode = "workspace-write"    # 현재 프로젝트에 파일 쓰기 허용, 여전히 오프라인

핵심 필드 설명:

• model / model_provider: 기본 모델과 기본 제공자.
• [model_providers.<id>].base_url: 서비스 /v1 루트; Codex는 Chat Completions 와이어 프로토콜로 상호작용(통상 POST {base_url}/chat/completions).
• env_key: 어떤 환경 변수에서 자격 증명을 가져올지 지정.
• wire_api: 와이어 프로토콜 유형; Chat Completions 호환은 "chat".
• profiles.* 및 --profile: 설정 묶음을 만들어 실행 시 빠르게 전환.

---

3. 실행 및 검증

현재 터미널에 COULTRA_API_KEY가 설정되어 있는지 확인(2단계 참조), 그런 다음:

# profile로 실행
codex --profile coultra "현재 저장소 구조를 한국어로 설명해줘"

# 또는 기본값으로 실행(이미 provider가 coultra로 설정됨)
codex "API에서 데이터를 가져와 CSV로 저장하는 Python 스크립트를 생성해줘"

실행 중 Codex는 로컬 샌드박스에서 "코드 보기, 파일 수정, 명령 실행"을 수행합니다. 권한이 필요하면 approval_policy에 따라 확인을 요청합니다. workspace-write는 프로젝트 디렉터리 내에서만 파일 쓰기를 허용하며, 여전히 오프라인입니다.

---

4. 샌드박스 / 승인 정책 빠른 참고

• 승인 정책:

  • --ask-for-approval 또는 approval_policy 설정으로 상호작용 정도를 제어.
  • --full-auto는 편의 플래그(방해가 적고, 여전히 샌드박스 내).

• 샌드박스 수준:

  • read-only: 읽기 전용(파일 쓰기 불가, 오프라인)
  • workspace-write: 현재 프로젝트 디렉터리 내 쓰기 가능, 오프라인 유지
  • danger-full-access: 비권장, 샌드박스 해제와 동일
  • CLI에서는 --sandbox MODE, 설정에서는 sandbox_mode="MODE" 사용.

일시적으로 네트워크가 필요합니까? 현재 버전은 "기본 오프라인" 보안 전략을 중시합니다. "위험" 모드 또는 향후 네트워크 허용 옵션은 신중히 사용하세요.

---

5. 자주 묻는 질문(FAQ)

① 401/403: API 키가 유효하지 않거나 잔액 부족

• GPTMeta Pro API 대시보드에서 키를 다시 생성; COULTRA_API_KEY가 현재 세션에서 유효한지 확인(echo $COULTRA_API_KEY).
• CI에서 Secrets로 환경 변수를 주입하여 하드코딩을 피하세요.

② 404 / "Resource not found": base_url이 잘못됨

• 대부분의 호환 구현은 base_url이 **…/v1**를 가리켜야 합니다. 일부 플랫폼(예: Azure)은 추가 경로가 필요하며, 경로가 불완전하면 404가 발생합니다.

③ --profile이 적용되지 않거나 일부 키가 로드되지 않음

• 최신 버전으로 업그레이드; 구버전에는 profile 관련 일부 키 로딩 문제의 알려진 이슈가 있습니다.

④ NPM 설치 후 codex 사용 불가 또는 버전 불일치

• Node 업그레이드(권장 22+), 또는 Homebrew 설치 사용; 최근 버전은 npm 패키지와 동작이 변경되었습니다.

⑤ 로컬/서드파티 provider에 연결 불가 또는 포트 오류

• base_url이 올바른지 확인; 초기 버전의 base_url/포트 관련 버그는 업그레이드로 해결할 수 있습니다.

---

6. 바로 재사용 가능한 최소 실행 구성(MVP)

# ~/.codex/config.toml
model = "gpt-4o"
model_provider = "coultra"

[model_providers.coultra]
name = "GPTMeta Pro API (OpenAI-compatible)"
base_url = "https://coultra.blueshirtmap.com/v1"
env_key = "GPTMeta_Pro_API_키"    # API 키를 직접 입력
wire_api = "chat"

[profiles.coultra]
model_provider = "coultra"
model = "gpt-4o"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

시작 명령:

export COULTRA_API_KEY="당신의_키"
codex --profile coultra "이 저장소에 CLI 하위 명령을 추가해줘"

---

7. 고급 사용 팁

CLI 참고

명령어	목적	예시
codex	대화형 TUI	codex
codex "..."	초기 프롬프트가 있는 대화형 TUI	codex "fix lint errors"
codex exec "..."	비대화형 "자동화 모드"	codex exec "explain utils.ts"

비대화형/CI 모드

파이프라인에서 Codex를 헤드리스로 실행합니다. 예시 GitHub Action 단계:

- name: Update changelog via Codex
  run: |
    npm install -g @openai/codex
    export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
    codex exec --full-auto "update CHANGELOG for next release"

모델 컨텍스트 프로토콜 (MCP)

~/.codex/config.toml에서 mcp_servers 섹션을 정의하여 Codex CLI를 MCP 서버를 사용하도록 구성할 수 있습니다. 이는 Claude 및 Cursor와 같은 도구가 각각의 JSON 구성 파일에서 mcpServers를 정의하는 방식을 반영하도록 설계되었지만, Codex는 JSON이 아닌 TOML을 사용하므로 형식이 약간 다릅니다. 예:

# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
[mcp_servers.server-name]
command = "npx"
args = ["-y", "mcp-server"]
env = { "API_KEY" = "value" }