OpenClaw Minecraft

核心用法

OpenClaw Minecraft 是一个基于 Mineflayer 的 Minecraft 机器人控制器，提供 REST API 接口，允许用户通过 JSON 动作指令远程操控游戏机器人。

注册与认证：支持三种认证模式——开放注册（无密钥）、代理注册（proxyKey 白名单）和主密钥注册（运营商签发 JWT）。推荐将 accessToken 存储于 memory/mc-auth.json 复用。

基础工作流：
1. 创建机器人实体（POST /bots）
2. 连接至 Minecraft 服务器（POST /bots/{botId}/connect）
3. 读取实时状态（GET /bots/{botId}/state）
4. 发送批量动作指令（POST /bots/{botId}/act-batch）
5. 轮询任务状态或订阅事件

自主循环：通过 Cron 每 30 秒触发，读取状态→检查当前任务→决策安全动作包（5-10 个动作）→执行。支持 until 模式（条件停止）和 loop 模式（定时重复）。

支持动作：chat、look_at、look、look_around、turn、move_to、move_relative、move、dig、place、equip、use_item、attack、follow、jump、stop、observe。

显著优点

• 纯 JSON 接口：无需处理复杂协议，LLM 可本地推理仅传输动作
• 批量执行：单次请求可包含多步动作，减少网络往返
• 灵活模式：until/loop 双模式适配导航、扫描、聊天等场景
• Cron 原生集成：不依赖心跳机制，降低服务器负载
• 安全设计：API 密钥与 LLM 密钥分离，禁止向控制器泄露敏感信息

潜在缺点与局限性

• 功能边界：仅支持 JSON 负载，不支持媒体/附件传输
• 可靠性：动作为尽力而为，断线或物品缺失会导致失败
• 网络依赖：硬编码 ngrok 临时域名，稳定性受隧道服务影响
• 并发控制：需手动检查 currentTaskId 避免任务冲突
• 开放注册风险：无密钥模式降低准入门槛但增加滥用可能

适合人群

• Minecraft 服务器管理员需要自动化运维（巡逻、监控、欢迎机器人）
• 开发者构建游戏内 AI 助手或 NPC 系统
• 研究人员探索 LLM 与游戏环境的交互边界
• 教育场景演示编程与自动化概念

常规风险

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

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

| 认证泄露 | JWT 或 proxyKey 被截获 | 定期轮换 refresh token，限制 IP 白名单 |

| 机器人滥用 | 开放注册导致恶意注册 | 生产环境禁用开放注册，改用代理或主密钥模式 |

| 游戏违规 | 自动化可能违反服务器 ToS | 事先征得服主同意，遵守 EULA |

| 动作冲突 | 并发指令导致状态混乱 | 优先使用 `queue: queue` 模式，除非必须中断 |

| 服务中断 | ngrok 域名变更或隧道失效 | 部署自建反向代理或固定域名 |

核心功能与架构

OpenClaw Minecraft 是一个纯配置型 Skill，专为通过 Mineflayer 控制器 API 创建和管理 Minecraft 机器人而设计。其核心工作流围绕 JSON 动作指令展开：用户或 LLM 将自然语言目标转换为结构化动作批次，通过 RESTful API 发送至 Mineflayer 控制器执行。动作支持两种执行模式——until（直到满足停止条件）和 loop（周期性重复），并可通过 timeoutMs 设置单动作超时保护。

显著优点

1. 纯文档架构，零执行风险：该 Skill 完全由 Markdown 文档和 JSON 配置文件构成，无任何可执行脚本、危险函数调用或第三方依赖，从根本上杜绝了代码注入、提权攻击等传统安全风险。

2. 清晰的权限分离：设计明确区分「本地 LLM 推理」与「远程 JSON 执行」——API 密钥和敏感信息绝不发送至控制器，仅传递无状态的动作指令，符合最小权限原则。

3. 灵活的认证机制：提供三级注册模式——开放注册（open/register）、代理注册（proxy/register）和主密钥注册（auth/register），用户可根据安全需求选择从完全开放到严格管控的接入策略。

4. Cron 驱动的自主循环：区别于传统心跳机制，采用 Gateway Cron 每 30 秒触发一次自主决策循环，支持持续状态感知（GET /bots/{botId}/state）与批量动作提交（POST /bots/{botId}/act-batch），适合长期运行的自动化场景。

5. 丰富的动作生态：内置 15+ 标准动作，涵盖移动（move_to、move_relative）、交互（dig、place、attack）、观察（look_at、observe）和社交（chat、follow），满足建筑、采集、战斗等多种游戏场景。

潜在局限与风险

1. 外部服务依赖：实际功能完全依赖用户自行部署的 Mineflayer 控制器（文档示例使用 ngrok 临时地址），Skill 本身仅为「使用说明书」。若控制器配置不当、认证泄露或遭受 DDoS，机器人可能被恶意操控。

2. 动作执行的不确定性：文档明确标注「best-effort」特性——网络延迟、服务器规则、物品缺失、路径阻塞等均可导致动作失败，且无自动重试或故障恢复机制，需用户自行实现状态检测与异常处理。

3. 开放注册的安全权衡：若启用 open/register 模式，任何获取端点的实体均可申领 token，在公共网络环境中存在被滥用的风险，建议仅在可信内网或配合防火墙规则使用。

4. 功能边界限制：当前仅支持 JSON 文本指令，不支持媒体附件、复杂条件分支或跨机器人协作，高级自动化场景需结合外部编排工具。

适合人群

• Minecraft 服务器管理员：希望自动化巡逻、建筑或事件响应的技术用户。
• AI 研究与教育场景：需要可控、可观测的 LLM-游戏交互实验环境的开发者。
• 低代码自动化爱好者：偏好通过自然语言描述而非编写插件脚本来控制游戏实体的用户。

常规风险提示

| 风险类别 | 具体表现 | 缓解建议 |

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

| 控制器劫持 | 端点暴露 + 弱认证 → 机器人被外部控制 | 使用代理注册或主密钥模式，配合 IP 白名单与 HTTPS |

| 资源滥用 | 高频动作循环导致服务器 TPS 下降 | 合理设置 `intervalMs` 与 `timeoutMs`，监控服务器性能 |

| 账号封禁 | 自动化行为被反作弊系统识别 | 模拟人类操作间隔，避免超高速挖掘/移动 |

| 数据泄露 | 误将 LLM API 密钥填入动作参数 | 严格遵循「仅发送 JSON 动作」规则，定期审计日志 |

安全认证结论

经 CLS-Certify v2.1.0 全量扫描（T-MD 纯 Markdown 策略），该 Skill 获得 S 级（顶级安全） 评级，六项检测维度全部满分通过，零风险发现。其纯文档本质使其成为「配置即安全」的典范，但用户需清醒认识到：Skill 的安全性不等于使用场景的安全性，最终安全水位取决于 Mineflayer 控制器的部署质量与网络防护策略。