批量部署
给团队或公司的多台电脑部署 Halo：先核对系统要求和安装包，再了解 Windows 命令执行环境、每位用户第一次打开看到什么，以及哪些设置能提前定好。
分发安装包、设置环境变量都在 Halo 之外完成，这些事 Halo 帮不上。
开始之前
- 每台电脑都按 安装 Halo 的步骤装一次。本页只补充管理员关心的部分：要求、安装包的特点、能提前定好什么。
- 上线前先过一遍 上线前检查。Halo 的 AI 执行工具不会逐次确认，这一点要先让使用者知道。
- 多人共用一个 Halo、或没有桌面的服务器场景，看 Halo Server。
系统要求
| 平台 | 要求 | 说明 |
|---|---|---|
| macOS | macOS 12 及以上，Apple 芯片和 Intel 芯片 | 更旧的 Mac 继续使用 Halo 2.x |
| Windows | Windows 10 及以上，仅 64 位（x64） | 没有 ARM64 版 |
| Linux | 64 位（x64），glibc 2.34 及以上（如 Ubuntu 22.04、Debian 12 或更新） | 只有 AppImage，没有 .deb / .rpm；更旧的系统继续使用 2.1.15 |
| Android | Android 7.0 及以上 | 只是远程客户端，连接某台电脑上运行的 Halo，本身不运行 AI |
| iOS | — | 没有 iOS 应用 |
各平台桌面版的差别：
| macOS | Windows | Linux | |
|---|---|---|---|
| 关闭窗口 | 收到后台，继续运行 | 收到托盘，继续运行 | 直接退出，后台工作停止 |
| AI 终端 | 有 | 有 | 没有 |
| 开机自动启动 | 可用 | 可用 | 不起作用 |
| AI 运行命令用的 shell | 系统自带的 shell | Git Bash（安装包自带，见 下文） | 系统自带的 shell |
安装包
| 平台 | 文件 | 签名 | 安装方式 |
|---|---|---|---|
| macOS | .dmg 和 .zip，分 arm64（Apple 芯片）和 x64（Intel）两种 | 官方版本有 Apple Developer ID 签名并经过公证 | 把 Halo 拖进「应用程序」文件夹 |
| Windows | Halo-Setup-<版本号>.exe（NSIS 安装程序） | 没有数字签名 | 带界面的安装向导，按用户安装，可以更改安装位置 |
| Linux | Halo-<版本号>.AppImage | — | 加上可执行权限后直接运行 |
<版本号> 换成实际版本，例如 3.0.4。
部署时要注意：
- Windows 会提示风险：安装程序没有签名，第一次运行会出现 SmartScreen 的「Windows 已保护你的电脑」，要点 更多信息 › 仍要运行。公司的杀毒软件或终端管控也可能拦截，需要提前把 Halo 的安装程序和安装目录加入白名单。
- Windows 是按用户安装：只装给当前登录的 Windows 账户，同一台电脑上的其他账户要各自安装。
- 覆盖安装会关掉正在运行的 Halo：Windows 安装程序开始前会强制结束当前用户正在运行的 Halo 及其子进程，正在跑的对话和数字人会中断。最好在使用者不忙的时候装。
- 卸载保留数据：Windows 卸载不会删除用户数据，重新安装后工作区、会话和数字人都还在。数据位置见 数据与配置位置。
- 没有静默安装参数：Halo 没有提供、也没有说明静默或无人值守安装的命令行参数。本页不推荐任何未经验证的安装开关。
- macOS 不用绕过 Gatekeeper：官方版本已公证，打开时只有普通的「从互联网下载」提示。只有自己构建或来源不明的副本才会提示「无法验证开发者」。
Windows 的命令执行环境
AI 在 Windows 上运行 git、npm、pip 这类命令需要 Git Bash。Halo 第一次启动时按这个顺序找：
- 环境变量
CLAUDE_CODE_GIT_BASH_PATH指向的bash.exe - Halo 自己装好的那一份
- 系统里已安装的 Git for Windows（
Program Files、Program Files (x86)或当前用户的Programs目录） PATH里能找到的git.exe旁边的 bash
都找不到时，Halo 先显示「需要首次设置」，自动下载并安装（标着「推荐」）默认选中：
- 安装程序里已经带了一份便携版 Git（PortableGit），所以这一步是在本机离线解压，不需要外网。只有这份文件缺失时，Halo 才会去下载镜像拉取。
- 使用者选 跳过,稍后手动安装 会进入「功能受限模式」：AI 只能对话，不能运行系统命令，会话页顶部一直显示「未安装命令执行环境,AI 无法运行系统命令」，点 立即安装 可以补装。
如果公司电脑已经统一装了 Git for Windows，Halo 会直接用它，使用者不会看到这个页面。具体画面见 安装 Halo › Windows：安装命令执行环境。
每位用户第一次打开看到什么
每台电脑、每个用户第一次打开 Halo，都会经过同样几步。Halo 没有提供替使用者跳过这些步骤的办法：
- 只有 Windows 且没找到 Git Bash 时：「需要首次设置」（见上一节）。
- 「让我们开始设置」：选 语言 和 主题，点 继续。语言默认跟随系统语言，主题默认 跟随系统。
- 「欢迎使用 Halo」 ›「选择一种方式开始」：最上面是推荐的登录方式，下面是 或选择其他方式 里的其他登录方式和 自定义 API。使用者也可以点 暂时跳过（「稍后在设置中配置你的 AI」）先进入首页，之后在 设置 › AI 模型 里再配；跳过后下次启动不会再出现这个向导。
- 进入首页。全新安装的官方版本还会在 Halo 工作区 里自动建好一位入门数字人「Halo AI 数字人模板」，在 数字人 › 我的数字人 里能看到。它没有设置任何触发器，可以改名、修改、绑定机器人，也可以卸载。
各登录方式的区别和怎么选，见 连接 AI 模型。如果公司有统一的模型网关，让使用者在第 3 步选 自定义 API 并填网关地址和密钥，见 模型网关与代理。
INFO
公司提供的 Halo 可能显示不同的登录选项。
能提前定好什么
官方版本
从官网下载的 Halo 只有下面这些能在部署时统一设置，其余设置都由每位用户在 Halo 里自己完成：
| 想定的事 | 怎么做 | 说明 |
|---|---|---|
| 数据文件夹放在哪 | 启动 Halo 前设置环境变量 HALO_DATA_DIR | 默认是用户主目录下的 .halo。设置后数据和日志（logs 子文件夹）都放到这个目录，~ 会被展开成用户主目录。应用数据文件夹（AI 浏览器的登录状态、默认的 Claude 配置目录、Windows 上的 Git Bash）仍在系统默认位置，见 数据与配置位置。没有界面入口，Halo 里也不能挪动数据文件夹。每位用户用自己的文件夹，不要多人共用 |
| Windows 用哪个 Git Bash | 预装 Git for Windows，或设置环境变量 CLAUDE_CODE_GIT_BASH_PATH 指向 bash.exe | 找到后不再显示「需要首次设置」 |
| 网络代理 | 使用系统代理设置 | 设置 › 系统 › 代理 留空时，Halo 自动沿用系统代理（含 PAC）。手动填写代理和例外地址见 模型网关与代理 |
Halo 没有提供可供管理员下发的配置文件或策略模板。
公司定制的 Halo
公司定制版本
公司可以基于 Halo 构建自己的版本，在构建时预先设定下面这些内容。这些都在构建时决定，使用者在 Halo 里看不到、也改不了对应的配置；从官网下载的 Halo 不包含这些预设。
| 可以预设的内容 | 使用者看到的效果 |
|---|---|
| 登录方式 | 第一次打开和 设置 › AI 模型 里只出现公司选定的登录方式 |
| 预设的模型服务 | 设置 › AI 模型 里出现「预设API」分组，固定好网关地址，使用者只填密钥 |
| IM 机器人的权限默认值 | 新建的机器人默认打开 权限控制，访客默认能用的工具由公司定好 |
| AI 浏览器的网站策略 | 只允许或禁止访问某些网站、指定主页；允许的话，设置 › 系统 里出现「浏览器允许的站点」，使用者可以自己补充 |
| 商店来源 | 设置 › 应用商店 里的来源可以被换成公司自己的商店、隐藏或锁定开关，见 私有商店 |
| 更新来源 | 从公司自己的地址获取更新 |
| 凭据加密 | 把 API Key 和令牌加密后再保存。官方版本不加密，以明文保存在 ~/.halo/config.json 里 |
| 远程访问和扩展的限制 | 关闭远程访问的互联网访问；禁止通过远程连接安装 MCP 服务器；禁止特定的 MCP 启动命令 |
| 内置网关和数字人 | 预先填好 联邦网关 地址，或随安装包附带数字人 |
| 数据文件夹名 | 使用另一个文件夹名（例如 ~/.halo-<名称>），和官方版本的数据互不影响 |
部署后的更新
- Halo 会自己检查并在后台下载新版本：启动 5 秒后检查一次，之后每 60 分钟一次，电脑唤醒时也会检查。准备好后弹出提示，使用者点 立即重启（Windows 走安装程序时是 立即安装）。
- 官方版本从 GitHub 发布页获取稳定版更新，界面里没有切换更新渠道的开关。
- Windows 从 3.0 起在后台准备更新，重启几秒就完成；新版本启动失败会自动退回旧版本。从 2.x 升级到 3.0 这一次仍然要跑安装程序。
- 发布方标为强制更新的版本，使用者不能推迟。
完整说明见 更新 Halo。
上线前检查
推给使用者之前，先确认这几件事已经讲清楚：
- AI 运行命令、改文件、删文件不会逐次确认，工作区只指向愿意让 AI 改动的文件夹。
- 官方版本的 API Key 和令牌以明文保存在
~/.halo/config.json里（界面中一律显示为***），这个文件夹不要放进网盘或公开备份。 - 打开 开发者模式 后，
http-raw.log会记录完整的请求，包括密钥。排查完要关掉。 - 拿到远程访问密码的人可以完全控制那台电脑上的 Halo。
逐项核对见 安全、隐私与数据流 › 管理员检查清单。
多人共用或服务器部署
想让多人通过浏览器或 Android 应用使用同一个 Halo，或者把数字人当作后端服务，用 Halo Server：它是同一个 Halo 在 Linux x64 容器里无界面运行，用环境变量配置。Halo Server 只支持 自定义 API 接入模型，没有自动更新，系统、高级、远程访问 设置也不显示。
遇到问题
Windows 拦截了安装程序或 Halo
Halo 的 Windows 安装程序没有数字签名。SmartScreen 提示时点 更多信息 › 仍要运行。被公司杀毒软件隔离时，请安全团队把安装程序和 Halo 的安装目录加入白名单，再重新安装。
每台 Windows 电脑都出现「需要首次设置」
说明这台电脑上没找到 Git Bash。保持 自动下载并安装，它会从安装包里离线解压，不需要外网。想彻底不出现，就预装 Git for Windows，或设置 CLAUDE_CODE_GIT_BASH_PATH。
提示「已有另一个版本在运行」
同一份数据只能有一个 Halo 在运行，正式版和预览版共用同一个数据文件夹。按提示退出另一个 Halo（可能在托盘里），再打开。
提示「数据来自更新的版本」
这台电脑上的数据被更新的 Halo 版本打开过，旧版本为了不损坏数据拒绝启动。装回较新的版本即可；部署时让所有电脑使用同一个或更新的版本，不要降级。
下一步
- 安全、隐私与数据流：上线前把数据流向和权限讲给安全团队听
- 更新 Halo：了解各平台的更新方式和强制更新
- Halo Server 快速开始：多人共用或无桌面环境时的部署方式