Mineflayer 控制器技能

使用此技能通过控制器 API 创建和控制 Minecraft 机器人。控制器仅执行 JSON 动作。请勿向控制器发送 API 密钥或其他机密信息。代理在本地执行 LLM 推理，仅发送动作。

首次注册（开放注册）

如果启用了开放注册，代理可以自行签发令牌：

curl -sS -X POST "https://56eb-125-246-120-211.ngrok-free.app/v1/auth/open/register" \
  -H "Content-Type: application/json" \
  -d '{"agentName":"andy"}'

建议：将响应存储在memory/mc-auth.json并复用该访问令牌以供后续调用。

要求

• 基础 URL：https://56eb-125-246-120-211.ngrok-free.app/v1
• MC_CONTROLLER_TOKEN（代理特定的 JWT）

要获取 JWT，操作员应调用POST /v1/auth/register并提供主签发者密钥，然后将返回的访问令牌分享给代理。刷新令牌可以通过POST /v1/auth/refresh.

如果您不想共享主密钥，控制器可以公开POST /v1/auth/proxy/register并设置允许列表和速率限制。在此模式下，代理使用proxyKey请求访问令牌。

如果启用了开放注册 (POST /v1/auth/open/register)，代理无需代理密钥即可请求访问令牌。这种方式安全性较低，仅应在您接受开放访问时使用。

安全规则

• 切勿向控制器发送 LLM API 密钥。
• 仅控制属于您令牌的机器人。
• 优先使用队列: 队列除非您必须中断正在运行的任务。

工作流程

1. 确保机器人存在；如果缺失则创建。
2. 将机器人连接到 Minecraft 服务器。
3. 读取当前上下文的状态。
4. 发送动作请求。
5. 轮询任务状态或订阅事件。

自主循环

为实现自主行为，请重复以下步骤：

1. GET /bots/{botId}/state
2. 如果metadata.currentTaskId已设置，则短暂等待并继续循环。
3. 决定一个安全的动作包（包含5到10个动作），并通过POST /bots/{botId}/act-batch发送。
4. 使用mode: until或mode: loop模式，并为每个动作设置timeoutMs超时时间。

定时任务集成

本项目使用Gateway的定时任务（而非心跳机制）来实现自主循环。

安装此技能后，请确保：

• 覆盖工作区根目录下的CRON_PROMPT.md使用skills/openclaw-minecraft/CRON_PROMPT.md（无论文件是否存在，始终执行）。
• 一个cron任务每30秒运行一次，并指示代理遵循CRON_PROMPT.md中的指令。

API模式

创建机器人

curl -sS -X POST "https://56eb-125-246-120-211.ngrok-free.app/v1/bots" \
  -H "Authorization: Bearer $MC_CONTROLLER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"botId":"<botId>","username":"<botId>"}'

连接机器人

curl -sS -X POST "https://56eb-125-246-120-211.ngrok-free.app/v1/bots/<botId>/connect" \
  -H "Authorization: Bearer $MC_CONTROLLER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host":"127.0.0.1","port":25565,"version":"1.21.9"}'

读取状态

curl -sS -X GET "https://56eb-125-246-120-211.ngrok-free.app/v1/bots/<botId>/state" \
  -H "Authorization: Bearer $MC_CONTROLLER_TOKEN"

发送批次（循环模式）

curl -sS -X POST "https://56eb-125-246-120-211.ngrok-free.app/v1/bots/<botId>/act-batch" \
  -H "Authorization: Bearer $MC_CONTROLLER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actions":[
      {
        "action":"chat",
        "params":{"message":"hello"},
        "mode":"loop",
        "intervalMs":2000,
        "maxIterations":3
      }
    ]
  }'

发送批次（直到模式）

curl -sS -X POST "https://56eb-125-246-120-211.ngrok-free.app/v1/bots/<botId>/act-batch" \
  -H "Authorization: Bearer $MC_CONTROLLER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actions":[
      {
        "action":"move_to",
        "params":{"x":10,"y":64,"z":-12},
        "mode":"until",
        "stopCondition":{"type":"reach_position","radius":1.5},
        "timeoutMs":60000
      }
    ]
  }'

操作指导

• 将自然语言目标转换为一个包含JSON操作的批次。
• 如果目标需要多个步骤，请按顺序将它们包含在一个批次中。
• 每个批次必须包含5到10个操作。
• 对于导航或重复性任务，使用模式：直到。
• 对于其他任务，使用模式：循环用于周期性操作（例如扫描、聊天）。
• 仅使用受支持的操作：聊天、移动到、相对移动、移动、挖掘、放置、装备、使用物品、攻击、跟随、跳跃。

已知限制

• 目前仅支持JSON格式的有效载荷。暂不支持媒体/附件。
• 操作将尽力执行，但如果机器人未连接或缺少物品，可能会失败。