Kimi Open Platform은 Codex가 사용하는 Responses API를 기본적으로 지원하므로 Codex에서 Kimi 모델을 직접 사용할 수 있습니다. 프로토콜 변환이나 로컬 프록시는 필요하지 않습니다. 이 가이드에서는 macOS와 Windows에서의 전체 설정 과정을 안내합니다.
Codex란 무엇인가요?
Codex는 리포지토리와 터미널 작업을 위한 OpenAI의 코딩 에이전트입니다. 다음 작업을 수행할 수 있습니다.
코드 작성: 함수, 테스트, 스크립트, 집중된 기능을 만듭니다.
낯선 코드베이스 이해: 파일을 검색하고, 호출을 추적하며, 구성 요소를 설명합니다.
코드 검토: 발생 가능성이 높은 결함, 위험한 가정, 누락된 테스트, 보안 문제를 식별합니다.
문제 디버깅 및 수정: 오류를 재현하고, 변경 사항을 제안하며, 검사를 실행합니다.
반복 작업 자동화: 승인에 따라 파일을 업데이트하고 문서화된 워크플로를 실행합니다.
Codex 설치 및 로그인
1부: Codex CLI 설치
macOS에서는 Terminal을, Windows에서는 PowerShell을 엽니다.
운영 체제에 맞는 명령을 실행하세요.
macOS:
Windows:
설치가 완료될 때까지 기다린 후 Terminal 또는 PowerShell을 닫았다가 다시 여세요.
다음을 실행하세요.
ChatGPT로 로그인(Sign in with ChatGPT)을 선택하고 브라우저에서 로그인을 완료한 뒤 Terminal 또는 PowerShell로 돌아오세요. 이 로그인에는 무료 ChatGPT 계정이면 충분하며 유료 구독은 필요하지 않습니다. 이후 구성할 외부 Kimi 경로에는 OpenAI 청구가 적용되지 않습니다.
2부: Codex 데스크톱 앱 설치
https://chatgpt.com/download의 공식 다운로드 페이지에서 macOS 또는 Windows용 데스크톱 앱을 다운로드하세요. Codex는 ChatGPT 데스크톱 앱에 작업 모드로 포함되어 있으며, 다운로드하는 앱의 이름은 ChatGPT입니다.
앱을 설치하고 실행한 다음 ChatGPT 계정으로 로그인하세요.
작업을 만들거나 프로젝트를 열고 작업 모드로 Codex를 선택하세요.
한 문장으로 인사해 주세요.를 입력하고 메시지를 보내세요.
내장 AI 모델과 외부 LLM API 비교
Codex를 설치한 후에는 내장 AI 모델을 사용하거나 호환되는 외부 LLM API를 연결할 수 있습니다. 어떤 옵션이 가장 적합한지는 원하는 설정 수준, 유연성, 계정 관리 방식에 따라 달라집니다.
Codex 내장 모델 사용
내장 모델은 가장 간편한 사용 환경을 제공합니다. 별도의 서비스를 실행하거나 API 키를 따로 설정하지 않아도 사용 가능한 모델을 선택해 코딩을 시작할 수 있습니다.
장점:
추가 설정 단계 없이 빠르게 설정할 수 있습니다.
Codex 도구 및 기능과 직접 통합
관리해야 할 서비스와 자격 증명이 줄어듭니다.
제한 사항:
계정에서 사용할 수 있는 모델만 선택할 수 있습니다.
다른 제공업체의 모델을 사용하려는 경우 유연성이 떨어집니다.
ChatGPT 계정으로 로그인해야 합니다. 무료 요금제에는 제한된 Codex 액세스가 포함되지만, 일반적으로 정기적으로 사용하려면 유료 ChatGPT 요금제(예: Plus 또는 Pro) 또는 사용량 기준으로 과금되는 OpenAI API 키가 필요합니다.
외부 LLM API 사용
외부 API를 사용하면 더 다양한 모델을 선택할 수 있고 다른 제공업체의 기존 계정도 활용할 수 있습니다. Kimi Open Platform은 Codex에서 사용하는 Responses API를 기본 지원하므로 직접 연결되며, 로컬 라우터가 필요하지 않습니다.
장점:
다른 제공업체의 모델에 액세스할 수 있습니다.
서로 다른 코딩 작업에 더 유연하게 대응할 수 있습니다.
외부 API 계정 및 사용량을 별도로 관리할 수 있습니다.
GPT 구독이 필요하지 않습니다. 비용에 민감한 상황에 적합합니다.
제한 사항:
API 키와 약간의 설정 변경이 필요합니다.
청구, 호환성, 개인정보 보호 및 문제 해결은 외부 제공업체에 따라 달라집니다.
가장 빠르게 설정하려면 내장 모델부터 시작하세요. 이미 외부 API 계정이 있거나 더 많은 모델을 선택하고 싶다면 다음 안내를 계속 진행하세요.
외부 LLM API를 Codex에 연결하는 방법: Kimi 예시
1단계: Kimi API 키 만들기
Kimi API 플랫폼을 엽니다. 콘솔에서 API 키를 만든 다음 비밀번호 관리자나 시크릿 관리자에 저장하세요. 전체 키는 한 번만 표시되므로 페이지를 떠나기 전에 복사해야 합니다.
참고: Kimi API는 사용한 만큼 비용을 지불하는 유료 서비스입니다. 테스트하기 전에 계정에 사용 가능한 잔액이 있는지 확인하세요. 콘솔의 Billing에서 잔액을 확인하거나 충전할 수 있습니다. 계정 잔액이 0이면 새 API 키만으로는 호출할 수 없습니다.
2단계: KIMI_API_KEY 환경 변수 설정
Codex는 환경 변수에서 API 키를 읽습니다. 키를 config.toml에 작성하지 마세요.
macOS 및 Linux:
키가 셸 기록에 남지 않도록 다음과 같이 입력하세요:
이 설정은 현재 터미널 세션에만 적용됩니다. 계속 유지하려면 export 명령을 ~/.zshrc에 추가하세요(Linux에서 bash를 사용하는 경우 ~/.bashrc). 이 파일에는 키가 일반 텍스트로 저장되므로 그에 맞게 권한을 설정하세요.
Windows(PowerShell):
YOUR_KIMI_API_KEY를 1단계에서 복사한 키로 바꾸세요. 세션 간에도 유지하려면 Settings > System > About > Advanced system settings > Environment Variables에서 KIMI_API_KEY를 추가하세요.
3단계: Kimi를 모델 제공자로 추가
사용자 수준 Codex 구성 파일을 엽니다. macOS 및 Linux에서는 ~/.codex/config.toml이고, Windows에서는 %USERPROFILE%\.codex\config.toml입니다. 파일이 아직 없으면 만드세요.
다음 구성을 추가하세요. model 또는 model_provider가 이미 있으면 해당 값을 바꾸고, model_catalog_json = 또는 service_tier =로 시작하는 모든 줄을 삭제하세요(다른 설정에서 남은 줄이 모델 메타데이터나 라우팅을 덮어쓸 수 있음).
API 키를 중국 플랫폼(platform.moonshot.cn)에서 만들었다면 base_url 값으로 https://api.moonshot.cn/v1을 사용하세요. 두 플랫폼의 키는 서로 호환되지 않습니다.
기존의 관련 없는 설정(예: notify, 승인, 샌드박스, 프로젝트, 인터페이스 환경설정)은 그대로 유지하고, [model_providers.openai] 같은 다른 제공자 섹션도 삭제하지 마세요.
각 설정의 역할:
| 설정 | 유형 | 용도 |
|---|---|---|
wire_api = "responses" | string | 네이티브 Responses API를 통해 Kimi에 연결합니다. 직접 연결에 필요한 핵심 설정입니다. |
env_key = "KIMI_API_KEY" | string | Codex가 API 키를 읽어 오는 환경 변수의 이름 |
model_context_window = 1048576 | integer | kimi-k3의 100만 컨텍스트 윈도우에 맞춥니다. 이 설정이 없으면 Codex는 기본 모델 메타데이터를 사용하며, 성능이 저하될 수 있습니다. |
4단계: Codex를 다시 시작하고 연결 확인
Codex는 시작할 때만 config.toml을 읽으므로, 먼저 실행 중인 Codex 세션을 모두 완전히 종료하세요. 그런 다음 프로젝트 디렉터리로 이동해 Codex를 시작합니다:
시작 후 Codex CLI에 현재 모델로 kimi-k3가 표시되는지 확인합니다:
간단한 요청(예: hello)을 보냅니다. 정상적으로 응답이 오면 Codex가 Kimi Responses API를 통해 연결되었음을 의미합니다.
응답이 실제로 Kimi를 통해 왔는지 확인하려면 세션에 공급자가 kimi로 표시되는지 확인하세요. 예를 들어 Codex 세션에서 /status를 입력하면 됩니다. 내부적으로 Codex는 POST https://api.moonshot.ai/v1/responses로 요청을 보냅니다.
Codex 데스크톱 앱에서 Kimi 사용하기
데스크톱 앱은 CLI와 동일한 사용자 수준 구성을 공유합니다. 먼저 위의 1~3단계를 완료한 다음, 다음을 진행하세요:
1단계: 데스크톱 앱 완전히 재시작하기
macOS에서는 Command+Q를 눌러 데스크톱 앱을 완전히 종료하세요. 창만 닫는 것으로는 충분하지 않습니다.
Windows에서는 모든 데스크톱 앱 창을 닫고 시스템 트레이에서 앱이 더 이상 실행 중이 아닌지 확인하세요.
데스크톱 앱을 다시 열어 ~/.codex/config.toml을 다시 불러온 뒤 프로젝트 폴더를 엽니다.
2단계: Custom 모델 선택 상태 유지하기
모델 선택기를 열고 kimi-k3를 선택하세요. 인터페이스에는 모델명 대신 Custom이 표시될 수 있으며, 이는 정상입니다. config.toml에 정의한 Custom 공급자는 데스크톱 모델 목록에 항상 이름으로 표시되지는 않지만, 요청에는 구성한 kimi-k3가 계속 사용됩니다.
3단계: 데스크톱 요청 경로 확인하기
hi처럼 간단한 요청을 보내세요. 정상적인 응답이 오면 기본 연결이 작동하는 것입니다:
다음으로 Codex의 에이전트 기능을 사용하는 작업을 보내세요:
도구 결과가 반환된 후에도 Desktop이 최종 답변을 계속 생성하면 모델 호출과 도구 호출이 제대로 작동하는 것입니다.
일반적인 통합 오류 해결하기
설정 후에도 "Missing environment variable"이 계속 표시되는 경우
Codex 세션은 세션 시작 시점이 아니라 백그라운드 app-server 데몬이 시작될 때 캡처된 환경에 연결됩니다. KIMI_API_KEY를 설정할 때 데몬이 이미 실행 중이었다면, 현재 터미널에서 변수가 설정된 것으로 표시되더라도 데몬은 해당 변수를 인식하지 못합니다. macOS에서는 GUI 세션 환경에 변수를 기록하고 데몬을 재시작하세요:
그런 다음 Codex를 다시 시작하세요. Windows에서는 시스템 전체에 변수를 설정한 후 로그아웃했다가 다시 로그인하거나 데스크톱 앱을 완전히 재시작하세요.
401 Unauthorized
API 키가 유효하지 않거나 키와 base_url이 서로 다른 플랫폼에 속해 있습니다. platform.kimi.ai에서 만든 API 키는 https://api.moonshot.ai/v1에서만 작동하고, platform.moonshot.cn에서 만든 키는 https://api.moonshot.cn/v1에서만 작동합니다. 또한 KIMI_API_KEY가 Codex 또는 Desktop을 시작하는 데 사용된 환경에서 사용 가능한지 확인하세요. CLI의 경우 Codex를 시작하는 터미널에서 확인하세요:
400 web_search.search_context_size is not supported
요청에 아직 지원되지 않는 search_context_size 매개변수가 포함되어 있으므로 제거하세요. Codex는 기본적으로 이 매개변수를 보내지 않으며, 내장 web_search 도구는 별도 설정 없이 작동합니다.
/v1/responses에서 404 발생
base_url이 잘못되었습니다. 정확히 https://api.moonshot.ai/v1(/v1 접미사 포함)인지 확인하세요. 이전에 CC Switch 또는 다른 로컬 라우터를 통해 연결했다면 base_url이 더 이상 http://127.0.0.1:... 같은 로컬 주소를 가리키지 않는지도 확인하세요.
429 Rate Limit
속도 또는 동시성 한도에 도달했습니다. Kimi API 플랫폼 콘솔의 Limits에서 사용 중인 등급의 할당량을 확인하세요.
경고: kimi-k3의 모델 메타데이터를 찾을 수 없음
kimi-k3는 Codex의 기본 제공 모델 카탈로그에 없습니다. 이 경고는 정상이며 사용에는 영향을 주지 않습니다. 3단계에서 설정한 model_context_window = 1048576이 이미 컨텍스트 윈도를 1M으로 처리하도록 보장합니다.
구성 변경 사항이 적용되지 않음
Codex는 시작할 때만 config.toml을 읽으므로 종료한 후 다시 시작하세요. 또한 사용자 수준의 ~/.codex/config.toml 파일 자체를 수정했는지, 그리고 -c 플래그나 프로필이 해당 설정을 덮어쓰고 있지 않은지 확인하세요. 이전에 CC Switch를 통해 연결했다면 Settings > Routing에서 Codex도 끄세요. 그렇지 않으면 CC Switch가 계속 config.toml을 다시 작성해 새 구성을 덮어씁니다.
Kimi API 사용의 이점
Codex API 워크플로에서 Kimi를 사용하면 코딩, 디버깅, 개발 작업을 개선할 수 있습니다. 고급 기능을 통해 정확한 응답을 생성하고 복잡한 지침을 처리하며 문제 해결 속도를 높일 수 있습니다. 생산성과 효율성을 높이기 위해 Codex 워크플로에서 Kimi를 사용할 때의 주요 이점은 다음과 같습니다.
긴 컨텍스트의 코드 이해
Kimi는 많은 양의 코드와 정보를 한 번에 처리할 수 있습니다. 서로 다른 파일과 프로젝트 섹션 간의 관계를 더 효과적으로 파악합니다. 따라서 규모가 크거나 복잡한 코드베이스도 훨씬 쉽게 다룰 수 있습니다.
더 나은 문서 및 리포지토리 분석
Kimi를 사용하면 프로젝트 문서, 기술 메모, 리포지토리를 빠르게 검토할 수 있습니다. 모든 파일을 직접 살펴보지 않아도 중요한 세부 정보를 더 쉽게 찾을 수 있습니다. 개발자는 더 짧은 시간에 프로젝트 전체를 명확히 이해할 수 있습니다.
비용 효율적인 AI 개발
Kimi는 다양한 개발 작업을 처리할 수 있는 실용적이고 예산 친화적인 선택지입니다. 비용이 더 높은 모델에 전적으로 의존하지 않아도 강력한 AI 지원을 활용할 수 있습니다. 팀은 비용을 더 잘 관리하면서 전반적인 생산성을 높일 수 있습니다.
더 빠른 지식 검색
대규모 코드베이스, 데이터 세트, 프로젝트 파일 전반에서 유용한 정보를 빠르게 찾을 수 있습니다. 답이나 참고 자료를 찾기 위해 리소스를 검색하는 시간이 줄어듭니다. 코딩, 테스트, 프로젝트 개선에 더 많은 집중을 할 수 있습니다.
향상된 워크플로 자동화
Kimi를 사용하면 반복적인 개발 작업을 더 쉽게 관리하고 완료할 수 있습니다. 코드 생성, 콘텐츠 검토, 일상적인 프로젝트 활동을 지원할 수 있습니다. 일상 워크플로를 체계적으로 유지하고 효율성과 생산성을 시간이 갈수록 높일 수 있습니다.
Codex가 개발 워크플로를 개선하는 방식
구성된 Codex CLI API 워크플로는 리포지토리 검사, 편집, 명령 실행, 검토를 하나의 컨텍스트로 연결합니다. Codex는 파일 골격을 만들고, 익숙하지 않은 모듈을 설명하며, 실패를 재현하고, 테스트를 제안하고, 승인된 검사를 실행할 수 있습니다. 외부 제공업체 지원은 모델 선택의 폭을 넓히지만 검토 책임까지 없애지는 않습니다.
각 작업은 범위를 좁힌 목표로 시작하세요. Codex에 편집 전에 검토하도록 요청하고, 제안된 변경 사항을 검토하며, 이해하는 명령만 승인하고, 리포지토리의 테스트를 실행한 뒤 최종 diff를 확인하세요. 생성된 코드는 검토와 검증을 통과하기 전까지 신뢰할 수 없는 기여물로 취급하세요.
결론
신뢰할 수 있는 Codex API 사용은 각 단계를 순서대로 테스트하는 데서 시작합니다. Kimi 계정을 만들고 자금을 충전한 다음, 환경에 API 키를 설정하고, 사용자 수준 제공업체 구성을 저장한 뒤 Codex를 재시작하고, 에이전트 작업으로 넘어가기 전에 간단한 프롬프트로 확인하세요. 키는 config.toml이 아닌 환경 변수에 보관하고, 실제 키는 절대 공개하지 마세요.