Mineflayer ChatGPT

Mineflayer ChatGPT is a Mineflayer plugin for sending and receiving messages with OpenAI ChatGPT or any other services having OpenAI-compatible API.

The minimum supported OpenAI model is GPT-5.6. OpenAI-compatible services must support Chat Completions Structured Outputs using JSON Schema.

Installation

npm install mineflayer-chatgpt

or as a dependency in package.json file:

"dependencies": {
    "mineflayer-chatgpt": "x.y.z"
}

Usage

Load the plugin:

import mineflayerChatgpt from 'mineflayer-chatgpt';

...

bot.loadPlugin(mineflayerChatgpt.chatgpt);

Set the configuration:

bot.chatgpt.setConfig({
    messageApiKey: 'sk-1234567890abcdef',
    moderationApiKey: 'sk-1234567890abcdef',
    model: 'gpt-5.6',
    historySize: 20,
    enableModeration: true,
    coolDownInSeconds: 15,
    minimumReplyConfidenceScore: 0.9,
    enableMessageLogging: true
});

messageApiKey and moderationApiKey are configured separately so that chat completions and moderation can use different providers. For example, point messageBaseURL at a local OpenAI-compatible LLM server (e.g. vMLX) to use a local model for chat, while still using a real OpenAI key for moderationApiKey to keep moderation checks against OpenAI's moderation endpoint:

bot.chatgpt.setConfig({
    messageApiKey: 'not-needed-by-local-server',
    messageBaseURL: 'http://localhost:8080/v1',
    moderationApiKey: 'sk-1234567890abcdef'
});

Send a message to ChatGPT:

bot.chatgpt.sendMessage('player', 'How to craft a diamond sword in Minecraft?');

Configuration

| Property | Description | Type | Required | Default | Example | |----------|-------------|------|----------|---------|---------| | messageApiKey | API key for the chat completion endpoint. Can be any placeholder value for local LLM servers that don't require authentication. | string | Yes | - | sk-1234567890abcdef | | moderationApiKey | OpenAI API key used for moderation and OpenAI Guardrails jailbreak detection. Required when enableModeration is true. | string | Only if enableModeration is true | - | sk-1234567890abcdef | | messageBaseURL | Base URL of the chat completion endpoint. Set this to use a local OpenAI-compatible LLM server (e.g. vMLX) instead of OpenAI. | string | No | OpenAI's default base URL | http://localhost:8080/v1 | | model | Chat completion model name. The minimum supported OpenAI model is GPT-5.6. | string | No | gpt-5.6 | gpt-5.6-sol | | instructions | Base developer instructions prepended to every conversation. Security instructions are appended internally when enableSecurityInstructions is true. | string | No | You are a helpful assistant in a Minecraft world. Answer questions and provide information relevant to the game. | You are a concise Minecraft redstone expert. | | historySize | Maximum number of messages kept per-player in memory. | number | No | 20 | 50 | | enableSecurityInstructions | Appends security instructions to the base instructions for hardening the model against prompt injection and other LLM threats. | boolean | No | true | false | | enableModeration | Enables outbound and inbound moderation checks. | boolean | No | true | false | | coolDownInSeconds | Minimum seconds required between a player's latest prior message and the next outbound message. | number | No | 15 | 30 | | minimumReplyConfidenceScore | Minimum accepted self-reported reply confidence score. Replies below this threshold are replaced by fallbackMessage. | number | No | 0.9 | 0.8 | | minimumJailbreakConfidenceScore | Minimum OpenAI Guardrails confidence required to classify an outbound message as a jailbreak attempt. | number (0–1) | No | 0.7 | 0.8 | | enableMessageLogging | Logs model replies to console output. | boolean | No | false | true | | fallbackMessage | Response returned when moderation, cooldown, or confidence checks fail. | string | No | Sorry, I cannot provide a response to that message. | Please wait a moment before sending another message. |

Security

Mineflayer ChatGPT attempts to implement OWASP Top 10 LLM apps recommendations.

LLM01 - Prompt Injection

• Security instruction hardening is appended to base instructions when enableSecurityInstructions is true, including explicit anti-override rules.
• Jailbreak attempts are detected before outbound moderation via OpenAI Guardrails. The sensitivity is configured with minimumJailbreakConfidenceScore.
• Jailbreak-like outbound content is blocked and replaced with fallbackMessage.

LLM02 - Sensitive Information Disclosure

• Player memory is isolated per player conversation to reduce cross-user leakage risk.
• Secret and credential pattern detection is applied to both outbound messages and inbound replies.
• Sensitive-looking content is blocked and replaced with fallbackMessage.

LLM03 - Supply Chain

• Trusted publisher on npmjs.com
• Please don't hack us. We're just an amateur family game lab.

LLM04 - Data and Model Poisoning

• Security instructions include guidance that external content may be untrusted.
• TODO: Explicit poisoning classifier, provenance validation, or trust scoring pipeline is implemented. This might be necessary on a modded Minecraft universe.

LLM05 - Improper Output Handling

• Slash commands are detected in inbound replies via detectSlashCommand.
• Replies containing slash commands are blocked and replaced with fallbackMessage.
• Security instructions include "Never generate executable commands."

LLM06 - Excessive Agency

• No tool-calling or autonomous action layer is exposed by Mineflayer ChatGPT.
• No additional explicit policy gate for agentic actions is implemented because actions are limited to returning chat text.

LLM07 - System Prompt Leakage

• Security instructions explicitly forbid revealing system prompts.
• Prompt leakage detection checks replies against security instruction strings.
• Suspected leakage is blocked and replaced with fallbackMessage.

LLM08 - Vector and Embedding Weaknesses

• Domain scoping instruction restricts responses to Minecraft-related topics.
• No vector database, hence no embedding retrieval or retrieval-integrity controls.

LLM09 - Misinformation

• Security instructions tell the model to avoid fabrication and acknowledge uncertainty.
• Inbound replies are confidence-gated; low-confidence replies are replaced with fallbackMessage.

LLM10 - Unbounded Consumption

• Security instructions enforce concise responses.
• Per-player history is bounded by historySize.
• Outbound message rate is gated with cooldown enforcement (coolDownInSeconds).

Colophon

Developer's Guide

Build reports:

• Code complexity report
• Unit tests report
• Test coverage report
• Integration tests report
• API Documentation

Related projects:

• minecraft-npc - CLI for running NPC bot on Minecraft, powered by Mineflayer