核心用法
OpenClaw Minecraft 是一款基于 Mineflayer 的 Minecraft 机器人控制器，通过 REST API 提供 JSON 格式的动作指令系统。用户需先通过开放注册或代理注册获取 JWT Token，然后依次完成创建机器人、连接服务器、读取状态、发送动作指令的工作流程。核心 API 包括 /bots（创建）、/bots/{id}/connect（连接）、/bots/{id}/state（状态读取）和 /bots/{id}/act-batch（批量动作执行）。
显著优点
1. 结构化动作系统：支持 chat、move_to、dig、place、attack 等 15+ 种原子动作，可通过 mode: until（条件终止）或 mode: loop（定时循环）实现复杂行为编排
2. 自主运行架构：基于 Gateway Cron 的 30 秒定时触发机制，无需持续心跳连接，配合本地 LLM 推理实现真正的无人值守自动化
3. 安全隔离设计：API Key 和 LLM 密钥完全本地化，控制器仅接收 JSON 动作指令，避免敏感信息外泄
4. 批量任务优化：单次请求可打包 5-10 个动作，减少网络往返，支持 queue 排队模式避免任务中断
潜在缺点与局限性
- 功能边界受限：仅支持 JSON 载荷，无法处理媒体文件或附件；动作执行为"尽力而为"模式，网络波动或物品缺失会导致失败
- 部署依赖较重：需要自行维护 ngrok 隧道或公网服务器，开放注册模式存在未授权访问风险
- 调试门槛较高：需同时理解 Minecraft 协议、Mineflayer API 和 cron 调度逻辑，错误排查涉及多层链路
适合人群
- 熟悉 JavaScript/Node.js 生态的开发者
- 需要 7×24 小时 Minecraft 自动化（农场、监控、聊天机器人）的服务器管理员
- 希望将 LLM 代理与游戏世界打通的 AI 实验者
常规风险
| 风险类型 | 说明 |
|---------|------|
| 未授权访问 | 开放注册模式下任意 agentName 可获取 Token，建议生产环境使用 proxyKey 白名单 |
| 资源滥用 | 高频 cron 任务可能导致服务器 CPU/内存过载，需合理设置 `timeoutMs` 和 `intervalMs` |
| 游戏封禁 | 自动化行为可能触发 Minecraft 服务器的反作弊机制，建议控制操作频率 |
| 数据持久化 | Token 默认存储于 `memory/mc-auth.json`，需确保文件权限和备份策略 |