附录 D · 最新补充 2026-10-08

常见踩坑全集索引

每章末尾的「常见踩坑」卡片散落在各处,这里按问题类型聚合成一张速查地图。你卡住时,先到这里按现象找对应小节。

排错顺序 先看“现象”是不是对得上,再看“最常见原因”,最后照“怎么处理”做。不要一急就重装全家桶,很多问题只是路径、缓存、权限或 DNS 等待。

环境与安装类

输入 node -v 或 npm -v 提示 command not found

常见原因: Node.js 没装成功,或终端还没刷新环境变量。
怎么处理: 先完全退出终端再打开。如果还不行,重新安装 Node.js LTS 版本,安装完再跑 node -v 和 npm -v。
相关章节: 第 02 章 · 常见踩坑

装了 Codex,但 codex 命令找不到

常见原因: 全局 npm bin 路径没进系统 PATH,或者安装命令执行失败。
怎么处理: 先跑 npm list -g --depth=0 看有没有 @openai/codex。没有就重新跑安装命令;有但找不到命令,重开终端或让 Codex/终端帮你检查 npm global bin 路径。
相关章节: 附录 C · 安装与升级

误装了不带 @openai/ 的 codex 包

常见原因: npm 上可能存在名字相近的包,新手容易把包名打短。
怎么处理: 卸载错误包,再安装 @openai/codex。以后复制教程里的完整命令,不要手打包名。
相关章节: 第 02 章 · 常见踩坑

npm install 报 EACCES 权限错误

常见原因: 全局 npm 安装目录没有写入权限。
怎么处理: 不要急着乱加 sudo。先让 Codex 根据你的系统检查 npm 全局路径,必要时换成用户级 npm 目录,或使用官方推荐的 Node 版本管理方式。
相关章节: 第 02 章 · 常见踩坑

安装卡住几分钟没动

常见原因: 网络慢、npm registry 连接不稳定,或终端正在下载大包。
怎么处理: 先等一会儿。如果 10 分钟完全没输出,按 Ctrl+C 中断,重新运行。反复失败时再检查网络和 npm 源。
相关章节: 第 02 章 · 常见踩坑

登录与网络类

codex login 时浏览器没自动弹出

常见原因: 默认浏览器拦截、远程终端没有浏览器、系统没把链接打开。
怎么处理: 看终端里有没有登录链接,手动复制到浏览器。远程机器可以用 codex login --device-auth 走设备码登录。
相关章节: 附录 C · 登录命令

登录失败,提示账号或权限不满足

常见原因: 账号没有对应 Codex 权限、组织策略限制、登录到了错误账号。
怎么处理: 先确认你登录的是要使用 Codex 的那个 ChatGPT/OpenAI 账号。再退出 codex logout 后重新登录。企业或团队账号要确认管理员是否开放了 Codex。
相关章节: 第 02 章 · 登录问题

Codex 提示 network error

常见原因: 本机网络、代理、公司防火墙、区域网络限制,或沙盒默认不允许命令联网。
怎么处理: 先确认浏览器能打开相关服务。再分清是“Codex 自己连不上”还是“Codex 跑的命令不能联网”。后者通常和沙盒网络权限有关,不要直接开最大权限,先让 Codex 解释需要访问哪个域名。
相关章节: 第 03 章 · 审批与沙盒

第一次启动很慢

常见原因: 首次登录、模型列表、配置读取、项目扫描都可能花时间。
怎么处理: 第一次先耐心等。长期每次都慢,再跑 codex doctor 看诊断报告,或换一个更小的项目目录启动。
相关章节: 附录 C · codex doctor

Codex App / CLI 高频问题

模型报 404、model not found,但换别的模型能跑

