서론

'마인크래프트 세계에서 자연어 지시를 이해하고 움직이는 Bot을 만들고 싶다. 하지만, AI의 API나 Bot의 상시 구동에 큰돈은 쓰고 싶지 않다.'와 같은 경우의 설계 패턴을 소개합니다.

이 글에서는 Jev를 지시 및 대화 흐름을 정리하는 애플리케이션 계층으로 사용하고, Gemini에게 행동을 생각하게 하며, Mineflayer로 Minecraft Java Edition 서버에 연결합니다. Cloudflare Workers는 외부 접수나 AI 호출의 창구로 사용하며, 게임 연결을 유지하는 Bot 본체와 역할 분담을 합니다.

이 글은 설계 예시입니다. 대상 리포지토리에는 Bot 구현이나 Jev의 API 정의가 포함되어 있지 않으므로, 특정 Jev SDK/API가 그대로 동작한다고 주장하지 않습니다. Jev의 실제 인터페이스에 맞춰서 후술하는 buildPrompt 등을 대체해 주십시오.

미리 알아두어야 할 점

'월 몇 원'은 기존의 머신을 Bot 실행 장소로 사용하고, 각 서비스의 무료 범위 내에 수렴되었을 경우의 목표입니다. Mineflayer는 Minecraft 서버 연결을 유지하는 Node.js 프로세스이므로, Cloudflare Workers 안에서 Bot을 상시 구동할 수는 없습니다. Bot을 구동할 머신을 새로 계약할 경우, 그 요금만으로 월 몇 원을 초과할 수 있습니다.

Gemini나 Cloudflare의 무료 범위/요금, 사용 가능한 모델은 변경될 수 있습니다. 무료 범위 초과 시의 요금을 포함하여 공개 전에 각 서비스의 최신 조건을 확인해 주십시오. 이 글의 구성이 '반드시 월 몇 원'을 보장하는 것은 아닙니다.

아키텍처

┌──────────────────────┐
│ 조작자 / Web UI │
└──────────┬───────────┘
...

Worker와 Bot 사이를 HTTPS로 하면, Bot 측에서 외부로 연결할 수 있게 됩니다. Minecraft 서버 연결은 Bot이 담당합니다. Worker에 게임 연결을 시키거나, AI의 응답을 그대로 게임 내 커맨드로 실행하지 않는 것이 핵심입니다.

컴포넌트별 책임

Jev: 지시와 대화의 문맥을 정리

Jev 계층에서는 사용자의 자연어, Bot의 역할, 현재 상황, 실행 가능한 행동을 하나의 입력에 모읍니다. 게임 내 채팅을 그대로 프롬프트에 연결하는 것이 아니라, 길이와 제어 문자 등을 제한하고 신뢰할 수 없는 발언을 명령으로 취급하지 않도록 설계합니다.

Gemini: 행동 후보를 구조화하여 반환

Gemini에게는 자유 형식의 문장이 아닌, 사전에 정해진 행동 중 하나를 선택하게 합니다. 응답은 반드시 스키마 검증하고, 예상치 못한 값이나 모호한 응답은 실행하지 않고 종료합니다.

Mineflayer: 게임 내 조작 담당

Mineflayer는 게임 서버 연결, 상태 획득, 허가된 행동의 실행을 담당합니다. AI의 응답을 Minecraft 커맨드로 직접 흘려보내지 않고, 애플리케이션 측의 행동 함수에 대응시킵니다.

Cloudflare Workers: 가벼운 API 창구 역할

Worker는 인증, 입력 검증, AI 호출, 결과 반환 등 짧은 시간으로 완료되는 HTTP 처리에 적합합니다. Mineflayer와 같이 TCP 연결을 장시간 유지하는 처리는 Worker에 두지 않고, Bot을 구동하는 Node.js 환경과 분리합니다.

행동 제한하기

다음은 자연어를 애플리케이션 내의 허가된 행동으로 변환하는 TypeScript 예시입니다. Jev 고유의 SDK를 보여주는 것이 아니라, Jev의 프롬프트 생성/Gemini 호출 부분에 연결되는 경계의 예입니다.

