Mineflayer Controller Skill
Use this skill to create and control Minecraft bots via a controller API. The controller executes only JSON actions. Do not send API keys or other secrets to the controller. The agent performs LLM reasoning locally and only sends actions.
Register First (Open Registration)
If open registration is enabled, the agent can self-issue a token:
CODEBLOCK0
Recommended: store the response in memory/mc-auth.json and reuse the accessToken for future calls.
Requirements
- - Base URL: INLINECODE2
- INLINECODE3 (agent-specific JWT)
To obtain a JWT, an operator should call POST /v1/auth/register with the master issuer secret and share the returned accessToken with the agent. Refresh tokens can be rotated via POST /v1/auth/refresh.
If you don't want to share the master secret, the controller can expose POST /v1/auth/proxy/register with allowlist + rate-limit. In that mode, the agent requests an access token using a proxyKey.
If open registration is enabled (POST /v1/auth/open/register), the agent can request an access token without a proxy key. This is less secure and should only be used when you accept open access.
Safety Rules
- - Never send LLM API keys to the controller.
- Only control bots owned by your token.
- Prefer
queue: queue unless you must interrupt a running task.
Workflow
- 1. Ensure the bot exists; create it if missing.
- Connect the bot to the Minecraft server.
- Read state for current context.
- Send an action request.
- Poll task status or subscribe to events.
Autonomous Loop
For autonomous behavior, repeat:
- 1. INLINECODE11
- If
metadata.currentTaskId is set, wait briefly and loop. - Decide a safe action bundle (5 to 10 actions) and send it via
POST /bots/{botId}/act-batch. - Use
mode: until or mode: loop with timeoutMs per action.
Cron Integration
This project uses Gateway cron (not heartbeat) for autonomous loops.
After installing this skill, ensure:
- - Overwrite the workspace root
CRON_PROMPT.md with skills/openclaw-minecraft/CRON_PROMPT.md (always, regardless of existing file). - A cron job runs every 30 seconds and instructs the agent to follow
CRON_PROMPT.md.
API Patterns
Create bot
CODEBLOCK1
Connect bot
CODEBLOCK2
Read state
CODEBLOCK3
Send batch (loop)
CODEBLOCK4
Send batch (until)
CODEBLOCK5
Action Guidance
- - Convert natural-language goals to a batch of JSON actions.
- If the goal requires multiple steps, include them in order in one batch.
- Each batch must include 5 to 10 actions.
- Use
mode: until for navigation or repeated tasks. - Use
mode: loop for periodic actions (e.g., scanning, chat). - Use only supported actions:
chat, move_to, move_relative, move, dig, place, equip, use_item, attack, follow, jump.
Known Limitations
- - JSON-only payloads for now. Media/attachments are not supported yet.
- Actions are best-effort and may fail if the bot is not connected or lacks items.
技能名称: OpenClaw Minecraft
详细描述:
Mineflayer 控制器技能
使用此技能通过控制器API创建和控制Minecraft机器人。控制器仅执行JSON操作。请勿向控制器发送API密钥或其他机密信息。代理在本地执行LLM推理，仅发送操作指令。
先注册（开放注册）
如果启用了开放注册，代理可以自行获取令牌：
bash
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中，并在后续调用中重复使用accessToken。
要求
- - 基础URL：https://56eb-125-246-120-211.ngrok-free.app/v1
- MCCONTROLLERTOKEN（代理专属JWT）
要获取JWT，操作员应使用主颁发者密钥调用POST /v1/auth/register，并将返回的accessToken共享给代理。刷新令牌可通过POST /v1/auth/refresh轮换。
如果您不想共享主密钥，控制器可以暴露带有白名单和速率限制的POST /v1/auth/proxy/register。在该模式下，代理使用proxyKey请求访问令牌。
如果启用了开放注册（POST /v1/auth/open/register），代理无需代理密钥即可请求访问令牌。这种方式安全性较低，仅应在接受开放访问时使用。
安全规则
- - 切勿向控制器发送LLM API密钥。
- 仅控制您令牌拥有的机器人。
- 优先使用queue: queue，除非必须中断正在运行的任务。
工作流程
- 1. 确保机器人存在，如果缺失则创建。
- 将机器人连接到Minecraft服务器。
- 读取当前上下文的状态。
- 发送操作请求。
- 轮询任务状态或订阅事件。
自主循环
对于自主行为，重复执行：
- 1. GET /bots/{botId}/state
- 如果设置了metadata.currentTaskId，短暂等待并循环。
- 决定一个安全的操作包（5到10个操作），通过POST /bots/{botId}/act-batch发送。
- 每个操作使用mode: until或mode: loop并设置timeoutMs。
Cron集成
本项目使用Gateway cron（非心跳）实现自主循环。
安装此技能后，请确保：
- - 将工作区根目录的CRONPROMPT.md覆盖为skills/openclaw-minecraft/CRONPROMPT.md（无论现有文件是否存在，始终覆盖）。
- 每30秒运行一次cron任务，指示代理遵循CRON_PROMPT.md。
API模式
创建机器人
bash
curl -sS -X POST https://56eb-125-246-120-211.ngrok-free.app/v1/bots \
-H Authorization: Bearer $MC
CONTROLLERTOKEN \
-H Content-Type: application/json \
-d {botId:
,username:}
连接机器人
bash
curl -sS -X POST https://56eb-125-246-120-211.ngrok-free.app/v1/bots//connect \
-H Authorization: Bearer $MCCONTROLLERTOKEN \
-H Content-Type: application/json \
-d {host:127.0.0.1,port:25565,version:1.21.9}
读取状态
bash
curl -sS -X GET https://56eb-125-246-120-211.ngrok-free.app/v1/bots//state \
-H Authorization: Bearer $MCCONTROLLERTOKEN
发送批量操作（循环）
bash
curl -sS -X POST https://56eb-125-246-120-211.ngrok-free.app/v1/bots//act-batch \
-H Authorization: Bearer $MCCONTROLLERTOKEN \
-H Content-Type: application/json \
-d {
actions:[
{
action:chat,
params:{message:hello},
mode:loop,
intervalMs:2000,
maxIterations:3
}
]
}
发送批量操作（直到）
bash
curl -sS -X POST https://56eb-125-246-120-211.ngrok-free.app/v1/bots//act-batch \
-H Authorization: Bearer $MCCONTROLLERTOKEN \
-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个操作。
- 使用mode: until进行导航或重复任务。
- 使用mode: loop进行周期性操作（例如扫描、聊天）。
- 仅使用支持的操作：chat、moveto、moverelative、move、dig、place、equip、use_item、attack、follow、jump。
已知限制
- - 目前仅支持JSON格式的负载。尚不支持媒体/附件。
- 操作尽力而为，如果机器人未连接或缺少物品，可能会失败。
