---
title: "批量部署 Halo：系统要求、安装包与预配置"
description: "给团队或公司的多台电脑部署 Halo：先核对系统要求和安装包，再了解 Windows 命令执行环境、每位用户第一次打开看到什么，以及哪些设置能提前定好。"
type: "how-to"
audience: ["admin"]
platforms: ["macos", "windows", "linux"]
related: ["getting-started/install", "advanced/updates", "advanced/security", "server/"]
lang: "zh-CN"
canonical: "https://hello-halo.cc/docs/advanced/deployment.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# 批量部署

给团队或公司的多台电脑部署 Halo：先核对系统要求和安装包，再了解 Windows 命令执行环境、每位用户第一次打开看到什么，以及哪些设置能提前定好。

分发安装包、设置环境变量都在 Halo 之外完成，这些事 Halo 帮不上。

## 开始之前 {#before-you-start}

- 每台电脑都按 [安装 Halo](https://hello-halo.cc/docs/getting-started/install.html) 的步骤装一次。本页只补充管理员关心的部分：要求、安装包的特点、能提前定好什么。
- 上线前先过一遍 [上线前检查](#before-rollout)。Halo 的 AI 执行工具不会逐次确认，这一点要先让使用者知道。
- 多人共用一个 Halo、或没有桌面的服务器场景，看 [Halo Server](#halo-server)。

## 系统要求 {#requirements}

| 平台 | 要求 | 说明 |
|---|---|---|
| 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（安装包自带，见 [下文](#windows-git-bash)） | 系统自带的 shell |

## 安装包 {#installers}

| 平台 | 文件 | 签名 | 安装方式 |
|---|---|---|---|
| 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 卸载不会删除用户数据，重新安装后工作区、会话和数字人都还在。数据位置见 [数据与配置位置](https://hello-halo.cc/docs/advanced/config-paths.html)。
- **没有静默安装参数**：Halo 没有提供、也没有说明静默或无人值守安装的命令行参数。本页不推荐任何未经验证的安装开关。
- **macOS 不用绕过 Gatekeeper**：官方版本已公证，打开时只有普通的「从互联网下载」提示。只有自己构建或来源不明的副本才会提示「无法验证开发者」。

## Windows 的命令执行环境 {#windows-git-bash}

AI 在 Windows 上运行 git、npm、pip 这类命令需要 Git Bash。Halo 第一次启动时按这个顺序找：

1. 环境变量 `CLAUDE_CODE_GIT_BASH_PATH` 指向的 `bash.exe`
2. Halo 自己装好的那一份
3. 系统里已安装的 Git for Windows（`Program Files`、`Program Files (x86)` 或当前用户的 `Programs` 目录）
4. `PATH` 里能找到的 `git.exe` 旁边的 bash

都找不到时，Halo 先显示「需要首次设置」，**自动下载并安装**（标着「推荐」）默认选中：

- 安装程序里已经带了一份便携版 Git（PortableGit），所以这一步是在本机离线解压，不需要外网。只有这份文件缺失时，Halo 才会去下载镜像拉取。
- 使用者选 **跳过,稍后手动安装** 会进入「功能受限模式」：AI 只能对话，不能运行系统命令，会话页顶部一直显示「未安装命令执行环境,AI 无法运行系统命令」，点 **立即安装** 可以补装。

如果公司电脑已经统一装了 Git for Windows，Halo 会直接用它，使用者不会看到这个页面。具体画面见 [安装 Halo › Windows：安装命令执行环境](https://hello-halo.cc/docs/getting-started/install.html#git-bash)。

## 每位用户第一次打开看到什么 {#first-run}

每台电脑、每个用户第一次打开 Halo，都会经过同样几步。Halo 没有提供替使用者跳过这些步骤的办法：

1. **只有 Windows 且没找到 Git Bash 时**：「需要首次设置」（见上一节）。
2. **「让我们开始设置」**：选 **语言** 和 **主题**，点 **继续**。语言默认跟随系统语言，主题默认 **跟随系统**。
3. **「欢迎使用 Halo」 ›「选择一种方式开始」**：最上面是推荐的登录方式，下面是 **或选择其他方式** 里的其他登录方式和 **自定义 API**。使用者也可以点 **暂时跳过**（「稍后在设置中配置你的 AI」）先进入首页，之后在 **设置 › AI 模型** 里再配；跳过后下次启动不会再出现这个向导。
4. 进入首页。全新安装的官方版本还会在 **Halo 工作区** 里自动建好一位入门数字人「Halo AI 数字人模板」，在 **数字人 › 我的数字人** 里能看到。它没有设置任何触发器，可以改名、修改、绑定机器人，也可以卸载。

各登录方式的区别和怎么选，见 [连接 AI 模型](https://hello-halo.cc/docs/getting-started/setup-ai.html)。如果公司有统一的模型网关，让使用者在第 3 步选 **自定义 API** 并填网关地址和密钥，见 [模型网关与代理](https://hello-halo.cc/docs/advanced/gateway-and-proxy.html)。

::: info
公司提供的 Halo 可能显示不同的登录选项。
:::

## 能提前定好什么 {#pre-configure}

### 官方版本 {#official-build}

从官网下载的 Halo 只有下面这些能在部署时统一设置，其余设置都由每位用户在 Halo 里自己完成：

| 想定的事 | 怎么做 | 说明 |
|---|---|---|
| 数据文件夹放在哪 | 启动 Halo 前设置环境变量 `HALO_DATA_DIR` | 默认是用户主目录下的 `.halo`。设置后数据和日志（`logs` 子文件夹）都放到这个目录，`~` 会被展开成用户主目录。应用数据文件夹（AI 浏览器的登录状态、默认的 Claude 配置目录、Windows 上的 Git Bash）仍在系统默认位置，见 [数据与配置位置](https://hello-halo.cc/docs/advanced/config-paths.html#app-data-folder)。没有界面入口，Halo 里也不能挪动数据文件夹。每位用户用自己的文件夹，不要多人共用 |
| Windows 用哪个 Git Bash | 预装 Git for Windows，或设置环境变量 `CLAUDE_CODE_GIT_BASH_PATH` 指向 `bash.exe` | 找到后不再显示「需要首次设置」 |
| 网络代理 | 使用系统代理设置 | **设置 › 系统 › 代理** 留空时，Halo 自动沿用系统代理（含 PAC）。手动填写代理和例外地址见 [模型网关与代理](https://hello-halo.cc/docs/advanced/gateway-and-proxy.html) |

Halo 没有提供可供管理员下发的配置文件或策略模板。

### 公司定制的 Halo {#company-builds}

::: info 公司定制版本
公司可以基于 Halo 构建自己的版本，在构建时预先设定下面这些内容。这些都在构建时决定，使用者在 Halo 里看不到、也改不了对应的配置；从官网下载的 Halo 不包含这些预设。
:::

| 可以预设的内容 | 使用者看到的效果 |
|---|---|
| 登录方式 | 第一次打开和 **设置 › AI 模型** 里只出现公司选定的登录方式 |
| 预设的模型服务 | **设置 › AI 模型** 里出现「预设API」分组，固定好网关地址，使用者只填密钥 |
| IM 机器人的权限默认值 | 新建的机器人默认打开 **权限控制**，访客默认能用的工具由公司定好 |
| AI 浏览器的网站策略 | 只允许或禁止访问某些网站、指定主页；允许的话，**设置 › 系统** 里出现「浏览器允许的站点」，使用者可以自己补充 |
| 商店来源 | **设置 › 应用商店** 里的来源可以被换成公司自己的商店、隐藏或锁定开关，见 [私有商店](https://hello-halo.cc/docs/advanced/private-store.html) |
| 更新来源 | 从公司自己的地址获取更新 |
| 凭据加密 | 把 API Key 和令牌加密后再保存。官方版本不加密，以明文保存在 `~/.halo/config.json` 里 |
| 远程访问和扩展的限制 | 关闭远程访问的互联网访问；禁止通过远程连接安装 MCP 服务器；禁止特定的 MCP 启动命令 |
| 内置网关和数字人 | 预先填好 [联邦网关](https://hello-halo.cc/docs/advanced/federation-gateway.html) 地址，或随安装包附带数字人 |
| 数据文件夹名 | 使用另一个文件夹名（例如 `~/.halo-<名称>`），和官方版本的数据互不影响 |

## 部署后的更新 {#updates}

- Halo 会自己检查并在后台下载新版本：启动 5 秒后检查一次，之后每 60 分钟一次，电脑唤醒时也会检查。准备好后弹出提示，使用者点 **立即重启**（Windows 走安装程序时是 **立即安装**）。
- 官方版本从 GitHub 发布页获取稳定版更新，界面里没有切换更新渠道的开关。
- Windows 从 3.0 起在后台准备更新，重启几秒就完成；新版本启动失败会自动退回旧版本。从 2.x 升级到 3.0 这一次仍然要跑安装程序。
- 发布方标为强制更新的版本，使用者不能推迟。

完整说明见 [更新 Halo](https://hello-halo.cc/docs/advanced/updates.html)。

## 上线前检查 {#before-rollout}

推给使用者之前，先确认这几件事已经讲清楚：

- AI 运行命令、改文件、删文件**不会逐次确认**，工作区只指向愿意让 AI 改动的文件夹。
- 官方版本的 API Key 和令牌以明文保存在 `~/.halo/config.json` 里（界面中一律显示为 `***`），这个文件夹不要放进网盘或公开备份。
- 打开 **开发者模式** 后，`http-raw.log` 会记录完整的请求，包括密钥。排查完要关掉。
- 拿到远程访问密码的人可以完全控制那台电脑上的 Halo。

逐项核对见 [安全、隐私与数据流 › 管理员检查清单](https://hello-halo.cc/docs/advanced/security.html#checklist)。

## 多人共用或服务器部署 {#halo-server}

想让多人通过浏览器或 Android 应用使用同一个 Halo，或者把数字人当作后端服务，用 [Halo Server](https://hello-halo.cc/docs/server/)：它是同一个 Halo 在 Linux x64 容器里无界面运行，用环境变量配置。Halo Server 只支持 **自定义 API** 接入模型，没有自动更新，**系统**、**高级**、**远程访问** 设置也不显示。

## 遇到问题 {#troubleshooting}

### Windows 拦截了安装程序或 Halo

Halo 的 Windows 安装程序没有数字签名。SmartScreen 提示时点 **更多信息 › 仍要运行**。被公司杀毒软件隔离时，请安全团队把安装程序和 Halo 的安装目录加入白名单，再重新安装。

### 每台 Windows 电脑都出现「需要首次设置」

说明这台电脑上没找到 Git Bash。保持 **自动下载并安装**，它会从安装包里离线解压，不需要外网。想彻底不出现，就预装 Git for Windows，或设置 `CLAUDE_CODE_GIT_BASH_PATH`。

### 提示「已有另一个版本在运行」

同一份数据只能有一个 Halo 在运行，正式版和预览版共用同一个数据文件夹。按提示退出另一个 Halo（可能在托盘里），再打开。

### 提示「数据来自更新的版本」

这台电脑上的数据被更新的 Halo 版本打开过，旧版本为了不损坏数据拒绝启动。装回较新的版本即可；部署时让所有电脑使用同一个或更新的版本，不要降级。

## 下一步 {#next-steps}

- [安全、隐私与数据流](https://hello-halo.cc/docs/advanced/security.html)：上线前把数据流向和权限讲给安全团队听
- [更新 Halo](https://hello-halo.cc/docs/advanced/updates.html)：了解各平台的更新方式和强制更新
- [Halo Server 快速开始](https://hello-halo.cc/docs/server/)：多人共用或无桌面环境时的部署方式