Skip to content
kunkundiPublic

About

A lightweight, cross-platform remote desktop software with support for Web Client access | 一款支持 Web 客户端访问的轻量级跨平台远程桌面软件。

Topics

Resources

Stars

4.8k stars

Watchers

27 watching

Forks

Repository files navigation

CrossDesk 标志:图标在左,双色文字在右

轻量、跨平台的远程桌面,支持电脑、浏览器、移动端和终端连接,用桌面墙集中查看与操控多台设备。

官方网站 · 下载客户端 · 打开 Web 客户端 · English

Platforms

Clients

Release npm Build License: GPL v3 Stars

爱发电 Ko-fi GitHub Sponsors

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 构建并签名,见 鸿蒙说明。

快速连接

通过设备 ID 连接

  1. 准备被控电脑。 安装并运行 CrossDesk,切换至 ID 连接模式,等待显示“已连接服务器”,查看“本桌面”中的本机 ID 和密码。
  2. 发起连接。 在另一台电脑的 CrossDesk 中输入被控电脑的 9 位 ID,点击“连接”;也可使用原生移动端或 Web 客户端。
  3. 验证密码。 输入被控电脑当前的连接密码,等待远程画面出现。桌面端可勾选“记住密码”,后续从“近期连接”重连。

使用自建服务器时,两端需要接入同一服务;升级客户端前请先更新服务端。更多连接和密码操作见 使用指南,连接失败、黑屏或无法操作键鼠时见 常见问题。

通过局域网 IP 直连

  1. 切换模式。 两台电脑均运行支持 IP 直连的桌面客户端,点击左上角模式按钮切换到 IP 直连模式。若按钮未显示,在 设置 → 常规 → 网络连接 中勾选 启用 IP 直连 并保存。
  2. 填写地址。 在控制端输入被控电脑显示的 IP:端口,例如 192.168.1.20:52888 或 [2001:db8::20]:52888,点击“连接”。只输入 IP 时使用默认端口 52888;请以对方界面显示的实际端口为准。
  3. 输入密码。 输入被控电脑在 IP 直连模式下显示的 6 位英文字母或数字密码,可勾选“记住密码”。切换模式时,“近期连接”同步切换为对应模式的设备记录。

两台电脑需要在局域网内可互相访问;网络可以有外网,也可以没有外网,直连会话不依赖云端信令服务。主窗口可直接切换本机 IP、修改端口和密码,默认开启所有 IP 接口监听,支持 IPv4 和 IPv6,支持通过 VPN 等接口连接,可在设置的“网络连接”中调整;关闭设置中的“启用 IP 直连”会停止监听、断开 IP 直连会话并隐藏模式按钮。详见 IP 直连使用指南。

仅允许可信设备连接(可选)

桌面端的可信设备限制默认关闭,适用于 ID 连接和 IP 直连。开启后,控制端仍需通过原有密码验证,并持有可信名单中设备的配对私钥;仅知道 ID 和密码不能通过这项限制。

  1. 在控制端复制配对信息。 打开 设置 → 常规 → 隐私保护 → 管理可信设备,在 本机配对信息 中点击 复制配对信息。
  2. 在被控端添加控制端。 打开同一管理界面,将收到的信息粘贴到 添加可信设备 输入框,点击 添加 即可加入,无需再次确认,也无需先建立远程连接。
  3. 在被控端开启限制。 返回设置,勾选 仅允许可信设备控制 并保存。之后照常通过 ID 或 IP 发起连接、验证密码。

配对信息只包含公钥、设备名称和 ID,不含私钥或密码,应通过可信渠道传递。添加后可点击 查看指纹 与控制端核对;也允许添加本机,同一公钥不会重复加入。信任是单向的,如需互相控制,应在双方分别添加对方。

添加和移除会立即保存;开启限制时,移除信任 会断开对应设备的会话,名单为空则拒绝所有控制端。也可以从管理界面的已连接设备中添加完成身份验证的控制端。

兼容范围: 使用支持配对的新版桌面端、iOS、Android 或鸿蒙移动端。手机和平板从“设置 → 本机配对信息”复制配对信息,再添加到被控电脑。旧客户端和当前终端 CLI 无法连接开启此限制的被控端。

