Codex CLI

Codex CLI는 CC Switch 원클릭 가져오기로 HiAPI에 연결하거나 직접 수동으로 설정(9단계)할 수 있습니다. 아래 단계는 gpt-6-astra를 예로 사용하며, HiAPI는 OpenAI Responses 프로토콜을 사용합니다. 이 튜토리얼은 Mac에서 Codex CLI 0.162.1로 검증했습니다. Mac 단계가 기본 경로이며 Windows 단계는 따로 정리했습니다. 이미 설치한 소프트웨어는 건너뛰어도 됩니다.

1. Node.js 설치

Node.js 설치에 설명된 대로 LTS 22.19 이상을 설치하고, 이미 있다면 건너뛰세요. 그런 다음 터미널에서 아래 두 명령을 실행하세요. 버전 번호가 보이면 충분합니다:

node --version
npm --version

2. Codex CLI 설치

방금 연 터미널에서 각 줄을 실행하세요:

npm install -g @openai/codex
codex --version

codex-cli 버전 번호가 보이면 충분합니다. 수동 설정(9단계)에는 0.134 이상이 필요합니다. Windows PowerShell에서는 npm.cmd install -g @openai/codex와 codex.cmd --version을 사용하세요.

3. CC Switch 설치 및 열기

CC Switch 설치 및 원클릭 가져오기에 설명된 대로 CC Switch를 내려받아 설치하고 엽니다. 이미 있다면 열기만 하세요.

이미 공급자가 있다면 먼저 Codex 페이지에서 “In use”로 표시된 카드의 이름을 기록해 두고, 필요할 때 기존 설정 백업에 설명된 대로 SQL 백업을 내보내세요.

4. HiAPI API 키 선택

API 키 발급받기에 설명된 대로 키를 선택하거나 만들고 이름을 기록하세요. 여기서는 키를 복사할 필요가 없습니다. 가져오기가 키를 함께 전달합니다.

5. 웹에서 원클릭 가져오기 준비

1. HiAPI Codex 연결 페이지를 열고 API Key setup → Codex → Command line → gpt-6-astra → macOS를 선택합니다. Windows에서는 시스템으로 Windows를 선택하세요.

2. Import to CC Switch를 클릭하고 API Key 드롭다운에서 기록한 키 이름을 고른 뒤, 하단에 **Responses API · https://api.hiapi.ai/v1**이 표시되는지 확인합니다.

3. Prepare import를 클릭한 다음 Open CC Switch를 클릭하고, 브라우저가 물으면 허용합니다.

각 단계의 스크린샷은 연결 페이지에서 가져오기 준비에 있습니다.

6. CC Switch에서 가져오기 확인

“Confirm provider import” 창에서 아래 항목을 확인하고 Switch to this provider immediately after import를 끈 상태로 두었다가 Import를 클릭합니다:

CC Switch의 Codex 페이지로 돌아왔을 때 HiAPI - gpt-6-astra 카드가 있으면 가져오기가 성공한 것입니다(아직 활성화되지는 않음). 스크린샷은 CC Switch에서 가져오기 확인을 참고하세요.

7. HiAPI 활성화

1. 먼저 Codex에서 실행 중인 작업이 끝날 때까지 기다리세요. CC Switch의 Codex → Direct 페이지에서 HiAPI - gpt-6-astra 카드의 Switch / Enable 버튼을 클릭합니다. 카드에 “In use”가 표시되어야 HiAPI가 활성화된 것입니다. 스크린샷은 HiAPI 활성화를 참고하세요.
2. 새 설정이 적용되도록 Codex를 완전히 종료했다가 다시 엽니다. CLI와 Desktop은 로컬 Codex 설정을 공유할 수 있습니다. 나중에 원래 공급자로 돌아가려면 여기서 해당 카드로 전환하고 클라이언트를 다시 여세요.

8. Codex 열기, 모델 선택 후 시작

1. 새 터미널을 열고 사용할 프로젝트 폴더로 이동하거나, 빈 폴더를 먼저 만드세요:

mkdir -p "$HOME/hiapi-project"
cd "$HOME/hiapi-project"
codex

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\hiapi-project"
Set-Location "$env:USERPROFILE\hiapi-project"
codex.cmd

