Skill: songjc0511/play-minecraft (version 1.0.0)

--- name: openclaw-mindcraft-controller description: 通过 Mindcraft HTTP API 控制 Minecraft Bot（无内置 LLM）。当用户提到 OpenClaw、外部 agent、REST 接口控制、读取状态、执行动作、批量任务编排时使用。 --- # OpenClaw Mindcraft Controller ## 适用场景 - 用户要用 OpenClaw 或任意外部系统控制 `mindcraft` Bot。 - 用户要求“不要内置 LLM，只走接口调用”。 - 用户需要：读取状态、查询动作 schema、执行动作、排错与恢复。 ## 快速流程 1. 确认服务已启动：`node main.js` 2. 确认配置为外控模式：`settings.js` 中 `external_controller_only: true` 3. 用 `GET /api/v1/agents` 找到 agent 名（如 `andy`） 4. 用 `GET /api/v1/agents/:agentName/actions/schema` 获取动作参数定义 5. 用 `POST /api/v1/agents/:agentName/actions/execute` 执行动作 6. 用 `GET /api/v1/agents/:agentName/state` 校验动作结果 ## 控制规则 - 动作前先查 schema，不要硬编码参数类型和数量。 - 长动作执行后必须二次读 state，避免“命令发送成功但未达成目标”。 - 异常时先执行 `!stop`，再做恢复动作。 - 多动作编排推荐“小步执行 + 每步校验”，不要一次提交过长链路。 ## API 基础信息 - Base URL: `http://localhost:8080` - Content-Type: `application/json` - 关键接口： - `GET /api/v1/agents` - `GET /api/v1/agents/:agentName/state` - `GET /api/v1/agents/:agentName/actions/schema` - `POST /api/v1/agents/:agentName/actions/execute` 详细字段和示例见 [reference.md](reference.md) 与 [examples.md](examples.md)。 ## 推荐执行模板 1. **发现 Agent** - 调用 `/agents` - 选择 `in_game=true` 的 agent 2. **加载能力** - 调用 `/actions/schema` - 缓存 command + params 描述 3. **执行动作** - 调用 `/actions/execute`，传 `command` + `args` 4. **结果验证** - 读 `/state`，核对位置、背包、健康、当前动作 5. **失败恢复** - 执行 `!stop` - 重新规划下一步动作 ## 常见故障处理 - `Agent 'xxx' not found` - 先调 `/agents`，确认 agent 名称。 - `Agent 'xxx' is not connected in game` - Bot 未进服；检查 Minecraft 是否开放 LAN 端口，或进程是否重启失败。 - 参数不匹配（args count/type） - 以 `/actions/schema` 为准重建入参。 - 命令存在但效果不符合预期 - 读 `/state` 二次确认，再做补偿动作（例如 `!stop`、`!goToCoordinates` 重试）。 ## 输出要求（给 OpenClaw 的调用层） - 每次动作调用都记录： - request payload - response payload - state 前后快照（至少位置/背包/健康） - 失败返回要保留原始 `error` 字段，便于排查。

path: examples.md
content: # 调用示例

## PowerShell 示例

### 1) 获取 agent 列表

```powershell
Invoke-RestMethod "http://localhost:8080/api/v1/agents"
```

### 2) 获取状态

```powershell
Invoke-RestMethod "http://localhost:8080/api/v1/agents/andy/state"
```

### 3) 获取动作 schema

```powershell
Invoke-RestMethod "http://localhost:8080/api/v1/agents/andy/actions/schema"
```

### 4) 执行命令（!stats）

```powershell
Invoke-RestMethod `
  -Method Post `
  -Uri "http://localhost:8080/api/v1/agents/andy/actions/execute" `
  -ContentType "application/json" `
  -Body '{"command":"!stats","args":[]}'
```

### 5) 执行命令（!goToCoordinates）

```powershell
Invoke-RestMethod `
  -Method Post `
  -Uri "http://localhost:8080/api/v1/agents/andy/actions/execute" `
  -ContentType "application/json" `
  -Body '{"command":"!goToCoordinates","args":[100,64,100,1.5]}'
```

### 6) 紧急停止（!stop）

```powershell
Invoke-RestMethod `
  -Method Post `
  -Uri "http://localhost:8080/api/v1/agents/andy/actions/execute" `
  -ContentType "application/json" `
  -Body '{"command":"!stop","args":[]}'
```

