Cline SSH Remote 教程（2026）：Desktop 远程开发配置与排错

Cline Desktop 的 SSH remote：界面留在本机，agent 在远程主机执行。v0.0.31（9 月 17 日）首发，v0.0.37（9 月 26 日）再度高亮；前置条件、Settings → Remote 配置、跳板机与常见报错，一篇讲全。

2026年9月28日

2026 年 9 月 17 日，Cline Desktop v0.0.31 上线了一个改变这个 coding agent「在哪干活」的功能：SSH remote。十天之后，v0.0.37（9 月 26 日）在全新的 What's new 弹窗里把它放在头条——你搜「Cline SSH remote」「Cline 远程开发」进来，多半就是被这波更新带动的。官方文档的一句话定位：应用留在你的电脑上；agent、它的工具和你的代码都住在远程机器上。

这个拆分就是全部重点。笔记本只负责聊天界面、审批按钮和实时输出；真正的编辑、终端命令、git 操作全部发生在开发机、构建机或云主机上。如果你的项目本来就部署在 Linux 服务器上——或者你的笔记本是 13 寸轻薄本、真正的算力在另一台机器上——这篇配置教程就是为你写的。下面依次讲：架构原理、前置条件、Settings → Remote 的完整配置步骤、跳板机（bastion）场景、六种你一定会遇到的报错，以及和 VS Code Remote-SSH 的对比。所有内容都来自 Cline 官方文档和 GitHub release notes——文档没写的细节，我们直接说明，不编。

快速答案

这是什么：Cline Desktop 的「本机 UI + 远端执行」拆分。文件编辑、终端命令、Git、MCP server 都在远程主机上执行；聊天、审批、实时输出留在桌面应用里。
什么时候有的：2026 年 9 月 17 日的 v0.0.31 首发。9 月 26 日的 v0.0.37 不是首发——只是 What's new 弹窗再次高亮。把这两个日期记对，网上大部分以讹传讹就跟你没关系了。
需要什么：一台 Linux（x64/arm64）或 macOS 主机，本机已经配好密钥认证（key-based）并信任主机指纹。不需要 root、不需要 npm、不需要开放端口——Cline 通过你现有的 SSH 连接传一个自包含 helper（Linux 上约 30 MB）上去。
怎么连：先在终端跑通免密登录，然后在 Cline 里走 Settings → Remote → New Host → Test Connection，最后在新会话页的环境选择器里选中主机。从头到尾大约两分钟。
最大的限制：不支持密码登录（只认密钥）、同时只能连一台主机、不支持 Windows 主机、断网约 45 秒后隧道关闭。

架构：界面在本机，执行在远端

大多数「远程开发」方案的本质是「把整个 IDE 搬到服务器上」。Cline Desktop 的 SSH remote 走的是另一刀，官方文档把边界写得很清楚：文件编辑、终端命令、Git、MCP server 全部远程执行，而聊天、审批和实时输出留在应用里。

什么在哪跑，一张表看明白：

层级	在哪执行
聊天界面、计划编辑	本机（Cline Desktop）
审批	本机——原生弹窗，不是终端里敲 y/n
文件编辑	远程主机，以 SSH 用户身份
终端命令	远程主机
Git 操作	远程主机
MCP server	远程主机
会话历史	远程主机

实现机制比你预想的轻。首次连接时，Cline 把「一个小型自包含 helper」传到主机的 ~/.cline/remote/ 目录——Linux 上约 30 MB，按 Cline 版本缓存——启动它，然后通过 SSH 隧道通信。文档列出了这套设计帮你省掉的东西：不需要 apt、npm、root 权限，也不需要开放任何端口。

把它交给你的服务器之前，有几个设计细节值得先知道：

主机上不暴露任何网络端口。 helper 启动的 Cline Hub 只绑定主机的 loopback 接口，应用通过 ssh -L 在本地转发——用文档的原话说，「主机上没有任何东西暴露给网络」。
它驱动的是你系统自带的 ssh，并且带上 BatchMode=yes 和 StrictHostKeyChecking=yes——复用你已有的密钥、config 和 known-hosts 信任，遇到该弹窗的情况宁可拒绝也不会绕过。
你的 API key 不会落在服务器上。 key/token 只「在会话期间通过认证隧道发给主机，不会写进远程机器的 provider 设置」。
不碰已有的 Cline CLI。 如果同一台主机上已经跑着同账号的 Cline CLI，remote helper 会启动自己隔离的 Hub，互不干扰。
主机元数据只存本机，路径 ~/.cline/data/settings/remote-environments.json（权限 0600），按 v0.0.31 release notes 的说法只存 identity file 路径，绝不存密钥内容。

