RubyChat Matrix 运营使用手册

1. 安装聊天客户端

各平台统一使用 Element：Windows PC 使用 Element Desktop，Android 和 iOS 使用 Element X。

Windows PC：打开 Element 官方下载页面，下载 Element Desktop，然后完成安装。
前往 Element 下载页面
Android 手机：打开 Google Play，搜索 Element X，然后安装。
下载 Element X Android
iPhone / iPad：打开 App Store，搜索 Element X，然后获取并安装。
下载 Element X iOS
安装完成后，打开当前设备对应的客户端并进入登录界面。

Android 消息通知 通过 Google Play 安装的 Element X Android 默认使用 FCM 接收后台消息通知。未安装 Google Play Services 的设备可改用 UnifiedPush，需要另行配置兼容的分发器。

PC 和手机可以同时使用 Element Desktop 和 Element X 可以登录同一个 Matrix 账号。

2. 配置 Home Server 并登录

无论使用 Element Desktop 还是 Element X，都必须先把 Home Server 切换到 RubyChat Matrix。

Home Server 地址

https://rubychat-matrix.rubygame.vip

用户名示例

operator

Windows PC：Element Desktop

打开 Element Desktop，选择登录已有账号。
在登录页面选择编辑或更改主服务器（Homeserver）入口。
填写下面的完整 Home Server 地址并确认：
https://rubychat-matrix.rubygame.vip
服务器识别成功后，输入管理员提供的现有 Matrix 用户名和密码登录。
首次在 PC 登录会生成一台新设备。使用已经登录的可信设备完成验证，或按管理员提供的恢复流程操作。

Android / iOS：Element X

打开 Element X，选择登录已有账号。
在登录页面选择 其他服务器、编辑服务器或更改主服务器（Homeserver）入口。
填写下面的完整 Home Server 地址并确认：
https://rubychat-matrix.rubygame.vip
服务器识别成功后，输入管理员提供的现有 Matrix 用户名和密码登录。
首次登录会生成一台新设备。使用已经登录的可信设备完成验证，或按管理员提供的恢复流程操作。

不要使用默认的 matrix.org 必须先更改 Home Server，再登录管理员提供的现有账号；不要在客户端中重新注册一个新账号。

进入会话列表后，再继续下一节选择需要使用的功能。

3. 选择是否绑定个人 IM（可选）

以下为个人 Telegram 和个人 Slack 的可选绑定方式，可全部不绑定，也可仅绑定其中一个。

不绑定也能正常聊天 不绑定个人 IM 时，仍可使用 Matrix 内部聊天，以及管理员预先配置并授权的共享 Slack 频道。

使用需求	是否需要绑定	接下来怎么做
只使用 Matrix 内部聊天和共享 Slack 频道	不需要	直接在已有会话和管理员分配的频道中聊天
同步个人 Telegram	可选	按第 4 节绑定个人 Telegram
同步个人 Slack	可选	按第 5 节绑定个人 Slack
同时同步 Telegram 和 Slack	可选	依次完成第 4 节和第 5 节

个人账号仅限账号持有人绑定 绑定操作必须在对应 Bridge Bot 私聊中完成，不要把 Telegram 验证码、Slack Token 或 Cookie 交给管理员。

TG

4. 绑定个人 Telegram（可选）

使用手机号登录；验证码会发送到已登录的官方 Telegram 客户端，不会通过短信发送。

操作步骤

在当前客户端点击“新聊天”（铅笔或加号图标），选择“私聊”。
输入 Telegram Bridge Bot 的完整账号：
@telegrambot:rubychat-matrix.rubygame.vip

必须包含开头的 @ 和完整服务器后缀。
打开机器人私聊并发送：
login phone +国家代码手机号

如果没有响应，改发 !tg login phone +国家代码手机号。

手机号必须使用国际格式并包含国家代码，中间不要使用空格。
Telegram 会把 6 位验证码发送到已经登录的官方 Telegram 客户端。
验证码不会通过短信发送。
按机器人提示，在当前私聊输入收到的 6 位验证码。
如果 Telegram 开启了两步验证，按机器人提示在当前私聊输入两步验证密码。
等待机器人明确回复登录成功。之后收到的新 Telegram 消息会出现在 Matrix 中。