常见原因: 当前账号、地区、组织策略或这一个 Codex 版本暂时拿不到你选的模型;也可能是配置里手动写了一个过新的模型名。
怎么处理: 先切回默认推荐模型,再更新客户端。CLI 用 /model 重新选择。Spark 已于 2026-09-14 停用;GPT-5.5 将在 10 月 14 日退役,不是已经停用。替代型号要看套餐和工作区权限,最新建议见模型迁移清单。GPT-5.4 / mini 也已不再提供给 ChatGPT 登录的 Codex。别忘了检查定时任务和脚本;不要把 ChatGPT 登录的退役公告直接套用到 OpenAI API。
参考来源: 先看官方 Models 和 Troubleshooting;仍无法判断时,再查 OpenAI Codex GitHub issues。

登录成功后仍提示未登录、权限不够,或者反复要求登录

常见原因: 登错账号、会话过期、公司/团队管理员没开放 Codex,或者把 API Key 登录和 ChatGPT 账号登录混在一起理解了。
怎么处理: 先确认浏览器里登录的就是要用 Codex 的账号。CLI 可先 codex logout 再重新登录;远程机器或浏览器打不开时用设备码登录。团队账号要请管理员确认 Codex 和相关功能是否已开放。
参考来源: OpenAI Codex GitHub issues 中常见 auth/login 标签;自动化令牌与登录差异可参考 Codex Authentication。

Codex App 一直转圈、发送按钮卡住,尤其是 Windows 上更明显

常见原因: 线程在等审批、终端面板卡住、网络连接不稳、项目太大,也可能是某个桌面端版本的 Windows 问题。
怎么处理: 先看有没有审批弹窗。再打开终端跑 git status 或 pwd 这种轻量命令确认线程还活着。仍然不动时,新开一个更小范围的线程,或者重启 App。反复复现就用 / 发送反馈并附日志。
参考来源: Codex App Troubleshooting 的 stuck states、terminal issues; GitHub issues 中也有 Windows 转圈反馈。

突然大面积报错、提示 at capacity 或一直连接失败

常见原因: 不一定是你电脑的问题,可能是 OpenAI 服务、某个模型或某个 Codex 组件正在降级。
怎么处理: 先看 OpenAI Status 的 Codex 状态。如果状态页正在提示问题,就先保存现场、减少反复重试,等服务恢复后再继续。赶时间时可以切模型、切 CLI/App 表面做交叉验证。
参考来源: OpenAI Status 会展示 Codex 组件状态和历史可用性。

教程里的按钮或命令找不到,但别人截图里有

常见原因: Codex App 和 Codex CLI 可能在不同时间拿到新功能;同一个功能也可能先在 CLI、App 或某个平台灰度。
怎么处理: 先更新 App 和 CLI。CLI 用 codex --version;桌面端可在设置或应用关于页查看。找不到按钮时,先用 Command menu、设置搜索或直接问 Codex:“我当前版本里这个功能在哪里?”
参考来源: Codex App Troubleshooting 说明 App 与 CLI 可能依赖不同版本。

内置终端看起来卡住,不知道能不能停

常见原因: 有时是开发服务器正常运行,有时是安装依赖、测试命令或网络请求真的卡住了。
怎么处理: 先判断命令类型:如果是 npm run dev 这类服务,一直占着终端是正常的;如果安装或测试 10 分钟没输出,可以 Ctrl+C 中断。桌面端终端面板可关闭再用 Cmd+J 打开。
参考来源: Codex App Troubleshooting 的 terminal issues。

Worktree 里缺 .env、依赖或本地配置,代码跑不起来

常见原因: Worktree 是另一个 checkout,默认有 Git 跟踪的文件;被 .gitignore 忽略的 .env、密钥、本地配置不会自动带过去。
怎么处理: 不要把密钥提交进 Git。需要给 Codex-managed worktree 复制安全的本地配置时,在项目根目录加 .worktreeinclude,只列必须复制的忽略文件,比如 .env.local。依赖缺失就给 worktree 跑一次安装脚本或配置 Local Environment。
参考来源: Codex App Worktrees 的 .worktreeinclude 说明。

Review 面板里出现“不是 Codex 改的”文件

