DEV Community: EdgeStorage

在多台远程服务器上并行跑 Codex：worktree 应该怎么分

EdgeStorage — Mon, 02 Nov 2026 12:37:21 +0000

并行跑 AI 任务，常见的阻碍往往不是模型能力，而是目录。

两个会话在同一个工作目录里改代码，A 刚写完的文件可能被 B 覆盖；你打开文件准备保存，界面提示版本已经过期；测试失败时，也很难判断是哪一个任务改坏的。机器一多，问题还会多一层：任务到底跑在哪台服务器、哪个目录、哪个分支？

Git worktree 能解决其中一部分问题，但它不是「把同一个目录挂到多台机器」的魔法。这篇讲清楚 TaskHandoff 里的分工方式：一台节点、一份仓库 clone、一个任务、一个 worktree，以及多节点时哪些事情不能做。

先说结论：多节点并行不是共享一个 worktree

Git worktree 是同一个仓库的独立工作目录和分支。它让多个会话各自拥有一个目录，减少并行编辑冲突；但 worktree 仍然属于某一台机器上的某一个仓库 clone。

所以多台远程服务器并行跑任务时，正确模型是：

同一远端仓库
   ├── 节点 A 的 clone → worktree A-1（分支 feature/a）
   └── 节点 B 的 clone → worktree B-1（分支 feature/b）

不是：

节点 A 的 worktree ← 同时挂给节点 B 的会话

前者是多个独立 checkout，后者会制造路径、锁和文件一致性问题。TaskHandoff 的多节点模型按节点管理实例和会话，不把 worktree 当成跨节点共享目录；它做的是把多个节点、多个实例和多个会话放进同一个控制面里查看和操作。

为什么不用同一个目录硬跑

在同一台机器上，两个 Codex 或 OpenCode 会话共用一个工作目录，至少会遇到三类问题：

文件互相覆盖：两个任务同时改同一个文件，后写入的版本不一定是你想要的。
状态难以归因：测试失败、依赖变化、未跟踪文件，分不清来自哪个任务。
保存冲突：文件被 AI、终端或另一个编辑器改过后，保存会因版本过期停止，需要先比较再决定。

worktree 把「任务」和「目录」绑定起来：一个任务一个目录，一个目录一个分支。这样每个任务的变更、测试和提交都能独立检查。

做法：一台节点，一个任务，一个 worktree

下面是一条可复用的路径。它不是通用答案，但边界比较清楚。

1. 把远程服务器接成节点

节点是运行 Node Agent、并实际管理实例的计算机。打开「设置 → 节点 → 添加节点」，根据网络条件选择连接方式。远程节点通常用反向 WSS：Node Agent 主动连 Control Plane，不需要给节点开放公网入站端口。

一次性加入 Token 只用于首次建立信任，配对完成后不要把它写进脚本仓库、工单或日志。

2. 在每台节点上创建 Git 实例

每台要参与并行的服务器，各自创建自己的 Docker 实例，并把同一个远端仓库 clone 进来。多节点不是共享工作区，而是每台机器保持自己的 clone。

如果你需要控制 Git 权限，凭据按 remote scope 匹配；HTTPS token 只在 credential-helper 请求期间短暂提供，不写进 remote URL、命令行或环境变量。SSH 私钥留在 Node Agent，实例只拿签名能力。

3. 从已有 Git 会话创建托管 worktree

打开已有 Git 会话的「环境 → 工作树」，选择「新建托管工作树 AI 会话」，填写新分支名称和起始引用，再选择 Codex 或 OpenCode。

创建完成后，TaskHandoff 会生成托管 worktree 和新会话；原会话仍停留在原来的工作目录。会话创建后工作目录不会自动改变，所以换 worktree 的正确做法是「在目标 worktree 上新开会话」，不是把当前会话挪过去。

4. 在另一台节点重复，而不是复制目录

第二台服务器也按同样方式创建自己的实例、clone 和 worktree。两个 worktree 可以在同一个远端仓库上使用不同分支，但它们在文件系统上彼此独立。

建议把分支名和任务目标绑定，例如 feat/api-timeout、fix/windows-paths。不要让两个会话在同一个 worktree 同时修改相同文件；如果一个任务需要改同一批文件，先拆任务，或者让它们串行。

5. 分别在每个 worktree 里审阅、测试、提交

每个 worktree 都有自己的变更集。分别检查测试和 diff，确认后再提交和推送。TaskHandoff 的远端操作是保守的：Pull 仅允许 fast-forward，不自动 merge、rebase 或 stash；分支分叉时阻止自动同步；永远不 force push。

复杂冲突、已分叉分支、大型或二进制 diff，建议到对应会话的终端里处理，然后刷新仓库页面。

多节点时，节点选择看什么

节点不是越多越好。比较实际的分配依据是：

运行时和依赖：哪台机器有项目需要的 Docker 镜像、系统工具或 GPU。
隔离边界：不同客户、不同仓库、不同权限的凭据是否应该落在不同节点。
网络位置：节点在公司内网、家用服务器还是云主机，决定了它能不能访问目标仓库和依赖。
任务时长：长任务放在常开的服务器上，临时任务放在随手可用的节点上。

