FAQ en

FAQ

Model / config

Q: Natural-language commands do nothing / log shows deepseek_key_missing? No API key. Set DEEPSEEK_API_KEY, or fill deepseek.apiKey in aibot.json. See Getting Started. Note: deterministic /aibot task commands work even without a key.

Q: Can I use a model other than DeepSeek? Yes. Point deepseek.baseUrl at any OpenAI-compatible endpoint and set the model. See Configuration.

Q: A single goal burns a lot of tokens? Lower brain.maxTurnsPerRequest / maxToolCallsPerTurn, and steer the model to high-level tools (mine_ore / gather) over low-level ones. You can disable exposeLowLevelTools. See Brain & Tools.

Behavior

Q: Bob just stands still / is stuck? It may have been aborted by StuckWatcher. Check the task_stuck_aborted log. If it happens while genuinely working, that task likely needs the isWaiting() opt-out. See Safety Net.

Q: I asked for diamonds but it stopped after making an iron pickaxe? Classic case: diamonds require an iron pickaxe first, so the engine back-chains "mine iron → craft iron pickaxe → then diamonds". If a mid step (e.g. gathering wood) fails in a harsh environment, the goal can break. There's now userGoal protection (prevents goal downgrade) and a treeless fallback (long-range tree prospecting). If it still fails, check the log for the failing step. See Goal Engine.

Q: The bot died? Check the cause: the diag_bot_died log notes fall / in_lava / air. The safety net handles drowning / lava / swarms, and dig-moves circuit-break on drowning / attack. Extremely harsh environments can still be fatal. See Safety Net.

Q: It teleports / bunny-hops, looks unnatural? Fixed in recent versions: walking taps jump once only when grounded with a real step/gap (no bunny-hop), gathering roams by walking (no teleport), descent is staircase-style. See Safety Net.

Q: No trees / ore nearby, so it gives up? Both gathering and mining use long-range palette scanning: if nothing is nearby, they locate the resource at range and pathfind to it. It only fails if the whole area truly lacks that resource.

Commands / permissions

Q: Commands don't work / panel says insufficient permission? /aibot commands need command permission (OP). Panel actions also run through server commands, limited by the server's permission config. See Client Panel.

Q: How do I discover commands / parameters? Press Tab after /aibot in-game for completion. Common commands in Commands.

Performance

Q: TPS dropped? Check with /aibot observe tps. Long-range scans are rate-limited to protect TPS; reduce the number of active bots, or lower perception.radius.

Development

Q: Compile errors after editing Minecraft / Fabric code? Usually a signature change. The project pins Yarn 1.21.3+build.2; verify signatures before touching item components / eating / fuel / mining speed / furnace / client networking. See Developer Guide.

Q: How do I verify a behavior works? Use /aibot verify <bot> <feature> for built-in scenarios, or /aibot deplint <bot> <spec> to audit the plan chain offline. See Developer Guide.

---

Didn't find your answer? Open a question on GitHub Issues.