Nekro Agent
NekroAgent 是一个面向多人互动场景的跨平台 Agent 框架，集 Claude Code 沙盒执行、工作区编排、长期记忆、结构化 MCP 管理与可视化控制台于一体，兼具高扩展性、多模态交互、实时状态推送和自动化运行能力。项目支持 QQ、Discord、Telegram、Minecraft、BilibiliLive、WeChat、Email、SSE(SDK) 等多种平台接入，应用于构建高智能聊天机器人，可扩展为具备代码执行、工具调用、插件协作和复杂任务处理能力的通用 Agent 系统
Last verified:
What is Nekro Agent?
Nekro Agent is an AI agent framework that provides a smarter, more elegant proxy execution experience. It guides AI to generate accurate code through a powerful and flexible prompt construction system, executes code in a secure containerized sandbox environment, and interacts with the real environment via RPC communication. The framework supports complex tasks like chart generation, general content processing, and multimodal visual understanding.
Key features include a highly extensible plugin system with various callbacks and prompt injection capabilities, native multi-user scenario interaction support, cloud-based real-time resource sharing services for plugins and personas, a feature-rich visual WebUI management panel, dynamic installation of PYPI dependencies, AI-enhanced plugin editor for rapid custom plugin development, flexible dynamic model scheduling system, and webhook-based custom event push capabilities. It natively supports OneBot v11, Minecraft, Bilibili Live, Discord, and other chat platforms.
Nekro Agent is designed for developers building AI chatbots and agent execution bots, users who need multi-platform AI assistants for QQ, Discord, Minecraft, and other platforms, communities seeking customizable AI chat frameworks with plugin systems, and anyone wanting to create intelligent AI agent systems with code execution capabilities. It's particularly suitable for those who need secure sandboxed code execution, multimodal interaction, and highly extensible bot frameworks.
Nekro Agent pricing
Pricing model: Freemium
Nekro Agent is an open source and free product under MIT license. There is no paid tier or subscription required. The software itself is completely free to use. Users only need to provide their own AI model API keys (for services like Chat模型) which are billed separately by the model provider. The Nekro AI cloud service platform provides free community-driven capabilities including Plugin Store and Persona Store for sharing and downloading plugins and personas. Self-hosted deployment means no usage limits from the software itself.
Nekro Agent pros
- Secure containerized sandbox execution environment with complete Python runtime
- Powerful code guidance, generation, error correction, and execution capabilities
- Native multimodal visual understanding and interaction support
- Highly extensible plugin system with key node callbacks and prompt injection
- Native multi-user scenario interaction support for group chats
- Cloud-based real-time resource sharing for plugins and personas
- Feature-rich visual WebUI application management panel
- AI-enhanced plugin editor for low-barrier custom plugin development
- Instant hot updates for system and plugin configuration
- External Chain of Thought (CoT) high-quality reasoning capabilities
- Persona separation with independent settings for each session
- Webhook-based custom event push capabilities
- Flexible dynamic model scheduling system balancing performance and cost
- Support for dynamic installation of PYPI dependencies
- Built-in plugin lineup including sticker management, AI drawing, web search, notes, timer, dice rolling
- Open source and free product with MIT license
- Cross-platform support for Linux, Windows, and MacOS
- Rejection of invalid prompts achieving cost reduction and efficiency improvement
- Async-first efficient response mechanism with event-driven architecture
Nekro Agent cons
- Requires Docker and Docker Compose for deployment
- Port conflicts possible on ports 8021 and 6099
- Complex initial setup requiring configuration file editing
- OneBot V11 protocol limitations for file sending
- Docker daemon connection issues may occur
- Model API calls can fail due to API key or network issues
- Sandbox code execution may timeout for complex tasks
- Limited adapter support compared to mature bot frameworks
- Documentation primarily in Chinese with limited English coverage
- Requires technical knowledge for plugin development and customization
Frequently asked questions about Nekro Agent
What is Nekro Agent?
Nekro Agent is an AI agent framework and upgraded successor to Naturel GPT that provides smarter, more elegant agent execution. It guides AI to generate accurate code through a powerful prompt construction system, executes code in a secure sandbox, and interacts with the real environment via RPC communication. It supports multimodal interaction, multi-user scenarios, and has a highly extensible plugin system.
How do I deploy Nekro Agent?
Nekro Agent can be deployed on Linux, Windows, or MacOS using Docker. Use the nekro-agent-toolkit to install: first set a default data directory with 'nekro-agent-toolkit -st <data_dir>', then run full deployment with 'nekro-agent-toolkit -i <data_dir> --with-napcat'. The toolkit generates an .env file and sets up Docker containers including Nekro Agent and NapCat.
What chat platforms does Nekro Agent support?
Nekro Agent natively supports OneBot v11, Minecraft, Bilibili Live, Discord, and QQ through its multi-platform adapter architecture. It provides unified development interfaces for adapters, with plans to add more chat platform support in the future.
How does the sandbox execution work?
Nekro Agent uses a secure containerized sandbox execution environment with a complete Python runtime. AI generates code through the prompt system, which is then executed in the sandbox. The sandbox supports dynamic installation of PYPI dependencies and has a configurable execution time limit (default 60 seconds via SANDBOX_RUNTIME_LIMIT).
What is the Plugin Store?
The Plugin Store is part of Nekro AI cloud service platform, providing centralized management of functional extension plugins. It supports one-click installation, upgrades, and graphical configuration. Developers can publish and share capability modules, while users can browse and install plugins easily.
How do I create custom plugins?
Use the AI-enhanced Plugin Editor in the WebUI's Plugin Management section. Create a new plugin or select an existing one, input your requirements in the Plugin Needs field, click AI Generate to get修改意见, apply the changes, and save. The editor integrates AI assistance with preset development knowledge for rapid plugin implementation.
What if Docker container fails to start?
Common reasons include port conflicts (check ports 8021 and 6099), configuration file errors in configs/nekro-agent.yaml, or permission issues. View detailed error information with 'docker-compose logs -f nekro_agent'. Ensure the installation directory has correct permissions and the Docker service is running.
How do I switch AI personas?
Set up persona information in Persona Management in the WebUI, then select the desired persona in Session Management. Nekro Agent supports persona separation with independent persona settings for each session.
What models can I use with Nekro Agent?
Nekro Agent supports flexible model scheduling and works with various LLM providers. Configure the model in the .env file with CHAT_MODEL setting. The flexible dynamic model scheduling system can balance performance and cost by selecting the most suitable model for each iteration step. Check the Model Selection Guide in documentation for detailed analysis.
How do I completely uninstall Nekro Agent?
Execute: 'cd <installation_directory>' then 'sudo docker-compose down' to stop containers, 'sudo docker volume rm nekro_postgres_data' and 'sudo docker volume rm nekro_qdrant_data' to delete mounted volumes, optionally 'sudo docker rmi kromiose/nekro-agent kromiose/nekro-agent-sandbox' to remove images, and finally 'rm -rf <installation_directory>' to delete the installation directory.