远程开发与管理

本指南介绍四项内容：让网络中的其他设备访问你的 VelaTerm、通过 SSH 或配对链接连接其他机器、通过 VelaTerm 账号与你自己的设备共享对话，以及在本机与远程机器之间传输文件。

1. 入口

远程相关功能位于标题栏右侧：

• 地球图标是远程访问（浏览器），可以让网络中的手机、平板或其他电脑通过网页浏览器使用这台机器上的 VelaTerm。服务运行期间，该图标以强调色高亮显示，其提示文字中还会显示「运行中 · 端口 N」。
• 箭头图标是连接远程服务，可以让这台机器通过 SSH、配对链接或你的 VelaTerm 账号，作为客户端连接另一台机器。
• 人像图标是账号入口，标有「实验性功能」。它用于在这台电脑上登录 VelaTerm 账号，并通过互联网与你已登录的其他设备共享对话。

旁边的「分享」按钮会打开「分享 VelaTerm」，用于向他人推荐 VelaTerm，不会共享任何会话。

2. 让其他设备访问这台机器（远程访问）

2.1 开启服务

点击地球按钮。选择「端口」（默认为 8799，并会记住你上次使用的端口）、配对链接使用的「IP」地址（「自动（第一个局域网地址）」或某个指定的网络接口；VPN 接口标有「VPN」），并设置访问密码（「设置访问密码」），然后点击「开启服务」。

每台连接的设备都需要输入访问密码。服务运行期间，面板会提示：「重新打开应用时远程访问会自动恢复，『停止服务』可关闭此功能。」如果之后启动应用时自动启动失败，面板会显示「自动启动失败：」及其原因。

「多端界面镜像」复选框默认勾选。勾选后，所有已连接设备上的标签页、分屏和当前会话保持一致，而键盘焦点在各设备上相互独立。如果希望每台设备各自安排标签页，请取消勾选。

2.2 连接设备

服务运行后，面板会显示运行状态、「证书指纹（SHA-256）」、配对链接和二维码：

要连接设备，可以用该设备的相机扫描二维码，或者将配对链接发送到该设备（例如通过隔空投送或发给自己的消息），然后在浏览器中打开链接并输入访问密码。配对链接和密码缺一不可；不通过配对链接而直接打开地址时，会显示「此服务要求使用配对链接访问。」浏览器与这台机器之间的通信采用端到端加密。

有两点与安全相关：

• 配对链接中带有访问凭据，请只分享给你自己的设备。如果你认为链接已经泄露，请点击「重新生成链接（踢掉全部设备）」：旧链接会立即失效，所有已连接的设备都会断开，直到它们打开新链接为止。
• 首次访问时，浏览器会警告证书不受信任，这对于自签名证书是正常现象。请将浏览器显示的指纹与面板中的指纹进行比对；如果两者一致，说明你连接的正是自己的机器。

如果机器有多个网络接口（有线、Wi-Fi、VPN），面板会显示首选地址，并将其他地址列在「其它 N 个链接」下。请选择与待连接设备处于同一网络的地址。

VelaTerm 重启后，配对链接依然有效。只有「重新生成链接（踢掉全部设备）」会替换它们。

2.3 浏览器客户端的功能

已连接设备上的登录页面和主界面：

浏览器客户端与桌面版操作的是同一批正在运行的会话：项目树相同，终端和对话输出也相同，任何一端都可以输入。开启「多端界面镜像」后，主机的标题栏会显示「被 N 端镜像」；点击即可查看「已连接的客户端」，包括它们的名称、地址和连接时间。客户端名称由客户端自行上报，因此只能当作标签，不能作为身份证明。

同一个终端在多台设备上打开时，其尺寸以其中一台设备为准。其他设备显示的是缩放后的副本，终端右上角带有「⤢ 镜像 … · 点击适配本窗口」标记；点击即可按当前窗口调整终端尺寸。

浏览器客户端不提供浏览器标签页，也没有原生图片粘贴选项，但可以在「文件」标签页中上传和下载文件（§5）。

2.4 已配对设备

在运行中的面板里点击「已配对设备」，即可查看所有连接过的设备及其「最后连接」时间：

要禁止某台设备访问，请点击「禁止访问」，然后点击「确认禁止」。该设备会立即断开，并且在打开新的配对链接之前无法重新连接；其他设备不受影响。如需一次断开所有设备，请使用「重新生成链接（踢掉全部设备）」。

2.5 停止服务