不要为了「看起来并行」把同一个 worktree 复制到多台机器。复制目录会带来身份、缓存和未跟踪文件的不一致；正确做法是每台节点从远端仓库创建自己的 checkout。

交付和清理：分支保留，目录才删除

托管 worktree 由 TaskHandoff 创建，可以安全地用于新 AI 会话。外部 worktree 只有位于实例授权目录且仍可访问时才能使用，系统不会接管或删除它。

删除托管 worktree 前，它必须是非主工作树、无修改、未锁定，并且没有活跃的 AI 或应用会话。删除的是工作树目录，关联的 Git 分支会保留；系统使用非 force 删除，不会顺手删掉你的分支。

主工作树、外部 worktree、有未提交修改或仍被活跃会话占用的 worktree，不能从界面删除。这条限制看起来麻烦，但它防止的是「清理目录时把正在跑的任务或未提交改动一起弄丢」。

踩坑：四个容易犯的错

把 worktree 当成跨机器共享目录。 它不是。多节点并行是多个 clone、多个 worktree，不是一个目录挂给多台机器。

两个会话共用一个 worktree。 文档明确建议并行任务分配不同 worktree；同一 worktree 里的两个会话会看到彼此写入磁盘的修改。

在主工作树上直接开长任务。 主工作树通常承载你正在做的改动。更稳妥的方式是从它创建托管 worktree，把实验性任务放到独立目录和分支。

以为移除 worktree 会删分支。 移除的是目录，Git 分支保留；但目录里有未提交修改或仍有活跃会话时，系统会阻止删除。

结果：行为上发生了什么变化

两台服务器上的任务出现在同一个控制面里，可以按节点、项目、状态查看。
每个任务有自己的目录和分支，文件冲突不再靠人肉记忆避免。
每个 worktree 单独测试、审阅、提交，失败时更容易归因。
清理 worktree 时分支保留，复杂合并回到终端显式处理。

可复用的五条原则

一个任务一个 worktree。 目录是并行任务的隔离边界，不是共享缓存。
worktree 属于节点，不属于控制面。 多节点并行靠多个 clone，不靠共享目录。
分支名写清楚任务目标。 让 worktree、分支和任务能一一对应。
每个 worktree 单独验收。 测试、diff、提交和推送都按 worktree 走。
清理是流程的一部分。 先关会话、保持干净、再移除目录；分支是否保留由 Git 决定。

管理多台远程服务器，不一定要开公网端口：多节点接入与免费中转

EdgeStorage — Mon, 02 Nov 2026 12:07:20 +0000

远程服务器管理和远程开发常被当成一个「能不能连上」的问题。真做起来，其实是两条链路：

你（浏览器 / 桌面端 / 手机）怎么访问 Control Plane；
Control Plane 怎么管理散在不同网络里的节点。

这两条链路的入口、认证和信任边界是分开的。把它们混成一条，最常见的做法就是给每台机器开公网端口、配端口映射，然后把安全寄托在「这个 URL 别人猜不到」上。

TaskHandoff 是免费、开源、可自托管的 AI 远程工作平台。它的做法是把这两条链路拆开：节点用反向连接主动接入；控制面可以不暴露到公网，通过 Thandoff 账户的免费后台中转供已授权客户端访问。

这篇文章讨论的不是「怎么在服务器上执行一条命令」，而是怎么把服务器纳入一个长期可用的远程工作台：节点、Docker 工作区、AI 会话和终端都在同一个控制面里。

问题：一台机器一个终端窗口，机器一多就崩

手上有三台机器的人，日常大概是这样的：笔记本、一台常开的家用服务器、一台公司内网主机。你在它们上面分别跑 Codex 或 OpenCode，然后开始当人肉调度器：

记得哪台机器上有哪个仓库、哪个分支、哪个 worktree；
反复切 SSH 窗口看进度，因为任务只活在那个终端里；
关掉笔记本之后，不知道服务器上的任务到底还在不在跑。

常见的三种连通方案各有代价：

公网 IP + 端口映射 / 内网穿透：每台机器一套 NAT、TLS、认证；暴露面变大，节点换网络后还要重新确认。
VPN：连通性解决了，但「哪台机器上有哪个任务」的可见性没有解决，也没有任务级的权限边界。
一台机器一个远程桌面：能用，但把整个桌面暴露出去，和「只想看一个任务的进度」不是一回事。

做法一：把节点接进来，而不是把端口开出去

在 TaskHandoff 里，节点是运行 Node Agent、并实际管理实例的计算机。所有节点出现在同一个控制面板里，可以按节点、项目、状态筛选。

图 1：设置 → 节点。左侧是本机和远程节点，右侧是节点的运行环境、实例与诊断信息。

添加节点的向导会先检查 Control Plane 的公网可达性，再根据目标机器的网络条件推荐连接方式。核心原则只有一句：让能够主动出站的一方发起连接，尽量减少公网入站端口。

