연동 가이드

제공업체 연동 가이드

도구별 설정 단계 및 문제 해결 방법을 확인해 보세요.

제공업체 연동 가이드/Codex 클라이언트 설정 가이드

Codex 클라이언트 설정 가이드

Codex 클라이언트는 OpenAI의 데스크톱 애플리케이션입니다. ChatGPT 계정으로 직접 로그인하거나 API 키를 사용하여 로컬 Codex 워크플로를 실행할 수 있습니다. 초보자가 자주 혼동하는 부분: 공식 계정 로그인, OpenAI 공식 API 키, 중계 제공자 키(Proxy Key)는 서로 다른 개념입니다.

공식 정보 다운로드 및 문서는 공식 사이트 기준을 따릅니다.
공식 문서 Codex 공식 시작 페이지 인증 및 키 ChatGPT 로그인 및 API 키 로그인 기본 설정 config.toml, 모델 및 Provider Windows 클라이언트 Windows 다운로드 및 설치 안내

먼저 두 가지 로그인 방식을 구분하세요

이 페이지에서는 데스크톱 클라이언트의 키, 모델 및 Provider 관련 설정만 다룹니다. 명령줄 설치, 터미널 명령어 및 포괄적인 CLI 사용법은 CLI 도구 페이지를 참조하세요.

ChatGPT 로그인API 키 로그인config.toml모델 선택커스텀 Provider제공자 키
방식추천 대상키 처리 방법
ChatGPT 로그인ChatGPT Plus / Pro / Business / Enterprise 계정을 보유하고 있으며 공식 Codex를 바로 사용하려는 사용자.클라이언트 로그인 안내에 따라 로그인합니다. 일반적으로 API 키를 수동으로 입력할 필요가 없습니다.
OpenAI API 키 로그인OpenAI Platform 계정의 종량제(Pay-as-you-go)를 사용하거나 로컬 워크플로에 API 키가 필요한 사용자.중계 제공자 키가 아닌 OpenAI 콘솔에서 발급받은 키를 사용합니다.
제공자(Provider) / 프록시 서비스제공자가 자체 API 주소, 키 및 모델명을 제공하는 경우.공식 API 키 로그인 창에 무작정 입력하지 마세요. 일반적으로 config.toml을 통해 커스텀 Provider를 구성해야 합니다.
Windows 파일 탐색기의 Codex 설정 디렉터리: C: \Users\guoguo\. codex and config.toml

예시 경로: C: \Users\YourUsername\. codex

API 키 설정 방법

Codex의 로컬 설정 디렉터리 이름은 . codex입니다. Windows 클라이언트는 %USERPROFILE%\. codex, macOS / Linux는 일반적으로 ~/. codex를 사용합니다. ChatGPT로만 로그인하는 경우 키를 직접 입력할 필요가 없습니다. 중계 제공자나 타사 키를 사용하는 경우 시스템 환경 변수에 키를 등록하고 config.toml에서 이 변수를 읽도록 설정하는 것을 권장합니다.

운영체제설정 파일키 저장 위치
Windows%USERPROFILE%\. codex\config.toml사용자 환경 변수(예: MZ_PROXY_API_KEY).
macOS / Linux~/. codex/config.toml현재 터미널 환경 변수. 정상 작동을 확인한 후 시스템 설정 방식에 맞게 영구 저장합니다.
WSL~/. codex/config.tomlWSL은 독립된 홈 디렉터리를 사용하므로 Windows의 %USERPROFILE%\. codex를 자동으로 읽지 않습니다.
키 임시 테스트 아래는 현재 터미널 창에서만 임시로 유효한 명령어입니다. 실행이 성공적으로 확인되면 시스템 환경 변수나 셸 설정 파일에 영구 등록하세요.
PowerShell에서 임시 테스트
$env:MZ_PROXY_API_KEY = "YOUR_KEY"

실제 API 키를 웹 페이지, 스크린샷, 채팅 기록 또는 프로젝트 저장소에 노출하지 마세요. config.toml에 직접 키를 입력하는 대신 환경 변수를 사용하는 것이 안전합니다. Windows에서 영구 저장하려면 시스템 '환경 변수'에서 사용자 변수를 추가하고, macOS / Linux는 사용하는 셸 설정 파일에 추가하세요.

모델 설정 방법

기본 모델은 config.toml의 최상단에 지정합니다. 공식 문서에서는 현재 gpt-5.5부터 시작할 것을 권장합니다. 중계 제공자를 사용하는 경우 제공자 백엔드의 모델 목록에 명시된 API 호출용 문자열을 입력해야 합니다. 백엔드에서 'Model ID', 'Model Name' 등으로 표시될 수 있으며 대소문자, 하이픈, 점 기호까지 원본 그대로 정확히 복사해야 합니다.

