ZCode 远程能力全解析：远程开发、远程控制与机器人通道

用 AI 编程工具时，常常会遇到两类"不在场"的问题。

一类是代码不在本地：项目跑在服务器上，或者依赖 Linux 环境、GPU 资源，本机根本没法直接开发。另一类是人不在电脑前：Agent 正在跑长任务，你需要出门、开会或者通勤，中途想看看进度、补两句指令。

ZCode 针对这两类场景提供了三组能力：远程开发（Remote Development）决定代码在哪跑，远程控制（Remote Control）和机器人通道（Bot Channel）决定你在哪操作。三者经常被混为一谈，但定位完全不同。

先理清关系

功能	解决什么问题	代码运行位置	操作入口
远程开发	代码不在本地	远程主机 / WSL / Docker 容器	桌面端 ZCode
远程控制	人不在电脑前	桌面端原本的环境	手机浏览器
机器人通道	人不在电脑前，长期用	桌面端原本的环境	微信 / 飞书

简单来说：远程开发决定代码在哪跑，远程控制和机器人通道决定你在哪操作。后两者可以配合远程开发一起使用——比如你在桌面端通过 SSH 连接了一台远程服务器写代码，出门后用手机打开远程控制，看到的仍然是那个 SSH 工作区，指令依然发往远程服务器执行。

远程开发：把工作区搬到目标环境里

远程开发是 ZCode 的核心能力之一。连接成功后，文件读取、终端命令、Git 操作和 Agent 本身，全部在目标环境内执行。桌面端只负责界面交互、账号管理和模型配置。

适用场景

• 项目代码和依赖只在远程 Linux 服务器上
• 需要用到远程 GPU、内网服务、数据库或专用工具链
• 在 Windows 上开发，但项目依赖 Linux 环境
• 想用 Docker 容器隔离项目依赖
• 本机性能或环境不足以直接运行项目

目标环境需要支持 POSIX shell，当前不支持连接原生 Windows 远程主机。

三种连接方式

方式	目标环境	说明
SSH	远程主机	填主机、端口、用户名、密码或私钥
WSL	本机 Windows Linux 子系统	仅 Windows 桌面端可用
Docker	本机正在运行的容器	从运行中容器列表选择或手动填写容器名/ID

入口在左侧边栏"项目"区域，点击加号选择"远程连接"即可。也可以从新任务页的工作区选择器，或右下角的项目名称菜单进入。

SSH 连接要点

• 主机支持 IP 或域名，端口默认 22。
• 认证支持密码或私钥；私钥带口令的需要填写口令。
• 资源下载方式可选"本地下载后上传"或"远端服务器下载"，后者在远端访问 CDN 更快时更省时间。
• 如果本机有 ~/.ssh/config，ZCode 会自动读取别名并填充配置。
• 密码和私钥口令不会明文保存，连接成功后加密存储在本机凭据中。

WSL 连接要点

• 发行版和 Linux 用户都可以留空，留空则使用默认值。
• 谨慎使用 root。以 root 创建的文件之后可能无法被普通用户修改。

Docker 连接要点

• 从运行中的容器列表选择，或手动填写容器名/容器 ID。
• 需要确保容器已启动，且内部具备 shell、Git 等基础工具链。

连接过程与排错

连接分四步：选择方式、填写配置、连接中、选择目录。首次连接较慢，因为要在远端准备服务和 Agent runtime；后续连接会复用资源。

失败时优先看页面底部的错误摘要或连接日志里的 ERROR。常见原因包括主机不可达、端口错误、认证信息有误、远端缺少解压工具、Docker 容器未运行等。

本地配置同步到远端

远程工作区不会自动继承本机的 Skill、MCP 和插件，需要手动同步。入口有三处：连接向导的"选择远程目录"步骤、工作区标题栏的"同步"下拉菜单、侧边栏工作区的"更多"菜单。

同步规则：逐条勾选、手动触发；远端已有同名项跳过不覆盖；只同步用户级内容。目前仅 SSH 和 WSL 支持同步，Docker 暂不支持。

需要特别注意：

• 同步不检查远端是否安装了 npx、Python 依赖等工具。
• MCP 中的密钥会原样写入远端，只应对信任主机操作。
• 同步过去的插件会在远端执行，需确认来源可靠。

远程控制：临时离开也能管任务

远程控制解决的是人离开了电脑、还想继续管理任务的问题。

它不是把代码同步到手机，而是把桌面端窗口的控制界面开放给手机访问。手机连接后，可以查看和切换窗口中已打开的工作区、任务和会话，并继续向 Agent 发送指令。

