远程开发

ZCode 远程开发用于把工作区放到远程主机或本机容器里运行。连接成功后，文件读取、终端命令、Git 操作和 ZCode Agent 都会在目标环境内执行；桌面端仍负责账号、模型配置、任务入口和界面交互。

这适合需要在服务器、内网机器、GPU 开发机或容器环境中工作的项目。你可以在本机继续使用 ZCode 的桌面体验，同时让 Agent 直接访问目标环境里的代码、依赖和命令行。

适合什么场景

• 项目代码和依赖只在远程 Linux 服务器上可用。
• 需要使用远程机器上的 GPU、内网服务、数据库或专用工具链。
• 想在本机 Docker 容器中隔离项目依赖，不污染本机环境。
• 本机性能或系统环境不适合直接运行项目，但仍希望使用 ZCode Agent 完成开发、调试和验证。

连接前准备

使用 SSH 连接前，请先确认：

• 本机可以通过 SSH 访问目标主机。
• 你知道主机地址、端口和用户名。
• 目标主机支持密码登录，或你已经准备好私钥文件和可选的私钥口令。
• 如果使用 ~/.ssh/config，可以先在终端执行 ssh <Host别名> 验证别名可用。

使用 Docker 连接前，请先确认：

• 本机 Docker daemon 正在运行。
• 目标容器已经启动。
• 容器内能访问项目目录，并具备项目运行需要的 shell、Git、Node.js 或其他工具链。
• 如果容器列表没有显示目标容器，你仍可以手动输入容器名或容器 ID。

从 ZCode 打开远程连接

在 ZCode 主界面右下角点击当前项目名称，打开工作区菜单，然后选择 远程连接。向导会先让你选择连接方式：SSH 用于连接远程主机，Docker 用于连接本机容器。

选择方式后点击 下一步，进入对应的配置页面。向导左侧会显示当前步骤：选择方式、填写配置、连接中、选择目录。连接过程较慢时，可以根据日志判断当前进度。

使用 SSH 连接远程主机

SSH 页面用于填写远程主机的连接信息。

你可以按下面顺序配置：

1. SSH 配置别名（可选）：ZCode 会读取本机 SSH config 中的可用别名。选择别名后，会自动填充主机、端口、用户名和私钥路径。没有别名时，保留“不使用别名”并手动填写即可。
2. 主机：填写远程主机地址或 IP，例如 192.168.1.100、dev.example.com。
3. 端口：默认是 22。如果服务器使用跳板端口或自定义端口，请改成实际端口。
4. 用户名：填写远程登录用户，例如 root、ubuntu、deploy。
5. 认证方式：选择 密码 或 私钥。密码不会写入连接历史；私钥方式需要填写私钥文件路径，私钥有口令时再填写私钥口令。
6. 资源下载方式：首次连接时，ZCode 会准备远端运行所需组件。默认 本地下载后上传 由本机下载资源后传到远端；远端服务器下载 会让远端直接访问 ZCode CDN，可减少上传等待，但远端需要能联网，并具备下载、解压和校验工具。

填写完成后点击 开始连接。连接成功后，ZCode 会进入远端目录选择步骤，你可以选择要作为工作区打开的目录。

使用 Docker 连接本机容器

Docker 页面用于选择或填写本机正在运行的容器。

如果 ZCode 检测到运行中的容器，可以从 选择正在运行的容器 中选择。打开下拉框时，ZCode 会刷新一次容器列表，避免使用已经停止的旧容器。

如果列表为空，或 Docker 当前没有返回完整列表，可以在 容器 输入框中手动填写容器名或容器 ID，例如：

zcode-dev
7f3a8c2d9e10

Docker 连接通过 docker exec 和 docker cp 进入本机容器。它适合连接已经准备好项目环境的开发容器；如果容器尚未启动，请先在终端运行 docker ps 确认可见。

首次连接与连接日志

点击 开始连接 后，向导会进入 连接中 页面。这里会显示实时连接日志，包括环境检测、远端资源准备、运行时初始化和失败原因。

首次连接通常比后续连接慢，因为 ZCode 需要在目标环境准备远端服务和 Agent runtime。后续连接会复用已准备好的资源，只在版本变化或资源缺失时重新安装。

如果连接失败，页面底部会显示错误摘要。你可以点击 上一步 修改配置后重试，也可以点击 去反馈，ZCode 会带上当前连接日志和截图，方便排查问题。

进入远程工作区后

连接成功并选择目录后，ZCode 会把该目录作为远程工作区打开。进入后你可以像本地工作区一样使用：

• 在文件树中查看和编辑远程文件。
• 让 Agent 阅读代码、修改文件、运行测试或执行命令。
• 使用终端操作远程主机或容器内的 shell。
• 使用 Git 查看状态、分支和提交。
• 从左侧工作区列表重新进入或重新连接最近使用的远程工作区。

需要注意的是，远程工作区的项目文件、命令执行和 Agent runtime 都在目标环境内；模型供应商、登录账号、全局设置和用量信息仍保存在桌面端。

常见问题

为什么 SSH 配置别名没有出现？

ZCode 会读取本机 SSH config 中可解析的别名。如果列表为空，可以先检查 ~/.ssh/config 是否存在、格式是否正确，并在终端执行 ssh <别名> 验证。即使别名没有出现，也可以手动填写主机、端口、用户名和认证信息。

什么时候选择“远端服务器下载”？

当远端服务器访问 ZCode CDN 更快，或者本机上传到远端很慢时，可以选择 远端服务器下载。远端需要具备 curl 或 wget、tar，以及 sha256sum、shasum 或 openssl 中的校验工具。远端无法访问公网时，建议使用默认的 本地下载后上传。

Docker 页面没有容器怎么办？

先在终端执行：

docker ps

如果没有运行中的容器，请先启动容器。如果终端里能看到容器，但 ZCode 列表为空，可以手动输入容器名或容器 ID 后连接。

连接失败时应该看哪里？

优先看 连接日志 最后一条 ERROR 或页面底部的错误摘要。常见原因包括 SSH 主机不可达、端口错误、用户名或密码错误、私钥口令错误、远端缺少下载 / 解压工具、Docker 容器未运行。错误信息不足时，点击 去反馈 提交日志。

手机 Remote Control 能直接新建 SSH 或 Docker 连接吗？

不能。手机 Remote Control 用于控制桌面端已经打开的工作区。SSH 和 Docker 远程工作区需要先在桌面端建立，之后手机端可以通过 Remote Control 进入已打开的工作区继续查看和输入指令。

下一步