모델 설정 예시
model = "gpt-5.5"
설정 항목입력 방법흔한 실수
model모델 ID / 모델명. 백엔드 모델 목록에 표기된 API 호출용 원본 식별자입니다.사용자가 임의로 지정한 표시용 이름 입력, 대소문자·하이픈·점 오기입.
model_provider아래에서 정의한 Provider ID를 선택합니다.Provider 테이블은 작성했으나 여기서 연결할 ID를 전환하지 않음.
openai_base_url내장 OpenAI Provider의 요청 URL만 변경할 때 사용합니다.커스텀 Provider와 혼용하여 요청이 엉뚱한 주소로 전송됨.
wire_api일반적으로 responses를 사용합니다.제공자가 Responses API를 지원하지 않는 경우 정상 작동하지 않을 수 있음.

중계 제공자(Provider) 설정 방법

제공자 설정의 핵심 3요소는 모델명, Base URL, 키 환경 변수입니다. 제공자가 OpenAI 호환 인터페이스를 지원하는 경우 Responses API를 우선 지원하도록 설정하세요. 구형 Chat Completions만 지원하는 제공자는 향후 호환성이 떨어질 수 있습니다.

Provider 설정 예시
model = "MODEL_ID_FROM_PROVIDER_DASHBOARD" model_provider = "mz_proxy" [model_providers.mz_proxy] name = "Example AI Provider" base_url = "https://YOUR_PROVIDER_API_URL" env_key = "MZ_PROXY_API_KEY" wire_api = "responses"
제공자의 자체 키를 사용하는 경우 '커스텀 Provider 예시'를 권장합니다. openai_base_url은 엔터프라이즈 프록시, 데이터 레지던시, 공식 OpenAI 포워딩 주소에만 사용하세요.
점검 항목올바른 방법잘못된 방법
Base URL제공자 백엔드에서 제공하는 API 주소를 복사합니다. /v1 포함 여부는 제공자 안내를 따릅니다.홈페이지 주소나 콘솔 대시보드 URL을 API 주소로 사용.
Key환경 변수 이름을 사용합니다(예: MZ_PROXY_API_KEY).프로젝트 파일에 키를 직접 작성하거나 스크린샷으로 공유.
Provider ID영문 식별자를 직접 생성합니다(예: mz_proxy).openai, ollama, lmstudio 등 예약된 ID를 사용.
모델 ID / 모델명백엔드 모델 목록에서 API 호출용 원본 식별자를 복사합니다.사용자 임의 명칭, 요금제 이름, 기억에 의존한 이름 입력.

클라이언트 설정에서 먼저 확인할 항목

Codex 클라이언트 설정을 열면 좌측에 'Personal, Integration, Coding, Archived' 그룹이 표시됩니다. 초보자는 일반(General) 설정부터 시작하여 작업 모드, 권한 범위, 기본 열기 대상, 터미널 및 언어를 확인하세요. 모델, 키 및 Provider 설정은 이전 단계의 config.toml에서 처리합니다.

Codex 앱의 일반 설정
설정 항목화면 설명초보자 팁
작업 모드 (Work mode)Codex 응답 시 기술적 세부 정보 표시 수준을 선택합니다. 개발/프로그래밍용은 코딩 및 제어에 집중하며, 일반 업무용은 기술적 세부 정보를 줄입니다.코드 작성이나 오류 해결 시에는 '개발/프로그래밍용', 텍스트 작성이나 내용 정리 시에는 '일반 업무용'을 선택하세요.
기본 권한 (Default permissions)Codex가 현재 워크스페이스 내 파일을 읽고 편집할 수 있도록 허용합니다. 워크스페이스 외부 접근 시에만 추가 권한을 요청합니다.기본값을 유지해도 좋습니다. 권한 승인 요청 시 대상 위치를 항상 확인하세요.
자동 검토 (Automatic review)Codex가 일부 추가 접근 요청을 자동으로 판단하지만 오류가 발생할 수 있습니다.익숙해지기 전까지는 비활성화하여 단계별로 직접 승인하고, 숙달된 후 필요에 따라 활성화하세요.
전체 접근 권한 (Full access)승인 없이 컴퓨터의 모든 파일을 편집하고 네트워크 명령을 실행할 수 있어 보안 위험이 큽니다.기본적으로 켜지 마세요. 결과를 완전히 이해하고 현재 작업에 반드시 필요한 경우에만 임시로 켜세요.
기본 열기 대상 (Default open target)파일이나 폴더를 열 때 기본으로 사용할 애플리케이션을 지정합니다. 스크린샷에는 Antigravity로 표시되어 있습니다.평소 사용하는 편집기나 워크스페이스를 선택하세요. 확실하지 않다면 현재 기본값을 유지하세요.
통합 터미널 셸 (Integrated Terminal Shell)Codex 통합 터미널에서 사용할 셸을 지정합니다(예: PowerShell, CMD, Git Bash).특정 터미널이 명시된 경우가 아니라면 Windows 초보자는 PowerShell을 우선 사용하는 것이 좋습니다.
언어 (Language)클라이언트 인터페이스 언어를 설정합니다. 스크린샷에는 자동 감지로 표시되어 있습니다.선호하는 언어나 자동 감지를 선택하세요.
하단 패널 / 기본 터미널 위치하단 패널 표시 여부 및 터미널 탭의 기본 위치(하단 또는 우측)를 설정합니다.화면 크기에 맞게 선택하세요: 노트북은 하단, 와이드 모니터는 우측이 편리합니다.
코드 리뷰 (Code Review)/review 실행 시 현재 대화에서 진행할지, 별도의 리뷰 대화로 분리할지 결정합니다.초보자는 맥락 파악이 용이한 '인라인 뷰(inline view)' 방식을 추천합니다.
추천 프롬프트 (Suggestion Prompt)프로젝트 파일 및 연결된 앱을 기반으로 다음 추천 작업을 제시합니다.활성화해 두어도 좋으며, 방해가 된다면 언제든 끌 수 있습니다.

