Codex预览功能在Agent Space中失效是因沙箱环境与app-server握手失败，而非模型或API问题；需通过CLI验证、重载沙箱运行时、指定端口、清除缓存并重建上下文来修复。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Agent Space 中 Codex 预览功能失效（如点击“Preview”无响应、白屏、加载转圈后中断、或报错提示 Failed to load preview）不是模型或 API 层问题，而是 Agent Space 的沙箱环境与 Codex 的预览服务进程握手失败导致的——它卡在本地 app-server 启动阶段，而非网络或鉴权环节。
确认是否为 Agent Space 特有预览故障
打开终端，cd 进入你的 Agent Space 项目根目录 → 运行 codex preview --port 3001 → 观察控制台输出。若出现 [AppServerConnection] Starting app-server connection currentState=connecting 并持续卡住超过8秒，且浏览器访问 http://localhost:3001 显示连接被拒绝，则确认是 Agent Space 沙箱内 app-server 子进程未成功 fork，非 Codex 本身 bug。
这一步必须做：CLI 能跑通预览，但 Agent Space 界面点 Preview 失败，说明问题出在 Electron 渲染进程与沙箱中 native host 的 IPC 通道上，不是你写的代码或配置文件的问题。
修复沙箱 app-server 启动失败
方法一：强制重载沙箱运行时（推荐优先尝试）
关闭所有 Codex 和 Agent Space 进程 → 打开任务管理器，结束全部 codex.exe、ChatGPT.exe、app-server.exe 进程 → 在 Agent Space 设置页中，找到「Advanced」→ 点击「Reset Sandbox Runtime」→ 等待进度条走完（约12秒）→ 重启 Agent Space。
方法二：手动指定沙箱绑定端口（绕过自动端口冲突）
编辑项目根目录下的 .codex/agent-space.toml → 在 [preview] 段落下新增一行：port = 3003 → 保存 → 在 Agent Space 中点击 Preview 前，先在终端执行：codex preview --port 3003 --no-browser → 再点界面按钮。这能避免 Electron 渲染进程抢不到默认端口 3001。
【关键前提】 必须确保 .codex/agent-space.toml 文件权限为当前用户可读写，Windows 上右键属性 → 安全 → 编辑 → 勾选“完全控制”，否则修改会被静默丢弃。
清除预览缓存并重建上下文
第一步：停用 Agent Space 自动预览监听
在 Agent Space 左下角状态栏，点击齿轮图标 → 取消勾选 “Auto-refresh preview on file change”。这能防止旧缓存文件被反复注入错误状态。
第二步：删除预览专属缓存目录
进入 %LOCALAPPDATA%\OpenAI\Codex\cache\preview\（Windows）或 ~/Library/Caches/OpenAI/Codex/preview/（macOS）→ 全选内容 → 彻底删除 → 不要放入回收站，直接 Shift + Delete。
第三步：重建预览上下文图谱
回到 Agent Space 项目根目录 → 终端执行：codex read --project . --include preview → 等待输出出现 Preview context built: 7 files indexed, 2 preview handlers resolved → 此时再点击 Preview 按钮。
