最近这两天，只要在开发者群里提到 Codex CLI，几乎必有人接一句“更新完 daemon 又坏了”。我前天刚帮一个同事处理了这个问题，他的报错非常典型——failed to open daemon process: 拒绝访问。（os error 5），明明前一天还好端端的，跑完更新命令再启动就翻车。查了一圈发现不是他的配置烂了，而是新版 CLI 在 Windows 上会主动拒绝从管理员权限的终端启动 daemon，旧进程又占着资源不放，两边一叠加就卡死了。
这篇文章就把我排查 Codex CLI 更新后 daemon 安装失败/启动失败的完整思路写下来，按报错信息分类，给 Windows、macOS、Linux 三套可以照抄的修复流程，最后再说一个容易搞混的情况：报错里出现的“error response from daemon”很多时候根本不是 Codex 的 daemon，而是 Docker 守护进程在拉镜像失败。刚踩坑的可以直接跳到对应章节，想彻底搞懂原理的可以从头看。
1. 先搞明白：更新之后，daemon 为什么“必须”重装一次
1.1 daemon 在 Codex CLI 里的真实角色
很多人的第一反应是“更新个命令行工具而已，怎么还扯上 daemon 了”。这要先从 Codex CLI 的架构变化说起。早期版本它就是纯粹的交互式命令行：你输入提示词，它调模型，把结果打印出来，会话结束进程就退出。功能越来越重之后——尤其是要支持 IDE 插件、长会话上下文、鉴权凭证自动刷新、本地缓存这些能力——每次请求都重新拉起子进程的代价就太高了。于是新版本引入了常驻后台进程，也就是我们说的 daemon。
这个 daemon 平时做的事情包括：持有当前会话的上下文和临时状态、向本地端口或命名管道提供 HTTP/WebSocket 服务（IDE 插件和前端面板就是通过这些来跟 CLI 通信的）、在后台刷新 API 鉴权凭证、以及统一管理本地的工具调用缓存。CLI 主进程更像是一个“前台”，把终端输入转发给 daemon，再把结果拿回来渲染。
打个比方：CLI 是门店前台，daemon 是后厨。升级 CLI 相当于你换了前台服务员的制服和话术，但后厨还是老班底。老后厨不认识新的传菜窗口，新前台也不知道该把单子递到哪个窗口，于是表面现象就是“daemon 安装失败”。实际原因往往不是安装这个动作本身失败，而是新旧版本之间的进程、路径、状态文件和安全策略没有同步。
1.2 升级导致 daemon 罢工的三条典型链路
从我见过的大量案例看，更新后 daemon 出问题基本逃不开下面四条链路。搞清楚链路比记命令更重要，因为命令很快会过时，链路不会。
残留进程与资源占用：旧版 daemon 还在后台跑着。新版启动时可能检测到旧的 socket 文件、pid 文件、命名管道或端口被占用，尝试接管又因为权限或握手协议不一致而失败。Windows 上特别容易遇到：旧进程是用管理员终端拉起来的，新进程想把它杀掉，结果自己也是普通权限，杀不动，只能报“拒绝访问”。
二进制路径变化与 PATH 缓存：npm、Homebrew、安装脚本在升级时会替换二进制；如果新版二进制换了名字，或者装到了另一个目录，而你的 shell 会话还是旧 PATH 快照，就会找不到新二进制。IDE 插件里的“unable to locate the codex cli binary”基本都出自这一类。
状态目录版本不兼容：Codex 的用户数据目录（Windows 在 %USERPROFILE%\.codex，macOS/Linux 在 ~/.codex）里存着会话数据库、缓存、日志和 socket 文件。新版 daemon 第一次启动时会尝试复用或迁移这些旧文件，一旦发现格式不对或文件被旧进程锁定，就可能直接中止，看起来就是“安装失败”。
平台安全策略拦截：Windows 上，Codex 检测到终端是以管理员身份运行时，会明确拒绝启动 daemon（报错会提示你用 non-elevated terminal）。macOS 上，从浏览器下载的未签名二进制会被 Gatekeeper 隔离，daemon 在隔离状态下根本无法正常工作。Linux 上则更多是文件属主、SELinux 这类权限问题。
清楚了这些，后面的修复流程就很好理解了：杀残留、清状态、理路径、过权限、重装验证。
2. 先读准错误信息：不同报错对应完全不同的处理方向
处理这类问题最大的忌讳就是不看报错直接重装。重装有时候能碰巧解决，但解决不了下次还会再犯。这里把我实际遇到过的几种报错按“错误原文→根因→处理方向”整理成一张表，后面再逐个展开。
| 报错关键词 | 根因 | 处理方向 |
|---|---|---|
| failed to open daemon process: 拒绝访问。（os error 5） | Windows 权限/ACL/终端提权状态 | 用非管理员终端、杀旧进程、修目录权限 |
| start the windows daemon from a non-elevated terminal | 检测到管理员终端 | 换成普通权限终端启动 |
| unable to locate the codex cli binary or required runtime components | PATH 问题/二进制丢失/运行时缺失 | 重刷 PATH、确认安装路径、装 Node LTS |
| vd is starting, please check vendor daemon's status in debug log | 第三方组件的 vendor daemon 未就绪 | 打开该组件的 debug 日志定位 |
| error response from daemon: failed to resolve reference "cr.weaviate.io/semi/..." | Docker 拉镜像失败（不是 Codex daemon） | 手动 docker pull、换镜像地址/标签 |
| error response from daemon: get "https://registry-1.docker.io/v2/": ... | Docker Hub 网络/DNS 问题 | 检查 DNS、重启 Docker、配置 registry mirror |
| port already in use / address already in use | daemon 端口被残留进程占用 | 查端口占用、杀进程、清理 |
2.1 “failed to open daemon process: 拒绝访问。（os error 5）”
这个是我开头提到过的 Windows 最常见错误码。os error 5 对应系统级的“拒绝访问”，出现在创建进程这个动作上，基本就是在 CreateProcess 环节被权限墙挡了。常见原因有两个：一是你当前终端本身是管理员权限，Codex 出于安全设计明确拒绝在 elevated token 下启动后台 daemon；二是用户数据目录或安装目录的 ACL 不对，新进程没有写入权限。
这里需要特别说明一点：Codex 拒绝在管理员终端里跑 daemon 是故意为之，不是 bug。后台进程持有完整权限，意味着任何同等权限的进程都能通过它做危险操作，所以它宁可在启动时报错，也不愿给用户一个“看起来能用但后门大开”的 daemon。知道这一点，你就别跟它对着干了，老老实实换普通终端。
2.2 “unable to locate the codex cli binary or required runtime components”
这条报错更多出现在 IDE 插件、编辑器终端或自定义脚本里，而不是直接敲 codex 命令。意思是启动方按 PATH 去找 codex 可执行文件，结果没找到；或者找到了二进制，但依赖的运行时组件缺失。典型场景是：你用 nvm 装了多个 Node 版本，全局包装在某个版本的路径下，IDE 却用另一个 shell 环境去找，结果扑空。
处理方式很简单：先在终端里跑where codex（Windows）或which codex（macOS/Linux）确认实际路径，然后在 IDE 的 codex 扩展设置里显式指定这个完整路径。如果多人共用同一台机器，还要注意是不是其他用户改了全局安装目录导致路径漂移。
2.3 “error response from daemon: failed to resolve reference ...”
看到“error response from daemon”这句，先冷静一下——这是 Docker 守护进程的经典错误前缀，不是 Codex 自己的 daemon。一般在两种场景出现：你的项目里用容器跑辅助服务（检索服务、沙箱环境、向量数据库等），Codex 在干活时需要先拉取这些镜像；或者你完全没意识到辅助服务是容器化的，只看到错误出现在 Codex 环境里。这两种情况的排查思路完全不同，千万别用清 Codex 状态目录的方式去处理 Docker 报错，那是白费劲。第五节我会专门讲这个。
2.4 “vd is starting”之类第三方 daemon 的提示
还有一类报错长得很怪，比如 “vd is starting, please check vendor daemon's status in debug log”。它直接告诉你了：某个第三方（vendor）的 daemon 正在启动中，但还没就绪，让你去 debug 日志里看具体状态。这时候关键是找到“谁的 debug log”。通常日志会放在用户目录下对应组件的子目录里，或者跟随 Codex 主日志一起输出。先找到具体组件名，再定位它的日志，不要在主日志里翻半天找不存在的东西。
还有一类常见但容易被忽略的提示：日志末尾写着 “port already in use”。这是 daemon 想监听某个本地端口，结果发现被占用了。有可能是旧 daemon 还活着，也有可能是别的软件占了这个端口。处理方式是按错误信息里给出的端口号，用 netstat 或 lsof 查占用进程。
3. Windows 修复实战：权限、残留进程、路径三板斧
3.1 先确认终端是否处于管理员状态
如果你看到的报错是 os error 5 或 non-elevated terminal，第一件事不是重装，而是看窗口标题栏。Windows Terminal 在管理员模式下，标签页标题前面会有“管理员: ”三个字；老版 cmd 窗口也一样。只要带了这三个字，先关掉，重新用普通方式打开终端。
注意一个细节：即便你只是在一个普通窗口里敲命令，如果这个窗口是通过“以管理员身份运行”的快捷方式拉起来的，或者你的默认终端配置文件被设置成了 elevated，那照样是管理员 token。检查方法是执行：
whoami /groups | findstr /i "S-1-16-12288"能查到 S-1-16-12288 就说明当前进程是高完整性级别（管理员），普通权限下应该只能看到 S-1-16-8192。看不到 12288 才是普通权限终端，可以继续。
3.2 杀残留进程、清理状态目录、重装
确认终端权限没问题之后，按顺序做下面几步。我在实际处理中，大多数情况做到前两步就恢复了。
# 1. 查看 codex 相关进程 tasklist | findstr /i codex # 2. 结束旧进程（一次性杀掉所有 codex 进程） Get-Process | Where-Object { $_.ProcessName -like "*codex*" } | Stop-Process -Force # 3. 备份登录态和配置 Copy-Item "$env:USERPROFILE\.codex\auth.json" "$env:USERPROFILE\.codex\auth.json.bak" -ErrorAction SilentlyContinue Copy-Item "$env:USERPROFILE\.codex\config.toml" "$env:USERPROFILE\.codex\config.toml.bak" -ErrorAction SilentlyContinue # 4. 清理可能引起冲突的缓存和日志（不要删 auth.json / config.toml） Remove-Item "$env:USERPROFILE\.codex\cache" -Recurse -Force -ErrorAction SilentlyContinue Remove-Item "$env:USERPROFILE\.codex\log" -Recurse -Force -ErrorAction SilentlyContinue Remove-Item "$env:USERPROFILE\.codex\sessions" -Recurse -Force -ErrorAction SilentlyContinue如果数据目录下能看到明显的 socket 文件或 pid 文件（扩展名可能是 .sock、.pid、.lock），也一并删掉。删完这些再看一遍有没有残留进程，然后重装：
# 5. 重新安装 npm uninstall -g @openai/codex npm install -g @openai/codex # 6. 验证 codex --version where.exe codex为什么一定要先杀进程再删目录？因为旧 daemon 如果还活着，它会持续占用会话数据库和 socket 文件，你删到一半它又写回来了，等于白删。Windows 上文件被占用时删除还会报“另一个程序正在使用此文件”，看到这个提示基本可以断定就是旧进程没死透。
3.3 npm 全局目录权限：另一个被忽略的元凶
如果重装完还是报同样错误，就要怀疑 npm 全局安装目录本身。常见情况是之前用管理员终端执行过npm install -g，导致包被装进了C:\Program Files\nodejs这种需要管理员权限才能写的目录。普通终端里再跑codex，CLI 能读，但它尝试在安装目录旁边写 daemon 需要的辅助文件时，就被 ACL 拒绝了。
先看全局目录在哪：
npm prefix -g如果这个路径在 Program Files 下，建议把 npm 全局目录改到用户目录：
npm config set prefix "$env:APPDATA\npm"改完确认 PATH 里有没有%APPDATA%\npm。没有的话，在系统环境变量里把它加进去，重新开终端，再全局装一次 codex。这一步是很多人重装十遍都不好的真正原因，值得仔细检查。
3.4 验证 daemon 是否真的起来了
重装完很多人只看到codex --version能出版本号就以为好了，但版本号只能证明 CLI 主程序活着，daemon 是另一回事。验证 daemon 的方式是真正跑一次交互会话，让它在本地起服务，然后观察日志文件有没有新增内容。
如果在 Windows 上依然看到 shared memory 或命名管道相关的报错，可以再检查是否有安全软件拦截了 codex 的本地通信。这类拦截通常会有对应的安全软件日志。实在找不到原因时，把旧日志备份后在 debug 模式下复现一次，拿到带操作系统的详细错误信息再搜，比盲目试命令高效得多。
4. macOS 与 Linux：过一次干净的重装流程
4.1 定位旧进程、端口和残留文件
macOS 和 Linux 的处理思路一样：先把旧世界清干净，再迎新版本。第一步同样是用进程名定位残留 daemon：
pgrep -fl codex有输出就把对应进程结束掉：
pkill -f codex # 如果不放心，再确认一次 pgrep -fl codex然后查看用户数据目录里有没有不该存在的 socket、pid、lock 文件：
ls -la ~/.codex/常见的碍事文件是~/.codex/daemon.sock、~/.codex/daemon.pid这类。删掉它们：
rm -f ~/.codex/*.sock ~/.codex/*.pid ~/.codex/*.lock这里提醒一句：~/.codex目录本身别整个删。里面的auth.json是你的登录凭证，删了就得重新登录一次。我会先备份：
cp ~/.codex/auth.json ~/.codex/auth.json.bak cp ~/.codex/config.toml ~/.codex/config.toml.bak 2>/dev/null4.2 macOS 特有的 Gatekeeper 与 Homebrew 问题
macOS 上还有两个额外关卡。第一个是 Gatekeeper 隔离属性。如果你不是从官方渠道自动更新，而是手动下载了新版二进制，系统会给它打上com.apple.quarantine标记。带这个标记的进程在访问用户目录时行为会很奇怪，daemon 起不来是常有的事。可以在“系统设置 → 隐私与安全性”里放行，也可以对已下载的二进制文件移除隔离属性：
xattr -d com.apple.quarantine "$(which codex)" 2>/dev/null第二个是 Homebrew 自身的问题。很多用户更新 codex 的时候，brew update先失败了，连带 codex 也跟着出问题。这种情况要先修 Homebrew：确认 Xcode Command Line Tools 已安装，装好之后跑一下brew doctor看它提示什么。如果连 Homebrew 本身都没装好，或者 brew 报错提到 /opt/homebrew 目录权限不对，先把这些基础问题解决掉再谈 codex。注意：brew install codex的时候不要加 sudo，Homebrew 本身就不允许在 root 下跑。
4.3 Linux 上容易踩的坑：磁盘空间、属主和 nvm
Linux 相对简单，但有几个坑我见过不止一次。第一是磁盘空间不足。daemon 会往 ~/.codex 下写日志和会话缓存，你构建容器或者装其他工具时把磁盘写满了，它启动时连日志文件都创建不了，报错会非常隐晦。先看一眼：
df -h ~第二是数据目录属主不对。如果你曾经用 sudo 跑过某个 codex 相关脚本，~/.codex 下某些文件可能变成了 root 属主，普通用户进程写不进去。用ls -la看到属主不对，直接改回来：
sudo chown -R $(whoami) ~/.codex第三是 nvm 用户。codex 如果是通过npm install -g装的，而你又用 nvm 管理多个 Node 版本，升级后 nvm 切到了另一个 Node 版本，全局命令路径就变了。这时候重新安装的 codex 可能找不到原来的二进制。处理办法是切回安装 codex 的那个 Node 版本，或者在 shell 配置里固定默认版本。
清理完残留、处理完平台问题之后，重装命令和 Windows 那套类似：
npm uninstall -g @openai/codex npm install -g @openai/codex # 如果你是 brew 安装的 brew uninstall codex brew cleanup brew install codex装完用which codex和codex --version验证，然后跑一个真实会话确认 daemon 正常。
5. 别混淆：有些“daemon 报错”其实是 Docker 守护进程在拉镜像失败
5.1 怎么区分 Codex daemon 和 Docker daemon
前面提过，“error response from daemon”是 Docker 的经典错误前缀。判断依据很简单：如果你看到错误里包含https://registry-1.docker.io/v2/、某个镜像仓库地址（比如cr.weaviate.io/semi/...），或者docker.io/...这种格式的引用，那说的就是 Docker 守护进程在拉取容器镜像时失败了，跟 Codex 自己的 daemon 不是一回事。
为什么 Codex 环境里会出现 Docker 报错？常见场景是：Codex 的某些辅助能力（比如本地语义检索、沙箱执行）在部分配置下通过容器承载，或者你的工作项目本身用 docker compose 启动了辅助服务。Codex 在调用这些服务时，Docker 需要先把镜像从仓库拉下来，拉不动就直接把这个错误抛给你。
5.2 两种典型的镜像拉取失败与处理
第一种：拉取第三方仓库镜像失败，比如报错的地址里有 “cr.weaviate.io/semi/...” 这种格式。
这种报错多半是镜像仓库的访问出了问题，或者镜像标签不存在。先手动拉一次看看完整错误：
docker pull cr.weaviate.io/semi/镜像名:版本号手动拉能成功，说明问题出在自动拉取的环境变量或认证上；手动也失败，就检查网络可达性。我见过有人卡在这里好几天，最后发现是自己把镜像标签写错了，服务端返回 404，被 Docker 包装成了 resolve reference 失败。所以第一步永远是单独 pull 一次，把完整错误看清楚。
第二种：拉取 Docker Hub 官方镜像失败，报 get "https://registry-1.docker.io/v2/": net/http ... timeout。
这是网络连接层面的问题。先确认 DNS 解析正常：
nslookup registry-1.docker.io解析正常但请求超时，常见原因是到 Docker Hub 的连接不稳定。应对方法是在 Docker 的 registry mirror 配置里加上你确认可用的加速地址。Linux 上改/etc/docker/daemon.json：
{ "registry-mirrors": ["https://你确认可用的镜像加速地址"] }改完重启 Docker 服务再拉取。macOS 和 Windows 的 Docker Desktop 则在设置面板里有对应的 Registry mirrors 配置项。注意只能填你实际验证过可用的地址，填了不可用的反而更慢。还有一个经常被忽略的原因就是磁盘空间不够，拉一半失败，先docker system df看看。
5.3 这类报错的排查顺序
我的习惯顺序是：先看错误里的镜像仓库地址，手动 pull；再查 DNS 和连通性；再看磁盘空间和 Docker 服务状态；最后才考虑改 mirror 配置。遇到 “vd is starting, please check vendor daemon's status in debug log” 这类第三方 daemon 提示，则是先确认哪个组件起了 vendor daemon，然后单独查那个组件的日志，别在 Codex 主日志里瞎找。
6. 更新后的习惯性检查：把“daemon 安装失败”挡在发生之前
6.1 更新 Codex CLI 的正确姿势
先说怎么更新。Codex CLI 的安装渠道不同，更新方式也不同，不能简单“删了重装”。npm 安装的使用npm update -g @openai/codex；Homebrew 安装的使用brew upgrade codex；如果是官方提供的安装脚本，通常会在 README 里写明对应命令。更新前先记下当前版本号codex --version，万一新版本有兼容问题，还能快速回退：npm 方式用npm install -g @openai/codex@<版本号>指定版本重装。
更新完立刻在同一个终端里继续跑 codex，是最容易出问题的操作。原因前面讲了：旧 daemon 还活着、当前 shell 的 PATH 还是旧的。我的习惯是更新后先关掉所有终端（含 IDE 内置终端），然后新开一个干净的窗口启动。如果 IDE 集成了 codex，IDE 本体也要完全退出再重启，这样才能让它重新解析相关配置。
6.2 我的避坑清单和个人习惯
整理几条我踩过之后的教训：
- 不要把整个 ~/.codex 删掉。只清 cache/log/sessions 这类可再生数据，auth.json 和 config.toml 先备份。
- 不要在管理员终端里长期运行 codex。Windows 上这不是“能用就行”的事，新版会直接拒绝启动 daemon，每次都得折腾一遍。
- 全局安装路径统一。npm、nvm、brew 别混着来，混着装容易造成“有两个 codex 但都不知道哪个生效”的混乱。用
which codex看清楚当前用的是哪个。 - 更新前先看 release notes。daemon 启动方式、数据目录结构这类改动一般都会写在变更说明里，提前知道能省不少排查时间。
- 把容器服务和 Codex 本身分开排查。看到 error response from daemon 先判断是 Docker 还是 Codex，不要笼统地全按“重装 codex”处理。
最后分享一个我现在固定的操作习惯：每次更新完，我会先跑codex --version，然后随便起一个会话让它加载上下文，再打开日志目录确认日志文件在正常滚动。整个检查不超过两分钟，但能让我确认 daemon 是真的活了，而不是只有 CLI 外壳活着。这套流程已经帮我避免了至少三次“看似正常、实际 daemon 根本没起来”的尴尬。
