OpenCode에서 Kimi K2.5를 Novita AI와 연결하기: 에이전트 코딩 가이드

에이전트 코딩은 자동 완성 그 이상으로 나아가고 있습니다: 현대 도구는 작업을 계획하고, 여러 파일을 편집하고, 명령을 실행하며, 결과가 실제로 작동할 때까지 실패를 반복할 수 있습니다. OpenCode는 터미널(데스크톱 앱 또는 IDE 확장 프로그램으로도 사용 가능)에서 실행할 수 있는 오픈 소스, 모델에 구애받지 않는 코딩 에이전트로, 이 워크플로를 자신의 환경에서 시도해볼 수 있는 실용적인 방법입니다.

💡이 가이드에서 배울 내용:

• Kimi K2.5를 **Novita AI의 API**를 통해 OpenCode에 연결하기
• 원하는 인터페이스(터미널/데스크톱/IDE)에서 사용할 수 있도록 OpenCode 설치 및 준비
• 작은 데모 프로젝트 구축하기

OpenCode란?

OpenCode는 여러 개발자 환경에서 실행할 수 있는 오픈 소스 AI 코딩 에이전트로, 가장 일반적으로는 터미널 기반 인터페이스(CLI + TUI)로 사용되지만 데스크톱 앱 또는 IDE 확장 프로그램으로도 사용할 수 있습니다.

OpenCode vs Claude Code

OpenCode와 Claude Code는 모두 터미널 기반 AI 코딩 에이전트이지만, 접근 방식이 다릅니다.

• OpenCode는 오픈 소스, 제공자에 구애받지 않는 에이전트입니다: “Models.dev를 통한 75개 이상의 LLM 제공자(로컬 모델 포함) 지원”을 강조하며, 다양한 모델 백엔드에 연결할 수 있는 유연한 도구로 자리 잡고 있습니다.
• Claude Code는 반면 Anthropic의 공식 Claude 우선 CLI입니다. 터미널에서 Claude 모델에 액세스하기 위한 명령줄 도구이며, MCP를 통한 확장(플러그인) 및 도구/데이터 연결을 위한 공식 생태계를 갖추고 있습니다.

빠른 비교표

측면	OpenCode	Claude Code
포지셔닝	오픈 소스, 다중 모델 터미널 코딩 에이전트	Anthropic의 공식 Claude 우선 터미널 코딩 에이전트
모델/제공자 선택	Models.dev를 통한 75개 이상의 LLM 제공자, 로컬 모델 포함	Claude 기반; MCP + 플러그인을 통해 확장
GitHub 자동화	/opencode 또는 /oc 댓글 트리거; GitHub Actions 러너에서 실행	확장은 플러그인/MCP에 초점(공식 생태계)
가격 진입점	도구는 오픈 소스; 비용은 선택한 모델 백엔드에 따라 다름	Claude 요금제 (Pro/Max/Team/Enterprise)

왜 Kimi K2.5인가?

Kimi K2.5는 네이티브 멀티모달, 실제 도구 실행, 대규모 에이전트 오케스트레이션을 하나의 오픈 모델로 결합합니다. 약 15T 혼합 비전-텍스트 토큰으로 훈련되어 이미지/비디오 이해, 코드 생성 및 시각적 디버깅을 포괄합니다.

지금 Kimi M2.5 사용해보기!

출처: Kimi

실용적인 요점