方式	谁发起连接	适合的场景	公网要求
反向 WSS	Node Agent	远程节点能访问 Control Plane	只公开 Control Plane 的 HTTPS
HTTPS 直连	Control Plane	Control Plane 能访问 Node Agent	公开 Node Agent 的 HTTPS API
可信控制面代理	当前 Control Plane	双方都不能接受入站连接	两端都能访问代理面板

反向 WSS 通常是首选。 它不要求给 Node Agent 配公网监听、NAT 和 TLS；Node Agent 会持久化连接，服务重启后自动重连。目标机也不需要预装 Node.js 或 npm——受支持的安装器会准备运行环境。

配对用的加入 Token 是一次性的，有有效期，只用于首次建立信任。配对完成后的反向连接使用单独凭据，不依赖 Token 保持在线。这一点值得单独强调：不要把长期凭据塞进安装命令，也不要把 Token 写进脚本仓库、工单或日志。

HTTPS 直连只在控制面无法被目标节点访问、但能访问 Node Agent 时使用。它要求公网 Node Agent 必须使用 HTTPS。把 listener 从 127.0.0.1 改成 0.0.0.0 只会扩大监听范围，不会自动配置 TLS、防火墙或认证——这是最容易出事的一步。

可信控制面代理用于双方都不能接受入站连接的场景。需要注意它的语义：代理面板可以读取、修改并代表你执行全部被代理的节点操作，而且这条路径不是端到端加密的，只能在同一可信管理边界内使用。

图 2：「添加远程节点」里的两种方式。选择控制面代理时，需要显式勾选「我信任此控制面板代理 node-agent 操作」。

做法二：控制面不暴露到公网，也能从手机或浏览器访问

第二条链路是「人 → Control Plane」。传统做法是域名 + HTTPS 反向代理，把控制面挂到公网。这在小团队里完全可行，但要求你维护 DNS、证书、端口和认证。

如果你不想把控制面暴露到公网，可以用 Thandoff 账户中转（免费）：把一台自管 Control Plane 发布到账户目录，移动端等已授权客户端通过后台中转访问它。官网当前把这项能力描述为端到端加密中继，节点覆盖中国与全球。

Control Plane 主动建立出站连接，所以不用为这条路径开放 Control Plane 或 Node Agent 的公网入站端口。
中转的是「客户端 → Control Plane」的 API、响应流和 WebSocket，不是节点之间的账号型中继。这个边界很重要，下面会单独说。
中转由 Control Plane 的后台进程持有：关闭设置页、退出本地 Web UI、授权用的浏览器会话过期，都不会停掉中转。
停止 Control Plane 服务、关闭远程访问、撤销绑定或发生身份冲突，会终止中转；服务恢复后，只要绑定仍有效且远程访问已开启，后台进程会用专用凭据重新连接。

两个操作的名字很像，语义完全不同：「关闭远程访问」保留账户绑定，随时可以再开；「断开 Thandoff 账户」会撤销绑定，下次要重新走一遍授权。授权码大约 5 分钟内有效，消费后立即失效；客户端访问时还会校验 Control Plane ID、账户、绑定 ID 和 revision，旧的或已撤销的授权不能继续建立新连接。

踩坑与边界：不能吹的部分

第一，账号型 Node Agent 中继目前还不支持。 文档写得很明确：Thandoff 账户中转的是客户端到 Control Plane 的访问，不是节点中继。如果两台机器都不能接受入站连接，正确路径是可信控制面代理，而不是指望账户中转替你连节点。把这条边界写清楚，比含糊带过更有用。

第二，复制数据目录会造成身份克隆。 Control Plane 的 ID 和签名身份保存在数据目录里；把整个目录复制一份、同时运行原安装和副本，两台机器会以同一个身份上线。账户服务检测到之后会把状态置为「身份冲突」，删除后台中转凭据并隔离所有远程数据连接。不要靠反复点「开启远程访问」绕过，先停掉其中一个安装，确定哪台机器保留原身份。

第三，反向代理不能只转发 /api/events。 实例终端、浏览器等功能还有别的 WebSocket 路由。稳妥的做法是让整个 Control Plane Origin 正确转发升级头，同时把请求体大小和读取超时放宽；否则会出现「页面能打开，但状态不更新」「终端一开就断」。

第四，移动端 Origin 必须是规范形式。 https://主机[:端口]，不能带路径、query、内嵌用户名密码，也不能依赖重定向。配置完成后不要随意更换 Origin——已有移动端配置会把 Control Plane ID 和签名密钥指纹与这条连接一起校验。

第五，关掉控制面不等于关掉任务。 关闭或重启 Control Plane 不会停止远程 Node Agent 管理的实例；真正会中断任务的是停止或删除实例、关闭会话、停止 Node Agent。Local Runtime 的实例会随 Node Agent 退出而停止，Docker Runtime 的实例会继续运行，并在下次启动后被重新发现和接管。

结果：行为上发生了什么变化

不列数字，只列可验证的差异：