连接前的准备：前置条件清单

官方前置条件很短：

macOS、Windows 或 Linux 上的 Cline Desktop。（从零开始装的话，我们的 Cline Desktop 教程先带你过一遍应用本身。）
本机有 SSH 客户端——ssh -V 能出版本号就行。macOS、Linux、Windows 10/11 都内置。
远程机器跑 Linux（x64 或 arm64）或 macOS。把 Mac 当主机连，要求本机也跑在 Mac 上。
密钥认证，且主机指纹已被本机信任。 Cline 不会弹出密码输入框，也不会弹指纹确认。
不支持：Windows 主机、32 位树莓派系统（Raspberry Pi OS）。

第一步：先在终端配好免密登录

这是一次性的工作，在你自己的终端里做——它也是 90% 后续报错的预防针。按文档的说法：

ssh-keygen -t ed25519——如果 ~/.ssh/id_ed25519 已经存在就跳过。
ssh-copy-id dev@dev.example.com——这是你最后一次输密码。（Windows 下用 PowerShell 把公钥追加进 authorized_keys。）
ssh dev@dev.example.com，第一次登录输 yes 信任主机指纹。

文档给的一行测试法：如果 ssh dev@dev.example.com 能让你免密码、免确认直接登上远程机器，Cline 就能连上。 这一步不通，Cline 里怎么配都没用——先回终端把 SSH 本身修好。

第二步：在 Settings → Remote 添加主机

打开 Cline Desktop：Settings → Remote → New Host。 各字段这样填：

字段	填什么
Name	随意起名（「build-server」「gpu-box」）
SSH host	主机名、IP，或 `~/.ssh/config` 里的别名
User	可选——你的 SSH 用户名
Port	留空走 SSH config 默认值（22），要改就显式填
Identity file	可选——私钥路径

点 Test Connection，出现绿色「Passed」徽章即配置成功；测试的同时会保存主机。文档特别提醒了一个容易误解的点：「保存或测试主机并不等于连接它」——真正的连接发生在下一步。

第三步：连接并打开远程项目

回到新建会话页，点环境选择器——工作区选择器左边的笔记本图标——在 Remote 分组下选中你的主机。首次连接会把 helper 传到主机上；然后点 Open folder… 选远程机器上的项目目录。最近用过的 workspace 会按主机分别记住。

接下来正常干活就行：所有工具调用都以你的 SSH 用户身份在主机上执行，聊天窗口把审批请求和输出流回本机桌面。想切回本地，在同一个选择器里点 Local——文档说这会「断开连接、停掉主机上的 helper，但把它留在缓存里」，重连很快。

跳板机与代理：走 ProxyJump

如果你的服务器在内网、必须先过跳板机（bastion），或者你手里只有一个 HTTP/SOCKS 代理：注意 Cline 的 SSH 层不走系统 HTTP(S) 代理设置，底下就是原生的 SSH。文档给的正路是在 ~/.ssh/config 里定义别名：

跳板机场景：用 ProxyJump 指令串接跳板。
HTTP/SOCKS 代理：用 ProxyCommand 配 nc。Windows 上文档指向 Git for Windows 自带的 connect.exe 替代 nc。

然后在 Cline 里把这个别名填进 SSH host 字段即可——整条连接（包括隧道）都走你终端 SSH 同样的路径。国内公司内网开发机必须过跳板机的同学，这一节就是为你写的。

常见报错排查：你实际会撞上的六种

全部来自官方排错清单：