常见原因: Review 面板按 Git 状态展示变更,它会看到你之前没提交的文件,不只显示 Codex 这一次改的内容。
怎么处理: 切到 staged / unstaged 或 “Last turn changes” 视图看本轮改动。开始大任务前尽量先提交或保持工作区干净,这样 Codex 改了什么会更清楚。
参考来源: Codex App Troubleshooting 的 review panel FAQ;另见 Review。

自动化跑出很多后台 Worktree,磁盘空间越来越大

常见原因: 频繁自动化会创建背景 worktree;被置顶、正在运行或设为 permanent 的 worktree 不会轻易清掉。
怎么处理: 归档不需要的自动化运行,不要随手 pin 每个结果。长期项目可以在设置里检查 worktree 保留数量,重要 worktree 再转成 permanent。
参考来源: Codex App Troubleshooting 的 automations FAQ;另见 Worktrees cleanup。

内置浏览器打不开登录后的后台,或看不到 Chrome 里的登录态

常见原因: Codex 内置浏览器适合预览本地、公开或不需要登录的页面;它不是你的 Chrome 个人资料,不会天然共享 Chrome Cookie。
怎么处理: 本地开发页优先用 @Browser 和 localhost。必须操作已登录网站时,用 Chrome 扩展和 @Chrome,并只给当前任务需要的网站权限。
参考来源: In-app browser 说明本地预览和登录网站的边界;登录网站参考 Chrome extension。

Chrome 扩展显示已安装,但 Codex 还是操作不了页面

常见原因: Chrome 个人资料不对、扩展被禁用、网站没有授权、任务没点名 @Chrome,或组织策略限制了浏览器能力。
怎么处理: 确认正在用安装扩展的 Chrome Profile,扩展处于启用状态。重新给目标域名授权,再在提示词里明确写 @Chrome 和要操作的网址。涉及隐私页面时,只开放必要站点。
参考来源: Codex Chrome extension 的权限与数据安全说明。

Computer Use 看不到桌面 App、点不了,或报权限 / sandboxPolicy 相关错误

常见原因: 插件没装、App 没被允许、macOS 没给 Screen Recording / Accessibility,Windows 上目标窗口不在前台;少数情况下是版本或系统兼容问题。
怎么处理: 先在 Codex 设置里安装并启用 Computer Use。macOS 去系统设置授权屏幕录制和辅助功能;Windows 保持目标 App 可见。若精确报 sandboxPolicy 或同类内部错误,先更新 App,再按官方建议提交 issue 和日志。
参考来源: Computer Use 权限说明; GitHub issues 中有 Windows Computer Use 相关反馈。

Appshots 快捷键没反应,截图传不到线程里

常见原因: Appshots 现在支持 macOS 和 Windows 桌面端,但不能从 CLI 新建。快捷键、接收对话或组织权限不对,都可能看起来像“没反应”。
怎么处理: 先更新桌面 App:Mac 同时按左右 Command,Windows 同时按左右 Alt,或使用自定义热键。检查 Appshot destination,避免传到最近操作的另一条对话。Mac 还要检查屏幕录制和辅助功能权限;Windows 截图在主 App 打开。仍失败可先手动附截图,详见分系统步骤。
参考来源: Appshots 的权限与排错说明。

插件已经安装,但新任务里还是找不到技能或工具

常见原因: CLI 版本过旧、插件刷新失败、外部连接尚未完成授权,或工作区策略不允许该插件。
怎么处理: 先把 CLI 更新到 0.154.0 或更高,再打开 Plugins 或 /plugins 确认安装状态和授权提示。新版当前会话通常会自动刷新工具、Skills 和 Hooks;仍没出现时再新开会话,并让 Codex 列出当前可用能力。IDE 扩展目前不支持插件。
参考来源: A7 · 插件安装和调用; OpenAI Plugins。

MCP 或插件突然要求重新登录,授权后刚才的操作也没有继续

