17 常见问题与排错

遇到问题时，不要一上来重装。先按问题类型缩小范围：安装状态、账号、密钥、配置、网络、权限、项目本身。

无法启动

如果 Codex 无法启动，先检查：

1. Code8 Manager 是否显示 Codex 已安装或已是最新
2. 启动按钮是否可点击
3. 是否刚刚更新过 Codex，需要重新打开 Manager
4. 安装路径是否仍然存在

如果还没有安装，先回到：Codex 下载一键安装教程。

安装失败或进度不动

如果 Codex 安装失败、安装进度不动，先检查：

1. Manager 是否还能正常联网
2. Windows 安装路径是否可写
3. 杀毒软件是否拦截安装程序
4. 是否重复打开了多个安装窗口
5. 电脑是否需要重启后再安装

如果你只是缺少 Windows 安装入口，先重新下载：Codex Windows 安装包下载。

插件安装失败或不可用

先确认当前客户端支持 Plugins，然后检查插件是否安装、其中的连接器或 MCP 服务是否完成授权。安装新插件后要新建任务，旧任务可能不会刷新能力目录。

详细步骤参考：Codex Skills 与 Plugins 安装教程。

Computer Use 或 Windows sandbox 报错

先区分两层：Computer Use 负责可见桌面应用操作，Windows sandbox 负责文件、命令和网络边界。

• 找不到插件、server 未启用、应用未授权：看 Computer Use Windows 教程
• sandbox setup、权限拒绝、找不到模块：看 Windows 原生沙箱报错修复

打不开或打开后空白

如果 Codex 打不开、内置浏览器打不开，优先判断是应用启动问题还是网络页面问题：

1. Manager 首页是否能看到 Codex 状态
2. 点击启动后是否出现窗口
3. 是否能在浏览器打开 ChatGPT / OpenAI 相关页面
4. 是否配置了系统代理但没有排除本地地址

如果是中文界面或语言设置问题，参考：Codex 中文设置教程。

无法登录

优先检查：

1. 当前网络是否能正常访问 ChatGPT / OpenAI
2. 代理节点是否稳定
3. 账号是否有可用套餐或权限
4. 是否可以在浏览器中正常打开 Codex 入口

API Key 无效

如果使用 Code8 API Key，检查：

1. auth.json 是否是合法 JSON
2. OPENAI_API_KEY 是否完整
3. API Key 前后是否有多余空格
4. Code8 账号余额是否充足
5. 是否已经重启 Codex

配置方式参考：Codex API Key 获取与配置。

更完整的获取和保存流程参考：Codex API Key 获取与配置教程。

配置不生效

常见原因是文件路径不对。Windows 通常是：

%userprofile%\.codex\config.toml
%userprofile%\.codex\auth.json

macOS / Linux 通常是：

~/.codex/config.toml
~/.codex/auth.json

还要注意项目级配置可能覆盖用户级配置。修改 config.toml 或 auth.json 后，建议重新启动终端、Codex CLI 或桌面应用。

配置文件细节参考：Codex config.toml 与 auth.json 配置说明。

第三方 API 或中转不通

如果你使用的是第三方 API、中转 API、DeepSeek 或自定义 openai_base_url，优先检查：

1. openai_base_url 是否包含正确的 /v1
2. API Key 是否属于同一个服务商
3. 模型名称是否被该服务商支持
4. 代理配置是否只影响外网，不影响本地地址
5. 修改配置后是否已经重启 Codex

完整配置思路参考：Codex 第三方 API 与中转配置教程。

命令执行失败

先让 Codex 解释它要运行的命令，再确认是否允许。遇到依赖安装、网络访问、删除文件、部署命令时尤其要谨慎。

任务结果不理想

可以把任务拆小：

1. 先让 Codex 读代码并总结
2. 再让它提出修改计划
3. 然后只改一个模块
4. 最后运行验证命令

更多任务习惯参考：用 Codex 完成第一个任务。