安装与首次启动

企业版桌面端由企业管理员统一分发，或在企业下载页获取。安装包已经包含运行 Agent 所需的运行时，不需要单独安装 Node、Python 或模型客户端。

系统要求

平台	支持范围	安装包
macOS	Apple Silicon / Intel	.dmg
Windows	x64 / ARM64	.exe
Linux	x64 / ARM64	.AppImage、.deb、.rpm

建议预留至少 2 GB 磁盘空间用于客户端、运行时和任务产物。企业版数据默认保存在 ~/.zworkspace，与个人版 ZCode 的 ~/.zcode 分开。

安装

macOS

1. 打开企业分发的 .dmg 安装镜像。
2. 将澄宇AI工作台拖动到「Applications」文件夹。
3. 从启动台启动。如果企业分发的是未签名包，按 IT 部门的放行指引操作，不要从非企业渠道下载安装包。

Windows

1. 运行企业分发的 .exe 安装程序。
2. 按安装向导完成安装。
3. 从开始菜单或桌面快捷方式启动。关闭窗口默认最小化到托盘，定时任务和后台任务会继续运行；需要直接退出时，使用托盘菜单的「退出」。

Linux

1. 选择 .AppImage、.deb 或 .rpm 安装包。

2. AppImage 需要先添加可执行权限：

   chmod +x 澄宇AI工作台-*.AppImage

3. 双击或在终端运行。部分发行版需要额外安装 fuse 依赖。

首次启动与登录

首次启动会进入企业登录页。请向企业管理员获取以下信息：

• 企业标识：租户的短标识，例如 tech-corp。
• 账号：企业管理员创建的成员账号，通常是邮箱或工号。
• 初始密码：首次登录后按提示修改。

登录后客户端会自动拉取运行配置，包括企业模型网关地址、可用模型、积分额度和已授权的工作台资源。不需要填写个人 API Key，也不要把密钥写进项目文件。

选择工作区

登录后选择一个本地项目目录作为工作区。工作区是 Agent 读取文件、执行命令和查看 Git 状态的范围；不同工作区之间的会话、文件和权限相互隔离。

如果你只是想提问、起草文字或做一次性分析，可以选择「不在项目中工作」。这类对话不会绑定 Git 仓库，但 Agent 创建的文件仍会留在磁盘上，需要自行清理。

验证安装

完成登录后，建议用一个不会产生副作用的任务确认链路：

1. 在输入框输入「列出当前目录的文件，并说明项目使用什么包管理器」。
2. 确认 Agent 能读取工作区文件并返回结果。
3. 在模型菜单中确认企业已授权的模型可见。
4. 在用量页面确认本次调用产生了积分记录。

网络代理与证书

如果企业网络需要代理才能访问模型网关，在 设置 → 常规 中配置：

字段	说明
HTTP 代理	例如 http://127.0.0.1:7890。留空表示直连，不会自动读取 HTTP_PROXY 等系统环境变量。
代理例外	不走代理的主机名或域名后缀，用英文逗号分隔，例如 localhost,127.0.0.1,.corp.example.com。
自定义证书	企业安全网关签发根证书的 PEM 文件路径。这不是跳过证书校验，只放行证书链中包含该根证书的连接。

修改代理或证书后需要重启客户端生效。

更新

企业版从管理员配置的更新源检查更新。有新版本时，客户端提示下载并在重启后生效；强制更新策略由企业后台控制。不要从第三方渠道替换安装目录中的运行时文件，否则可能破坏签名校验和更新链路。

故障排查

现象	先检查
登录提示企业不存在	企业标识是否输错；账号是否属于该企业；租户是否已开通
登录成功但模型列表为空	管理员是否给成员分配了模型；企业网关是否健康；运行配置是否已刷新
提示积分为 0	本月额度是否用完；管理员是否调整了额度；是否需要申请临时积分包
客户端无法联网	代理地址、代理例外、根证书；留空代理不会继承系统环境变量
安装包无法打开	是否为企业分发版本；macOS 是否被隔离属性拦截；Windows 是否被安全软件拦截
更新失败	更新源是否可达；磁盘空间是否足够；是否有安全软件锁定安装目录

更多 Linux/WSL 问题见 Linux / WSL 排查指南。

完成检查

• 客户端安装完成，版本号与企业公告一致。
• 使用企业标识和成员账号登录成功。
• 模型菜单中能看到已授权模型。
• 完成一次只读任务，并看到积分记录。
• 代理、证书和更新源按企业网络要求配置完成。