常见原因: OAuth 凭据已经过期或刷新失败。CLI 0.154.0 会显示新的登录挑战,但为了避免重复写入,被拒绝的工具调用不会自动重跑。
怎么处理: 按可信的官方登录流程重新授权,然后先确认刚才的读取、发送或写入是否已经发生。确认没有重复风险后,再手动重新提交那一步;不要连续猛点重试。
参考来源: A11 · 插件和 MCP 更新; OpenAI Changelog。

/import 不可用,或没有导入想要的旧聊天

常见原因: 当前任务还在运行、正在远程会话、连接了本地 app-server daemon,或旧聊天不在支持的最近 30 天范围内。CLI 最多导入 50 条近期聊天。
怎么处理: 回到空闲的本地 CLI 会话再输入 /import,选择 Claude Code 或 Cursor。桌面端则去 Settings > Import; Claude Cowork 目前只在桌面端导入流程中支持。
参考来源: A10 · 从其他 Agent 导入; OpenAI Import from another agent。

手机 Remote 看不到任务、一直重连,或消息加载失败

常见原因: 电脑主机休眠或离线,手机和电脑不是同一账号/工作区,配对已失效,或任务消息在网络波动后没有正常加载。
怎么处理: 保持电脑唤醒和在线,确认账号与工作区一致。消息失败先点 Retry;仍不行就去电脑的 Settings > Connections 检查或重新配对。高风险批准等回电脑再处理。
参考来源: A9 · Codex Remote; OpenAI Codex Remote。

Settings 里找不到 Computer History

常见原因: 当前不是 macOS 桌面端,套餐或地区不支持,Memories 未启用,企业管理员没有开放,或功能仍在分批推送。它也不支持 API Key 和 Amazon Bedrock 登录。
怎么处理: 更新桌面端,确认是 Pro、Business 或 Enterprise 账号并检查 Memories。团队账号联系管理员。功能没有开放时不要安装声称能“强制开启”的第三方工具。
参考来源: A6 · Computer History; OpenAI Computer History。

MCP 工具不可用、tool not found,或服务一直连不上

常见原因: MCP server 没装好、配置路径不对、环境变量缺失、App/CLI 还没重新加载,或公司策略不允许这个 MCP。
怎么处理: 先用 Codex 设置里的 Integrations & MCP 或 CLI 的 MCP 状态命令确认它有没有被识别。再检查 server 命令、环境变量和授权。改完配置后重启 Codex 或新开线程。
参考来源: Codex MCP 和 Customization: MCP。

命令联网被拒绝,提示 sandbox 或 network blocked

常见原因: Codex 默认会限制命令的网络访问,这是为了避免工具随便连外网或被网页内容诱导执行危险操作。
怎么处理: 让 Codex 先说明“要访问哪个域名、为什么必须联网、能不能离线做”。确认合理后再批准这一次或配置更窄的域名规则。不要为了省事直接长期开最大权限。
参考来源: Agent approvals & security 和 Permissions。

长线程突然不记得前面内容,或旧线程/项目历史搜不到

常见原因: 长线程会触发上下文压缩;切模型、归档、侧边栏过滤、项目筛选也会让你感觉“内容不见了”。
怎么处理: 切模型或大改需求前,先让 Codex 总结当前状态。找不到线程时,切侧边栏过滤为 Chronological,再去 Settings 里看 archived chats / archived threads。搜索不到时换更短关键词。
参考来源: Codex App Troubleshooting 的 archived threads 与 sidebar filter; GitHub issues 中有 context/search 类反馈。

GitHub、PR 或 gh 功能用不了

常见原因: GitHub CLI 没装或没登录,本地仓库没 remote,当前账号没有仓库权限,或 Codex 运行在没有你 Chrome/GitHub 登录态的环境。
怎么处理: 先查 gh auth status 和 git remote -v。能在浏览器打开仓库不代表 CLI 已授权。团队仓库还要确认你有 push / PR 权限。
参考来源: Codex GitHub integration 和 OpenAI Codex GitHub issues。

