Mindcraft 完整上手指南：用 LLM + Mineflayer 打造 Minecraft AI 智能体

AI Agent人工智能游戏开发【免费下载链接】mindcraftMinecraft AI with LLMsMineflayer项目地址https://gitcode.com/GitHub_Trending/mi/mindcraft点击查看免费下载Mindcraft 是一个把大语言模型LLM与 Mineflayer 机器人框架结合的开源项目它让 AI 智能体能够真正住进《我的世界》Java 版智能体可以通过自然语言对话、自主感知环境、采集资源、合成物品、建造建筑并支持多智能体协作。阅读本文后你将掌握 Mindcraft 从环境准备、安装运行到模型配置、任务编排、容器化部署的完整实战流程并能读懂其配置文件与源码级实现细节直接上手运行自己的 Minecraft AI。本指南以仓库根目录的 README.md 为骨架展开并辅以 settings.js、main.js、minecollab.md 等源码与文档进行深度印证。一、项目速览与安全警告Mindcraft 的定位用一句话概括用 LLM 与 Mineflayer 为 Minecraft 打造智能大脑Crafting minds for Minecraft with LLMs and Mineflayer。智能体不再是简单的脚本机器人而是由一个或多个大模型驱动的、具备感知-推理-行动闭环的自主 Agent。[!Caution]不要将开启了编码coding功能的机器人连接到公共服务器。本项目允许 LLM 在你的电脑上编写并执行代码代码运行在沙箱环境中但依然存在被注入攻击injection attacks的风险。代码写作功能默认关闭你需要在settings.js中将allow_insecure_coding设为true才能开启——后果自负。这是 README 中反复强调的第一原则Mindcraft 的能力边界越大安全风险也越高。当你决定开启自由编码能力时官方强烈建议配合 Docker 容器运行见第五节。二、环境要求Requirements在开始之前请确保满足以下三项硬性条件依赖要求说明Minecraft Java 版最高支持v1.21.11推荐v1.21.6通过局域网开放端口供机器人连接Node.jsv18 或 v20 LTS推荐Node v24 可能因原生依赖native dependencies出问题API Key至少一个受支持 API 提供商的密钥默认使用 OpenAI两个重要的安装提示README 原文强调在 Windows 上安装 Node.js 时务必勾选Automatically install the necessary tools自动安装必要工具否则原生模块编译会失败在 macOS 上如果npm install报错参见 FAQ 中的 Common Issues 章节排查原生模块构建问题。三、安装与运行Install and Run按照 README 的六步流程从零启动一个 Mindcraft 智能体确认前置条件具备上面的 Minecraft、Node.js 和至少一个 API Key获取代码下载 latest release 并解压或直接 clone 本仓库配置密钥将keys.example.json重命名为keys.json并填入你的 API Key只需填一个你用的提供商。模型在andy.json或其他 profile 文件中指定其他模型可参考第六节的 API 表格安装依赖在安装目录的终端中执行npm install开启游戏启动一个 Minecraft 世界并将其开放到局域网LAN端口为55916启动机器人在安装目录运行node main.js。仓库中的 keys.example.json 展示了所有受支持 API 提供商的密钥变量名例如OPENAI_API_KEY、GEMINI_API_KEY、ANTHROPIC_API_KEY、DEEPSEEK_API_KEY、QWEN_API_KEY、MISTRAL_API_KEY、XAI_API_KEY、REPLICATE_API_KEY、GROQCLOUD_API_KEY、HUGGINGFACE_API_KEY、NOVITA_API_KEY、OPENROUTER_API_KEY、GHLF_API_KEY、HYPERBOLIC_API_KEY、CEREBRAS_API_KEY、MERCURY_API_KEY等。每个 key 对应一个 profile 文件profiles/ 目录下提供了gpt.json、claude.json、gemini.json、llama.json、qwen.json、grok.json、mistral.json、deepseek.json等现成模板。如果遇到问题先查 FAQ 或在 Discord 上寻求支持GitHub issue 的响应并不及时。要运行任务Tasks参见 Minecollab 说明。启动背后的代码逻辑从源码看main.js 是整个启动入口它使用 yargs 解析命令行参数将--profiles传入的参数直接覆盖settings.profiles然后调用Mindcraft.init()初始化 mindserver再为每个 profile 调用Mindcraft.createAgent()创建智能体。也就是说每份 profile JSON 对应一个独立的智能体。main.js 还支持用环境变量覆盖设置MINECRAFT_PORT、MINDSERVER_PORT、PROFILES、INSECURE_CODING、BLOCKED_ACTIONS、MAX_MESSAGES、NUM_EXAMPLES、LOG_ALL以及最灵活的SETTINGS_JSON一个 JSON 字符串直接Object.assign合并进 settings。这让无头部署和容器化运行变得非常方便。四、核心配置settings.js项目的全局配置集中在根目录的 settings.js 中。下面结合源码逐项解读关键配置项4.1 连接与版本minecraft_version: auto, // 或指定版本如 1.21.6 host: 127.0.0.1, // 或 localhost、你的公网IP port: 55916, // 设为 -1 自动扫描开放端口 auth: offline, // 或 microsoft在线服务器需微软账号minecraft_version默认auto自动匹配服务器版本port对应你在游戏里开放局域网时使用的端口默认 55916auth: offline用于本地/离线服务器连接在线服务器需改为microsoft见第七节。4.2 Mindserver 与 UImindserver_port: 8080, auto_open_ui: true, // 启动时在浏览器打开 UImindserver 负责管理所有智能体并托管 Web UI默认端口 8080UI 代码位于 src/mindcraft/public/index.html其可配置项定义在 src/mindcraft/public/settings_spec.json。4.3 智能体与消息行为base_profile: assistant, // survival、assistant、creative 或 god_mode profiles: [./andy.json], // 可加载多个 profile每个对应一个机器人 load_memory: false, // 是否加载上一会话的记忆 init_message: Respond with hello world and your name, // 生成时发给所有机器人的初始消息 only_chat_with: [], // 限定可与机器人对话的用户列表为空则公开聊天 chat_ingame: true, // 机器人回复是否显示在游戏内聊天框 language: en, // 翻译语言支持 Google Translate 的全部语言名 render_bot_view: false, // 是否在浏览器 localhost:3000/3001... 渲染机器人视角base_profile指向 profiles/defaults/ 下的四个基础人格survival生存、assistant助手、creative创造、god_mode上帝模式使用多个 profile 时每个机器人需要单独/msg发消息单个 profile 中的字段会覆盖 base profile 的对应值。4.4 语音TTSspeak: false, // 开启后所有机器人可通过文本转语音说话。 // 在每个 profile 内用 {provider}/{model}/{voice} 格式指定语音模型。 // 设为 system 则使用系统自带 TTS。 // Windows 和 macOS 开箱即用Linux 需安装 espeak如 apt install espeak、pacman -S espeak。4.5 能力开关与安全边界allow_insecure_coding: false, // 允许 newAction 命令模型可在你电脑上写/运行代码。自行承担风险 allow_vision: false, // 允许视觉模型把截图作为输入进行解释 blocked_actions: [!checkBlueprint, !checkBlueprintLevel, !getBlueprint, !getBlueprintLevel], // 要禁用并从文档中移除的命令列表例[!setMode] code_timeout_mins: -1, // 代码允许运行的分钟数-1 表示不限制 relevant_docs_count: 5, // 提示词中选取的相关代码函数文档数量-1 表示全部allow_insecure_coding是 README 安全警告的核心开关默认关闭开启后模型才能使用newAction自由编写 JavaScript 代码执行动作blocked_actions默认禁用了四类蓝图检查命令针对非建造任务场景这是一个相当实用的默认配置对应的命令系统实现在 src/agent/commands/ 下actions.js、queries.js、index.js。4.6 上下文与推理控制max_messages: 15, // 上下文中保留的最大消息数 num_examples: 2, // 提供给模型的示例数量 max_commands: -1, // 连续回复中可用命令的最大数量-1 不限制 show_command_syntax: full, // full、shortened 或 none narrate_behavior: true, // 自动播报简单动作如 Picking up item! chat_bot_messages: true, // 是否向其他机器人公开广播消息 spawn_timeout: 30, // 机器人生成超时秒数生成慢时可调大 block_place_delay: 0, // 放置方块间隔(ms)防止被服务器反作弊踢出 log_all_prompts: false, // 是否将所有提示词记录到文件其中max_messages与num_examples直接决定每次请求送入 LLM 的上下文规模——这直接影响 token 消耗与推理质量。示例选择依赖 embedding 模型见第九节记忆功能则由 src/agent/memory_bank.js 实现。五、Docker 容器部署如果打算开启allow_insecure_coding官方强烈建议把应用跑在 Docker 容器中以降低运行未知代码的风险。这在连接远程服务器之前尤其推荐但仍不保证绝对安全。方式一直接构建并运行docker build -t mindcraft . docker run --rm --add-hosthost.docker.internal:host-gateway -p 8080:8080 -p 3000-3003:3000-3003 -e SETTINGS_JSON{auto_open_ui:false,profiles:[./profiles/gemini.json],host:host.docker.internal} --volume ./keys.json:/app/keys.json --name mindcraft mindcraft方式二使用 docker-composedocker-compose up --build关键点容器内访问宿主机上的本地 Minecraft 服务器时必须使用特殊主机地址host.docker.internal代替localhost并在 settings.js 中写入host: host.docker.internal, // 替代 localhost让容器内机器人加入你的本地 Minecraft同时注意该命令中通过SETTINGS_JSON环境变量注入了auto_open_ui: false与profiles覆盖——这正是 main.js 中SETTINGS_JSON解析逻辑的实际应用。此外如果连接的 Minecraft 版本不受支持可以尝试 viaproxy 代理服务 来桥接版本差异。六、模型定制Model Customization6.1 受支持的 API 提供商总表在settings.js之外模型的选择发生在各 profile 文件中。以下是 README 提供的完整支持清单API 名称配置变量说明openaiOPENAI_API_KEY默认提供商googleGEMINI_API_KEYGemini 系列anthropicANTHROPIC_API_KEYClaude 系列xaiXAI_API_KEYGrok 系列deepseekDEEPSEEK_API_KEYDeepSeekollama本地无需 key本地模型qwenQWEN_API_KEY通义千问mistralMISTRAL_API_KEYMistralreplicateREPLICATE_API_KEYReplicate 托管模型groq不是 grokGROQCLOUD_API_KEYGroq 推理加速huggingfaceHUGGINGFACE_API_KEYHugging FacenovitaNOVITA_API_KEYNovitaopenrouterOPENROUTER_API_KEYOpenRouter 聚合glhfGHLF_API_KEYGLHFhyperbolicHYPERBOLIC_API_KEYHyperbolicvllm无需 key本地 vLLM 服务cerebrasCEREBRAS_API_KEYCerebrasmercuryMERCURY_API_KEYInception Labs注意groq与grok是不同的提供商配置变量也不同GROQCLOUD_API_KEYvsXAI_API_KEY。本地模型方面官方支持 ollama并提供了自微调finetuned模型安装命令ollama pull sweaterdog/andy-4:micro-q8_0 ollama pull embeddinggemma6.2 API 自动识别机制源码印证在 src/models/_model_map.js 中可以看到Mindcraft 会动态扫描src/models/目录下所有导出了静态prefix字符串的模型类构建apiMap映射表。当 profile 只给出模型名而未指定api时selectAPI()会按前缀匹配以gpt、o1、o3开头 →openai包含claude→anthropic包含gemini→google包含grok→xai包含mistral、deepseek、qwen分别对应各自 API同时保留了local→ollama的向后兼容别名。这就是 README 中简单写法自动生效的底层原理。各 API 的具体实现类位于 src/models/gpt.js、claude.js、gemini.js、deepseek.js、qwen.js、vllm.js、ollama.js等。七、连接在线服务器Online Servers要让机器人加入在线服务器需要正式的 Microsoft/Minecraft 账号。可以用你自己的账号但如果你想同时进服陪它玩就得再准备一个账号。修改 settings.js 中的连接配置host: 111.222.333.444, port: 55920, auth: microsoft, // 其余配置保持不变...[!Important]profile 中的机器人名字必须与 Minecraft 账号名完全一致否则机器人会对着自己自言自语刷屏。多账号的使用技巧Mindcraft 会使用Minecraft 启动器当前登录的账号连接。因此你可以先在启动器切换账号运行node main.js等机器人连上之后再切回自己的主账号进服。八、任务系统TasksTasks 能让机器人自动带着目标和起始物品启动完成采集或建造目标后自动退出。8.1 运行一个采集任务以采集 4 个橡木原木oak_log为例node main.js --task_path tasks/basic/single_agent.json --task_id gather_oak_logs任务文件 tasks/basic/single_agent.json 的完整格式如下{ gather_oak_logs: { goal: Collect at least four logs, initial_inventory: { 0: { wooden_axe: 1 } }, agent_count: 1, target: oak_log, number_of_target: 4, type: techtree, max_depth: 1, depth: 0, timeout: 300, blocked_actions: { 0: [], 1: [] }, missing_items: [], requires_ctable: false } }字段含义README 原文 源码印证initial_inventory回合开始时机器人拥有的物品键为玩家槽位索引值为{物品: 数量}target目标物品名number_of_target需要收集的目标物品数量达标即任务成功type任务类型techtree表示科技树/采集合成类任务timeout超时秒数超时未完成则退出游戏上例为 300 秒blocked_actions按智能体索引指定的被禁用动作missing_items缺失物品清单requires_ctable是否必须使用合成台。任务的加载逻辑在 main.js 中--task_path指定任务 JSON 文件--task_id指定要执行的任务键名两者缺一不可否则抛错task_id is required。8.2 更丰富的任务生态如果你想获得更多优化和Minecraft 世界的自动启动能力即自动化评测需要按照 Minecollab 安装说明 配置评测环境。仓库内提供了大量现成任务模板基础任务tasks/basic/建造任务含金字塔、教堂、花朵等多智能体蓝图tasks/construction_tasks/蓝图生成器为 tasks/construction_tasks/generate_multiagent_construction_tasks.js烹饪任务含地狱厨房 Hells Kitchen 变体tasks/cooking_tasks/合成任务含多智能体协作变体tasks/crafting_tasks/评测脚本入口tasks/evaluation_script.py。根据 minecollab.mdMineCollab 评测覆盖三大类任务烹饪协作收集食材并按多步配方烹饪、建造按程序生成的蓝图协作施工用编辑距离评分、合成从衣物、家具到工具的完整合成链。评测脚本支持--num_agents、--num_parallel并行世界、--insecure_coding建造任务需要自由编码等参数结果会写入experiments/目录。九、Bot Profiles智能体配置档案Bot Profiles 是定义智能体的 JSON 文件如根目录的 andy.json它们决定三件事后端 LLM用于对话、编码、嵌入embedding的模型提示词Prompts影响机器人行为的系统提示示例Examples帮助机器人完成任务的行为范例。最简 profile 甚至只有名字和模型两行{ name: andy, model: gpt-5.4-mini }9.1 模型规格Model Specificationsmodel字段可以是一个简单字符串如model: gpt-5.4也可以写成{api}/{model}的显式形式例如openrouter/google/gemini-2.5-pro用来指定聚合提供商。更灵活的是把model写成一个对象此时必须指定api可选的还有model、url和额外的params。你还可以为对话、编码、视觉、嵌入和语音合成分别指定不同的模型/提供商model: { api: openai, model: gpt-5.4, url: https://api.openai.com/v1/, params: { max_tokens: 1000, temperature: 1 } }, code_model: { api: openai, model: gpt-5.4-mini, url: https://api.openai.com/v1/ }, vision_model: { api: openai, model: gpt-5.4, url: https://api.openai.com/v1/ }, embedding: { api: openai, url: https://api.openai.com/v1/, model: text-embedding-3-small }, speak_model: openai/tts-1/echo各字段职责分工字段用途默认回退model聊天对话所有未指定的模型默认用它code_modelnewAction编码动作回退到modelvision_model图像/截图解释回退到modelembedding为示例选择做文本嵌入回退到modelspeak_model语音合成播报回退到model要点所有 API 都有默认模型和默认 URL因此这些字段都可省略params可接受该 API 支持的任何键值对用于传额外参数如max_tokens、temperatureparams不支持 embedding 模型并非所有 API 都支持 embedding、视觉或语音合成需要按表选择。仓库中的 profiles/gemini.json 展示了带语音与冷却时间cooldown的真实示例{ name: gemini, model: gemini-flash-latest, speak_model: google/gemini-2.5-flash-preview-tts/Kore, cooldown: 2000 }9.2 Embedding 模型Embedding 用于嵌入并高效挑选对话与编码所需的相关示例这正是 settings 中num_examples选取示例的底层依赖。支持的 Embedding APIopenai、google、replicate、huggingface、novita。如果使用不支持的模型会回退到简单的**词重叠word-overlap**匹配方法性能会下降。官方建议使用受支持的 embedding API。9.3 语音合成模型Voice Synthesis语音合成模型用于播报机器人的回复通过speak_model指定。它的解析方式与其他模型不同只支持{api}/{model}/{voice}三段的字符串格式例如openai/tts-1/echo。目前语音合成仅支持openai和google两家。9.4 通过命令行指定 Profiles默认情况下程序使用settings.js中指定的 profiles。你也可以用--profiles参数在启动时指定一个或多个智能体档案node main.js --profiles ./profiles/andy.json ./profiles/jill.json从 main.js 的源码可以看到这个参数会直接覆盖settings.profiles然后程序按顺序为每个 profile 创建一个智能体——这就是单机跑多机器人协作的方式。十、参与贡献与补丁机制Contributing项目欢迎各类贡献官方对 GitHub issue 响应较慢对 Pull Request 更积极寻求更活跃的支持与方向指引可加入 Discord。AI 生成的代码允许提交但务必仔细审查——大量粗制滥造的代码和文档会损害项目发展。补丁Patches项目依赖的部分 node 模块存在 bug。给依赖打补丁的标准流程是先修改你本地的 node 模块文件然后运行npx patch-package [package-name]仓库 patches/ 目录中已内置了 6 个补丁分别针对minecraft-data、mineflayer、mineflayer-pathfinder、mineflayer-pvp、prismarine-viewer、protodef等关键依赖——这也印证了 README 所说某些依赖模块有 bug的情况是真实存在的而这些补丁是保障 Mineflayer 生态与 Mindcraft 兼容性的关键。引用Citation本项目的工作已发表于论文Collaborating Action by Action: A Multi-agent LLM Framework for Embodied ReasoningarXiv:2504.17950。在研究中使用本项目时请按 README 提供的 BibTeX 条目引用article{mindcraft2025, title {Collaborating Action by Action: A Multi-agent LLM Framework for Embodied Reasoning}, author {White*, Isadora and Nottingham*, Kolby and Maniar, Ayush and Robinson, Max and Lillemark, Hansen and Maheshwari, Mehul and Qin, Lianhui and Ammanabrolu, Prithviraj}, journal {arXiv preprint arXiv:2504.17950}, year {2025}, url {https://arxiv.org/abs/2504.17950}, }十一、常见问题排查路径当你运行 Mindcraft 遇到问题时按以下优先级排查安装失败macOS/原生模块→ 查看 FAQ 的 Common Issues 章节机器人连不上游戏→ 确认 Minecraft 已开放局域网且端口为 55916检查 settings.js 的host/port/auth三项机器人不说话→ 确认 profile 名称与游戏账号一致在线服场景检查only_chat_with与chat_ingame设置任务不启动→ 确认--task_path与--task_id同时给出且任务 JSON 的target/number_of_target字段正确需要跑评测/自动开服→ 转向 Minecollab 安装说明使用 tasks/evaluation_script.py 并按其参数要求配置--num_agents、--template_profile、--insecure_coding等。结语从环境搭建、模型配置、安全边界到任务编排与容器化部署Mindcraft 提供了一套完整且高度可配置的LLM 驱动 Minecraft 智能体方案。理解 settings.js 的每一项开关、掌握 profile 的五种模型分工、熟悉任务 JSON 的字段语义你就能自由地把 GPT、Claude、Gemini 或本地 Ollama 模型装进Minecraft 世界里从单智能体对话到多智能体协作建造逐步探索具身智能embodied AI在游戏环境中的无限可能。赞分享AI Agent人工智能游戏开发【免费下载链接】mindcraftMinecraft AI with LLMsMineflayer项目地址https://gitcode.com/GitHub_Trending/mi/mindcraft点击查看免费下载相关推荐10分钟上手MyTested.WebApiASP.NET Web API测试快速开始实例10分钟上手MyTested.WebApiASP.NET Web API测试快速开始实例 想要快速掌握ASP.NET Web API的流畅测试方法吗今天我将探索Mindcraft打造智能 Minecraft 伴侣探索Mindcraft打造智能 Minecraft 伴侣 项目介绍 在这个数字化时代游戏不仅仅是为了娱乐。Mindcraft项目巧妙地融合了语言模型AI Agent人工智能游戏开发SGN项目揭秘终极多态二进制编码器如何绕过安全检测SGN项目揭秘终极多态二进制编码器如何绕过安全检测 SGNShikata ga nai是一款基于Go语言开发的终极多态二进制编码器通过先进的混淆和加密技上一篇5分钟掌握SMUDebugTool解锁AMD Ryzen处理器隐藏性能的专业工具下一篇Dagger TypeScript SDK GitRef 类 API 参考从 Git 引用到目录树的完整调用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考