CrossDesk 让你从电脑、浏览器、手机或终端(桌面 CLI)连接远端电脑,也能通过桌面墙(DeskHub)集中查看与操控多台设备。项目基于 MiniRTC,支持自托管。
主要功能 · 下载与平台支持 · 快速连接 · 终端 CLI · Agent / MCP · IP 直连 · 可信设备 · 界面预览 · 使用指南 · 文档导航 · 自托管 · 帮助与反馈 · 赞助
- 跨平台远控: Windows、macOS、Linux 桌面互控,浏览器及原生 iOS / Android 客户端访问电脑;鸿蒙 PC 与移动端处于开发阶段。
- 局域网 IP 直连: 桌面客户端通过 IP、端口和六位密码连接,无需云端信令服务;支持独立端口、记住密码及按模式显示近期设备。
- 终端主控: 在终端中通过设备 ID 观看和操控远程桌面,支持 ANSI / Kitty / Sixel 画面、局部缩放与平移、持续本地命令模式及 Pi 扩展,可单独构建。
- 桌面墙: 多设备实时预览、分组、放大操控、群控和批量文件分发。
- 画面与声音: H.264 / AV1、硬件编解码、远端音频,会话内调整画质、帧率和远端显示器分辨率;记住已确认的分辨率选择,最后一个控制端断开后恢复原显示模式。可用能力随平台与设备而异。
- 日常协作: 多显示器切换、键鼠与组合键、文本剪贴板;双栏文件浏览支持目录导航、文件与文件夹双向传输、拖放和任务管理。
- Agent / MCP: 通过本机 MCP 服务授权 Agent 观察和操作远端电脑,提供实时监看、人工接管、多会话、剪贴板和文件工具;可安装对应平台的 MCP 包。
- 可信设备: 桌面端可选开启可信设备限制,在连接密码之外校验设备身份;支持复制、粘贴配对信息,提前添加允许访问本机的设备。
- 部署与运维: P2P 直连、TURN 中继、SRTP 媒体加密、自托管,以及 Windows 登录前远控和 Linux 无头运行。
从 官方网站 或 GitHub Releases 下载与你的系统和 CPU 架构匹配的安装包;也可直接打开 Web 客户端。
| 平台 | 支持范围与安装要求 |
|---|---|
| Windows | 控制 / 被控;Windows 10+,x64;.exe 安装包,也支持便携构建 |
| macOS | 控制 / 被控;macOS 14.0+;按 Intel / Apple Silicon 选择 x64 / arm64 .pkg |
| Linux | 控制 / 被控;Ubuntu 20.04+、glibc 2.31 基线;amd64 / arm64 .deb |
| iOS / iPadOS | 仅控制;从 App Store 安装,商店版系统要求以页面为准;当前源码目标为 iOS 16.0+,也可自行构建签名 |
| Android | 仅控制;Android 8.0+,arm64;下载已签名 APK 安装,或自行构建 |
| 鸿蒙 PC(开发版) | 控制 / 被控;API 26,arm64;使用 DevEco 构建并签名 HAP,仍在进行真机验收 |
| 鸿蒙手机 / 平板(开发版) | 仅控制;API 20+,arm64;使用 DevEco 构建并签名 HAP,仍在进行真机验收 |
| Web | 仅控制;支持 WebRTC 的浏览器;无需在控制端安装客户端 |
| 终端 CLI(开发版) | 仅控制;分发目标为 macOS / Linux(x64、arm64)和 Windows(x64);通过 npm 安装 或从源码构建,使用要求见 CLI 说明 |
| MCP(开发版) | 仅控制;在 Codex 或 DSH 中操作远端并监看画面;DSH 安装一个插件包,Codex 需 Node.js 22+,见 安装与使用 |
请按下载页面选择与你的系统和芯片匹配的安装包。开发版功能可能尚未包含在已发布安装包中,具体以对应 Release 说明为准。
- Linux: 已有桌面选普通版
crossdesk-linux-…deb;需要独立 Xfce 桌面的服务器选crossdesk-virtual-desktop-xfce-…deb。两者选择其一,安装与启动方法见 使用指南 和 无头运行。 - macOS: 首次运行时按提示授予屏幕录制及辅助功能权限;前者用于桌面采集,后者用于远程键鼠输入。权限说明
- iOS: 优先从 App Store 安装;GitHub 的未签名产物仍需自行签名,步骤见 iOS 构建说明。鸿蒙需使用 DevEco 构建并签名,见 鸿蒙说明。
- 准备被控电脑。 安装并运行 CrossDesk,切换至 ID 连接模式,等待显示“已连接服务器”,查看“本桌面”中的本机 ID 和密码。
- 发起连接。 在另一台电脑的 CrossDesk 中输入被控电脑的 9 位 ID,点击“连接”;也可使用原生移动端或 Web 客户端。
- 验证密码。 输入被控电脑当前的连接密码,等待远程画面出现。桌面端可勾选“记住密码”,后续从“近期连接”重连。
使用自建服务器时,两端需要接入同一服务;升级客户端前请先更新服务端。更多连接和密码操作见 使用指南,连接失败、黑屏或无法操作键鼠时见 常见问题。
- 切换模式。 两台电脑均运行支持 IP 直连的桌面客户端,点击左上角模式按钮切换到 IP 直连模式。若按钮未显示,在 设置 → 常规 → 网络连接 中勾选 启用 IP 直连 并保存。
- 填写地址。 在控制端输入被控电脑显示的
IP:端口,例如192.168.1.20:52888或[2001:db8::20]:52888,点击“连接”。只输入 IP 时使用默认端口 52888;请以对方界面显示的实际端口为准。 - 输入密码。 输入被控电脑在 IP 直连模式下显示的 6 位英文字母或数字密码,可勾选“记住密码”。切换模式时,“近期连接”同步切换为对应模式的设备记录。
两台电脑需要在局域网内可互相访问;网络可以有外网,也可以没有外网,直连会话不依赖云端信令服务。主窗口可直接切换本机 IP、修改端口和密码,默认开启所有 IP 接口监听,支持 IPv4 和 IPv6,支持通过 VPN 等接口连接,可在设置的“网络连接”中调整;关闭设置中的“启用 IP 直连”会停止监听、断开 IP 直连会话并隐藏模式按钮。详见 IP 直连使用指南。
桌面端的可信设备限制默认关闭,适用于 ID 连接和 IP 直连。开启后,控制端仍需通过原有密码验证,并持有可信名单中设备的配对私钥;仅知道 ID 和密码不能通过这项限制。
- 在控制端复制配对信息。 打开 设置 → 常规 → 隐私保护 → 管理可信设备,在 本机配对信息 中点击 复制配对信息。
- 在被控端添加控制端。 打开同一管理界面,将收到的信息粘贴到 添加可信设备 输入框,点击 添加 即可加入,无需再次确认,也无需先建立远程连接。
- 在被控端开启限制。 返回设置,勾选 仅允许可信设备控制 并保存。之后照常通过 ID 或 IP 发起连接、验证密码。
配对信息只包含公钥、设备名称和 ID,不含私钥或密码,应通过可信渠道传递。添加后可点击 查看指纹 与控制端核对;也允许添加本机,同一公钥不会重复加入。信任是单向的,如需互相控制,应在双方分别添加对方。
添加和移除会立即保存;开启限制时,移除信任 会断开对应设备的会话,名单为空则拒绝所有控制端。也可以从管理界面的已连接设备中添加完成身份验证的控制端。
兼容范围: 使用支持配对的新版桌面端、iOS、Android 或鸿蒙移动端。手机和平板从“设置 → 本机配对信息”复制配对信息,再添加到被控电脑。旧客户端和当前终端 CLI 无法连接开启此限制的被控端。
重装、清除应用数据或迁移电脑前,请先查看 身份备份与迁移。仅保存 ID 和密码不足以恢复已绑定的桌面身份;更换设备身份后需要重新配对。
本机凭据、远程连接和近期设备集中在主窗口,左上角提供连接模式切换和桌面墙入口。
切换本机 IP、修改端口与密码,通过对方地址连接;下方展示独立的局域网近期设备。
按分组查看多台设备,点击画面放大,再选择接管操控;支持批量连接、静音与文件分发。
群控会向所有已连接设备发送输入;关闭桌面墙会断开全部远程连接。操作范围与详细用法见 桌面墙使用指南。截图使用演示数据,更多操作见 使用指南。
在会话工具栏打开文件传输,同时浏览本机与远端目录,选择文件或文件夹后发送,也可在两栏之间拖放;任务列表显示进度并支持取消未完成任务。远端目录浏览需要兼容的被控端。
远程会话支持显示器切换、画质与帧率调整、声音、文本剪贴板同步和双向文件传输。工具栏还可查看网络状态、控制隐私屏;桌面设置中可配置 IP 直连开关、可信设备限制、编码、中继、自托管、最小化时暂停视频及桌面墙画面预算。
被控端为 Windows、macOS 或 Linux X11 时,可在 画面设置 → 分辨率 中选择当前显示器支持的模式,无需重连。桌面和原生移动端会记住远端确认成功的选择,重连时在仍受支持的情况下重新应用;最后一个控制端断开后,被控端恢复本轮连接首次调整前的显示模式。Linux 需要 X11 采集和 RandR,Wayland / XWayland 暂不支持此项调整。
crossdesk-cli 在终端中通过 9 位设备 ID 连接被控电脑,默认只读、静音。普通终端使用 ANSI 字符画面,支持 Kitty 或 Sixel 图形协议的终端可显示像素画面;可切换显示器、调整画质、放大细节和平移,也可明确开启键鼠控制。CLI 可以独立于桌面 GUI 构建,被控电脑仍需运行 CrossDesk 并提供可捕获的图形会话,信令服务需支持 cli 临时身份注册。
| ANSI 字符画面 | Kitty 协议像素画面 |
|---|---|
![]() |
![]() |
用彩色字符显示桌面轮廓,适合普通终端;查看局部可用 +/- 或滚轮以鼠标位置缩放。 |
直接显示像素画面,适合支持 Kitty 图形协议的终端,如 Ghostty。 |
ANSI 用字符显示画面,Kitty 可显示像素画面;实际效果取决于终端支持、字体和窗口大小。
准备 Node.js 22 或以上及 npm,从 @chunkdash/crossdesk-cli 安装。npm 会按操作系统与 CPU 架构选择原生程序,无需安装 Xmake 或 C++ 编译工具链。
npm install -g @chunkdash/crossdesk-cli@latest
crossdesk-cli doctor --json
crossdesk-cli 123456789将 123456789 换成被控电脑的 9 位设备 ID,连接时按提示隐藏输入密码。默认只读、静音;doctor 仅检查本机环境,不发起连接。更新到最新版时,重新执行上面的 npm install -g @chunkdash/crossdesk-cli@latest。
无需全局安装时,也可使用 npx,首次运行会下载对应平台包:
npx @chunkdash/crossdesk-cli@latest doctor --json
npx @chunkdash/crossdesk-cli@latest 123456789请安装统一入口 @chunkdash/crossdesk-cli,并保留 npm 的可选依赖,不要添加 --omit=optional;仅安装平台包不会注册 crossdesk-cli 命令。平台运行要求、旧包迁移及故障排查见 npm 分发说明。
默认只读、静音。只读模式下按 c 开启键鼠控制,按 +/- 或滚轮缩放,按 f 回到全景。控制模式下退出时,先按 Ctrl+],再按 q,否则普通按键会发给远端电脑。
# 普通终端,用字符显示画面
crossdesk-cli 123456789 --renderer ansi
# 支持 Kitty 图形协议的终端,用像素显示画面
crossdesk-cli 123456789 --renderer kittyCLI 通过设备 ID 连接,暂不提供 IP 直连、音频播放、文件传输或剪贴板同步,也不支持连接开启可信设备限制的电脑。被控电脑需要运行 CrossDesk 并有可用的桌面。自托管用户需要使用支持 CLI 连接的服务端。
完整 CLI 指南 · 参数、Pi 扩展与自行构建 · 安装故障排查
CrossDesk MCP 让你在 Codex 或 DeepSeek Harness 对话中安排远程任务,并在右侧查看远端画面。远端电脑运行 CrossDesk;本机按下表安装后,在面板中选择设备并授权。
| 使用环境 | 安装与配置 | 远端画面 |
|---|---|---|
| Codex 桌面版 | Codex 安装指南:注册 MCP,无需额外插件 | Agent 打开右侧内置浏览器 |
| DeepSeek Harness 桌面版(DSH) | DSH 安装指南:只安装一个对应平台的 MCP 插件包,自动注册服务 | 插件自动打开当前对话侧栏 |
- 下载与你的本机对应的平台安装包,再按上表完成安装。
- 让 Agent 打开 CrossDesk,在监看面板选择设备、输入连接密码,并选择仅查看或允许控制。密码在本地面板中输入;保存密码与允许以后自动连接分别设置。
- Agent 通过截图、键鼠和结构化桌面工具执行任务;用户可实时监看、暂停 Agent、人工接管或断开连接。
支持最多 8 个并行设备会话、多屏观察、远端文本剪贴板、文件浏览与传输、声音、系统锁屏及本地输入密码的解锁流程。窗口与可访问性操作受远端平台和系统权限限制,部分工具需要新版被控端。浏览器、终端和 MCP Apps 的面板能力因宿主而异;配置及兼容范围见 MCP 文档。
可从 App Store 安装原生控制端,支持触控与虚拟鼠标、多显示器、远端音频、文件收发和文本剪贴板。悬浮菜单的“剪贴板”按钮可主动发送本机文本,单次上限为 128 KiB;画面设置可调整受支持的远端显示器分辨率,并记住已确认的选择。iPhone / iPad 当前不能作为被控桌面,应用内更新检查指向 App Store。
原生控制端支持触控与外接键鼠、多屏切换、文件收发、文本剪贴板和画面设置。切换应用时优先通过画中画保持会话;不支持画中画时尝试通过后台通知保留连接。悬浮菜单可开关电脑的隐私屏。Android 手机和平板当前不能作为被控端。
PC 端可控制和被控制,复用桌面界面与桌面墙;手机和平板使用原生 ArkUI 控制端,支持触控、外接键鼠、多屏、文本剪贴板和文件收发。PC 录屏与输入控制需要系统授权,真机和长期会话验收仍在进行。
- Windows: CrossDesk Service 支持锁屏、登录和安全桌面控制。安装版 Release 开启“开机自启”后,登录前后使用同一本机 ID 和密码;用户登录后界面自动打开,已有远控连接继续保留。便携版和 Debug 不提供此开关。无显示器时会尝试准备虚拟显示器,并优先恢复已记录的显示分辨率。功能限制及启停命令见 Windows 无人值守指南。
- Linux: 可复用现有桌面,也可创建独立 Xvfb / Xfce 会话,操作方法见 Linux 无头运行。
可自行部署信令与 TURN 中继服务,并在客户端“设置 → 常规 → 自托管配置”中启用。控制端与被控端需要接入同一服务。
部署指南 · 客户端配置 · 服务端源码 · Web 客户端部署
- 使用指南:安装、连接、会话操作、设置和无人值守。
- 常见问题:连接失败、黑屏、系统权限及文件位置。
- 连接与可信设备:选择连接方式、配对及迁移身份。
- 更新客户端:检查更新、安装与失败后的处理。
- 自行构建:需要从源码安装时使用。
遇到问题时,可在桌面端主菜单打开 反馈与建议,导出诊断日志,并 提交问题。请附上两端系统、客户端版本、连接方式、报错及复现步骤;分享前检查日志和截图中的私人信息。详见 反馈与诊断日志。
如果 CrossDesk 对你有帮助,欢迎通过以下平台赞助,支持项目的持续开发、跨平台测试与日常维护。感谢你的支持!
爱发电 · Ko-fi · GitHub Sponsors
感谢 HelloGitHub、阮一峰的科技爱好者周刊 与 LinuxDo 社区的推荐、交流与支持。
Copyright (c) 2026 JUNKUN DI.
CrossDesk 使用 GPL-3.0-only 许可。隐私说明见 隐私政策。
CrossDesk 使用 SignPath.io 为本仓库构建的官方 Windows 发布包提供代码签名。
Free code signing provided by SignPath.io, certificate by SignPath Foundation.