• GPT-5.2, Claude 4.5 Opus, Gemini 3 Pro 대비 강력한 에이전트 벤치마크: 차트에서 Kimi K2.5는 에이전트 평가 제품군에서 선두를 차지합니다: HLE-Full 50.2, BrowseComp 74.9, DeepSearchQA 77.1. BrowseComp에서 K2.5는 GPT-5.2(65.8), Claude 4.5 Opus(57.8), Gemini 3 Pro(59.2)를 앞서며 - 브라우징, 증거 수집, 반복적 개선이 필요한 장기 작업에 유용합니다.
• 다국어 우위를 가진 경쟁력 있는 레포 수준 코딩: K2.5는 SWE-Bench Verified 76.8 및 SWE-Bench Multilingual 73.0을 기록합니다. Claude 4.5 Opus가 Verified(80.0)에서 약간 높고 Gemini 3 Pro도 선두(80.9)를 차지하지만, K2.5는 강력한 경쟁력을 유지하며 다국어 설정에서 두각을 나타냅니다 - GPT-5.2(72.0)보다 앞서고 Gemini 3 Pro(65.0)보다 훨씬 앞서며, 이는 혼합 언어 레포의 다중 파일 패치에 중요합니다.
• 개발자 워크플로(문서, 다이어그램, UI)를 위한 강력한 이미지 이해: 이미지 벤치마크에서 K2.5는 일관되게 최고 수준입니다: MMMU Pro 78.5, MathVision 84.2, OmniDocBench 1.5 88.8 - 기술 PDF 읽기, 다이어그램 해석, 시각적 요구 사항을 코드로 변환하는 실용적인 작업을 지원합니다.
• 실제 제품 반복에 도움이 되는 비디오 추론: 비디오 작업의 경우 K2.5는 VideoMMMU 86.6 및 LongVideoBench 79.8을 기록하여, 더 강력한 장문맥 비디오 이해 능력을 나타냅니다 - 제품 데모 분석, UI 녹화 디버깅, 워크스루에서 요구 사항 추출에 유용합니다.

OpenCode 설치 방법

OpenCode는 몇 가지 설치 옵션을 제공합니다. 가장 빠른 방법은 한 줄 설치 스크립트이며, 가장 이식성이 좋은 방법은 npm 패키지를 설치하는 것입니다.

macOS / Linux

권장:

curl -fsSL https://opencode.ai/install | bash

또는 (크로스 플랫폼):

npm install -g opencode-ai
# or
bun add -g opencode-ai

시작:

opencode

Windows

권장:

npm install -g opencode-ai
# or
bun add -g opencode-ai

curl | bash는 bash 환경(WSL 또는 Git Bash)이 필요합니다. PowerShell/CMD에서는 npm/bun을 사용하세요.

시작:

opencode

OpenCode에서 MiniMax M2.1 사용 방법

Novita AI에서 API 키 가져오기

