Minecraft Bridge
Persistent local HTTP service that bridges OpenClaw to a live Minecraft Java Edition
bot session. Exposes a REST API on http://localhost:${MC_BRIDGE_PORT|3001} for live
state reads and in-game bot actions.
Boundary:
- - Use this skill for live bot control and live game-state reads
- Use
minecraft-wiki for knowledge questions - Use
minecraft-server-admin for RCON, server.properties, whitelist/ban/op, and generic server administration
Quick State Machine
CODEBLOCK0
Check current state with: GET http://localhost:3001/status
Setup (first time)
1. Environment variables
Set in
~/.openclaw/openclaw.json or export in shell:
CODEBLOCK1
2. Open Minecraft to LAN (singleplayer)
ESC → Open to LAN → Allow Cheats ON → Start LAN World
Note the port shown (e.g. 54321) — set
MC_PORT to that value.
3. Start the bridge
node ~/.openclaw/skills/minecraft-bridge/bridge-server.js
Wait for: INLINECODE7
4. Verify
curl http://localhost:3001/status
Runtime Operations
When user gives a live-game command:
- 1. Check bridge health —
GET /status; if unreachable → show setup instructions above - Execute action — call appropriate endpoint (see API Reference below)
- Report result — format response conversationally; include coordinates, item names, counts
- Persist context — write significant events to OpenClaw memory (coordinates found, items collected, goals achieved)
Interpreting /status response
{
"connected": true,
"username": "ClawBot",
"position": {"x": -142, "y": 64, "z": 88},
"health": 18.0,
"food": 14,
"gameTime": 6000,
"inventoryCount": 12,
"biome": "plains"
}
- -
gameTime 0–6000 = morning, 6000–12000 = day, 12000–18000 = dusk/night - INLINECODE10 max 20.0; below 6 = danger
- INLINECODE11 max 20; below 6 = can't sprint, below 1 = taking damage
API Overview
See references/api-spec.md for the full schema.
Core endpoints:
- -
GET /status — bridge + bot connection state - INLINECODE14 ,
GET /position, GET /nearby — live state reads - INLINECODE17 ,
POST /mine, POST /collect, POST /craft, POST /follow, POST /stop — live bot actions - INLINECODE23 — send in-game chat
- INLINECODE24 — send arbitrary slash commands; use with caution
Security note: /command forwards arbitrary slash commands. On servers where the bot has elevated permissions, this may include destructive or admin-level commands. Prefer minecraft-server-admin for server administration tasks.
Dependent Skills
Dependent skills should health-check the bridge before using it.
See references/dependency-guide.md for the canonical dependency-check pattern and degradation behavior.
Error Handling
| Error | Cause | Recovery |
|---|
| INLINECODE28 | Bridge not started | Run INLINECODE29 |
| INLINECODE30 |
Bridge up, bot offline | Open Minecraft, check MC_HOST/PORT |
|
{"error":"pathfinding failed"} | Path blocked | Try
/stop then retry with different coords |
|
{"error":"no crafting table"} | Craft without workbench | Move near crafting table first |
| Bot stuck looping | Pathfinding bug | POST /stop, then resume |
Auto-reconnect is built in — bridge retries every 5 s after disconnect.
Additional Resources
- -
references/api-spec.md — Full API schema with all request/response fields - INLINECODE35 — How other skills should declare bridge dependency
- INLINECODE36 — Detailed error diagnosis
- INLINECODE37 /
scripts/stop.sh — Convenience wrappers
Minecraft Bridge
持久的本地HTTP服务，将OpenClaw桥接到一个实时的Minecraft Java版机器人会话中。在http://localhost:${MCBRIDGEPORT|3001}上暴露REST API，用于实时状态读取和游戏内机器人操作。
边界：
- - 使用此技能进行实时机器人控制和实时游戏状态读取
- 使用minecraft-wiki处理知识性问题
- 使用minecraft-server-admin处理RCON、server.properties、白名单/封禁/OP以及通用服务器管理
快速状态机
UNSTARTED → 运行 bridge-server.js → STARTING → 机器人生成 → CONNECTED
CONNECTED → 游戏关闭或踢出 → DISCONNECTED → 自动重连 → CONNECTED
使用以下命令检查当前状态：GET http://localhost:3001/status
设置（首次使用）
1. 环境变量
在~/.openclaw/openclaw.json中设置或在shell中导出：
MC_HOST=localhost # 服务器IP（单人游戏局域网为localhost）
MC_PORT=25565 # 游戏端口
MCBOTUSERNAME=ClawBot # 机器人的游戏内名称（离线模式服务器）
MCBRIDGEPORT=3001 # 桥接HTTP端口（默认3001）
MC_VERSION=1.21.1 # Minecraft版本字符串
2. 将Minecraft开放至局域网（单人游戏）
ESC → 对局域网开放 → 允许作弊：开 → 开始局域网世界
记下显示的端口（例如54321）——将MC_PORT设置为该值。
3. 启动桥接服务
bash
node ~/.openclaw/skills/minecraft-bridge/bridge-server.js
等待显示：🎮 Bridge ready at http://localhost:3001
4. 验证
bash
curl http://localhost:3001/status
运行时操作
当用户发出实时游戏命令时：
- 1. 检查桥接健康状态 — GET /status；如果无法访问 → 显示上述设置说明
- 执行操作 — 调用相应的端点（参见下面的API参考）
- 报告结果 — 以对话方式格式化响应；包含坐标、物品名称、数量
- 持久化上下文 — 将重要事件写入OpenClaw记忆（找到的坐标、收集的物品、达成的目标）
解读/status响应
json
{
connected: true,
username: ClawBot,
position: {x: -142, y: 64, z: 88},
health: 18.0,
food: 14,
gameTime: 6000,
inventoryCount: 12,
biome: plains
}
- - gameTime 0–6000 = 早晨，6000–12000 = 白天，12000–18000 = 黄昏/夜晚
- health 最大20.0；低于6 = 危险
- food 最大20；低于6 = 无法冲刺，低于1 = 持续掉血
API概览
完整模式参见references/api-spec.md。
核心端点：
- - GET /status — 桥接+机器人连接状态
- GET /inventory、GET /position、GET /nearby — 实时状态读取
- POST /move、POST /mine、POST /collect、POST /craft、POST /follow、POST /stop — 实时机器人操作
- POST /chat — 发送游戏内聊天
- POST /command — 发送任意斜杠命令；请谨慎使用
安全提示：/command会转发任意斜杠命令。在机器人拥有较高权限的服务器上，这可能包含破坏性或管理员级别的命令。服务器管理任务请优先使用minecraft-server-admin。
依赖技能
依赖技能在使用桥接服务前应进行健康检查。
参见references/dependency-guide.md获取规范的依赖检查模式和降级行为。
错误处理
| 错误 | 原因 | 恢复方法 |
|---|
| ECONNREFUSED | 桥接服务未启动 | 运行node bridge-server.js |
| {connected:false} |
桥接已启动，机器人离线 | 打开Minecraft，检查MC_HOST/PORT |
| {error:pathfinding failed} | 路径被阻挡 | 尝试/stop，然后用不同坐标重试 |
| {error:no crafting table} | 没有工作台进行合成 | 先移动到工作台附近 |
| 机器人卡住循环 | 寻路bug | POST /stop，然后继续 |
内置自动重连——桥接服务在断开连接后每5秒重试一次。
附加资源
- - references/api-spec.md — 包含所有请求/响应字段的完整API模式
- references/dependency-guide.md — 其他技能如何声明桥接依赖
- references/troubleshooting.md — 详细的错误诊断
- scripts/start.sh / scripts/stop.sh — 便捷包装脚本