2. 처음 실행 시 디렉터리를 신뢰할지 물으면 방금 선택한 폴더 경로가 맞는지 확인한 뒤 안내에 따라 확인하고 기본 권한을 유지하세요. 원클릭 가져오기를 사용했다면 codex를 바로 실행하고, 수동 설정에 쓰는 --profile hiapi는 붙이지 마세요.

3. Codex 입력 상자에 /model을 입력하고 Enter를 누릅니다. 화살표 키로 GPT-6 Astra / gpt-6-astra를 선택하고 Enter를 누르세요. 사고 수준(thinking level)을 묻는다면 하나를 선택해 확인한 뒤 Esc를 눌러 돌아갑니다.

① 화살표 키로 GPT-6-Astra를 선택합니다. ② Enter를 눌러 확인합니다.

4. “안녕하세요, 한 문장으로 자기소개를 해 주세요.”를 보내세요. 정상적으로 답하면 연결이 된 것입니다. HiAPI 콘솔의 요청 로그에 이 요청이 보이면 HiAPI를 거쳐 가는 것입니다. 이후에는 하고 싶은 작업을 입력 상자에 적으면 됩니다.

9. 수동 설정(CC Switch 없이)

원클릭 가져오기를 사용했다면 이 단계는 건너뛰세요. 수동 설정은 Codex CLI에만 해당하며 Codex Desktop에는 적용되지 않습니다.

1. Mac에서는 터미널에서 아래 세 줄을 실행하세요. 같은 이름의 파일이 이미 있으면 먼저 자동으로 백업됩니다:

mkdir -p "$HOME/.codex"
if [ -f "$HOME/.codex/hiapi.config.toml" ]; then cp "$HOME/.codex/hiapi.config.toml" "$HOME/.codex/hiapi.config.toml.bak-$(date +%Y%m%d-%H%M%S)"; fi
nano "$HOME/.codex/hiapi.config.toml"

2. 새 파일이라면 아래 내용을 모두 붙여 넣으세요. 파일이 이미 있으면 같은 이름의 필드와 테이블만 갱신하고 나머지는 유지하며 중복해서 추가하지 마세요. 최상위 필드는 [model_providers.hiapi] 앞에 와야 합니다. env_key = "HIAPI_API_KEY"는 Codex가 환경 변수를 읽는 방식이므로 그대로 두세요.

model_provider = "hiapi"
model = "gpt-6-astra"

[model_providers.hiapi]
name = "HiAPI"
base_url = "https://api.hiapi.ai/v1"
env_key = "HIAPI_API_KEY"
requires_openai_auth = false
wire_api = "responses"

3. Ctrl+O → Enter → Ctrl+X를 눌러 저장하고 종료합니다. 파일 이름은 반드시 hiapi.config.toml이어야 하며 .toml.txt가 되면 안 됩니다. CODEX_HOME을 설정했다면 그 디렉터리에 파일을 저장하세요.

4. HiAPI 콘솔 → API Keys로 돌아가 키 옆의 복사 아이콘을 클릭하고 전체 HiAPI API 키를 복사하세요. Codex를 시작할 같은 터미널에서 아래 명령을 실행하고(YOUR_HIAPI_API_KEY를 자신의 HiAPI API 키로 바꾸고 따옴표는 유지), 프로젝트 디렉터리로 이동해 시작하세요:

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex --profile hiapi

5. Windows에서는 PowerShell로 $env:USERPROFILE\.codex 디렉터리를 만들고, 메모장에서 hiapi.config.toml을 열어 같은 TOML을 붙여 넣으세요. 기존 파일은 먼저 백업합니다. Save as에서 “All files”와 UTF-8을 선택하고 .txt 확장자가 붙지 않았는지 확인하세요. 같은 PowerShell 창과 프로젝트 디렉터리에서 실행합니다:

$env:HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex.cmd --profile hiapi

환경 변수는 현재 터미널에만 적용됩니다. 터미널을 닫은 뒤에는 다시 설정하세요. 시작한 뒤에는 8단계와 같이 모델을 선택하세요.

문제 해결

여기에는 Codex CLI에 특화된 문제만 정리했습니다. 401, 404, 429 같은 일반적인 오류는 자주 발생하는 오류를 참고하세요.