处理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，经常能看到真实原因：

日志关键词	真实原因	解决方案
unknown feature key	版本兼容 bug	降级版本
database locked	进程没杀干净	杀掉所有 codex 进程
permission denied	文件夹权限问题	检查目录权限

快速区分场景

使用环境	最可能原因	优先操作
VS Code Codex 插件	插件新版本 bug	降级插件 + 删除 .codex
Codex Desktop（Windows 商店）	安装包缺失文件	不要用商店版，改用官网安装包
自己开发调用 codex app-server	路径 / 通信配置错误	检查 stdio 通信、二进制路径配置

预防建议

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