AstrBot Desktop 是面向本地桌面使用的 AstrBot 打包发行版。它内置 WebUI、后端运行时和桌面壳层，适合希望快速安装、在本机使用 ChatUI、插件与知识库能力的用户；如果你计划长期运行在服务器上，更推荐使用上游 AstrBot 的源码、Docker 或面板部署方式。

适用场景

• 想在 Windows、macOS、Linux 上直接安装 AstrBot，不想先配置完整命令行环境。
• 主要在本机使用 ChatUI、插件市场、知识库等能力。
• 希望把数据保存在本地目录中，便于备份、迁移和故障排查。
• 需要 stable / nightly 两种发布通道，日常使用与抢先体验都方便。

主要特点

1. 开箱即用的桌面安装体验，默认集成 WebUI 与后端运行时。
2. 与上游 AstrBot 生态保持兼容，适合本机体验 ChatUI、插件和常见工作流。
3. 默认使用独立本地数据目录，配置、插件和日志更容易管理。
4. 提供 stable / nightly 通道，适合稳定使用或提前体验最新改动。
5. 支持迁移到源码部署，也支持从源码部署迁移回桌面端。

一键安装

如果你只想使用软件，不需要本地构建，请直接从 Releases 下载对应系统的安装包。

• Stable：适合大多数用户日常使用。
• Nightly：基于较新的上游改动自动构建，适合提前体验新功能或修复。
• 下载时请按操作系统与 CPU 架构选择对应安装包。

数据与配置位置

桌面端默认把 AstrBot 根目录放在用户主目录下的 .astrbot：

• macOS / Linux：~/.astrbot
• Windows：C:\Users\<用户名>\.astrbot

常见目录如下：

路径	说明
data/config/	配置文件目录
data/plugins/	插件目录
data/plugin_data/	插件数据目录
data/knowledge_base/	知识库数据
data/webchat/	WebChat 相关数据
logs/	桌面端与后端日志

如果你需要在桌面端和源码部署之间迁移数据，请先阅读 docs/data-migration.md。

更新与版本通道

• stable：面向日常使用，默认推荐。
• nightly：更接近上游最新提交，适合测试新功能或修复。
• Windows、macOS 和 Linux AppImage 场景通常可以直接使用桌面端更新入口；部分 Linux 安装方式会退化为手动下载安装。

常见问题

适合部署在服务器上吗？

不推荐。AstrBot Desktop 更适合本地桌面使用和个人工作流体验；如果你要长期稳定运行在服务器上，更建议使用上游 AstrBot 的源码、Docker 或面板部署方式。

如何从局域网内其他设备访问 WebUI？

桌面端默认只监听 127.0.0.1:6185，仅允许本机访问。如果确认需要在同一局域网内访问，可以在 AstrBot 命令配置中把 dashboard host 改为 0.0.0.0。

配置文件路径：

~/.astrbot/data/cmd_config.json

Windows 对应路径通常是：

C:\Users\<用户名>\.astrbot\data\cmd_config.json

写入以下内容：

{
  "dashboard": {
    "host": "0.0.0.0",
    "port": 6185
  }
}

保存后完全退出并重新启动 AstrBot Desktop，然后在其他设备访问：

http://<运行 AstrBot Desktop 的主机内网 IP>:6185/

如需恢复默认本机访问，可把 dashboard.host 改回 127.0.0.1 后重启应用。

环境变量仍可作为高级覆盖项，且优先级高于 cmd_config.json：

ASTRBOT_DASHBOARD_HOST=0.0.0.0
ASTRBOT_DASHBOARD_PORT=6185

开启局域网访问前，请确认系统防火墙允许端口 6185，并不要在不可信网络或公网环境暴露该端口。

macOS 提示“应用已损坏”或无法打开

如果你是从网络下载的安装包，macOS 可能会给应用打上 quarantine 标记。可执行：

xattr -dr com.apple.quarantine /Applications/AstrBot.app

然后重新启动应用。如果应用不在 /Applications，请替换为实际路径。

为什么某些 MCP 工具提示缺少 node、npx 或 uvx？

部分 MCP 工具需要依赖系统里的 node / npx / uvx。这类依赖不由桌面端安装包统一提供，需要你在系统里额外安装。

• Node.js 安装文档：https://nodejs.org/
• uv 安装文档：https://docs.astral.sh/uv/getting-started/installation/

安装后可自行检查：

node -v
npm -v
npx -v
uvx --version

进阶文档

• docs/data-migration.md：桌面端与源码部署之间的数据迁移说明。
• docs/development.md：本地构建、维护命令、版本同步与发布说明。
• docs/environment-variables.md：环境变量清单。
• docs/architecture.md：当前桌面端架构说明。
• docs/repository-structure.md：仓库目录职责总览。

问题反馈

如需安装帮助，或想反馈问题与建议，可以通过以下方式联系：

• GitHub Issues：https://github.com/AstrBotDevs/AstrBot-desktop/issues
• QQ 群：1060046189

开源协议

本项目采用 AGPL-3.0 开源协议，协议全文见 LICENSE。