快速开始

欢迎使用 Nekro Agent (以下简称 NA)！本文档将帮助您快速开始使用这个强大的 AI 代理系统。

⚠ 安全警告 ⚠

本项目运行时允许 AI 在独立 Docker 容器环境中执行任意代码，应用已采用多种包括但不限于容器隔离、权限限定等安全措施，但仍存在一定的安全风险，例如:

1. IP 地址泄漏
2. 容器逃逸
3. 其它未知风险

! 请知悉结果接受自行承担风险后继续，作者不对使用本项目造成的任何损失负责 !

官方部署选择

根据您的操作系统选择合适的部署方式：

• NA-Tools 部署 (推荐) - 官方 CLI 工具，支持 Linux/macOS 一键部署、备份与管理
• Linux 部署教程 - 适用于使用 apt 作为包管理器的 Linux 发行版
• Windows 部署教程 - 适用于 Windows 10/11 系统
• MacOS 部署教程 - 适用于 MacOS 系统

社区部署方案

• Nekro-Agent-Toolkit 跨平台部署 Cli 工具

  • 跨平台部署方案和便捷式的安装、备份、恢复NekroAgent 的方案。

• 1Panel 应用部署

  • 基于 1Panel 面板的开箱即用一键部署方案，支持纯界面部署操作和 OpenResty 反向代理配置，自动配置 NapCat 协议端。

• iStoreOS 系统部署

  • 在基于 OpenWRT 的软路由系统运行 Nekro Agent，提供一键安装脚本。

基本配置

成功部署后，您需要完成以下基本配置：

1. 适配器配置：连接到您选择的聊天平台
2. 模型配置：设置 AI 模型及 API 密钥
3. 系统配置：设置基本系统参数和用户权限

⚠ 重要安全信息 ⚠

为安全起见，请务必阅读以下信息:

1. 务必修改协议端默认密码：公网 WebUI 必须使用强密码（建议 12 位以上，含数字、字母、符号）
2. 为安全起见，请避免使用默认端口

详细配置说明请参考以下文档：

• 适配器配置
• 系统配置
• 应用更新

首次使用

访问管理界面

完成部署后，您可以通过以下地址访问管理界面：

• http://<您的服务器IP>:8021 (远程访问)
• http://localhost:8021 (本地访问)

登录管理界面

首次登录时，请使用部署过程中生成的管理员账户和密码进行登录

2.3.0 推荐路径

如果使用的是 preview 镜像或 main 分支构建，建议在完成基础部署后继续阅读以下内容：

1. 完成协议端、模型组和系统配置
2. 阅读工作区总览（即将发布）
3. 跟随工作区快速上手创建第一个工作区（即将发布）
4. 再继续阅读 Claude Code 沙盒与记忆系统（即将发布）

基本使用流程

1. 连接适配器：完成适配器配置并确认连接状态
2. 设置人设：配置 AI 的基本人设和行为模式
3. 测试对话：通过您选择的平台与 AI 进行对话测试
4. 创建工作区：在 WebUI 中创建工作区并绑定目标频道
5. 启动 Claude Code 沙盒：配置模型预设、CLAUDE.md 与运行策略
6. 扩展功能：按需启用记忆系统、MCP、技能、定时器等能力

下一步

完成基础配置后，您可以探索更多高级功能：

• 工作区总览 - 了解新版工作区与 Claude Code 主路径（即将发布）
• 工作区快速上手 - 走通第一个工作区任务（即将发布）
• Claude Code 沙盒 - 理解沙盒任务与通信记录（即将发布）
• 记忆系统 - 了解长期记忆与记忆重建（即将发布）
• 模型组配置 - 配置多种模型组合

快速参考

常用管理命令

# 查看 NA 容器日志
sudo docker logs -f nekro_agent

# 查看 NapCat 容器日志
sudo docker logs -f nekro_napcat

# 重启服务
sudo docker restart nekro_agent

常用聊天指令

/na-info - 显示当前应用信息
/na-help - 显示帮助信息
/reset - 重置当前会话

💡 功能探索

好奇 Nekro Agent 能做什么？查看 应用场景展示 了解丰富多样的实际使用案例和创意玩法！