网上搜到第三方 Codex 包或 App,不知道能不能装

常见原因: 热门工具常会出现名字相似的第三方包、假客户端或“增强版”工具,新手很容易把它们当官方软件。
怎么处理: 只从 OpenAI 官方下载页、官方文档或明确的 @openai/codex 包名安装。任何要求你粘贴 OpenAI 登录令牌、刷新令牌、完整 Cookie 的第三方工具都先停手。
参考来源: Codex CLI 官方入口; 第三方假包风险可在安全新闻和 npm/GitHub 页面交叉确认。

10 月更新后遇到的问题

/mcp login 没反应,或者不知道 name 填什么

先分入口: 这是 CLI 0.161.0 新增的会话命令,写在 Codex 输入框,不是普通 shell。name 是已配置的 MCP 服务名。
怎么处理: 先查 codex --version,在会话用 /mcp 找到服务。按实际名字登录,完成可信页面授权后先测试读取。没有服务先配置,不支持这种登录方式或被组织限制时按服务说明处理。
相关章节: MCP 登录步骤与官方来源

CLI 语音打开了,却收不到声音或耳机没声

常见原因: 麦克风权限没开,输入输出设备选错,或声卡输入通道不匹配。换耳机后原来的设备选择也可能不适用。
怎么处理: 在 0.161.0 的 /voice settings 检查麦克风、扬声器和输入通道,再做一句话测试。系统授权给实际运行的终端,不要用扩大文件或联网权限的方法修复收音。
相关章节: CLI 语音设置与来源

升级后找不到 Daybreak,旧设置也没生效

原因: 0.161.0 的 Daybreak 默认隐藏,需要显式开启 cli_daybreak;仅设置 daybreak=true 不够。
怎么处理: 普通用户保持默认即可。确实开展获授权安全工作的人,再检查启用标志、登录资格、提供商和模型支持。入口缺失不代表所有安全插件坏了,开关也不会自动授予访问资格。
相关章节: Daybreak 的适用条件与来源

网关能列模型、能聊天,但 Codex 请求一直失败

常见原因: 网关只支持 Chat Completions,或没有完整转发 Responses 的流式输出、工具调用和多轮状态。
怎么处理: 当前 Codex 要求兼容 Responses API,不能靠把 wire_api 改成 chat 解决。让管理员核对协议,用临时目录做只读工具测试和一次追问。不要先关沙盒,也不要公开密钥。
相关章节: 模型网关兼容说明与来源

断线后不知道消息有没有发出去,能直接再发吗?

先别重复: 界面没有结果不代表服务没有执行。新版改善队列恢复,仍不能替所有外部操作保证不重复。
怎么处理: 回原任务看最新历史与队列,去目标服务核对邮件、提交或部署状态。只重试确认未完成的步骤,不要同时开多条相同任务。仍异常就保留版本和报错做诊断。
相关章节: 断线恢复步骤和可复制提示词

手机小组件没出现,或者打开后找不到电脑上的任务

先查什么: 任务和额度小组件记录来自 iOS 1.2026.267,不能直接套到 Android 或桌面。还要确认账号、工作区、所选电脑和连接状态。
怎么处理: 先更新并打开手机 App,确认完整任务列表可用后再添加组件。空白时先恢复原电脑连接,核对任务归属,不要重建一份任务。仅凭组件状态不能证明结果已保存或发布。
相关章节: 手机小组件和接力步骤

已经登录,为什么找不到 auth.json?

原因: 凭据可能使用系统钥匙串或 keyring 存储,只有文件存储模式才一定要找对应文件。
怎么处理: 以实际登录状态为准。没有文件不等于登录失败,不要为此删除整个 .codex 目录,也不要让别人发一份凭据文件给你。分享诊断只保留脱敏错误,不贴登录令牌。
参考来源: 官方配置与状态存储说明

9 月更新后遇到的问题

已经升级了,为什么模型列表没有 GPT-6.1 Sol?

先看哪里: 确认是在 Work / Codex,而不是普通 Chat;再核对账号套餐、工作区和客户端版本。
怎么处理: Free / Go 不在首发范围,Enterprise / Edu 默认需要管理员开启。符合范围也可能仍在分批开放,先用当前可选模型。不要为了找入口购买来路不明的账号或修改权限文件。
参考来源: 官方模型范围; 新模型上手

找不到 Ultrafast,或者开了加速后额度消耗很快

常见原因: Ultra 是推理与多智能体档位,Ultrafast 是速度档位,有独立的模型、套餐和管理员限制。
怎么处理: 先切回 Standard 核对用量,查自己的套餐是否符合要求。更快输出不代表整项工作同比加速,用量倍率也不是速度倍率。GPT-6 Luna 没有 Ultra,GPT-6.1 Sol 当前也没有 Ultrafast。
参考来源: 官方 Speed; 档位对照

Work 已同步到手机,为什么电脑一睡眠任务就卡住?

常见原因: 聊天可以跨设备继续,但某一步仍依赖本地文件、程序或登录状态。云端协调不等于所有操作都在云端运行。
怎么处理: 让任务说明卡在哪台电脑、哪个步骤,恢复那台电脑联网并核对连接。确认之前操作有没有成功再重试,尤其不要重复发送、付款或部署。想脱离本地电脑运行,要另外准备适合的云端环境。
参考来源: 本地访问条件; Remote 与同步的区别

安装插件后没有面板,也不能监控新消息?

常见原因: 工具调用、插件界面和事件订阅是不同能力,要服务分别接入。旧插件不会自动支持全部新功能。
怎么处理: 先查该插件实际提供什么和当前账号范围。输入框提及限桌面端,网页扩展对 Free / Go 尚待开放。事件要服务支持 MCP 2.0 和 webhook;确认订阅真的建立后再依赖它,不能把“好的,我会关注”当成成功凭证。
相关章节: 插件扩展与事件订阅和官方来源

照旧教程打开实验性上下文管理,为什么没效果?

原因: 9 月 30 日的官方配置参考已将这个功能标为当前不可用,不是再加一个开关就能解决。
怎么处理: 停止照抄旧开启示例。先备份配置,只检查这一项,不要清空其他模型、连接和权限设置。长任务可先用进度文档记录已完成事项与下一步。
相关章节: 更正说明及官方配置来源

Windows 运行后台命令时,总有黑色窗口一闪而过

先做什么: 记录触发动作和 codex --version。0.159.2 的修复针对这类后台进程和沙盒命令闪窗。
怎么处理: 用原安装渠道升级 CLI,重新打开终端验证实际版本;只升级 App 不一定升级独立 CLI。仍有问题再保留日志排查,不要禁用沙盒或系统安全软件来掩盖现象。
参考来源: 官方 0.159.2 修复; 升级说明

升级后 plugin-creator 或自动追问建议不见了

原因: CLI 0.159 已移除随包提供的 plugin-creator 技能、自动追问建议及对应设置,不代表插件市场整体失效。
怎么处理: 继续用现有已安装插件;开发插件时查当前官方流程。无需为了找回旧入口反复重装或清掉所有配置。
相关章节: CLI 新旧入口对照与来源

CLI 输入 /voice 没反应,或者没有语音选项

先分版本: 0.155 时需要实验开关,0.156 起已默认开启语音支持,旧教程步骤不应继续套用。
怎么处理: 运行 codex --version 确认实际版本,检查终端麦克风权限。新版可按 F8 切换,用 /voice settings 选声音;F8 被系统占用时先查功能键设置。暂不可用就继续文字,不要降低沙盒权限。App Voice 和 CLI 是不同入口。
相关章节: CLI 语音操作与版本来源

升级后服务商提示不支持 reasoning summary,请求被拒绝

