命令在哪里执行

在沙箱配置里选择 ZAI 的命令和文件操作在沙箱、独立执行沙箱还是一台远程设备上进行，以及在设备上执行有什么不同。

沙箱配置的 运行方式 决定 ZAI 在哪里执行命令、读写文件和使用技能：默认和 ZAI 一起在云端沙箱里，也可以放到与它配对的另一个云端沙箱，或者一台已接入的远程设备上。运行方式和 出网级别、内网路由一样取自对当前聊天生效的那一份沙箱配置，规则见能力在哪里生效。

谁可以做：组织的沙箱配置由组织 Owner 选择运行方式，Admin 可以查看。成员可以在 我的资源 → 沙箱配置 为自己的私聊选择，见在控制台管理自己的资源。

前提

这项功能需要 Z Tag 管理员开启。这套 Z Tag 服务没有开启这项功能时，沙箱配置的表单和详情里没有 运行方式，ZAI 的命令都在沙箱中执行。

开启后又关闭时，沙箱配置里选过的运行方式保留，新的 Session 一律在沙箱中执行；此前按其他运行方式开始的 Session 再收到消息时失败，提示「这个 Session 的运行方式已停用。重试时平台会在沙箱中新开 Session 执行。」。重新开启后，新的 Session 恢复按沙箱配置执行。

三种运行方式

运行方式	命令、文件和技能在哪里
在沙箱中执行	和 ZAI 在同一个云端沙箱里。新建沙箱配置时默认选这一项
在独立执行沙箱中执行命令	在与 ZAI 配对的另一个云端沙箱里
在远程设备上执行命令	在所选的一台远程设备上，以安装这台设备的系统用户身份执行

独立执行沙箱和 在沙箱中执行 一样遵守沙箱配置的 出网级别、内网路由和连接器的授权；它启动慢或启动失败时的提示也一样，中断时的提示见沙箱启动失败或中断时。
后两种方式下，ZAI 自己调用模型用的服务地址和占位值只在它所在的沙箱里，执行命令的一侧拿不到，命令和脚本不能借用它们调用模型；独立执行沙箱的网络仍然放行模型服务的地址。
远程设备上的命令不受沙箱配置的网络规则约束，见在远程设备上执行时。

选择运行方式

新建沙箱配置时，在表单的 运行方式 里选择。已有的沙箱配置，在详情页把鼠标移到名称上，点出现的铅笔按钮，在编辑框里修改。
选 在远程设备上执行命令 时，再在 远程设备 里选一台，能选哪些见哪些设备可以选。表单里的两段提示分别说明选设备不等于授权，以及设备上的命令以登录用户的身份执行。
保存后，详情页的 出网级别 旁显示 运行方式 和所选的设备。

修改只影响之后开始的 Session：已有的 Session 按原来的方式继续，直到这段工作结束。例外是在远程设备上执行命令的已有 Session：沙箱配置改用其他运行方式或其他设备后，它进行中的一轮会停止，提示「沙箱配置已不再使用这台远程设备执行命令，本轮已停止。……」，下一条消息在新的 Session 里按新的设置执行。要让某个话题马上改用新的运行方式，在其中发送 /restart，见命令速查。

哪些设备可以选

组织的沙箱配置可以选组织的远程设备。成员自己的沙箱配置可以选他自己的设备，以及组织授权给他或 全体成员 的设备，后者在列表里标有 组织提供。
设备要已启用，并且已经用支持执行命令的设备程序连接过 Z Tag：只支持 Linux 和 macOS，安装设备的用户不能是 root，用户主目录要在 /home 或 /Users 下；Windows 设备不能选。设备离线时仍可以选，但执行命令时它要在线。
编辑时，原来选的设备不再符合条件的话，列表里在它的名称后标注「（当前不可用）」。没有可以选的设备时，表单会说明这些条件。

选了设备不等于授权。聊天所在范围的设备使用范围也要包含这台设备：群里是加到这个 Channel、它所在的 Workspace 或整个组织的设备，私聊里是成员自己的设备和授权给他或全体成员的设备。不包含时，这里的每一轮在开始执行前就失败，提示「执行命令的远程设备不在这个聊天的设备使用范围内。……」，不会改在沙箱中执行。设备的使用范围怎样设置，见范围设置。

沙箱配置的详情会列出用这份配置、设备使用范围却不含这台设备的范围，这些范围里的任务执行命令时会失败，其下单独授权了这台设备的 Workspace 或 Channel 除外。默认沙箱配置的详情另有一句提示：没有单独选择沙箱配置的范围同样用它，这些范围也要授权这台设备。

