본문으로 건너뛰기
개발자 리소스
개발자 리소스

Codex App

Codex App에서 RunAPI를 모델 공급자로 사용하고, Responses 호환 모델을 선택한 후 연결을 확인합니다.

Markdown 보기

개요

Codex는 Windows 및 macOS용 ChatGPT 데스크탑 앱에서 사용할 수 있습니다. 이 가이드는 로컬 Codex App을 RunAPI의 OpenAI 호환 Responses 엔드포인트로 지정하고, RunAPI 모델을 선택하고, 연결을 확인합니다.

이것은 응답과 코드를 생성하는 데 사용되는 모델 공급자를 변경합니다. RunAPI 도구는 추가하지 않습니다. 호스팅된 MCP는 자체 클라이언트 및 인증 요구 사항을 가진 별도의 통합입니다.

시작하기 전에

  • 현재 버전의 ChatGPT 데스크톱 앱을 설치하고 로그인한 후 Codex를 최소 한 번 실행하십시오.
  • 인증 가이드를 따라 전용 표준 RunAPI API 키를 생성하십시오. 리포지토리에 커밋하지 마십시오.
  • 모델 카탈로그에서 Responses API를 지원하는 모델의 정확한 식별자를 복사하십시오.

이 단계는 사용자 수준 구성을 읽는 로컬 Codex 클라이언트를 구성합니다. 호스팅된 Codex 클라우드 작업은 구성하지 않습니다.

API 키 저장

데스크톱 앱은 셸의 환경 변수를 상속받지 못할 수 있습니다. ~/.codex/.env를 생성하거나 편집하고 키를 별도의 줄에 추가하세요:

DOTENV 
export RUNAPI_API_KEY=YOUR_RUNAPI_API_KEY

이 파일을 저장소 외부에 보관하세요. macOS 및 Linux에서는 사용자 계정으로만 제한하세요:

SHELL 
chmod 600 ~/.codex/.env

RunAPI 구성

사용자 수준 ~/.codex/config.toml을 여십시오. 기존 파일에 다음 값을 병합하십시오. 관련 없는 설정을 교체하거나 기존 최상위 키의 두 번째 복사본을 추가하지 마십시오:

TOML 
model = "YOUR_RUNAPI_MODEL_ID"
model_provider = "runapi"

[model_providers.runapi]
name = "RunAPI"
base_url = "https://runapi.ai/v1"
env_key = "RUNAPI_API_KEY"
wire_api = "responses"

공급자 및 인증 설정은 사용자 수준이어야 합니다. Codex는 프로젝트의 .codex/config.toml에 있는 model_provider 및 model_providers를 무시합니다. TOML에는 환경 변수 이름만 저장되며, API 키는 ~/.codex/.env에 보관됩니다.

base_url은 작업 URL이 아닌 API 루트입니다. wire_api = "responses"를 사용하면 Codex는 POST /v1/responses를 전송합니다. 공급자 계약에 대해서는 OpenAI의 커스텀 모델 공급자 구성을 참조하세요.

모델 선택

YOUR_RUNAPI_MODEL_ID를 모델 카탈로그에서 복사한 정확한 식별자로 교체하세요. Responses API를 노출하는 모델을 선택하세요. Chat Completions만 지원하는 것은 이 구성에 충분하지 않습니다.

model을 변경할 때는 앱을 완전히 재시작하고 새 Task를 시작하세요. 기존 Task는 시작 시 사용된 모델과 제공자를 유지할 수 있습니다.

재시작 및 확인

  1. ChatGPT 데스크톱 앱을 완전히 종료한 후 다시 여십시오.
  2. Codex를 열고 리포지토리에서 새 작업을 시작하십시오.
  3. Describe this repository in one sentence.와 같은 짧은 프롬프트를 보내십시오.
  4. Codex가 정상 응답을 반환하고 RunAPI가 선택한 모델에 대한 POST /v1/responses 요청을 기록하는지 확인하십시오.

첫 번째 검증은 짧게 유지하여 구성 오류를 작업별 동작과 쉽게 구분할 수 있도록 하세요.

RunAPI 도구 추가

위의 모델 공급자는 Codex 추론을 RunAPI를 통해 라우팅합니다. MCP는 별개입니다. 지원되는 클라이언트가 모델 검색, 계정 정보, 지원되는 작업 워크플로를 위해 RunAPI 도구를 호출할 수 있게 합니다.

호스팅된 MCP 가이드에서 현재 지원되는 클라이언트 및 인증 요구 사항을 확인할 수 있습니다. Codex 특정 호스팅 MCP 인증은 검증되지 않았으므로, 이 페이지에서는 Codex MCP 설정 단계를 제공하지 않습니다. 모델 공급자 구성을 MCP 서버 항목으로 대체하지 마세요. 두 통합은 서로 다른 목적을 수행합니다.

문제 해결

  • Codex가 이전 공급자를 계속 사용함: 파일이 ~/.codex/config.toml인지 확인하고, 중복된 model 또는 model_provider 키를 제거한 후 앱을 완전히 재시작하고 새 작업을 시작하세요.
  • RUNAPI_API_KEY가 없음: 키가 터미널 프로필에만 있는 것이 아니라 ~/.codex/.env에 있는지 확인한 후 앱을 재시작하세요.
  • 인증 실패: 인증 가이드를 통해 표준 키를 생성하거나 교체하세요. 키를 config.toml이나 지원 로그에 붙여넣지 마세요.
  • 요청에서 404 반환: base_url을 https://runapi.ai/v1/responses가 아닌 https://runapi.ai/v1로 설정하세요.
  • 모델을 사용할 수 없거나 필드를 거부함: 정확한 식별자를 다시 복사하고 해당 모델이 Responses API와 요청한 기능을 지원하는지 확인하세요.
  • Codex가 다른 모델을 선택함: 신뢰할 수 있는 프로젝트의 .codex/config.toml 파일에서 model 재정의 설정을 확인하세요. 프로젝트 설정은 사용자 수준의 공급자를 대체할 수 없지만 모델을 선택할 수 있습니다.
  • CLI는 작동하지만 앱은 실패함: ~/.codex/.env를 확인한 후 앱을 완전히 재시작하세요. GUI 애플리케이션은 셸에서만 내보낸 변수를 읽지 못할 수 있습니다.
  • 클라우드 작업이 RunAPI를 사용하지 않음: 이 로컬 설정은 로컬 Codex 클라이언트에 적용되며, 호스팅된 클라우드 작업은 사용자 컴퓨터의 파일을 읽지 않습니다.

RunAPI 제거

  1. ~/.codex/config.toml에서 RunAPI model, model_provider, [model_providers.runapi] 값을 제거하거나, 이전에 사용하던 제공자 값을 복원합니다.
  2. 다른 로컬 도구에서 사용하지 않는다면 ~/.codex/.env에서 RUNAPI_API_KEY를 제거합니다.
  3. 앱을 완전히 재시작하고 새 작업을 시작합니다.
  4. 더 이상 필요하지 않은 경우 RunAPI에서 전용 키를 폐기합니다.

다음 단계

공유 프로토콜 동작은 LLM API Quickstart를, 정확한 요청 및 응답 필드는 Responses API Reference를 참조하세요. 필요에 따라 Model Catalog, Authentication Guide, 또는 Hosted MCP로 계속 진행하세요.