点击面板底部的「停止服务」。浏览器客户端会断开连接，正在运行的会话则继续运行，因为它们属于桌面版。停止服务也会关闭自动启动；下次开启服务时，需要重新输入访问密码。

3. 连接其他机器

点击标题栏中的连接按钮。面板包含三个标签页：「SSH」「URL」和「Remote」。

3.1 SSH：远程机器只需提供 SSH

此方式适用于没有安装任何 VelaTerm 组件的远程机器。远程机器可以运行 Linux（x86_64 或 ARM64）、macOS（Apple 芯片或 Intel）或 Windows（x86_64）；Windows 机器可以使用微软的 OpenSSH 服务器，或 Cygwin、MSYS2 的 SSH 服务器。连接时会自动完成全部配置：VelaTerm 检测远程系统，将对应的 VelaTerm 服务端复制过去，启动服务端并使其独立持续运行，将本地端口转发到服务端，然后打开一个自动登录的远程窗口。

输入 user@host[:port]，然后点击「连接」。以下细节值得了解：

主机密钥验证。首次连接某台主机时，会显示其「SSH 主机指纹」，并提示「首次连接这台主机，请核对指纹一致后再继续。」核对无误后点击「指纹无误，连接」；密钥会保存到 known_hosts 中，之后不会再次询问。如果已知主机的密钥发生变化，会出现红色警告：「⚠ 这台主机的密钥变了：可能是服务器重装，也可能是中间人攻击。确认无误再继续。」请先查明原因，再进行确认。

身份验证。VelaTerm 会直接使用你现有的 SSH 配置（ssh-agent、~/.ssh/config 和密钥）。只有在密钥认证失败时，才会出现「SSH 密码」输入框。「记住密码」会将密码保存在系统钥匙串中（绝不会保存到数据库），并在下次连接时使用。

镜像远端桌面版。此选项默认关闭，并按主机分别记忆。如果远程机器上也在运行 VelaTerm 桌面版，而你希望看到与之完全相同的界面（相同的标签页、分屏和当前会话，任何一端的改动都会同步到两端），请开启此选项。如果远程机器上的桌面版没有运行，VelaTerm 会直接打开其数据库；如果没有该数据库，则使用单独的数据库。不开启此选项时，远程服务端使用自己的数据目录（~/.velaterm/data，Windows 上为 %USERPROFILE%\.velaterm\data），与远程机器上安装的桌面版相互独立。

在镜像关闭的情况下，按住 Option（Windows 和 Linux 上为 Alt）点击连接按钮，会多显示一个选项「复用远端桌面版的数据库」。它让远程服务端打开远端桌面版的数据库，但不接入正在运行的桌面版。建议两者使用相同的 VelaTerm 版本。

最近连接。连接过的主机会列在「最近连接」下（「查看全部 (N)」可显示完整列表）。点击某一项只会填入表单；检查无误后，再点击「连接」。钥匙图标表示已保存密码，×（「忘记此主机」）会移除该主机及其已保存的密码。

进度。首次连接时需要复制服务端（数十 MB），按钮上会依次显示「准备服务端…」「传输服务端…」和「启动服务端…」及百分比。之后的连接会复用远程机器上已有的服务端，速度要快得多。

3.2 URL：对方机器已开启远程访问

如果另一台机器上的 VelaTerm 已开启远程访问（§2），并且你有它的配对链接，可以使用此方式。与在网页浏览器中打开链接相比，这种方式提供独立的窗口、使用系统钥匙串中保存的密码自动登录，并由应用负责核对指纹。

粘贴配对链接，输入对方机器上设置的「登录密码」，然后点击「连接」。首次连接时会显示对方机器的 TLS 证书指纹，请将其与该机器面板中显示的「证书指纹（SHA-256）」进行比对。之后如果指纹未变，会直接连接；如果指纹发生变化，则会显示红色警告。与 SSH 主机一样，最近使用的配对链接会列在表单下方。

3.3 Remote：登录同一账号的设备

「Remote」标签页列出已登录你的 VelaTerm 账号的设备（§4）。每台设备都会显示「在线」或「离线」及其共享的内容，例如「整个工作空间」、某个项目或某段对话；未共享时显示「此设备尚未共享内容。」设备在线且正在共享时，点击「查看共享内容 →」即可在新窗口中打开其共享内容。如果尚未登录，该标签页会显示「登录 VelaTerm」链接。

4. 通过 VelaTerm 账号共享（实验性功能）