type BotAction =
|	{ type: 

API 키는 코드나 GitHub에 포함하지 않고, Worker의 Secret으로 등록합니다. 아래는 '모델이 반환한 JSON을 앱 측에서 추가로 검증한다'는 흐름을 보여주는 개념 예시입니다. 모델명이나 SDK 호출 형식은 사용하려는 Gemini API의 현재 사양에 맞춰주세요.

interface Env {
GEMINI_API_KEY: string;
}
...


`extractModelText`

은 Gemini의 응답 타입에 맞게 구현해야 합니다. JSON 모드를 지정하더라도 네트워크 오류, 상한 도달, 빈 응답, 손상된 JSON 등은 발생할 수 있습니다. 실패 시에는 행동을 실행하지 않는 fail-closed 방식으로 처리합니다.

## Mineflayer 측에서 행동을 실행하기

Worker로부터 받은 값도 신뢰하지 않고, Bot 측에서 재차 검증한 후에 Mineflayer API에 전달해야 합니다. 다음은 행동을 함수에 대응시키는 예시입니다.

import mineflayer from "mineflayer";
const bot = mineflayer.createBot({
host: process.env.MINECRAFT_HOST!,
...


추종이나 채광 등의 작업을 추가할 때도, 행동을 하나씩 추가하고 대상/거리/시간 상한 및 중단 조건을 설정해야 합니다. 서버 운영자의 허가를 받은 환경에서만 Bot을 연결하고, 서버의 규칙과 다른 플레이어의 경험을 존중해 주세요.

## Bot과 Worker 간 통신

상시 연결을 전제로 한 시스템을 만들기 전에, 최소 구성에서는 Bot이 Worker에게 주기적으로 지시를 가져오는 방식이 처리하기 쉽습니다.

async function pollCommand(workerUrl: string, botToken: string) {
const response = await fetch(${workerUrl}/api/commands/next, {
headers: { Authorization: Bearer ${botToken} },
...


토큰은 환경 변수 등의 Secret 관리 수단에 저장하고, Bot별로 발급 및 만료가 가능하도록 합니다. 폴링 간격을 너무 짧게 잡지 말고, 연속 실패 시에는 대기 시간을 늘리는 백오프(backoff)를 구현합니다. Worker 측에서는 인증, 요청 크기 제한, 레이트 제한, 중복 실행 방지를 수행해야 합니다. 태스크를 여러 개 보유하는 단계가 되면, 이용 규모와 요금을 확인한 후 큐 등으로 교체합니다.

## 운영 비용을 낮게 유지하는 방법들

- Gemini에게는 행동 선택이 필요할 때만 문의한다.
- 대화 기록이나 주변 상황은 최소한으로 하고, 매번 많은 로그를 보내지 않는다.
- 1인당 빈도 상한, 쿨다운, 1회 행동 시간을 설정한다.
- 'say', 'follow', 'stop' 등 소수의 행동부터 시작하고, 위험한 임의 명령을 허용하지 않는다.
- Worker 이용량, Gemini 이용량, Bot 실행 환경 비용을 각각 모니터링한다.
- 무료 범위를 초과했을 때 의도치 않은 과금이 계속되지 않도록 상한/알림/정지 절차를 마련한다.

실제 월별 비용은 Bot을 구동하는 머신, 가동 시간, AI 이용량, 각 서비스의 요금 체계에 따라 달라집니다. 본인 장비를 사용할 경우에도 전기세나 네트워크 비용은 별도로 고려해야 합니다.

## 로컬에서 테스트하기

우선 Worker나 공개 서버를 사용하지 않고, 본인 장비에서 Bot과 Minecraft 서버를 연결하여 동작 확인을 합니다. Zenn 기사의 프리뷰는 리포지토리 루트에서 실행할 수 있습니다.

Zenn CLI의 의존성을 설치

npm install

기사 미리보기 (http://localhost:8000)

...


Bot을 구동하는 경우, Minecraft 서버 연결 정보나 API 키를 `.env` 등에서 관리하고, `.env` 파일을 Git에 추가하지 마세요. 공개하기 전에 의도치 않은 행동을 하지 않는지, AI API가 실패했을 때 멈추는지, Bot을 안전하게 끊을 수 있는지 확인해야 합니다.

## 🚀 공개 리포지토리

코드는 모두 GitHub에서 오픈 소스로 공개하고 있습니다.

## 📦 사용 방법 (배포 절차)

### 1. 리포지토리 클론

git clone https://github.com/fk2000/minecraft-ai-bot.git
cd minecraft-ai-bot
npm ci
...


### 2. 환경 변수 설정

`.env` 파일을 편집하여 Minecraft 서버 연결지, Bot 계정, Jev API 키를 설정합니다. 실제 API 키나 인증 정보는 Git에 커밋하지 마세요. Gemini의 대화 기능을 사용할 경우에는 `GEMINI_API_KEY`도 설정해야 합니다.

### 3. 컨테이너 빌드 및 실행

npm run build:container
npm run start:container


Discord 연동 등 임의 기능에 대한 자세한 설정은 공개 리포지토리의 README를 확인해 주세요. Minecraft 서버 운영자의 허가를 받은 환경에서 사용하고, 각 서비스의 이용 약관과 서버 규칙을 준수해야 합니다.

## 요약

Jev로 지시를 구성하고, Gemini로 허가된 행동을 선택하며, Mineflayer로 게임에 연결합니다. 이처럼 역할을 분담하면 AI의 생성 결과를 그대로 실행할 위험을 줄이고, 각 컴포넌트를 독립적으로 테스트할 수 있습니다. Cloudflare Workers는 HTTP 접수나 짧은 처리에 사용하고, Mineflayer의 장시간 연결은 Node.js 프로세스에 맡기는 것이 중요합니다.

월 몇 원이라는 비용은 이용 조건이나 실행 환경에 따라 달성할 수 없으므로, 무료 사용량과 상시 가동 비용을 반드시 개별적으로 견적해 보세요. 안전한 작은 행동부터 시작하고, 로그와 제한을 정리한 후에 기능을 확장합시다.

읽고 도움이 되었다면 Zenn의 '좋아요'나 배지 등의 지원 기능으로 응원해 주시면 감사하겠습니다.

### Discussion

![](https://static.zenn.studio/images/drawing/discussion.png)

【개인 개발】Jev×Gemini×Mineflayer로 월 몇 원으로 구동되는 마인크래프트 AI Bot 설계 패턴 [GitHub 공개]

요약

핵심 포인트

서론