🧠mindcraft⛏️

利用大语言模型和Mineflayer!为Minecraft打造智能机器人。

常见问题解答 | Discord支持 | 视频教程 | 博客文章 | 论文网站 | MineCollab

[!注意] 请勿将此机器人连接到启用了代码执行功能的公共服务器。该项目允许大语言模型在您的计算机上编写和执行代码。虽然代码处于沙箱环境中，但仍可能受到注入攻击。默认情况下，代码编写功能已禁用；您可以通过在settings.js中将allow_insecure_coding设置为true来启用该功能。敬请留意。

入门指南

系统要求

• Minecraft Java版（最高至v1.21.11，推荐v1.21.6）
• 已安装Node.js（建议使用Node v18或v20 LTS版本。Node v24及以上版本可能会导致原生依赖项出现问题）
• 至少一个来自受支持API提供商的API密钥。请参阅支持的API列表。默认使用OpenAI。

[!重要提示] 如果在Windows上安装Node.js，请确保勾选“自动安装所需工具”选项。

如果在macOS上运行npm install时遇到错误，请参阅常见问题解答，以解决原生模块构建问题。

安装与运行

1. 确保已满足上述系统要求。

2. 下载最新发布版本并解压，或直接克隆本仓库。

3. 将keys.example.json重命名为keys.json，并填入您的API密钥（只需一个即可）。所需模型可在andy.json或其他配置文件中设置。如需使用其他模型，请参考下表。

4. 在终端或命令提示符中，进入安装目录并运行npm install。

5. 启动一个Minecraft世界，并将其开放为局域网游戏，监听本地回环地址端口55916。

6. 在安装目录中运行node main.js。

如遇问题，请查阅常见问题解答或前往Discord支持频道寻求帮助。目前我们对GitHub上的问题响应较为有限。有关任务执行，请参阅MineCollab使用说明。

配置

模型自定义

您可以在settings.js中配置项目相关参数。查看文件。

您还可以在各代理配置文件中（如andy.json）设置代理名称、使用的模型及提示词。模型可通过model字段指定，例如model: "gemini-2.5-pro"。请务必使用与所选API提供商匹配的正确API密钥。所有支持的API列表如下。

⭐ 查看支持的API ⭐

API名称	配置变量	文档链接
openai	OPENAI_API_KEY	文档
google	GEMINI_API_KEY	文档
anthropic	ANTHROPIC_API_KEY	文档
xai	XAI_API_KEY	文档
deepseek	DEEPSEEK_API_KEY	文档
ollama（本地）	无	文档
qwen	QWEN_API_KEY	国际版/中文版
mistral	MISTRAL_API_KEY	文档
replicate	REPLICATE_API_KEY	文档
groq（非Grok）	GROQCLOUD_API_KEY	文档
huggingface	HUGGINGFACE_API_KEY	文档
novita	NOVITA_API_KEY	文档
openrouter	OPENROUTER_API_KEY	文档
glhf	GHLF_API_KEY	文档
hyperbolic	HYPERBOLIC_API_KEY	文档
vllm	无	无
cerebras	CEREBRAS_API_KEY	文档
mercury	MERCURY_API_KEY	文档

如需更全面的模型配置及语法说明，请参阅模型规格。

对于本地模型，我们支持ollama平台，并提供经过微调的专属模型供您使用。要安装我们的模型，请先安装ollama，然后在终端中运行以下命令：

ollama pull sweaterdog/andy-4:micro-q8_0 && ollama pull embeddinggemma

连接在线服务器

若要连接到在线服务器，您的机器人需要一个官方的Microsoft/Minecraft账号。您可以使用自己的个人账号，但如果您希望同时登录并游玩，则需要另一个账号。要进行连接，请修改settings.js中的以下几行：

"host": "111.222.333.444",
"port": 55920,
"auth": "microsoft",

// 其余部分保持不变...

[!重要提示] 机器人在profile.json中的名称必须与Minecraft玩家名称完全一致！否则机器人会不断向自己发送消息。

若需使用不同账号，Mindcraft将连接当前Minecraft启动器所使用的账号。您可以在启动器中切换账号，然后运行node main.js，待机器人成功连接后再切换回您的主账号。

任务

任务会自动启动机器人，并提供一个提示和一个需要获取的目标物品或建造蓝图。要运行一个简单的任务，例如收集4个橡木原木，可以执行以下命令：

