Codex CLI에서 OneAster 사용하기

소개

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

준비 사항

시작하기 전에 다음을 확인하세요:

Node.js 설치 완료 Node.js 공식 사이트에서 다운로드하여 설치하세요 (최신 LTS, v20 이상 권장). npm으로 Codex CLI를 설치하기 위해 필요합니다
OneAster API 키 획득 완료 OneAster 콘솔에 로그인하여 API 키를 받으세요 (sk-로 시작)

팁: OneAster 계정이 없으시다면 먼저 OneAster에서 가입하고 API 키를 받으세요.

1단계: Codex CLI 설치

다음 방법 중 하나를 선택해 설치하세요:

npm (권장)
Homebrew (macOS)

npm으로 전역 설치합니다. 모든 운영체제에 적용됩니다:

npm install -g @openai/codex

권한 문제가 발생하면 명령 앞에 sudo를 붙이세요 (macOS / Linux).

macOS 사용자는 Homebrew로도 설치할 수 있습니다:

brew install codex

설치 확인

설치 후 다음 명령으로 정상 설치 여부를 확인합니다:

codex --version

버전 번호가 출력되면 설치 성공입니다.

2단계: OneAster API 설정

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

2.1 설정 디렉터리 위치

macOS / Linux: ~/.codex/
Windows: C:\Users\<사용자명>\.codex\

디렉터리가 없다면 터미널에서 codex를 한 번 실행한 뒤 Ctrl + C로 종료하세요. 자동으로 생성됩니다.

2.2 API 키 설정

설정 디렉터리에 auth.json 파일을 만들거나 열어 OneAster 키를 입력합니다:

{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxx"
}

필드	설명
`OPENAI_API_KEY`	본인의 OneAster API 키 (`sk-`로 시작)

2.3 모델 공급자 설정

설정 디렉터리에 config.toml 파일을 만들거나 열어 OneAster 공급자를 추가합니다:

# 기본 사용 모델
model = "gpt-5.5"
# 기본 공급자 — 아래 [model_providers.oneaster]와 매칭
model_provider = "oneaster"

# oneaster 공급자 설정
[model_providers.oneaster]
name = "oneaster"
base_url = "https://api.oneaster.ai/v1"
wire_api = "responses"
requires_openai_auth = true

필드	설명
`model`	기본 모델 ID. 아래 모델 목록에서 선택
`model_provider`	기본 공급자. `[model_providers.xxx]`의 ID와 일치해야 함
`name`	공급자 표시 이름. 자유롭게 지정 가능
`base_url`	OneAster의 OpenAI 호환 주소. `https://api.oneaster.ai/v1`로 고정
`wire_api`	통신 프로토콜. 최신 Codex는 `responses` (Responses API) 사용 필요
`requires_openai_auth`	`true`로 설정하면 `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-codex`	Codex에 최적화된 코딩 모델	에이전트형 코딩 작업
`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” 같은 로그인 안내가 보인다면 설정이 적용되지 않은 것입니다. 점검 절차:

config.toml과 auth.json이 모두 ~/.codex/ 안에 있는지 확인
config.toml의 model_provider가 oneaster로 설정되어 있는지 확인
auth.json의 JSON 형식이 정확하고 키가 완전히 입력되었는지 확인

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

상태 코드	의미	해결 방법
`401 Unauthorized`	API 키가 없거나 무효	`auth.json`의 키가 올바르고 `sk-`로 시작하는지 확인
`403 Forbidden`	권한 부족 또는 키 만료	콘솔에서 키 상태 확인

또한 base_url이 https://api.oneaster.ai/v1로 설정되어 있는지, OpenAI 공식 URL이 아닌지 확인하세요.

Q3: 연결이 실패해요?

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

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

최신 Codex CLI (0.84.0 이상)에서는 chat 프로토콜이 제거되었습니다. config.toml의 wire_api를 responses로 변경하세요:

wire_api = "responses"

OneAster는 이미 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.oneaster]
name = "oneaster"
base_url = "https://api.oneaster.ai/v1"
wire_api = "responses"
env_key = "oneaster_API_KEY"

그리고 환경 변수 oneaster_API_KEY를 OneAster 키로 설정하면 됩니다. 이 경우 auth.json은 필요 없습니다.

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

두 가지 방법이 있습니다:

대화형 UI에서: /model 명령으로 전환
설정 수정: config.toml의 model 필드를 변경한 후 Codex CLI 재시작

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

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

지원

사용 중 문제가 발생하면:

OneAster 시작하기

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

​소개

​준비 사항

​1단계: Codex CLI 설치

​설치 확인

​2단계: OneAster API 설정

​2.1 설정 디렉터리 위치

​2.2 API 키 설정

​2.3 모델 공급자 설정

​3단계: 시작하기

​설정 확인

​대화형 모드

​승인 모드

​모델 전환

​지원 모델

​자주 쓰는 명령

​자주 묻는 질문

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

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

​Q3: 연결이 실패해요?

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

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

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

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

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

​지원

OneAster 시작하기

소개

준비 사항

1단계: Codex CLI 설치

설치 확인

2단계: OneAster API 설정

2.1 설정 디렉터리 위치

2.2 API 키 설정

2.3 모델 공급자 설정

3단계: 시작하기

설정 확인

대화형 모드

승인 모드

모델 전환

지원 모델

자주 쓰는 명령

자주 묻는 질문

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

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

Q3: 연결이 실패해요?

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

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

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

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

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

지원