Codex 설치는 어렵지 않지만, 실제로 쉽게 막히는 부분은 연동입니다: API Key를 어디에 두는지, config.toml을 어떻게 작성하는지, Windows와 macOS의 차이점은 무엇인지, VS Code가 왜 터미널의 변수를 읽지 못하는지, 모델을 고정해야 하는지……

Codex를 최대한 빨리 실행하고 싶다면, 구성을 세 가지 값으로 정리할 수 있습니다:

Provider: acedatacloud
Base URL: https://api.acedata.cloud/v1
API Key env: ACEDATACLOUD_API_KEY

완료 후 Codex CLI, Desktop 및 VS Code 확장은 ~/.codex/config.toml을 공유할 수 있으며, 모델은 시작 후 바로 선택하면 되므로 모델을 바꾸기 위해 연동 구성을 계속 수정할 필요가 없습니다.

아래에서 처음부터 한 번의 구성을 완료합니다.

준비 작업

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

  • Ace Data Cloud에 등록하고 로그인함
  • 사용 가능한 애플리케이션을 생성했거나 보유함
  • 로컬 컴퓨터에 Node.js와 npm이 설치됨
  • 터미널 또는 PowerShell을 사용할 수 있음
  • Codex CLI, Codex Desktop 또는 VS Code 확장 중 적어도 하나를 사용할 준비가 됨

첫 번째 단계: Ace Data Cloud API Key 가져오기

Ace Data Cloud 애플리케이션 목록을 열고, 사용 가능한 애플리케이션에 들어가 API Key를 복사합니다.

다음 사항에 유의하세요:

  • API Key는 민감한 자격 증명이므로 공개 저장소에 작성하지 마세요
  • 실제 Key를 튜토리얼 스크린샷에 넣지 마세요
  • 환경이나 용도별로 자격 증명을 따로 생성하고 관리하는 것을 권장합니다
  • 유출이 의심되면 즉시 교체하거나 취소해야 합니다

이 글에서는 환경 변수 ACEDATACLOUD_API_KEY를 일관되게 사용하여 평문 자격 증명을 Codex 구성 파일에 직접 작성하지 않습니다.

두 번째 단계: Codex CLI 설치

npm을 사용하여 Codex를 전역 설치합니다:

npm install -g @openai/codex

설치 후 확인합니다:

codex --version

명령을 찾을 수 없다는 메시지가 표시되면, 먼저 npm 전역 실행 파일 디렉터리가 PATH에 추가되어 있는지 확인한 후 터미널을 다시 여세요.

주로 VS Code를 사용하는 경우 OpenAI에서 배포한 Codex 확장도 설치할 수 있습니다:

code --install-extension openai.chatgpt

CLI와 VS Code 확장은 구성 파일을 공유하므로, 먼저 Provider와 환경 변수를 구성한 다음 편집기를 시작하여 검증하는 것을 권장합니다.

세 번째 단계: API Key 환경 변수 설정

macOS / Linux: 현재 터미널 세션

export ACEDATACLOUD_API_KEY="你的 API Key"

이 명령은 현재 Shell 및 그 하위 프로세스에만 적용됩니다. 터미널을 닫으면 변수가 사라집니다.

macOS / Linux: 장기 적용

Zsh를 사용하는 경우:

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

Bash를 사용하는 경우:

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.bashrc
source ~/.bashrc

공유 컴퓨터에서 실제 Key가 포함된 Shell 구성을 무작정 복사하지 마세요. 팀 환경에서는 자격 증명 관리 도구 및 최소 권한 정책과 함께 사용해야 합니다.

Windows PowerShell

setx ACEDATACLOUD_API_KEY "你的 API Key"

실행 후 PowerShell을 닫고 다시 여세요. setx는 현재 열려 있는 프로세스를 자동으로 업데이트하지 않으므로, 기존 터미널과 VS Code는 여전히 새 값을 읽지 못할 수 있습니다.

현재 PowerShell 세션에서만 임시로 설정하려면:

$env:ACEDATACLOUD_API_KEY="你的 API Key"

네 번째 단계: config.toml 생성 또는 편집