검증 및 문제 해결

키, 모델 또는 Provider를 수정한 후 클라이언트를 재시작하고 새 테스트 대화를 만듭니다. 처음에는 파일을 수정하지 말고 현재 프로젝트와 모델이 정상 작동하는지 확인만 요청하세요.

최초 검증용 질문 템플릿
First state which files you can see. Do not modify files or run commands. Reply only with whether the current project is readable and the model ID or model name you are using.
현상주요 원인해결 방법
키 누락 또는 인증 실패 안내 발생환경 변수가 적용되지 않았거나 클라이언트를 재시작하지 않음.터미널/클라이언트를 다시 시작하세요. Windows의 경우 새 터미널 창에서 환경 변수를 확인하세요.
Model Unavailable (모델 사용 불가)모델 ID/모델명이 올바르지 않거나 제공자 측에서 해당 모델을 활성화하지 않음.제공자 백엔드의 모델 목록에서 원본 식별자를 다시 복사하세요.
404 / endpoint not foundBase URL 경로 오류. 주로 /v1이 중복되었거나 누락됨.추측하지 말고 제공자 문서를 확인하여 올바른 API 주소를 입력하세요.
요청이 공식 OpenAI로 전송됨커스텀 Provider ID로 전환하지 않았거나 부적절하게 openai_base_url을 사용함.model_provider 설정값이 본인이 지정한 Provider ID와 일치하는지 확인하세요.
WSL에서는 되지만 Windows 클라이언트에서 안 됨Windows와 WSL이 서로 다른 . codex 디렉터리를 참조함.클라이언트가 실제로 읽고 있는 설정 파일을 수정하고 있는지 확인하세요.
공식 ChatGPT 로그인만 사용하는 경우 제공자 키를 미리 설정할 필요가 없습니다. API 키, 엔터프라이즈 프록시 또는 타사 중계 제공자를 명시적으로 사용할 때만 config.toml을 수정하세요.

권한 및 보안

Codex 클라이언트는 사용자의 확인에 따라 프로젝트 파일을 읽고 수정하거나, 코드 검사를 실행하고 웹 페이지를 열 수 있습니다. 초보자에게 가장 중요한 원칙은 승인하기 전에 무엇을 수행하려는지 명확히 확인하는 것입니다.

확인 항목주요 점검 사항초보자 팁
승인 요청 (Approval prompts)파일 수정, 검사 실행, 외부 서비스 접근 여부.이해가 가지 않는다면 먼저 거부하고 Codex에게 이유를 설명하도록 요청하세요.
파일 변경 사항 (File changes)추가, 삭제 또는 수정된 파일 목록.제출하기 전에 요약만 보지 말고 각 diff(변경 내용)를 하나씩 확인하세요.
프로젝트 범위 (Project scope)현재 대화가 컴퓨터의 어떤 프로젝트와 연결되어 있는지.이전 프로젝트나 테스트용 프로젝트가 아닌지 확인하세요.
변경 사항 적용 위치원본 프로젝트 대신 격리된 복사본(isolated copy)을 수정하는지 여부.위험성이 불확실할 때는 격리된 복사본을 우선 사용하세요.
브라우저 페이지 확인열린 페이지가 로컬 개발 환경 페이지인지 여부.계정, 결제 또는 백엔드 관리 권한과 관련된 경우 직접 수동으로 검증하세요.