报错	解法
`Could not resolve hostname`	检查拼写、连上 VPN，或直接用 IP
`Permission denied (publickey)`	重跑 `ssh-copy-id`；检查 User 字段；Identity file 必须指向私钥，不是 `.pub` 公钥
`Host key verification failed`	先在终端手动登录一次并输 `yes`——Cline 拒绝未信任或已变更的主机指纹
`Identity file ... not accessible`	修正路径，或者干脆留空
`Remote target ... is unsupported`	Windows 主机、32 位 ARM、跨系统连 Mac 都不支持
带口令的私钥终端能用、Cline 不行	先把钥匙装进 agent：macOS 用 `ssh-add --apple-use-keychain ~/.ssh/id_ed25519`，其他平台 `ssh-add`

值得记住的规律：Cline 不负责创建 SSH 认证，只负责消费它。 上面每一种错，都先回终端层修好。

上手前要知道的限制

只支持密钥登录。 文档原话「永远不会显示密码输入框」——服务器只开密码认证的话，先配密钥。
信任必须预先建立。 Cline 遇到未知或已变更的主机指纹会直接拒绝而不是弹窗询问；trust-on-first-use 那一步发生在你的终端里。
一次只能连一台主机。 当前版本没有多主机会话。
两件事远程会话里还做不了：往消息里附本机文件；把远程文件在本机编辑器里打开。
断网会杀掉会话。 断连「约 45 秒后」隧道关闭；重新选中主机即可重连。未保存的中间状态自己负责——跟任何 SSH 会话一样。

时间线：v0.0.31 首发，v0.0.37 再上头条

很多转述把两个日期搅在一起，这里按 release notes 理一遍干净的时间线：

v0.0.31（2026-09-17）——SSH remote 首发：「在 Settings → Remote 添加并测试主机，然后在欢迎页工作区选择器旁的环境选择器里选中它。」同一版还把并行 sub-agent 改成了真并发——「委派三件独立的工作，耗时取决于最慢的那件」。此时 Mac 主机还要靠 CLINE_REMOTE_HELPER_BINARY 本地编译 helper。
v0.0.34（09-22）——Mac 连 Mac：「现在可以从一台 Mac 通过 SSH remote 连到另一台 Mac」，Apple Silicon 和 Intel 主机都有了签名 helper。
v0.0.36（09-25）——SSH 设置打磨：已保存主机未改动时禁用 Save，新建主机按钮改名 Add。
v0.0.37（09-26）——新增 About 页（版本号、更新通道、Check for updates）和更新后的一次性 What's new 弹窗。它的第一期就是你搜到这篇文章的原因：「第一期覆盖 SSH remotes、worktrees、composer 里的 pull request status，以及并行 sub-agents。」之后可以在 About 页的 Highlights 里随时回看。

所以：如果哪篇文章说 SSH remote 是「v0.0.37 的新功能」，它差了十天和一个版本号。v0.0.37 是扩音器，不是功能本身。

同一批还带来了什么

What's new 弹窗一共点了四样，其中两样和 SSH remote 是天然搭档：

并行 sub-agents（子代理）。 按 subagents 文档的说法，Cline 能「并行生成专注的研究型 agent」，每个都有「自己的 prompt 和上下文窗口」，以只读方式探索代码库——读文件、搜索、ls、grep、git log、git diff——然后「把详细报告交回主 agent」，不污染主 agent 的上下文。它们不能编辑文件、不能开浏览器、不能碰 MCP server、不能联网搜索，官方标注这是实验特性。默认启用（走 use_subagents 工具；在 Settings → Features → Agent 里可关闭）。由于 SSH remote 会话里所有工具执行都在主机上进行，sub-agent 的探索也是对着远程代码库跑的——大仓库放在高配开发机上、用并行子代理做前期调研，是很顺的组合。
Worktrees。 Git worktree 允许多个分支并排检出；v0.0.35 的 notes 显示 worktree 感知行为已经落地（斜杠菜单里的插件命令跟随「会话自己的工作区（包括 worktree）」）。我们没找到完整 worktree 功能集的专门文档页，具体能力还在演进——这是我们诚实的说法，不是抱怨。
Composer 里的 PR status。 只在 What's new 弹窗里被点名；我们没核实到专门的文档页，没见过的机制就不描述了。

对比 VS Code Remote-SSH 和终端 agent

最顺理成章的参照物是微软那套。按 VS Code 官方文档，Remote-SSH「直接在远程机器上运行命令和其他扩展」，并且「会在远程操作系统上安装 VS Code Server」。所以两者在核心原则上一致——代码和执行都放主机——差别在别处：

	Cline Desktop SSH remote	VS Code Remote-SSH
主机上的足迹	约 30 MB helper，免 root 免 npm	安装 VS Code Server
本机界面	桌面聊天应用 + 原生审批弹窗	完整编辑器窗口
适合谁	在开发机上跑 agent 会话	以编辑器为中心的远程开发

第三条路：终端类 agent（Claude Code、Codex CLI、Cline CLI）跑在 SSH 会话里的 tmux 中——界面本身就住在服务器上。Cline Desktop 的 SSH remote 把这个方向反过来：GUI 和审批按钮留在你桌上，执行发生在远端。如果你是编辑器重度用户，Remote-SSH 加 Cline 的编辑器扩展（我们的 Cline 入门教程讲的就是编辑器路线）依然是最顺的组合；如果你偏好 Cline Desktop 的聊天式工作流、但代码在服务器上——这个功能就是为你准备的。

诚实说明

官方文档页没印任何版本号。 本文所有版本事实都来自 GitHub release notes（v0.0.31、v0.0.34、v0.0.36、v0.0.37），均已内链。
Worktrees 和 composer 里的 PR status 没有专门文档页（至少我们没找到）；本文只复述 What's new 弹窗和 release notes 的原话。这些后续可能补文档——过段时间读到本文的话，以当时的官方文档为准。
我们没有逐一实测所有平台组合。 主机支持范围（Linux x64/arm64、Mac 连 Mac、不支持 Windows 主机）引自文档，不是我们的实测结论。
延迟与性能表现官方没有数据，实际体验取决于你到主机之间的链路。

FAQ

Cline 支持 SSH 远程开发吗？从哪个版本开始？

支持。SSH remote 首发于 2026 年 9 月 17 日的 Cline Desktop v0.0.31，入口在 Settings → Remote。9 月 26 日的 v0.0.37 加了 About 页和 What's new 弹窗，把这项功能和 worktrees、PR status、并行 sub-agents 一起再次高亮。桌面应用低于 v0.0.31 就先升级；What's new 弹窗本身要 v0.0.37 才有。

Cline Desktop 怎么连接远程服务器？

三步。第一步，终端里先跑通免密登录：生成密钥（ssh-keygen -t ed25519）、推送公钥（ssh-copy-id user@host）、手动登录一次信任指纹。第二步，Cline Desktop 里进 Settings → Remote → New Host，填 host/user/port/私钥路径，点 Test Connection 直到出现「Passed」。第三步，新建会话页点环境选择器，在 Remote 下选主机并打开远程目录。之后文件编辑、终端命令、Git、MCP server 都在服务器上执行，聊天和审批留在本机。

Cline 的 SSH remote 能用密码登录吗？

不能。文档写得很死：「永远不会显示密码输入框。」只支持密钥认证，且主机指纹必须已被信任。如果你现在登录服务器靠输密码，先跑一次 ssh-copy-id；私钥带口令的话，先 ssh-add 装载，让 agent 能非交互地使用它。

跳板机 / 堡垒机场景怎么配？

可以，但走 SSH 自己的机制，不是 Cline 的设置项。系统 HTTP(S) 代理会被忽略；在 ~/.ssh/config 里用 ProxyJump 定义别名实现跳板串接（HTTP/SOCKS 代理则用 ProxyCommand 配 nc——Windows 上用 Git for Windows 自带的 connect.exe），先在终端验证别名能通，再把别名填进 Cline 的 SSH host 字段。

Cline SSH remote 和 VS Code Remote-SSH 怎么选？

两者解决的是同一半问题——代码和执行都放主机——但本机体验不同。VS Code Remote-SSH 会在远程安装 VS Code Server，给你完整的编辑器；Cline Desktop 的 SSH remote 只放一个约 30 MB 的 helper，免 root 免 npm，本机保留聊天式 agent 界面，审批是原生弹窗。编辑器优先的工作流选 Remote-SSH；想用桌面应用的聊天和审批、让服务器干重活的工作流选 Cline SSH remote。两者连同一台主机也不冲突——装的是互不相干的组件。