node main.js --task_path tasks/basic/single_agent.json --task_id gather_oak_logs

以下是一个示例任务的 JSON 格式：

{
    "gather_oak_logs": {
      "goal": "收集至少四根原木",
      "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
    }
}

initial_inventory 是机器人在任务开始时拥有的初始物品清单，target 表示目标物品，而 number_of_target 则表示智能体需要收集的目标物品数量，以成功完成任务。

如果你想进一步优化并自动启动 Minecraft 世界，你需要按照 Minecollab 指南 中的说明进行操作。

Docker 容器

如果你打算启用 allow_insecure_coding，建议将应用程序运行在 Docker 容器中，以降低运行未知代码的风险。在连接到远程服务器之前，强烈建议这样做，尽管这并不能完全保证安全性。

docker build -t mindcraft . && docker run --rm --add-host=host.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-compose up --build

在 Docker 中运行时，如果希望机器人加入你的本地 Minecraft 服务器，必须使用特殊的主机地址 host.docker.internal，以便从容器内部访问你的本地主机。请将以下内容添加到你的 settings.js 文件中：

"host": "host.docker.internal", // 而不是 "localhost"，用于从 Docker 容器内连接到本地 Minecraft

若要连接到不受支持的 Minecraft 版本，可以尝试使用 viaproxy。

机器人配置文件

机器人配置文件是 JSON 文件（如 andy.json），用于定义：

1. 机器人后端使用的 LLM 模型，用于对话、编码和嵌入。
2. 用于影响机器人行为的提示语。
3. 帮助机器人完成任务的示例。

模型规格

LLM 模型可以简单地指定为 "model": "gpt-4o"，也可以更具体地写成 "{api}/{model}" 的形式，例如 "openrouter/google/gemini-2.5-pro"。所有支持的 API 可以在此处查看 模型自定义。

model 字段可以是字符串或对象。如果使用对象格式，必须指定 api，还可以选择性地指定 model、url 和其他 params。你也可以为聊天、编码、视觉处理、嵌入和语音合成使用不同的模型或提供商。以下是一个示例：

"model": {
  "api": "openai",
  "model": "gpt-4o",
  "url": "https://api.openai.com/v1/",
  "params": {
    "max_tokens": 1000,
    "temperature": 1
  }
},
"code_model": {
  "api": "openai",
  "model": "gpt-4",
  "url": "https://api.openai.com/v1/"
},
"vision_model": {
  "api": "openai",
  "model": "gpt-4o",
  "url": "https://api.openai.com/v1/"
},
"embedding": {
  "api": "openai",
  "url": "https://api.openai.com/v1/",
  "model": "text-embedding-ada-002"
},
"speak_model": "openai/tts-1/echo"

model 用于聊天，code_model 用于新动作编码，vision_model 用于图像理解，embedding 用于嵌入文本以选择相关示例，而 speak_model 则用于语音合成。如果没有特别指定，model 将默认用于其他所有功能。并非所有 API 都支持嵌入、视觉处理或语音合成。

所有 API 都有默认的模型和 URL，因此这些字段是可选的。params 字段也是可选的，可用于为模型指定额外的参数。它接受 API 支持的任何键值对，但不适用于嵌入模型。

嵌入模型

嵌入模型用于嵌入文本，并高效地选择与对话和编码相关的示例。

支持的嵌入 API：openai、google、replicate、huggingface、novita

如果你尝试使用不受支持的模型，系统将默认采用简单的词重叠方法，性能可能会有所下降。我们建议使用受支持的嵌入 API。

语音合成模型

语音合成模型用于朗读机器人的响应，并通过 speak_model 进行指定。此字段的解析方式与其他模型不同，仅支持格式为 "{api}/{model}/{voice}" 的字符串，例如 "openai/tts-1/echo"。目前我们仅支持 openai 和 google 作为语音合成提供商。

通过命令行指定配置文件

默认情况下，程序会使用 settings.js 中指定的配置文件。你可以使用 --profiles 参数指定一个或多个代理配置文件：node main.js --profiles ./profiles/andy.json ./profiles/jill.json。

贡献

我们欢迎对该项目的贡献！通常我们对 GitHub 上的问题响应较慢，但对拉取请求的响应更快。请加入 Discord 以获得更积极的支持和指导。

