Aicraft 为你的 Paper 服务器添加了私人的 AI 聊天功能——支持游戏内和浏览器端。你可以与 Ollama、Unsloth、vLLM 或任何兼容 OpenAI 的 API 进行对话。聊天记录按玩家保存,并提供 Web UI 用于查看历史记录及绑定你的 Minecraft 账号。
v1.1.0 新增了 Web UI、SQLite/Postgres 聊天记录、每位玩家的独立聊天 ID、账号绑定功能,以及与 LuckPerms 兼容的每日聊天次数限制。
Requirements
- Paper 1.21 或更高版本,包括 26.x(不支持 Spigot)
- Java 21 用于 Paper 1.21.x 服务器,Java 25 用于 Paper 26.x 服务器
- 一个 OpenAI 兼容 的聊天 API —— 本地部署或云端均可
- 可选: 开放端口 8765(或你选择的端口),以便从主机外部访问 Web UI
兼容:
localhost 上的 Ollama
- Unsloth / vLLM / LM Studio 及其他
/v1/chat/completions 端点
- OpenAI、Groq、OpenRouter 等
Installation
- 从此页面的 Versions 选项卡下载最新的 Aicraft
.jar 文件。
- 将其放入服务器的
plugins/ 文件夹中。
- 启动或重启服务器。
- 首次运行时,Aicraft 会创建以下文件:
plugins/Aicraft/config.yml — AI 端点设置
plugins/Aicraft/web.yml — Web UI、数据库和速率限制
plugins/Aicraft/aicraft.db — SQLite 数据库(自动创建)
- 在玩家使用插件之前编辑
config.yml(参见下方的 Configuration)。
- 修改配置后重启服务器(最安全的方式)。重新加载可能不会重启 Web 服务器或数据库。
AI configuration (`config.yml`)
endpoint: "http://localhost:11434/v1/chat/completions"
api-key: "ollama"
model: "llama3.2"
system-prompt: "You are a helpful assistant inside a Minecraft server. Keep replies concise and game-friendly."
timeout-seconds: 120
max-history-messages: 20
| Option |
Description |
endpoint |
聊天完成 API 的完整 URL(/v1/chat/completions) |
api-key |
作为 Authorization: Bearer … 发送的 API 密钥。如果你的服务器忽略身份验证,可使用任意占位符(例如 ollama) |
model |
你的提供商期望使用的模型名称 |
system-prompt |
追加到每个新聊天之前的系统提示语 |
timeout-seconds |
AI 请求的 HTTP 超时时间(秒) |
max-history-messages |
保留在 AI 上下文窗口中的最大用户 + 助手消息数量 |
Ollama (local, recommended)
在与 Minecraft 同一台机器上:
ollama pull llama3.2
ollama serve
endpoint: "http://localhost:11434/v1/chat/completions"
api-key: "ollama"
model: "llama3.2"
如果 Ollama 运行在其他主机上,请将 localhost 替换为该机器的 IP 地址或主机名。
OpenAI (cloud)
endpoint: "https://api.openai.com/v1/chat/completions"
api-key: "sk-your-key-here"
model: "gpt-4o-mini"
Other local providers
将 endpoint 指向你的堆栈暴露的任何 /v1/chat/completions URL。支持 localhost 和私有 LAN 地址。
Web & database configuration (`web.yml`)
enabled: true
port: 8765
bind-address: "0.0.0.0"
database:
type: sqlite
sqlite-file: "aicraft.db"
postgres:
host: "localhost"
port: 5432
database: "aicraft"
username: "aicraft"
password: ""
rate-limits:
default-chats-per-day: 50
linking:
link-code-expiry-minutes: 2
web-session-days: 30
| Option |
Description |
enabled |
开启或关闭 Web UI |
port / bind-address |
Web 服务器监听的地址(0.0.0.0 = 所有接口) |
database.type |
sqlite(默认)或 postgres |
database.sqlite-file |
plugins/Aicraft/ 内的 SQLite 文件 — 自动创建 |
database.postgres.* |
Postgres 连接设置(数据库必须预先存在) |
rate-limits.default-chats-per-day |
当没有权限覆盖时,每位玩家每 24 小时的最大新聊天次数 |
linking.link-code-expiry-minutes |
/ailink 代码的有效时长(分钟) |
linking.web-session-days |
已绑定的 Web 会话持续时长(天) |
Database notes:
- SQLite 无需设置 —
.db 文件和表会在首次启动时自动创建。
- 迁移会自动运行;你无需手动执行 SQL。
- 即使
enabled: false,数据库也会被始终使用,以便保存游戏内聊天。
- 对于 Postgres,请先创建数据库,然后设置
type: postgres 并填写凭据。
How to use in-game
| Command |
What it does |
/newchat |
开始一个新的私人聊天 — 你将获得 Chat #N(你的个人 ID) |
/ai <message> |
在你当前的聊天中发送消息 |
/endchat |
结束你当前的聊天(历史记录仍会被保存) |
/reopenchat <id> |
重新打开你的某个已保存的聊天(例如 /reopenchat 1) |
/ailink |
将你的账号绑定到 Web UI(在网页输入用户名后) |
Chat IDs are per-player. If you run /reopenchat 1, that is your chat #1 — not another player's.
Example session:
/newchat
→ Chat #3 started. Only you see this conversation.
/ai what should I build in survival?
/ai give me a compact starter base layout
/endchat
/reopenchat 3
/ai add a storage room to that plan
/endchat
/ai 仅在聊天处于活动状态时有效(通过 /newchat 或 /reopenchat 激活)。
- 其他玩家无法看到你的消息或 AI 的回复。
Web UI
在浏览器中打开 http://<server-ip>:8765(使用 web.yml 中的 port)。
Link your account:
- 在网页上输入你的 Minecraft 用户名。
- 加入服务器并运行
/ailink。
- 在游戏内仅对你显示的代码输入到网页中。
What you can do on the web:
- 浏览完整的聊天记录
- 从浏览器开始新的聊天
- 继续之前的对话
- 查看与游戏内相同的每位玩家的聊天编号(
Chat #1 始终属于你)
服务器管理员提示:
- 如果玩家远程连接,请在防火墙中转发/开放 Web 端口。
- 设置
bind-address: "127.0.0.1" 并使用反向代理,以便在不直接暴露端口的情况下实现 HTTPS 或外部访问。
- 通过
enabled: false 禁用 Web UI —— 游戏内聊天和数据库持久化功能仍然正常工作。
权限
| 权限 |
默认值 |
描述 |
aicraft.use |
true (所有人) |
/newchat, /ai, /endchat, /reopenchat |
aicraft.web |
true (所有人) |
Web UI 的 /ailink |
aicraft.chats.unlimited |
op |
无每日新建聊天数量上限 |
aicraft.chats.<n> |
— |
例如 aicraft.chats.50 = 每 24 小时可创建 50 个新聊天 |
速率限制 计算的是滚动 24 小时窗口内 创建的新聊天数量 —— 而非单个消息。
- 如果玩家拥有
aicraft.chats.50,他们每天可以创建 50 个新聊天。
- 如果他们同时拥有
aicraft.chats.unlimited,则无限额度优先。
- 否则将应用
web.yml 中的默认值(default-chats-per-day)。
LuckPerms 开箱即用。按常规方式向组授予节点权限。如果安装了 LuckPerms,离线状态下通过 Web 创建聊天的玩家将使用 LuckPerms 缓存的权限。
示例(LuckPerms):
/lp group vip permission set aicraft.chats.100 true
/lp group default permission set aicraft.chats.10 true
故障排除
"No active chat. Start one with /newchat."
在运行 /ai 之前,请先运行 /newchat 或 /reopenchat <id>。
"Daily chat limit reached"
玩家已达到其 24 小时内新建聊天的上限。请授予更高的 aicraft.chats.<n> 权限、aicraft.chats.unlimited,或在 web.yml 中提高 default-chats-per-day 的值。
"Failed to reach AI endpoint" / 连接错误
- 确认你的 AI 服务器正在运行(例如
ollama serve)。
- 检查
config.yml 中的 endpoint —— 包含完整路径(/v1/chat/completions)。
- 如果模型运行在其他机器上,请使用该主机的 IP 地址而不是
localhost。
- 确保 Minecraft 服务器能够访问该主机和端口(防火墙、Docker 网络)。
HTTP 404 / 未找到模型
- 为
config.yml 中 model 字段指定的名称运行 ollama pull <model>(或等效命令)。
model 必须与你的提供商列出的名称完全匹配。
回复缓慢或超时
- 在
config.yml 中增加 timeout-seconds 的值。
- 在本地使用更小/更快的模型。
Web UI 无法加载
- 检查
web.yml 中的 enabled: true。
- 确认你的防火墙/托管面板已开放该端口。
- 查看服务器日志,寻找
Aicraft web UI running on http://...。
"/ailink" 提示没有待处理的 Web 链接
先在 Web UI 中输入你的用户名,然后在有效期(link-code-expiry-minutes)内运行 /ailink。
链接代码已过期
重新开始:再次在 Web 中输入你的用户名,然后在游戏内运行 /ailink。
Postgres 连接错误
- 确保数据库存在,且
web.yml 中的凭据正确无误。
- 确保 Minecraft 服务器能够访问 Postgres 主机。
加入 Discord! (进行中)
Aicraft adds private AI chat to your Paper server — in-game and in the browser. Talk to Ollama, Unsloth, vLLM, or any OpenAI-compatible API. Conversations are saved per player, with a web UI for history and linking your Minecraft account.
v1.1.0 adds the web UI, SQLite/Postgres chat history, per-player chat IDs, account linking, and LuckPerms-friendly daily chat limits.
Requirements
- Paper 1.21 or newer, including 26.x (Spigot is not supported)
- Java 21 for Paper 1.21.x servers, Java 25 for Paper 26.x servers
- An OpenAI-compatible chat API — local or cloud
- Optional: open port 8765 (or your chosen port) if you want the web UI reachable from outside the host
Works with:
- Ollama on
localhost
- Unsloth / vLLM / LM Studio and other
/v1/chat/completions endpoints
- OpenAI, Groq, OpenRouter, etc.
Installation
- Download the latest Aicraft
.jar from the Versions tab on this page.
- Drop it into your server's
plugins/ folder.
- Start or restart the server.
- On first run, Aicraft creates:
plugins/Aicraft/config.yml — AI endpoint settings
plugins/Aicraft/web.yml — web UI, database, and rate limits
plugins/Aicraft/aicraft.db — SQLite database (created automatically)
- Edit
config.yml before players use the plugin (see Configuration below).
- Restart after changing config (safest). Reloading may not restart the web server or database.
AI configuration (`config.yml`)
endpoint: "http://localhost:11434/v1/chat/completions"
api-key: "ollama"
model: "llama3.2"
system-prompt: "You are a helpful assistant inside a Minecraft server. Keep replies concise and game-friendly."
timeout-seconds: 120
max-history-messages: 20
| Option |
Description |
endpoint |
Full URL to the chat completions API (/v1/chat/completions) |
api-key |
API key sent as Authorization: Bearer …. Use any placeholder (e.g. ollama) if your server ignores auth |
model |
Model name your provider expects |
system-prompt |
Prepended to every new chat |
timeout-seconds |
HTTP timeout for AI requests |
max-history-messages |
Max user + assistant messages kept in the AI context window |
Ollama (local, recommended)
On the same machine as Minecraft:
ollama pull llama3.2
ollama serve
endpoint: "http://localhost:11434/v1/chat/completions"
api-key: "ollama"
model: "llama3.2"
If Ollama runs on another host, replace localhost with that machine's IP or hostname.
OpenAI (cloud)
endpoint: "https://api.openai.com/v1/chat/completions"
api-key: "sk-your-key-here"
model: "gpt-4o-mini"
Other local providers
Point endpoint at whatever /v1/chat/completions URL your stack exposes. localhost and private LAN addresses are supported.
Web & database configuration (`web.yml`)
enabled: true
port: 8765
bind-address: "0.0.0.0"
database:
type: sqlite
sqlite-file: "aicraft.db"
postgres:
host: "localhost"
port: 5432
database: "aicraft"
username: "aicraft"
password: ""
rate-limits:
default-chats-per-day: 50
linking:
link-code-expiry-minutes: 2
web-session-days: 30
| Option |
Description |
enabled |
Turn the web UI on or off |
port / bind-address |
Where the web server listens (0.0.0.0 = all interfaces) |
database.type |
sqlite (default) or postgres |
database.sqlite-file |
SQLite file inside plugins/Aicraft/ — created automatically |
database.postgres.* |
Postgres connection settings (database must exist beforehand) |
rate-limits.default-chats-per-day |
Max new chats per player per 24h when no permission overrides it |
linking.link-code-expiry-minutes |
How long an /ailink code stays valid |
linking.web-session-days |
How long a linked web session lasts |
Database notes:
- SQLite is zero-setup — the
.db file and tables are created on first startup.
- Migrations run automatically; you never need to run SQL by hand.
- The database is always used (even with
enabled: false) so in-game chats are saved.
- For Postgres, create the database first, then set
type: postgres and fill in credentials.
How to use in-game
| Command |
What it does |
/newchat |
Start a new private chat — you get Chat #N (your personal ID) |
/ai <message> |
Send a message in your active chat |
/endchat |
End your active chat (history is still saved) |
/reopenchat <id> |
Reopen one of your saved chats (e.g. /reopenchat 1) |
/ailink |
Link your account to the web UI (after entering your username on the web) |
Chat IDs are per-player. If you run /reopenchat 1, that is your chat #1 — not another player's.
Example session:
/newchat
→ Chat #3 started. Only you see this conversation.
/ai what should I build in survival?
/ai give me a compact starter base layout
/endchat
/reopenchat 3
/ai add a storage room to that plan
/endchat
/ai only works while a chat is active (/newchat or /reopenchat).
- Other players cannot see your messages or the AI's replies.
Web UI
Open http://<server-ip>:8765 in a browser (use your port from web.yml).
Link your account:
- Enter your Minecraft username on the web page.
- Join the server and run
/ailink.
- Enter the code shown only to you in-game on the web page.
What you can do on the web:
- Browse your full chat history
- Start new chats from the browser
- Continue old conversations
- See the same per-player chat numbers as in-game (
Chat #1 is always yours)
Tips for server admins:
- Forward/open the web port in your firewall if players connect remotely.
- Set
bind-address: "127.0.0.1" and use a reverse proxy if you want HTTPS or external access without exposing the port directly.
- Disable the web UI with
enabled: false — in-game chat and database persistence still work.
Permissions
| Permission |
Default |
Description |
aicraft.use |
true (everyone) |
/newchat, /ai, /endchat, /reopenchat |
aicraft.web |
true (everyone) |
/ailink for the web UI |
aicraft.chats.unlimited |
op |
No daily cap on new chats |
aicraft.chats.<n> |
— |
e.g. aicraft.chats.50 = 50 new chats per 24h |
Rate limits count new chats created in a rolling 24-hour window — not individual messages.
- If a player has
aicraft.chats.50, they get 50 new chats per day.
- If they also have
aicraft.chats.unlimited, unlimited wins.
- Otherwise the default from
web.yml applies (default-chats-per-day).
LuckPerms works out of the box. Grant nodes to groups as usual. Players creating chats from the web while offline use LuckPerms cached permissions if LuckPerms is installed.
Example (LuckPerms):
/lp group vip permission set aicraft.chats.100 true
/lp group default permission set aicraft.chats.10 true
Troubleshooting
"No active chat. Start one with /newchat."
Run /newchat or /reopenchat <id> before /ai.
"Daily chat limit reached"
The player has hit their 24h new-chat cap. Grant a higher aicraft.chats.<n> permission, aicraft.chats.unlimited, or raise default-chats-per-day in web.yml.
"Failed to reach AI endpoint" / connection errors
- Confirm your AI server is running (
ollama serve, etc.).
- Check
endpoint in config.yml — include the full path (/v1/chat/completions).
- If the model runs on another machine, use that host's IP instead of
localhost.
- Ensure the Minecraft server can reach that host and port (firewall, Docker networking).
HTTP 404 / model not found
- Run
ollama pull <model> (or equivalent) for the name in model.
- Match
model exactly to what your provider lists.
Slow or timed-out replies
- Increase
timeout-seconds in config.yml.
- Use a smaller/faster model locally.
Web UI won't load
- Check
enabled: true in web.yml.
- Confirm the port is open in your firewall / hosting panel.
- Check the server log for
Aicraft web UI running on http://....
"/ailink" says no pending web link
Enter your username on the web UI first, then run /ailink within the expiry window (link-code-expiry-minutes).
Link code expired
Start over: enter your username on the web again, then run /ailink in-game.
Postgres connection errors
- Make sure the database exists and credentials in
web.yml are correct.
- Ensure the Minecraft server can reach the Postgres host.
Join the Discord! (WIP)
评论 0
登录后参与评分
还没有评论,来抢沙发吧