搜索不到机器人时 直接输入完整账号并确认发起私聊，不要只输入 telegrambot，也不要创建同名普通用户。

保护登录信息 Telegram 手机号、6 位验证码和两步验证密码只用于当前机器人私聊，不要截图转发，也不要发到群聊或工单。

Telegram 绑定成功的表现

机器人明确提示 Telegram 登录成功

Telegram“设备”列表中出现新的关联会话

外部发送的新 Telegram 消息出现在 Matrix

从 Matrix 回复后，Telegram 另一端收到消息

Telegram 常见异常

没有收到验证码：确认手机号包含国家代码，并检查已经登录的官方 Telegram 客户端；Telegram 不会通过短信发送此验证码。

验证码错误或过期：重新发送完整的手机号登录命令，并输入 Telegram 最新发送的 6 位验证码。

提示密码错误：机器人询问的是 Telegram 两步验证密码，不是 Matrix 密码。

登录成功但没有聊天：当前未回填旧历史。请让另一个 Telegram 账号发一条新消息，再查看 Matrix 左侧会话或新建的个人 Space。

SL

5. 绑定个人 Slack（可选）

使用个人 Slack Web 登录态进行绑定。绑定成功后，个人 Slack 会话会同步到 Matrix。

Slack Token 和 Cookie 等同于个人登录凭据 只允许在与 Slack Bridge Bot 的加密私聊中发送。发送前确认房间只有当前 Matrix 用户和机器人；若没有显示加密，不要继续。不要发给管理员、同事、群聊或工单，也不要保存在截图和文档中。

操作步骤

在当前客户端点击“新聊天”，选择“私聊”，输入 Slack Bridge Bot 的完整账号：
@slackbot:rubychat-matrix.rubygame.vip

必须包含开头的 @ 和完整服务器后缀。
在电脑浏览器登录个人 Slack Web 账号，并打开需要同步的工作区。
打开浏览器开发者工具，在 Slack 页面中取得两项登录信息：
- 用户 Token：以 xoxc- 开头，位于 localStorage 的 localConfig_v2 对象中；
- 名为 d 的 Cookie：值以 xoxd- 开头。
在 Console 中可先运行下面的命令，找到目标工作区对应的 token 字段：

JSON.parse(localStorage.localConfig_v2).teams

Cookie 可在“Application（应用）→ Cookies → https://app.slack.com”中找到，名称必须是 d，不要复制其他 Cookie。
回到 Slack Bridge Bot 私聊，按下面格式发送登录命令，把两个占位符替换为刚取得的实际值：
login token <xoxc-token> <xoxd-cookie>
等待机器人明确回复登录成功。根据服务器同步设置，最近的个人 Slack 会话会陆续出现在 Matrix 中。
从 Slack 发送一条新消息，并从 Matrix 回复，确认双向同步正常。

不绑定个人 Slack 也不影响共享频道 管理员预先配置并授权的共享 Slack 频道仍可直接使用，不需要提供个人 Slack Token 或 Cookie。

个人 Slack 绑定成功的表现

机器人明确提示 Slack 登录成功

Matrix 中出现个人 Slack Space 或会话房间

Slack 的新消息出现在 Matrix

从 Matrix 回复后，Slack 另一端收到消息

个人 Slack 常见异常

提示 Token 或 Cookie 无效：确认两项信息来自同一个已登录的 Slack Web 会话，并分别以 xoxc- 和 xoxd- 开头。

登录命令无权限：记录 Matrix 账号、机器人 ID、发生时间和错误文字，让系统管理员检查 Bridge 权限；不要附带 Token 或 Cookie。

登录成功但没有会话：等待 30–90 秒后重新进入会话列表，再从 Slack 发送一条新消息触发同步。

经常退出登录：Slack Web Session 可能已经失效或被企业安全策略撤销，需要重新取得登录信息；仍然发生时联系组织管理员确认政策。

6. 故障排查

优先按现象排查。不要反复创建新 Matrix 账号，也不要把密码、验证码、Token 或 Cookie 交给管理员。

Home Server 提示无效或无法连接

确认填写的是 https://rubychat-matrix.rubygame.vip。
确认包含 https://，前后没有空格，也没有填写其他地址。
检查或切换当前设备的网络后重试；仍然失败时，把错误文字和发生时间发给系统管理员。

