Codex 沙盒报错 helper_unknown_error: setup refresh had errors（写权限/ACL）

你会遇到什么

Codex 执行 shell 时突然报 helper_unknown_error: setup refresh had errors；就算给了 workspace_write 权限，写项目目录下的文件也反复失败；失败后 agent 只能尝试提权方式执行（需要人工审批）。新电脑 + 从旧电脑拷贝的目录、跨机器/跨用户共享目录、WSL UNC 路径最容易触发。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

Codex 启动时会跑一次「setup refresh」：对配置的 write roots 做 ACL/ACE 检查并补写权限，失败则整体报 setup refresh had errors（界面显示 helper_unknown_error）。典型触发：

启动时的 setup refresh 是对 write roots 的 ACL/ACE 权限自检与补写：客户端要确认当前用户对配置的写目录有权限，检查失败就整体报 setup refresh had errors。

Windows 的 ACL 按 SID 记录属主：目录 owner 若是另一台机器或已删除用户的 SID，当前用户不是 owner，即使有读写权限也无法修改 ACL（修改 ACL 需要 owner 或特权）——「拷贝过来的文件夹」是最典型来源。

UNC/WSL 路径（\wsl.localhost\...）在 GetSecurityInfo 层失败是另一条独立链路（本机实测变体）。

确定性推论：先分清「权限不足」与「ACL 不可改」——icacls <目录> 看 owner 与实际 ACL；拷来的目录用 takeown /f <目录> /r 拿回属权再改 ACL；UNC/WSL 路径的写 root 换成 WSL 内路径（/root/...）而不是 Windows 侧路径；判断路径：报错在权限检查阶段 + 目录来自拷贝 = SID 属主问题，先 takeown。

一步步来

1. 先看沙盒日志定位 — 排查

比瞎猜快：C:\Users\<user>\.codex\.sandbox\sandbox.<date>.log（旧版路径 C:\Users\<user>\.codex.sandbox\...）。搜 setup refresh had errors / write ACE，看具体是哪个路径、什么错误。

2. 改 owner（最常见修复） — 必做

命令行等价：

takeown /f <dir> /r /d y

或图形界面：资源管理器 → 目录属性 → 安全 → 高级 → 更改所有者 → 当前用户，勾选「替换子容器和对象的所有者」。

3. 补 ACL（owner 正确但仍缺权限时） — 必做

icacls <dir> /grant <user>:(OI)(CI)F /T

4. 恢复验证 — 必做

重新开一个 Codex 会话触发 setup refresh，日志出现 errors=[] 即恢复——幂等，不需要重装/重置。

怎么确认修好了

沙盒日志出现恢复标记（实测输出形态）：

sandbox.<date>.log
→ setup refresh completed with errors: []（errors=[]）
→ setup binary completed

Codex 会话里对项目目录的写操作正常，不再需要提权审批。

其它环境的表现

症状

Codex 执行 shell 时报 helper_unknown_error: setup refresh had errors；即使用 workspace_write 权限，写项目目录下的文件也反复失败；失败后 agent 尝试提权方式执行（需要人工审批），同意后才能继续。常见于新电脑 + 从旧电脑拷贝的目录、或跨机器/跨用户共享目录、WSL UNC 路径。

原因

Codex 启动时会跑一次「setup refresh」：对配置的 write roots 做 ACL/ACE 检查并补写权限，失败则整体报 setup refresh had errors（界面显示 helper_unknown_error）。典型触发：

1. 目录 owner 是另一台机器/已删除用户的 SID（旧电脑直接拷贝的文件夹）——当前用户不是 owner，无权修改该目录 ACL → ACE 检查失败；
2. UNC/WSL 路径（\\wsl.localhost\...）上 GetSecurityInfo 失败（本机实测变体，错误码 1）。

解法

1. 先看沙盒日志定位（比瞎猜快）：C:\Users\<user>\.codex\.sandbox\sandbox.<date>.log（旧版路径 C:\Users\<user>\.codex.sandbox\sandbox.<date>.log）。搜 setup refresh had errors / write ACE，能看到具体是哪个路径、什么错误。
2. 改 owner（最常见修复）：资源管理器 → 目录属性 → 安全 → 高级 → 更改所有者 → 当前用户，勾选「替换子容器和对象的所有者」；命令行等价：takeown /f <dir> /r /d y。
3. 补 ACL（owner 正确但仍缺权限时）：icacls <dir> /grant <user>:(OI)(CI)F /T。
4. 恢复验证：重新开一个 Codex 会话触发 setup refresh，日志出现 errors=[] 即恢复——幂等，不需要重装/重置。