接入 AstrBot

AstrBot 是一款由社区维护的开源一站式 Agent 助手，专为降低AI能力落地门槛设计。它原生支持接入QQ、微信、飞书、Telegram、Discord等10+主流消息平台，无需复杂开发即可将AI能力部署到你日常使用的聊天工具中；同时提供可视化技能配置、插件市场、MCP（模型上下文协议）扩展能力，支持自定义工具调用、自动化任务流、第三方服务集成，可满足个人私用、社群运营、团队协作、轻量业务自动化等多场景需求。

将DeepSeek系列模型接入AstrBot，可充分发挥DeepSeek V4的强推理能力、最高100万token的上下文窗口优势与高性价比特性：既可以用DeepSeek V4 Pro处理长文档理解、复杂逻辑推理、代码开发等专业任务，也可以用DeepSeek V4 Flash满足日常问答、消息回复等低延迟需求，无需自行部署模型服务，即可获得企业级的AI能力支撑。

通过本教程，你将掌握AstrBot的两种安装方式、DeepSeek模型的接入配置方法、基础使用流程，以及后续扩展的方向指引，全程操作无需代码基础，新手也可轻松完成。

💡 前置准备

1. 提前获取你的DeepSeek API Key：可前往DeepSeek开放平台创建并复制，确保API Key已开启DeepSeek V4系列模型的访问权限。
2. 环境检查：
   • 若选择uv安装方式：macOS/Linux需确保已安装curl（可执行curl --version验证，正常将输出版本号信息）；Windows需确保PowerShell版本≥5.1（可执行$PSVersionTable.PSVersion验证）。
   • 若选择Docker安装方式：需提前安装Docker Engine与Docker Compose v2+（可执行docker --version与docker compose version验证，正常将输出版本号信息）。
3. 网络要求：确保当前环境可正常访问GitHub与DeepSeek API地址https://api.deepseek.com，若为服务器部署，需提前开放6185端口的安全组与防火墙规则。
4. 路径注意：避免在包含中文、空格或特殊字符的目录下执行安装与初始化命令，否则可能导致服务启动失败。

1. 安装 AstrBot

通过 uv 安装 AstrBot

macOS 和 Linux 用户执行以下命令安装 AstrBot：

curl -LsSf https://docs.astrbot.app/install.sh | bash

操作目的：通过官方维护的安装脚本一键安装uv包管理器与AstrBot核心程序，无需手动配置环境变量。 预期结果：终端无报错，最终输出「AstrBot installed successfully」类的成功提示。 注意事项：若执行时提示permission denied，可在命令前添加sudo临时提升权限执行。

Windows 用户执行以下命令安装：

iwr -useb https://docs.astrbot.app/install.ps1 | iex

操作目的：通过官方PowerShell脚本完成Windows环境下的AstrBot安装。 预期结果：PowerShell无报错，最终输出安装成功提示。 注意事项：若执行时提示脚本禁止运行，可先执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser放开当前用户的脚本执行权限，安装完成后可按需恢复原有设置。

然后初始化并启动 AstrBot：

astrbot init # 仅首次使用时执行，用于初始化环境。这个指令会将 AstrBot 安装到当前终端所在的目录。
astrbot run  # 启动 AstrBot。这个指令会检测当前目录是否安装了 AstrBot，如果未安装会提示使用 `astrbot init` 初始化。

astrbot init 操作说明：

• 操作目的：初始化AstrBot运行目录，生成默认配置文件、插件目录、数据存储目录等必要文件结构。
• 预期结果：当前目录下生成名为astrbot_data的文件夹，终端输出「Initialization completed」提示。
• 注意事项：仅首次在当前目录使用时需要执行，后续启动直接用astrbot run即可。

astrbot run 操作说明：

• 操作目的：启动AstrBot核心服务与Web管理界面，加载本地配置。
• 预期结果：终端输出服务启动日志，明确显示「Web UI running on http://0.0.0.0:6185」，无报错信息。
• 注意事项：启动后请勿关闭当前终端，否则服务会停止；若需后台运行，可配合nohup、screen等工具实现。

通过 Docker 安装 AstrBot

首先克隆 AstrBot 仓库：

git clone https://github.com/AstrBotDevs/AstrBot --depth 1
cd AstrBot

操作目的：拉取AstrBot最新的Docker部署配置文件，--depth 1参数用于仅拉取最新提交，减少克隆体积与耗时。 预期结果：当前目录下生成AstrBot文件夹，进入文件夹后可看到docker-compose.yml文件。 注意事项：若克隆速度慢，可使用GitHub镜像地址替换原仓库地址，或通过代理访问。

然后启动服务：

sudo docker compose up -d

操作目的：基于Docker Compose配置文件后台启动AstrBot容器服务，无需手动配置依赖环境。 预期结果：终端输出容器创建与启动成功的日志，执行docker ps可看到名为astrbot的容器处于运行状态。 注意事项：若当前用户已加入docker用户组，可省略sudo；若启动报错端口被占用，可修改docker-compose.yml中的端口映射规则，将左侧的6185改为其他未被占用的端口。

