NekroAgent: a multi-platform agent framework built around a code sandbox
NekroAgent 是一个面向多人互动场景的跨平台 Agent 框架，集 Claude Code 沙盒执行、工作区编排、长期记忆、结构化 MCP 管理与可视化控制台于一体，兼具高扩展性、多模态交互、实时状态推送和自动化运行能力。项目支持 QQ、Discord、Telegram、Minecraft、BilibiliLive、WeChat、Email、SSE(SDK) 等多种平台接入，应用于构建高智能聊天机器人，可扩展为具备代码执行、工具调用、插件协作和复杂任务处理能力的通用 Agent 系统
At a glance
- What is it?
- NekroAgent is a Python agent framework that routes messages from QQ, Discord, Telegram and other platforms through a shared core, then lets the model answer by writing code that runs in a container. It is mature enough to deploy with one script, but its most interesting features are still marked preview.
- Who is it for?
- Adopt NekroAgent if you are running a multi-user chat bot on a platform the adapters already cover and you want the model to execute code rather than only emit text. Do not adopt it if you need a stable, fully documented memory or MCP layer today, since the README labels those preview.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 20 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem NekroAgent targets: one agent, many chat platforms, real tool use
Most chat bot projects are written for a single platform. A QQ bot is a QQ bot. Moving it to Discord means rewriting the message handling, the permission model and the command layer. NekroAgent takes the opposite position. The README describes an adapter layer where each platform needs only to implement message receipt and message sending, while channel management, plugin execution and sandbox calls are handled by a shared core engine. That is the whole pitch: the adapter is thin, the engine is where the work happens.
The second half of the problem is what the agent is allowed to do. A conventional bot replies with text. NekroAgent instead guides the model to generate code and run it in a containerized environment, with RPC used to talk back to the real system. The README calls the sandbox the foundation for complex tasks and method-level extensibility. So the intended user is not someone who wants a FAQ responder. It is someone building a bot that has to convert a file, call an external tool, or chain several steps together inside a group chat where several people are talking at once.
Input stream, dispatcher, shared services, output stream
The architecture diagram in the README is small but specific. Adapters sit outside the core. Each adapter feeds an input stream named collect_message, which hands off to a dispatcher. The dispatcher routes into core shared services covering channels, plugins and the sandbox. Results come back through an output stream named forward_message, which the adapters consume and push to their platform.
That is a clean separation, and the consequence is that adding a platform does not mean touching business logic. It also means the core has to be opinionated about what a channel is, since channel state is a shared service rather than something each adapter owns. The README lists OneBot v11 for QQ, Discord, Telegram, Minecraft, Bilibili Live, WeChat through WeChatPad, Email over SMTP and IMAP, and an SSE plus SDK option for custom integrations. The SSE adapter is the escape hatch: if your platform is not on the list, you can speak the event protocol yourself instead of writing a full adapter.
Around the execution path sit the preview features. The README describes a workspace and Claude Code sandbox system for managing prompts, skills, model presets, files, extensions, MCP, sandboxes and run state in one place. A memory system is described as introducing entities, relations, paragraphs, episodes, vector retrieval and a rebuild maintenance mechanism. MCP service management gets a registry and a card-style interface. None of these are presented as finished.
Getting it running: the install script and the two Docker tags
The README recommends a one-line install script. From GitHub:
sudo -E bash -c "$(curl -fsSL https://raw.githubusercontent.com/KroMiose/nekro-agent/main/docker/install.sh)" - --with-napcat
There is a mirror for networks that cannot reach GitHub cleanly, served through ep.nekro.ai, with the same script path and the same --with-napcat flag. The README states that --with-napcat produces a fully automatic standard deployment, and that omitting it drops the script into interactive mode where you are prompted to confirm installing Napcat.
If you prefer to manage containers yourself, two image tags are published to both Docker Hub and GHCR. latest tracks tagged releases and is described as suitable for production. preview is rebuilt on every main branch update and is described as suitable for testing and development. The pull commands given are docker pull kromiose/nekro-agent:latest and docker pull kromiose/nekro-agent:preview.
For API work, passing --docs exposes Swagger UI at http://localhost:8021/api/docs and ReDoc at http://localhost:8021/api/redoc. Error responses are structured with error, message, detail and data fields, and the README notes Accept-Language support on those errors. Note the port: 8021, not 8000.
Where the preview label actually matters
The README is unusually honest about maturity. The feature list splits into checked items and items marked with a test-tube symbol, and the test-tube items are the workspace and Claude Code sandbox, the memory system, structured MCP management and the command management center. The preview section repeats them and adds timers, stop-reply flow, channel quotas, plugin activation policy, and WebUI improvements including SSE push, system events, agent activity cards and multi-language support.
Treat that split as the real constraint. The stable surface is adapters, chat, personas, sandbox execution, multimodal handling, plugins, docker-compose deployment, hot reload, scheduled tasks, WebUI and event support. The preview surface is exactly the part that makes the project interesting to an agent builder: long-term memory and structured MCP. If your design depends on entities and relations persisting across sessions, you are building on a component the maintainers have not declared stable.
The other constraint is the licence. The repository metadata reports NOASSERTION, and the README says nothing about licensing terms. That is not a detail you can guess at. If you plan to run this commercially or fork it, read the licence file in the repository before you build anything on top of it. I cannot tell you what those terms are from the material available.
Why not just write a NoneBot plugin
NoneBot is the obvious comparison, and the README makes it explicit: the project is a rewrite of Naturel GPT, a NoneBot plugin, and the logo section carries a NoneBotPlugin badge. So the lineage is not hidden.
The difference is in what the model is asked to produce. A NoneBot plugin responds to a matched command or a message pattern with logic the developer wrote. NekroAgent responds by having the model write code, which then executes in a container and communicates back over RPC. That shifts the extension point from Python functions you register to a sandbox the model can target. The README frames this as method-level extensibility and as a way to avoid what it calls useless prompts and abusive agent iteration.
The trade-off is real. With a NoneBot plugin you can read the handler and know exactly what will happen. With NekroAgent the behavior is generated per request, and the container is the boundary that keeps that generation from touching the host. If your bot's job is a fixed set of commands, the sandbox is overhead you are paying for nothing. If your bot's job is open-ended file and data work in a group chat, the sandbox is the reason to pick this over a plugin framework.
Maintenance cost and the preview-to-stable gap
The release history shows a project that moves. v2.2.0 landed in January 2026 with async tasks and plugin capability work, v2.3.0 in April with a memory-focused title, and v2.4.0 in August 2026 described as knowledge network and interconnection enhancement. The last push to main is dated 2026-08-27, close to the v2.4.0 tag. Three releases across roughly seven months, with main receiving commits after the most recent tag.
That cadence has a cost. If you run the preview image, you are tracking main, and main is where the workspace, memory and MCP work is landing. The README says preview is rebuilt on every main update. Upgrading means accepting that the memory schema, which the README describes in terms of entities, relations, paragraphs and episodes, may change between builds. If you run latest, you are on tagged releases, but the features you wanted are the preview ones.
There is also an operational surface to maintain: a container runtime, the sandbox image, the WebUI, the adapters for each platform you connect, and the plugin set. The one-script install makes the first hour easy. It does not make the following months free.
Who this fits, and what to check before you deploy
The fit is narrow but clear. You are running a bot in a multi-user chat environment, on one of the listed platforms, and you want the agent to do work rather than only talk: process an image, convert a document, call an external service, chain steps. You want a single core with pluggable adapters so that adding Discord later does not mean a second codebase. You are comfortable running containers and reading a doc site rather than a README.
The misfit is equally clear. If you need a fixed command surface with predictable output, a plain plugin framework is less machinery for the same result. If your deployment cannot run containers, the sandbox model does not apply. If your compliance process requires knowing the licence before adoption, the NOASSERTION status in the repository metadata is a blocker until you read the actual licence file.
Before deploying, check three things against the doc site at doc.nekro.ai rather than the README. First, whether the memory system's entity and relation model is documented well enough to design against, or whether it is still moving. Second, whether the MCP registry has a documented configuration format, since the README mentions the interface but not the keys. Third, whether the adapter you need is in the stable list or the in-development list. The install script and the two image tags are the easy part. The preview label on workspace, memory and MCP is the part that decides whether this is your framework this quarter or next.
Editorial conclusion
Adopt NekroAgent if you are running a multi-user chat bot on a platform the adapters already cover and you want the model to execute code rather than only emit text. Do not adopt it if you need a stable, fully documented memory or MCP layer today, since the README labels those preview. Before committing, verify the licence terms yourself, because the repository reports NOASSERTION, and check whether the doc site documents the preview features you actually intend to use.
Community notes