Home Server 正确，但账号无法登录

重新输入管理员提供的 Matrix 用户名和密码，注意大小写。不要自行注册新账号；仍无法登录时联系系统管理员重置密码。

搜索不到机器人

确认使用完整 ID，开头有 @，后缀是 :rubychat-matrix.rubygame.vip。
从“新聊天 / 私聊”入口输入，不是在顶部消息全文搜索框中搜索。
直接粘贴完整 ID 后按 Enter；本服务器不会显示所有用户列表。
不要创建名为 telegrambot 或 slackbot 的普通用户。

机器人进入私聊但不回复

Telegram Bot 可尝试发送 !tg help，Slack Bot 可尝试发送 !slack help。

仍不回复时，记录发生时间、Matrix 账号、机器人 ID 和错误文字交给技术人员；不要附带验证码、密码、Token 或 Cookie。

Telegram 登录成功，但看不到外部聊天

等待 30–90 秒，回到会话列表后重新进入房间。
查看会话列表中是否出现 Telegram 桥接房间。
从 Telegram 让另一个账号发送一条新消息。
旧历史不出现是当前配置的预期行为，不代表登录失败。

个人 Slack 登录失败或没有同步会话

确认 Token 以 xoxc- 开头，Cookie 名称为 d 且值以 xoxd- 开头。
确认两项信息来自同一个已登录的 Slack Web 工作区。
确认登录命令发送在 @slackbot:rubychat-matrix.rubygame.vip 私聊中，不是在群聊中。
登录成功后等待 30–90 秒，再从 Slack 发送一条新消息触发同步。
仍然失败时，只把 Matrix 账号、机器人 ID、发生时间和错误文字发给系统管理员。

绝对不要提供：Slack Token、Cookie、Slack 密码或完整登录命令。

管理员分配的共享 Slack 频道不可见

重新进入会话列表或管理员指定的 Space。
确认当前登录的是管理员已授权的完整 Matrix 账号。
仍然不可见时，把 Matrix 账号和频道名称发给管理员检查分配状态。

共享 Slack 频道不要求绑定个人 Slack，也不要为了解决频道不可见而提交个人 Token 或 Cookie。

登录后出现“新的验证请求”

这是 Matrix 的新设备验证，不是 Telegram 或 Slack 绑定。

若该设备确为刚登录的新设备，应在已有的可信设备上确认并核对验证码；此操作不会自动绑定任何个人 IM。

桥接房间无法解密或机器人提示看不到

先完成当前客户端的 Matrix 设备验证并重新进入会话，然后回对应机器人私聊重新执行该平台的登录流程。不要把不可解密房间截图、验证码、Token 或 Cookie 发送给其他人。

需要技术人员协助时提供什么

Matrix 完整账号，例如 @operator01:rubychat-matrix.rubygame.vip；
平台名称和机器人完整 ID；
发生时间，精确到分钟；
机器人返回的错误文字，可遮盖账号隐私；
使用 Android、iOS 还是 Windows 客户端，以及客户端名称。

绝对不要提供：Matrix 密码、Telegram 验证码或两步验证密码、Slack Token、Cookie 或 Slack 密码。

7. 解绑、换人和账号交接

个人 Telegram 和个人 Slack 都必须在各自的 Bridge Bot 私聊中退出。不要把原账号或登录凭据直接交给接替人员。

场景	运营操作	结果
退出个人 Telegram	`list-logins` → `logout <Login ID>`	停止 Telegram 新消息同步，已存在的 Matrix 房间和历史可继续保留
退出个人 Slack	在 Slack Bridge Bot 私聊发送 `logout`	停止个人 Slack 新消息同步，已有房间和历史可能继续保留
离开共享 Slack 频道	在当前客户端的房间菜单选择“离开”	只移除当前 Matrix 用户；其他参与者和共享频道不受影响

退出个人 Telegram 账号

使用当初完成 Telegram 手机号登录的 Matrix 账号，打开与 @telegrambot:rubychat-matrix.rubygame.vip 的私聊。
先查看当前账号的登录记录：
list-logins

