ChatGPT / Codex 설정

Codex는 OpenAI 공식 CLI AI 코딩 어시스턴트입니다. 4AICode API로 연결하면 키·팀 할당량·사용량을 한 콘솔에서 관리하고, 실제 토큰 사용량 기준으로 과금됩니다.

💡 초보자 팁: **[방법 1: 연결 어시스턴트(GUI)]**부터 시작하는 것을 권장합니다. 명령 입력 없이 클릭 몇 번으로 설정할 수 있습니다.

사전 준비: 토큰 받기

어떤 방법이든 먼저 4AICode 토큰이 필요합니다.

1. 4AICode 로그인 후 대시보드 → 토큰 관리.
2. "New Token" 클릭.
3. 생성 문자열 복사(sk-4ai-<your-token> 형식).

⚠️ 중요:

• 토큰은 생성 시 한 번만 표시됩니다. 비밀번호 관리자·메모 앱에 저장.
• 가이드의 sk-4ai-<your-token>는 placeholder. 실제 토큰으로 교체.
• CLI 예제에서 꺾쇠와 placeholder 내용을 실제 토큰으로 바꾸세요.
• 비밀번호처럼 취급하고 공유·GitHub 커밋 금지.

방법 1: 연결 어시스턴트(초보자 권장)

4AICode 연결 어시스턴트는 MyGo 기반 네이티브 데스크톱 UI를 사용하며 터미널 명령이 필요 없습니다.

1. 연결 어시스턴트 다운로드

Windows 빌드는 아직 게시자 서명이 없어 첫 실행 시 SmartScreen이 뜰 수 있습니다. Defender 검증 진행 중. 다운로드 폴더에서 certutil -hashfile 4aicode-assistant-windows-amd64.exe SHA256(Windows) 실행 후 SHA256SUMS.txt 해당 줄 해시와 비교하세요.

macOS는 Developer ID 서명·Apple notarization 적용. DMG를 열어 Applications에 넣어 설치.

(체크섬: SHA-256 Checksums · 버전 정보)

다운로드 링크에 릴리스 버전이 표시됩니다. 업데이트 전 어시스턴트 시스템 트레이/메뉴 바에서 Quit; 창만 닫으면 백그라운드 실행 유지. 앱 교체 후 재실행하고 창 우측 상단 버전·빌드 ID를 다운로드 페이지와 비교하세요.

2. 3단계 설정

1. 계정 연결: 어시스턴트를 열고 sk-4ai-<your-token> 붙여넣기, Mainland China 또는 International 선택, 해당 라인 API에서 불러온 드롭다운에서 모델 선택 후 "Connect". 토큰·라인 변경 시 모델 목록 재로드; Refresh Models 로 재시도.
2. 설치 및 실행: "Select Project & Launch Codex" 클릭. Codex CLI가 없으면 선택한 디렉터리에서 실행 전 다운로드·설치. 다운로드 중 상태 메시지 표시; 완료까지 대기.
3. 상시 사용: 창을 닫아도 Windows는 시스템 트레이, macOS는 메뉴 바에 남아 빠르게 접근.

토큰은 시스템 자격 증명 관리자에 안전 저장. 입력 옆 눈 아이콘으로 표시/숨김. 연결 시 다시 숨김.

3. 공식 Windows 데스크톱 앱 연결

로컬 Codex는 API key 로그인을 지원하며 4AICode 잔액을 직접 사용할 수 있습니다.

1. 어시스턴트에서 모델 선택 후 연결. 모델 목록은 휠·키보드 선택 지원.
2. Copy Desktop Login Key 클릭. 데스크톱 제공자 설정 준비 후 로컬 연결 키 복사.
3. 공식 ChatGPT / Codex 데스크톱 앱 완전 종료 후 재실행. Sign in another way → API key → OpenAI API key에 붙여넣기.
4. 어시스턴트를 켜 둔 채 새 로컬 작업 시작. 모델·라인 변경 후 데스크톱 앱 재시작.

두 앱은 동일 Windows 사용자·Codex 설정 디렉터리(보통 %USERPROFILE%\.codex) 사용. CODEX_HOME 설정 시 양쪽 동일 경로.

config.toml은 로컬 연결 키가 있어 비공개 취급. 문제 공유 시 자격 증명 가림. Restore Original Configuration은 어시스턴트 데스크톱 로그인 모드 종료.

