Codex app-server process is not available错误原因排查与解决指南

Codex app-server process is not available错误原因排查与解决指南需要先看清适用场景和关键步骤，避免只记结论却忽略实际限制。

错误含义

Codex 的本地后台核心进程（app-server）启动失败 / 崩溃退出 / 无法被前端连接。

Codex Desktop / VSCode Codex 插件分为两层：

1. UI 界面层：Electron 窗口 / VSCode 面板
2. app-server 后端层：本地后台进程，负责调用模型、执行代码、Agent 任务

界面启动成功，但拉起不了后台服务，就会弹出这条报错。

常见原因（按出现概率排序）

1. 安全软件拦截（Windows 最高发）

Windows Defender、火绒、360 等杀毒软件把 codex.exe / app-server 判定为风险程序，阻止进程创建。

现象：点 Reload 反复失败，无明显弹窗，进程一闪就消失。

2. 缓存 / 本地数据库损坏

~/.codex 目录（Windows：C:Users[用户名].codex）内 SQLite 数据库、状态文件损坏，app-server 启动立刻崩溃。

3. 安装包损坏 / 文件缺失

Codex 更新失败、商店安装不完整，缺少 app-server 二进制文件。微软商店版 Codex 经常出现这个 BUG。

4. 路径与权限问题

1. Windows 用户名包含中文、特殊字符
2. 程序放在 OneDrive 同步目录
3. 权限不足，无法读写 .codex 文件夹
4. 不要用管理员模式强行启动（反而更容易异常）

5. 版本 BUG

新版 Codex（VSCode 插件、桌面客户端）存在官方已知 bug：部分版本启用实验性功能配置项（如 thread_tools 等），app-server 无法识别配置直接崩溃。

很多人只能降级插件 / 客户端版本临时解决。

6. 残留进程占用锁

旧的 codex 进程没彻底关闭，占用 SQLite 数据库文件锁，新进程启动失败。

7. WSL、远程 SSH 环境特殊问题

VSCode Remote SSH、WSL 环境下，本地客户端和远端 codex 二进制不匹配，通信异常。

分步修复方案（按优先顺序操作）

步骤 1：彻底杀掉所有 Codex 残留进程

Windows：打开任务管理器，结束所有 codex.exe 进程。

Mac / Linux：

pkill -f codex

关闭 VSCode / Codex 桌面程序的全部窗口。

步骤 2：清理损坏缓存（最有效方案）

找到 .codex 文件夹：

1. Windows：C:Users你的用户名.codex
2. Mac：~/.codex
3. Linux：~/.codex

先备份，然后直接删除整个 .codex 文件夹

重新打开 Codex 客户端，会自动重建配置

注意：删除后历史对话会清空！

步骤 3：杀毒软件放行

把以下文件 / 目录加入白名单：

1. Codex 安装目录内的 codex.exe
2. 用户目录 .codex 整个文件夹

步骤 4：重装 / 更换安装渠道

微软商店安装的 Codex 容易缺文件：卸载商店版，改用官网独立安装包 / npm CLI 版本：

npm install -g @openai/codex

VSCode 插件用户：如果最新版报错 → 安装上一个稳定旧版本

步骤 5：验证基础 CLI 能否正常运行

打开终端执行：

codex --versioncodex app-server

1. 如果这里直接报错，说明二进制本身损坏，需要重装
2. 如果终端可以正常启动 app-server，仅仅 VSCode / 桌面 app 报错，是客户端 UI 与后端路径配置不匹配

步骤 6：进阶排查（查看崩溃日志）

在 Codex 内部菜单打开日志，查看 stderr，经常能看到真实原因：

快速区分场景

预防建议

1. 不要直接强制关闭窗口，尽量正常退出 Codex / VSCode
2. 如果之后再次复现，先打开任务管理器手动结束全部 codex.exe，不用重启电脑
3. 频繁反复出现的话，再去删除 ~/.codex 缓存目录根治
4. 避免将 Codex 安装在 OneDrive 等同步目录中
5. Windows 用户名尽量使用英文，避免中文和特殊字符

本次实际解决情况

现象： Codex 提示 app-server process is not available

根因： 残留的 Codex app-server 僵尸进程卡死，数据库文件被占用上锁。旧进程没正常退出，新界面尝试拉起后台服务冲突。

解决方法： 退出并重启 Codex，相当于完成了：

1. 杀掉卡住的后台 codex 进程
2. 释放 .codex 目录里数据库文件锁
3. 重新正常启动 app-server