Switch to English

✨ 高可扩展 | 高自由度 | 极简部署 的 AI 聊天 & 代理执行 Bot! ✨

🚅 源自首批大模型机器人应用 Naturel GPT 的 Agent 升级重构续作 🌈
📚 Nekro Agent 文档中心 提供完整的入门指南与开发文档 📚
💬 技术交流/答疑 -> 加入社区 QQ 交流群: 636925153 (1群|将满) | 679808796 (2群|新开) | Discord Channel 🗨️
🚀 NekroAI 云社区 提供插件和人设实时自由共享，生态观测功能等你体验！ 🚀

我们很高兴地宣布，我们正在计划进行国际化改造，以更好地支持我们的全球社区。我们欢迎来自世界各地的开发者加入我们的行列。

来我们的官方 Discord 服务器上与我们聊天，分享您的想法，成为 Nekro Agent 未来的重要一员！

• 加入我们的 Discord: NekroAI Official

NekroAgent 通过强大灵活的提示词构建系统，引导 AI 生成准确的代码并在沙盒中执行，通过 RPC 通信来与真实环境交互。主要特点包括：

核心执行与扩展能力:

• 代码生成与安全沙盒：引导 AI 生成代码并在安全的容器化环境中执行，实现复杂任务与方法级扩展性的坚固基石！
• 高度可扩展的插件系统：提供多种关键节点回调、提示词注入、自定义沙盒方法，从小型工具扩展到大型系统优雅集成的超智能中枢解决方案！
• 原生多人场景互动：高效洞悉群聊场景需求，在复杂的多人对话中保持交互能力！
• 极致的降本增效：拒绝无效提示词与滥用迭代智能体，聚焦解决问题的逻辑根本。
• 自动纠错与反馈：深耕提示词纠错与反馈机制，打破困于错误与重复的循环。

连接与交互:

• 多平台适配器架构：原生支持 OneBot v11 (QQ)、Discord、Telegram、Minecraft、B站直播、微信、邮件 及 SSE+SDK 等多种聊天平台，提供统一的开发接口。
• 原生多模态视觉理解：可处理图片、文件等多种资源，与用户进行多模态交互。
• 基于事件驱动的异步架构：遵循异步优先的高效响应机制。

生态与易用性:

• 云端资源共享：包括插件、人设等，拥有强大友好的社区驱动能力。
• 功能齐全的可视化界面：提供强大的应用管理与监控面板。

以下内容为当前 main / preview 版本中的重点新能力：

• 全新工作区 / Claude Code 沙盒体系（预览版）：统一管理提示词、技能、模型预设、文件、扩展、MCP、沙盒与运行状态，面向更完整的 Agent 工作流。
• Memory System 长期记忆（预览版）：引入实体、关系、段落、episode、向量检索与重建维护机制，为 Agent 提供可持续沉淀的长期上下文能力。
• 结构化 MCP 服务管理（预览版）：新增 registry 与卡片式管理界面，让外部工具与 MCP 服务接入更清晰、更可控。
• 命令系统重构（预览版）：命令注册、解析、分组、补全、输出查看与前端管理能力完成一轮系统化升级。
• 定时器与运行治理增强（预览版）：新增 timers 管理、停止回复流程、频道配额与插件激活策略，提升自动化和可运营性。
• WebUI 与实时状态体验升级（预览版）：聊天消息样式、SSE 实时推送、系统事件、Agent 活动卡片、工作区导航与多语言支持都有明显增强。

Nekro Agent 的核心是面向 输入/输出流 设计的。适配器（Adapter）作为连接外部平台的桥梁，仅需实现对具体平台消息的接收（输入流）和发送（输出流）。所有复杂的业务逻辑，如频道管理、插件执行、沙盒调用等，都由 Nekro Agent 的核心引擎自动接管和处理。这种设计确保了极高的扩展性和维护性，让开发者可以专注于实现适配器本身的功能，而无需关心核心的复杂实现。

graph TD
    subgraph 外部平台
        P1["平台 A (例如: QQ)"]
        P2["平台 B (例如: Minecraft)"]
        P3[...]
    end

    subgraph Nekro Agent
        subgraph 适配器层
            A1["适配器 A"]
            A2["适配器 B"]
            A3[...]
        end

        subgraph 核心引擎
            Input["输入流 (collect_message)"] --> Dispatcher
            Dispatcher{"消息<br>分发器"} --> Services["核心共享服务<br>(频道, 插件, 沙盒等)"]
            Services --> Output["输出流 (forward_message)"]
        end
    end

    P1 <==> A1
    P2 <==> A2
    P3 <==> A3

    A1 --> Input
    A2 --> Input
    A3 --> Input

    Output --> A1
    Output --> A2
    Output --> A3

启用 --docs 参数后可访问：

• Swagger UI: http://localhost:8021/api/docs
• ReDoc: http://localhost:8021/api/redoc