重装、清除应用数据或迁移电脑前,请先查看 身份备份与迁移。仅保存 ID 和密码不足以恢复已绑定的桌面身份;更换设备身份后需要重新配对。

界面预览

桌面客户端

本机凭据、远程连接和近期设备集中在主窗口,左上角提供连接模式切换和桌面墙入口。

CrossDesk ID 连接模式:模式切换、本机 ID、远程连接入口和近期设备;数据为演示

IP 直连模式

切换本机 IP、修改端口与密码,通过对方地址连接;下方展示独立的局域网近期设备。

CrossDesk IP 直连模式:本机 IP 和端口编辑入口、六位密码、远端地址输入和局域网近期设备;数据为演示

桌面墙(DeskHub)

按分组查看多台设备,点击画面放大,再选择接管操控;支持批量连接、静音与文件分发。

DeskHub 桌面墙:六台演示设备的远程画面与管理工具栏

群控会向所有已连接设备发送输入;关闭桌面墙会断开全部远程连接。操作范围与详细用法见 桌面墙使用指南。截图使用演示数据,更多操作见 使用指南。

双栏文件传输

在会话工具栏打开文件传输,同时浏览本机与远端目录,选择文件或文件夹后发送,也可在两栏之间拖放;任务列表显示进度并支持取消未完成任务。远端目录浏览需要兼容的被控端。

双栏文件传输:本机与远端路径、文件列表、发送按钮和任务列表;数据为演示

会话操作与设置

远程会话支持显示器切换、画质与帧率调整、声音、文本剪贴板同步和双向文件传输。工具栏还可查看网络状态、控制隐私屏;桌面设置中可配置 IP 直连开关、可信设备限制、编码、中继、自托管、最小化时暂停视频及桌面墙画面预算。

被控端为 Windows、macOS 或 Linux X11 时,可在 画面设置 → 分辨率 中选择当前显示器支持的模式,无需重连。桌面和原生移动端会记住远端确认成功的选择,重连时在仍受支持的情况下重新应用;最后一个控制端断开后,被控端恢复本轮连接首次调整前的显示模式。Linux 需要 X11 采集和 RandR,Wayland / XWayland 暂不支持此项调整。

会话画面设置:质量、帧率、远端显示器分辨率和画面偏好;背景为公开页面演示图

终端客户端 CLI

crossdesk-cli 在终端中通过 9 位设备 ID 连接被控电脑,默认只读、静音。普通终端使用 ANSI 字符画面,支持 Kitty 或 Sixel 图形协议的终端可显示像素画面;可切换显示器、调整画质、放大细节和平移,也可明确开启键鼠控制。CLI 可以独立于桌面 GUI 构建,被控电脑仍需运行 CrossDesk 并提供可捕获的图形会话,信令服务需支持 cli 临时身份注册。

画面预览

ANSI 字符画面 Kitty 协议像素画面
CrossDesk CLI 的 ANSI 四象限全景:顶部显示只读模式和连接状态,底部显示操作快捷键 CrossDesk CLI 的 Kitty 协议全景:同一远程桌面以像素画面显示,保留状态栏和操作快捷键
用彩色字符显示桌面轮廓,适合普通终端;查看局部可用 +/- 或滚轮以鼠标位置缩放。 直接显示像素画面,适合支持 Kitty 图形协议的终端,如 Ghostty。

ANSI 用字符显示画面,Kitty 可显示像素画面;实际效果取决于终端支持、字体和窗口大小。

通过 npm 安装并连接

准备 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 kitty

CLI 通过设备 ID 连接,暂不提供 IP 直连、音频播放、文件传输或剪贴板同步,也不支持连接开启可信设备限制的电脑。被控电脑需要运行 CrossDesk 并有可用的桌面。自托管用户需要使用支持 CLI 连接的服务端。

完整 CLI 指南 · 参数、Pi 扩展与自行构建 · 安装故障排查

Agent 与 MCP

CrossDesk MCP 让你在 Codex 或 DeepSeek Harness 对话中安排远程任务,并在右侧查看远端画面。远端电脑运行 CrossDesk;本机按下表安装后,在面板中选择设备并授权。

