使用文档

适用于 Roamtty Android 版与 iOS 版。其他问题请看支持页面或发邮件至 support@roamtty.com。

Roamtty 是 SSH 客户端：AI 编程工具（Claude Code、Codex、Grok 等）运行在你自己的服务器上，Roamtty 在手机上启动它们、显示状态，并让你顺手地操作终端。应用没有后端服务器，连接只发往你添加的主机。

快速开始

1. 在服务器上开启 SSH，装好并登录 AI 命令行工具。
2. 在 Roamtty 主机页点 + 添加主机，再在主机菜单中选“安装插件”装上 tmux 和 mosh。
3. 点“AI Agent”，选文件夹，开始工作。锁屏或断网后任务仍在服务器上运行，回来自动接上。

手机不在服务器所在的网络时，用 Tailscale 连回去，不必把 SSH 暴露在公网。

准备服务器

任何能 SSH 登录的 Linux、macOS、BSD 或 Windows 主机都可以。

• Ubuntu / Debian：sudo apt install openssh-server
• macOS：系统设置 → 通用 → 共享 → 打开“远程登录”
• Windows：可选功能中添加“OpenSSH 服务器”，再在管理员 PowerShell 中运行 Start-Service sshd

然后按官方说明安装 claude、codex 或 grok，先在服务器上登录一次。Roamtty 不会经手你的账号或 API Key。

tmux（断线后任务继续运行）和 mosh（换网络不掉线）不用手动装：在主机菜单中选“安装插件”，应用会用主机的包管理器安装（Linux 需 sudo，sudo 密码不保存；macOS 用 Homebrew；Windows 用 winget 装 psmux）。

添加主机

在主机页点 +，填名称、地址（域名、局域网 IP 或 Tailscale 的 100.x.y.z）、用户名和端口。

认证方式可选密码、私钥（Ed25519 / RSA，支持加密私钥）或交互式认证（一次性验证码等）。密码只在勾选“在本机加密保存密码”时保存。会话模式保持默认的 tmux。

首次连接会弹出服务器的 SHA-256 指纹，点“信任并连接”即可。

可选：核对指纹

想确认连上的确实是自己的服务器（比如在公共 Wi-Fi 上），可在服务器上运行下面的命令，看输出中的 SHA256:… 是否与应用显示的一致：

for f in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf "$f"; done

以后指纹变化时连接会被阻止；确认是服务器重装或换了密钥后，在主机菜单中选“重新核验…”。

主机卡片显示系统图标、在线状态与建连延时；卡片右侧的 ⋮ 菜单可打开终端、查看文件、启动 AI Agent、安装插件、编辑或删除主机。

启动 AI Agent

点“AI Agent”（或主机菜单中的同名项），选择起始文件夹、Agent 和权限模式：

• 计划 / 只读：Claude Code 先出计划，批准后才修改；Codex、Grok 以只读沙箱运行。
• 普通：改文件或运行命令前先问你。
• YOLO：跳过所有确认，只在信任任务与环境时使用。

应用记住上次的选择，常用文件夹显示在顶部。“打开终端”则打开普通 shell。

会话列表

首页按待确认、运行中、已完成分组列出所有会话，卡片标题是 Agent 当前的任务。

• 等待确认的卡片上点“允许”，不用打开终端即可批准。
• 已完成的卡片显示回答摘要，点“追问”直接输入下一条指令。
• 每个会话是服务器上独立的 tmux 会话。锁屏、断网或关掉应用后任务继续运行，点卡片即重新附着。
• 卡片菜单中的“关闭”会结束远端任务；服务器连不上时长按卡片可强制删除，只移除手机上的卡片。
• 每台主机最多保留 8 个会话。

装有 mosh 时终端优先走 mosh（UDP），8 秒无回应自动回退到 SSH。

终端操作

光标行末尾常驻一个 Esc 键，停止输入后它变成回车键。

屏幕边缘拿扳手的小幽灵：按住弹出快捷键环（Esc、Ctrl、Shift、F1–F12 等，随前台的 Agent 变化），拖到键上松手即发送；点按展开操作栏：

• 会话菜单：返回主机详情、关闭或重启当前会话、切换到其他会话
• 上传文件 / 下载文件
• 插入图片：一次最多 9 张，上传后把远端路径填进命令行，方便发给 Agent
• 常用命令：读取服务器上的 shell 历史，点一条即执行
• 设置：编辑文本（在大输入框里写好长提示词再发送）、固定或隐藏操作栏、粘贴、调整字号

文件与监控

主机菜单中的“查看文件”通过 SFTP 浏览服务器：预览代码（带语法高亮）、Markdown 和图片并在文件中查找，重命名、删除、新建文件夹、复制路径、单个或批量下载，或在当前文件夹直接打开终端、启动 AI Agent。首次下载时选择手机上的下载目录，之后自动保存到那里。在相册等应用中把图片分享给 Roamtty 即可上传到服务器。

点主机卡片进入详情页，实时查看 CPU、内存、磁盘、网络、GPU 和占用最高的进程，适合确认构建或测试是否卡住；顶部按钮可直接启动 AI Agent、打开终端或查看文件。

远程桌面

能开桌面的主机会在会话卡片右下角显示桌面按钮；没有会话的主机，在主机详情页点“桌面”。第一次打开时应用会自动安装桌面插件，不需要填任何配置。退出桌面页后连接在后台保持（默认 10 分钟，可在设置里修改），再点约 1 秒回到画面。

桌面页的工具栏（竖屏在底部，横屏在右侧）有“操作”、“键盘”、“显示桌面”和“所有窗口”。

在“操作”里可以切换屏幕触控和鼠标指针两种方式，还能传文件、同步剪贴板、打开电脑的声音、调整帧率和画质。键盘支持把打好的中文直接发到电脑。

• Linux：X11 桌面；Wayland 支持 wlroots 系合成器（sway、Hyprland、labwc、river）。GNOME、KDE 的 Wayland 会话暂不支持，可在登录界面选 X11 会话。
• macOS 13 及以上：第一次打开时，在 Mac 的“系统设置 › 隐私与安全性”里为 Roamtty Desktop 打开“屏幕与系统音频录制”和“辅助功能”。
• Windows 10 1903 及以上、Windows 11：需要已在电脑上登录桌面。

画面可用时走 UDP（端口 60000–61000，和 mosh 相同），被防火墙挡住时自动改走 SSH。同一台电脑同时只能由一台手机控制。没有图形桌面的服务器不显示按钮。

设置

左上角菜单 →“设置”：

• 外观：跟随系统、深色或浅色
• 终端字体：内置多款等宽字体，也可导入自定义 TTF / OTF 字体，并带 Nerd Font 图标回退
• 语言：简体中文或 English
• 下载目录：下载的文件保存到哪里

同一菜单中的“帮助”有一份手势与操作的速查。

后台与锁屏

Agent 等你确认或做完一轮时，应用会发通知，点通知直接进入对应会话；可在设置 → 通知里选择全部提醒、只在等你确认时提醒或关闭。

• Android：在设置中打开“允许后台运行”并取消电池优化；小米、华为、OPPO、vivo 等还需允许自启动并在最近任务中锁定；OPPO、一加、realme（ColorOS）还要在 应用详情 → 耗电管理 选“完全允许后台行为”，否则退到后台几秒后网络就被断开，Agent 通知也要等回到应用才到（设置 → 后台连接 里有入口）。有连接时通知栏常驻一条 Roamtty 通知（可在 设置 → 通知 →“隐藏后台连接通知”里关掉，连接不受影响）；Agent 等你确认或做完一轮时另发一条通知，点它直接进入那个会话。
• iPhone：系统会在后台暂停网络连接。任务在服务器的 tmux 里继续运行，回到应用时自动重连。应用离开屏幕约半分钟后，系统不再让它运行，之后的变化会在回到应用时提醒。

保证任务不中断的是服务器上的 tmux，而不是手机一直在线。

从外网连接：Tailscale

Tailscale 把手机和服务器放进同一个加密虚拟局域网，每台设备得到固定的 100.x.y.z 地址；服务器不需要公网 IP，也不用开放端口。Roamtty 无需任何设置，流量经系统 VPN 走隧道。

1. 服务器：Linux 运行下面的命令并在浏览器中登录；macOS、Windows 从 tailscale.com/download 安装。

   curl -fsSL https://tailscale.com/install.sh | sh
   sudo tailscale up

2. 手机：安装 Tailscale App，用同一个账号登录。
3. 在 Roamtty 中用服务器的 100.x.y.z 地址（tailscale ip -4）添加主机。

• 先连上 Tailscale 再打开 Roamtty；手机同一时间只能开一个 VPN。
• mosh 在隧道内直接可用，无需放行 UDP 端口。
• 使用服务器自己的 OpenSSH，不要开启 Tailscale SSH（--ssh），否则主机指纹会变。
• 在 Tailscale 后台对服务器关闭密钥过期（Disable key expiry），以免几个月后在外面突然连不上。
• 延时偏高时在服务器上运行 tailscale ping <手机的 100.x 地址>，显示 via DERP 说明在走中继，可自建 DERP（见下）。

# 安装（版本见 GitHub Releases，写作时为 0.29.5）
wget -O headscale.deb https://github.com/juanfont/headscale/releases/download/v0.29.5/headscale_0.29.5_linux_amd64.deb
sudo apt install ./headscale.deb

server_url: https://hs.example.com
listen_addr: 127.0.0.1:8080
dns:
  magic_dns: true
  base_domain: ts.example.net   # 不能与 server_url 的域名相同

hs.example.com {
    reverse_proxy 127.0.0.1:8080
}

sudo systemctl enable --now headscale && sudo systemctl reload caddy
sudo headscale users create me
sudo headscale preauthkeys create --user 1 --reusable --expiration 24h

derp:
  server:
    enabled: true
    region_id: 999
    region_code: "headscale"
    region_name: "Headscale Embedded DERP"
    verify_clients: true
    stun_listen_addr: "0.0.0.0:3478"
    private_key_path: /var/lib/headscale/derp_server_private.key
    automatically_add_embedded_derp_region: true
    ipv4: 203.0.113.10          # VPS 公网 IP
  urls:
    - https://controlplane.tailscale.com/derpmap/default   # 保留官方节点作后备
  paths: []

常见错误

仍未解决？发邮件至 support@roamtty.com（请勿附上密码、私钥或真实服务器地址）。