Claude智能体MC挖钻石对抗赛：AI Agent实战项目

用 Claude 智能体在 Minecraft 里自动挖钻石看起来像游戏脚本但合适定位是一次 AI Agent 学习实验。把一个明确目标“挖到钻石”交给 AI让 AI 读取游戏状态、决定下一步动作、执行动作、再观察结果继续调整这个过程几乎覆盖了 Agent 的核心闭环。本文围绕“Claude 智能体 MC 挖钻石对抗赛”这条主线从 Claude Code 安装开始逐步搭建一个能在个人 Minecraft 服务器里运行的挖钻石机器人并把它扩展成两个智能体比赛计分的对抗赛。文章适合已经会一点 JavaScript、想动手理解 Agent 工作方式、又希望结果能可视化呈现的开发者。学完之后你能独立完成一个“AI 决策 游戏执行”的完整项目并知道日志、超时、重试、计分这些工程细节该放在哪里。这里要强调一个前提整个实验在你自己搭建的 Minecraft 服务器里运行不进入公共服务器不做任何影响其他玩家的行为。挖钻石的目标只是为了验证智能体的感知、决策和执行能力而不是做一个作弊工具。1. 先拆解“Claude 智能体 Minecraft 挖钻石”的架构原理1.1 为什么把 Minecraft 当作 Agent 实验场Minecraft 是一个非常适合做 Agent 实验的环境原因有三点。第一环境状态可读取。机器人能够拿到自己的坐标、朝向、背包物品、周围方块列表这些信息可以直接转换成结构化 JSON成为大模型的“眼睛”。第二动作可执行。移动、挖掘、放置、合成、丢弃都是有限的离散动作可以被脚本封装成函数。Agent 不需要控制像素级画面只需要调用这些函数。第三结果可量化。挖到多少钻石、花了多少时间、走过了多少区块都能用数字统计。对抗赛的输赢、策略优劣、路径效率全部可以复盘。挖钻石这个任务本身也很合适。它需要 Agent 理解“钻石矿分布在深层”“需要铁镐或更好的镐才能采集”“先找到矿洞再深入比乱挖更快”这些游戏知识并把知识转化成连续的动作序列。相比“让 AI 聊天”这类任务更有工程感。1.2 从“调用 API”到“Agent”的差距很多人第一次接触 Claude只是通过对话框输入问题、得到回答。这是单次调用模型没有环境也没有行动能力。Agent 的工作方式完全不一样它是一条循环感知环境 - 形成目标 - 拆解任务 - 执行动作 - 观察结果 - 修正计划在这个项目里Claude 承担的是“决策层”的角色。它不直接控制鼠标键盘而是读取机器人发来的状态描述输出“下一步做什么”。真正在游戏里移动、挖掘的是 Mineflayer 机器人。把两者分开价值很明显。模型负责复杂推理和任务规划脚本负责稳定执行。即使模型决策偶尔不合理也不会导致游戏客户端崩溃只会产生一次无效动作。1.3 整体技术选型整个系统由四部分组成模型决策层、执行层、环境层、编排层。组件职责选型理由Claude Code接收状态、输出动作决策官方 CLI 工具支持非交互模式适合被脚本调用Mineflayer连接 Minecraft、移动、挖掘、读取背包Node.js 生态API 完整社区成熟Minecraft Java Edition提供可观察、可交互的沙盒环境状态可量化适合搭建实验场地Dify可视化编排 Prompt 和工具流程可选适合不想写太多胶水代码的情况如果只是跑通最小闭环不引入 Dify 也可以。先用 Node.js Mineflayer Claude Code 就能完成。Dify 的价值在于把多轮 Prompt、工具调用和日志可视化适合后续做更复杂的流程编排。2. 环境准备Claude Code、Node.js、Minecraft 服务器要一次装齐2.1 需要哪些软件在开始写代码之前先把运行环境确认好。很多坑都出现在版本不一致上尤其是 Minecraft 服务器版本和 Mineflayer 版本不匹配时机器人会反复掉线。软件建议版本用途Node.js18 或 20运行 Mineflayer 脚本npm随 Node.js 安装安装依赖包Claude Code以官方文档为准命令行智能体工具Minecraft Java Edition 服务端1.16.5 或 1.20.x搭建个人服务器Mineflayer与服务器版本匹配游戏机器人库如果你只在本机学习可以下载一个 Minecraft Java 版服务端不需要游戏客户端。机器人直接通过 Mineflayer 连接到服务端。2.2 安装 Claude CodeClaude Code 是 Anthropic 推出的命令行智能体工具可以直接在终端里完成写代码、读文件、执行命令等任务。这个项目的思路是把它当作一个可被 Node.js 调用的决策服务。安装命令以官方文档为准常见方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后确认命令可用claude --version如果终端提示“claude 不是内部或外部命令”或者“无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”说明 npm 全局目录没有加入 PATH或者安装没有成功。先执行npm root -g查看全局目录再确认该目录是否在 PATH 中。首次使用 Claude Code 需要配置 API Key。推荐通过环境变量注入而不是写在代码里export ANTHROPIC_API_KEY你的密钥在 Windows PowerShell 下可以改成$env:ANTHROPIC_API_KEY你的密钥密钥要像密码一样管理建议放进项目根目录的.env文件并通过dotenv加载不进 Git 仓库。2.3 初始化 Node.js 项目并安装 Mineflayer在一个新目录里初始化项目mkdir claude-diamond-agent cd claude-diamond-agent npm init -y然后安装 Mineflayer 和寻路插件npm install mineflayer npm install mineflayer-pathfindermineflayer负责连接服务器和操作方块mineflayer-pathfinder提供自动寻路能力。如果没有寻路插件机器人就只能原地跳和转身无法主动走向目标方块。安装完成后用以下代码验证能创建一个机器人const mineflayer require(mineflayer) const bot mineflayer.createBot({ host: 127.0.0.1, port: 25565, username: Claude_Bot_01, version: 1.20.1 }) bot.on(spawn, () { bot.chat(AI agent online) console.log([bot] 已进入服务器) }) bot.on(error, (err) { console.error([bot] 连接错误:, err.message) }) bot.on(end, (reason) { console.log([bot] 连接断开:, reason) })username是机器人在游戏中的名字必须保证服务器里没有同名在线玩家。version必须和服务端版本一致否则协议解析会出现问题。2.4 准备 Minecraft 个人服务器从 Minecraft 官网或服务端发布页下载对应版本的 server 包放到一个独立目录启动时接受 EULAecho eulatrue eula.txt java -Xmx2G -jar server.jar nogui为了让机器人更容易发挥建议关闭 PvP、把难度调整为和平或简单、关闭怪物生成避免智能体在挖钻石途中被僵尸干扰。如果是单机实验可以把server.properties中的online-mode设为false但这会降低安全性必须保证只有局域网内可信设备能连接。注意不要把online-modefalse的服务器直接暴露到公网。个人实验环境建议只监听127.0.0.1或局域网地址。3. 从零写一个 Mineflayer 机器人让智能体具备“手脚”3.1 先让机器人学会寻找钻石矿石机器人要能挖钻石第一步是“看见”钻石。Mineflayer 提供了findBlock接口可以按方块名搜索周围方块。const mineflayer require(mineflayer) const pathfinder require(mineflayer-pathfinder) const { GoalBlock } require(mineflayer-pathfinder).goals const bot mineflayer.createBot({ host: 127.0.0.1, port: 25565, username: Claude_Bot_01, version: 1.20.1 }) bot.loadPlugin(pathfinder.pathfinder) function findNearestDiamond(maxDistance 32) { return bot.findBlock({ matching: (block) block.name diamond_ore || block.name deepslate_diamond_ore, maxDistance }) } async function moveToBlock(block) { await bot.pathfinder.goto(new GoalBlock(block.position.x, block.position.y, block.position.z)) } async function digBlock(block) { await bot.dig(block) }diamond_ore是普通石质钻石矿石deepslate_diamond_ore是深板岩钻石矿石。在 1.18 版本之后钻石矿主要出现在深层所以两种都要匹配。3.2 把“挖钻石”组织成可执行函数找到方块之后不能直接冲过去挖。机器人要先确认自己的工具、当前位置和目标方块之间是否有障碍然后才执行挖掘。下面是一个更完整的挖掘函数async function collectDiamond() { const target findNearestDiamond(48) if (!target) { console.log([collect] 附近没有钻石矿石需要继续探索) return { success: false, reason: not_found } } try { await moveToBlock(target) await bot.waitForTicks(5) await digBlock(target) await bot.waitForTicks(10) console.log([collect] 挖掘完成) return { success: true, reason: digged } } catch (err) { console.error([collect] 挖掘失败:, err.message) return { success: false, reason: failed } } }waitForTicks是 Mineflayer 中的等待函数用于模拟游戏刻的推进。移动之后立刻挖掘可能会因为机器人和方块之间还没对齐而失败加几个 tick 等待会更稳定。3.3 用结构化状态描述让 AI 理解环境Claude 无法直接读取游戏运行时的变量你必须把机器人当前状态整理成文本或 JSON 再发给它。状态信息越简洁模型越容易给出有效决策。推荐只保留这些字段坐标、朝向、背包钻石数量、当前目标任务、附近方块摘要。function buildStateReport() { const inventory bot.inventory.items() const diamonds inventory .filter((item) item.name diamond) .reduce((sum, item) sum item.count, 0) return { position: bot.entity.position, yaw: Math.round(bot.entity.yaw * 100) / 100, diamondCount: diamonds, nearbyBlocks: bot.findBlock({ matching: () true, maxDistance: 16, count: 20 }).map((block) block.name) } }这样 AI 看到的状态就是“我现在在坐标 X 深度是 Y背包装备是铁镐钻石数量是 0附近 16 格内有石头、泥土、铁矿石”。它不需要理解游戏画面只需要处理这个结构化的环境摘要。3.4 让机器人具备基本“探索”策略钻石矿不会总在眼前。机器人必须有一套不依赖模型也能运行的探索逻辑否则每次找不到钻石都去问 Claude既慢又费 token。可以先用启发式规则兜底当机器人周围找不到钻石矿石时向更深层下降或者沿矿洞方向前进。async function explore() { const pos bot.entity.position const targetY Math.max(pos.y - 1, -58) const target new GoalBlock(pos.x 10, targetY, pos.z) await bot.pathfinder.goto(target) }这里的“探索”是确定性的脚本行为。Claude 的职责是判断“当前应该挖、应该找、还是应该继续深入”具体移动路径由寻路插件完成。这种分工能大幅减少模型调用次数。4. 接入 Claude Code 决策层形成感知-决策-执行闭环4.1 用 Claude Code 的非交互模式做决策Claude Code 除了交互式聊天还提供了适合脚本调用的非交互模式。可以在终端中直接传 promptclaude -p 用一个词回答Minecraft 钻石矿石通常出现在什么深度Node.js 可以通过child_process调用这个命令把机器人的状态报告放进 prompt把返回结果解析成动作指令。const { execSync } require(child_process) function askClaudeForAction(stateReport) { const prompt 你是 Minecraft 挖钻石智能体。请根据状态决定下一步动作。 状态 ${JSON.stringify(stateReport, null, 2)} 只能输出 JSON { action: dig | explore | move | done, target: 具体方向或坐标, reason: 选择该动作的简短理由 } const result execSync(claude -p ${prompt}, { encoding: utf-8, timeout: 30000, env: process.env }) return JSON.parse(result.trim()) }这段代码的关键在于 prompt 格式固定、动作枚举有限、输出强制 JSON。如果让 AI 自由发挥后面的解析逻辑会变得不可维护。4.2 构造感知-决策-执行主循环有了感知函数、执行函数和决策函数就可以把它们组合成一个主循环。let running true async function agentLoop() { while (running) { const state buildStateReport() const decision askClaudeForAction(state) console.log([agent] 决策:, decision) if (decision.action done || state.diamondCount 8) { console.log([agent] 目标完成结束循环) running false break } if (decision.action dig) { await collectDiamond() } else if (decision.action explore) { await explore() } else if (decision.action move) { // 尝试解析坐标 } // 每次动作之间留出时间避免游戏刻响应不过来 await bot.waitForTicks(20) } }这个循环看起来简单却是 Agent 的骨架。模型的一次输出只决定一个动作真正的判断依据仍然是下一次环境感知。多轮下来任务会被逐步推进。4.3 让循环在出错时也能继续运行模型输出不一定每次都合法。JSON 解析失败、动作枚举不存在、路径寻路超时都是会出现的问题。要给循环加上容错机制function safeParseAction(rawOutput) { try { const parsed JSON.parse(rawOutput) if (!parsed.action) return { action: explore, reason: 缺少 action 字段 } return parsed } catch (err) { console.error([agent] JSON 解析失败:, rawOutput) return { action: explore, reason: 模型输出非法 } } }兜底动作选择“explore”而不是“停止”是为了让机器人至少保持移动。如果每次非法输出都结束进程整个项目会非常脆弱。4.4 引入 cc-switch 和 Ollama 作为可选配置Claude Code 的 API 配置可以通过环境变量控制。如果团队需要在多个模型网关之间切换可以使用 cc-switch 这类社区工具管理配置。它本质上是一个配置切换器不改变 Agent 的运行逻辑。如果希望把决策层换成本地模型可以借助 Ollama 部署模型并通过兼容接口把 Claude Code 的 base URL 指向本地服务。代价是本地模型的推理能力通常不如云端模型但优势是数据不出本机、成本固定。实际选择取决于你的场景学习实验用官方 Claude Code 更省心离线开发或隐私敏感场景才需要考虑本地模型方案。5. 升级成双人对抗赛裁判计分与多智能体协作5.1 对抗赛规则设计单机器人只能验证“能不能挖到钻石”对抗赛才能真正展示“谁的策略更好”。规则要简单、可执行、可统计。参数建议值说明比赛时长10 分钟时间到则强制结束目标钻石数8 个先达到者获胜参赛方两个机器人或一个机器人和一个玩家AI vs AI 更公平计分方式背包中的钻石数量掉落在外的钻石不算地图范围以出生点为中心 128 格限制探索范围避免无限加载规则越简单裁判逻辑越容易写。实际运行时两个机器人分别用不同username登陆同一个服务器互不通信各自执行自己的决策循环。5.2 裁判模块与计分裁判模块独立于机器人运行负责周期性地读取两个机器人的背包状态并输出比分。let scoreA 0 let scoreB 0 let elapsed 0 const timeLimit 600 const checkInterval 5 function countDiamonds(bot) { return bot.inventory.items() .filter((item) item.name diamond) .reduce((sum, item) sum item.count, 0) } setInterval(() { elapsed checkInterval scoreA countDiamonds(botA) scoreB countDiamonds(botB) console.log([score] ${elapsed}s A${scoreA} B${scoreB}) if (elapsed timeLimit || scoreA 8 || scoreB 8) { endMatch(scoreA, scoreB) } }, checkInterval * 1000) function endMatch(scoreA, scoreB) { if (scoreA scoreB) console.log([result] 平局) if (scoreA scoreB) console.log([result] A 获胜) if (scoreA scoreB) console.log([result] B 获胜) console.log([result] 最终比分 A${scoreA} B${scoreB}) process.exit(0) }裁判模块的价值不只是决定输赢它还会产生结构化的时间线日志。比赛结束后你可以回放任意时间点的双方分差分析某个决策是否有效。5.3 从竞争到协作多智能体扩展对抗赛是竞争型多智能体。另一种更复杂的模式是协作型多智能体一个机器人负责探路和标记矿洞另一个负责跟随挖掘。协作场景需要共享状态最简单的方式是让两个机器人读写同一个 JSON 文件。{ shared_goal: find_diamond, known_caves: [ { x: 100, y: -50, z: 200, status: exploring } ], target_diamond_count: 8, updated_at: 1710000000 }两个机器人每隔几秒读取一次共享文件把自己的探索结果更新进去。这个方案比直接让两个智能体互相聊天更可靠因为文件状态天然可回溯、可恢复。注意多机器人同时跑会导致服务器 TPS 下降机器人数量越多决策循环频率就要越低。本地实验建议先跑 2 个机器人。5.4 多智能体对抗赛的观察重点对抗赛结束后重点复盘三类问题第一决策质量。Claude 有没有在明显有钻石矿的位置继续盲目探索有没有反复在同一个矿洞口进出第二执行效率。机器人寻路是否绕路挖掘后有没有立刻拾取掉落物第三资源配置。两个机器人是否抢同一个矿脉如果是在协作模式下探路信息有没有被另一方有效利用。这些观察比最终比分更重要因为它们直接指向 Agent 系统下一步要调优的地方。6. 完整运行流程、预期输出与常见问题排查6.1 完整启动顺序按以下顺序启动能最大程度避免环境混乱# 第一步启动 Minecraft 服务端 java -Xmx2G -jar server.jar nogui # 第二步确认服务端已输出 Done 启动信息 # 第三步启动机器人 A node botA.js # 第四步启动机器人 B node botB.js # 第五步启动裁判进程 node referee.js如果在同一台机器上运行三个机器人脚本会共享 CPU 和内存资源。先启动服务端再启动机器人最后启动裁判可以避免机器人因为服务端未就绪而反复重连。6.2 预期输出正常情况下可以期待看到以下日志[bot] 已进入服务器 [agent] 决策: { action: explore, target: 向下, reason: 钻石矿通常在深层需要下降 } [bot] 移动到坐标 100, -50, 200 [collect] 附近没有钻石矿石需要继续探索 [agent] 决策: { action: dig, target: diamond_ore, reason: 发现钻石矿石开始挖掘 } [collect] 挖掘完成 [score] 120s A2 B1 [result] 最终比分 A8 B5如果日志长时间停在“附近没有钻石矿石”说明探索策略没有有效向深层推进。如果频繁出现“JSON 解析失败”说明 prompt 格式约束不够严格需要在提示词里增加更强硬的输出限制。6.3 常见问题排查表问题现象常见原因检查方式处理建议claude命令找不到未全局安装或 PATH 未配置执行npm root -g查看全局目录将 npm 全局目录加入 PATH重新安装Claude Code 登录报unfortunately, claude is not available to new users right now账号资质、注册授权范围等原因查看官方文档的账号开放说明确认账号符合官方开放条件使用合规授权方式不要通过非正规渠道获取账号Bot 无法登录服务器服务器版本与 Mineflayer 版本不匹配对比服务端和bot.version统一使用同一版本如 1.20.1Bot 上线后被踢出用户名冲突查看服务器日志更换username机器人挖不到钻石探索深度不够检查日志中的 Y 坐标让机器人下降到 Y-54 附近钻石分布更密集决策超时API 响应慢或网络波动查看execSync是否抛出 timeout加大超时时间增加重试机制模型输出非法 JSONPrompt 约束不足打印原始输出固定输出格式在解析失败时兜底执行探索两个机器人卡在同一位置寻路目标互相冲突查看服务器 TPS 和日志给两个机器人分配不同出生点或探索方向6.4 排查链路推荐顺序遇到问题时不要先怀疑模型。按以下顺序排查服务器是否正常启动TPS 是否稳定。机器人是否成功上线日志有没有连接错误。机器人所在位置、深度是否符合预期。感知函数返回的状态字段是否完整。模型返回的动作是否被正确解析。执行函数是否正常返回有没有抛异常。大多数“AI 不干活”的问题其实都出在前三层。环境稳定之后再逐步调试模型 Prompt。7. Agent 工程化最佳实践与后续扩展方向7.1 Agent 循环里的工程细节跑通最小闭环之后要把精力放在稳定性上。以下几个细节是实际运行中最重要的。固定 Prompt 输出格式。大模型对格式的要求依赖 prompt 约束要在 prompt 中明确“只能输出 JSON禁止额外解释”同时在代码里做兜底解析。限制单次决策成本。每次调用都会消耗 token。不要让 Agent 在“前方没有钻石”的情况下反复问模型先用脚本做简单探索。日志要带时间戳和状态切片。每一轮循环记录决策、动作、状态变化赛后才能定位问题。function logRound(state, decision, result) { const line { time: new Date().toISOString(), position: state.position, diamondCount: state.diamondCount, decision, result } console.log(JSON.stringify(line)) }结构化日志比散装文字更容易处理。用JSON.stringify输出一整行后续可以用 jq 或 Python 脚本快速分析。7.2 成本、安全与资源控制生产化运行之前要解决成本和风险问题。API Key 必须通过环境变量或密钥管理服务加载不能出现在代码仓库和日志里。单次实验也要关注 token 消耗建议记录每一轮调用 token 数设置单次比赛预算。Minecraft 服务器只监听本机或可信局域网地址。不要把带online-modefalse的服务器暴露到公网否则任何人都能连接并进入你的实验环境。每次运行要设置硬性超时。智能体循环不能无限跑比赛时间、最大决策次数、最大循环次数都要有上限。7.3 从“挖钻石”扩展到更复杂的 Agent 项目挖钻石项目本质上是一个“目标导向型 Agent”的最小原型。把“钻石”替换成“木材”“铁锭”或者把“挖”替换成“建造”方法几乎不变。可以按以下方向扩展扩展方向需要新增的能力自动建造房屋方块放置、结构规划、材料统计地图绘制路径记录、扫描区块、回传地图数据资源管理背包有限空间下的取舍策略多 Agent 协作共享状态、任务分配、通信协议视觉感知截取游戏画面并交给多模态模型分析如果觉得写代码成本高可以尝试 Dify 搭建可视化工作流把“感知-决策-执行”节点化。它的逻辑和本文一致只是把胶水代码变成了可视化连线。7.4 运行前检查清单每次实验前按下面清单确认一遍能省下大量排错时间服务器版本与mineflayer和minecraft-data版本一致。机器人用户名没有冲突。服务器只监听本机或局域网地址。ANTHROPIC_API_KEY已配置且未写入代码。决策命令配置了超时和重试。探索逻辑有最小深度下限避免在地表反复徘徊。裁判模块有时间限制和结束条件。每轮循环输出结构化日志。记录了比赛开始前的 token 数量或预算。赛后保存了比分时间线和关键决策日志。这份清单同时适用于单机器人测试和双机器人对抗赛。稳定跑完一次完整比赛之后再考虑增加模型能力、视觉模块或更复杂的协作协议。这个项目里最值得一提的判断是不要让 AI 控制每一个细节而是让 AI 只做它擅长的决策把执行交给稳定脚本。挖钻石任务之所以适合入门正是因为它能让决策层和执行层的边界变得非常清楚。下一步练习建议是回到日志文件挑一段失败路径还原当时的 Prompt、状态和决策找出是模型策略问题还是环境感知问题。能完成这个复盘你对 Agent 系统的理解就真正超过“能跑通 demo”的水平了。