t8y2/motty · 上手攻略

  • 仓库：t8y2/motty
  • 链接：https://github.com/t8y2/motty
  • 分类：agent（SSH/SFTP/端口转发/VNC/RDP + AI 助手一体桌面客户端）
  • 作者：spark
  • 更新：2026-10-29

版本锚点：最新 release v0.1.8（2026-10-29 发布，README 与 releases API 均已核对）；go.mod 声明 go 1.26.0；最新提交 2026-10-29。仓库成熟度标注为 experimental。

一、这是什么

Motty 是一个用 Go 写的原生桌面 SSH 工作区，把终端、文件（SFTP/SCP）、端口转发、VNC/RDP 远程桌面，以及一个内置 AI 助手塞进同一个窗口。核心卖点是它构建在 Viva 这个自研 GUI 框架上——直接对 Metal / Direct3D / Vulkan 下手，不含 Electron、不嵌浏览器、不带 JavaScript 层。

所以它和 Termius、Tabby、WindTerm、MobaXterm 这类工具的定位差别很清楚：不是"给终端套个壳"，而是把"运维人员一天要开的那五六个窗口"合并成一个工作台。窗口标题、托盘图标都在 README 里明确区分了 release 与 dev 构建（Motty Dev）。

仓库结构也说明它是有明确边界的工程：internal/sshconn（SSH 拨号/主机密钥/认证/代理/跳板）、internal/term（终端模拟器与解析器）、internal/rfb + internal/desktop/vnc、internal/rdpcore + internal/desktop/rdp（MIT 协议的 gopher-rdp 派生分支）、internal/sftpclient / internal/scpclient、internal/forward、internal/ai（助手、工具、风险闸门、MCP 服务端）。RDP 部分是明确标注的第三方 MIT fork，附有变更清单。

二、解决什么问题

典型的运维/开发痛点是"应用切得太碎"：一个 SSH 客户端开终端，一个 SFTP 客户端传文件，一个 VNC 客户端看图形界面，一个浏览器标签页跑 web 端工具，外加一个 AI 工具想读终端上下文。每个都要登录一次、切一次窗口、切一次剪贴板。

Motty 的取舍是：全部放进一个窗口，用命令面板（macOS Cmd+Shift+P，其他平台 Ctrl+Shift+P）驱动，鼠标变成可选。终端、文件、转发、AI 助手之间共享同一套会话上下文。

第二个层面的问题是安全与信任。Motty 的做法是：主机密钥先在它自己的 known_hosts 里校验，校验通过前不发送任何凭据；保存的密码与密钥口令进 AES-256-GCM 金库，金库密钥放系统密钥串或用 Argon2id 主密码包裹；AI 提供商的 API key 也在金库里；终端文本发给模型前默认脱敏（密钥文件、赋值语句、URL 内嵌凭据、常见 token 格式）。它还明确说自己没有埋点分析，可选的更新检查会访问 GitHub Releases，默认关闭。

三、快速安装

方式 A：下载发行包（推荐）

从 releases 页面 下载对应平台的包：

平台 包格式
macOS（arm64, amd64） .dmg、.zip
Windows（amd64, arm64） .exe 安装器、便携 .zip（数据存在 motty.exe 同级的 motty-data）
Linux（amd64, arm64） .deb、.tar.gz

⚠️ Homebrew / AUR / .AppImage 目前尚未提供（README 明确写了 "not available yet"）。Linux 用户只能手动下 deb 或 tar.gz。

签名情况：macOS 构建在有凭据时已签名并公证；Windows 在配置了证书时签名；Linux 包未签名。

系统要求：macOS 需 Metal 与 Xcode 命令行工具；Windows 10/11；Linux 需 X11。

方式 B：从源码构建

需要 Go 1.26+，且 Viva 框架必须 checkout 在仓库旁边（Viva 是独立项目、有独立许可，不 vendored）：

git clone https://github.com/t8y2/motty
git clone https://github.com/vivaui/viva
cd motty
go run ./cmd/motty

打包也走 Viva：

cd ../viva
go run ./cmd/viva package -C ../motty --format app,dmg
go run ./cmd/viva package -C ../motty --target linux --arch amd64 --format tar.gz,deb

日常开发用 make run（带 -tags dev，窗口标题会显示 "Motty Dev"），make dev 会在 motty 或 ../viva 有 Go 文件变更时自动重建重启（watch 模式需要 fswatch，一次性模式不需要）。

四、核心用法

4.1 连接第一台主机

README 给的上手流程是五步：Hosts → New host → 填名称/地址/账号名 → 选认证方式（running agent / 私钥文件 / 密码）→ 连接后把主机密钥指纹与服务器上的比对，信任一次或保存。

这个流程的要点是"先验指纹再发凭据"，不是走过场。

4.2 认证方式覆盖面

支持：agent key、identity file、OpenSSH 用户证书（会自动配对 -cert.pub companion 文件）、PuTTY .ppk（v2/v3，含 Argon2id）、密码、keyboard-interactive 交互轮次。多问题的一轮认证（同一个 PAM 栈同时要密码和一次性码）会合并成一个对话框，每问一题一个字段。主机证书的 CA 一旦以 @cert-authority 落盘，连接时不再提示；未知证书则像未知主机密钥一样按指纹询问。

4.3 命令面板与快捷键

操作 macOS Windows / Linux
命令面板 Cmd+Shift+P Ctrl+Shift+P
终端内查找 Cmd+F Ctrl+F
命令历史 Cmd+Shift+H Ctrl+H
文件面板 Cmd+Shift+S Ctrl+S
新窗口 Cmd+Shift+N Ctrl+N

全部可配置。

4.4 AI 助手的两种模式

  • Ask 模式：以可见终端内容为上下文回答问题。
  • Agent 模式：可以在该终端里执行命令，带风险分级 + 审批闸门。Ask 模式下如果助手判断需要工具，会请求切换到 Agent；批准后请求会在 Agent 模式重试，这个选择会被记住。

运行过的命令会显示为命令本身，并在终端左边距带一个强调标记。Motty 会把自己加的捕获 wrapper 和标记从屏幕与自己的命令历史里隐藏掉——但远端 shell 自己的 history 不在 Motty 控制范围内，这点 README 说得很直白。

长对话按固定预算只发送最新的若干轮，所以会话不会撑爆模型上下文。悬停最后一条回答可以看到 token 用量和复制按钮。

4.5 MCP 服务端（对外部 agent 开放）

Motty 内置一个可选 MCP server，把同样的工具暴露给外部 agent。默认关闭、仅监听 loopback、bearer token 保护，支持 observe 与 ask 两种模式。

无窗口版本：

motty mcp-serve

这个模式由 agent 通过 stdio 启动，不需要端口也不需要 token，作用于你显式开放给 agents 的主机。

4.6 文件与终端联动

SFTP 支持多选、递归上传下载、有界传输队列、断点续传、取消/重试、改名、删除、改权限、书签。替换文件时的语义很讲究：先 stage 一个部分副本，校验续传的前缀，只有完整同步后才原子 rename；失败时旧文件保持完整。

内置原生编辑器可打开 UTF-8 文件（上限 1 MiB），在 stage 前后对远端文件做哈希，并保留权限。没有 SFTP 的服务器可以用内置 SCP 回退。

附件面板可以让它跟随 SSH 终端的当前目录（Bash 和 Zsh）。注意区分两个开关：Settings > Files 里有一个独立的、默认关闭的开关，是"终端在就绪空提示符时跟随文件面板导航"——两者不是一回事。

五、典型适用场景

  1. 多主机运维：主机可分组、打标签、搜索，并能从 OpenSSH config、PuTTY、Xshell、MobaXterm、WindTerm、Electerm 导入。
  2. 跳板机链路：Jump routes 对每一跳独立做校验与认证。
  3. 只监听 loopback 的图形服务：VNC/RDP 都可以经由 SSH 主机连接。
  4. 隧道：local、remote、SOCKS5、HTTP CONNECT 规则均为 loopback-only、持久化、显式启动；隧道随拥有它的 SSH tab 一起停止。还可以配置全局出站 SOCKS5/HTTP 代理，每个保存的网络主机可继承它、强制直连，或使用自己的代理。X11 转发会先用 per-session fake cookie 校验，再替换为本地 Xauthority cookie。
  5. 把 AI 助手接进真实运维流程：助手能读当前终端上下文，也能在审批闸门后执行命令。
  6. 多端同步：加密的 .mottybak 导出，以及通过 WebDAV、S3 兼容存储或 GitHub Gist 做记录级同步。记录带混合逻辑时钟（hybrid logical clocks）和 90 天删除 tombstone，多台机器收敛而不会互相覆盖。标签页、窗口布局、快捷键、字体、密钥路径、云凭据始终留在本地。

远程桌面能力边界（README 承诺在 docs/remote-desktop.md 里）：VNC 支持 RFB 3.3/3.7/3.8，None 与 VNC Authentication 认证，Raw/CopyRect/RRE/Hextile/ZRLE 编码，桌面尺寸调整、指针、键盘与文本剪贴板。RDP 走 TLS 且优先 NLA，在用户明确做出信任决定后固定服务器证书。

