# mindcraft

**Repository Path**: xuegoo_admin/mindcraft

## Basic Information

- **Project Name**: mindcraft
- **Description**: mineflayer
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-10-18
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 头脑制作镐
我的世界-bots/mindcraft | 趋势转变
用LLMs为Minecraft打造思维 矿工！

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

注意

不要将此机器人连接到启用编码的公共服务器。该项目允许LLM编写/在你的计算机上执行代码，该代码处于沙箱环境中，但仍可能受到注入攻击。默认情况下禁用代码编写，你可以通过设置来启用它 allow_insecure_coding 到 true 在 settings.js你们被警告了。

## 开始
要求
我的世界 Java 版 (最高版本 v1.21.11，推荐版本 v1.21.6)
Node.js 已安装 (建议使用 Node v18 或 v20 LTS。Node v24+ 可能会导致原生依赖项出现问题)
至少一个来自受支持的 API 提供方的 API 密钥。参见 支持的APIOpenAI 是默认选项。
重要

如果在 windows 上安装节点，请确保进行检查 Automatically install the necessary tools

如果你遇到 npm install macOS上的错误，请参见 常见问题解答 用于解决本地模块构建问题

安装并运行
确保你满足上述要求。

下载 最新发布 并解压它，或者克隆该仓库。

重命名 keys.example.json 到 keys.json 并填写您的API密钥（您只需要一个）。所需的模型已设置在 andy.json 或其他配置。其他型号请参考下面的表格。

在终端/命令提示符，运行 npm install 从安装目录

启动一个我的世界世界并在本地主机端口上将其开放到局域网 55916

运行 node main.js 从安装目录

如果你遇到问题，请检查 常见问题解答 或者在上面寻找支持 discord我们目前对 GitHub 问题的响应不太及时。要运行任务，请参考 Minecollab 指南

## 配置
模型定制
你可以配置项目详细信息 settings.js. 查看文件。

你可以像这样在代理的资料中配置代理的名称、模型和提示信息 andy.json. 可以用模型指定 model 字段，其值类似于 model: "gemini-2.5-pro"你需要为所选择的 API 提供商获取正确的 API 密钥。请参阅下方支持的所有 API。

## ⭐ 查看支持的 API ⭐
如需更全面的模型配置和语法，请参阅 型号规格.

对于本地模型，我们支持 ollama 我们还提供自己微调后的模型供您使用。 要安装我们的模型，请安装 ollama 并在终端中运行以下命令:

ollama pull sweaterdog/andy-4:micro-q8_0 && ollama pull embeddinggemma
在线服务器
要连接到在线服务器，您的机器人需要一个微软的官方/Minecraft 账户。你可以使用自己的个人账户，但如果你想连接并一起玩的话，需要另一个账户。要连接，请更改这些行在 settings.js:

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

// rest is same...
重要

机器人的名字在 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": "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
    }
}
的 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 从您的 Docker 容器中调用您的本地主机。将其放入您的 settings.js:

"host": "host.docker.internal", // instead of "localhost", to join your local minecraft from inside the docker container
要连接到不受支持的Minecraft版本，您可以尝试使用 viaproxy

机器人的资料
机器人的资料是json文件（例如） andy.json）定义:

用于交谈、编程和嵌入的机器人后端大语言模型
用来影响机器人行为的提示。
示例有助于机器人执行任务。
型号规格
LLM 模型可以简单地指定为 "model": "gpt-5.4"，或者更具体地说，与 "{api}/{model}"，比如 "openrouter/google/gemini-2.5-pro"。查看所有支持的 API 这里.

的 model 字段可以是一个字符串或一个对象。一个模型对象必须指定一个 api，以及可选的“a” 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_model 用于 newAction 编码， 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生成的代码，请务必仔细审核。提交大量马虎的代码和文档会严重影响开发进程。

补丁
我们所依赖的一些节点模块中存在错误。要添加补丁，请修改本地的节点模块文件并运行 npx patch-package [package-name]

开发团队
感谢所有为该项目做出贡献的人，特别是官方开发团队: @MaxRobinsonTheGreat, @科尔比恩, @icwhite, @毛衣狗, @Ninot1Quyi, @riqvip, @尤克里里-抓痕, @mrelmida

引用:
这项工作发表在论文中 逐行动协作：多-具身推理的代理LLM框架.如果您在研究中使用了该项目，请使用此引用:

@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上和线下提交问题、提出建议以及帮助改进这个项目的人。

贡献者