외부 모델을 Codex에 연결하는 과정은 복잡합니다. 이 가이드는 Kimi API를 실습 예시로 사용하여 macOS와 Windows에서 Codex API 설정 전 과정을 안내합니다.
Codex란 무엇인가요?
Codex는 저장소 및 터미널 작업을 위한 OpenAI의 코딩 에이전트입니다. 다음과 같은 작업을 수행할 수 있습니다.
코드 작성: 함수, 테스트, 스크립트, 특정 기능을 작성합니다.
낯선 코드베이스 이해: 파일을 검색하고, 호출을 추적하고, 구성 요소를 설명합니다.
코드 리뷰: 발생 가능한 결함, 위험한 가정, 누락된 테스트, 보안 문제를 식별합니다.
디버그 및 문제 해결: 오류를 재현하고, 변경 사항을 제안하고, 검사를 실행합니다.
반복 작업 자동화: 사용자의 승인을 받아 파일을 업데이트하고 문서화된 워크플로를 실행합니다.
Codex 설치 및 로그인
1부: Codex CLI 설치
macOS에서는 터미널을, Windows에서는 PowerShell을 엽니다.
운영체제에 맞는 명령을 실행하세요:
macOS:
curl -fsSL https://chatgpt.com/codex/install.sh | shWindows:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"설치가 끝날 때까지 기다린 다음, 터미널 또는 PowerShell을 닫았다가 다시 엽니다.
다음을 실행하세요:
codexChatGPT로 로그인을 선택하고 브라우저에서 로그인을 완료한 다음, 터미널 또는 PowerShell로 돌아옵니다.
2부: Codex 데스크톱 앱 설치하기
Codex 데스크톱 앱 공식 페이지를 방문하세요.
macOS 또는 Windows용 ChatGPT 데스크톱 앱을 다운로드하세요.
앱을 설치하고 실행한 다음 ChatGPT 계정으로 로그인하세요.
작업을 생성하거나 프로젝트를 열고 작업 모드로 Codex를 선택하세요.
Say hello in one sentence.를 입력하고 메시지를 전송하세요.
내장 AI 모델 vs. 외부 LLM API
Codex를 설치한 후에는 내장 AI 모델을 사용하거나 호환되는 외부 LLM API를 연결할 수 있습니다. 어떤 방식이 더 나은지는 원하는 설정 수준, 유연성, 계정 관리 방식에 따라 달라집니다.
Codex 내장 모델 사용하기
내장 모델은 가장 간단한 방식입니다. 다른 서비스를 실행하거나 별도의 API 키를 설정할 필요 없이 사용 가능한 모델을 선택해 바로 코딩을 시작할 수 있습니다.
장점:
추가 설정 단계 없이 빠르게 시작할 수 있습니다.
Codex 도구 및 기능과 직접 통합됩니다
관리해야 할 서비스와 자격 증명이 더 적습니다
제한 사항:
계정에서 사용 가능한 모델 중에서만 선택할 수 있습니다
다른 제공업체의 모델을 사용하고 싶을 때 유연성이 떨어집니다
GPT 구독이 필요하며, 사용 비용이 상대적으로 높습니다.
외부 LLM API 사용하기
외부 API를 사용하면 더 많은 모델을 선택할 수 있고 다른 제공업체의 기존 계정을 활용할 수 있습니다. 다만 일부 모델은 Codex에서 사용하기 전에 추가 설정이나 로컬 호환 도구가 필요합니다.
장점:
다른 제공업체의 모델에 접근할 수 있습니다
다양한 코딩 작업에 더 유연하게 대응할 수 있습니다
외부 API 계정과 사용량을 별도로 관리할 수 있습니다
GPT 구독이 필요 없어 비용에 민감한 상황에 적합합니다.
제한 사항:
API 키와 추가 설정이 필요합니다
계속 실행 상태를 유지해야 하는 로컬 라우터가 필요할 수 있습니다
결제, 호환성, 개인정보 보호, 문제 해결이 외부 제공업체에 따라 달라집니다
가장 빠르게 시작하고 싶다면 내장 모델부터 사용해보세요. 이미 외부 API 계정이 있거나 더 다양한 모델을 사용하고 싶다면 아래 안내를 계속 따라가세요. 여기서는 외부 모델을 Codex에 연결하는 실제 예시로 Kimi API를 사용합니다.
외부 LLM API를 Codex에 연결하는 방법: Kimi 예제
macOS 설정
1단계: 터미널 A를 열고 Node.js와 npm 확인하기
위치: Command+Space를 누르고 Terminal을 입력한 뒤 Enter를 누릅니다. 이 첫 번째 창을 터미널 A로 취급합니다.
실행:
node --version
npm --version예상 결과: 각 명령이 버전을 출력합니다. Node.js의 v22.x.x, npm의 10.x.x와 같은 출력은 예시일 뿐 최소 요구 사항이 아닙니다.
명령을 찾을 수 없는 경우: 브라우저를 열고 https://nodejs.org/en/download로 이동하여 LTS macOS용 .pkg를 다운로드한 뒤, Finder에서 다운로드 폴더를 열고 패키지를 더블클릭하여 설치 프로그램의 기본값을 그대로 수락합니다. Command+Q로 터미널을 닫고 터미널 A를 다시 열어 두 버전 확인 명령을 다시 실행합니다. 두 명령 모두 버전을 반환할 때까지 계속하지 마세요.
2단계: Kimi API 키 생성하기
Kimi API 플랫폼을 엽니다. 콘솔에서 API 키를 생성한 다음 비밀번호 관리자나 시크릿 관리자에 저장합니다. 콘솔이 전체 키를 한 번만 표시한다면 페이지를 벗어나기 전에 복사해 두세요.
3단계: 터미널 A에서 MOONSHOT_API_KEY 설정하기
위치: 터미널 A로 돌아갑니다.
실행:
export MOONSHOT_API_KEY="YOUR_KIMI_API_KEY"YOUR_KIMI_API_KEY 부분만 실제 Kimi 키로 바꾸세요. 따옴표와 변수 이름 MOONSHOT_API_KEY는 그대로 두어야 합니다.
예상 결과: export 명령은 아무 출력도 표시하지 않습니다. 값이 화면에 노출되지 않은 채 존재하는지 확인합니다:
test -n "$MOONSHOT_API_KEY" && echo "Kimi key is set"터미널에 Kimi key is set이 출력되어야 합니다.
4단계: 터미널 A에서 Kimi 직접 테스트하기
위치: MOONSHOT_API_KEY가 설정된 터미널 A를 계속 사용합니다.
실행:
curl --silent --show-error https://api.moonshot.ai/v1/chat/completions \
-H "Authorization: Bearer $MOONSHOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"kimi-k2.7-code","messages":[{"role":"user","content":"Say hello in one sentence."}],"stream":false}'예상 결과: JSON 응답이 표시되며, choices[0].message.content에 생성된 텍스트가 포함되어 있습니다.
5단계: 터미널 B를 열고 터미널 A에서 라우터 시작하기
위치: 터미널 A가 활성화된 상태에서 Command+N을 눌러 두 번째 창을 엽니다. 새 창을 터미널 B라고 부릅니다. 라우터 명령을 실행하기 전에 터미널 A로 돌아가세요.
터미널 A에서 실행:
npx @codeproxy/cli --base-url https://api.moonshot.ai/v1 --model kimi-k2.7-code --apikey "$MOONSHOT_API_KEY"기본 URL이나 모델을 바꾸지 마세요. $MOONSHOT_API_KEY는 변수 참조 그대로 두어야 하며, 키를 다시 붙여넣은 두 번째 사본이어서는 안 됩니다.
첫 실행 시 나타날 수 있는 프롬프트: npx가 Need to install ... Ok to proceed? (y)를 표시할 수 있습니다. 먼저 패키지 이름과 연결된 서드파티 소스를 확인하세요. 해당 패키지를 수락하는 경우에만 y를 입력하고 Enter를 누르세요. 여기서는 특정 패키지 버전이 테스트되었다고 명시하지 않습니다.
예상 결과: 프로세스가 계속 실행되며 127.0.0.1:8787에서 대기 중이라고 알려줍니다. 터미널 A는 열어 둔 상태로 두세요.
실패한 경우: npm이 패키지를 다운로드하지 못하면 인터넷 연결을 확인하고 node --version과 npm --version을 다시 실행하세요. 포트 8787이 이미 사용 중이라면 해당 포트를 사용하는 다른 로컬 프로세스를 중지하거나 해당 프로세스의 터미널로 돌아가 Ctrl+C를 누른 다음 라우터 명령을 다시 실행하세요.
6단계: 터미널 B에서 로컬호스트 테스트하기
위치: 터미널 B를 클릭합니다.
실행:
curl --no-buffer --show-error http://127.0.0.1:8787/v1/responses \
-H "Content-Type: application/json" \
-d '{"model":"kimi-k2.7-code","input":"Say hello in one sentence.","stream":true}'예상 결과: 터미널 B에 Responses 형식과 유사한 스트리밍 이벤트 또는 한 문장짜리 인사말이 담긴 출력이 표시됩니다. 정확한 이벤트 순서는 라우터 릴리스에 따라 다를 수 있습니다.
다음이 표시되는 경우 Connection refused: 터미널 A를 확인하세요. 라우터가 중지되었다면 5단계 명령을 다시 실행하고 창을 열어 둔 채로 유지하세요. 터미널 A에 업스트림 401 오류가 표시되면 그곳에서 MOONSHOT_API_KEY를 재설정하고 라우터를 다시 시작하세요.
7단계: macOS Codex 설정 파일 생성 및 편집
위치: 계속 터미널 B를 사용합니다.
실행:
mkdir -p "$HOME/.codex"
if [ -f "$HOME/.codex/config.toml" ]; then cp "$HOME/.codex/config.toml" "$HOME/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S)"; fi
touch "$HOME/.codex/config.toml"
open -e "$HOME/.codex/config.toml"이 명령들은 필요한 경우 사용자 수준 설정 파일을 생성하고, 기존 파일을 백업한 뒤 ~/.codex/config.toml을 TextEdit에서 엽니다.
파일이 비어 있는 경우
다음 전체 설정 내용을 붙여넣으세요:
model = "kimi-k2.7-code"
model_provider = "kimi-proxy"
model_context_window = 256000
model_supports_reasoning_summaries = false
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 600000파일에 이미 설정이 있는 경우
전체 설정 내용을 기존 파일 위에 그대로 붙여넣지 마세요. 관련 없는 설정은 그대로 두고 필요한 줄만 개별적으로 수정하세요.
model =로 시작하는 줄을 찾아 해당 줄 전체를 다음으로 바꾸세요:
model = "kimi-k2.7-code"model_provider =로 시작하는 줄을 찾아 해당 줄 전체를 다음으로 바꾸세요:
model_provider = "kimi-proxy"model_context_window =로 시작하는 줄을 찾아 해당 줄 전체를 다음으로 바꾸세요:
model_context_window = 256000model_supports_reasoning_summaries =로 시작하는 줄을 찾아 해당 줄 전체를 다음으로 바꾸세요:
model_supports_reasoning_summaries = false이 네 가지 설정 중 아직 존재하지 않는 항목이 있다면, 파일 상단 부근에 누락된 줄을 추가하세요.
다음으로 시작하는 줄 전체를 찾아 삭제하세요:
model_catalog_json =또한 다음으로 시작하는 줄 전체도 찾아서 삭제하세요:
service_tier =아래 섹션을 추가하세요:
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 600000[model_providers.openai]와 같은 다른 제공자 섹션은 제거하지 마세요.
notify, 승인, 샌드박스, 프로젝트, 인터페이스 관련 설정 등 관련 없는 기존 설정은 그대로 유지하세요. 다른 사용자의 notify 줄을 복사하지 마세요. 컴퓨터별 절대 경로가 포함되어 있을 수 있습니다.
Command+S를 눌러 파일을 저장한 뒤 TextEdit을 닫으세요.
8단계: Codex 재시작 및 macOS 전체 테스트 실행
위치: 터미널 A에서 라우터를 계속 실행 상태로 둡니다. 터미널 B에서는 Ctrl+C로 기존 Codex 세션을 종료한 다음, 임시로 사용할 폴더를 준비하세요.
터미널 B에서 실행:
mkdir -p "$HOME/codex-kimi-test"
cd "$HOME/codex-kimi-test"
codex테스트: hello.를 입력하고 Enter를 누르세요. 한 문장짜리 답변이 나오면 기본 요청 경로가 정상 작동함을 확인한 것입니다.
Windows 설정
독립적인 PowerShell 창 두 개를 사용합니다. PowerShell A는 현재 세션의 Kimi 키를 저장하고 라우터를 실행합니다. PowerShell B는 localhost를 테스트하고, 설정을 편집하며, Codex를 시작합니다. 영구 사용자 변수는 이후에 열리는 창들도 지원하며, 현재 세션 할당 덕분에 PowerShell A에서 즉시 키를 사용할 수 있습니다.
1단계: PowerShell A를 열고 Node.js와 npm 확인하기
위치: Windows 키를 누르고 PowerShell을 입력한 다음 Windows PowerShell을 엽니다. 이 창을 PowerShell A라고 부릅니다.
실행:
node --version
npm --version예상 결과: 두 명령 모두 버전을 출력합니다. v22.x.x, 10.x.x와 같은 값은 예시일 뿐이며 최소 요구 사항이 아닙니다.
명령을 인식하지 못하는 경우: 브라우저를 열고 https://nodejs.org/en/download에 접속합니다. LTS Windows용 .msi를 다운로드하고, 파일 탐색기에서 다운로드 폴더를 연 다음 설치 프로그램을 더블클릭해 기본값을 그대로 수락하되, 설치 프로그램이 Node.js를 PATH에 추가하는 옵션을 유지하는지 확인합니다. 모든 PowerShell 창을 닫고 PowerShell A를 다시 열어 두 명령을 다시 실행합니다.
2단계: Kimi API 키 만들기
Kimi API 플랫폼을 엽니다. 콘솔에서 API 키를 만든 다음 비밀번호 관리자나 시크릿 관리자에 저장합니다. 콘솔이 전체 키를 한 번만 보여준다면 페이지를 벗어나기 전에 복사해 두세요.
3단계: PowerShell A에서 영구 변수와 현재 세션 변수 설정하기
위치: PowerShell A로 돌아갑니다.
실행:
[Environment]::SetEnvironmentVariable("MOONSHOT_API_KEY", "YOUR_KIMI_API_KEY", "User")
$env:MOONSHOT_API_KEY = "YOUR_KIMI_API_KEY"두 줄에서 YOUR_KIMI_API_KEY만 동일한 Kimi 키로 바꾸세요. MOONSHOT_API_KEY, User, 따옴표, 구두점은 그대로 둡니다. 첫 번째 줄은 이후 프로세스를 위해 값을 저장하고, 두 번째 줄은 PowerShell A에서 즉시 사용할 수 있게 합니다.
예상 결과: 두 명령 모두 출력이 없습니다. 키를 출력하지 않고 존재 여부만 확인합니다:
$null -ne $env:MOONSHOT_API_KEYPowerShell은 True를 출력해야 합니다.
False가 출력되는 경우: 직선 따옴표를 사용해 현재 세션 할당 명령을 다시 실행하세요. 정책 때문에 User 값 쓰기가 차단된 경우, 이번 실습에서는 현재 세션 값으로 진행하고 사용자 환경 변수를 어떻게 저장해야 하는지 관리자에게 문의하세요. 로그나 공유된 텍스트에 노출된 키는 모두 폐기하세요.
4단계: PowerShell A에서 Kimi를 직접 테스트하기
API 참고 문서에는 POST URL이 표시될 수 있지만, POST https://...만 그대로 PowerShell에 입력하지 마세요. 여기서 보여주는 것처럼 Invoke-RestMethod -Method Post를 사용하세요.
위치: $env:MOONSHOT_API_KEY가 설정된 PowerShell A에 그대로 머뭅니다.
실행:
$headers = @{ Authorization = "Bearer $env:MOONSHOT_API_KEY" }
$body = @{ model = "kimi-k2.7-code"; messages = @(@{ role = "user"; content = "Say hello in one sentence." }); stream = $false } | ConvertTo-Json -Depth 5
$response = Invoke-RestMethod -Method Post -Uri "https://api.moonshot.ai/v1/chat/completions" -Headers $headers -ContentType "application/json" -Body $body
$response.choices[0].message.content엔드포인트, 모델, 변수 이름은 바꾸지 마세요. PowerShell은 $env:MOONSHOT_API_KEY에서 키를 읽습니다.
예상 결과: 마지막 줄에서 choices[0].message.content에서 나온 한 문장짜리 인사말이 출력됩니다.
401을 받은 경우: 키가 전역 .ai 콘솔에서 발급된 것인지 확인하고, 필요하면 폐기 후 다시 만든 다음 3단계의 두 할당 명령을 다시 실행하고 재시도하세요. 모델이 거부된다면 ID가 정확히 kimi-k2.7-code인지 확인하고 Kimi 콘솔에서 모델 접근 권한을 확인하세요.
5단계: PowerShell B를 열고 PowerShell A에서 라우터 시작하기
위치: Windows 키를 다시 눌러 PowerShell을 입력하고 두 번째 Windows PowerShell 창을 엽니다. 이 창을 PowerShell B라고 부릅니다. 라우터 명령을 실행하려면 PowerShell A로 돌아갑니다.
PowerShell A에서 실행:
npx @codeproxy/cli --base-url https://api.moonshot.ai/v1 --model kimi-k2.7-code --apikey $env:MOONSHOT_API_KEY$env:MOONSHOT_API_KEY는 그대로 두세요. 키를 명령에 직접 붙여넣지 마세요.
최초 실행 시 나타날 수 있는 안내: npx가 Need to install ... Ok to proceed? (y)를 표시할 수 있습니다. 패키지와 제3자 출처를 검토하세요. 수락하는 경우에만 y를 입력하고 Enter를 누르세요. 특정 패키지 버전이 테스트되었다고 보장하지는 않습니다.
예상 결과: 프로세스가 계속 열려 있으며 127.0.0.1:8787에서 대기 중이라고 보고합니다. PowerShell A는 계속 열어 두세요.
실패하는 경우: PowerShell A에서 node --version과 npm --version을 실행하세요. 둘 중 하나라도 실패하면 1단계를 반복하세요. 8787 포트가 사용 중이라면 해당 창에서 Ctrl+C로 다른 라우터를 중지한 다음 명령을 다시 실행하세요.
6단계: PowerShell B에서 localhost 테스트하기
위치: PowerShell B를 클릭합니다. PowerShell A의 라우터는 중지하지 마세요.
실행:
$localBody = @{ model = "kimi-k2.7-code"; input = "Say hello in one sentence."; stream = $false } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8787/v1/responses" -ContentType "application/json" -Body $localBodylocalhost URL은 교체하지 마세요. PowerShell A의 라우터를 가리키는 주소입니다.
예상 결과: PowerShell이 인사말을 포함한 Responses와 유사한 객체 또는 출력을 반환합니다. 정확한 필드는 라우터 버전에 따라 다를 수 있습니다.
연결이 거부되는 경우: PowerShell A를 확인하여 라우터가 종료되었다면 5단계 명령을 다시 실행하세요. PowerShell A에 업스트림 인증 오류가 표시되면 Ctrl+C를 눌러 $env:MOONSHOT_API_KEY를 재설정하고 라우터를 다시 시작하세요. 기본 @codeproxy/cli 빠른 시작에는 로컬 인증 헤더를 추가하지 마세요.
7단계: Windows Codex 설정 만들기 및 편집하기
위치: 계속 PowerShell B를 사용합니다. 공급자 설정은 프로젝트 폴더가 아니라 $HOME\.codex\config.toml에 있어야 합니다.
실행:
New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null
$configPath = "$HOME\.codex\config.toml"
if (Test-Path $configPath) { Copy-Item $configPath "$configPath.backup-$(Get-Date -Format 'yyyyMMdd-HHmmss')" }
if (-not (Test-Path $configPath)) { New-Item -ItemType File -Path $configPath | Out-Null }
notepad "$HOME\.codex\config.toml"이 명령들은 사용자 디렉터리를 생성하고, 기존 설정 파일이 있으면 백업하며, 파일이 없으면 새로 만들고 메모장에서 엽니다.
메모장에서: 아래의 완전한 기본 설정을 붙여넣으세요. 파일에 이미 충돌하는 중복 model 또는 provider 키가 있다면 제거하세요:
model_provider = "kimi-proxy"
model = "kimi-k2.7-code"
model_context_window = 256000
model_supports_reasoning_summaries = false
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 600000kimi-proxy, localhost URL, 또는 responses는 교체하지 마세요. Ctrl+S를 눌러 저장한 뒤 메모장을 닫으세요.
파일 이름 확인: 다음을 실행하세요:
Get-Item "$HOME\.codex\config.toml" | Select-Object FullName, Name, Length예상 결과: Name이 config.toml.txt가 아니라 정확히 config.toml이며, Length는 0보다 큽니다.
메모장이 .txt를 추가한 경우: 메모장에서 파일 → 다른 이름으로 저장을 선택하고 파일 형식을 모든 파일로 설정한 뒤 config.toml을 입력하고 $HOME\.codex에 저장하세요. Get-Item을 다시 실행하세요. Codex가 공급자 설정을 무시하면 사용자 수준 경로를 편집했는지 확인하고 중복된 TOML 키를 제거하세요.
8단계: Codex 재시작 및 전체 Windows 테스트 실행하기
위치: PowerShell A와 그 라우터는 계속 실행 상태로 둡니다. 실행 중인 Codex 앱이나 세션을 완전히 종료하세요. PowerShell B를 닫고, Windows 키 → PowerShell 입력 → Windows PowerShell 열기로 다시 연 뒤 임시 폴더를 만드세요.
다시 연 PowerShell B에서 실행:
New-Item -ItemType Directory -Force -Path "$HOME\codex-kimi-test" | Out-Null
Set-Location "$HOME\codex-kimi-test"
codex테스트: hello.를 입력하고 Enter를 누르세요. 한 문장짜리 답변이 오면 기본 요청 경로가 확인된 것입니다.
Codex 데스크톱 앱에서 Kimi 사용하기
계속하기 전에 로컬 라우터와 config.toml을 위한 macOS 또는 Windows 설정의 1~7단계를 완료하세요. CLI 테스트를 먼저 완료할 필요는 없지만, 데스크톱 앱에서 Kimi를 사용하는 동안 라우터는 계속 실행 중이어야 합니다.
1단계: 로컬 라우터 계속 실행하기
다음에서 @codeproxy/cli가 실행 중인 Terminal A 또는 PowerShell A를 계속 열어 두세요:
http://127.0.0.1:87872단계: 공급자 설정 확인하기
사용자 수준 Codex 설정 파일을 여세요.
macOS에서는 다음을 실행하세요:
open -e "$HOME/.codex/config.toml"Windows에서는 다음을 실행하세요:
notepad "$HOME\.codex\config.toml"파일에 다음 최상위 설정이 포함되어 있는지 확인하세요:
model = "kimi-k2.7-code"
model_provider = "kimi-proxy"
model_context_window = 256000
model_supports_reasoning_summaries = false
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 6000003단계: 데스크톱 앱 완전히 재시작하기
macOS에서는 Command+Q를 눌러 데스크톱 앱을 완전히 종료하세요. 창만 닫는 것으로는 충분하지 않습니다.
Windows에서는 데스크톱 앱의 모든 창을 닫고, 앱이 시스템 트레이에서도 실행되고 있지 않은지 확인하세요.
데스크톱 앱을 다시 열고 프로젝트 폴더를 엽니다.
5단계: Custom 모델을 그대로 선택된 상태로 둡니다
데스크톱 모델 선택기에는 Kimi K2.7 Code 대신 Custom이 표시될 수 있습니다. 이는 정상적인 동작입니다.
config.toml에 정의된 커스텀 프로바이더는 데스크톱 모델 목록에 이름으로 표시되지 않는 경우가 있습니다. Kimi 프로바이더를 사용하려는 경우 GPT-5.6 Sol 같은 OpenAI 모델을 선택하지 마세요. Custom이 선택된 상태를 유지하세요.
다음과 같은 경고가 표시될 수도 있습니다:
Model metadata for `kimi-k2.7-code` not found.
Defaulting to fallback metadata.이는 연결 실패가 아니라 경고입니다. 다음 설정에는 정상적인 사용에 필요한 중요한 모델 정보가 이미 포함되어 있습니다:
model_context_window = 256000
model_supports_reasoning_summaries = false5단계: 데스크톱 요청 경로 확인
데스크톱 앱에서 다음 프롬프트를 보냅니다:
데스크톱 앱이 응답하는 동안 터미널 A 또는 PowerShell A를 확인하세요. 터미널 A 창에 새 요청이 수신되고 데스크톱 앱이 답변을 반환하면, 데스크톱 앱이 로컬 Kimi 라우트를 사용하고 있는 것입니다.
일반적인 통합 오류 문제 해결
zsh: command not found: POST
POST URL은 명령어가 아니라 API 문서 표기법입니다. macOS에서는 전체 curl 예제를 복사하세요. Windows에서는 전체 Invoke-RestMethod -Method Post 예제를 복사하세요.
포트 8787에서 연결이 거부됨
터미널 A 또는 PowerShell A로 돌아갑니다. 실행 중인 라우터 프로세스가 없다면 현재 세션의 Kimi 변수를 설정하고 문서에 나온 npx @codeproxy/cli ... 명령을 다시 실행하세요. 해당 창을 열어 둔 채로 창 B에서 localhost 테스트를 반복하세요.
401 응답
라우터 창을 확인해 어느 단계에서 실패했는지 파악하세요. 업스트림 Kimi에서 발생한 401은 대개 MOONSHOT_API_KEY가 유효하지 않거나, 폐기되었거나, 잘못된 지역 계정에서 발급된 것을 의미합니다. 전역 .ai 콘솔에서 해당 키를 폐기하고 새로 생성한 뒤, 현재 세션 변수를 재설정하고 라우터를 다시 시작하세요. 기본 라우터 경로에는 인바운드 베어러 검사가 없습니다. 다른 어댑터에서 로컬 401이 발생하면 선택적 CODEX_KIMI_PROXY_KEY가 누락되었거나 유효하지 않은 경우일 수 있습니다.
지원되지 않는 매개변수 또는 도구 오류
라우터가 Kimi가 허용하지 않는 필드를 전달하고 있을 수 있습니다. 샘플링 필드는 설정하지 않은 상태로 두어야 하며, 값을 지정해야 한다면 허용되는 고정 값만 사용해야 합니다. tool_choice가 auto 또는 none인지, 그리고 어댑터가 reasoning_content를 보존하는지 확인하세요. 다단계 테스트가 여전히 실패한다면 해당 라우터 버전 사용을 중단하고 Kimi를 명시적으로 지원하는 버전을 선택하거나 업데이트하세요.
Codex가 프로바이더를 무시함
사용자 파일을 직접 여세요: macOS에서는 open -e "$HOME/.codex/config.toml"을, Windows에서는 notepad "$HOME\.codex\config.toml"을 실행합니다. 최상위 model_provider = "kimi-proxy" 항목이 하나, 프로바이더 테이블이 하나, localhost 기본 URL, 그리고 wire_api = "responses"가 있는지 확인하세요. 저장한 뒤 Codex를 완전히 종료했다가 다시 시작하세요. 프로바이더 선택 항목을 프로젝트 .codex/config.toml에만 넣지 마세요.
npx가 라우터를 시작하지 못함
라우터 창 A에서 node --version과 npm --version을 실행하세요. 둘 중 하나라도 실패하면 nodejs.org/download에서 Node.js LTS 패키지를 설치하고, 터미널을 닫았다가 다시 열어 다시 시도하세요. npx가 패키지 다운로드 권한을 요청하면 y를 입력하기 전에 패키지와 출처를 확인하세요.
Kimi API 사용의 이점
Cursor API 워크플로에서 Kimi를 사용하면 코딩, 디버깅, 개발 작업을 개선할 수 있습니다. 고급 기능 덕분에 정확한 응답을 생성하고, 복잡한 지시를 처리하며, 더 빠른 문제 해결을 지원합니다. 다음은 생산성과 효율성을 높이기 위해 Cursor 워크플로에서 Kimi를 사용할 때 얻을 수 있는 주요 이점입니다.
긴 컨텍스트 코드 이해
Kimi는 대량의 코드와 정보를 한 번에 처리할 수 있습니다. 서로 다른 파일과 프로젝트 부분 간의 관계를 더 효과적으로 파악합니다. 그 결과 크거나 복잡한 코드베이스 작업이 훨씬 수월해집니다.
문서 및 저장소 분석 개선
Kimi를 사용하면 프로젝트 문서, 기술 노트, 저장소를 빠르게 검토할 수 있습니다. 모든 파일을 일일이 살펴보지 않아도 중요한 세부 사항을 쉽게 찾을 수 있습니다. 개발자는 더 짧은 시간에 프로젝트 전체를 더 명확하게 파악할 수 있습니다.
비용 효율적인 AI 개발
Kimi는 다양한 개발 작업을 처리하는 데 실용적이고 비용 효율적인 선택지를 제공합니다. 비용이 더 높은 모델에 전적으로 의존하지 않고도 강력한 AI 지원을 받을 수 있습니다. 팀은 비용을 더 잘 통제하면서 전반적인 생산성을 높일 수 있습니다.
더 빠른 지식 검색
대규모 코드베이스, 데이터셋, 프로젝트 파일 전반에서 필요한 정보를 빠르게 찾을 수 있습니다. 답이나 참고 자료를 찾느라 자료를 뒤지는 시간이 줄어듭니다. 코딩, 테스트, 프로젝트 개선에 더 많은 관심을 기울일 수 있습니다.
향상된 워크플로 자동화
반복적인 개발 작업을 Kimi와 함께 더 쉽게 관리하고 완료할 수 있습니다. 코드 생성, 콘텐츠 검토, 일상적인 프로젝트 활동을 지원받을 수 있습니다. 일상적인 워크플로가 시간이 지나도 체계적이고 효율적이며 더 생산적으로 유지됩니다.
Codex가 개발 워크플로를 개선하는 방식
구성된 Codex CLI API 워크플로는 저장소 검사, 편집, 명령 실행, 검토를 하나의 컨텍스트로 연결합니다. Codex는 파일을 뼈대로 구성하고, 낯선 모듈을 설명하고, 오류를 재현하고, 테스트를 제안하고, 승인된 검사를 실행할 수 있습니다. 외부 제공자 지원은 모델 선택의 폭을 넓혀 주지만 검토 책임을 없애 주지는 않습니다.
각 작업은 좁은 범위의 목표로 시작하세요. Codex에게 편집 전에 먼저 검사하도록 요청하고, 제안된 변경 사항을 검토하고, 이해되는 명령만 승인하고, 저장소의 테스트를 실행하고, 최종 diff를 확인하세요. 생성된 코드는 검토와 검증을 통과하기 전까지는 신뢰할 수 없는 기여물로 취급하세요.
결론
신뢰할 수 있는 Codex API 사용은 각 단계를 순서대로 테스트하는 데서 나옵니다: Codex를 인증하고, Kimi를 직접 호출하고, localhost를 시작해 테스트하고, 사용자 수준의 제공자 구성을 저장하고, 읽기 전용 프롬프트를 실행하고, 파일 및 도구 작업을 완료하세요. 실제 Kimi 키는 라우터와 함께 보관하고, 비밀 정보는 공유 파일에 두지 말고, 작업이 끝나면 라우터를 중지하세요.