Hagency 快速入门 #

这是一份完整的首次使用指南：从"我完全不知道 Matrix 是什么"到"我已经在自己的服务器上和团队聊天"。如果下面某个概念你不熟悉，先看 Matrix 协议——那篇把本页用到的所有词汇都定义好了，还包含完整的客户端对比。

第 1 步——在 Hagency 上创建服务器 #

打开 hagency.cloud，点击 立即开始。

注册 Hagency 平台账户并完成邮箱验证，或使用支持的 OAuth 提供商登录。
选择套餐。
配置服务器地址：选择 <子域名>.hagency.cloud 的子域名，并可选填写自己的 Matrix ID 域名。Matrix 身份域名在服务器创建后固定。
确认地址和套餐，点击 创建 Hagency Server。

Hagency Cloud 部署基于 Matrix 的整合应用 Hagency Server，提供聊天、认证、管理、项目与 Agent。各工作区使用共享数据库基础设施上的隔离数据库，Element Web 客户端可选。

部署完成后，打开服务器的账号中心（/auth/）并注册首位管理员。若要通过平台管理用户、房间和用量，在服务器设置中授权平台管理。Agent 执行需要连接 Hagency 桌面客户端。

下载 Hagency Desktop，使用服务器地址登录，再按 Agent 设置创建 Agent、连接执行设备上的模型账号并启动服务。普通 Matrix 聊天也可继续按下文配置 Element。

当仪表板变绿，你会看到一张卡片，里面列着你后续需要用到的全部信息：

使用在服务器账号中心注册的 Matrix 账号。平台登录和服务器登录使用各自的账户。

从 Matrix 客户端子页里挑一个。本教程用 Element，因为它功能最全：

启动客户端，进入欢迎页。
点登录。
当出现主机服务器字段时，点编辑（Element）或其他（FluffyChat / Cinny）。千万不要直接用默认的 matrix.org——那会登录到 Matrix 公服，而不是你自己的服务器。
把 https://<你的名称>.hagency.cloud 粘进去。
点继续。客户端会校验是否能访问到你的主机服务器，然后弹出登录表单。
输入你的 Matrix 用户名（只填本地名，例如 alice，不要填完整的 @alice:server 格式）和 Matrix 密码。
点登录。

你现在已通过 Matrix 客户端连接到自己的 Hagency Server。

Element（以及大多数客户端）在首次登录时会带你走三个快捷设置：

设置显示名。 这是别人看到的人类可读名字——例如"Alice Chen"。随时可改。
上传头像。 可选，但上传后你在群聊里不会看起来那么"匿名"。
设置加密密钥备份。 Matrix 的加密密钥默认只存在设备上，如果设备丢失且没有备份，你会失去所有加密历史。Element 会邀请你生成一段 恢复密钥（一长串字符）和/或 恢复口令——至少保存其中一个到安全的地方，例如密码管理器。

新房间打开。在底部输入框里写一条消息，按回车。恭喜——你刚刚通过自己的 Hagency Server 发出了第一条端到端加密消息。

在房间里点房间标题 → 成员 → 邀请。

对方接受后，这个房间就会出现在他的客户端里。

如果你在第二台设备登录（例如笔记本 + 手机），Matrix 会提示出现了未验证的会话。验证一下能防止攻击者入侵服务器后偷偷加入自己的设备读你的消息。

验证通过后，所有加密房间的历史会在新设备上解密。完整细节见安全 → 设备验证。

仪表板一直卡在 "pending" 超过一分钟。 点重试，或查看右上角的通知铃铛。集群繁忙时容器创建偶尔会慢一点。
Element 提示"无法连接到主机服务器"。 确认你填的是 https:// 开头，而且用的是 <你的名称>.hagency.cloud（不是 hagency.cloud）。在浏览器里打开 https://<你的名称>.hagency.cloud/_matrix/client/versions，应该能看到一小段 JSON。如果看不到，说明工作区还没跑起来，去仪表板检查。
"凭证无效"，但密码明明是对的。 记住：你的 Hagency 仪表板 密码（hagency.cloud）和 Matrix 密码（Element 登录）是两套。需要重置 Matrix 那个，在 服务器 → Matrix 用户 里操作。
恢复密钥丢了，读不了旧的加密消息。 这是协议层的限制——Matrix 的端到端加密决定了即便是 Hagency 运营方也无法帮你恢复。不过之后的新消息在新设备上能正常显示。