Codex CLI, Desktop 및 VS Code 확장은 다음 구성 파일을 공유합니다:

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

디렉터리가 없으면 먼저 생성하세요.

macOS / Linux:

mkdir -p ~/.codex

그다음 다음 내용을 작성합니다:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "sh"
args = ["-c", "echo $ACEDATACLOUD_API_KEY"]

Windows는 동일한 Provider와 Base URL을 사용하지만, 인증 명령을 PowerShell로 변경합니다:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:ACEDATACLOUD_API_KEY"]

구성의 세 가지 이름은 반드시 엄격하게 일치해야 합니다:

  • model_provider = "acedatacloud"
  • [model_providers.acedatacloud]
  • [model_providers.acedatacloud.auth]

Base URL도 /v1을 완전하게 포함해야 합니다.

다섯 번째 단계: Codex 시작 및 모델 선택

구성을 저장한 후 터미널을 다시 열고 실행합니다:

codex

Codex에 진입한 후 실행합니다:

/model

현재 Provider가 acedatacloud인지 확인한 다음, 사용 가능한 목록에서 모델을 선택합니다.

연동 구성에서 model을 고정할 필요는 없습니다. Provider와 모델 선택을 분리하면 모델 전환 시 TOML을 반복해서 편집하는 비용을 줄일 수 있습니다. 실제 모델 종류와 사용 가능 범위는 업데이트될 수 있으므로 /model 및 플랫폼의 실시간 목록을 기준으로 해야 합니다.

여섯 번째 단계: 최소 요청으로 검증

처음부터 Codex에 전체 저장소 리팩터링을 요청하지 마세요. 먼저 결과를 빠르게 판단할 수 있는 간단한 요청을 보내세요. 예를 들면 다음과 같습니다:

请概括当前项目的目录结构，不要修改任何文件。

그런 다음 Ace Data Cloud Usage History를 열어 요청이 도착했는지 확인하고, 상태 및 사용량을 확인하세요.

최소 요청이 성공하면 파일 읽기, 수정 방안 생성, 코드 편집 및 테스트 실행을 단계적으로 시도하세요.

VS Code 구성 핵심 사항

VS Code 확장은 동일한 ~/.codex/config.toml을 읽지만, API Key를 볼 수 있는지는 확장 실행 프로세스의 환경에 따라 달라집니다.

구성 후 VS Code를 완전히 종료하고 다시 여세요. macOS / Linux에서 그래픽 인터페이스로 시작한 후에도 변수를 읽지 못한다면, 이미 Key가 설정된 터미널에서 다음을 실행할 수 있습니다:

code .

다음 환경을 사용하는 경우 확장이 실제로 실행되는 쪽에서 변수를 구성해야 합니다:

  • Remote SSH: 원격 호스트
  • WSL: WSL Linux 환경
  • Dev Container: 컨테이너 환경
  • Codespaces 또는 유사한 원격 환경: 해당 원격 세션

로컬 Shell에서만 변수를 설정하는 것으로는 원격 확장이 자동으로 이를 얻는다고 보장할 수 없습니다.

Codex Desktop 구성 핵심 사항

Desktop은 CLI와 구성 파일을 공유하지만, 그래픽 애플리케이션은 터미널에서 임시로 실행한 export를 반드시 상속하는 것은 아닙니다.

Desktop이 Key를 읽지 못하는 경우:

  1. 환경 변수를 장기 또는 시스템 수준으로 설정합니다
  2. Desktop을 완전히 종료합니다
  3. 애플리케이션을 다시 시작합니다
  4. Provider와 모델을 다시 확인합니다

일반적인 오류 해결

1. 401, Unauthorized 또는 Incorrect API Key

확인 순서:

  1. API Key가 완전하게 복사되었는지
  2. 환경 변수 이름이 ACEDATACLOUD_API_KEY인지
  3. 현재 프로세스가 변수를 설정한 후 시작되었는지
  4. auth.command가 현재 운영 체제에 맞는지
  5. 자격 증명이 아직 유효한지 전체 Key를 로그나 채팅에 출력하지 마세요. 변수는 “존재 여부”만 판단하는 방식으로 확인할 수 있습니다.

macOS / Linux:

if [ -n "$ACEDATACLOUD_API_KEY" ]; then echo "Key is set"; else echo "Key is missing"; fi

PowerShell:

if ($env:ACEDATACLOUD_API_KEY) { "Key is set" } else { "Key is missing" }

2. Provider가 acedatacloud로 변경되지 않음

구성 파일 경로와 TOML 계층을 확인하세요. 일반적인 오류는 다음과 같습니다:

  • 파일 이름을 config.toml.txt로 작성함
  • 다른 사용자 디렉터리를 편집함
  • 테이블 이름의 철자가 일치하지 않음
  • 따옴표 또는 배열 형식 오류
  • 저장 후 클라이언트를 다시 시작하지 않음

3. Base URL 요청 실패

주소가 다음인지 확인하세요:

https://api.acedata.cloud/v1

https:// 또는 끝의 /v1을 빼먹지 말고, 콘솔 페이지 주소를 잘못 사용하지도 마세요.

4. CLI는 작동하지만 VS Code는 작동하지 않음

이는 일반적으로 Provider 구성 문제가 아니라 VS Code 프로세스가 환경 변수를 읽지 못하는 문제입니다. 변수가 설정된 터미널에서 code .를 시작하거나, 시스템 수준 변수를 구성한 후 VS Code를 완전히 다시 시작하세요.

5. WSL, SSH 또는 컨테이너에서 Key를 읽을 수 없음

환경 변수는 Codex 또는 확장이 실제로 실행되는 환경에 설정해야 합니다. Windows 호스트의 setx는 WSL에 자동으로 기록되지 않으며, 로컬 변수도 원격 SSH 호스트나 컨테이너에 자동으로 전달되지 않습니다.

6. 사용하려는 모델을 찾을 수 없음

이전 모델 ID를 수동으로 추측하지 마세요. /model을 실행하여 실시간 선택 가능 항목을 확인하고, 애플리케이션 권한, 잔액 및 현재 Provider를 점검하세요.

7. 요청은 도착하지만 복잡한 작업을 완료할 수 없음

먼저 작업 범위를 줄이세요: Codex가 읽기 전용으로 분석하고 계획을 나열하도록 한 다음, 단계적으로 수정과 테스트를 허용하세요. 모델 연결이 성공했다고 해서 모든 리포지터리 작업을 한 번에 완료해야 한다는 의미는 아닙니다. 복잡한 변경에는 여전히 명확한 승인 기준, 테스트 및 수동 검토가 필요합니다.

권장 구성 확인 목록

첫 번째 정식 작업을 제출하기 전에 항목별로 확인하세요:

  • 애플리케이션 목록에서 유효한 API Key를 가져옴
  • Key가 ACEDATACLOUD_API_KEY에 저장됨
  • Key를 Git 리포지터리에 작성하지 않음
  • model_provider가 acedatacloud임
  • Base URL이 https://api.acedata.cloud/v1임
  • auth.command가 운영 체제와 일치함
  • Codex 또는 VS Code를 완전히 다시 시작함
  • /model에서 Provider와 모델을 볼 수 있음
  • 최소 테스트 요청이 성공함
  • Usage History에서 해당 호출 기록을 볼 수 있음

하나의 Provider로 중복 구성 줄이기

이 연결 방식의 핵심은 TOML을 한 줄 더 작성하는 것이 아니라 안정적인 경계를 구축하는 것입니다:

  • API Key는 환경 변수로 관리
  • Provider 연결은 config.toml로 관리
  • 모델은 Codex 내에서 작업에 따라 선택
  • 호출 기록과 사용량은 Ace Data Cloud 콘솔에서 통합 확인
  • CLI, Desktop 및 VS Code는 하나의 구성을 공유

인증, Provider 및 모델 선택이 명확히 분리되면 많은 “Codex가 왜 또 작동하지 않지” 문제를 빠르게 파악할 수 있으며, 반복해서 로그인하거나 재설치하거나 여러 구성 사본을 복사할 필요가 없습니다.

Codex 구성 센터를 열어 다양한 클라이언트의 공식 가이드를 확인하거나, 애플리케이션 목록으로 이동하여 API Key를 가져오세요.

참고 자료