使用环境 安装与配置 远端画面
Codex 桌面版 Codex 安装指南:注册 MCP,无需额外插件 Agent 打开右侧内置浏览器
DeepSeek Harness 桌面版(DSH) DSH 安装指南:只安装一个对应平台的 MCP 插件包,自动注册服务 插件自动打开当前对话侧栏
  1. 下载与你的本机对应的平台安装包,再按上表完成安装。
  2. 让 Agent 打开 CrossDesk,在监看面板选择设备、输入连接密码,并选择仅查看或允许控制。密码在本地面板中输入;保存密码与允许以后自动连接分别设置。
  3. Agent 通过截图、键鼠和结构化桌面工具执行任务;用户可实时监看、暂停 Agent、人工接管或断开连接。

支持最多 8 个并行设备会话、多屏观察、远端文本剪贴板、文件浏览与传输、声音、系统锁屏及本地输入密码的解锁流程。窗口与可访问性操作受远端平台和系统权限限制,部分工具需要新版被控端。浏览器、终端和 MCP Apps 的面板能力因宿主而异;配置及兼容范围见 MCP 文档。

移动端与鸿蒙

iOS / iPadOS

可从 App Store 安装原生控制端,支持触控与虚拟鼠标、多显示器、远端音频、文件收发和文本剪贴板。悬浮菜单的“剪贴板”按钮可主动发送本机文本,单次上限为 128 KiB;画面设置可调整受支持的远端显示器分辨率,并记住已确认的选择。iPhone / iPad 当前不能作为被控桌面,应用内更新检查指向 App Store。

使用说明 · 构建与签名

Android

原生控制端支持触控与外接键鼠、多屏切换、文件收发、文本剪贴板和画面设置。切换应用时优先通过画中画保持会话;不支持画中画时尝试通过后台通知保留连接。悬浮菜单可开关电脑的隐私屏。Android 手机和平板当前不能作为被控端。

使用说明 · 源码构建

鸿蒙 HarmonyOS(开发版)

PC 端可控制和被控制,复用桌面界面与桌面墙;手机和平板使用原生 ArkUI 控制端,支持触控、外接键鼠、多屏、文本剪贴板和文件收发。PC 录屏与输入控制需要系统授权,真机和长期会话验收仍在进行。

使用与限制 · 构建与签名 · PC 说明 · 移动端功能

无人值守与无头运行

  • Windows: CrossDesk Service 支持锁屏、登录和安全桌面控制。安装版 Release 开启“开机自启”后,登录前后使用同一本机 ID 和密码;用户登录后界面自动打开,已有远控连接继续保留。便携版和 Debug 不提供此开关。无显示器时会尝试准备虚拟显示器,并优先恢复已记录的显示分辨率。功能限制及启停命令见 Windows 无人值守指南。
  • Linux: 可复用现有桌面,也可创建独立 Xvfb / Xfce 会话,操作方法见 Linux 无头运行。

自托管

可自行部署信令与 TURN 中继服务,并在客户端“设置 → 常规 → 自托管配置”中启用。控制端与被控端需要接入同一服务。

部署指南 · 客户端配置 · 服务端源码 · Web 客户端部署

帮助与反馈

遇到问题时,可在桌面端主菜单打开 反馈与建议,导出诊断日志,并 提交问题。请附上两端系统、客户端版本、连接方式、报错及复现步骤;分享前检查日志和截图中的私人信息。详见 反馈与诊断日志。

支持 CrossDesk

如果 CrossDesk 对你有帮助,欢迎通过以下平台赞助,支持项目的持续开发、跨平台测试与日常维护。感谢你的支持!

爱发电 · Ko-fi · GitHub Sponsors

致谢与许可

感谢 HelloGitHub、阮一峰的科技爱好者周刊 与 LinuxDo 社区的推荐、交流与支持。

Copyright (c) 2026 JUNKUN DI.

CrossDesk 使用 GPL-3.0-only 许可。隐私说明见 隐私政策。

Code signing policy

CrossDesk 使用 SignPath.io 为本仓库构建的官方 Windows 发布包提供代码签名。

Free code signing provided by SignPath.io, certificate by SignPath Foundation.

  • Committers and reviewers(代码提交与审核): kunkundi
  • Approvers(签名审批): kunkundi

About

A lightweight, cross-platform remote desktop software with support for Web Client access | 一款支持 Web 客户端访问的轻量级跨平台远程桌面软件。

Topics

Resources

Stars

4.8k stars

Watchers

27 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages