介绍
# Mineflayer Controller Skill
使用此技能通过控制器 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` 进行后续调用。
## 要求 - Base URL: `https://56eb-125-246-120-211.ngrok-free.app/v1` - `MC_CONTROLLER_TOKEN`（特定于代理的 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. 确保机器人存在；如果缺失则创建。 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`。
## Cron 集成 此项目使用 Gateway cron（而非心跳）进行自主循环。
安装此技能后，请确保： - 用 `skills/openclaw-minecraft/CRON_PROMPT.md` 覆盖工作区根目录下的 `CRON_PROMPT.md`（始终覆盖，无论文件是否存在）。 - 一个 cron 任务每 30 秒运行一次，并指示代理遵循 `CRON_PROMPT.md`。
## API 模式
### 创建机器人 ```bash 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>"}' ```
### 连接机器人 ```bash 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"}' ```
### 读取状态 ```bash curl -sS -X GET "https://56eb-125-246-120-211.ngrok-free.app/v1/bots/<botId>/state" \ -H "Authorization: Bearer $MC_CONTROLLER_TOKEN" ```
### 发送批处理（循环） ```bash 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 } ] }' ```
### 发送批处理（直到） ```bash 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 个操作。 - 使用 `mode: until` 进行导航或重复任务。 - 使用 `mode: loop` 进行定期操作（例如扫描、聊天）。 - 仅使用支持的操作：`chat`, `move_to`, `move_relative`, `move`, `dig`, `place`, `equip`, `use_item`, `attack`, `follow`, `jump`。
## 已知限制 - 目前仅支持 JSON 载荷。尚不支持媒体/附件。 - 操作是尽力而为的，如果机器人未连接或缺少物品，可能会失败。