DEV Community: EdgeStorage

Codex 在 Windows + PowerShell 上的问题，我们决定换个思路绕开

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 里选的那条路，以及这条路的代价。

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

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 在这三个问题上做的架构选择：为什么控制面和执行面要拆开，状态到底归谁管，以及由此付出的代价。

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

假设你手上有三台机器：一台笔记本、一台常开的家用服务器、一台公司内网主机。你在它们上面分别跑 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 服务，任务还在不在跑。
状态所有权写进文档，而不是留在实现里。 用户遇到「正在重连」时，需要一句话告诉他这意味着什么。

想自己跑一遍

三层结构和每个概念的职责：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.