怎么用

1. 点击 ZCode 左下角侧栏的手机图标，打开"移动端远程控制"弹窗。
2. 扫描弹窗左侧的二维码，或复制链接在手机浏览器中打开。

连接成功后，手机端接入的是整个桌面窗口，不是扫码时停留的那个工作区。桌面上已打开的所有工作区，手机端都能查看和切换。

手机端能做什么

• 按工作区或时间线查看任务，按创建/更新时间排序，刷新状态。
• 在已有工作区中新建任务。
• 对暂时断开的远程工作区发起重新连接。
• 进入会话页查看 Agent 回复、执行过程和进度。
• 在底部输入框继续发送指令，复制内容，进行反馈，或分叉会话。

安全注意事项

• 关闭弹窗不等于停止远控，必须点击"停止"才会真正断开。
• 连接地址本身携带授权信息，相当于临时访问凭证，不要公开发布或转发。
• 怀疑地址泄露时，刷新二维码可使旧地址立即失效。
• 远控期间桌面端需保持运行和联网。
• 同一时间仅支持一个手机页面连接。

机器人通道：接入微信与飞书

如果需要频繁在手机上操作，每次打开远程控制就不太方便。机器人通道可以把 ZCode 接入微信或飞书，在聊天窗口中直接管理任务，更适合长期使用。

方式	入口形式	适用场景
远程控制	扫码访问网页	临时查看，短期使用
机器人通道	微信/飞书会话常驻	长期跟进，频繁操作

两者操作的都是桌面端已有的会话，代码运行环境保持不变。

微信配置

打开"移动端远程控制"弹窗，右侧就是机器人通道入口。选择微信，用手机微信扫码确认，凭据会自动保存。之后直接在微信里和该机器人对话即可。

飞书配置

分两步：

1. 在 ZCode 中选择飞书并扫码，手机端跳转飞书开放平台，确认智能体应用的名称和头像后点击"立即创建"。
2. ZCode 会生成一条限时有效的绑定命令，格式类似 /bind C67356。在飞书中找到刚创建的机器人，发送该命令，收到绑定成功提示即完成。

绑定后可用命令包括：查看状态、新建任务、切换项目、切换模型、切换运行模式、调整回复详细程度等。

飞书渠道采用流式卡片回复，没有回复颗粒度选项。Agent 回答会在同一张卡片内原地更新，不会刷屏。工具调用部分默认折叠，需要用户决策时会以单独卡片提问。

机器人管理

已创建的机器人可以在管理列表中调整：关联或解绑凭据、设置回复颗粒度（飞书除外）、配置工作区访问范围、启用/停用、删除。

限制工作区访问范围是个实用功能，项目多的时候可以让界面更精简。

功能边界与常见问题

手机端能新建 SSH/WSL/Docker 连接吗？

不能。新建远程开发连接必须在桌面端完成。但对于已登记在当前窗口中、暂时断开的远程工作区，远程控制可以对其发起重新连接（实际连接过程仍由桌面端执行）。机器人通道是否支持该操作，建议以官方文档为准。

手机端能打开桌面端没打开过的项目吗？

不能。手机端只能访问当前桌面窗口已打开或已登记的工作区，无法浏览本地其他目录，也无法连接窗口之外的环境。

是否支持多设备同时连接？

不支持。同一时间仅允许一个手机页面连接远程控制。

Docker 远程开发支持同步 Skill、MCP、插件吗？

目前仅 SSH 和 WSL 支持，Docker 暂不支持。

远程开发连接失败怎么排查？

优先看连接日志最后一条 ERROR 或页面底部的错误摘要。常见原因有主机不可达、端口错误、认证信息有误、远端缺少基础工具、容器未运行等。

小结

ZCode 的三组远程能力对应三种不同场景。

远程开发解决代码在哪跑。如果项目依赖特定的 Linux 环境、GPU 资源，或者团队统一用服务器开发，SSH、WSL、Docker 三种方式基本能覆盖大多数需求。

远程控制和机器人通道解决人在哪操作。前者扫码即用，适合临时出门、会议间隙快速查看进度；后者需要一次配置，但之后可以在微信或飞书中直接使用，更适合长期跟进的项目。

三者可以组合使用。比如在桌面端通过 SSH 连接远程服务器开发，出门之后用手机远程控制或微信机器人通道继续跟进同一个远程工作区——代码始终在服务器上跑，你只是换了个地方发指令。

根据自己的使用场景选择即可。