加一台机器：在目标机上跑一条带一次性 Token 的安装命令，不用为它开放公网入站端口。
节点掉线：状态显示重连中，网络恢复后自动连回来，不需要重新配对——节点记录和配对关系都不应该靠删除来「测试连通性」。
在外面：手机或桌面客户端登录同一个 Thandoff 账户，从 Control Plane 目录里添加面板，不需要记公网 IP，也不需要把控制面挂到公网。
长任务：关浏览器、退出本地 Web UI，任务在节点上继续；回到电脑上能看到权威状态。
多机视图：所有远程服务器和实例在同一个看板里，按节点、项目、状态筛选，不用逐个 SSH 上去看。

图 3：多节点之后，「按所属节点筛选」会变成最常用的视图之一。

可复用的五条原则

两条链路分开规划。 人怎么访问控制面、控制面怎么访问节点，入口和信任边界不是一回事。
让能出站的一方发起连接。 反向连接优先于端口映射；少开一个入站端口，就少一类暴露面。
一次性 Token 只用于建立信任。 长期连接用独立凭据，Token 不进仓库、工单和日志。
把「关闭」和「断开」做成两个语义不同的操作。 一个可恢复，一个要重新授权，界面上必须说清楚。
能力边界写进文档。 不支持的中继方式要明说，并给出替代路径——这比让用户自己试错便宜得多。

Codex 在 Windows + PowerShell 上的问题，我们决定把执行面换到 Linux

EdgeStorage — Wed, 14 Oct 2026 07:49:34 +0000

标题备选（数字钩子，需带上查询语句与日期）：

「4,269 条 issue 标题里带 Windows：Codex 在 PowerShell 下的问题是结构性的」

「Codex CLI 有 203 条标题含 PowerShell 的 issue，我们不再指望修好它」

先说结论：Codex 在 Windows 上不是不能用，而是你把任务规模化之后，被 PowerShell 打断的次数会变成一种固定成本。我们试过的方向里，性价比最高的不是写更长的提示词教模型写 PowerShell，而是把执行面换到 Linux 用户态。

TaskHandoff 是免费、开源、可自托管的 AI 远程工作平台。这篇先把网上能查到的真实问题摊开（都带链接，可以自己核），再讲我们在 TaskHandoff 里选的那条路，以及这条路的代价。

一、先看真实问题：四类，且不是同一类

A 类：PowerShell 不是 Bash，模型的命令会持续撞墙

Codex CLI 在 PowerShell 下会反复生成 rg 'pattern' *.md 这种写法，直接报 os error 123；同一环境里 rg -g '*.md' 'pattern' . 是正常的。报告者的原话是：这不是一次失败，而是在正常使用中不断生成不被支持的命令形式，产生可避免的失败调用和恢复工作，浪费时间和 token（#45685）。
过大的 PowerShell 命令会在启动前就失败，报 os error 206（#45788）。
引号、反斜杠、JSON 参数被 PowerShell 改写；从 Bash 教程抄来的命令直接失败；ExecutionPolicy 拦截脚本；路径带空格或中文就出问题（knightli.com 的排查手册）。

B 类：Windows 特有的策略与沙箱层

exec_command 在 PowerShell 还没启动前就被拒绝：CreateProcess rejected: blocked by policy，没有子进程 PID、没有退出码。值得注意的是，报告者当时已经配置 approval_policy=Never + sandbox_policy=DangerFullAccess，依然被拦，而且错误信息不告诉你是哪一层策略拦的（#44839）。同类报告还有只读 Get-Content 被拒（#43881）、只读健康检查被拒（#43633）。
Windows 沙箱阻塞 Node 子进程：spawnSync EPERM、errno -4048；想改成提权模式，反而在 UAC 提示出现前就失败：helper_sandbox_lock_failed / SetNamedSecurityInfoW ... failed: 5（#45697）。同类还有子进程管道建立失败、PID 为 0（#44838）。

C 类：跨文件系统与路径映射

切到 WSL2 之后，项目路径会变成 /mnt/c/Program Files/WindowsApps/... 这种形态；合法符号链接被拒；粘贴的图片 image tool 读不到（而沙箱里的 Bash 明明能读）（#44182）。Windows + WSL2 无法创建本地项目也有人在报（#45887）。
CRLF 会让 Git 显示「所有文件都被修改」，权限位全部变化；同一个仓库可能出现 Windows 侧能拉取、WSL 侧不能拉取（knightli.com）。
官方说明里有一条容易被忽略：集成终端 shell 和 agent environment 是两个独立设置。你把集成终端改成 Git Bash，agent 依然用 PowerShell 跑命令（nenufm.com）。

D 类：安全软件与企业环境

卡巴斯基把 %USERPROFILE%\.codex\.sandbox-bin\codex-command-runner-0.154.0.exe 判为 PDM:Exploit.Win32.Generic.nblk 并拦截；而该文件与官方 npm 包内的文件 SHA-256 完全一致，Kaspersky 自己的动态分析结果又是 Clean（#45810）。
与 FSLogix 不兼容（#45897）；应用商店更新后启动失败报 rename_staging EPERM（#45858）。

规模参考（2026-09-16 用 GitHub 搜索查询，计数为近似值）：repo:openai/codex type:issue 共 28,341 条，其中 label:"windows-os" 7,291 条，标题含 Windows 的 issue 4,269 条，标题含 PowerShell 的 203 条。

