⛏️ Mineclaw

Give your Minecraft server an agent—not just a chatbot.
给 Minecraft 服务器一个真正会理解、会查找、会规划、会行动的 Agent。

Workspace-driven AI agents for Paper and Folia servers.
面向 Paper 与 Folia 服务器、由工作区驱动的 AI Agent 体验。

Download · Source

---

✨ Why Mineclaw

为什么是 Mineclaw

Mineclaw brings an agent-native experience into Minecraft. The model can combine operator-authored knowledge with live game state, plan multi-step work, discover Skills, compose tools, and request real server actions—all from public chat.
Mineclaw 把 Agent 级体验带进 Minecraft：模型能把服主编写的知识与实时游戏状态结合起来，规划多步任务，自主发现 Skill、组合 Tool，并从公共聊天中请求真实的服务器操作。

• A workspace that shapes the agent. AGENTS.md, tools.yml, and skills/*.md define its identity, knowledge, procedures, and available capabilities.
  用工作区塑造 Agent。 AGENTS.md、tools.yml 与 skills/*.md 共同定义身份、知识、操作规程和可用能力。
• Live state becomes planning input. Read-only tools expose nearby blocks, position, inventory item types and counts, and online account names, so the agent can reason about materials, location, and participants instead of answering generic questions.
  把实时状态变成规划依据。 只读 Tool 可以观察附近方块、位置、背包物品类型与数量以及在线玩家账号名，让 Agent 围绕材料、地点和参与者推理，而不是只回答泛泛的问题。
• Skills that turn server knowledge into play. Rules, events, custom plugin commands, and multi-step procedures become documents the model can discover and follow.
  让服务器知识变成可玩的 Skill。 服规、活动、第三方插件命令和多步流程都能写成模型可发现、可遵循的文档。
• Visible, native interaction. Streaming output appears in the Action Bar; the completed answer is broadcast once in public chat.
  自然、可见的服内交互。 流式生成显示在 Action Bar，完整答案只在公屏广播一次。
• Built for Paper and Folia. Entity, region, global, HTTP, and file work stay on their appropriate scheduling boundaries.
  面向 Paper 与 Folia 构建。 实体、区域、全局、HTTP 和文件任务各自在正确的调度边界运行。

🎮 Four jobs worth giving an agent

四个值得交给 Agent 的任务

1. Optimize a crafting plan from the real inventory

根据真实背包做合成优化

A player asks: @ai With what I have now, how should I split my oak to craft the most fences while keeping 16 logs untouched? The agent inspects the actual inventory, totals logs, planks, and sticks, applies the recipe ratios and reserve constraint, then returns exact crafting steps and expected leftovers.
玩家问：@ai 按我现在的背包，橡木怎么配比才能合成最多的栅栏，同时保留 16 根原木？ Agent 会读取真实背包，汇总原木、木板与木棍，结合配方比例和保留约束，给出精确的合成步骤与预计余料。

This is more than finding an item in a slot: live game state becomes a constrained resource-allocation problem the agent solves for this player, right now.
这不只是“背包里有没有某件物品”，而是把实时游戏状态转化成约束明确的资源规划问题，并针对当前玩家即时求解。

2. Build a route from server-specific rules and live state

结合本服规则与现场状态规划路线

An operator documents an event's checkpoints, prerequisites, time windows, forbidden shortcuts, and rewards in the workspace. A player can ask: @ai I have iron gear and 25 minutes. Starting from here and without teleporting, which treasure-hunt route can I finish, and what am I missing?
服主把活动检查点、前置条件、开放时段、禁止的捷径与奖励写进工作区。玩家可以问：@ai 我穿铁装，只有 25 分钟。从这里出发且不用传送，寻宝活动走哪条路线能完成？还缺什么？

The agent combines the player's inventory, current world and position with the event Skill and server documents, rejects routes that violate the constraints, and produces an ordered plan grounded in facts no general-purpose model could know. Documents and Skills are read hot, so tonight's route can change without restarting the server.
Agent 会把玩家背包、当前世界与位置，同活动 Skill 和服务器文档结合起来，排除不满足约束的路线，形成一份有顺序的行动计划。这些本服事实不是通用模型能够预知的；文档与 Skill 支持热读取，今晚的路线改动无需重启服务器即可生效。

3. Decide whether to act, then take the next step

先判断是否该行动，再推进下一步

After command dispatch is enabled, a player asks: @ai Am I ready to hunt an End City? If I am, locate the nearest one; otherwise give me the smallest useful prep list. The agent checks inventory and equipment, verifies the current dimension, reads the bundled locate-structure Skill, and branches on what it finds.
启用命令分发后，玩家问：@ai 我现在适合去找末地城吗？准备够了就帮我定位最近的；不够就给我一份最精简的补给清单。 Agent 会检查背包与装备、确认当前维度、读取内置 locate-structure Skill，再根据观察结果决定下一步。

If the conditions are met, it dispatches locate structure end_city as that player; otherwise it stops at a concrete preparation plan. Minecraft displays the coordinates, while Mineclaw reports only that the command was dispatched—not a success it cannot prove.
条件满足时，它会以当前玩家身份分发 locate structure end_city；否则停在具体的准备方案。坐标由 Minecraft 显示，Mineclaw 只报告命令已分发，不冒充自己无法证明的执行成功。

4. Turn a custom plugin into a multiplayer coordinator

把第三方插件变成多人协作 Agent

Suppose a server already uses KitesPlaces. After reviewing the repository's kp-warps.md example and adding narrow command rules, a player can ask: @ai Find the exact farm warp and send Alice and Bob there if they are online.
假设服务器已经安装 KitesPlaces。服主审核仓库中的 kp-warps.md 示例并添加最小范围的命令规则后，玩家可以说：@ai 找到农场对应的准确传送点；Alice 和 Bob 在线的话，请他们过去。

The agent checks the online roster, obtains the real warp list through synchronous console feedback, resolves the exact name instead of guessing, and sends a separate approval request to each target player before dispatch. It is coordinating people, live server state, a third-party command language, and consent—not merely expanding a slash-command alias.
Agent 会核对在线名单，通过控制台同步反馈取得真实传送点列表，解析准确名称而不是猜测，并在分发前分别向每位目标玩家发出审批请求。它协调的是玩家、实时服务器状态、第三方命令语义与本人授权，而不只是给斜杠命令套一层别名。

Mineclaw does not bundle KitesPlaces or gain new Java handlers from Markdown. The point is the reusable agent loop: observe → retrieve server knowledge → plan → act through policy → report only what was proven. Each server can reshape that loop with its own Skills, tools, and procedures.
Mineclaw 不会捆绑 KitesPlaces，Markdown 也不能凭空生成新的 Java handler。案例真正展示的是可复用的 Agent 闭环：观察 → 检索本服知识 → 规划 → 按策略行动 → 只报告已证实结果。每个服务器都能用自己的 Skill、Tool 与规程重新塑造这条链路。

🧩 Compatibility

兼容性

• Server: Paper 26.2 or Folia 26.2; the descriptor declares folia-supported: true.
  服务端： Paper 26.2 或 Folia 26.2；插件描述声明 folia-supported: true。
• Runtime: Java 25.
  运行时： Java 25。
• Model API: a complete OpenAI-compatible Chat Completions endpoint. Tool use requires streaming and tool-call support from the provider.
  模型接口： 完整的 OpenAI-compatible Chat Completions 端点；Tool 模式要求上游支持流式输出与 tool calls。
• Other platforms: standalone Spigot/Bukkit and other Paper or Minecraft versions are not compatibility promises.
  其他平台： 不承诺兼容独立 Spigot/Bukkit 或其他 Paper、Minecraft 版本。

Treat 26.2 + Java 25 as the current target, not a minimum-version declaration.
请把 26.2 + Java 25 视为当前适配目标，而不是最低版本。

📦 Installation

安装

1. Prepare a Paper/Folia 26.2 server running Java 25.
   准备运行 Java 25 的 Paper/Folia 26.2 服务端。
2. Download Mineclaw-0.1.2.jar from GitHub Releases, or build it from source.
   从 GitHub Releases 下载 Mineclaw-0.1.2.jar，或从源码构建。
3. Stop the server and place the JAR in plugins/.
   停止服务端，把 JAR 放入 plugins/。
4. Start once so Mineclaw can create its default workspace.
   启动一次，让 Mineclaw 创建默认工作区。
5. Put the API key in plugins/Mineclaw/.env, then adjust config.yml as needed.
   把 API 密钥写入 plugins/Mineclaw/.env，再按需调整 config.yml。
6. Restart, or run /mineclaw reload as an administrator.
   重启服务端，或由管理员执行 /mineclaw reload。

Build from source:
从源码构建：

git clone https://github.com/kites262/mineclaw.git
cd mineclaw
git checkout 0.1.2
./gradlew --no-daemon clean test assemblePlugin

Deployable artifact:
可部署产物：

build/plugins/Mineclaw-0.1.2.jar

First-start data directory:
首次启动生成目录：

plugins/Mineclaw/
├── config.yml
├── .env
├── message.yml
├── AGENTS.md
├── tools.yml
└── skills/
    ├── guide.md
    ├── command-safety.md
    └── locate-structure.md

🔐 API configuration and .env

API 配置与 .env

api.base_url, api.model, and api.api_key may each contain a literal value or the name of an environment variable. Mineclaw resolves each field in this order:
api.base_url、api.model 与 api.api_key 均可填写字面量或环境变量名。Mineclaw 对每个字段按以下顺序解析：

Process environment → sibling .env → literal text in config.yml
系统环境变量 → 同目录 .env → config.yml 中的字面量

Once a higher-priority layer defines a variable—even as an empty value—fallback stops. Only a missing variable name causes the configuration text itself to be used literally.
只要更高优先级定义了该变量，即使值为空，也会终止回退；只有变量名不存在时，配置文本本身才作为字面量使用。

Recommended references:
推荐写法：

api:
  base_url: 'MINECLAW_API_BASE_URL'
  model: 'MINECLAW_API_MODEL'
  api_key: 'MINECLAW_API_KEY'

MINECLAW_API_BASE_URL=https://api.example.com/v1/chat/completions
MINECLAW_API_MODEL=your-model-id
MINECLAW_API_KEY=replace-with-your-secret

• The shipped configuration keeps the default URL and model as literals and points only the key at MINECLAW_API_KEY.
  发行配置保留 URL 与模型字面量，只让密钥引用 MINECLAW_API_KEY。
• First start creates only an empty MINECLAW_API_KEY= placeholder and best-effort applies mode 0600 on POSIX filesystems.
  首次启动只创建空的 MINECLAW_API_KEY= 占位符，并在 POSIX 文件系统上尽力设置为 0600。
• .env supports comments, export, single quotes, and double quotes, but performs no variable interpolation.
  .env 支持注释、export、单双引号，但不执行变量插值。
• .env must be a regular, non-symlink UTF-8 file no larger than 64 KiB.
  .env 必须是非符号链接的普通 UTF-8 文件，最大 64 KiB。
• The URL must be an absolute HTTP(S) URI; the model cannot be blank or contain whitespace/control characters. An empty key is rejected before any request.
  URL 必须是绝对 HTTP(S) 地址；模型不能为空，也不能含空白或控制字符。空密钥会在请求发出前被本地拒绝。
• Retryable API failures are retried up to five times by default after the initial request, with exponential backoff starting at 500 ms. Set api.max_retries to override this.
  可重试的 API 故障默认会在首次请求后最多重试五次，指数退避从 500 毫秒开始；可通过 api.max_retries 覆盖。 config.yml and .env are published as one immutable snapshot at startup or reload. A turn already in progress keeps its original snapshot.
  config.yml 与 .env 会在启动或重载时组成同一个不可变快照；已经开始的 turn 继续使用原快照。

See the complete default configuration.
查看完整默认配置。

🗂️ Workspace and extension model

工作区与扩展方式

• AGENTS.md defines the agent's identity, voice, priorities, operating procedure, and behavioral boundaries.
  AGENTS.md 定义 Agent 的身份、语气、优先级、操作流程与行为边界。
• tools.yml enables, disables, and describes handlers implemented by the current Mineclaw build.
  tools.yml 启用、停用并描述当前 Mineclaw 版本已经实现的 handler。
• skills/*.md documents server knowledge and teaches the model how to compose existing tools and commands.
  skills/*.md 保存服务器知识，并教模型如何组合现有 Tool 与命令。
• message.yml controls player-facing messages, approval cards, and interaction hints.
  message.yml 控制玩家可见文案、审批卡和交互提示。

AGENTS.md, tools.yml, message.yml, and skills are read hot when used. Editing them usually requires no restart. config.yml and .env take effect only at startup or after /mineclaw reload.
AGENTS.md、tools.yml、message.yml 与 Skill 会在使用时热读取，修改后通常无需重启；config.yml 与 .env 只在启动或 /mineclaw reload 后生效。

Default seeding fills in missing files and never overwrites an existing agent, tool catalog, or skill. Markdown can teach the agent new procedures, but it cannot create a Java handler that Mineclaw does not implement or install a plugin absent from the server.
默认播种只补齐缺失文件，不覆盖已有的 Agent、Tool 目录或 Skill。Markdown 可以教 Agent 新流程，但不能凭空创造 Mineclaw 尚未实现的 Java handler，也不能安装服务器上不存在的插件。

Bundled workspace resources:
内置工作区资源：

• AGENTS.md
• tools.yml
• message.yml
• skills/

🧰 Built-in tools

内置 Tool

• look_block — reads the block the current player is looking at.
  读取当前玩家准星指向的方块。
• feet_block — reads the block under the current player.
  读取当前玩家脚下的方块。
• inventory — returns slot-level item types and counts, without item metadata.
  返回各槽位的物品类型与数量，不暴露物品元数据。
• online_players — returns the current caller and online account names only.
  只返回当前调用者与在线玩家账号名。
• list, read, grep — discover and read the Mineclaw workspace.
  发现、搜索并读取 Mineclaw 工作区。
• run_command — requests a policy-checked command dispatch.
  请求一次经过策略校验的命令分发。

online_players does not expose UUIDs, locations, worlds, permissions, or display names.
online_players 不暴露 UUID、位置、世界、权限或展示名。

🛡️ Command policy and player approval

命令策略与玩家审批

Command execution is not the main source of Mineclaw's intelligence; it is an optional bridge from an agent decision to a server action. It starts disabled with commands.run_enabled: false.
命令执行不是 Mineclaw 智能体验的主体，而是把 Agent 决策连接到服务器操作的可选桥梁；它默认通过 commands.run_enabled: false 关闭。

• Console commands must fully match console_whitelist.
  控制台命令必须完整匹配 console_whitelist。
• A same-player command may dispatch directly only when the player is online and the normalized command fully matches player_whitelist.
  当前玩家在线且规范化命令完整匹配 player_whitelist 时，才可能直接分发。
• Cross-player commands always require the actual target player's approval. Same-player commands outside the allowlist also enter approval.
  跨玩家命令始终需要实际目标玩家确认；当前玩家未命中白名单的命令也会进入确认流程。
• Bukkit/Paper permissions still apply after Mineclaw policy accepts a request.
  即使 Mineclaw 策略允许请求，Bukkit/Paper 权限仍然生效。

The approval card shows the requester, operation, command, execution identity, and expiry. Its final line contains clickable Accept and Reject buttons backed by one-time UUID tokens. Players never need to type an approve command.
审批卡会展示请求者、操作内容、命令、执行身份与有效期，最后一行提供可点击的接受与拒绝按钮，并绑定一次性 UUID 令牌。玩家无需手输 approve 命令。

An optional gesture can accept a pending request: sneak, look straight up, and right-click air with a non-empty main-hand item that has no use effect in air. Empty-hand clicks and interactions that already do something—placing, throwing, eating, charging, blocking, tool use, or unknown custom behavior—are excluded.
待确认时也可使用快捷手势：按住 Shift、视角朝正上方，并用主手中“对空气使用不会产生效果”的非空物品右键空气。空手以及放置、投掷、进食、蓄力、格挡、工具使用或未知自定义行为都不会触发。

Dispatched does not mean succeeded. Player dispatch confirms only that Bukkit accepted the command for dispatch; it cannot capture all player-facing feedback or prove side effects. Console dispatch may capture synchronous feedback, but that still does not prove every downstream effect completed.
分发成功不等于实际执行成功。 玩家命令只能确认 Bukkit 接受了分发，无法捕获全部玩家反馈，也不能证明副作用完成；控制台命令可能捕获同步反馈，但仍不能证明所有后续效果已经完成。

Mineclaw distinguishes player offline, command not found, dispatch rejected, execution exception, and unknown outcome instead of collapsing them into success.
Mineclaw 会区分玩家离线、命令未找到、分发被拒绝、执行异常与结果未知，不会把它们统一包装成成功。

🔒 Protected files and workspace boundary

敏感文件与工作区边界

• config.yml and .env may appear in listings, but expose only path, type, and protected: true—never size or contents.
  config.yml 与 .env 可以出现在文件列表，但只暴露路径、类型和 protected: true，不返回大小或内容。
• read returns a fixed protected response; grep skips both files.
  read 只返回固定保护提示，grep 会跳过这两个文件。
• Direct paths, normalized aliases, symlink aliases, and hard-link aliases receive the same protection.
  直接路径、规范化别名、符号链接别名和硬链接别名都受同一保护。
• Absolute paths, .. traversal, and symlink escape are rejected.
  绝对路径、.. 穿越和符号链接逃逸都会被拒绝。
• Current file tools are read-only: list, read, and grep. No edit, overwrite, move, or delete handler is exposed.
  当前文件 Tool 只有只读的 list、read 与 grep，不提供编辑、覆盖、移动或删除 handler。

The model cannot elevate itself, edit protected configuration, read secrets, or bypass server permissions. AI is not OP; server policy remains authoritative.
模型不能自行提权、编辑受保护配置、读取密钥或绕过服务器权限。AI 不是 OP，服务器策略始终拥有最终裁决权。

💬 Usage and permissions

使用方式与权限

• @ai <question> — starts a public AI turn. Permission: mineclaw.command.chat (default true).
  发起一次公共 AI 对话。权限：mineclaw.command.chat（默认 true）。
• /mineclaw clear — clears the server-wide public session. Permission: mineclaw.command.clear (OP).
  清空全服公共 Session。权限：mineclaw.command.clear（OP）。
• /mineclaw reload — atomically reloads config.yml and .env. Permission: mineclaw.command.reload (OP).
  原子重载 config.yml 与 .env。权限：mineclaw.command.reload（OP）。
• /mineclaw tools — shows the current tool catalog status. Permission: mineclaw.command.tools (OP).
  查看当前 Tool 目录状态。权限：mineclaw.command.tools（OP）。
• mineclaw.command.approve (default true) — receive and act on approvals addressed to the player.
  接收并处理发给自己的审批。
• mineclaw.bypass.ratelimit (default false) — bypass the per-player rate limit.
  绕过玩家级速率限制。

The public chat prefix defaults to @ai and can be changed with chat.public_prefix.
公共聊天前缀默认为 @ai，可通过 chat.public_prefix 修改。

🖥️ Runtime behavior

运行时行为

• Only one AI turn runs server-wide at a time. Requests received while busy are rejected and never enter the session.
  全服同一时间只运行一个 AI turn；忙碌时收到的请求会被拒绝，也不会进入 Session。
• The public session is server-wide and in-memory. It stores only completed user/assistant turns, not internal tool messages.
  公共 Session 是全服共享的内存状态，只保存已完成的 user/assistant 轮次，不保存内部 Tool 消息。
• Restarting, disabling the plugin, or running clear removes the session.
  重启、停用插件或执行 clear 会清空 Session。
• context.max_messages retains recent complete turns; reaching context.max_tokens clears the server session.
  context.max_messages 保留最近的完整轮次；达到 context.max_tokens 时清空服务器 Session。
• The Action Bar starts with the configurable actionbar_thinking message (Thinking... by default). Between tool rounds, retries, and paragraphs, the current frame remains visible until the next renderable character atomically replaces it; low-frequency refreshes prevent it from fading during a long wait.
  Action Bar 会先显示可配置的 actionbar_thinking 文案（默认 Thinking...）。在 Tool 轮次、重试与段落之间，当前画面会保留到下一个可显示字符原位替换，并通过低频刷新避免长时间等待时提前淡出。
• One newline becomes a space or soft break. A blank line—two or more consecutive newlines—starts a fresh internal paragraph without first sending an empty frame. CRLF and stream-chunk boundaries are normalized.
  单个换行作为空格或软换行；空行（两个及以上连续换行）会开始新的内部段落，但不会预先发送空帧，同时正确处理 CRLF 与跨流式分片边界。
• Safe Markdown rendering currently focuses on real **bold** formatting.
  当前安全 Markdown 渲染重点支持真正的 **粗体**。

🔧 Configuration map

配置速览

• api — endpoint, key, model, timeout, and retries.
  端点、密钥、模型、超时与重试。
• context — session message and token limits.
  Session 消息与 token 上限。
• chat — public prefix, wake pattern, reply length, and Action Bar length.
  公共前缀、唤醒规则、回复长度与 Action Bar 长度。
• tools, commands — tool switches, command dispatch, and allowlists.
  Tool 开关、命令分发与白名单。
• rate_limit — per-player and global cooldowns.
  玩家级与全局冷却。
• workspace, file_tools — default seeding and read-only file limits.
  默认资源播种与只读文件限制。
• turn — maximum tool rounds and calls per turn.
  每个 turn 的最大 Tool 轮次与调用数。
• identity, environment — fallback name, observation distance, inventory summary, and tool cooldown.
  回退名称、观察距离、背包摘要与 Tool 冷却。
• logging — plugin log level.
  插件日志级别。

Command regexes use full-match semantics. Scope every pattern deliberately: a broad expression grants broad dispatch authority.
命令正则采用完整匹配语义。请有意识地限定每条表达式；过宽的规则等同于授予过宽的分发能力。

🧪 Build and verification

构建与验证

The project uses Gradle Wrapper 9.5.0, Java toolchain 25, and Paper API 26.2.build.87-stable. assemblePlugin produces a deployable JAR containing runtime dependencies.
项目使用 Gradle Wrapper 9.5.0、Java toolchain 25 与 Paper API 26.2.build.87-stable；assemblePlugin 会生成包含运行时依赖的可部署 JAR。

./gradlew --no-daemon clean test assemblePlugin

JVM tests cover parsing, policy, rendering, protected files, and dispatch semantics. They cannot prove real Folia scheduler behavior or compatibility with every external plugin; verify high-risk changes on an actual 26.2 server.
JVM 测试覆盖解析、策略、渲染、敏感文件保护与分发语义，但无法证明真实 Folia 调度行为或所有外部插件兼容性；高风险改动仍应在实际 26.2 服务端验证。

⚠️ Deliberate boundaries

有意保留的边界

• Mineclaw does not grant the model OP or replace Bukkit/Paper permission checks.
  Mineclaw 不授予模型 OP，也不代替 Bukkit/Paper 权限检查。
• Enabling tools does not implicitly enable command dispatch.
  启用 Tool 不会隐式开启命令分发。
• Approval authorizes one dispatch attempt, not proof of its outcome.
  接受审批只授权一次分发尝试，不代表操作已经完成。
• Player-facing command feedback is not automatically returned to the model.
  玩家屏幕上的命令反馈不会自动回传给模型。
• The gesture shortcut does not support an empty hand; clickable buttons remain the primary path.
  快捷审批不支持空手；可点击按钮仍是主要交互。
• A Markdown skill cannot create a missing tool handler or install an absent server plugin.
  Markdown Skill 不能创造不存在的 Tool handler，也不能安装服务器上没有的插件。
• The current conversation is public, server-wide, in-memory, and single-turn-at-a-time—not a private agent or persistent memory.
  当前对话是全服公共、内存态、单并发，不是私聊 Agent 或持久记忆。

---

Build the agent your server deserves.
为你的 Minecraft 服务器，塑造一个真正属于它的 Agent。