虽然允许提交 AI 生成的代码，但请务必仔细审查。大量提交粗糙的代码和文档会严重阻碍开发进程。

补丁

我们依赖的一些 Node.js 模块存在 bug。要添加补丁，只需修改本地的 Node.js 模块文件，然后运行 npx patch-package [package-name]。

开发团队

感谢所有为项目做出贡献的人，尤其是官方开发团队：@MaxRobinsonTheGreat、@kolbytn、@icwhite、@Sweaterdog、@Ninot1Quyi、@riqvip、@uukelele-scratch、@mrelmida。

引用：

本工作发表在论文《逐行动协作：用于具身推理的多智能体 LLM 框架》中（arXiv 预印本 arXiv:2504.17950）。如果你在研究中使用本项目，请引用以下文献：

@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},
}

贡献者

感谢所有在 GitHub 上提交过问题、提出过建议，并总体上帮助使这个项目变得更好的人。

MindCraft 快速上手指南

MindCraft 是一个利用大语言模型（LLM）和 Mineflayer 库，让 AI 代理在 Minecraft 中自主思考、编码和行动的开源项目。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统：Windows, macOS 或 Linux。
  • Windows 用户注意：安装 Node.js 时务必勾选 Automatically install the necessary tools 选项。
  • macOS 用户注意：若遇到 npm install 报错，通常涉及原生模块编译问题，需确保已安装 Xcode Command Line Tools。
• 游戏版本：Minecraft Java Edition（推荐 v1.21.6，支持范围最高至 v1.21.11）。
• 运行环境：Node.js（推荐 LTS 版本 v18 或 v20。注意：Node v24+ 可能导致原生依赖兼容性问题）。
• API 密钥：至少需要一个支持的 LLM 提供商 API Key（默认支持 OpenAI，同时也支持 Google Gemini, Anthropic, Ollama 本地模型等）。

安装步骤

1. 获取源码

下载最新发布的 Release 包 并解压，或者克隆仓库：

git clone https://github.com/mindcraft-bots/mindcraft.git
cd mindcraft

2. 配置 API 密钥

将示例配置文件重命名并填入你的 API Key：

cp keys.example.json keys.json

编辑 keys.json，填入你拥有的任意一个服务商的 Key（例如 OPENAI_API_KEY）。

安全警告：默认情况下代码写入功能是关闭的。若需在 settings.js 中开启 allow_insecure_coding: true，请务必在沙箱环境（如 Docker）中运行，以防 LLM 生成的代码对主机造成风险。

3. 安装依赖

在项目根目录执行：

npm install

4. 准备 Minecraft 世界

1. 启动 Minecraft Java 版。
2. 创建一个新世界并进入。
3. 按 Esc 打开菜单，选择 对局域网开放 (Open to LAN)。
4. 设置端口为 55916（如果该端口被占用，可修改 settings.js 中的端口配置），然后确认开放。

基本使用

启动 AI 代理

确保 Minecraft 世界已在局域网开放，且在终端中位于项目目录下，运行：

node main.js

此时，AI 代理将尝试连接到你开放的本地世界。你可以在游戏中看到它以玩家身份加入，并通过聊天框与其互动或观察其自动行为。

运行特定任务

你可以预设任务让 AI 自动完成（例如收集物品）。以下是一个收集 4 个橡木原木的示例命令：

node main.js --task_path tasks/basic/single_agent.json --task_id gather_oak_logs

自定义模型与代理

• 切换模型：编辑 profiles/andy.json（或其他 profile 文件），修改 model 字段。例如使用 Gemini：

  "model": "gemini-2.5-pro"
  

  确保已在 keys.json 中配置对应的 GEMINI_API_KEY。
• 使用本地模型 (Ollama)： 首先拉取专用模型：

  ollama pull sweaterdog/andy-4:micro-q8_0 && ollama pull embeddinggemma
  

  然后在 profile 中将 api 设置为 ollama。

进阶：多账号联机

若要连接远程服务器或与自己的主账号一起玩，需在 settings.js 中修改配置：

"host": "你的服务器 IP",
"port": 服务器端口，
"auth": "microsoft",

注意：Bot 在 profile 中设定的名字必须与登录的 Minecraft 账号名称完全一致，否则会导致逻辑冲突。启动时，MindCraft 会使用当前 Minecraft 启动器登录的账号身份。