Desktop 安装
本页说明如何安装和使用 Hagicode Desktop。它是官方桌面客户端,负责把默认本地安装流程与日常管理入口放到同一处。
推荐方式
macOS、Linux 以及不走商店的 Windows 用户,个人本地使用时推荐 Desktop:
- 首次启动引导会把下载与启动流程串起来
- Hagicode Server 的启动、停止与版本由程序统一管理
- 图形界面更方便查看状态与操作
- 内置版本管理,便于切换不同版本
- 默认数据留在本地,便于自行控制
Windows 用户请优先考虑 Microsoft Store 安装。
什么是 Hagicode Desktop
Hagicode Desktop 是 Hagicode 的官方桌面应用程序,支持 Windows、macOS 和 Linux。它负责下载、启动和管理本机的 Hagicode Server,并提供版本管理与日常操作入口。
主要优势
- 内置 .NET 运行时:运行 Hagicode Server 所需的
.NET已随 Desktop 提供,无需单独安装 - 服务管理:内置 Hagicode Server 管理,轻松启动和停止服务
- 版本切换:支持多版本管理,可在不同版本之间自由切换
- 本地运行:所有数据存储在本地,保护您的隐私
- 版本检测:自动检测可用的新版本
适用场景
这些场景可优先用 Desktop:
- 个人开发者希望在本地使用 Hagicode
- 希望数据和项目都留在自己机器上的用户
- 偏好图形界面、不想手写部署配置的用户
- 需要频繁切换不同版本的开发者
安装前准备
Desktop 不内置 Node.js,也不再提供内部的 Node 运行环境。它会使用系统 PATH 中的 node 与 npm,并把 Agent CLI 等托管包安装到本机 npm 的全局目录。开始之前请先准备:
| 依赖 | 要求 | 说明 |
|---|---|---|
| Node.js | 24 或更高版本 | 同时提供 npm,参见 安装 Node.js |
| Git | 任意当前稳定版本 | 启动时会检测;“新建项目”对话框里的“演示项目”需要用它克隆示例仓库,参见 安装 Git |
| Agent CLI | 至少一个,并已登录 | 向导只会列出本机已检测到的 CLI,参见 AI Agent CLI 安装 |
先在终端确认版本:
node --version # 需要 v24.0.0 或更高npm --versiongit --version装好之后再启动,或重启 Desktop
Desktop 在启动时读取系统 PATH。如果在 Desktop 已打开时才安装 Node.js 或 Git,请完全退出并重新启动 Desktop,再刷新依赖页面。
下载 Desktop
快速下载
Windows 用户推荐优先使用 Microsoft Store 安装;只有在您需要手动安装包、指定版本文件或 Store 不可用时,再使用下方的手动下载入口。
选择适合您操作系统的版本,直接下载安装程序:
下载列表加载失败时
如果这里暂时无法加载 Desktop 安装包列表,安装入口不会给出无效的下载链接,而是引导您前往官方版本历史页:index.hagicode.com/desktop/history。您可以在那里选择版本并下载安装包;也可以直接使用下方的 GitHub Releases。
其他获取方式
您还可以从以下渠道获取 Hagicode Desktop 安装程序:
- Windows 默认推荐:访问 Microsoft Store 安装 走官方商店分发渠道
- 官方发布页面:访问 Hagicode GitHub Releases 下载手动安装包
- 官方网站:访问 Hagicode 官网 获取下载链接与安装说明
选择正确的版本
根据您的操作系统选择对应的安装程序:
- Windows:优先使用 Microsoft Store;如需手动安装文件,再下载
.exe安装程序或.msix安装包 - macOS:下载
.dmg安装程序 - Linux:下载
.AppImage或.tar.gz安装包
系统要求
- Windows:Windows 10 或更高版本(64 位)
- macOS:macOS 10.15 或更高版本
- Linux:主流 Linux 发行版(Ubuntu 20.04+、Fedora 33+ 等)
需要自行准备的依赖
Desktop 已内置运行 Hagicode Server 所需的 .NET 运行时,并按当前支持的本地 SQLite 路径完成默认初始化,您无需单独安装 .NET。但 Node.js 24+ 与 Git 需要您自行安装,详见上文的安装前准备。
安装与启动提示
macOS Gatekeeper 提示
如果您已经将应用安装到默认路径 /Applications/Hagicode.app,但首次启动时看到”应用已损坏”、“无法打开”或类似 Gatekeeper 提示,通常是因为 macOS 为从互联网下载的应用附加了 com.apple.quarantine 隔离属性,而不是 Hagicode Desktop 安装向导本身出错。
您可以在终端执行以下命令。该命令需要管理员权限,会递归移除默认安装路径上应用的 quarantine 属性:
sudo xattr -dr com.apple.quarantine /Applications/Hagicode.app执行完成后,请重新启动 Hagicode Desktop。
运行 Desktop
下载完成后,打开安装程序或应用包完成安装,再启动 Hagicode Desktop。
网络要求
确保您的网络连接正常。Desktop 需要从互联网获取版本信息和 Hagicode Server 安装包;如果下载失败,请检查网络、代理或防火墙设置后重试。
首次启动引导
第一次打开 Desktop 时,会先进入 Desktop 自带的“首次使用引导”。它只负责把 Hagicode Server 装好并启动,依次包括:
- 选择语言:选择 Desktop 使用的语言。首次启动内置后端时,也会采用对应的默认语言。
- 欢迎:了解本次引导会完成的准备工作。
- 确认法律文档:确认当前版本的 EULA 与隐私政策,正式文档会在浏览器中打开阅读。
- 下载 Hagicode Server:下载最新的 Server 安装包并校验其摘要。
下载完成后回到 Desktop 首页,点击“启动 Hagicode 服务”即可启动 Hagicode Server,随后按首页提示打开 Web 界面。
步骤可能不完整
部分分发渠道(例如已随安装包提供 Server 的版本),或在版本更新后只需重新确认法律文档时,引导只会显示其中的部分步骤。
首次使用 Web 界面
首次进入 Web 界面后,会出现 初始化向导(与上面的 Desktop 首次使用引导是两件不同的事)。它会带您选择界面语言与主题、设置默认 Hagicoder、创建第一个项目。详细步骤请阅读:
版本管理
Hagicode Desktop 支持多版本管理,您可以在不同版本之间自由切换。