常见原因: 部分服务商不接受推理摘要选项;0.155.1 调整了新建本地终端会话的默认值。
怎么处理: 先升级到 0.155.1 或更新稳定版,再开新会话测试。手动配置的摘要设置仍会保留,必要时核对该项和服务商支持范围。摘要开关不等于推理强度,不要顺手改模型、清空全部配置或更换账号。
参考来源: 官方 9 月 18 日 0.155.1 修复记录

悬浮 Quick Chat 打开了,却不知道我在改哪个项目

常见原因: 悬浮控件新建的聊天在项目之外,不会自动变成当前仓库里的任务。
怎么处理: 回主 App,选择正确项目并从那里继续或新建任务。临时问答可用 Quick Chat,但不要因为找不到文件就授权整个磁盘。入口不出现时检查客户端版本、Settings > Pets 和工作区策略。
参考来源: 官方悬浮快捷聊天说明

使用与协作类

Codex 一次改了太多文件

常见原因: 你的提示词目标太大,没有限制范围,也没有要求先计划。
怎么处理: 马上说:“请停止扩展,用三句话总结刚才改了哪些文件。接下来只保留最必要改动。”以后大任务先用“请先给计划,我确认后再改”。
相关章节: 第 04 章 · 口语化编程内功

页面打开是一片白

常见原因: JavaScript 报错、资源路径错、HTML 标签没闭合,或你打开方式不对。
怎么处理: 打开浏览器控制台看红色报错,复制给 Codex。提示词写:“我期待看到页面,实际是一片白,控制台报错是 [...],请先定位再修。”
相关章节: 第 07 章 · 先描述现象

样式没生效,刷新还是旧的

常见原因: 浏览器缓存、改错文件、CSS 路径不对,或本地服务器还指向旧目录。
怎么处理: 先强制刷新。再让 Codex 检查 HTML 里引用的 CSS 路径和实际文件路径是否一致。确认本地服务器启动目录就是项目根目录。
相关章节: 第 05 章 · 常见踩坑

Codex 一直反问细节,不动手

常见原因: 任务边界太模糊,它不知道应该保守还是发挥。
怎么处理: 给它一个默认判断权:“你可以做合理假设,先做最小版本,不确定处用 TODO 标注,完成后告诉我假设了什么。”
相关章节: 第 04 章 · 识别反问

本地预览服务器启动了,但浏览器访问不到

常见原因: 端口写错、服务器已退出、另一个程序占用端口,或你访问了 localhost 以外的地址。
怎么处理: 看终端输出的端口号,通常访问 http://localhost:8000 或 http://127.0.0.1:8000。如果端口占用,换一个端口再启动。
相关章节: 第 05 章 · 本地预览

部署类

GitHub Desktop 看不到我的仓库

常见原因: 项目文件夹还不是 Git 仓库,或你打开的是上一级/下一级目录。
怎么处理: 确认项目根目录里有 .git。没有的话用 GitHub Desktop 的 Add Existing Repository 或 Create Repository 流程。目录选错就重新添加正确项目根目录。
相关章节: 第 08 章 · 部署踩坑

Publish 报错 remote already exists

常见原因: 这个本地仓库已经连过一个 GitHub 远程地址。
怎么处理: 先别乱删。让 Codex 跑只读检查:当前 remote 指向哪里、GitHub 上仓库是否存在、你想保留哪个。确认后再改 remote。
相关章节: 第 08 章 · GitHub 问题

Vercel Import 时看不到仓库

常见原因: GitHub 授权没给 Vercel、仓库是私有且未授权、账号登错。
怎么处理: 检查 Vercel 连接的 GitHub 账号,重新授权目标仓库。团队仓库还要确认你有权限。
相关章节: 第 08 章 · Vercel Import

Vercel 部署完是 404

常见原因: 入口文件不在 Vercel 认为的根目录,或项目实际需要构建但配置为空。
怎么处理: 纯静态站确认根目录有 index.html。如果项目在子目录,Import 时要设置 Root Directory。
相关章节: 第 08 章 · 404

