프록시, 터널, 또는 깨진 도구 호출 (tool calls)과 싸울 필요 없이 Cursor 내부에서 Moonshot Kimi (K2.6)를 사용하세요.

빠른 시작 · 작동 원리 · Cursor 설정 · FAQ · 소스 빌드

Cursor에서 Kimi를 사용하고 싶으시군요. 간단해 보입니다.

하지만 실제로 해보면 금방 벽에 부딪힙니다:

시도하는 방법	발생하는 현상
Cursor를 api.moonshot.ai로 직접 지정	Cursor는 OpenAI 형태의 API를 기대하며, Kimi가 거부하는 페이로드 (payload)를 전송합니다
127.0.0.1에서 로컬 프록시 (local proxy) 사용	Cursor가 사설 네트워크 URL을 차단합니다: "사설 네트워크에 대한 액세스가 금지되었습니다"
LiteLLM + cloudflared를 직접 연결	작동하다가 갑자기 안 됩니다. 도구 이름이 깨지거나, 스트리밍 (streaming) 불일치, 사고 모드 (thinking mode) 루프, 빈 메시지 프로브 (empty message probes) 등이 발생합니다
Cursor의 무작위 설정 변경	HTTP 400 오류, 에이전트 모드 (Agent mode)가 작업 도중 중단, MCP 도구의 무음 실패

당신은 프로토콜 배관공 (protocol plumber)이 되려고 가입한 것이 아닙니다. 코드를 작성하고 싶었을 뿐입니다.

Kimi Cursor Gateway는 당신을 대신해 지루하고 취약한 작업을 수행하는 작은 Windows 앱입니다:

• Cursor가 실제로 전송하는 내용에 최적화된 **로컬 OpenAI 호환 게이트웨이 (local OpenAI-compatible gateway)**를 실행합니다.
• Cursor가 연결할 수 있도록 공용 HTTPS 터널 (public HTTPS tunnel) (Cloudflare Quick Tunnel)을 엽니다.
• 깨끗한 요청을 Moonshot Kimi K2.6으로 전달합니다.
• Cursor에 붙여넣을 정확한 Base URL + API 키를 보여줍니다.

Python 스크립트도 필요 없습니다. 수동 cloudflared 터미널 세션도 필요 없습니다. LiteLLM 설정 고고학 (config archaeology)도 필요 없습니다.

사용자 → Cursor IDE → https://….trycloudflare.com/v1
↓
Kimi Cursor Gateway (사용자의 PC)
...

platform.moonshot.ai에서 하나를 생성하세요.

이것은 당신의 실제 Kimi 키이며, 암호화된 상태로 당신의 기기에 머뭅니다.

옵션 A — 설치 프로그램 (권장)

Releases에서 최신 Kimi Cursor Gateway_*_x64-setup.exe를 다운로드하여 실행하세요.

옵션 B — 포터블 (USB 친화적, 설치 불필요)

Releases에서 포터블 zip을 다운로드하여 압축을 풀고, Start Kimi Cursor Gateway.bat를 더블 클릭하세요.

옵션 C — 직접 빌드하기

아래의 소스 빌드 (Build from source) 섹션을 참조하세요.

• Launch Kimi Cursor Gateway - Paste your Moonshot API key - Click Start Gateway - Wait until the app shows a public Base URL (ends with /v1) - Copy the Gateway API key shown in the app, this is not your Moonshot key

Tip: "Start with Windows"를 켜두세요. 앱이 트레이(tray)에서 실행되며, 필요할 때 터널(tunnel)을 재시작하고 URL이 변경되면 알림을 보냅니다.

Cursor → Settings → Models를 열고 다음과 같이 설정하세요:

설정 (Setting)	값 (Value)
OpenAI API Key	앱에 표시된 Gateway key
Override OpenAI Base URL	ON
Base URL	https://….trycloudflare.com/v1 (앱에서 확인)
Model	gpt-5-high-max

그 다음, 작동 여부를 확인하기 위해 Cursor에게 간단한 질문을 던져보세요:

"Say hi in one sentence."

답변이 온다면 성공입니다. 이제 Kimi가 당신의 에디터를 구동하고 있습니다.

OpenAI API Key: <gateway-key-from-app>
Override Base URL: ON
Base URL: https://<your-tunnel>.trycloudflare.com/v1
...

왜 gpt-5-high-max인가요?

Cursor는 특정 모델 이름만 추가할 수 있도록 제한하고 있습니다. 게이트웨이는 해당 별칭(alias)과 gpt-4-turbo 같은 다른 이름들을 **256K 컨텍스트 윈도우 (context window)**를 가진 kimi-k2.6으로 매핑합니다. 당신은 Cursor 친화적인 이름을 입력하고, 실제 작업은 Kimi가 수행합니다.