借助账号共享，你可以通过互联网在其他设备上继续某台电脑上正在进行的 AI 对话，无需开放端口，也无需处于同一网络。共享内容经由 velaterm.com 传输，并采用端到端加密。此功能目前处于实验阶段。

4.1 登录

点击标题栏中的账号按钮。「账号」对话框中会显示「登录 VelaTerm」，点击后在网页浏览器中继续操作。VelaTerm 等待期间会显示「请在浏览器中完成登录，然后返回 VelaTerm。」你可以展开「登录请求详情」，将其与网站上显示的请求进行比对。

登录后，对话框会显示你的名称和「账号 ID：」、一个用于打开 velaterm.com 上账号页面的「账号」按钮，以及「退出登录」。退出登录会断开这台电脑的连接，并停止它共享的所有内容。

4.2 共享内容

在「开始共享」下选择「共享范围」：「整个工作空间」「项目」或「会话」。如果选择项目或会话，请从列表中选中具体对象，然后点击「开始共享」。每个共享项都会显示在「共享中」下，并附有其状态（「共享中」或「共享未就绪」）和「停止共享」按钮。可以同时共享多项内容。重启后共享依然有效，但只有在这台电脑运行 VelaTerm 且在线时才能访问。

共享的只有 AI 对话。普通终端和浏览器页面永远不会被共享，查看共享内容的设备也无法打开终端、文件、设置或新标签页。

4.3 在其他设备上打开共享内容

在登录同一账号的另一台设备上，打开连接按钮中的「Remote」标签页（§3.3），然后点击「查看共享内容 →」。你可以查看共享的对话。对于共享电脑上以会话视图显示的会话，你还可以发送消息、中断智能体并答复其权限请求；对于其他会话，窗口会说明需要主机先将该会话切换到会话视图。

请注意，AI 智能体以共享电脑上当前用户的权限执行操作：它可以在该电脑上运行命令和修改文件。任何能够继续共享对话的人都可以指挥智能体，因此请只与你自己控制的设备共享，并在不再需要访问时使用「停止共享」。

5. 传输文件

在浏览器客户端以及 URL 和 SSH 远程窗口中，右栏的「文件」标签页可以在你的设备与运行会话的机器之间传输文件。本地桌面版不需要此功能，因此不会显示这些操作。

• 上传：右键点击文件夹或其中的文件，选择「上传文件…」；或点击「文件」标签页顶部的上传按钮（「把文件上传到这个目录」）；也可以将文件拖到文件树上。不支持上传文件夹。
• 下载：右键点击文件，选择「下载」。在网页浏览器中，文件由浏览器自身的下载管理器处理。在 URL 或 SSH 远程窗口中，会弹出保存对话框，询问文件的存放位置（默认为“下载”文件夹）。

上传任务以及远程窗口中的下载任务会显示在「传输」列表中，并附有大小、速度和剩余时间。点击取消按钮可停止某一项，点击「清空」可移除已完成的项。如果上传过程中连接中断，该项会显示「正在重连…」，VelaTerm 会持续重试约一分钟。中断的上传不会在目标位置留下不完整的文件，再次上传同一文件时会从中断处继续。

6. 在手机上使用 VelaTerm

在手机浏览器中打开配对链接（§2.2），例如扫描远程访问面板中的二维码。在手机上，VelaTerm 会切换为专为小尺寸触摸屏设计的布局。布局在页面加载时确定：屏幕短边小于 768 像素的触摸设备会使用该布局。在地址后加上 ?view=mobile 或 ?view=desktop 可以自行选择布局（平板也可以使用 ?view=mobile），也可以在「更多操作」（•••）菜单中选择「切换到桌面版」；你的选择会被记住。

移动端布局分为两级：

• 会话列表：项目树，附带搜索框（「搜索会话 / 分组…」）和状态筛选（「工作中」「等待处理」「已查看」）。会话需要在桌面版或电脑浏览器中创建，创建后会自动出现在这里。
• 会话页面：轻点会话即可打开，使用「‹ 返回」回到列表。处于会话视图的会话会显示完整对话。以终端视图运行的 Claude Code、Codex、OpenCode、Pi 和 OMP 会话会显示其对话，并提供一个输入框，输入的内容会发送到终端。其他会话会显示终端和一排按键栏：Esc、Tab、Ctrl（点击后会展开一排 Ctrl 组合键，如 ^C、^D、^R 和 ^W）、方向键、^C、键盘按钮，以及用于发送图片的相机按钮。滑动可滚动，轻点可调出键盘，长按可选中单词并「复制」。

