快速开始
从零到聊上天最短的路：安装、备齐凭据、在应用里配置、开聊。本页全部在安装向导和应用设置里完成，不需要终端。
1. 下载与安装
要装的是两样东西，彼此独立。
| 得到什么 | 用来做什么 | |
|---|---|---|
| 客户端 | 桌面窗口 | 在桌面应用里聊天 |
| Agent | 引擎，以及本机 Session 服务 | 一切聊天，无论用哪种窗口 |
在一台电脑上聊天两样都要：只装客户端没有引擎，只装 Agent 没有桌面窗口。最省事的顺序是先装客户端 —— 首次启动它会提议在同一台电脑上安装引擎，接受之后本页大部分内容就已经完成了。
客户端（窗口）
- 打开下载页，选你的平台。
- macOS —— 打开
.dmg，把 Xiaohe 拖进「应用程序」。首次可能要右键 → 打开。 - Linux ——
sudo dpkg -i Xiaohe_*_amd64.deb。 - Windows —— 运行
Xiaohe_*_x64-setup.exe。若出现 SmartScreen，选更多信息 → 仍要运行。
安装无需账号。
Agent（引擎）
支持 macOS Apple Silicon、Linux x86_64、Windows x86_64。
-
Windows —— 下载 xiaohe-installer.exe 并双击。向导依次走完：语言 → 运行时 → Node.js → Claude（CLI 与 SDK，约 250MB）→ DeepSeek API key → 桌面客户端 → 总览 → 安装。出现 UAC 提示时确认。
-
macOS 与 Linux —— 在终端运行：
curl -fsSL https://download.xiaohe.team/xiaohe-agent/install.sh | bash脚本会安装引擎并询问是否安装桌面客户端。问到“Issue a local Session…”时选是，聊天密钥会替你写好。
Windows 向导还会顺带问 DeepSeek key、替你装客户端。macOS 与 Linux 上则稍后到应用里设置模型，见第 3 步。
2. 账号与凭据
应用可能问你要的东西都在这里。安装前什么都不需要，哪个设置页要了再去办哪一个。
| 凭据 | 从哪里来 | 什么时候需要 |
|---|---|---|
| 模型服务商 key（DeepSeek、Kimi……） | 服务商自己的平台，如 DeepSeek 开放平台 | 永远需要 —— 没有模型聊天不会出话。模型网关是另一条不需要服务商账号的路 |
Session 密钥 xh_ses_… | 由 Session 服务自己签发 —— 本机安装会自动写进应用 | 每个窗口、每种形态。登录同一账号的设备会经账号同步拿到这把密钥 |
许可证 xh_lic_… | 账号中心 —— 邮箱注册、充值、领取授权 | 桌面专业版功能。新装带约七天试用 |
云钥匙 xh_cld_… | 账号中心，与许可证在一起 | 云端服务 —— MCP、DERP 与模型网关 |
| 私有网络 | 在应用内加入，无需安装额外应用 | 只有要连另一台机器上的 Session 时才需要 |
在账号中心用邮箱注册；在那里充值的余额同时供给模型网关与专业版购买。在 设置 → 账号 登录后，这台电脑和手机就连到同一账号：Session 密钥随之同步，你的电脑之间也能互相找到。
3. 登录、填入、启用服务器
打开桌面应用，按下面的顺序过一遍设置页。这个顺序就是解除聊天阻塞的顺序。
- 登录。 在 设置 → 账号 用第 2 步的账号登录。这一步把应用连上你的账号 —— Session 密钥同步到你的其他设备，电脑之间也能互相找到。
- 许可证与云钥匙。 在 设置 → 授权与密钥 贴上许可证
xh_lic_…和云钥匙xh_cld_…（有就贴）。两样都没有也能聊天 —— 它们只关专业版功能与云端服务。 - 给它一个模型。 在 设置 → 助手 选一家服务商并贴 key。没有模型时聊天窗口能打开，但永远不出话。
- 启动本机服务。 在 设置 → 服务器 点启动本机服务。它会在本机安装并启动 Session 服务，并替你写好 Session 密钥 —— 什么都不用贴。若要连别处的 Session，改用添加远程服务器，填那台机器的地址和密钥。
- 开聊。 新建会话，发一条消息。
4. 设置标签页
桌面应用的设置就是几个标签页。其中两个是聊上天的必需项，其余可选。
| 标签页 | 作用 | 是否必需 |
|---|---|---|
| 助手 | 模型服务商与密钥 | 必需 —— 没有模型就没有回复 |
| 服务器 | Session 服务器：启动本机服务、添加远程服务器、测试密钥、看状态 | 必需 —— 没有服务器就没有聊天 |
| 账号 | 账号登录；连起你的电脑与手机，Session 密钥随之同步、设备互认 | 否 —— 不登录也能聊天，多设备时才需要 |
| 授权与密钥 | 许可证（专业版）与云钥匙（MCP、DERP、模型网关） | 否 —— 试用覆盖头几天；之后专业版与云端服务需要 |
| 私网设备 | 应用内私有网络；加入后可连你其他机器上的 Session | 否 —— 只有多机场景需要 |
| 更新 | 应用更新与通道 | 否 —— 默认自动 |
其余标签页 —— 运行环境、资料、通用（语言、主题、字号）、语音、用量与费用、反馈 —— 都是个人偏好与诊断项，聊天都不需要。
其他窗口
同一套聊天还有两个窗口，前提是某处已经有一个 Session：
- Web UI —— 在运行 Session 的机器上打开浏览器访问
http://127.0.0.1:8110/，按提示粘贴xh_ses_…密钥。浏览器保存自己的设置，所以每个浏览器粘一次。 - iPhone —— 手机不跑 Session，总是连已有的那个。在 设置 → 账号 登录账号，再到 设置 → 服务器 → 添加远程服务器 填地址和密钥。若那台电脑只在私有网络里可达，先在 设置 → 私网设备 加入。
排错
| 现象 | 可以试试 |
|---|---|
| 离线 | 在 设置 → 服务器 点启动本机服务 |
| 401，或密钥被拒 | 重启本机服务，然后重开应用。仍不行？把设备登录到同一账号让密钥同步，或重新签发一把 |
| 卡在激活 | 在 设置 → 授权与密钥 贴上许可证，或改用 Web UI —— 它没有桌面门槛 |
| 模型报错 | 检查运行 Session 那台机器上的 设置 → 助手 |
保持更新
客户端在 设置 → 更新 里自更新。引擎的更新是一条终端命令，见高级使用。
接下来
| 目标 | 下一步 |
|---|---|
| 终端聊天、服务器命令、模型服务商 | 高级使用 |
| 接入自己的工具 | Session API |
| 一把 key 访问 DeepSeek、Kimi 与 Claude | 模型网关 |