This is a submission for the OpenClaw Challenge.

What I Built

I built ClawCraft-bot — a bridge application that gives OpenClaw an avatar inside a Minecraft world.

Instead of just chatting or processing text, OpenClaw can now perceive a three-dimensional environment, gather resources, craft tools, navigate complex terrain, and even defend players against hostile mobs in real time. The bot acts as an independent agent running through a local HTTP API, translating OpenClaw's high-level reasoning into precise in-game actions.

How I Used OpenClaw

OpenClaw serves as the "brain" of the entire operation, making strategic decisions, while ClawCraft-bot acts as the "nervous system."

The Tech Stack & Environment

• Launcher: SKLauncher 3.2.18 (Offline mode)
• Minecraft Version: Java Edition 1.21.11
• Bridge API: Node.js + Express.js
• Bot Engine: Mineflayer + pathfinder, pvp, collectblock

The system runs on a local Minecraft world. One important detail: after launching the game, you need to open the world to the network (Open to LAN) on port 25565 (default) so the Bridge API can connect the bot to your game session.

Architecture

The system is built around a simple principle: the LLM is the brain, the bot is the body. OpenClaw reasons and decides; ClawCraft-bot perceives and acts. They communicate through a thin HTTP layer, which means the agent never touches Mineflayer directly — and Mineflayer never needs to know anything about LLMs.

Five layers, one direction

The codebase is organized into five layers, each knowing only about the one below it:

SKILL.md          ← Layer 5: instructions OpenClaw reads to understand the API
bridge-api.js     ← Layer 4: Express HTTP server, the contract between LLM and bot
actions/          ← Layer 3: six modules split by responsibility
plugins.js        ← Layer 2: pathfinder, pvp, collectblock, tool
bot-core.js       ← Layer 1: Mineflayer lifecycle and auto-reconnect

This separation means you can swap out the LLM integration entirely — replace OpenClaw with any HTTP client — without touching a single line of game logic. Conversely, upgrading the Mineflayer version or adding a new plugin stays contained in Layers 1–2.

Layer 3 (actions/) is where most of the domain logic lives, split into focused modules: info for reading game state, navigation for movement, chat for communication, world for block interaction, combat for fighting and protection, and items for inventory and crafting. An index.js registry routes incoming API calls to the right module.

The bridge API

The HTTP API listens on 127.0.0.1:3001 — localhost only, by design. This isn't an oversight; it's a deliberate security boundary. An LLM that can issue /actions/attack or /actions/collect shouldn't be exposed to the network.

The API is split into two kinds of endpoints:

• Read endpoints (GET): /status, /inventory, /nearby, /scan-blocks, /findblock — these return immediately and can be called at any time. OpenClaw uses them to build a picture of the world before deciding what to do next.
• Action endpoints (POST): /actions/goto, /actions/collect, /actions/craft, etc. — these start a job and return a jobId immediately, without waiting for the action to complete.

Why a job queue?

This is the most important architectural decision in the project, and it's worth explaining explicitly.

Minecraft actions are not instantaneous. Navigating to a location takes several seconds. Mining a stack of wood takes longer. If a POST request blocked until the action finished, the LLM would be left hanging — and more importantly, a second command arriving mid-navigation would conflict with the first, causing pathfinder to fight itself.

The solution is a serial job queue: every action is enqueued and executed one at a time. A POST to /actions/collect returns immediately:

{ "jobId": "a3f9...", "status": "pending" }

OpenClaw then polls /jobs/a3f9... until the status becomes done or failed. While waiting, it's free to call read endpoints — checking health, scanning for threats, updating its world model. The queue prevents conflicts without requiring locks or complex concurrency primitives.

[

The diagram above shows the full request lifecycle: OpenClaw reads world state, decides on an action, posts it to the bridge, receives a jobId, and polls for completion while the bot executes in-game.

What SKILL.md does

The final layer is SKILL.md — a plain text file that serves as the API contract for the LLM. It describes every endpoint, its parameters, and the expected response shape. It also encodes behavioral rules that can't be enforced in code: things like "always put away your tool before eating" or "check /status before starting a long task."

Setup

1. Launch Minecraft

1. Use SKLauncher (or any other launcher) to start Minecraft Java Edition 1.21.11.
2. Load a world and select "Open to LAN" on port 25565.

2. Install ClawCraft-bot

git clone https://github.com/premananda108/ClawCraft-bot.git
cd ClawCraft-bot
npm install
# Edit .env if needed (specify the port from MC)
npm start

3. Configure OpenClaw

1. Install OpenClaw by following its official documentation.
2. Create a new Skill in OpenClaw. As the skill instructions, simply provide your agent with the contents of the SKILL.md file from this repository. It contains all the necessary behavior rules and API descriptions for the AI.

Intelligence & LLM Efficiency

One of the key features of the project is the use of a detailed SKILL.md file. This allowed me to:

• Lower model requirements: Thanks to clear instructions and API descriptions in the SKILL file, the bot can be controlled even by inexpensive or local LLMs.
• Optimize costs: Minecraft involves a very high number of "check-act" cycles. Using local models (via Ollama or similar tools) lets you run the bot for hours without burning through expensive API tokens.

Demo

# 1. Installation
npm install

# 2. Setup (copy and edit)
cp .env.example .env
# Edit .env: MC_HOST, MC_PORT, MC_USERNAME

# 3. Run
npm start

What I Learned

Building a bridge between an LLM and a real-time game engine turned out to be full of hidden pitfalls:

• Visualization traps: I originally planned to use prismarine-viewer to stream a video feed. However, it turned out to work incorrectly with Minecraft Java 1.21.11. In the end, I decided to drop visualization from the final build in favor of control stability.
• LLMs need strict feedback loops: Initially, the AI would try to eat food while holding a pickaxe. I had to explicitly write into SKILL.md that a tool must be put away before eating. Designing an API for AI is a balancing act between flexibility and hard rules.
• Lifecycle chaos: Minecraft bots sometimes die. I learned that handling automatic respawns requires strict event decoupling — otherwise the system starts injecting multiple pathfinding plugins into the same bot instance, leading to massive memory leaks.

ClawCon Michigan

Unfortunately, I wasn't able to attend ClawCon Michigan this time around, but it's wonderful to see the OpenClaw community growing and building incredible things!