移动端布局不显示浏览器标签页、文档标签页和分屏，不支持键盘快捷键，并且保持自己的视图，不跟随「多端界面镜像」。Kiro 会话以只读视图提供其历史记录。

VelaTerm iOS 版已在 App Store 上线，Android 版已在 Google Play 上线。

7. 断开、关闭以及保留的内容

7.1 三层状态

断开连接后“一切是否都还在”，取决于具体是哪一层：

只有第三层需要留意：只要远程服务端进程还在运行，你的会话就会继续运行。

7.2 关闭远程窗口

SSH：远程服务端是由这次连接启动的，因此关闭窗口时会弹出「Disconnect remote」（断开远程连接）对话框，提供三个选项。「Stop server」（停止服务端）会关闭远程机器上的服务端，并结束其中正在运行的会话。「Keep running」（保持运行）只断开当前窗口；下次连接该机器时会复用这个服务端，所有会话都完好无损。「Cancel」（取消）会保持窗口打开。如果希望智能体在你离开期间继续工作，请选择「Keep running」。

接入远端桌面版的 SSH 连接：如果通过「镜像远端桌面版」将窗口接入了正在运行的桌面版，关闭窗口只会断开连接，桌面版会继续运行。

URL：你只是以访客身份连接到一个已在运行的 VelaTerm。关闭窗口只意味着你离开；对方会继续运行，你回来时一切照旧。

7.3 连接中断

网络中断时，远程窗口顶部会出现红色提示条，显示「连接已断开，正在尝试重连…」，VelaTerm 会自动重试。正在运行的会话不受影响；在 SSH 模式下，远程服务端的运行不依赖于 SSH 连接。

在 SSH 窗口中，VelaTerm 还会自动重建 SSH 隧道（「SSH 链路已断，正在重建隧道…」）。如果放弃重试，提示条会显示「SSH 链路已断开，点击『立即重连』再试一次」；此时请点击「立即重连」。如果远程服务端本身已经停止，在该窗口中重连无济于事：请回到主窗口重新连接。连接时会检查远程服务端是否仍在运行：如果仍在运行，则复用它（所有会话都保留）；只有在它未运行时，才会启动新的服务端。

远程机器休眠、注销或重启时，SSH 模式的服务端及其正在运行的会话都会结束。项目树保存在磁盘上，不受影响。

7.4 速查表

8. 安全要点

• 密码（SSH 密码和远程登录密码）只有在你选择「记住密码」时才会保存，并且只保存在系统钥匙串中，绝不会保存到数据库。远程访问的密码仅以哈希形式保存，以便服务能够自动重启。
• 局域网浏览器访问使用带自签名证书的 TLS。配对链接中带有端到端加密所需的凭据，服务会拒绝不通过配对链接发起的连接。
• SSH 主机密钥和远程 TLS 证书采用首次使用即信任的方式：已知且未变化的目标直接连接，新目标需要确认一次，指纹发生变化时会显示红色警告。请先查明原因再确认。
• 可以随时禁止单台设备访问（§2.4），也可以随时重新生成配对链接。
• 账号共享仅限于 AI 对话，但这些对话中的智能体会以你在共享电脑上的权限执行操作（§4.3）。

如果标题栏显示「⚠ vX ≠ vY」标记，说明界面与其连接的 VelaTerm 服务报告的版本不同，部分功能可能无法配合使用。请更新 VelaTerm，使两者运行相同的版本。

9. 常见问题

窗口已连接，但左栏一直为空，或红色提示条始终不消失。远程服务端可能已经停止。请回到主窗口重新连接（§7.3）。

服务无法在 8799 端口上启动。该端口已被其他程序占用。请在面板中选择其他端口，然后重新开启。

浏览器提示证书不受信任。对于自签名证书，这是正常现象。请核对指纹后继续（§2.2）。

希望远程机器上的智能体在我离开期间继续工作。在 SSH 模式下，关闭窗口时选择「Keep running」。会话会在远程机器上继续运行，之后你可以重新连接，从中断处接着工作。

终端在手机上显示得很小。这是按另一台设备的尺寸缩放后的副本。轻点终端右上角标记中的「点击适配本窗口」，即可按手机屏幕调整终端尺寸。

我的电脑没有显示「查看共享内容」。只有当该电脑在线、登录了同一账号并且正在共享内容时，才会显示该按钮。请在该电脑上打开 VelaTerm，检查其「账号」对话框中的「共享中」一栏。