OpenClaw Minecraft

核心用法

OpenClaw Minecraft是一个基于Mineflayer的Minecraft机器人控制器，通过REST API以JSON格式发送动作指令实现游戏内自动化操作。

主要功能：

• 创建并连接Minecraft机器人到指定服务器
• 读取机器人实时状态（位置、背包、任务等）
• 批量发送动作指令（支持5-10个动作的action bundle）
• 支持两种执行模式：until（条件达成停止）和loop（定时循环）
• 集成Gateway cron实现每30秒自主决策循环

认证方式：

• 开放注册模式（Open Registration）：无需密钥，直接获取JWT
• 代理注册模式（Proxy）：使用allowlist+速率限制的proxyKey
• 主密钥注册：管理员签发token后分发给agent

支持动作：chat、move_to、move_relative、move、dig、place、equip、use_item、attack、follow、jump

显著优点

• LLM本地推理：API密钥不上传，仅发送JSON动作，隐私安全性较好
• 批处理高效：单次请求可包含多步动作，减少网络往返
• 灵活执行模式：until模式适合导航任务，loop模式适合周期性扫描/聊天
• 定时自主：cron驱动无需心跳，适合长期挂机场景
• 状态可观测：实时轮询任务状态和机器人上下文

潜在缺点与局限性

• 公网暴露风险：示例使用ngrok临时域名，生产环境需固定域名+TLS
• 开放注册安全隐患：若启用open registration，任何知道端点的人可注册机器人
• 动作可靠性有限：best-effort执行，断连或物品缺失时可能失败
• 无媒体支持：纯JSON载荷，不支持截图、文件上传等富媒体交互
• 硬编码依赖：必须覆盖CRON_PROMPT.md，可能与其他技能冲突
• 版本兼容性：需显式指定Minecraft版本（如1.21.9），版本不匹配可能导致连接失败

适合人群

• 需要自动化Minecraft农场、建筑、巡逻的服主或玩家
• 开发游戏AI agent的研究者（基于Mineflayer生态）
• 希望用自然语言控制游戏角色的LLM应用开发者

常规风险

| 风险类型 | 说明 | 缓解建议 |

|---------|------|---------|

| 未授权访问 | open registration模式下token可被任意获取 | 禁用开放注册，改用proxy或主密钥模式 |

| 资源滥用 | 机器人可能被用于服务器破坏（griefing） | 限制action权限、速率限制、操作审计 |

| 网络中间人 | ngrok免费域名无固定证书锚点 | 部署自有域名+Cloudflare或自签证书 |

| 任务死锁 | until模式可能因条件无法满足永久阻塞 | 始终设置timeoutMs上限 |

| 状态不同步 | 本地LLM决策与游戏实际状态可能偏差 | 高频轮询state接口，增加校验逻辑 |

核心用法

OpenClaw Minecraft 是一个基于 Mineflayer 框架的 Minecraft 机器人控制 Skill，允许用户通过 JSON API 创建和管理游戏内自动化代理。核心工作流程包括：注册获取 JWT 令牌、创建机器人实例、连接 Minecraft 服务器、读取状态并发送动作指令。支持两种主要操作模式——until（到达条件停止）和 loop（定时重复执行），可处理聊天、移动、挖掘、建造、攻击等 12 种基础动作。

该 Skill 的最大特色是定时自主循环机制，通过 Gateway cron 每 30 秒触发一次决策流程，使机器人能够在无需人工干预的情况下持续运行。开发者需将 CRON_PROMPT.md 覆盖至工作区根目录，确保 cron 任务能正确加载自主决策逻辑。

显著优点

1. 架构清晰：LLM 在本地完成推理，仅向控制器发送 JSON 动作，避免 API 密钥外泄
2. 批处理高效：单次请求可打包 5-10 个动作，减少网络往返延迟
3. 状态机友好：until 模式内置停止条件（如 reach_position），便于构建复杂行为树
4. 零依赖：纯文档/配置型 Skill，无第三方 npm 包引入

潜在缺点与局限性

• 动态DNS风险：API 端点硬编码为 ngrok 隧道地址（56eb-125-246-120-211.ngrok-free.app），域名随时可能失效或被恶意接管
• T3来源可信度：个人开发者维护，无 GitHub 仓库背书，代码透明度有限
• 配置侵入性：强制覆盖工作区 CRON_PROMPT.md，可能破坏用户现有定时任务
• 令牌管理粗放：JWT 建议存储于明文 JSON 文件，缺乏加密保护
• 网络隔离薄弱：IP 直连模式缺乏域名验证，易受中间人攻击

适合人群

• 拥有自建 Minecraft 服务器、希望快速部署自动化 NPC 的服主
• 熟悉 Mineflayer 生态、能自行审计 API 端点安全性的开发者
• 接受实验性功能、愿意承担 T3 来源风险的极客用户

常规风险

| 风险类型 | 严重度 | 说明 |

|---------|--------|------|

| 域名接管 | 高 | ngrok 免费域名过期后可能被攻击者注册，重定向恶意指令 |

| 令牌泄露 | 中 | `memory/mc-auth.json` 若权限配置不当，可导致账户被盗 |

| 配置丢失 | 低 | 强制覆盖 CRON_PROMPT.md 可能破坏其他 Skill 的定时任务 |

| 中间人攻击 | 中 | 缺乏证书固定，TLS 连接存在被截获可能 |

建议在生产环境部署前，将控制器迁移至固定域名或自托管服务器，并实施 mTLS 双向认证。