最近一段时间AI 下棋、打 DOTA、玩《星际争霸》的新闻已经不太能刺激到技术人了。但如果你刷到过“Claude 智能体在《我的世界》里比谁先挖到钻石”这种对抗赛视频可能会停下来多看两眼一个 AI 在 3D 开放世界里自主找矿、挖矿、合成工具、再往地下钻这个过程和传统的“跑一个棋盘游戏”完全是两码事。这篇文章就以《【原声中配】27-Claude智能体MC挖钻石对抗赛全记录》这个系列内容为引子拆解一个真正的智能体Agent在 MC 里挖钻石时背后需要什么样的系统设计、代码结构和工程兜底。我们会从一个比赛视频出发讲到智能体的 observe-think-act 循环、环境接入、决策模型、行动执行协议再到实际跑通一套最小系统的完整代码。如果你正准备入门 AI Agent 开发或者想把 Claude 这类大模型接入到一个有真实物理规则和状态反馈的环境里这篇文章会比其他“Hello World”教程更有参考价值。1. 一场挖钻石比赛为什么值得技术人围观先给一个判断MC 挖钻石之所以成为智能体测试场不是因为它“好玩”而是因为它把 AI Agent 需要面对的所有工程问题都压缩到了一个看似简单的任务里。很多人以为智能体就是“大模型 一个函数调用”。但真正的 Agent 要解决的是目标如何分解任务是“挖到钻石”第一步是砍树、造木镐还是先找到洞穴状态如何感知智能体怎么知道自己在哪里、身上有什么工具、脚下是什么方块动作如何执行大模型只是输出文字谁来把“往西走 10 格挖脚下的石头”变成游戏里的真实操作失败如何恢复掉进岩浆、被怪物打死、挖错了方向智能体能不能自己意识到并换一条路线资源如何约束每次调用大模型都有 token 成本和时间延迟智能体不能每走一步都问一次大模型。对抗赛的形式又把难度往上推了一层。两支智能体在同一个地图、同样的资源条件下竞争比的不仅是“能不能挖到钻石”还包括谁的规划更高效、谁的探索策略更合理、谁在关键时刻更少犯错。这种“同图对抗”本身就是很好的 Agent 评测方式比单独的指标打分直观得多。所以这个系列表面上是一期游戏实况实际上是在展示一个 Agent 系统的完整工作流。你完全可以把“挖钻石”替换成“在服务器上排查故障”“写一个周报并发送邮件”“根据日志定位线上问题”底层逻辑是完全一样的。2. 智能体在 MC 里到底怎么干活核心概念在进入代码之前先把几个容易混淆的概念理清楚。很多读者会问Claude 和 Claude Code 和 Claude 智能体到底是什么关系这里做一个对比。概念本质在挖钻石任务中的角色Claude大语言模型负责“思考”根据当前状态生成下一步动作Claude Code终端里的编码助手可以理解为一种 Agent 形态擅长读写文件和执行命令Claude 智能体Agent大模型 工具 环境感知 行动循环整个挖钻石系统包括模型、控制脚本、MC 客户端MC 环境一个实时 3D 模拟器负责“反馈”提供坐标、方块信息、物品栏状态很多教程把 Agent 讲得很玄其实核心就是一个循环观察Observe从环境里采集状态数据。在 MC 里就是坐标、朝向、背包、周围方块。思考Think把状态整理成上下文交给大模型让它决定下一步动作。行动Act把模型的输出解析为具体的环境指令执行后环境发生变化。再次观察拿到新的状态继续循环。这个循环听起来简单但工程上每一步都有大量细节。比如观察频率控制MC 里方块数据量很大不可能把整个地图都塞进上下文再比如行动粒度一次让模型输出“走到 X 坐标朝向 Y挖方块 Z”是合理的但让模型输出“移动 0.3 格”就完全没有必要因为游戏引擎已经有寻路能力。这里还涉及一个关键设计决策模型决策粒度。在成熟方案里大模型不负责底层控制而是负责“高层指令”比如“先去附近砍树”底层由程序化的控制逻辑执行比如用寻路算法走到树旁边。这种分层设计恰恰是 Agent 工程里最重要的经验之一大模型的价值在决策不在控制。3. 挖钻石任务的本质智能体的三层能力一场完整的挖钻石对抗其实是在同时考验智能体的三层能力。理解这三层你就知道为什么这个任务比下棋复杂。3.1 第一层目标分解与规划“挖到钻石”是一个天然的多步骤任务先确认附近有没有树有树才能合成工作台。有了工作台才能合成木镐然后挖石头合成石镐。有了石镐才能更高效地挖矿洞。挖矿洞要选对高度钻石只在特定深度出现。一路往下挖的时候还要避开岩浆、水坑和怪物。这个任务链条非常长而且中间每一步都可能失败。如果智能体没有规划能力只会“见一步走一步”大概率会在森林里迷路或者在矿洞里反复绕圈。在实现上这层能力通常由系统提示词System Prompt来完成告诉模型“你的最终目标是挖到钻石请使用合理的 Minecraft 生存策略”同时维护一个全局任务状态让模型知道“目前已经完成到哪一步”。3.2 第二层探索与信息收集MC 是一个部分可观测环境。智能体看不到整个地图必须通过移动和观察来获取信息。这很像现实中的运维场景你不可能一眼看到整个系统的状态必须一步步登录、查日志、跑命令才能定位问题。在对抗赛中探索策略的差异会直接决定胜负。有的智能体选择沿地表狂奔寻找洞穴入口有的选择直接向下挖竖井有的先造一个简易矿道再分支挖掘。哪种策略更好取决于地图生成规则而这个判断恰恰是大模型擅长的因为它读过大量 MC 攻略知道钻石生成的高度范围和分布规律。3.3 第三层失败恢复与环境适应挖钻石过程中最常见的失败场景包括掉进岩浆导致工具和物品全部烧毁。挖到了基岩层发现高度不对。被怪物击杀回到出生点。背包满了挖到的好东西带不回去。一个“会聊天”的模型无法应对这些情况但一个合格的 Agent 必须能感知异常状态、调整计划并重新执行。比如模型发现“我掉进岩浆了当前血量很低”应该立刻输出“先往高处爬并离开岩浆寻找安全区域治疗”而不是继续执行原来的挖掘指令。这层能力是 Agent 和后端接口调用最大的区别后端接口只要响应正确Agent 必须应对环境变化并动态调整行为。4. 环境准备搭一套最小可运行的 Claude 智能体理论讲完下面进入实战。我们先把“对抗赛”简化掉搭一个最小系统一个 Claude 智能体接入一个本地 MC 服务器能够自主完成“挖到一颗钻石”这个任务。先说明完整复刻视频里的豪华对抗赛很难但跑通核心闭环只需要四个组件一个 MC Java 版服务器本地跑即可版本建议 1.20 左右实际以你安装的客户端为准。一个能连接 MC 的机器人客户端这里使用 Node.js 生态的mineflayer库。一个决策模块使用 Claude API 或本地的 Claude Code 通道接收状态、输出动作。一个控制协议定义模型输出的 JSON 格式让机器人客户端能解析并执行。4.1 安装基础环境由于 mineflayer 是 Node.js 库建议先装好 Node.js 18 以上版本。然后创建项目目录并安装依赖mkdir mc-agent cd mc-agent npm init -y npm install mineflayer决策模块用 Python 写更方便调用 Anthropic SDKpip install anthropic这里有个容易踩坑的地方很多人直接在全局环境里安装各种依赖结果 Node 和 Python 的包版本互相冲突。更稳妥的做法是每个项目单独建虚拟环境Node 项目保留自己的node_modulesPython 依赖用venv隔离。4.2 启动 MC 服务器并关闭在线验证单人测试环境下不需要真的注册正版账号。在服务器的server.properties里关闭在线验证online-modefalse server-port25565 motdMC Agent Test Server注意online-modefalse只适合本机或内网实验不要把这套配置暴露到公网否则任何人都能伪造身份进入你的服务器。生产环境或公网联机场景下请务必保持online-modetrue并做好白名单和权限管理。4.3 获取 Claude API 访问能力智能体的大脑由 Claude 提供。你可以通过 Anthropic 官方 API 获取密钥也可以使用兼容 Anthropic 协议的其他服务。这里的关键点是密钥不要硬编码在代码里建议放到环境变量中。export ANTHROPIC_API_KEY你的密钥如果密钥没生效最常见的报错是authentication_error或者invalid_api_key。排查顺序是先确认环境变量是否真的注入到当前进程再确认网络能正常访问 API 服务最后确认账号是否有对应模型的调用权限。5. 完整代码实现观察-思考-行动循环下面直接给出一个可以跑通的最小实现。整个系统由三个文件组成bot.jsmineflayer 客户端负责连接服务器、操作角色、上报状态。agent.py决策模块负责把状态整理成提示词、调用 Claude、解析动作。protocol.json动作协议示例说明模型输出应该长什么样。5.1 建立游戏连接先写bot.js的核心逻辑连接 MC 服务器并在spawn后打印当前坐标。// 文件路径mc-agent/bot.js const mineflayer require(mineflayer); const bot mineflayer.createBot({ host: localhost, port: 25565, username: AI_Miner, version: 1.20.1 // 请根据你的服务器实际版本修改 }); bot.on(spawn, () { console.log([Bot] 已进入游戏当前坐标, bot.entity.position); bot.chat(我是 AI 矿工开始执行挖钻石任务); }); bot.on(error, (err) { console.error([Bot] 连接错误, err.message); }); bot.on(kicked, (reason) { console.warn([Bot] 被服务器踢出, reason); });运行node bot.js如果控制台打印出坐标说明连接链路已经打通。这里的重点是mineflayer 提供的是程序化的操作原语比如移动、挖掘、使用物品。它不管“该挖哪里”“该用什么工具”这些决策要交给更上层的大模型。所以在设计时不要尝试让 mineflayer 做事先规划它的任务就是执行和执行反馈。5.2 状态采集与动作协议为了让大模型能“观察”我们需要把游戏状态压缩成一段可读的文本或 JSON。MC 里的状态非常多不能全塞给模型否则上下文长度和 token 消耗都会失控。最小状态下只需要四类信息当前位置和维度。当前血量、饥饿值。背包里的关键物品。周围 5 格内有哪些类型的方块。对应地模型输出的动作也需要定义成一个严格协议。这里建议用 JSON 格式方便解析和校验{ thought: 我现在有木镐和石镐背包有 3 个食物应该继续向下挖矿寻找钻石层。, action: { type: dig_down, direction: south, steps: 5, priority: high } }动作类型也不能太细。常见的动作只要覆盖移动、挖掘、拾取、合成、检查背包、报告状态。如果模型输出了协议之外的动作系统要么丢弃要么由兜底逻辑处理。5.3 决策模块Python 调用 Claude下面写agent.py它的职责是接收一段状态 JSON构造提示词调用 Claude API返回模型决策。# 文件路径mc-agent/agent.py import json import os from anthropic import Anthropic # 初始化客户端密钥从环境变量读取 client Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY)) SYSTEM_PROMPT 你是一个在《我的世界》中执行挖钻石任务的智能体。 你的最终目标找到并挖掘至少 1 颗钻石。 你可以使用的动作类型包括 - move_to: 移动到指定坐标 - dig: 挖掘指定方块 - collect: 拾取附近掉落物 - craft: 合成指定物品 - check_inventory: 检查背包 - report: 向人类报告当前状态和下一步计划 输出要求 1. 只输出 JSON不要输出任何解释性文字。 2. JSON 必须包含 thought 和 action 两个字段。 3. action.type 必须是上述动作类型之一。 4. 如果当前状态无法确定下一步输出 type 为 report 的动作。 def decide_next_action(state: dict) - str: 根据当前游戏状态让 Claude 输出下一个动作 JSON。 state_text json.dumps(state, ensure_asciiFalse, indent2) response client.messages.create( modelclaude-sonnet-4-5, # 以你账号可用的实际模型为准 max_tokens512, systemSYSTEM_PROMPT, messages[ { role: user, content: f当前游戏状态如下\n{state_text}\n请决定下一步动作。 } ] ) return response.content[0].text.strip()这段代码体现了几个工程要点系统提示词里明确列出了动作白名单。这一步非常重要否则模型可能输出“向右上方跳跃 30 度”这种无法执行的指令。max_tokens不要设置太大动作只是一个 JSON256 到 512 足够。这能显著降低响应延迟和成本。所有状态先转成 JSON 文本再塞进用户消息。这样格式清晰模型更容易提取关键信息。5.4 行动执行器把模型决策变成真实操作最后是bot.js里的执行器。它的职责是接收agent.py输出的 JSON解析出动作类型调用 mineflayer 对应的 API 执行。// 文件路径mc-agent/executor.js const mineflayer require(mineflayer); // 根据模型输出的动作类型执行对应的游戏操作 async function executeAction(bot, action) { switch (action.type) { case move_to: { const target action.target; await bot.pathfinder.goto( new mineflayer.vec3(target.x, target.y, target.z) ); return 已移动到 (${target.x}, ${target.y}, ${target.z}); } case dig: { const block bot.blockAt( new mineflayer.vec3(action.x, action.y, action.z) ); if (!block) { return 错误目标位置没有方块; } await bot.dig(block); return 已挖掘 ${block.name}; } case report: return 报告${action.message || 暂无报告}; default: return 未知动作类型${action.type}; } } module.exports { executeAction };执行器的关键设计是只执行白名单动作。未知动作直接返回错误而不是尝试猜测模型意图。这样即使模型偶尔抽风系统也不会做出不可控的行为。上面这段代码依赖mineflayer-pathfinder插件来实现寻路实际使用时需要额外安装npm install mineflayer-pathfinder然后在bot.js里加载插件并注册bot.pathfinder。这里不再展开读者可以查看 mineflayer 官方文档按版本说明完成配置。5.5 主循环把三部分串起来有了状态采集、决策模块、执行器剩下就是最核心的主循环。伪代码如下# 文件路径mc-agent/main.py import json from agent import decide_next_action, STATE_VERSION def run_agent(bot): while True: # 1. 观察 state collect_state(bot) # 2. 思考 decision decide_next_action(state) # 3. 行动 action parse_action(decision) result execute_action(bot, action) # 4. 记录日志 log_decision(state, decision, result) # 5. 检查任务是否完成 if has_diamond(bot): break time.sleep(1)这里最容易被忽略的是最后一步任务终止条件。很多新手做完前四步就停了结果智能体挖到钻石之后还在继续挖浪费 token 和时间。在对抗赛场景里更要强调终局判断谁先背包里有钻石谁就赢。6. 运行验证如何判断智能体真的在“变聪明”运行整个系统后不要只看“有没有挖到钻石”这一个结果。建议按照下面的观察维度来验证系统是否正常工作。6.1 看决策日志每一轮循环都应该记录输入状态摘要。模型输出的 thought 和 action。执行结果。把这部分日志打印出来你会看到类似这样的轨迹[观察] 位置(120, 70, 300), 背包[木镐, 石镐, 食物x3], 周围方块[石头, 泥土] [思考] 当前处于地表下方约 10 格应该继续向下寻找钻石层。 [行动] dig_down, steps5 [执行] 已挖掘 5 个方块如果日志里出现反复重复同一个动作、或者模型输出的动作完全脱离实际状态说明提示词或状态采集需要调整。6.2 记录关键节点回放对抗赛视频里最精彩的不是最终结果而是过程中的关键转折智能体怎么发现矿洞的、怎么在岩浆边缘停住的、怎么调整挖掘方向的。对应到工程上就是要在系统里加上事件标记。比如if inventory_has(diamond): log_event(SUCCESS, 背包检测到钻石任务完成) if health 5: log_event(DANGER, 血量过低触发安全策略)这些事件标记以后可以用来做版本对比改了一版提示词之后智能体的失败次数有没有下降、平均完成时间有没有缩短。6.3 用多轮对抗检验稳定性单次跑通只是“运气好”。如果你想真正验证智能体的决策能力至少跑 5 到 10 局统计平均完成时间。成功率成功挖到钻石的局数占比。失败原因分布掉岩浆、迷路、被怪物打死、卡在角落。这个统计思路和线上 A/B 测试一模一样。不要用单一局的结果来评价一个 Agent 系统。7. 常见问题与排查思路跑通这套系统之后你大概率会遇到下面几个问题。我整理了最典型的排查表格问题现象可能原因排查方式解决方案智能体连接服务器后被踢出服务端版本与客户端版本不匹配查看server.properties版本信息和 bot 启动日志统一 MC 服务端与 mineflayer 的版本模型输出动作无法解析JSON 格式不规范打印 model 原始输出检查是否包含解释性文字在提示词中强调“只输出 JSON”增加输出格式校验和重试机制智能体原地重复执行同一动作状态信息不足模型无法感知变化检查状态采集是否包含位置和背包变化在状态中增加执行结果反馈让模型看到“上一步已执行”Claude API 调用超时上下文过长或服务端过载查看请求耗时和 token 用量精简状态信息、启用超时重试设置max_tokens上限Windows 下claude命令找不到Claude Code 安装后未加入 PATH终端执行where claude或重新打开终端重新安装并配置环境变量或在 CLI 中指定完整路径智能体挖到钻石后不停止缺少任务终止判断检查主循环是否有has_diamond判断增加背包检测逻辑命中后立即 break掉落物拾取不到移动过快或拾取距离判断错误检查 collect 动作执行时机在挖掘后增加短暂等待再执行拾取其中“Claude API 调用超时”是最会影响对抗赛观感的问题。两个智能体比赛谁先挖到钻石时如果某一方每次决策都要等 10 秒那即使决策再聪明也很难赢。优化方向有两个一是控制状态长度只传关键信息二是设置合理的超时重试避免一次请求挂死整个循环。8. 从游戏到生产Agent 工程的通用经验看完上面的例子你会发现 MC 挖钻石这个场景几乎就是真实 Agent 工程的缩影。下面这些经验既适用于游戏智能体也适用于自动化助理、运维 Agent、数据查询 Agent。8.1 动作协议必须白名单化让大模型直接输出自然语言命令是非常危险的。在生产环境中动作类型、参数范围、可调用工具都必须有严格白名单。比如财务 Agent 只能调用“查询订单”“生成报表”等固定动作绝对不能让它输出“执行 delete 语句”这种自由动作。动作协议应该像 API 接口一样有 schema建议用 JSON Schema 做校验{ $schema: http://json-schema.org/draft-07/schema#, type: object, properties: { action: { type: object, properties: { type: { type: string, enum: [move_to, dig, collect, craft, report] }, target: { type: object, properties: { x: {type: number}, y: {type: number}, z: {type: number} } } }, required: [type] }, thought: {type: string} }, required: [thought, action] }8.2 状态信息要精简且有反馈大模型的上下文窗口是有限的token 是有成本的。每次循环塞入整个世界的全部信息既慢又贵。正确做法是只传“和当前目标相关的状态”并且一定包含上一步动作的执行结果反馈。模型需要知道“我刚刚说要挖方块现在挖到了没”否则它会失去对环境的感知连续性。8.3 必须有安全兜底和人工中止通道在 MC 里最危险的操作是挖到脚下方块导致掉进岩浆。在生产 Agent 里对应的就是误删数据、越权访问、执行了不可逆命令。所以任何 Agent 系统都必须有操作前校验。危险操作二次确认。执行超时熔断。人工中止开关。不要相信大模型“永远不会输出危险指令”。你要做的是在系统层面兜住它。8.4 日志与回放是 Agent 调试的核心工具Agent 的调试比普通程序难得多因为它是多步交互、有随机性的。没有日志你根本无法定位是提示词问题、状态采集问题、还是执行器问题。强烈建议记录每一轮完整的状态、思考、动作、结果。支持按局回放。对比不同版本 Prompt 的决策质量和成功率。这也是对抗赛视频最有价值的地方它天然就是一局完整的回放观众能清楚看到每个决策导致的结果。9. 总结下一站往哪里走把一个 Claude 智能体放进 MC 挖钻石本质上是在做一个非常小的“自主决策-行动验证-失败恢复”系统。这个小系统放大到真实业务场景就是现在炙手可热的 AI Agent自动处理工单、自动排查故障、自动完成多步骤任务。如果你被这期对抗赛视频勾起了兴趣建议按下面的路线继续深入第一先跑通本文的最小闭环把“连接服务器-采集状态-调用 Claude-执行动作”这条链路走顺哪怕只在本地跑通一次也算。第二尝试给智能体增加记忆能力。目前的实现里模型只能看到最近一次状态看不到整个任务的历史轨迹。你可以把关键动作和结果以“经验”形式存下来在下次决策时作为参考输入。第三尝试把单智能体改成多智能体对抗或协作。两个 Claude 智能体在同一个服务器里比赛挑战会瞬间上升它们需要处理竞争、防止互相干扰、还要保证各自目标的独立性。第四把控制协议和决策模块抽象成通用组件。今天它连接的是 MC明天它连接的就是你的代码仓库、数据库、服务器集群。底层逻辑完全一样。最后提醒一句无论智能体跑在哪里安全边界、动作白名单、回滚机制和人工监督永远比“让它更聪明”优先级更高。希望这篇文章能帮你从一场游戏对抗赛里看出 Agent 工程的真问题并能亲手把它跑起来。建议收藏备用尤其是第 5 节和第 7 节的代码与排查表后续做 Agent 开发时大概率会翻回来查。