복사한 키는 로컬 어시스턴트에 연결; 4AICode 토큰은 시스템 자격 증명 금고에 유지. ChatGPT로 이미 로그인한 사용자는 로그인 유지 후 이 버튼·앱 재시작 가능. API-key 모드는 로컬 Codex 작업용. ChatGPT 웹·workspace·클라우드 기능은 각 공식 계정 권한. 공식 인증 문서

데스크톱 오류: Model provider fouraicode_assistant not found

데스크톱 앱이 로드한 설정에 어시스턴트 제공자 정의가 없음:

1. 트레이에서 구 어시스턴트 종료, 최신 버전 다운로드, Connect. 연결 표시면 Disconnect 후 재연결. v0.1.2부터 설정 주기 점검, 백업 소유 확인 시 재연결로 정의 복구 가능.
2. 공식 앱 완전 종료·재실행 후 해당 대화 열기.
3. 지속 시 동일 Windows 사용자·설정 디렉터리(CODEX_HOME 포함) 확인. 어시스턴트 버전·단계·설정 경로를 지원에 공유.

Restore Original Configuration 후 어시스턴트 대화를 이어가려면 재연결. 원래 제공자 사용 시 데스크톱 앱 재시작 후 새 작업.

연결 설정 변경

Reconfigure and Connect → Back Up and Connect 확인. 4AICode 전환 전 현재 설정·이전 백업 저장, project trust·MCP·다른 제공자 유지. 복원 시 전환 전 설정으로. 완료 후 데스크톱 앱 재시작.

연결 실패

메시지별 조치: 타임아웃 재시도, 프록시 앱·포트 확인, 날짜·시간(인증서), 잘못된 모델 목록 새로고침. 지속적 서비스 오류는 지원 문의. 토큰·잔액·한도는 대시보드. 어시스턴트 버전·오류 메시지 공유; 설정 파일은 자격 증명 가림.

방법 2: CLI 설정(개발자용)

터미널 사용에 익숙하면 설치 명령과 원클릭 설정 스크립트 실행. 약 2분.

# Option A: via npm (recommended, requires Node.js 16+)
npm install -g @openai/codex

# Option B: via Homebrew (macOS only)
brew install --cask codex

# International route (recommended)
export RELAY4AI_BASE_URL=https://relay.4aicode.com/v1
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s install 'sk-4ai-<your-token>'

# Mainland China direct route (.net)
curl -fsSL https://4aicode.net/codex-setup.sh | bash -s install 'sk-4ai-<your-token>'

codex

일반 작업

1. 모델 및 Reasoning effort 전환

어시스턴트: Disconnect → 드롭다운에서 다른 모odel → 재연결 → Codex 재시작.

CLI 설정: 로컬 설정 파일 편집:

• macOS / Linux: ~/.codex/config.toml
• Windows: %USERPROFILE%\.codex\config.toml

다음 두 줄만 수정(다른 필드 유지):

model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"

Reasoning effort: low, medium, high, xhigh. Codex 재시작 후 적용.

2. 상태 확인 또는 설정 롤백

# Check current provider and model status
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s status

# Uninstall and restore pre-setup config
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s uninstall

문제 해결 및 FAQ

Q1: codex: command not found 또는 인식 안 됨?

• 원인: Codex CLI 미설치 또는 PATH 미갱신.
• 조치: 터미널 닫고 새로 열기. 지속 시 Node.js 확인 후 npm install -g @openai/codex 재실행.

Q2: 401 Unauthorized?

• 원인: 토큰 무효·폐기 또는 placeholder 미교체.
• 조치: sk-4ai-<your-token> 교체 여부 확인. 대시보드에서 새 토큰 후 설정 명령 재실행.

Q3: PowerShell 실행 정책 오류?

• 조치: 위 & ([scriptblock]::Create(...)) 사용 또는 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Q4: 설정·모델 변경이 적용 안 됨?

• 조치: Codex는 시작 시 설정 캐시. CLI/App 완전 종료 후 새 터미널에서 codex.

Q5: 공식 Codex 데스크톱 앱(Codex App)?

• 어시스턴트 연결 → Copy Desktop Login Key → 데스크톱 앱 완전 재시작 → API key 로그인·붙여넣기. 위 Windows 안내 참고.
• 공식 제공자로 복귀: 어시스턴트에서 원래 설정 복원. 로컬 키로 로그인했으면 데스크톱에서 로그아웃 후 공식 로그인 선택.