중요: Cursor에는 반드시 **게이트웨이 키 (gateway key)**를 사용하세요. Moonshot 키를 사용해서는 안 됩니다. 당신의 Moonshot 키는 앱 외부로 절대 유출되지 않습니다.

아키텍처 (30초 요약 버전)

Cursor
→ public HTTPS tunnel (cloudflared Quick Tunnel)
→ local gateway (127.0.0.1:4001, Rust/Axum)
...

전체 상세 내용: ARCHITECTURE.md

Cursor의 에이전트 모드 (Agent mode)는 OpenAI 스타일의 복잡한 페이로드 (payload)를 보냅니다. Kimi는 형식이 엄격합니다. 게이트웨이는 그 중간에서 이를 번역하는 역할을 합니다.

Cursor가 보내는 것	게이트웨이가 수행하는 작업
모델 별칭 (gpt-4-turbo, gpt-5-high-max, …)	kimi-k2.6으로 매핑
developer 역할 (role) 메시지	system으로 변환
mcp.fs.read_file과 같은 MCP 도구 이름	유효한 Kimi 식별자로 정제 (Sanitize)
type: "custom" 도구, 평면적인 도구 형태 (flat tool shapes)	표준 함수 도구 (standard function tools)로 정규화
모델 검증 중 빈 messages	시드 사용자 메시지 (seed user message) 주입
stream: true + SSE 기대치	Cursor에 적절한 text/event-stream 반환
Kimi가 거부하는 사고/추론 (Thinking / reasoning) 필드	해당 필드 제거 또는 비활성화
지원되지 않는 샘플링 파라미터 (temperature, top_p, …)	제거 (K2.6은 고정된 샘플링을 사용함)

이것들은 수동으로 디버깅하는 데 몇 시간이 걸렸던 작업들입니다. 이 앱은 이를 자동으로 처리합니다.

Cursor는 보안상의 이유로 http://127.0.0.1:… 호출을 거부합니다.

Cloudflare Quick Tunnel을 사용하면 로컬 게이트웨이를 가리키는 임시 https://….trycloudflare.com URL을 얻을 수 있습니다.

트레이드오프 (Trade-off): 앱을 재시작하면 터널 URL이 변경될 수 있습니다. UI에서 변경 시점을 알려주므로, 새로운 Base URL을 복사하여 Cursor에 붙여넣으세요.

기능	제공 사항
원클릭 설정 마법사	API 키 → 게이트웨이 → 터널 → Cursor 지침
시스템 트레이 + 자동 시작	조용히 실행되며 재부팅 후에도 유지됨
Doctor 진단 도구	문제가 발생했을 때 11가지 자동 점검 수행
실시간 로그 + ZIP 내보내기	추측 없이 디버깅 가능
게이트웨이 키 로테이션 (Key rotation)	URL이 유출될 경우 터널을 잠금 처리
DPAPI 암호화된 Moonshot 키	실제 키가 로그나 Cursor에 노출되지 않음
Agent + MCP 호환	Kimi K2.6에 맞게 정제된 도구 호출 (Tool calls)
포터블 모드 (Portable mode)	설정이 .exe 파일 옆에 저장되어 USB 사용에 용이

Cursor Agent 모드에서도 작동하나요?

네. v1.1+ 버전은 특히 Agent + MCP 도구 페이로드 (payload)를 강화했습니다. 잘못된 도구 이름으로 인한 일반적인 HTTP 400 오류, 빈 메시지 프로브 (probes), 스트리밍 불일치 문제 등이 게이트웨이에서 처리됩니다.

왜 Cursor에서 Moonshot API 키를 직접 사용할 수 없나요?

세 가지 이유가 있습니다:

• Cursor는 OpenAI의 API 형태 (API shape)를 사용하며, Moonshot의 API는 유사하지만 완전히 동일하지는 않습니다.
• Cursor는 도구 스키마 (tool schemas)와 역할 (roles)을 전송하지만, Kimi는 번역 없이 이를 거부합니다.
• API가 작동하더라도, Cursor는 프라이빗/로컬 URL로의 직접적인 호출을 차단합니다.

게이트웨이가 이 세 가지 문제를 모두 해결합니다.

터널 URL이 변경되어 Cursor에서 오류가 발생합니다

Quick Tunnel URL은 일시적입니다. 앱이 터널을 재시작하면 새로운 trycloudflare.com 호스트 네임 (hostname)을 받게 됩니다.

