Bots4Velo
Bots4Velo 是一个多协议、无头 Minecraft 客户端,运行在 Velocity 内部。它保持机器人在线、处理身份验证、切换后端服务器、执行挂机行为,并可选择使用 Paper 伴侣来管理无敌状态、游戏模式和重生点。
AFK_Image
支持的协议
| 配置值 |
协议 |
适配器 |
1.16.5 |
754 |
旧版登录/游戏 |
1.21.11 |
774 |
现代登录/配置/游戏 |
26.1.2 |
775 |
现代登录/配置/游戏 |
26.2 |
776 |
现代登录/配置/游戏 |
protocol-version: "AUTO" 会在选择适配器之前 ping 机器人的目标后端。后端名称必须与 Velocity 的 [servers] 条目完全匹配,包括大小写。
安装
仅机器人连接
-
将最新的 bots4velo.jar 发布版本放入 Velocity 的 plugins 目录中。
-
启动一次 Velocity。它将创建:
plugins/bots4velo/config.yml
plugins/bots4velo/secrets.yml.example
plugins/bots4velo/managed-bots.yml(在创建第一个机器人后)
-
确保目标后端已注册在 Velocity 的 [servers] 部分中。
-
在创建机器人之前重启或重载 Bots4Velo。
服务端玩家控制
要使用无敌状态、游戏模式、挂机属性或重生点:
- 在每个目标 Paper 后端的
plugins 目录中安装匹配的 bots4velo-paper.jar 发布版本。
- 在 Velocity 和所有 Paper 后端上使用相同的共享密钥。解码后的密钥必须至少为 32 字节。
- 优先使用环境变量:
# Velocity: plugins/bots4velo/config.yml
runtime:
backend-control:
enabled: true
secret: ""
secret-env: "BOTS4VELO_BACKEND_SECRET"
# Paper: plugins/Bots4VeloPaper/config.yml
shared-secret-env: "BOTS4VELO_BACKEND_SECRET"
shared-secret: ""
环境变量的优先级高于 YAML 回退值。更改密钥后,请重启 Velocity 和所有 Paper 后端。
默认配置和首次启动
捆绑的 config.yml 故意包含以下内容:
templates: {}
bots: {}
没有静态机器人,安装插件也不会登录任何账户。切勿直接在 config.yml 或 managed-bots.yml 中放置真实密码。
此默认设置仅适用于新生成的配置。升级现有实例不会删除其配置的机器人。
1. 准备密码
复制示例到:
plugins/bots4velo/secrets.yml
示例:
passwords:
farm01: "replace-with-a-strong-password"
secrets.yml 会被 Git 忽略,不得提交。生产部署可以使用 Velocity 进程环境变量代替。
2. 创建机器人
在 Velocity 控制台或以具有权限的玩家身份在聊天中运行以下命令:
/vbot create Farm01 AFK_Farm01 secret:farm01 survival
参数:
Farm01: 机器人 ID;允许字母、数字、_ 和 -;
AFK_Farm01: 离线模式玩家名称,3–16 个字符;
secret:farm01: 从 secrets.yml 读取 passwords.farm01;
survival: 注册的 Velocity 后端名称。
机器人将写入 managed-bots.yml 并排队启动。全局 spawn-interval-ms 限制连接突发。
对于不需要身份验证的机器人:
/vbot create Observer AFK_Observer - lobby
凭证 - 选择 NONE 身份验证。不要在 AuthMe/AuthMeUI 服务器上使用它,否则机器人将有意忽略身份验证界面。
3. 使用环境变量
/vbot create Farm02 AFK_Farm02 env:BOTS4VELO_FARM02_PASSWORD survival
BOTS4VELO_FARM02_PASSWORD 必须在 Velocity 进程环境中存在。Windows 服务和启动脚本应在启动 Velocity 之前设置它。
4. 移除机器人
/vbot remove Farm01
remove 仅删除使用 /vbot create 创建的机器人。静态机器人必须从 config.yml 中移除。
权限
Bots4Velo 默认不授予每个玩家控制权。使用 LuckPerms 时,仅授予每个角色所需的权限:
/lp user <player> permission set bots4velo.view true
/lp user <player> permission set bots4velo.control true
/lp user <player> permission set bots4velo.create true
/lp user <player> permission set bots4velo.reload true
| 权限 |
用途 |
bots4velo.view |
列出、状态、队列、诊断和历史记录 |
bots4velo.control |
启动、停止、重新连接、切换、移动和行为控制 |
bots4velo.create |
创建和管理机器人 |
bots4velo.reload |
验证和重载配置 |
bots4velo.admin |
所有权限 |
若要仅允许玩家创建机器人,请授予 bots4velo.create。当他们还需要监控或操作访问权限时,添加 view 或 control。
常用命令
/vbot help [page]
/vbot list [id|selector] [--page <page>]
/vbot queue [id|selector] [--page <page>]
/vbot status <id>
/vbot monitor [id]
/vbot history <id>
/vbot doctor [id|selector]
/vbot servers
/vbot create <id> <username> <secret:name|env:NAME|-> [target-server|-]
/vbot remove <id>
/vbot start <id|selector>
/vbot stop <id|selector>
/vbot reconnect <id|selector>
/vbot server <id|selector> <server>
/vbot movehere <id|selector>
/vbot command <id|selector> <command...>
/vbot behavior <id|selector> <start|pause|status>
/vbot afk <id|selector> status
/vbot afk <id|selector> preset <safe|farm|normal>
/vbot invulnerable <id|selector> <on|off|keep>
/vbot gamemode <id|selector> <survival|creative|adventure|spectator|unchanged>
/vbot spawnpoint <id|selector> <current|worldspawn|clear>
/vbot spawnpoint <id|selector> set <world> <x> <y> <z> [yaw]
/vbot respawn <id|selector>
/vbot language [en_US|zh_CN]
/vbot reload --check
/vbot reload
批量选择器
使用 all、@group:<name>、@tag:<name>、@server:<name> 或简写形式 @farm:
/vbot start all
/vbot stop @farm
/vbot server @lobby survival
/vbot reconnect @server:lobby
/vbot list all --state PLAY --page 1
/vbot movehere 必须由游戏内玩家执行。机器人首先切换至该玩家的后端,随后通过服务器端传送进行移动;玩家在该后端上仍需拥有传送权限。
AuthMe 与 AuthMeUI
Bots4Velo 支持:
- AuthMe/AuthMeReloaded 的
/login 和 /register 聊天流程;
- AuthMe 6 原生对话框(Dialogs);
- AuthMeUI 1.3.4 的规则、注册及登录对话框;
- 现代协议版本下的加入前与加入后身份验证。
当安装了身份验证插件时,请使用密码引用创建机器人:
/vbot create AuthBot AFK_AuthBot secret:authbot survival
使用 secret: 或 env: 引用将选择 auth.mode: AUTO。由于插件会读取对话框操作以及诸如 password 和 confirm 等字段键,因此支持 AuthMeUI 自定义标题和中文标签。
如果状态显示如下:
auth=disabled
AUTHME_UI ... ignored mode=NONE
则机器人处于无验证模式。请移除使用 - 创建的机器人,然后使用 secret:name 或 env:NAME 重新创建它。
请勿同时启用 AuthMe 原生对话框和 AuthMeUI 对话框。版本 1.16.5 不使用 AuthMeUI,而是继续使用聊天身份验证。
后端名称与协议检测
Velocity 配置示例:
[servers]
lobby = "127.0.0.1:25591"
survival = "127.0.0.1:25592"
try = ["lobby"]
创建机器人时使用已注册的名称:
/vbot create Farm01 AFK_Farm01 secret:farm01 survival
target-server 和 protocol-detection-server 必须完全匹配。如果日志中包含以下内容:
Unknown protocol detection backend: afk
则当前 Velocity 实例中没有名为 afk 的后端。请将机器人更改为正确的名称,或将 afk 添加到 Velocity 的 [servers] 中并重启 Velocity。/vbot reload 不会重新注册 Velocity 后端。
要在静态配置中强制指定协议:
proxy:
protocol-version: "26.2"
固定的协议无法修复缺失的目标后端问题。
机器人行为与玩家状态
基本的挂机(AFK)行为在身份验证后启动,并在服务器切换、重连和新 PLAY 会话建立后恢复:
/vbot behavior Farm01 start
/vbot behavior Farm01 status
/vbot behavior Farm01 pause
启用 Paper 辅助组件后,可以管理服务器端属性:
/vbot afk Farm01 preset safe
/vbot afk Farm01 preset farm
/vbot invulnerable Farm01 on
/vbot gamemode Farm01 creative
/vbot spawnpoint Farm01 worldspawn
/vbot respawn Farm01
这些操作由 Paper 执行,而非通过客户端数据包伪造。缺少辅助组件、密钥不匹配或后端不可达都会返回明确的失败信息。
验证与语言
请先验证更改:
/vbot reload --check
仅在验证成功后应用更改:
/vbot reload
验证失败绝不会替换正在运行的现有机器人。
消息默认使用英文。使用以下命令切换至中文:
/vbot language zh_CN
使用以下命令切回英文:
/vbot language en_US
语言文件位于 plugins/bots4velo/languages/ 下。自定义文件在升级过程中会被保留,缺失的键将从内置消息中填充。
诊断与故障排除
/vbot doctor <id>
/vbot status <id>
/vbot history <id>
常见状态说明:
CONFIGURATION:配置阶段仍在等待中,通常是在等待 AuthMeUI/AuthMe 对话框或资源包门控;
auth-ui Presented=1, Submitted=0:已看到 UI 但未提交;首先检查 auth.mode 是否不为 NONE,然后检查凭据引用;
target=MISSING:目标名称未在 Velocity 的 [servers] 中注册;
protocol=auto/pending:自动检测尚未完成;请检查后端连通性;
FAILED:身份验证失败、验证码(CAPTCHA)、双重验证(2FA)、封禁或重试配额耗尽;修复账号并手动运行 start 或 reconnect。
附加组件
独立的附加组件按每个组件一个目录存放:
plugins/bots4velo/addons/<addon-name>/
addon.jar
config.yml
Bots4Velo
Bots4Velo is a multi-protocol, headless Minecraft client that runs inside Velocity. It keeps bots online, handles authentication, switches backend servers, runs AFK behaviors, and can optionally use a Paper companion to manage invulnerability, game mode, and respawn points.
AFK_Image
Supported protocols
| Configuration value |
Protocol |
Adapter |
1.16.5 |
754 |
Legacy Login/Play |
1.21.11 |
774 |
Modern Login/Configuration/Play |
26.1.2 |
775 |
Modern Login/Configuration/Play |
26.2 |
776 |
Modern Login/Configuration/Play |
protocol-version: "AUTO" pings the bot's target backend before selecting an adapter. Backend names must exactly match Velocity's [servers] entries, including case.
Installation
Bot connections only
-
Put the latest bots4velo.jar release in Velocity's plugins directory.
-
Start Velocity once. It creates:
plugins/bots4velo/config.yml
plugins/bots4velo/secrets.yml.example
plugins/bots4velo/managed-bots.yml after the first bot is created
-
Make sure the target backends are registered in Velocity's [servers] section.
-
Restart or reload Bots4Velo before creating bots.
Server-side player controls
To use invulnerability, game mode, AFK properties, or respawn points:
- Install the matching
bots4velo-paper.jar release in the plugins directory of every target Paper backend.
- Use the same shared secret on Velocity and every Paper backend. The decoded secret must be at least 32 bytes.
- Prefer an environment variable:
# Velocity: plugins/bots4velo/config.yml
runtime:
backend-control:
enabled: true
secret: ""
secret-env: "BOTS4VELO_BACKEND_SECRET"
# Paper: plugins/Bots4VeloPaper/config.yml
shared-secret-env: "BOTS4VELO_BACKEND_SECRET"
shared-secret: ""
The environment variable takes precedence over the YAML fallback. Restart Velocity and all Paper backends after changing the secret.
Default configuration and first startup
The bundled config.yml intentionally contains:
templates: {}
bots: {}
There are no static bots, and installing the plugin does not log into any account. Never put real passwords directly in config.yml or managed-bots.yml.
This default only applies to newly generated configuration. Upgrading an existing instance does not delete its configured bots.
1. Prepare a password
Copy the example to:
plugins/bots4velo/secrets.yml
Example:
passwords:
farm01: "replace-with-a-strong-password"
secrets.yml is ignored by Git and must not be committed. Production deployments can use a Velocity process environment variable instead.
2. Create a bot
Run this in the Velocity console or in chat as a player with permission:
/vbot create Farm01 AFK_Farm01 secret:farm01 survival
Arguments:
Farm01: bot ID; letters, digits, _, and - are allowed;
AFK_Farm01: offline-mode player name, 3–16 characters;
secret:farm01: reads passwords.farm01 from secrets.yml;
survival: the registered Velocity backend name.
The bot is written to managed-bots.yml and queued for startup. The global spawn-interval-ms limits bursts of connections.
For a bot that does not need authentication:
/vbot create Observer AFK_Observer - lobby
The - credential selects NONE authentication. Do not use it on an AuthMe/AuthMeUI server, or the bot will intentionally ignore the authentication UI.
3. Use an environment variable
/vbot create Farm02 AFK_Farm02 env:BOTS4VELO_FARM02_PASSWORD survival
BOTS4VELO_FARM02_PASSWORD must be present in the Velocity process environment. Windows services and launch scripts should set it before starting Velocity.
4. Remove a bot
/vbot remove Farm01
remove deletes only bots created with /vbot create. Static bots must be removed from config.yml.
Permissions
Bots4Velo does not grant every player control by default. With LuckPerms, grant only what each role needs:
/lp user <player> permission set bots4velo.view true
/lp user <player> permission set bots4velo.control true
/lp user <player> permission set bots4velo.create true
/lp user <player> permission set bots4velo.reload true
| Permission |
Purpose |
bots4velo.view |
Lists, status, queue, diagnostics, and history |
bots4velo.control |
Start, stop, reconnect, switch, move, and behavior control |
bots4velo.create |
Create and remove managed bots |
bots4velo.reload |
Validate and reload configuration |
bots4velo.admin |
All permissions |
To let players create bots only, grant bots4velo.create. Add view or control when they also need monitoring or operation access.
Common commands
/vbot help [page]
/vbot list [id|selector] [--page <page>]
/vbot queue [id|selector] [--page <page>]
/vbot status <id>
/vbot monitor [id]
/vbot history <id>
/vbot doctor [id|selector]
/vbot servers
/vbot create <id> <username> <secret:name|env:NAME|-> [target-server|-]
/vbot remove <id>
/vbot start <id|selector>
/vbot stop <id|selector>
/vbot reconnect <id|selector>
/vbot server <id|selector> <server>
/vbot movehere <id|selector>
/vbot command <id|selector> <command...>
/vbot behavior <id|selector> <start|pause|status>
/vbot afk <id|selector> status
/vbot afk <id|selector> preset <safe|farm|normal>
/vbot invulnerable <id|selector> <on|off|keep>
/vbot gamemode <id|selector> <survival|creative|adventure|spectator|unchanged>
/vbot spawnpoint <id|selector> <current|worldspawn|clear>
/vbot spawnpoint <id|selector> set <world> <x> <y> <z> [yaw]
/vbot respawn <id|selector>
/vbot language [en_US|zh_CN]
/vbot reload --check
/vbot reload
Batch selectors
Use all, @group:<name>, @tag:<name>, @server:<name>, or the short form @farm:
/vbot start all
/vbot stop @farm
/vbot server @lobby survival
/vbot reconnect @server:lobby
/vbot list all --state PLAY --page 1
/vbot movehere must be run by an in-game player. Bots are switched to the player's backend first, then moved with a server-side teleport; the player still needs teleport permission on that backend.
AuthMe and AuthMeUI
Bots4Velo supports:
- AuthMe/AuthMeReloaded
/login and /register chat flows;
- AuthMe 6 native Dialogs;
- AuthMeUI 1.3.4 rules, registration, and login dialogs;
- pre-join and post-join authentication on modern protocol versions.
When an authentication plugin is installed, create the bot with a password reference:
/vbot create AuthBot AFK_AuthBot secret:authbot survival
A secret or environment reference selects auth.mode: AUTO. AuthMeUI custom titles and Chinese labels are supported because the plugin reads Dialog actions and field keys such as password and confirm.
If status shows:
auth=disabled
AUTHME_UI ... ignored mode=NONE
the bot is in no-auth mode. Remove the bot created with -, then recreate it with secret:name or env:NAME.
Do not enable AuthMe native Dialogs and AuthMeUI Dialogs at the same time. Version 1.16.5 does not use AuthMeUI and continues to use chat authentication.
Backend names and protocol detection
Example Velocity configuration:
[servers]
lobby = "127.0.0.1:25591"
survival = "127.0.0.1:25592"
try = ["lobby"]
Use the registered name when creating the bot:
/vbot create Farm01 AFK_Farm01 secret:farm01 survival
Both target-server and protocol-detection-server must match exactly. If the log contains:
Unknown protocol detection backend: afk
the current Velocity instance has no backend named afk. Change the bot to the real name, or add afk to Velocity's [servers] and restart Velocity. /vbot reload does not re-register Velocity backends.
To force a protocol in a static configuration:
proxy:
protocol-version: "26.2"
A fixed protocol does not repair a missing target backend.
Bot behavior and player state
Basic AFK behaviors start after authentication and recover after server switches, reconnects, and new PLAY sessions:
/vbot behavior Farm01 start
/vbot behavior Farm01 status
/vbot behavior Farm01 pause
With the Paper companion enabled, server-side properties can be managed:
/vbot afk Farm01 preset safe
/vbot afk Farm01 preset farm
/vbot invulnerable Farm01 on
/vbot gamemode Farm01 creative
/vbot spawnpoint Farm01 worldspawn
/vbot respawn Farm01
These operations are executed by Paper, not faked by client packets. Missing companions, mismatched secrets, and unreachable backends return explicit failures.
Validation and language
Validate changes first:
/vbot reload --check
Apply them only after validation succeeds:
/vbot reload
A failed validation never replaces the bots that are already running.
Messages default to English. Switch to Chinese with:
/vbot language zh_CN
Switch back with:
/vbot language en_US
Language files live under plugins/bots4velo/languages/. Custom files are preserved across upgrades and missing keys are filled from the bundled messages.
Diagnostics and troubleshooting
/vbot doctor <id>
/vbot status <id>
/vbot history <id>
Common states:
CONFIGURATION: the Configuration phase is still waiting, usually for an AuthMeUI/AuthMe Dialog or resource-pack gate;
auth-ui Presented=1, Submitted=0: a UI was seen but not submitted; first check that auth.mode is not NONE, then check the credential reference;
target=MISSING: the target name is not registered in Velocity's [servers];
protocol=auto/pending: automatic detection is not complete; check backend reachability;
FAILED: authentication failure, CAPTCHA, 2FA, ban, or retry budget exhaustion; fix the account and run start or reconnect manually.
Addons
Independent addons live in one directory per addon:
plugins/bots4velo/addons/<addon-name>/
addon.jar
config.yml
评论 0
登录后参与评分
还没有评论,来抢沙发吧