跳转到内容
ZeoKeel Wiki

快速开始

这一页把「一台空机器」变成「能发出第一条消息」，分角色给出路径、可照抄的命令与判据。每一节都给出可自查的判据；卡住时先看本页的「第一小时常见问题」一节。

先选你的路径

Section titled “先选你的路径”
你是怎么开始你要先准备什么
企业员工向管理员要企业访问地址，打开 https://<企业域名>/ 下载对应平台安装包（也可以直接找同事拷安装包）管理员给你的账号与密码；一个项目目录作为工作区
企业管理员先按私有化部署把服务端跑起来；客户端安装包随服务端镜像发布，部署完成后由这台服务器对员工提供对外地址、证书模式、初始超管密码（见容器化部署的前提条件）
想先试用官方渠道的客户端安装包在服务端镜像里：取官方镜像包，一条命令导出三平台安装包（见下），在自己的机器上把服务端跑起来一台能装 Docker 的 Linux x64 机器，或一个愿意让你登录的测试服务端

客户端安装包从哪来

Section titled “客户端安装包从哪来”
平台安装包说明
Windows x64.exe（NSIS 安装程序）未签名，SmartScreen 可能提示「未知发布者」
macOS（Apple 芯片 / arm64）.dmg正式发布版已签名 + 公证；预发布版仅签名
Linux x64.AppImage授予执行权限后运行；企业交付面不含 deb

客户端安装包随服务端镜像发布（不单独挂在下载站），所以只有两个来源：

  1. 企业服务器（推荐）：部署完成后打开 https://<企业域名>/（门户页），页面上直接列出三平台下载入口；
  2. 官方镜像包（试用 / 单机）：从更新服务器或 GitHub Release 取官方镜像包，再解出安装包：
Terminal window
VER=<版本>        # 以 latest.json 里的 server.version 为准
# 正式渠道是 official，预发布渠道是 beta，按需替换
curl -fL -O "https://release.zeokeel.com/official/releases/${VER}/zeokeel-server-${VER}-amd64.zip"
curl -fL -O "https://release.zeokeel.com/official/releases/${VER}/SHA256SUMS"
sha256sum -c SHA256SUMS
unzip -p "zeokeel-server-${VER}-amd64.zip" image.tar | docker load
mkdir -p ./zeokeel-stack
docker run --rm -v "$PWD/zeokeel-stack:/out" -e ZEOKEEL_UNPACK_STACK=/out \
  "zeokeel-harness-server:${VER}"
ls -1 ./zeokeel-stack/client    # 三平台安装包 + CLIENT-RELEASE.json

判据：sha256sum -c 输出全部 OK；client/ 目录里出现三平台安装包与 CLIENT-RELEASE.json。没有 client/ 说明你用的不是正式发布包（本地自建的镜像不带客户端资产）。

完整说明见容器化部署与离线部署；安装包与清单的服务端侧判据见客户端分发与升级。

首次启动会发生什么

Section titled “首次启动会发生什么”
  1. 应用获取单实例锁（重复启动只会聚焦已有窗口，不会开出第二个进程）；
  2. 应用创建（或复用）固定 desktop profile，并在本机 127.0.0.1 上启动官方 DSH Web 界面——端口默认由系统随机分配，只监听回环；
  3. 主窗口加载这个本机页面。未登录时这一页就是登录页；登录成功后同一窗口直接切到应用界面，不需要手动刷新；
  4. 关闭窗口不是退出：窗口只是隐藏，本地服务继续跑（自动化任务照常触发）；要真正结束应用与本地服务，走托盘菜单的退出；
  5. 安装包已经包含 Electron、Node.js、pnpm 与固定版本的上游 DSH 依赖——不需要另行安装 Node.js、pnpm 或 DSH，应用也不修改系统全局 PATH 或 shell 配置。

判据：窗口出现登录页；托盘图标存在且右键菜单包含「打开 <产品名>」「导出诊断信息…」「退出」。

登录

Section titled “登录”

登录页分两步：先填服务端地址，再由服务端决定可用的登录方式。

  1. 服务端地址：填管理员给你的地址（示例 https://harness.example.com）。远程地址必须是 https，只有 localhost / 127.0.0.1 才允许 http；尾部斜杠会被自动归一。渠道包内置了服务端地址时，这一步会被预填并跳过；
  2. 登录方式：由服务端配置决定——本地账号（用户名 + 密码）、LDAP（目录账号 + 密码）、OIDC（点「使用浏览器登录」，在弹出的浏览器窗口里完成授权后此页自动继续）；
  3. internal（内网自签）模式：首次连接需要信任本部署的 Caddy 本地 CA，否则会停在「无法连接服务端」；
  4. 登录成功后客户端会向这台服务端拉取渠道内容、模型清单与账号信息；模型是否可用、单价与折扣、余额都由服务端决定。

登录失败时登录页会原样给出原因，按文案就能定位：

