第 7 章 · SpectrAI 桌面端 v1.0.4远程控制
SpectrAI 操作手册 v1.0.4 · 桌面端 · 第 7 章
概述
远程控制让你从桌面之外的端向本机会话发指令、看进度、收通知。SpectrAI 提供三条通路：局域网访问（同一 WiFi 下用浏览器直连）、Cloud Relay（公网中继，随时随地）、以及聊天机器人（Telegram / 飞书 / 企业微信）。本章讲桌面端如何开通与配置这三条通路，并说明会话生成的文件如何回传到配对手机。远端客户端（手机 App、浏览器）本身的界面不在本章展开，以桌面端操作为准。
⚠️ 注意远程控制的前提是桌面端保持运行。Cloud Relay 与聊天机器人为 Pro 及以上套餐可用；局域网访问所有套餐均可用。
核心概念
局域网访问：同一局域网内的手机、平板、电脑用浏览器打开桌面端地址、输入配对码即可连接，无需公网或额外服务。
Cloud Relay：桌面端在内网（无公网 IP）时，通过公网中继服务器转发事件，让远端穿透内网访问。为 Pro+ 专属，且各套餐有绑定机器数量上限。
聊天机器人：把 Telegram / 飞书 / 企业微信接入桌面端，用于远程下指令、查状态、收推送。三者已合并到同一个「机器人配置」入口，按平台切换管理。
配对手机收件箱：桌面会话生成的文件可以主动推送到配对手机的收件箱，而不是只回一句本地路径让你手动找。
操作步骤：启用局域网访问
局域网访问适合你和桌面在同一 WiFi 下、用另一台设备的浏览器远控。
- 打开「设置 → 网络与连接 → 局域网访问」
- 打开「启用局域网访问」开关，服务启动后会显示访问地址与配对码
- 记下访问地址（形如
http://192.168.x.x:9800），点「复制」可直接复制；也可让另一台设备扫描页面上的二维码
- 在另一台设备的浏览器打开该地址，输入 6 位配对码完成连接。配对码 5 分钟后过期，点刷新按钮可换新码
- 已连接的设备出现在「已配对设备」列表，可查看设备名与 IP，点「踢出」即可撤销
- 如需改端口，在「服务端口」填新值并点「应用」（默认
9800，修改后会重启服务）
⚠️ 注意局域网访问建议只在可信网络下使用；如需公网远控，请改用 Cloud Relay 走加密中继，不要把局域网端口直接暴露到公网。
操作步骤：启用 Cloud Relay
Cloud Relay 让你在没有公网 IP 时也能从外网远控。此功能为 Pro+ 专属。
- 打开「设置 → 网络与连接 → Cloud Relay」
- 打开「启用 Cloud Relay」开关，桌面端会连接中继服务器，状态区显示「已连接 / 连接中 / 重连中 / 未连接 / 连接异常」
- 在「机器名称」填一个便于识别的名字（会显示在手机端），点「保存配置」
- 连接成功后，页面出现「手机扫码连接」二维码；手机打开 SpectrAI Remote 扫码即可连接
- 已连接的客户端显示在「已连接客户端」列表
🔧 高级如需自建中继，把「Relay 服务器地址」改为自建服务器的 WebSocket 地址（形如
wss://your-relay-domain.com）再重连；Relay 服务器代码在packages/relay-server/。各套餐的绑定机器数量上限不同，页面会显示当前上限。
操作步骤：配置 Telegram 机器人
Telegram 机器人用你自建的 Bot，通过 Bot Token 接入。此功能为 Pro+ 专属。
- 在 Telegram 中找
@BotFather，创建一个 Bot 并复制它给出的 Bot Token - 在桌面端打开「设置 → 远程控制 → 机器人配置」，平台切到「Telegram」，进入「平台配置」子页
- 粘贴 Bot Token，点「保存」，再打开「启用 Bot」开关
- 国内网络通常需要代理才能连 Telegram；若「代理」显示未配置，点提示跳到「网络与连接 → 网络与语音」配置代理
- 切到「授权用户」子页，添加允许与 Bot 交互的 Telegram User ID（向 Bot 发消息即可获取自己的 ID），可设为管理员或只读
- 切到「推送设置」子页，用总开关和分项（确认请求 / 错误 / 完成 / 卡住 / 工作流）控制推送哪些事件
操作步骤：配置飞书机器人
飞书机器人适合团队协作与企业 IM。此功能为 Pro+ 专属。
- 在飞书开放平台创建应用，拿到 App ID 与 Secret
- 在桌面端打开「设置 → 远程控制 → 机器人配置」，平台切到「飞书」，进入「平台配置」子页
- 填写 App ID 与 Secret 并保存，然后启用
- 在「推送设置」子页勾选要接收的事件类型
操作步骤：配置企业微信机器人
企业微信机器人适合企业内部协作，支持两种连接方式。此功能为 Pro+ 专属。
- 在桌面端打开「设置 → 远程控制 → 机器人配置」，平台切到「企业微信」，进入「平台配置」子页
- 选择连接方式：
- 智能机器人 API：填写 Bot ID 与 Secret（走长连接）
- 自建应用 Relay：填写 Corp ID、Agent ID、Secret
- 保存并启用后，在「推送设置」子页勾选要接收的事件类型
操作步骤：指定机器人与远程控制的模型
机器人的智能回复、自动会话标题、对话摘要等后台调用，已统一由「模型分配」里的一个业务位控制，不再在各机器人页单独配 Provider。
- 打开「设置 → AI 模型 → 模型分配」
- 找到「机器人/远程控制」业务位，选择一个支持 HTTP Chat Completions 的 Provider，再选具体模型
- 留空则由系统按可用配置自动回退
💡 提示给机器人分配一个响应快、成本低的模型，可避免远程指令占用主会话的高价额度。
操作步骤：把会话文件回传到配对手机
用手机远控桌面会话、让 AI 生成了文件（报告、截图、导出包等）时，可以让 AI 把文件直接推到配对手机的收件箱，而不是只给一个本地路径。
- 在会话中直接要求，例如“把这个文件发到我手机”“回传手机”
- AI 会把文件推送到配对手机收件箱（优先配对手机，必要时可降级到已配置的 IM 渠道）
- 手机端在收件箱查看文件；点条目上的「来源 / 打开会话」可跳回对应会话（手机端界面，以桌面操作为准）
⚠️ 注意配对手机通道单文件上限约 800MB，大文件走分片下载；超限会明确提示。要看到收件箱进度条与分片效果，手机端需升级到配套版本。
详细配置
| 字段名 | 类型 | 默认值 | 作用 | 入口位置 |
|---|---|---|---|---|
| remote.enabled | boolean | false | 启用局域网访问服务 | 设置 → 网络与连接 → 局域网访问 → 启用局域网访问 |
| remote.port | number | 9800 | 局域网服务监听端口（修改后重启服务） | 设置 → 网络与连接 → 局域网访问 → 服务端口 |
| enabled（Relay） | boolean | false | 启用 Cloud Relay 公网中继（Pro+） | 设置 → 网络与连接 → Cloud Relay → 启用 Cloud Relay |
| serverUrl（Relay） | string | 官方地址 | Relay 服务器 WebSocket 地址（可改为自建，形如 wss://…） | 设置 → 网络与连接 → Cloud Relay → Relay 服务器地址 |
| machineName（Relay） | string | null | 本机在手机端显示的名称 | 设置 → 网络与连接 → Cloud Relay → 机器名称 |
| botToken | secret | null | 自建 Telegram Bot 的 Token（加密存储） | 设置 → 远程控制 → 机器人配置 → Telegram → 平台配置 |
| appId | string | null | 飞书应用 App ID | 设置 → 远程控制 → 机器人配置 → 飞书 → 平台配置 |
| appSecret | secret | null | 飞书应用 Secret（加密存储） | 设置 → 远程控制 → 机器人配置 → 飞书 → 平台配置 |
| corpId | string | null | 企业微信企业 ID（自建应用 Relay 方式） | 设置 → 远程控制 → 机器人配置 → 企业微信 → 平台配置 |
| agentId | string | null | 企业微信应用 ID（自建应用 Relay 方式） | 设置 → 远程控制 → 机器人配置 → 企业微信 → 平台配置 |
| agentSecret | secret | null | 企业微信应用 Secret（加密存储；智能机器人方式改填 aibotBotId / aibotSecret） | 设置 → 远程控制 → 机器人配置 → 企业微信 → 平台配置 |
| 机器人/远程控制（模型分配业务位） | enum | 未分配 | 机器人与远程控制后台调用（智能回复、会话标题、摘要）使用的全局 Provider 与模型；留空自动回退 | 设置 → AI 模型 → 模型分配 → 机器人/远程控制 |
高级用法
跨端会话列表与所属工作区
手机端 / 网页端的会话列表能看到每个会话所属的工作区，便于在多项目下区分；列表变更会更及时同步。远端短暂掉线时，桌面端不会立刻清空当前选中的机器，恢复后可继续操作。
推送事件分级
机器人的「推送设置」按事件类型分项：确认请求、错误、完成、卡住、工作流。按需只开关心的类型，避免噪音。三个平台各自独立配置，互不影响。
常见问题
局域网扫码后连不上
确认「局域网访问」已启用；用另一台设备打开的是桌面端的局域网 IP 地址（不是 localhost）；确认配对码未过期（5 分钟）；检查防火墙是否放通了服务端口（默认 9800）。
Cloud Relay 一直显示未连接
确认套餐为 Pro 及以上；检查网络能访问 Relay 服务器地址；如用自建 Relay，确认地址是 wss:// 开头的 WebSocket 地址；必要时关掉再重开开关重连。
Telegram Bot 收不到消息
确认 Bot Token 正确、「启用 Bot」已打开；国内网络确认已在「网络与连接」配置代理；确认你的 Telegram User ID 已加入「授权用户」；在「推送设置」确认勾选了对应事件类型。
同账号多设备，如何区分推送来自哪台桌面端
在 Cloud Relay 的「机器名称」为当前桌面端取一个名字（如“办公室工作站”），远端列表与推送会带上此名称。
相关章节
- 第 1 章 账号与激活 — 账号登录是远程控制的前提
- 第 8 章 Provider 与 API — Provider 配置
- 第 9 章 设置与快捷键 — 网络、代理与模型分配设置
- 第 11 章 套餐与模式 — Cloud Relay 与机器人的套餐门控
- 第 10 章 FAQ 与故障排查 — 网络、权限、推送延迟问题排查