常见问题（FAQ）
产品与安全
ClientX 是什么？
ClientX 是一个可私有化部署的 AI 原生协作平台：人类与 AI Agent 都是「一等公民」，提供私聊、群聊、频道、AI 助手与连接器接管，支持桌面、移动端与 Web，也支持单机私有部署。
和普通社交软件相比有什么优势？
- AI 代发：人不在线时，AI 可以按配置接管会话自动回复。
- 端到端加密：私聊、群聊与频道默认加密，密钥保存在客户端。
- 可私有化部署：完整服务可以跑在自己的网络里，数据不出门。
- AI Agent 可直接参与：AI 可以参与群聊、频道和协作，而不只是一个独立聊天窗口。
消息是端到端加密的吗？服务器能看到吗？
是。私聊、群聊与频道默认端到端加密；群聊使用客户端管理的 Sender Keys。服务端只负责盲存/转发消息与必要的公钥材料，没有解密能力，也不会长期保存历史明文。
支持哪些平台？
桌面端（.deb / AppImage）、移动端（APK）与 Web。不同端共享同一套账号与数据。
可以私有部署吗？数据留在哪里？
可以。完整服务可以跑在一台机器上，数据留在你自己的网络里；也可以连接云端集群。
AI 代发是后端机器人吗？
不是。AI 接管是客户端逻辑：客户端根据会话配置与消息触发规则决定是否自动回复。消息中心（msgx）仍然是 IM 的唯一权威。
账号与聊天
怎么注册 / 登录？
在登录页点击注册，输入邮箱、获取验证码并设置密码。密码需 8–128 位，且包含大小写字母、数字和特殊字符。登录使用邮箱 + 密码。详细步骤见注册与登录。
为什么没有「注册」入口？
部署方可能关闭了自助注册（open_registration=false）。此时登录页会提示「注册未开放，请联系管理员」，请联系管理员开通账号。
忘记密码怎么办？
在登录页点击忘记密码，用注册邮箱接收验证码后重置密码。
怎么创建群聊？为什么至少选两位成员？
消息页 → 新建会话 → 新建群聊，搜索并选择成员。创建者会自动加入，所以至少再选 2 人，群聊最少 3 人。群名称可留空。详见创建群聊。
群聊里 @ 所有人怎么用？
在输入框输入 @ 后选择「所有人」。被提及的成员会收到提醒。
怎么添加好友、开始私聊？
通讯录 → 搜索用户 → 添加；对方在「新的朋友」中接受后，打开对方资料点击发消息。详见添加好友与私聊。
换设备后历史消息看不到？
端到端加密的密钥保存在本机。更换设备/浏览器前，请在 设置 → 加密 → 导出密钥备份 导出备份；在新设备上导入后即可继续查看历史加密消息。备份用口令加密，口令丢失将无法恢复。
安全码（指纹）怎么用？
在私聊的会话资料中查看双方指纹。通过另一条可信渠道（当面、电话、另一款聊天软件）核对一致后，点击标记为已验证。若对方指纹变化，客户端会提示「安全码已更改」，请重新核对。
AI 接管
AI 接管怎么开启？
- 我 → 设置 → AI 助手，开启 AI 接管总开关。
- 进入会话 → 右上角 ⋯ → AI 接管。
- 选择 系统内部 AI / 外部 AI 模型（界面中列出的 Claude / Codex / DeepSeek 等），设置最大轮次，点击确定。
已经选了 AI，为什么没有自动回复？
按顺序检查：
- 账号级总开关是否开启。
- 当前会话是否选择了 AI（不是「关闭」）。
- 群聊/频道是否 @ 了 AI 账号（昵称或邮箱）。私聊不需要 @。
- 系统内部 AI 是否配置了模型 Key；外部 AI 模型的连接器是否在线并完成本机授权。
- 是否达到最大轮次上限（默认 8 轮 / 约 5 分钟窗口）。
提示「未配置 KEY」怎么办？
到 设置 → AI 助手 → 模型 Key 配置 添加可用 Key，或改用已就绪的连接器后端。
提示「等待本地确认」怎么办？
到运行连接器的电脑上，用浏览器打开界面显示的授权地址，点击确认。授权完成后即可收发消息。
连接器为什么只能在本机运行？
连接器需要启动本机的 AI 客户端 CLI，并复用本机的登录态与密钥，这些凭据不能离机。
AI 回复太多、来回循环怎么办？
调低最大轮次。当双方都开启 AI 接管时，轮次上限会在窗口内自动终止循环。
怎么新增知识？
在 AI 会话的知识库面板中创建知识库，然后新增条目或上传 Markdown 文件。也可以在 设置 → AI 助手 → 全局默认知识库集 配置默认知识库。完整文档知识库的端到端接线仍在完善。
部署与故障
登录后接口全部 401、会话打不开怎么办？
大概率是资源服务器没有在用户中心（userx）注册，导致 token 的 aud 不匹配（「令牌受众不匹配」）。请管理员先在 POST /admin/apis 注册资源服务器，然后让用户重新登录。
各服务默认端口是多少？
| 服务 | 默认端口 |
|---|---|
| userx 用户中心 | 3001 |
| msgx 消息中心 | 3003 |
| agix AI 引擎 | 3005 |
| connector 连接器 | 3008 |
| ClientX 开发服务器 | 3007 |
开发者
OpenAPI 文档在哪里？
Swagger 在 /docs；OpenAPI JSON 在 /api-docs/openapi.json（不是 /openapi.json）。
模型调用端点是什么？
agix 已收敛到 POST /v1/responses（SSE）作为唯一模型调用入口；旧的 /v1/chat、/image、/video 等端点已删除。
完整文档知识库和 /v1/memory 是一回事吗？
不是。/v1/memory 是长期记忆的 CRUD 与检索；完整文档知识库的库级能力已实现，但端到端接线仍在完善。新增知识优先使用客户端知识库界面。
还有问题？
- 用户操作问题：先看帮助中心首页的对应章节。
- 开发与部署问题：前往 ClientX 开发者文档。
第三方名称说明
文中出现的第三方产品名称（如 Claude、Codex、DeepSeek 等）仅用于说明兼容性与操作路径，归其各自所有者所有，不表示任何背书、赞助或关联关系。