二、为什么「修好 PowerShell」这条路收益有限

把上面四类分开看就清楚了：A 类是 shell 语义差异，B 类是 Windows 安全模型与沙箱实现，C 类是跨文件系统映射，D 类是第三方安全软件。它们不是一个补丁能一起解决的问题。

社区里有人做过一轮很扎实的尝试（nenufm.com，2026-07-21 发布、2026-09-06 更新）：

装了 PowerShell 7，对体验有帮助，保留；
把一大段 PowerShell 工具提示词放进全局 AGENTS.md——没解决问题，后来删掉了；
装了 Coreutils 想让命令更接近 Unix，结果 PSConsoleHostReadLine 会改写交互输入，Get-Command rm 显示的别名和实际执行入口不一致，辨认成本上升，最后卸载；
还发现失败未必跟 shell 语法有关：有一次是 Codex 调用了旧版本目录里的 codex.exe，换到当前安装路径就成功了——这种错误升级 PowerShell 或换 Bash 都救不了。

他最后的做法是把约束写简单：精确搜索用 rg -n -F、多条件用多个 -e、不要额外嵌套 pwsh -Command。

这条经验值得记住：提示词能降低概率，但降不到零；而每次失败的代价是一次工具调用、一次恢复、以及被消耗掉的上下文。

三、我们选的路：Windows 只当入口，任务跑在 Linux 侧

TaskHandoff 在 Windows 桌面端上有一个明确的约束：Windows 上创建本机实例走的是 Docker Runtime，内置 Local Runtime 只在受支持的非 Windows 节点提供（见安装与登录）。

翻译成使用方式就是：Windows 负责界面，任务实际跑在 Linux 容器里。A 类的 PowerShell 语义问题、B 类的 Windows 沙箱策略问题，在这一层就不存在了——agent 执行的是容器内 Linux shell 的命令。

另外两条路径也在同一套模型里：

把远程 Linux 主机加为节点。 一台 Debian/Ubuntu 机器加入后，和本机实例出现在同一个控制面里，可以按节点、项目、状态筛选。装法和步骤见首次配置和远程节点。
只让 Windows 承担操作入口。 桌面端、浏览器、移动端、聊天桥接共用同一个控制面，跟进任务不需要守在一个 PowerShell 窗口前。

顺带解决掉几个 C 类和运维层面的老问题：

路径与工作目录：一次 AI 会话绑定固定工作目录，创建后不会自动改变；要换 worktree，就在目标 worktree 上新建会话（见使用 AI 会话）。少一层「Windows 路径 → WSL 路径 → 容器路径」的心智转换。
交付：改动通过文件/变更视图审阅，走分支或 worktree 交付；远端操作是保守的——Pull 仅允许 fast-forward，永远不 force push，分支分叉就阻止自动同步（见仓库协作）。
凭据：Git 凭据按「协议 + 主机 + 端口 + 大小写敏感的路径前缀」限定范围，不支持通配符；HTTPS token 只在 credential-helper 请求期间短暂提供，不写进 remote URL、命令行和环境变量（见Git 凭据）。不用在 Windows 上给每个项目单独配一遍。
长任务不靠窗口活着：关闭桌面主窗口只是隐藏到托盘，Docker Runtime 实例保持运行，下次启动后节点代理会重新发现并接管（见安装与登录）。配合移动端和聊天桥接，离开电脑也能看进度。

四、代价，说清楚

Windows 上要装 Docker。 安装桌面应用本身不等于安装 Docker；创建 Docker 实例前，节点必须已安装并启动 Docker daemon，且当前用户有权限访问它。
Local Runtime 在 Windows 上不可用，想要「直接使用宿主机目录和工具」的用法得放到非 Windows 节点上。
换成 Linux 用户态意味着接受 Linux 工具链。如果你的项目强依赖 Windows 专有工具，这套方式不适用。
多了一层容器：镜像拉取、卷管理和环境模板这些概念需要理解一次。

五、可复用的五条原则

区分「操作环境」和「执行环境」。 你人在 Windows 上工作，不代表 agent 必须在 PowerShell 里执行命令。
不要在提示词层面解决平台语义问题。 提示词能降低概率，不能替代把环境换对。
同一类问题要分层归因：shell 语义、沙箱策略、文件系统映射、安全软件——它们的解法完全不同。
让失败可解释。 「blocked by policy」这种没有规则归属的错误，会让 agent 和人都无法自行恢复；选工具时要把它算作一个真实成本。
长任务的存活不要依赖终端窗口。 判定方法：关掉窗口、重启界面服务，任务还在不在跑。

停掉控制面之后，服务器上的 AI 任务还在跑：我们为什么把它拆成三层

EdgeStorage — Wed, 14 Oct 2026 07:49:27 +0000

用一个界面对着某台机器上的某个终端窗口，是大多数人开始用 AI 写代码的方式。任务变多之后，尤其是任务分散在本地电脑和远程服务器上时，会出现三个具体问题：任务分散在多台机器上、每个任务需要独立且可丢弃的环境、长任务不能因为浏览器关了或者界面断了就死掉。