切换版本
- 打开 Hagicode Desktop
- 进入”版本管理”页面
- 打开”已下载版本”标签页
- 在已安装版本中找到要切换的版本
- 点击该版本右侧的”切换”按钮
- 等待切换完成
版本切换注意事项
- 切换版本会自动重启 Hagicode Server
- 确保在切换前保存所有工作
- 不同版本的项目配置可能会有差异
启动和停止服务
Hagicode Desktop 提供了简单的方式来管理 Hagicode Server 服务。
启动服务
在 Desktop 应用程序的首页,点击”启动 Hagicode 服务”按钮即可启动 Hagicode Server。

停止服务
要停止 Hagicode Server,点击首页的”停止服务”按钮。
服务状态
Desktop 应用程序会实时显示 Hagicode Server 的运行状态,包括:
- 服务状态(运行中/已停止)
- 服务端口号
- 当前版本信息
后续步骤
安装完成后,您可以继续以下步骤:
故障排除
安装失败
如果安装过程中遇到问题:
- 检查网络连接:确保能够访问互联网
- 检查磁盘空间:确保有足够的磁盘空间
- 以管理员身份运行:在 Windows 上,右键点击安装程序,选择”以管理员身份运行”
- 查看安装程序提示:记下安装程序给出的错误信息,提交问题时一并附上
找不到 Node.js、npm 或 Git
如果 Desktop 提示缺少 node、npm 或 git,或提示 Node.js 版本过低:
- 确认已安装:在终端运行
node --version、npm --version、git --version。Node.js 需要 24 或更高版本,安装方法见 安装 Node.js 与 安装 Git。 - 重启 Desktop:Desktop 在启动时读取系统
PATH。安装后请完全退出并重新启动 Desktop,再刷新依赖页面。 - 检查 PATH:在终端能运行但 Desktop 找不到时,通常是
PATH只在某个 shell 配置里生效(例如通过 nvm 或 fnm 在.bashrc/.zshrc中设置)。请改用系统级安装,或确保从能读到该PATH的环境启动 Desktop。 - 手动安装 CLI 包:Desktop 提示需要手动安装 CLI 包时,请在 Desktop 之外的终端执行它给出的命令,完成后回到 Desktop 刷新。关于外部 Node / npm 环境与
PATH的行为,见 Desktop 如何使用你的 Node 环境。
服务启动失败
如果 Hagicode Server 无法启动:
- 检查端口占用:Desktop 默认使用端口 36556(首页会显示当前实际端口),请确保它未被其他程序占用
- 检查防火墙设置:确保防火墙允许 Hagicode Server 访问网络
- 重启应用程序:尝试重启 Hagicode Desktop
- 查看日志:在 Desktop 应用程序中查看详细的错误日志
需要更多帮助?
如果您遇到此处未涵盖的问题:
- 查看 Desktop 的 GitHub Issues 寻找类似问题
- 访问我们的社区论坛寻求帮助
- 提交新的 Issue,详细描述您的问题,并附上系统版本、
node --version与 Desktop 日志
HagiCode
HagiCode 是面向项目开发的 AI 编码工作台:丰富、便捷的界面交互让规划、Agent 执行与项目工作更容易上手和跟进,带来更投入的开发体验。
丰富、便捷的界面交互,让规划、Agent 执行与项目工作更容易上手和跟进。
- 智能OpenSpec 工作流把意图转化为从提案、设计、任务到交付的可执行路径。
- 高效多 Agent 并行推进调研、实现与审阅,并支持多仓库变更和你熟悉的 Agent CLI。
- 有趣丰富、便捷的界面交互让规划、Agent 执行与项目工作更容易上手和跟进,带来更投入的开发体验。
下载 Windows 版
分享 HagiCode
让想法变成真正交付的软件。
HagiCode 是面向项目开发的 AI 编码工作台:用 OpenSpec 工作流规划变更,多 Agent 并行执行,再由 Hero Scenario 让进度一目了然,把想法变成真正交付的软件。
- 智能
- OpenSpec 工作流把意图变成从提案到交付的可执行路径。
- 高效
- 多 Agent 并行推进调研、实现与审阅。
- 有趣
- 丰富、便捷的界面交互,让规划、Agent 执行和项目工作更容易跟进。
© 2026 HagiCode | Powered By hagilight-starlight@0.22.0 | Branch: main | Commit: 7fbb6c5 | Built:

