# SSH

cmux ssh 为远程计算机创建工作区。浏览器窗格通过远程网络路由，通过 scp 拖放文件，编码代理将通知发送到本地侧边栏，会话在拖放时重新连接。

## 用途

```
cmux ssh user@remote
cmux ssh user@remote --name "dev server"
cmux ssh user@remote --command 'omp "investigate auth"'
cmux ssh user@remote -p 2222
cmux ssh user@remote -i ~/.ssh/id_ed25519
cmux ssh user@remote --transport mosh
cmux mosh user@remote
cmux mosh-tmux user@remote
cmux mosh-tmux user@remote --session agent-main
```

cmux ssh 读取 ~/.ssh/config 中的主机别名、身份文件和代理设置。所有标志均反映其 ssh 等效项。

## 旗帜

| 旗帜 | 描述 |
| --- | --- |
| `--name` | 设置工作区标题 |
| `--command` | 在 shell 启动后于初始远程终端中运行一次命令文本 |
| `-p, --port` | SSH 端口（默认 22） |
| `-i, --identity` | 身份文件的路径 |
| `-o, --ssh-option` | 传递任意 SSH 选项（例如 -o StrictHostKeyChecking=no） |
| `--transport` | 交互式终端传输方式：ssh（默认）或 mosh |
| `--no-focus` | 创建工作区而不切换到它 |

## Mosh 终端传输

如果交互式终端需要在切换 Wi-Fi、VPN、热点或睡眠与唤醒后保持连接，请使用 cmux ssh user@remote --transport mosh。Mosh 仅承载终端 PTY；SSH 仍负责远程元数据、cmux 服务的设置与控制、浏览器代理、上传和重新连接。

cmux 要求本地安装 Mosh 1.4 或更高版本，并在启动前检查远程 mosh-server。如果客户端缺失或不兼容、服务器缺失，或远程检查失败，cmux 会说明原因并继续使用 SSH。

创建一个 Mosh 工作区，用于创建或附加命名的 tmux 会话（默认：main）。tmux 配置会在重连和应用会话恢复后保留。这是可漫游的 tmux 终端，而不是 cmux ssh-tmux 的原生镜像。--session <name> 选择会话；其他选项与 cmux mosh 相同。没有 Mosh 时，同一配置会通过 SSH 运行。

## SSH 深层链接

当网站或工具想要提供“在 cmux 中打开”按钮时，请使用 cmux SSH 深层链接。该链接将打开 cmux，显示确认提示，然后在用户确认后运行等效的 cmux ssh 命令。

```
cmux://ssh?host=dev.example.com
cmux://ssh?host=dev.example.com&user=alice&port=2222&title=GPU%20box
cmux://ssh?host=workspace123.vm-ssh.freestyle.sh&user=workspace123%2Csession-token
cmux://ssh?host=dev.example.com&host-key-policy=accept-new&no-focus=true
```

使用网站按钮的 cmux.com 后备 URL。如果未安装 cmux，它将打开本机链接并显示下载。

```
https://cmux.com/deeplink/ssh?host=workspace123.vm-ssh.freestyle.sh&user=workspace123%2Csession-token&title=Freestyle
```

提示和规则按钮使用相同的后备形状。逗号、冒号和文字加号在进行 URL 编码时会被保留：

```
https://cmux.com/deeplink/prompt?text=Review%20this%20branch
https://cmux.com/deeplink/rules?name=freestyle&text=Prefer%20commas,%20colons:%20and%20small%20PRs
```

使用 SVG 图标作为仪表板按钮，或在需要光栅图像时使用 PNG 徽标：

```
https://cmux.com/cmux-icon.svg
https://cmux.com/logo.png
```

使用 URLSearchParams 构建后备 URL，以便安全地编码标题、主机别名和用户名：

```
const params = new URLSearchParams({
  host: "workspace123.vm-ssh.freestyle.sh",
  user: "workspace123,session-token",
  title: "Freestyle",
});

const href = "https://cmux.com/deeplink/ssh?" + params.toString();
```

| 参数 | 含义 |
| --- | --- |
| `host` | 必需的 SSH 主机或 ~/.ssh/config 别名。 |
| `user` | 可选的 SSH 用户。 cmux 将其与主机组合为 user@host。 |
| `port` | 可选 SSH 端口，1 到 65535。 |
| `title` / `name` | 可选的工作区标题。仅使用标题或名称之一。 |
| `connect-timeout` | 可选的 ConnectTimeout 值（以秒为单位），范围为 1 到 600。 |
| `server-alive-interval` | 可选的 ServerAliveInterval 值（以秒为单位），从 1 到 3600。 |
| `server-alive-count-max` | 可选的 ServerAliveCountMax 值，1 到 100。 |
| `host-key-policy` | 可选的 StrictHostKeyChecking 策略：accept-new、ask、strict 或 yes。 |
| `no-focus` | 可选布尔值。 true 创建工作区而不切换到它。 |

对稳定应用程序使用 cmux://，对 Nightly 使用 cmux-nightly://，对调试或标记的开发版本使用 cmux-dev://。

外部链接无法传递身份文件、原始 ssh 选项、命令、ProxyCommand 或转发规则。将密钥、ProxyJump、主机名和高级选项放在 ~/.ssh/config 中。 cmux 显示命令预览并要求用户在连接之前信任 SSH 目标。

## 浏览器窗格

远程工作区中的浏览器窗格通过远程计算机的网络路由所有 HTTP 和 WebSocket 流量。输入 localhost:3000，您将看到在远程机器上运行的开发服务器。没有 -L 标志，没有手动端口转发。每个远程工作区都有一个独立的 cookie 存储，因此会话的范围仅限于每个连接。

## 拖放

将图像或文件拖到远程终端中，cmux 通过现有 SSH 连接通过 scp 上传。 cmux 通过 TTY 检测前台 SSH 进程，并通过 ControlMaster 多路复用路由上传。

## 通知

远程计算机上的进程可以运行在本地实例上执行的 cmux 命令。当编码代理在远程盒子上调用 cmux 通知时，通知会显示在本地侧边栏中。工作区选项卡上的蓝色环亮起。 Cmd+Shift+U 跳转到它。通过每台主机的冷却时间来抑制来自不稳定连接的通知垃圾邮件。

## 通过 SSH 编码代理

cmux claude-teams 和 cmux omo 都在 SSH 会话中工作。远程主机上的 Go 中继守护进程处理与本地 Swift CLI 相同的 tmux-compat 转换。当计算在远程机器上运行时，队友代理会在本地计算机上本地 cmux 拆分时生成。

```
# Inside an SSH session:
cmux claude-teams
cmux omo
```

## 重新连接

当连接断开时，cmux 以指数退避（3 秒、6 秒、12 秒，最多 60 秒）重新连接。远程会话持续存在，并且 cmux 在重新连接时重新连接，并使用最小屏幕获胜语义调整大小。除非您的配置已设置它们，否则将注入默认的 keepalive 选项（ServerAliveInterval=20、ServerAliveCountMax=2）。

## 中继守护进程

首次连接时，cmux 会探测远程主机（uname -s、uname -m）并上传版本控制的 cmuxd-remote 二进制文件。该二进制文件通过 stdio 使用 JSON-RPC 并处理三件事：

| 特点 | 如何 |
| --- | --- |
| 浏览器流量代理 | 通过守护进程的 stdio 通道进行 SOCKS5 和 HTTP CONNECT |
| CLI中继 | 使用 HMAC-SHA256 身份验证反向 TCP 隧道，以便远程进程可以在本地调用 cmux 命令 |
| 会话管理 | 在重新连接时保留会话，协调跨多个附件的 PTY 大小调整 |

守护程序二进制文件存储在远程主机上的 ~/.cmux/bin/cmuxd-remote/<version>/<os>-<arch>/cmuxd-remote 中，并根据应用程序中嵌入的 SHA-256 清单进行验证。

Canonical: https://cmux.com/zh-CN/docs/ssh

Documentation index: https://cmux.com/llms.txt