在远程设备上执行时

远程设备不是沙箱，而是一台真实的电脑，可能正是成员日常使用的那台。选这种运行方式之前，先了解：

身份与文件：命令以安装设备的系统用户身份执行，可以读写这个用户能访问的文件，也可以进入这个用户主目录里已有的项目。工作目录以外的改动会留在设备上。同一台设备上的不同 Session 以同一个用户运行，能读到彼此的文件，见远程设备按登录用户的权限运行。
网络与连接器：命令用设备自己的网络和设备上已有的登录状态，不受 出网级别 和内网路由限制，访问时也不会带上连接器里的凭证。连接器里的数据库、SSH、Git 仓库和 Kubernetes 在设备上用不了，需要它们的任务请改在运行方式不是远程设备的聊天里做。插件提供的 MCP 服务不在设备上运行，照常可用。
工具：能用的工具取决于设备自己装了什么。ZAI 的沙箱里预装的办公文档、PDF、OCR、浏览器和字体等在设备上不保证有，依赖它们的技能在设备上不提供，见默认可用的文件处理能力。
Artifact 与远程设备操作：在设备上执行命令的聊天里，ZAI 不能发布 Artifact，也不能用远程设备的终端、文件传输、截图和桌面操作，只能查看有哪些设备和设备的信息。需要这些时，它会说明原因，能用附件交付的改用附件；也可以改在运行方式不是远程设备的聊天里做。
外部触发：Webhook、事件订阅和定时任务开始的工作同样在设备上执行命令，见远程设备按登录用户的权限运行。

工作目录与文件

ZAI 在设备上的每个 Session 有自己的工作目录，位于安装设备的用户主目录下的 ~/ZTag/sessions。ZAI 第一次在这台设备上执行命令时，才会创建 ~/ZTag。
Session 结束时，Z Tag 只删除工作目录里的 .ztag 目录、技能目录和根上的 AGENTS.md，ZAI 生成的其他文件留在设备上，不再需要时可以手动删除。你发给 ZAI 的附件默认下载到 .ztag 里，随 Session 结束删除；要保留时让 ZAI 存到其他位置。
设备重新关联到另一台电脑后，Session 在新电脑上的空工作目录里继续，原来那台电脑上的文件不会迁移过去。按维护远程设备完整卸载后在同一台电脑上重新接入时，~/ZTag/sessions 仍在，Session 在原来的目录继续，文件都在。

设备上的进程

ZAI 把程序放到后台运行（输出写到文件，并用 nohup、setsid、tmux 这类方式脱离出去）时，程序跨轮保留，直到 Session 结束；输出仍连着命令的后台程序可能在这一轮结束时一起结束。命令打开的桌面程序，例如 xdg-open 打开的浏览器、code . 打开的编辑器，同样保留到 Session 结束。
下面这些情况会结束 ZAI 在设备上启动的进程，包括后台程序和桌面程序：
- Session 结束，包括在话题里发送 /restart；
- 设备被停用或撤销关联，在本机暂停连接或停止后台服务，或者设备程序重启、更新；
- 设备被移出聊天所在范围的使用范围，或沙箱配置改用其他运行方式或其他设备，这时结束的是这个聊天里的进程。
交给设备上原本就在运行的服务启动的进程不受影响，例如你自己的 tmux 会话、pm2、systemd --user 或 launchd 启动的程序，Z Tag 不会结束它们。
需要长期使用的程序请自己在设备上启动；ZAI 打开的窗口可能在上面这些情况下被关掉。
ZAI 的命令运行期间算设备在忙：推荐更新会等命令结束，防休眠选 有任务时 的电脑保持唤醒，见自动更新和防休眠与防锁屏。脱离出去留在后台的程序不算在忙，推荐更新不等它们，安装更新时它们随之结束。

设备停用、撤销或删除时

设备详情的 在此设备上执行命令的沙箱配置 一节列出选了这台设备的沙箱配置。停用、撤销关联和删除设备对它们的影响，见停用、撤销与删除。

失败时

设备离线、正在更新，或者同时执行的任务已满时，这一轮会先等一会儿；设备已停用、撤销关联、不在使用范围里或设备程序不支持时立即失败。这些情况都不会改在沙箱中执行：Session 保留，设备恢复后在原来的工作目录继续。等待多久、执行中连接中断会怎样，见沙箱启动失败或中断时；各个提示的处理办法见按现象排查问题；一台设备能同时执行多少任务，见远程设备的限制。

本页目录