TaskHandoff 是免费、开源、可自托管的 AI 远程工作平台。这篇讲它在这三个问题上做的架构选择：为什么控制面和执行面要拆开，状态到底归谁管，以及由此付出的代价。

问题：任务一多，你就开始手动当调度器

假设你手上有三台机器：一台笔记本、一台常开的家用服务器、一台公司内网主机。你在它们上面分别跑 Codex 或 OpenCode。于是你每天在做这些事：

记得哪台机器上有哪个仓库、哪个分支、哪个 worktree；
手动把环境装好，或者忍受容器里从零开始装工具；
反复切 SSH 窗口看任务进度，因为任务只在那个终端的上下文里存在；
关掉笔记本之后，不知道家用服务器上的任务到底还在不在跑。

这些动作里没有一个是真正的开发工作，但它们都会消耗注意力，而且出错时很难回溯。

我们的做法：三层，各管一件事

浏览器 / 桌面端 / 移动端 / 聊天平台
              │
              ▼
        Control Plane（UI、API、聊天网关）
              │
              ▼
         Node Agent（节点资源与实例生命周期）
              │
              ▼
     Controlled Instance（工作区、应用、AI 会话）

关键不在分层本身，而在每层各自拥有什么状态：

Control Plane 拥有节点清单、实例看板、跨实例的 AI 会话视图、聊天凭据与消息路由。它是你操作的地方，也是多端共用的入口。
Node Agent 拥有节点本地配置、运行时资源、目录清单和实例生命周期。实例的启停由它执行。
Controlled Instance 承载工作区、应用、AI 会话和触发器，可以独立运行。

因为实例生命周期归 Node Agent，停止或重启 Control Plane 不会顺带停掉节点上由 Node Agent 管理的 Docker 实例；控制面板恢复后会重新同步状态。

同理，AI 会话的对话状态以 AI Session 本身为准，控制面负责的是凭据、绑定、命令解析和路由。所以关掉网页不会中断任务——这条被写进了文档 FAQ，因为它是最常被问的问题。

一篇会话绑定固定工作目录，创建后不会自动改变（这条也在文档里）。要换个 worktree 干活，是「在目标 worktree 上新建会话」，而不是「把当前会话挪过去」。这是同一套状态所有权思路的延续：会话不追着环境跑。

停掉控制面之后会发生什么

这条不用实测也能从状态所有权推出来，文档里也已经把它写成了 FAQ——因为问的人最多：

关掉浏览器页面：任务继续跑，重新打开后恢复权威状态。
停止或重启 Control Plane：由 Node Agent 管理的 Docker 实例继续跑，控制面板恢复后重新同步。
真正会中断任务的操作：停止或删除实例、关闭会话、停止 Node Agent。

这里有个最容易误判的坑，我们也把它写进了文档：页面显示「正在重连」不等于后台任务停了。 如果界面一直卡在重连，问题通常在网络路径上——最常见的原因是反向代理没有转发 /api/events 的 WebSocket，而不是 Agent 挂了。把「显示状态」和「权威状态」分开看，能省掉不少误判。

取舍与被否决的方案

为什么不把实例生命周期直接放在控制面？ 那样控制面重启就会波及正在跑的长任务，而且单点变成了「UI 挂掉 = 所有任务挂掉」。把生命周期的所有权下移到节点，代价是控制面离线期间你只能在节点上继续跑已经存在的实例——新建实例、改配置这类操作都要等控制面回来。

断线重连的语义要写清楚。 界面断线重连时会重新获取权威会话快照。最容易造成误解的是那个「正在重连」提示——它不代表后台任务已经停止。我们把这条明确写进文档，而不是靠用户自己猜：会话状态在 Agent 那边，界面的连接状态只是显示层的问题。

运行时不锁死在 Docker。 Docker Runtime 是当前主要的隔离运行时，一个节点可以跑多个实例；Local Runtime 直接用宿主机环境，同一宿主用户只能有一个本地实例，也不支持 Windows。两者共享同一套实例模型，运行时通过 adapter 扩展，所以将来接 Kubernetes 不需要另做一套 UI 流程。

结果：行为上发生了什么变化

不写数字，只列可验证的行为差异：

关掉网页、甚至停掉控制面，节点上正在跑的任务不受影响；重新打开后能拿回权威状态。
本地和远程服务器上的实例出现在同一个看板里，可以按节点、项目、状态筛选，不用逐个 SSH 上去看。
长任务可以在移动端或聊天里跟进；Telegram、微信、钉钉、飞书的桥接把消息和审批路由到指定实例的会话。
实例可以独立运行，节点负责它的生命周期，控制面挂了也不会连带停掉它。

可复用的四条原则

把生命周期所有权放在离资源最近的那一层。 编排层可以崩、可以升级，但它不该拥有「谁在运行」这个事实。
区分「显示状态」和「权威状态」。 界面上的连接状态、重连提示，都不等于后台任务的状态；接错这两个概念会带来大量虚假告警和误判。
让长任务的存活不依赖交互层。 判定标准很简单：关掉浏览器、重启 UI 服务，任务还在不在跑。
状态所有权写进文档，而不是留在实现里。 用户遇到「正在重连」时，需要一句话告诉他这意味着什么。

