远程开发
ZCode 远程开发用于把工作区放到远程主机、WSL 发行版或本机容器里运行。连接成功后，文件读取、终端命令、Git 操作和 ZCode Agent 都会在目标环境内执行；桌面端仍负责账号、模型配置、任务入口和界面交互。
这适合需要在服务器、内网机器、GPU 开发机或容器环境中工作的项目。你可以在本机继续使用 ZCode 的桌面体验，同时让 Agent 直接访问目标环境里的代码、依赖和命令行。
适合什么场景
- 项目代码和依赖只在远程 Linux 服务器上可用。
- 需要使用远程机器上的 GPU、内网服务、数据库或专用工具链。
- 在 Windows 上开发，但项目依赖 Linux 环境，希望直接在 WSL 里跑。
- 想在本机 Docker 容器中隔离项目依赖，不污染本机环境。
- 本机性能或系统环境不适合直接运行项目，但仍希望使用 ZCode Agent 完成开发、调试和验证。
连接前准备
目标环境需要 POSIX shell。 当前不支持连接原生 Windows 远程主机。如果你要用的是 Windows 本机上的 Linux 环境，请选择 WSL。
使用 SSH 连接前，请先确认：
- 本机可以通过 SSH 访问目标主机。
- 你知道主机地址、端口和用户名。
- 目标主机支持密码登录，或你已经准备好私钥文件和可选的私钥口令。
- 如果使用
~/.ssh/config，可以先在终端执行ssh <Host别名>验证别名可用。
使用 WSL 连接前，请先确认：
- 你在 Windows 桌面端，这是 WSL 入口出现的前提。
- 本机已经安装 WSL，并且至少有一个发行版可用。
- 想指定某个 Linux 用户时，确认该用户在发行版里确实存在。
使用 Docker 连接前，请先确认：
- 本机 Docker daemon 正在运行。
- 目标容器已经启动。
- 容器内能访问项目目录，并具备项目运行需要的 shell、Git、Node.js 或其他工具链。
- 如果容器列表没有显示目标容器，你仍可以手动输入容器名或容器 ID。
从 ZCode 打开远程连接
在左侧边栏的 项目 区域点击右侧的 +，选择 远程连接。新任务页的工作区选择器里也能进入，主界面右下角的项目名称菜单同样保留了这个入口。
向导会先让你选择连接方式：
| 方式 | 连到哪里 | 出现条件 |
|---|---|---|
| SSH | 远程主机 | 全平台 |
| WSL | 本机的 Windows Linux 子系统 | 仅 Windows 桌面端 |
| Docker | 本机正在运行的容器 | 全平台 |
选择方式后点击 下一步，进入对应的配置页面。向导左侧会显示当前步骤：选择方式、填写配置、连接中、选择目录。连接过程较慢时，可以根据日志判断当前进度。
使用 SSH 连接远程主机
SSH 页面用于填写远程主机的连接信息。
你可以按下面顺序配置：
- SSH 配置别名（可选）：ZCode 会读取本机 SSH config 中的可用别名。选择别名后，会自动填充主机、端口、用户名和私钥路径。没有别名时，保留“不使用别名”并手动填写即可。注意：ZCode 使用内置 SSH 客户端直连，别名只用于预填以上四个字段——
ProxyJump/ProxyCommand等跳板配置不会生效，含跳板的别名会被当作直连主机处理。需要经跳板访问的主机，请先在本地建立端口转发（如ssh -L），再让 ZCode 连接转发端口。 - 主机：填写远程主机地址或 IP，例如
192.168.1.100、dev.example.com。 - 端口：默认是
22。如果服务器使用跳板端口或自定义端口，请改成实际端口。 - 用户名：填写远程登录用户，例如
root、ubuntu、deploy。 - 认证方式：选择 密码 或 私钥。私钥方式需要填写私钥文件路径，私钥有口令时再填写私钥口令。密码和私钥口令不会明文写进连接历史；连接成功后它们会加密保存在本机的凭据存储里，供之后重连使用。
- 资源下载方式：首次连接时，ZCode 会准备远端运行所需组件。默认 本地下载后上传 由本机下载资源后传到远端；远端服务器下载 会让远端直接访问 ZCode CDN，可减少上传等待，但远端需要能联网，并具备下载、解压和校验工具。
填写完成后点击 开始连接。连接成功后，ZCode 会进入远端目录选择步骤，你可以选择要作为工作区打开的目录。
使用 WSL 连接本机 Linux 子系统
WSL 入口 只在 Windows 桌面端显示，适合项目依赖 Linux 工具链或运行环境的场景。
连接配置只有两项，均可留空：
- 发行版：ZCode 会检测本机已安装的 WSL 发行版供你选择。留空时连接系统默认发行版。即使没有检测到发行版，也可以保留为空，直接尝试连接默认发行版。
- Linux 用户：决定 ZCode 在 WSL 中以哪个用户身份工作。留空时使用该发行版的默认用户；填写后，Agent、终端命令、Git 操作以及文件的读取和创建都会使用这个用户的身份和权限。填写的用户必须已存在于该发行版中。
请谨慎使用 root。 以 root 连接后，在工作区中新建的文件可能归 root 所有，之后使用普通用户时可能无法修改。除非确有必要，建议使用日常开发所用的普通用户。
连接成功并选择工作区目录后，文件读写、终端命令、Git 操作和 Agent 都会在所选的 WSL 环境中执行。和 SSH 一样，WSL 也支持将本机的 Skills、MCP 配置和 Plugins 手动同步到当前 WSL 用户的环境中。
使用 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 都在目标环境内；模型供应商、登录账号、全局设置和用量信息仍保存在桌面端。
把本地配置同步到远端
远程工作区里的 Agent 跑在目标主机上，因此本机装的技能、配置的 MCP 服务器和插件默认不会跟过去。ZCode 提供了三个同步入口，把它们一次性搬到远端。
入口有好几处。最早的一处在连接向导里——SSH 和 WSL 走到 选择远程目录 这一步时，就已经可以先把配置同步过去，不必等工作区打开。连上之后，工作区标题栏的 同步 下拉里有三项：同步 Skill、同步 MCP、同步 Plugin；侧边栏工作区行的「更多」菜单，以及设置里对应的技能、MCP、插件页面也都有同一入口。本地工作区不显示这些菜单。
| 同步项 | 同步什么 |
|---|---|
| Skill | 你本机的 用户级 技能 |
| MCP | 你本机的 用户级 MCP 服务器配置 |
| Plugin | 你本机的用户级插件；来自市场的插件会在远端重新安装 |
三者的共同规则：
- 逐条勾选、手动触发，不会自动同步。
- 远端已存在同名项一律跳过，不覆盖，列表里会标出来并默认不勾选。
- 只同步 用户级 内容。项目级技能、工作区级 MCP、插件自带的 MCP 都不在范围内。
- 如果远端目录写不进去，或者连接超时，ZCode 会在开始复制前就告诉你。
- 部分失败不影响已成功的项，失败项会单独列出原因。
有几点需要特别留意：
同步不保证能用。 远端是否装了 npx、Python 依赖或技能需要的命令行工具，ZCode 不做检查。同步过去的东西起不来，通常要你到远端手动补依赖。
MCP 配置里的密钥会原样写到远端配置文件。 如果 MCP 服务器配置里有 API Key 或 Authorization 头，同步会把它们一起写过去，所以只对你信任的主机做这个操作。
插件的敏感配置项不会同步。 标记为敏感的配置和路径类配置会被跳过，界面会提示还有几项需要你在远端手动填。另外市场插件是在远端重新安装的，远端需要能访问对应的市场地址。
同步过去的插件会在远端执行。 插件里的技能、命令、Hooks 和 MCP 都会在远端环境里加载运行，同步前请确认插件来源可靠。
目前 SSH 和 WSL 远程支持这些同步操作。
常见问题
为什么 SSH 配置别名没有出现？
ZCode 会读取本机 SSH config 中可解析的别名。如果列表为空，可以先检查 ~/.ssh/config 是否存在、格式是否正确，并在终端执行 ssh <别名> 验证。即使别名没有出现，也可以手动填写主机、端口、用户名和认证信息。
什么时候选择“远端服务器下载”？
当远端服务器访问 ZCode CDN 更快，或者本机上传到远端很慢时，可以选择 远端服务器下载。远端需要具备 curl 或 wget、tar，以及 sha256sum、shasum 或 openssl 中的校验工具。远端无法访问公网时（内网、离线环境），使用默认的 本地下载后上传：由本机下载全部组件后经 SFTP 传到远端并安装到 ~/.zcode/server，远端全程无需联网。
远程连接会走设置里的 HTTP 代理吗？
不会。SSH 连接和 Web 远程控制通道都不经过设置中的 HTTP 代理，代理只覆盖模型、MCP 等出网请求——完整范围见 HTTP 代理的作用范围。远端服务器自身需要代理时，请在远端 shell 环境中自行配置。
Docker 页面没有容器怎么办？
先在终端执行：
docker ps
如果没有运行中的容器，请先启动容器。如果终端里能看到容器，但 ZCode 列表为空，可以手动输入容器名或容器 ID 后连接。
连接失败时应该看哪里？
优先看 连接日志 最后一条 ERROR 或页面底部的错误摘要。常见原因包括 SSH 主机不可达、端口错误、用户名或密码错误、私钥口令错误、远端缺少下载 / 解压工具、Docker 容器未运行。错误信息不足时，点击 去反馈 提交日志。
手机 Remote Control 能新建或连接远程工作区吗？
不能创建全新的 SSH、WSL 或 Docker 连接——填写连接参数这一步必须在桌面端完成。但如果某个远程工作区已经登记在当前桌面窗口里、只是显示为断开，Remote Control 可以对它发起重新连接，实际连接过程仍由桌面端执行。