해결 방법: 앱 대시보드에서 새로운 Base URL을 복사하여 Cursor → Settings → Models → Override OpenAI Base URL에 붙여넣으세요.

내 API 키는 안전한가요?

사용자의 Moonshot 키는 Windows DPAPI로 암호화되며 Cursor로 전송되지 않습니다. Cursor는 로컬에서 생성된 **게이트웨이 키 (gateway key)**만 확인합니다.

터널은 활성화된 동안 공개 상태이므로, URL을 아는 사람이라면 누구나 게이트웨이에 접속을 시도할 수 있습니다. 완화 방법으로는 게이트웨이 Bearer 인증 (Bearer auth), 키 순환 (key rotation), 사용하지 않을 때 게이트웨이 중단 등이 있습니다.

상세 내용: SECURITY.md

어떤 모델이 지원되나요?

게이트웨이는 Kimi K2.6 (kimi-k2.6)을 대상으로 합니다. Cursor에서 커스텀 모델 별칭 (custom model alias)을 추가하세요. 기본값은 gpt-5-high-max입니다. 다른 별칭들 (gpt-4-turbo, gpt-4o, …)도 매핑되어 작동합니다.

macOS나 Linux에서도 작동하나요?

아직은 지원하지 않습니다. 이번 릴리스는 Windows 10/11 전용입니다. 핵심 게이트웨이는 Rust로 작성되어 있어 포팅이 가능하며, 기여 (contributions)를 환영합니다.

앱 창을 계속 열어두어야 하나요?

앱은 **시스템 트레이 (system tray)**에 상주할 수 있습니다. 게이트웨이와 터널이 실행 중인 한 Cursor는 작동합니다. 항상 준비된 상태를 원한다면 자동 시작 (autostart)을 활성화하세요.

Cursor에서 "Access to private networks is forbidden"이라고 합니다

로컬 URL (127.0.0.1 또는 localhost)을 지정했기 때문입니다. Cursor는 설계상 이를 차단합니다. 앱에서 제공하는 공개 HTTPS Base URL (/v1으로 끝나는 trycloudflare.com 주소)을 사용하세요.

사전 요구 사항: Windows 10/11, Rust 1.70+, Node.js 18+

git clone https://github.com/Lolner95/use-kimi-on-cursor.git
cd use-kimi-on-cursor
npm install
...

프로덕션 설치 프로그램 (Production installer):

npm run tauri:build
# 출력: src-tauri/target/release/bundle/nsis/Kimi Cursor Gateway_1.0.0_x64-setup.exe

Portable 빌드 (설치 프로그램 없음):

npm run build:portable
# 출력: release-portable/Kimi Cursor Gateway/

라이브 통합 테스트 (Live integration tests) (실제 Moonshot 키 및 네트워크 필요):

npm run test:live

설치 모드(Installed mode)는 다음 경로에 데이터를 저장합니다:

%LOCALAPPDATA%\KimiCursorGateway\
config.json ← Moonshot 키 (DPAPI 암호화됨)
logs\
...

Portable 모드는 실행 파일 옆의 KimiCursorGatewayData/ 폴더를 사용합니다.

파일	내용
ARCHITECTURE.md	구성 요소, 엔드포인트 (endpoints), Sanitizer 규칙
...

방식	설정 시간	Agent/MCP 안정성?	유지보수
이 프로젝트	~5분	예 (목적에 맞게 제작됨)	낮음, 앱이 터널 (tunnel) 처리 및 수정 수행
수동 LiteLLM + cloudflared	1–3시간	취약함	높음, 모든 장애의 책임이 사용자에게 있음
Cursor 내 직접 Moonshot 사용	해당 없음	아니오	Cursor URL 정책에 의해 차단됨
기타 OpenAI 프록시 (proxies)	가변적	복불복	프로토콜 불일치(protocol mismatches)를 직접 디버깅해야 함

버그를 발견하셨나요? 이슈 (issue)를 생성해 주세요.

해결책이 있으신가요? PR (Pull Request)을 환영합니다. 변경 사항은 집중적으로 유지해 주시고, 게이트웨이 (gateway)를 수정하는 경우 실제 Cursor + Kimi 환경에서 테스트해 주세요.

보안 문제: SECURITY.md를 참조하시고, 먼저 비공개로 보고해 주시기 바랍니다.

Cursor에서 Kimi를 사용하는 것이 리버스 프록시 (reverse proxies) 박사 학위까지 요구해서는 안 됩니다.

이 프로젝트가 당신의 불필요한 작업 (yak-shaving) 시간을 아껴주었다면, 저장소(repo)에 스타 (star)를 눌러주세요. 다른 사람들이 이 프로젝트를 찾는 데 큰 도움이 됩니다.