想自己跑一遍

TaskHandoff 官网（产品定位与客户端下载）：https://www.thandoff.com/
开源仓库：https://github.com/edgestorage/task-handoff
三层结构和每个概念的职责：https://docs.thandoff.com/guide/
部署到自己的机器（Docker Compose 或 Debian/Ubuntu systemd 一键安装）：https://docs.thandoff.com/guide/install
接入远程节点：https://docs.thandoff.com/integrations/remote-nodes
「关闭网页会不会停任务」「停 Control Plane 会不会停实例」：https://docs.thandoff.com/faq

A review checklist for AI coding agent output (7 things I check before trusting a change)

EdgeStorage — Tue, 15 Sep 2026 02:08:05 +0000

Every team running an AI coding agent eventually hits the same wall: the agent produces a lot of output, and reviewing that output is now the bottleneck. A terminal transcript is not a review artifact. Here is the checklist I use before I trust an agent's change, and the tooling each line implies.

The checklist

1. Can I see the change as a diff, not as prose?
If the only thing you get is a summary, you are reviewing a claim, not code. Ask for the diff first. Everything after this line only matters if this one is true.

2. Do I know which directory the agent was in?
Ambiguous working directories are the root cause of a surprising number of "it edited the wrong file" incidents. Pin the path explicitly and make it part of the job record.

3. Is the change isolated to a ref I can check out?
A branch or a worktree means you can test the change yourself, and revert is one command. If the agent mutated your working tree in place, you have already lost the ability to compare. There is a full walkthrough of the worktree approach in the worktree session tutorial.

4. Which commands did it run, and did any of them touch the network?
Install scripts, dependency bumps and curl | sh are where the sharp edges live. Log tool activity, not just the final text.

5. Where did the credentials come from?
If the agent needed a private remote, the token should be scoped to that host and short-lived where possible. Broad credentials handed to an autonomous process is how a small mistake becomes an incident — see git credentials.

6. Can a second person reproduce the run?
Same image, same runtime, same starting commit. If reproducing it takes a verbal explanation, it is not a process yet.

7. What stopped it?
Time limit, token limit, an approval gate, or completion — you should be able to tell from the session state alone. Getting the states named unambiguously is worth doing early; a shared status glossary removes a lot of ambiguity from handoffs.

What this implies about your setup

Once you write the checklist down, the requirements fall out almost mechanically:

sessions need an explicit working directory and state,
workspaces need to be disposable and isolated, so a bad run cannot poison the next one (instances),
Git review needs to be native, not bolted on (repository workspace),
automations that repeat a routine need their own audit trail (automation, actions),
and the whole thing has to run where the code runs, or the credential question answers itself badly.

The uncomfortable part

Most of this checklist exists because I did the opposite first. I let an agent work directly in a checkout I cared about, reviewed the summary, and merged. It worked — for about three weeks. The failure was not a dramatic bug; it was a dependency change nobody noticed until a deploy.

Since then I run every agent task in a disposable workspace, with the diff as the deliverable. That workflow is what I packaged as TaskHandoff: a self-hosted control plane where each task gets its own Local or Docker workspace, sessions are reviewable, and Git changes arrive as a branch or worktree you can test. Apache-2.0, and the docs start at docs.thandoff.com (installation, FAQ).

What is on your checklist? I am particularly curious whether people gate on cost, on network access, or on the diff size.

Self-hosting an AI coding agent workbench: running Codex on my own machines

EdgeStorage — Mon, 14 Sep 2026 17:34:57 +0000

Most AI coding assistants assume you are fine sending your repository somewhere else. For side projects that is a reasonable trade. For anything with a client contract, an internal service, or a repository you cannot move, it is not.

The interesting shift of the last year is that the agent part has become a commodity — Codex, OpenCode, Claude Code and friends all expose a CLI you can run yourself. What is still missing for most teams is everything around the agent: where does it run, which filesystem does it see, who reviews the diff, and how do you run the same routine twice without re-explaining it from scratch.

I have been building that layer for a while. Here is the model that ended up working for me, and the concrete pieces you need if you want to reproduce it.

1. Separate the control plane from the machine that runs the agent

The mistake I made first was treating "the agent" as the single thing to manage. In practice there are three distinct things:

a control plane that owns identity, sessions and routing,
one or more nodes — your laptop, a home server, a cheap VPS — that can actually execute work,
a set of workspaces that give each task an isolated filesystem and process tree.

Once those are three separate concepts, everything else gets easier. A session is not "a chat window", it is a job with an owner, a working directory, a runtime and a status. You can list it, resume it, hand it to a colleague, or kill it.

If you want the shape of that in practice, the first setup guide walks the control-plane/node split end to end, and remote nodes covers what it takes to attach a second machine — the interesting part is that node enrollment is a token, not a VPN, so a box behind NAT is reachable without exposing your whole network.