2. 配置 AstrBot 中的默认模型

初始化完成后，打开 Web UI：

http://localhost:6185 # 如果 AstrBot 运行在服务器上，则访问 http://<server-ip>:6185

操作目的：通过可视化Web管理界面完成模型配置，避免手动修改配置文件容易出现的语法错误。 访问说明：若为本地部署直接访问http://localhost:6185；若为服务器部署，将<server-ip>替换为服务器的公网IP地址，确保服务器已开放6185端口的入站规则。

在左侧边栏进入 模型提供商 页面，点击 + 新增，选择 DeepSeek，将你的 DeepSeek API Key 粘贴到 API Key 输入框中，然后点击 保存配置。 步骤说明：

1. 进入「模型提供商」页面的目的是管理所有接入的LLM服务，AstrBot已内置DeepSeek的官方适配，无需手动填写API地址。
2. 粘贴API Key的作用是身份认证，后续调用DeepSeek接口时会自动携带该密钥。
3. 预期结果：保存后模型提供商列表中出现DeepSeek条目，状态显示为「启用」，无报错提示。
4. 注意事项：API Key请妥善保管，不要泄露给他人，也不要提交到公共代码仓库，避免产生不必要的费用损失。

接着在左侧边栏进入 配置文件（普通配置） 页面，将 默认对话模型 设置为刚刚配置的模型，确认选择后，点击右下角的保存按钮。 操作目的：设置全局默认对话模型，后续所有新会话将默认使用该模型，无需每次手动选择。 参数说明：可根据使用场景选择对应模型：

• 日常问答、消息回复等低延迟场景推荐选择deepseek-v4-flash，响应速度快、成本更低；
• 长文档理解、代码开发、复杂推理等场景推荐选择deepseek-v4-pro[1m]，支持百万级上下文，推理能力更强。 预期结果：保存后页面提示「配置已生效」，默认对话模型显示为你选择的DeepSeek模型。

其余设置，例如消息平台和技能等，可以按需配置。更多信息请参考 AstrBot 文档。 扩展指引：消息平台配置可将AstrBot接入QQ、微信等IM工具，实现聊天工具内直接调用DeepSeek模型；技能与插件配置可扩展工具调用、自动化任务等能力，可按需查看官方文档完成配置。

3. 开始使用

点击右上角的 Chat，进入 AstrBot Chat UI。现在你可以开始使用 DeepSeek 模型进行对话。 界面说明：Chat UI支持多会话管理、引用回复、模型切换、技能触发等功能，你可以直接输入问题发起对话，也可以上传文件、触发已配置的技能。 最佳实践：若需要处理长文档，可直接将文档粘贴到输入框，DeepSeek V4的百万上下文支持一次性处理最多100万token的内容，无需手动拆分。

你也可以配置消息平台，在常用聊天应用中直接使用 AstrBot。 场景示例：配置QQ平台后，可将AstrBot作为社群智能客服，自动回复群成员的问题；配置飞书平台后，可作为团队内部AI助手，支持员工查询文档、处理日常事务。

💡 避坑指南

1. 无法访问Web UI：首先检查AstrBot服务是否正常运行，终端有无报错；其次检查端口是否被占用，防火墙/安全组是否开放6185端口；若为服务器部署，确认使用的是服务器公网IP而非localhost。
2. 调用模型报错401：检查API Key是否正确，有无前后空格，是否已开启DeepSeek V4模型的访问权限。
3. 调用模型报错402：登录DeepSeek开放平台检查账户余额是否充足，若余额不足请充值后再使用。
4. 消息平台配置后无响应：检查对应平台的账号是否登录成功，有无被平台风控，权限配置是否正确。

❓ 常见问题

• Q：可以同时接入多个模型吗？ A：可以，在「模型提供商」页面多次添加不同的模型即可，使用时可在Chat UI中手动切换。
• Q：如何升级AstrBot？ A：uv安装的用户执行astrbot upgrade命令即可升级到最新版本；Docker安装的用户在AstrBot目录下执行git pull拉取最新配置，再执行docker compose up -d --force-recreate重启容器即可。
• Q：AstrBot的数据存储在哪里？ A：所有配置、会话、插件数据都存储在astrbot_data目录下（uv安装）或Docker挂载卷中（Docker安装），可直接备份该目录实现数据迁移。

参考资料

• awesome-deepseek-agent

✨ 教程总结 本教程覆盖了AstrBot的两种安装方式、DeepSeek模型的接入配置与基础使用流程，你现在已经可以在AstrBot中使用DeepSeek系列模型处理各类任务。下一步你可以：

1. 访问AstrBot官方文档学习消息平台、技能、插件、MCP的进阶配置；
2. 查看awesome-deepseek-agent获取更多DeepSeek Agent的使用案例与最佳实践；
3. 若遇到问题可前往AstrBot GitHub仓库提交Issue反馈，或加入社区交流群寻求帮助。