Vercel 部署失败 Build error

常见原因: 构建命令不对、依赖没装、项目类型识别错、代码本身报错。
怎么处理: 复制 Vercel 的红色错误日志给 Codex,让它先总结“失败在哪一步”。纯 HTML 项目通常不需要 Build Command。
相关章节: 第 08 章 · Build error

Push 之后 Vercel 没自动重新部署

常见原因: Push 到了错误分支、Vercel 没连这个仓库、GitHub webhook 没触发。
怎么处理: 确认 GitHub 上能看到最新 commit。再去 Vercel 项目 Deployments 看有没有新记录。没有就检查 Production Branch 和 Git 连接。
相关章节: 第 08 章 · 自动部署

域名与 DNS 类

填完 DNS 后访问 Bad Gateway

常见原因: DNS 已经指到了平台,但平台项目还没正确绑定域名,或代理/缓存还没更新。
怎么处理: 先在 Vercel 域名设置里看状态。不要反复乱改 DNS。记录你改动的时间,等一段时间再查。
相关章节: 第 09 章 · DNS 踩坑

Vercel 一直 Pending,不变 Valid

常见原因: DNS 记录填错、记录冲突、DNS 传播还没完成。
怎么处理: 逐条核对 Vercel 要求的 A/CNAME 记录。删除冲突的旧记录。刚改完 DNS 等待 10 分钟到数小时很正常。
相关章节: 第 09 章 · Pending

www 能打开,裸域打不开

常见原因: www.example.com 和 example.com 是两个不同主机名,需要分别配置。
怎么处理: 在 Vercel 同时添加裸域和 www 域名。DNS 里按平台要求分别配置 A 记录和 CNAME。
相关章节: 第 09 章 · www 与裸域

HTTPS 一直没启用

常见原因: 域名验证还没完成,证书还在签发,或 DNS 没正确指向平台。
怎么处理: 先确认域名状态是 Valid。再等待证书签发。不要为了“立刻好”来回切换 DNS,那只会让等待重新开始。
相关章节: 第 09 章 · HTTPS

手滑买到了不适合自己的域名后缀

常见原因: 没注意后缀差异,或只看价格没看使用限制。
怎么处理: 先确认是否能退款。正式项目优先选常见后缀,比如 .com、.io、.app 等。面向中国大陆服务时再单独考虑合规和备案。
相关章节: 第 09 章 · 买域名

Codex 协作类

Codex 看起来在绕圈子

常见原因: 它已经尝试多轮但没有新信息,还在重复猜测。
怎么处理: 打断它,让它列“已尝试方法 / 失败原因 / 缺少信息 / 下一步最小实验”。必要时开启新会话,把当前状态摘要贴进去。
相关章节: 第 07 章 · 打破绕圈

它说修好了,但我不知道怎么验证

常见原因: 你没有在任务里要求“完成后告诉我怎么验收”。
怎么处理: 补一句:“请给我一份验收清单,包括浏览器里点哪里、终端跑什么命令、看到什么算成功。”
相关章节: 附录 A · 解释自己刚做了什么

越改越乱,想回到之前

常见原因: 没有及时 commit,或连续让 Codex 改了太多轮。
怎么处理: 先别继续改。让 Codex 查看 Git diff,总结当前改动。如果有 commit,用 Git 回退;没有 commit,让它按 diff 逐块撤回。
相关章节: 第 07 章 · Git 回退

资料来源与维护口径

本页新增的 Codex App / CLI 高频问题,主要参考 OpenAI 官方 Codex 文档、OpenAI Status,以及 OpenAI Codex GitHub issue 列表里反复出现的公开反馈。教程会把官方事实和用户反馈分开处理:官方文档能确认的写成明确步骤,GitHub issue 里看到的现象只整理成排查线索。

排错时最有用的一句话 “请先不要继续修改,把现象、最可能原因、你已经尝试过的操作、下一步最小验证列成表。”它能把慌乱变成清单。