2. One workspace per task, not per conversation

The second change was moving from "one container per project" to "one workspace per task". A task workspace is disposable: it gets a working directory, a defined runtime, and a bounded life. Two agents working on the same repository in parallel stop stepping on each other's files, and cleaning up is a delete rather than an archaeology exercise.

That works with either a local runtime (run directly on the host, reuse the tools you already have installed) or a Docker runtime (each workspace in its own container). I default to Docker for anything that installs dependencies, and local for repositories where I want the host toolchain.

See instances for how workspaces are created and restored, and workspace: repository if you want the Git side of it.

3. Make the agent's output reviewable, not just readable

A terminal scrollback is a terrible review artifact. What I want after an agent finishes is:

the diff, in a form I can read like a pull request,
the commands it actually ran,
a branch or worktree I can check out and test myself.

The practical trick is to have the agent deliver onto a separate ref instead of mutating your working tree. Worktrees are the cheapest version of that: the agent works on its own checkout, git diff shows you exactly what happened, and merging is a normal Git operation. There is a walkthrough of that workflow in the worktree session tutorial.

If the agent needs to pull a private dependency, the credentials question comes up immediately. Scope the token to the specific remote, use it for provisioning, and keep it out of the agent's environment where possible — git credentials goes into that in more detail than is comfortable.

4. Automate the routines you repeat

After a few weeks you notice you are running the same sequence over and over: pull, update a lockfile, run the test suite, fix the lint, open a branch. That is where a small automation layer pays for itself. I ended up with four primitives that compose:

documents — the instructions, versioned,
triggers — what starts it (schedule, webhook, manual),
actions — what it does (run a session, run a command, notify),
schedules — when.

Once those exist you stop pasting the same prompt and start reviewing output instead. The automation docs cover the model, and actions is the part with the sharp edges.

What I would tell someone starting today

Run the agent where the code lives. Latency is the least of your problems; data residency and filesystem access are the real ones.
Give every task a disposable workspace. It removes an entire class of "which file did it overwrite" bugs.
Make the agent deliver a diff, not a summary. Reviewing summaries is how you end up trusting a black box.
Automate only after you have run the routine manually three times.

If you want to try this shape without assembling it yourself, this is exactly what I have been packaging as TaskHandoff — a self-hosted control plane for AI coding agents, Apache-2.0, with local and remote nodes, per-task Local or Docker workspaces, Codex and OpenCode sessions, Git review, and scheduled automation. Start with installation, or skim the FAQ if you are wondering whether it needs Docker or a public IP.

The docs are at docs.thandoff.com (also in Chinese — the site is bilingual, add /en/ for the English tree).

What is your setup? Are you running agents on your laptop, a home lab box, or somewhere properly boring like a VPS? I am curious which of the three layers above people are missing.

DEV Community: EdgeStorage

在多台远程服务器上并行跑 Codex：worktree 应该怎么分

先说结论：多节点并行不是共享一个 worktree

为什么不用同一个目录硬跑

做法：一台节点，一个任务，一个 worktree

1. 把远程服务器接成节点

2. 在每台节点上创建 Git 实例

3. 从已有 Git 会话创建托管 worktree

4. 在另一台节点重复，而不是复制目录

5. 分别在每个 worktree 里审阅、测试、提交

多节点时，节点选择看什么

交付和清理：分支保留，目录才删除

踩坑：四个容易犯的错

结果：行为上发生了什么变化

可复用的五条原则

相关文档

管理多台远程服务器，不一定要开公网端口：多节点接入与免费中转

问题：一台机器一个终端窗口，机器一多就崩

做法一：把节点接进来，而不是把端口开出去

做法二：控制面不暴露到公网，也能从手机或浏览器访问

踩坑与边界：不能吹的部分

结果：行为上发生了什么变化

可复用的五条原则

相关文档

Codex 在 Windows + PowerShell 上的问题，我们决定把执行面换到 Linux

一、先看真实问题：四类，且不是同一类

A 类：PowerShell 不是 Bash，模型的命令会持续撞墙

B 类：Windows 特有的策略与沙箱层

C 类：跨文件系统与路径映射

D 类：安全软件与企业环境

二、为什么「修好 PowerShell」这条路收益有限

三、我们选的路：Windows 只当入口，任务跑在 Linux 侧

四、代价，说清楚

五、可复用的五条原则

相关文档

停掉控制面之后，服务器上的 AI 任务还在跑：我们为什么把它拆成三层

问题：任务一多，你就开始手动当调度器

我们的做法：三层，各管一件事

停掉控制面之后会发生什么

取舍与被否决的方案

结果：行为上发生了什么变化

可复用的四条原则

想自己跑一遍

A review checklist for AI coding agent output (7 things I check before trusting a change)

The checklist

What this implies about your setup

The uncomfortable part

Self-hosting an AI coding agent workbench: running Codex on my own machines

1. Separate the control plane from the machine that runs the agent

2. One workspace per task, not per conversation

3. Make the agent's output reviewable, not just readable

4. Automate the routines you repeat

What I would tell someone starting today