页面提示含义处置
无法连接服务端，请检查地址与网络地址写错、网络不通、证书不受信任（internal 模式未信任 Caddy 本地 CA）核对地址与证书；internal 模式先信任本地 CA
网络错误，请检查服务端地址后重试探测登录方式时请求失败（服务端重启、反代 502 等）确认服务端 /healthz 正常后重试
账号或密码错误凭据不对（LDAP / OIDC 也一样回到这一条）找管理员核对账号
登录尝试过于频繁，请稍后再试命中登录限流（失败计数按账号与来源 IP 分别计）等 5 分钟窗口过去再试
账号已被禁用，请联系管理员账号被禁用联系管理员
请先修改密码（改密页）管理员重置过你的密码，服务端要求下次登录先改密在改密页设置新密码后继续

退出登录会解除全部会话（连接器、浏览器与登录态一起清理）。想换一台服务端或换账号，直接从设置里退出后重新登录即可——客户端会整份丢弃上一台服务端的在飞状态。

本地 Web 端口

Section titled “本地 Web 端口”

本地 Harness 服务只监听 127.0.0.1，端口默认由系统随机分配（dsh-desktop.port: 0），避免与其他服务冲突。若某个界面插件依赖稳定 origin（localStorage 按 origin 隔离），可以固定端口：

dsh-desktop:
  port: 43189

端口必须是 0–65535 之间的整数（0 = 随机）。修改后应用会有序重启（先完整销毁当前运行时再拉起），不会在运行中的页面里热替换。

边界：固定端口已被占用时，本机服务监听失败，窗口无法加载。处置：把端口改回 0 或换一个空闲端口，然后重启应用。

四个核心入口

Section titled “四个核心入口”

登录之后，员工每天用的是这四个入口：

  1. 会话：新建会话时选择工作区（项目目录），然后直接对话。模型可调用的工具按权限门控逐次审批——写文件、跑命令、操作浏览器都要你点头；「只读 / 工作区内修改 / 完全权限」三档决定沙箱的可写范围。
  2. 能力中心：安装市场或组织里的技能与智能体（需要管理员授权），查看「我的」本地创作与上传审核状态。安装、更新、卸载都有确认与拒绝理由，不会静默处理。
  3. 连接器：把外部系统以 MCP 接入。管理员在管理后台按一条标准 MCP 配置（type + url，或 command/args/env）登记，客户端授权一次即可让模型调用其工具；OAuth 令牌会自动续期。
  4. 自动化任务：把高频工作交给官方 Schedule 到点提醒（单次 / 间隔 / 每日 / 每周 / cron + 提示词），投递回原会话；任务按账号隔离，执行记录在「自动化任务」里可查。

其余常驻能力同样在左侧入口里：内置浏览器（Agent 可接管，控制权只能由右下角按钮交接）、语音输入（输入框麦克风，本机识别、离线可用）、五轨记忆（确认制写入，项目轨按目录与 git 分支隔离）、应用中心（员工自建的 WASM 应用在独立窗口打开）。

第一小时常见问题

Section titled “第一小时常见问题”
现象判据处置
点了关闭，应用「不见了」进程仍在，托盘图标仍在关闭 = 隐藏到托盘；从托盘「打开 <产品名>」恢复，或从托盘「退出」真正结束
应用起不来、窗口空白固定端口被占用；或本地服务未起来把 dsh-desktop.port 改回 0 或换空闲端口后重启应用
登录卡在「连接中…」服务端地址不可达或证书不受信任在浏览器里打开 https://<企业域名>/healthz 确认服务端可用；internal 模式先信任本地 CA
登录后没有可用模型服务端的模型目录为空，或你的账号没有余额找管理员在管理后台配置模型与余额（模型与密钥都在服务端）
「检查更新」没有任何反应客户端未登录（没有更新源），或后台检查失败是静默的未登录时客户端不做任何外发更新检查；登录后用托盘菜单手动检查可看到结果
Windows 首次运行提示「未知发布者」安装包未签名属预期；先用镜像包同目录的 SHA256SUMS 校验，再运行
macOS 提示「未能验证开发者」包内没有公证票据预发布包仅签名；请使用正式发布的安装包
Linux 双击没反应AppImage 没有执行权限chmod +x 后运行
应用反复闪退有崩溃记录，但界面没机会显示运行安装后的程序并加 --export-diagnostics（不启动服务端，只打印诊断 ZIP 路径）；或从托盘「导出诊断信息…」
插件/预设没出现应用固定运行 desktop profile，改动要重启才进 Loader 组合重启应用；第三方插件写 ~/.zeokeel-harness/cordis.patch.yml（渠道不同则数据根不同）

算装好了的判据

Section titled “算装好了的判据”
#判据怎么判
1应用起来了托盘菜单可用，主窗口不是空白页
2登录成功窗口切到应用界面，设置 → 账户里能看到账号与服务端地址
3模型可用新会话能选到模型（清单来自服务端）
4会话可用选一个工作区，发出第一条消息并收到回复
5工具可用让模型写一个文件或跑一条命令：出现确认卡片，批准后执行；拒绝时模型能看到拒绝原因

相关

Section titled “相关”