附录 D

常见踩坑全集索引

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

排错顺序 先看“现象”是不是对得上,再看“最常见原因”,最后照“怎么处理”做。不要一急就重装全家桶,很多问题只是路径、缓存、权限或 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 版本暂时拿不到你选的模型;也可能是配置里手动写了一个过新的模型名。
怎么处理: 先切回默认模型或上一个可用模型,再更新 Codex App / CLI。CLI 里用 codex --version 看版本;桌面端可以在设置里更新。不要一上来改一堆配置,先确认是不是“只有某个模型不行”。
参考来源: OpenAI Codex GitHub issues 中有模型 404 与连接类反馈;版本差异可参考 Codex App Troubleshooting。

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

常见原因: 登错账号、会话过期、公司/团队管理员没开放 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 桌面端能力,需要前台窗口和系统权限;有些 App 只能给可见截图,拿不到完整离屏文本。
怎么处理: 确认是在 macOS Codex App 里用,按两个 Command 键或你设置的热键。系统设置里检查 Screen & System Audio Recording 与 Accessibility。仍不行时,先用普通截图作为附件。
参考来源: Appshots 的权限与排错说明。

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 页面交叉确认。

使用与协作类

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 里看到的现象只整理成排查线索。

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