AIRI Minecraft Agent 集成指南基于 Mineflayer 的本地游戏 Agent 接入与认知架构解析【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiAIRI 的 Minecraft 集成通过 Mineflayer 将 Agent 接入可信的 Minecraft 服务器使 Agent 能够接收游戏上下文、执行游戏内动作并回报状态是 AIRI 在游戏场景中的本地开发与维护入口。本文基于仓库中的官方文档 integrations/minecraft 说明 展开结合integrations/minecraft模块源码完整覆盖从环境配置、AIRI 通道对接、启动验证到安全边界的实战流程并深入解析其感知 → 反射 → 意识 → 动作的四层认知架构与 AIRI 服务端通信原理。注意当前 Mineflayer 实现处于弃用迁移路径上官方计划迁移到 Fabric mod 运行时因此本文所述运行时主要面向当前本地开发与维护不建议围绕它构建长期新功能详见 integrations/minecraft/README.md 的 Deprecation Notice。前置条件在开始之前需要准备以下三部分环境安装仓库依赖在仓库根目录执行pnpm i安装包括integrations/minecraft在内的 workspace 依赖。该模块的依赖集中在 integrations/minecraft/package.json核心包括mineflayer及其生态插件mineflayer-pathfinder、mineflayer-pvp、mineflayer-auto-eat、mineflayer-collectblock、mineflayer-tool、mineflayer-armor-manager、minecraft-data、prismarine-*系列数据包以及用于 LLM 推理的xsai/generate-text和用于与 AIRI 服务端通信的proj-airi/server-sdk。可访问的 Minecraft 服务器需要一台本机可达或可信的 Minecraft 服务器连接地址与端口通过环境配置提供默认指向localhost:25565见下文配置表。可用的聊天与模型服务在 AIRI 中配置可用的聊天 Provider 和模型同时为 Minecraft Agent 准备一套 OpenAI 兼容的模型设置OPENAI_API_BASEURL、OPENAI_API_KEY、OPENAI_MODEL、OPENAI_REASONING_MODEL。::: warning 凭据安全 API Key、服务地址和 Minecraft 服务器凭据只应保存在本地.env.local文件中。不要提交commit、截图或分享这些值。 :::配置环境变量将环境变量模板复制为本地文件cp integrations/minecraft/.env integrations/minecraft/.env.local然后编辑integrations/minecraft/.env.local填写 Minecraft 服务器、AIRI 以及模型服务相关设置。模板文件位于 integrations/minecraft/.env所有配置项在启动时由 integrations/minecraft/src/composables/config.ts 中的 Zod schema 校验。AIRI 通道配置在桌面版Desktop ver.中打开Settings → Connection显示并复制Auth Token。随后在.env.local中加入以下 AIRI 通道设置AIRI_WS_BASEURLws://localhost:6121/ws AIRI_CLIENT_NAMEminecraft-bot AIRI_WS_TOKENAuth Token from Settings → ConnectionAIRI_WS_TOKEN缺失或错误会导致模块无法向 AIRI 注册这是启动后必须重点检查的一项。完整配置项参考结合 integrations/minecraft/.env 模板与 config.ts 的默认值整理如下环境变量是否必填默认值说明AIRI_WS_BASEURL是ws://localhost:6121/wsAIRI 服务端 WebSocket 地址必须是ws:或wss:协议AIRI_CLIENT_NAME是minecraft-bot注册到 AIRI 的客户端名称AIRI_WS_TOKEN否空AIRI Auth Token缺失时模块无法完成注册BOT_HOSTNAME是localhostMinecraft 服务器地址BOT_PORT是25565服务器端口Zod 校验要求为 1–65535 的整数BOT_USERNAME是airi-bot机器人游戏名BOT_AUTH否空认证方式取值限定为mojang/microsoft/offline三者之一在线账号可取消注释BOT_AUTHmicrosoft启动时弹出微软登录授权令牌会缓存到本机Linux~/.minecraft、macOS~/Library/Application Support/minecraft、Windows%appdata%/.minecraftBOT_VERSION否1.20Minecraft 协议版本BOT_MASTER_USERNAME否空机器人在游戏内绑定的“主人”玩家名用于识别真正的玩家例如主人攻击时不逃跑OPENAI_API_BASEURL是空模板无默认OpenAI 兼容接口地址必须是http:或https:OPENAI_API_KEY是空模型服务 API KeyOPENAI_MODEL是deepseek-chat主对话/规划模型OPENAI_REASONING_MODEL是deepseek-reasoner推理模型ENABLE_MCP_SERVER否false启用 MCP REPL 服务器无认证默认关闭ENABLE_DEBUG_SERVER否false启用调试服务器无认证默认关闭ENABLE_MINECRAFT_VIEWER否false启用 Prismarine Viewer无认证默认关闭从源码结构看config.ts 将配置划分为openai、debug、bot、airi四组并在initEnv()时统一解析一旦校验失败会直接抛出异常终止启动校验错误信息会明确列出失败的配置路径如bot.port: BOT_PORT must be an integer。日志输出时apiKey、password、token都会被脱敏为[REDACTED]。注意区分三个 debug 开关它们对应的调试端点完全无认证。启动时若任一开关为truemain.ts 会打印一段醒目的安全警告——这些端口暴露给互联网或不信任的局域网可能导致远程代码执行RCE和机器人被完全接管。启动 Agent从仓库根目录运行pnpm -F proj-airi/minecraft-bot dev或者在integrations/minecraft/目录内直接执行pnpm dev。对应的 npm script 定义在 integrations/minecraft/package.jsondev使用tsx --env-file.env --env-file-if-exists.env.local启动 src/main.ts因此.env与.env.local都会被加载tsx支持--env-file-if-exists本地文件不存在时不会报错。启动后请通过终端输出验证两点对 AIRI 的认证是否成功——AIRI_WS_TOKEN缺失或错误时模块无法向 AIRI 注册对应 start-background-client.ts 中的连接逻辑首次连接失败不会阻塞启动而是打印AIRI server is unavailable; continuing startup without AIRI and retrying in background并在后台持续重试。是否成功连接 Minecraft 服务器——机器人会尝试登录并在spawn后打印Bot ready。运行时行为补充断线重连Mineflayer 包装层支持自动重连最多重试 5 次见 main.ts 中的reconnect: { enabled: true, maxRetries: 5 }断线、被踢kicked或插件初始化失败都会触发重连过渡流程见 core.ts 中的forwardDisconnect。心跳参数AIRI 客户端的心跳配置为readTimeout: 120_000、pingInterval: 20_000见 main.ts。这是因为机器人进程偶尔会因繁忙的 Mineflayer 封包处理/感知 tick 出现约 30 秒的事件循环静默默认 30 秒读超时会误判掉线导致游戏内机器人频繁上下线。游戏内命令聊天中以#前缀输入的命令会走内置命令分发core.ts 的parseCommand/createCommandChatHandler#help会列出已注册命令。而!pause则用于暂停/恢复认知引擎见 cognitive/index.ts机器人会在游戏内回复当前状态。源码视角AIRI 与 Minecraft 的双向桥接Minecraft 模块通过 airi-bridge.ts 与 AIRI 服务端交换事件订阅并发送的关键事件如下事件方向作用spark:commandAIRI → 机器人接收高层指令intent取值plan/proposal/action/pause/resume/reroute/context路由为signal:airi_command触发一轮全新的意识决策循环而不是静默写入历史context:updateAIRI → 机器人接收被动上下文写入认知事件总线历史专用通道不唤醒决策循环module:announcedAIRI → 机器人模块广播与监听spark:notify/spark:emit机器人 → AIRI回报通知与命令执行状态queued/working/done/droppedcontext:update机器人 → AIRI将游戏内状态如任务进度以AppendSelf策略推送回 Stage 运行时同时main.ts 监听module:configure事件允许桌面端在运行期下发新的机器人配置并热更新MinecraftBotRuntime.updateBotConfig会先停掉旧 bot 再按新配置重建见 minecraft-bot-runtime.ts这就是桌面端“游戏命令中继”能实时生效的底层机制。认知架构感知 → 反射 → 意识 → 动作机器人内部并非简单的“LLM 接聊天”而是一套四层认知架构详见 integrations/minecraft/README.md 的 Cognitive Architecture 一节Layer A 感知层Perception位于 src/cognitive/perception/将 Mineflayer 原始事件受击、实体移动、低血量、潜行切换、系统消息等见events/definitions/*归一化为类型化事件再经 YAML 规则引擎rules/*.yaml如danger/damage.yaml、social/teabag.yaml推导出signal:*信号。Layer B 反射层Reflex位于 src/cognitive/reflex/基于有限状态机处理本能反应如自动进食behaviors/auto-eat、防御behaviors/defend、逃离危险behaviors/escape-hazard、待机注视behaviors/idle-gaze反射可向意识层发送抑制信号避免不必要的 LLM 调用。Layer C 意识层Conscious位于 src/cognitive/conscious/brain.ts负责事件队列编排与 LLM 回合生命周期js-planner.ts在隔离沙箱isolated-vm中执行 JS 规划脚本query-dsl.ts提供只读的世界/物品栏/实体查询 DSL供规划脚本安全读取游戏状态。Layer D 动作层Action位于 src/cognitive/action/task-executor.ts执行归一化动作指令并发出动作生命周期事件action-registry.ts校验参数并分发工具调用llm-actions.ts维护绑定到 Mineflayer skills采集方块、收集木头、合成、战斗、移动等见 src/skills/的工具目录。README 中给出的典型事件流是Build a house玩家下达指令 → 感知层检测事件 → 意识层规划结构 → 动作层按步骤执行收集木头 → 合成木板 → 砌墙→ 意识层确认完成。此外container.ts通过 Awilix 完成依赖注入装配CognitiveEngine作为 Mineflayer 插件在spawn时统一初始化各层见 cognitive/index.ts。安全边界与使用限制官方文档与 integrations/minecraft/README.md 的 Safety Notice 一致强调不要将 Agent 连接到不信任的公共服务器。Agent 控制一个本地 Minecraft 会话与网络连接即使动作规划运行在隔离沙箱中恶意服务器仍可能诱发非预期行为。运行时可以执行 JavaScript 生成的动作计划来控制机器人这些脚本虽然运行在隔离环境但驱动的仍是真实的本地进程可访问 Minecraft 会话、本地网络及机器侧资源因此应仅将其视为本地开发与可信服务器工具。三个调试开关MCP Server / Debug Server / Prismarine Viewer无认证保护默认关闭仅在明确知道后果时开启并确保端口不可被外部访问。参考资料官方集成文档docs/content/en/docs/integrations/minecraft.md模块说明含认知架构与迁移计划integrations/minecraft/README.md环境变量模板integrations/minecraft/.env配置校验与默认值integrations/minecraft/src/composables/config.ts入口与机器人生命周期integrations/minecraft/src/main.ts、integrations/minecraft/src/minecraft-bot-runtime.tsAIRI 桥接integrations/minecraft/src/airi/airi-bridge.ts【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考