Q6: Windows PowerShell에서 한·중문 깨짐?

PowerShell 5.1은 다운로드 응답 charset으로 디코드. 서버는 UTF-8 선언. 캐시·프록시로 깨지면 Ctrl+C 후 UTF-8로 명시 다운로드:

$setupClient = New-Object System.Net.WebClient
$setupClient.Encoding = [System.Text.Encoding]::UTF8
try {
  $setupScript = $setupClient.DownloadString('https://4aicode.com/codex-setup.ps1')
} finally {
  $setupClient.Dispose()
}
& ([scriptblock]::Create($setupScript))

프롬프트에 토큰·모델 입력.

Q7: 시작 시 plan type is required for chatgpt authentication?

구 스크립트가 로그인 정보 없는 ChatGPT 인증 상태를 만들 수 있음. 최신 스크립트와 4AICode 토큰으로 install 재실행. 기본 API key 인증. 첫 설치 백업은 uninstall 시 복원 가능.

status는 설정 파일 확인. Codex 테스트 메시지로 연결 확인. .com·.net 릴레이 URL 모두 지원.

Q8: 재설치 후에도 workspace routing discovery unauthorized (401)?

공식 서비스가 ChatGPT 세션 workspace 정보 읽기 중 Codex 거부. 구 스크립트가 토큰·plan 필드로 로그인 자동 보존, 무효 세션에도 남을 수 있음. uninstall이 그 세션 복원, reinstall 시 다시 선택될 수 있음.

Windows PowerShell에서 최신 스크립트 받아 API key 인증 명시:

$setup = irm ("https://4aicode.com/codex-setup.ps1?v=" + [DateTimeOffset]::UtcNow.ToUnixTimeSeconds())
& ([scriptblock]::Create($setup)) install -AuthMode apikey
codex login status
codex

프롬프트에 4AICode 토큰 입력. codex login status는 API key 인증 표시. 릴레이 API key 모드는 공식 ChatGPT workspace 세션과 독립. 명시 chatgpt 모드는 유효 공식 로그인·workspace 필요.

기타 도구 및 SDK

다른 에디터·SDK는 표준 OpenAI 호환 매개변수로 4AICode ChatGPT 풀에 연결:

API 매개변수

• Base URL: https://relay.4aicode.com/v1(본토는 https://relay.4aicode.net/v1)
• API Key: 4AICode Token(sk-4ai-<your-token>)

Python SDK 예제

from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.com/v1",
    api_key="sk-4ai-<your-token>",  # 실제 토큰으로 교체
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Hello! Please write a quicksort algorithm."}],
)

print(response.choices[0].message.content)

cURL 예제

curl https://relay.4aicode.com/v1/chat/completions \
  -H "Authorization: Bearer sk-4ai-<your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "ping"}]
  }'

부록: 수동 고급 설정(참고)

💡 일반 사용자는 생략 가능. 설정 검토·수동 병합이 필요한 개발자용.

설정 파일 위치:

• macOS / Linux: ~/.codex/
• Windows: %USERPROFILE%\.codex\

1. auth.json

두 인증 방식 지원. 설정 스크립트 기본은 릴레이 API key:

• 기본 apikey: 아래처럼 auth_mode = "apikey"와 4AICode 토큰. 기존 ChatGPT 자격 증명은 첫 설치 백업에 유지.
• 명시 chatgpt: Windows install에 -AuthMode chatgpt, macOS/Linux는 install <Token> <model> <reasoning_effort> chatgpt. 원본 로그인 파일 보존·구조 검사. 공식 서비스가 세션·workspace 검증; 무효 시 codex login 갱신.

두 모드 모두 config.toml의 experimental_bearer_token으로 4AICode 릴레이 인증. 스크립트는 원본 파일 먼저 백업. auth.json, config.toml, 백업은 평문 자격 증명이므로 비밀번호 취급·git 제외·공유 시 가림:

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-4ai-<your-token>"
}

2. config.toml

4AICode를 model provider로 설정. cli_auth_credentials_store = "file"이면 설정 스크립트가 쓴 auth.json 사용:

model_provider = "OpenAI"
openai_base_url = "https://relay.4aicode.com/v1"
model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"
cli_auth_credentials_store = "file"

[model_providers.OpenAI]
name = "4aicode"
base_url = "https://relay.4aicode.com/v1"
wire_api = "responses"
experimental_bearer_token = "sk-4ai-<your-token>"
requires_openai_auth = true