• 1단계: 계정 생성 또는 로그인 [https://novita.ai](https://novita.ai)를 방문하여 가입하거나 로그인하세요.
• 2단계: 키 관리로 이동 로그인 후 “API Keys”를 찾으세요.
• 3단계: 새 키 생성 “Add New Key” 버튼을 클릭하세요.
• 4단계: 키를 즉시 저장 생성된 키를 복사하여 저장하세요. 일반적으로 한 번만 표시됩니다.

API 키 받기

OpenCode에 Novita API 키 추가하기

1. OpenCode를 실행합니다:

opencode

2. OpenCode 프롬프트에서 다음을 실행합니다:

/connect

3. Novita AI를 검색하여 선택한 후, Novita API 키를 붙여넣습니다.
4. Kimi K2.5(모델 ID: moonshotai/kimi-k2.5)를 선택합니다.

이제 끝입니다. OpenCode는 선택한 모델을 사용하여 Novita AI의 API를 통해 에이전트 요청을 라우팅합니다.

첫 번째 프로젝트 구축: Woolf Stream

데모를 즉시 시각적으로 만들고(스크린샷으로 공유하기 쉽게) 단일 페이지 웹 앱인 Woolf Stream을 구축하겠습니다. 사용자가 이미지를 업로드하고, 몇 가지 크리에이티브 컨트롤을 선택하면, 앱이 Novita AI의 OpenAI 호환 채팅 엔드포인트(Kimi K2.5, 이미지 채팅 지원)를 호출하여 20세기 초 모더니스트 기법에서 영감을 받은 스트림 오브 컨셔스니스 산문을 생성합니다(버지니아 울프를 그대로 인용하거나 모방하지 않음).

구축할 내용

• 단일 페이지 Next.js 14 (App Router) 데모 with TypeScript + TailwindCSS
• API 키 패널 (비밀번호 입력 + 표시/숨기기, localStorage에 저장/지우기; 하드코딩 금지)
• 드래그 앤 드롭 이미지 업로드 (png/jpg) with 미리보기 및 클라이언트 측 base64 데이터 URL 변환
• 컨트롤:
  • 길이 사전 설정: 150 / 300 / 600 / 1000 단어
  • 톤 슬라이더: dreamy ↔ sharp
  • 초점 드롭다운: sensory / memory / time / social gaze
• 생성 흐름:
  • “Generate Prose” 버튼은 API 키 + 이미지가 모두 있을 때까지 비활성화
  • 로딩 표시기 + HTTP 상태 및 문제 해결 힌트가 포함된 오류 패널
• 출력:
  • 생성된 산문이 있는 읽기 카드
  • 복사 버튼 + .txt 다운로드
  • “사용된 프롬프트 보기” 아코디언 (투명성 및 재현성을 위해)

빌드 모드로 전환 및 실행

OpenCode에서 빌드 모드로 전환한 후 아래 프롬프트를 붙여넣으세요.

프롬프트

Next.js 14 (App Router) + TypeScript + TailwindCSS를 사용하여 단일 페이지 데모를 빌드하세요.

목표: 사용자가 이미지(png/jpg)를 업로드합니다. 앱은 이미지를 OpenAI 호환 채팅 엔드포인트(이미지 채팅 지원)로 보내고, 버지니아 울프의 모더니스트 기법에서 영감을 받은 아름다운 스트림 오브 컨셔스니스 산문 구절을 생성합니다. 출력은 텍스트 전용입니다.

API 요구 사항 (엄격):

• OpenAI 호환 사용자 지정 기본 URL: https://api.novita.ai/openai
• 모델: moonshotai/kimi-k2.5
• 사용자는 자신의 API 키를 입력합니다(비밀번호 필드 + 표시/숨기기). localStorage에만 저장합니다. 하드코딩하지 마세요.
• 요청에는 Authorization: Bearer {userKey}가 포함됩니다.

UI 요구 사항:

• Monet / Water Lilies 분위기 UI: 부드러운 파스텔 팔레트, 종이 질감, 미묘한 붓터치 그라데이션 배경, 부드러운 글로우 그림자, 둥근 카드, 작은 리플 호버 애니메이션. 모바일 반응형.
• 컴포넌트: API 키 저장/지우기, 드래그&드롭 업로드 + 미리보기, 컨트롤: 길이(150/300/600/1000 단어), 톤 슬라이더(dreamy↔sharp), 초점 드롭다운(sensory/memory/time/social gaze), 생성 버튼(키나 이미지 없으면 비활성화), 로딩 표시기, 오류 패널.
• 출력: 읽기 카드로 렌더링된 산문 + 복사 + .txt 다운로드 + “사용된 프롬프트 보기” 아코디언.

멀티모달 호출 (필수):

• POST /v1/chat/completions를 사용하세요.
• 콘텐츠가 다음 두 가지를 모두 포함하는 배열인 메시지를 전송하세요:

{type:“text”, text:”…지시사항…”}

{type:“image_url”, image_url:{url:“data:image/png;base64,…”}}

• 모델의 텍스트 응답을 표시하세요.

작문 제약 (중요):

• 20세기 초 모더니스트 스트림 오브 컨셔스니스(서정적 리듬, 내면성, 감각적 디테일, 연상적 도약, 유동적 시간)에서 영감을 받은 독창적인 산문을 생성하세요.
• 울프의 텍스트를 인용하거나 재생산하지 마세요. 울프인 척 하지 마세요. 직접적인 패스티시 라인 금지.
• 이미지에 고정: 구도, 빛, 색상, 분위기, 암시된 움직임 반영; 피사체 배치 유지.
• 출력: 하나의 연속된 구절(최대 1-3 문단). 글머리 기호 없음, 분석 없음.

제공 사항:

• 완전히 실행 가능한 코드 + 파일 트리.
• base_url과 사용자 키를 주입하는 API 래퍼.
• 클라이언트 측 이미지 → base64 데이터 URL.
• HTTP 상태 코드 및 문제 해결 힌트가 포함된 명확한 오류.

로컬에서 실행

OpenCode가 프로젝트를 생성한 후:

npm install
npm run dev

Next.js가 출력한 로컬 URL(보통 http://localhost:3000)을 열고 다음을 확인하세요:

• 페이지가 Monet / Water Lilies 느낌으로 렌더링됨
• API 키 저장/지우기가 작동(localStorage에만 저장), 표시/숨기기 토글이 올바르게 작동
• 드래그 앤 드롭 업로드가 작동하고, 미리보기에 선택한 이미지가 표시됨
• “Generate Prose” 버튼이 API 키 + 이미지가 모두 있을 때까지 비활성화됨
• 산문은 텍스트 전용, 1-3 문단, 분명히 이미지 기반
• 복사 + .txt 다운로드가 작동
• “사용된 프롬프트 보기”가 전송된 정확한 프롬프트를 표시
• 오류(잘못된 키 / 네트워크)가 HTTP 상태 및 명확한 힌트를 표시

데모: Woolf Stream

터미널 너머의 OpenCode: 데스크톱 앱 + IDE 통합

OpenCode는 종종 터미널에서 사용되지만, 데스크톱 앱(베타) 또는 IDE 내에서도 실행할 수 있으며, 두 경우 모두 Novita AI의 OpenAI 호환 API를 계속 사용할 수 있습니다. 인터페이스는 변경되지만 모델/제공자 설정은 동일하게 유지됩니다: minimax/minimax-m2.1을 선택하세요.

데스크톱 앱

OpenCode의 데스크톱 빌드는 macOS, Windows, Linux에서 사용할 수 있습니다. 긴 에이전트 세션을 위해 독립형 UI를 선호한다면 데스크톱 앱이 좋은 선택이며, 이미 Novita AI용으로 만든 제공자 구성을 사용할 수 있습니다.

IDE 통합

OpenCode는 다음을 위한 공식 통합 흐름을 제공합니다:

• VS Code
• Cursor
• Zed
• Windsurf
• VSCodium

결론

OpenCode를 사용하면 한 공급업체에 종속되지 않고 에이전트 워크플로를 쉽게 채택할 수 있습니다. Novita AI의 Kimi K2.5를 사용하면 레포 수준 반복 및 멀티모달 개발 작업을 위한 실용적인 설정을 얻을 수 있으며, 동일한 API 구성으로 터미널(또는 데스크톱/IDE)에서 사용할 수 있습니다.

API 키 받기

Novita AI는 개발자가 간단한 API를 사용하여 AI 모델을 쉽게 배포할 수 있도록 지원하는 AI 클라우드 플랫폼이며, 또한 구축 및 확장을 위한 저렴하고 안정적인 GPU 클라우드를 제공합니다.

자주 묻는 질문

OpenCode란 무엇인가요?

OpenCode는 오픈 소스 AI 코딩 에이전트 프레임워크로, LLM이 실제 개발 환경에서 코드를 작성, 실행, 디버깅할 수 있게 하여 종단 간 빌드 속도를 높입니다.

OpenCode의 소유자는 누구인가요?

OpenCode는 Claude나 Gemini와 같은 대형 AI 연구소가 소유하지 않았습니다. 이는 OpenCode 팀/커뮤니티가 유지 관리하는 오픈 소스 프로젝트로, opencode.ai의 제작자가 개발을 주도합니다. 독점적인 “모델 소유자”는 없으며, 프로젝트는 제공자에 구애받지 않으며 단일 LLM 공급업체와 독립적으로 설계되었습니다.

OpenCode가 Claude보다 더 나은가요?

OpenCode는 엄밀히 말해 Claude Code보다 “더 낫다”고 할 수 없습니다. 차이가 있습니다. OpenCode는 오픈 소스이며 모델에 구애받지 않아, 유연성을 원하고 하나의 에이전트 워크플로에서 여러 모델(예: Novita AI를 통한 Kimi K2.5)을 실행할 자유를 원한다면 더 나은 선택입니다. 반면 Claude Code는 Anthropic의 공식 Claude 우선 CLI로, Claude 생태계에 완전히 투자했다면 가장 매끄러운 경험을 제공합니다.

OpenCode는 안전한가요?

네, OpenCode는 코드나 컨텍스트 데이터를 저장하지 않으므로 개인정보 보호에 민감한 환경에서 작동할 수 있습니다.

OpenCode는 무료인가요?

OpenCode는 드물게 멈추게 하는 오픈 소스 도구 중 하나입니다. 현재 GitHub에서 80,000개 이상의 별을 받고 있으며, 사용해 본 후에는 그 인기가 타당하다는 것을 알게 됩니다. Claude Code와 같은 AI 코딩 에이전트이지만 완전히 무료이며 오픈 소스입니다.