六、坑与注意

  1. ⚠️ 开发构建与发布版共享数据目录。默认数据目录、主机、设置、AI 配置和金库都是共用的；只有"工作区"（当前页面、会话、活动会话、标签布局）是独立的。开发构建可能升级配置或 AI schema，导致旧版发布版读不了；金库和云同步操作影响的是同一个日常环境。README 明确说"共享数据不是测试沙箱"。做迁移、删除、主密码或密钥重置测试前务必先备份，并用显式的 MOTTY_DATA_DIR 加测试凭据。另外，单独的目录只隔离应用文件，不自动隔离系统钥匙串里的条目。

  2. ⚠️ macOS 开发构建会动钥匙串。标准入口会创建或复用 ~/Library/Application Support/motty/development-signing 下的私有签名身份，首次访问可能需要一次系统钥匙串授权。签名或校验失败会直接停止启动，不会静默跑一个未签名构建。

  3. ⚠️ 审批闸门是安全控件，不是沙箱。README 原话："不要把 agent 指向一台跑错命令不可接受的机器。"它做的是事前确认，不是事后隔离。

  4. ⚠️ Linux 包未签名，从第三方源安装时需自行核对来源。

  5. ⚠️ 允许不安全远程 HTTP 是有代价的。远程 WebDAV 和 S3 地址默认要求 HTTPS；要在可信局域网用 HTTP，需要勾选 "Allow insecure remote HTTP"。README 说得很清楚：该连接未加密，认证细节可能被截获——不过备份文件在上传前仍是加密的。这个选择只保存在本机。

  6. ⚠️ WSL 选发行版而不是手打 wsl。Motty 能从 PATH 和常见安装目录探测 PowerShell / CMD / Git Bash，并把每个已安装的 WSL 发行版列为独立条目。文件面板也能跟随 WSL 终端的目录，走 \\wsl.localhost 共享。关键限制：只有 Motty 自己启动的 shell 才能上报它当前的目录。选发行版是首选做法，不要在 PowerShell 里手输 wsl。

  7. ⚠️ 别把 AI 的命令捕获当成完整的历史清理。Motty 隐藏自己的 wrapper 和标记，但远端 shell 的 history 仍会留下那条命令。

  8. ⚠️ 端口转发是 loopback-only 且需显式启动。这是好设计，但意味着改配置后不会自动生效，需要手动起隧道。

  9. ⚠️ 内置编辑器有 1 MiB 上限，大文件要靠外部编辑器或 SFTP。

  10. ⚠️ Linux 缺少 X11 就跑不起来，它是硬依赖。

  11. ⚠️ X11 转发有 fake cookie 校验步骤，部分服务器的 X11 配置与它不兼容时会出现诡异症状，排查成本不低。

  12. ⚠️ 排障要看日志目录：Windows %APPDATA%\motty\logs、macOS ~/Library/Application Support/motty/logs、Linux ~/.config/motty/logs（便携版在 motty-data\logs）。异常退出后有 crash-*.log，提 issue 时要附 motty.log 和最新的崩溃日志。

  13. ⚠️ 依赖 Viva 且未 vendored，从源码构建必须把 Viva clone 在旁边，否则直接编译失败。

  14. ⚠️ 维护流程有明确的社区约定：大改动先开 issue 讨论；PR 前要跑 test -z "$(gofmt -l .)"、go vet ./...、go test ./...、go test -race ./... 四项。

  15. ⚠️ 桌面框架能力应该提给 Viva。README 明确要求："Keep SSH, protocol and product logic in this repository. A capability that belongs to the desktop framework should be proposed in Viva instead."

七、与同类对比

Motty Termius Tabby WindTerm / Electerm MobaXterm
技术栈 Go + Viva 原生渲染 Electron Electron / 可换渲染 原生（Electron 系） 原生
运行时开销 最低（无浏览器引擎） 较高 中 中 低
终端保真度 真实 PTY、256 色与真彩、alternate screen、5000 行回滚、宽字符与组合字符、鼠标上报、输入方法、DECSET 2026 同步更新、kitty 键盘协议 中 中 中 中
内置 AI 助手 有（Ask/Agent + 风险闸门 + 脱敏） 有（偏云同步套餐） 插件为主 少 无
MCP 开放 有（可选，默认关，loopback + bearer token） 无 无 无 无
同步 加密 .mottybak + WebDAV/S3/Gist，CRDT 收敛 云端为主 本地配置 本地 本地
成熟度 experimental，v0.1.8 商业成熟 较成熟 较成熟 成熟但偏 Windows

Motty 相对 Termius 的核心差异是不依赖 Electron、不上云、且把 AI 与 MCP 做成一手能力；相对 MobaXterm 的差异是跨平台 + 原生渲染 + 内置 AI；相对纯终端客户端的差异是它把 VNC/RDP 也做进了一个窗口。

八、一句话推荐结论

如果你受够了 Electron 客户端的内存占用、需要一个把 SSH/SFTP/转发/VNC/RDP/AI 收进单窗口的原生工具，并且愿意接受 experimental 阶段的稳定性风险，Motty 值得试；如果你只想要一个稳定省事的 SSH 客户端，WindTerm 或 MobaXterm 更保险。

本文基于仓库 README（main 分支）、go.mod、releases API v0.1.8 与 repo_cards/4713 采集。写作只读公开内容，未 clone、未运行代码。文中标注 ⚠️ 的条目为作者自身风险提示或 README 明确声明的边界，非推测。