API 使用标准 HTTP 状态码，错误响应为结构化格式并支持 Accept-Language：

{
  "error": "ValidationError",
  "message": "参数校验失败",
  "detail": "field: error detail",
  "data": null
}

Nekro Agent 提供了强大而直观的可视化界面，方便您管理和监控 Agent 的所有行为，以及实现多种精细化的 Agent 行为策略控制等。

Nekro Agent 提供多样化的应用场景，从情感陪伴到复杂任务处理，满足各类需求：

• 💖 情感交互与陪伴：通过灵活的人设系统和先进的大语言模型，提供自然流畅的情感互动体验，支持多种角色定制和可扩展的记忆能力
• 📊 数据与文件处理：高效处理各类图像、文档及数据，无需额外软件支持，轻松完成格式转换与内容提取
• 🎮 创意与开发辅助：从网页应用生成到数据可视化，让创意实现变得简单高效
• 🔄 自动化与集成：支持事件订阅推送和多 AI 协作，实现复杂任务的智能自动化
• 📚 学习与生活助手：从学习辅导到内容创作，再到智能家居控制，全方位提升生活品质

👉 更多精彩用例与演示，请访问应用场景展示页面！

• ✅ 多平台适配：
  • ✅ OneBot v11 (QQ)
  • ✅ Discord
  • ✅ Telegram
  • ✅ Minecraft
  • ✅ Bilibili Live (B 站直播)
  • ✅ WeChat (微信，通过 WeChatPad)
  • ✅ Email (邮件，SMTP/IMAP)
  • ✅ SSE+SDK (Server-Sent Events + SDK)
  • ✅ ... 更多适配器开发中
• ✅ 智能聊天：群聊/私聊场景下的上下文智能聊天
• ✅ 自定义人设：支持自定义人设与云端人设市场
• ✅ 沙盒执行：安全的容器化代码执行环境
• ✅ 多模态交互：支持发送、接收和处理图片及文件资源
• ✅ 插件生态：高度可扩展的插件系统与云端插件市场
• ✅ 一键部署：基于 docker-compose 的容器编排一键部署
• ✅ 热重载：配置热更新与指令控制支持
• ✅ 定时任务：支持定时自触发插件与节日祝福
• ✅ WebUI：功能齐全的可视化应用管理控制面板
• ✅ 事件支持：可响应多种平台事件通知并理解其上下文
• ✅ 外置思维链 (CoT) 能力支持
• ✅ 完善第三方插件能力及 AI 生成插件
• 🧪 工作区 / Claude Code 沙盒（预览版）：统一管理沙盒任务、提示词、技能、模型预设、文件与扩展
• 🧪 Memory System（预览版）：长期记忆、向量检索、记忆维护与可视化管理面板
• 🧪 结构化 MCP 管理（预览版）：MCP 服务注册、共享配置与可视化卡片管理
• 🧪 命令管理中心（预览版）：新命令系统、命令输出页与可视化管理界面

我们提供了多种部署方式，请访问 快速开始文档 查看详细教程：

• Linux 部署教程
• Windows 部署教程
• MacOS 部署教程

sudo -E bash -c "$(curl -fsSL https://raw.githubusercontent.com/KroMiose/nekro-agent/main/docker/install.sh)" - --with-napcat

如果从 Github 下载脚本遇到网络问题，您可以使用 Nekro Endpoint 的边缘代理访问地址：

sudo -E bash -c "$(curl -fsSL https://ep.nekro.ai/e/KroMiose/nekro-agent/main/docker/install.sh)" - --with-napcat

提示:

上述命令中的 --with-napcat 参数会启动全自动标准部署。 如果不加此参数，脚本会以交互模式启动，届时请选择 Y 以安装 Napcat。

Nekro Agent 提供两种 Docker 镜像标签，同时发布到 Docker Hub 和 GitHub Container Registry (GHCR)：

• latest: 稳定版本，基于 tag 发布，适用于生产环境
• preview: 预览版本，每次 main 分支更新自动构建，包含最新功能，适用于测试和开发

# 使用稳定版本（推荐）
docker pull kromiose/nekro-agent:latest

# 使用预览版本（体验最新功能）
docker pull kromiose/nekro-agent:preview

# 使用稳定版本
docker pull ghcr.io/kromiose/nekro-agent:latest

# 使用预览版本
docker pull ghcr.io/kromiose/nekro-agent:preview

我们欢迎所有开发者为 Nekro Agent 社区贡献代码或想法！

• 插件开发指南(施工中)
• 应用开发指南
• 项目架构解析

注意：贡献代码前请先阅读许可说明中的条款，贡献代码即表示您同意这些条款。

常见问题及解答请访问 故障排除与 FAQ

前往 Release 页面 查看重要更新日志

NekroAgent 采用 自定义的开源协议（基于 Apache License 2.0 修改）进行分发。请在遵守协议的前提下使用本项目！

感谢以下开发者对本项目做出的贡献