---

## Python 示例（OpenClaw 调用层可直接复用）

```python
import requests

BASE = "http://localhost:8080"
AGENT = "andy"

def api_get(path: str):
    r = requests.get(BASE + path, timeout=30)
    r.raise_for_status()
    return r.json()

def api_post(path: str, payload: dict):
    r = requests.post(BASE + path, json=payload, timeout=120)
    r.raise_for_status()
    return r.json()

def run_action(command: str, args: list):
    return api_post(
        f"/api/v1/agents/{AGENT}/actions/execute",
        {"command": command, "args": args}
    )

def get_state():
    return api_get(f"/api/v1/agents/{AGENT}/state")

if __name__ == "__main__":
    print(api_get("/api/v1/agents"))
    print(api_get(f"/api/v1/agents/{AGENT}/actions/schema")["success"])
    print(run_action("!stats", []))
    print(get_state()["state"]["gameplay"]["position"])
```

---

## 任务编排示例（采集 4 个橡木原木）

1. `!collectBlocks("oak_log", 4)`
2. 轮询 `/state` 查看 `inventory.counts.oak_log`
3. `< 4` 则继续尝试
4. `>= 4` 即成功

建议在每轮执行前后调用 `!stats` 记录上下文，便于故障追踪。


path: reference.md
content: # OpenClaw 调用参考

## 1. 前置条件

- 启动命令：`node main.js`
- `settings.js` 推荐：
  - `external_controller_only: true`
  - `mindserver_port: 8080`
- Minecraft 世界可连通（本地 LAN 示例：`127.0.0.1:55916`）

## 2. 接口定义

### GET `/api/v1/agents`

用途：列出可控 bot 与连接状态。  
成功响应示例：

```json
{
  "success": true,
  "agents": [
    {
      "name": "andy",
      "in_game": true,
      "socket_connected": true,
      "viewer_port": 3000
    }
  ]
}
```

---

### GET `/api/v1/agents/:agentName/state`

用途：读取结构化状态（位置、血量、饥饿、背包、邻近实体等）。

响应结构核心字段（示例）：

```json
{
  "success": true,
  "state": {
    "name": "andy",
    "gameplay": {
      "position": { "x": 1.2, "y": 64, "z": -3.4 },
      "health": 20,
      "hunger": 20
    },
    "action": { "current": "Idle", "isIdle": true },
    "inventory": { "counts": { "oak_log": 4 } }
  }
}
```

---

### GET `/api/v1/agents/:agentName/actions/schema`

用途：查询全部命令及参数规格。建议调用方缓存。

响应示例：

```json
{
  "success": true,
  "commands": [
    {
      "name": "!goToCoordinates",
      "category": "action",
      "description": "Go to the given x, y, z location.",
      "blocked": false,
      "params": [
        { "name": "x", "type": "float", "domain": [-Infinity, Infinity] },
        { "name": "y", "type": "float", "domain": [-64, 320] },
        { "name": "z", "type": "float", "domain": [-Infinity, Infinity] },
        { "name": "closeness", "type": "float", "domain": [0, Infinity] }
      ]
    }
  ]
}
```

---

### POST `/api/v1/agents/:agentName/actions/execute`

用途：执行单个动作或查询命令。

请求体：

```json
{
  "command": "!stats",
  "args": []
}
```

成功响应：

```json
{
  "success": true,
  "command": "!stats",
  "args": [],
  "result": "..."
}
```

失败响应（示例）：

```json
{
  "success": false,
  "error": "Agent 'andy' is not connected in game."
}
```

## 3. 编排建议（OpenClaw）

- 先获取 `schema` 再执行，避免参数错误。
- 任何动作后都读取 `state` 校验结果。
- 若动作冲突或卡住：先执行 `!stop`，再恢复流程。
- 对采集/移动任务使用循环策略：
  - `execute` -> `state` -> 判断目标是否达成 -> 未达成则继续。

## 4. 安全与约束

- 外控模式默认无 LLM，但动作仍会与真实游戏世界交互。
- 建议在私有/本地世界验证自动化流程后再扩大范围。
- 若需要并发控制多个 bot，用 `/agents` 按 `name` 分开调度。


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)