机器人无响应时改发 !tg list-logins。
复制机器人返回的完整 Login ID，然后执行：
logout <Login ID>

无响应时改发 !tg logout <Login ID>。不要把尖括号当作 Login ID 的一部分。
等待机器人明确回复 Logged out，再到 Telegram → 设置 → 设备中复核；若关联会话仍在，手动终止该会话。

Telegram logout 不会删除 Telegram 账号或远端聊天 它只删除 Matrix Bridge 保存的 Telegram 登录会话。退出后不会自动清理房间，因此原桥接房间和 Matrix 历史可能继续保留，但不会再同步新消息。

退出个人 Slack 账号

使用当初完成个人 Slack 登录的 Matrix 账号，打开与 @slackbot:rubychat-matrix.rubygame.vip 的私聊。
发送退出命令：
logout

机器人无响应时改发 !slack logout。
等待机器人明确回复退出成功，再确认个人 Slack 会话不再同步新消息。

Slack logout 不会删除 Slack 账号或远端聊天 它只删除 Matrix Bridge 保存的个人 Slack 登录会话。已有 Matrix 房间和历史可能继续保留，但不会再同步新消息。

离开共享 Slack 频道仅影响当前 Matrix 用户 其他 Matrix 参与者仍然留在房间，共享 Slack 频道也会继续工作。后续需要重新使用时，由管理员再次添加对应 Matrix 账号。

人员离职或账号换人

原使用者在 Telegram Bridge Bot 私聊执行 list-logins 和 logout <Login ID>。
原使用者在 Slack Bridge Bot 私聊执行 logout。
到 Telegram“设置 → 设备”复核关联会话已经移除，并按组织安全要求复核 Slack Web Session。
按账号交接要求离开共享 Slack 频道；如需保留工作记录，可由管理员先完成交接。
Matrix 管理员停用原 Matrix 用户；不要把原账号、密码、Token 或 Cookie 直接交给新人。
为新人创建独立 Matrix 用户；新人按需绑定个人 Telegram 和 Slack，再由管理员分配需要的共享频道。

8. 常见问题

Windows PC 和手机可以同时登录同一个 Matrix 账号吗？

可以。Element Desktop 和 Element X 会作为不同设备登录同一个账号。首次在新设备登录后，应使用可信设备或恢复方式完成设备验证。

必须绑定 Telegram 或 Slack 才能聊天吗？

不需要。个人 IM 绑定全部可选；不绑定时仍可使用 Matrix 内部聊天，以及管理员预先配置并授权的共享 Slack 频道。

多个 Matrix 用户可以分别绑定个人 Telegram 和 Slack 吗？

可以。每位运营使用独立 Matrix 账号，并分别绑定个人 Telegram 和 Slack；不同用户的个人登录会话相互独立。

可以让多个运营共用一个 Matrix 账号和一套外部账号吗？

不建议。共用会破坏审计、设备验证和离职交接，也容易造成 Telegram 和 Slack 会话管理混乱。应给每个运营独立 Matrix 账号。

为什么搜索不到管理员分配的共享 Slack 频道？

共享 Slack 频道通常是私有房间，不能依赖搜索发现。向管理员提供完整 Matrix ID，由管理员直接添加即可；不需要绑定个人 Slack。

为什么绑定后没有以前的聊天记录？

历史回填数量取决于各 Bridge 的服务器设置，不保证导入全部旧记录。先等待同步完成，再从 Telegram 或 Slack 发送一条新消息确认新消息是否正常。

Slack Token 或 Cookie 可以发给管理员帮忙吗？

不可以。它们等同于个人 Slack 登录凭据，只能发送到当前 Matrix 用户与 Slack Bridge Bot 的加密私聊。排查问题时只能提供错误文字、发生时间、Matrix 账号和机器人 ID。

普通 Matrix 群组会自动变成 Telegram 群或 Slack 频道吗？

不会。桥接房间必须由 Bridge 与外部会话建立对应关系。不要把普通 Matrix 群组当成外部平台群组使用。

Matrix 密码和外部平台密码需要相同吗？

不需要，也绝对不应相同。Matrix、Telegram 和 Slack 是相互独立的账号系统；个人 Slack 绑定使用 Web Session Token 和 Cookie，不要提交 Slack 密码。