新手常见问题与排错入口

新手使用 Codex CLI 的大多数问题并非工具缺陷，而是任务表达、边界控制、验证习惯与配置姿态不当造成的。本节汇总高频误区、安全默认做法与排错顺序，帮你在卡住时快速恢复正轨。

一、高频误区与正确做法

常见误区	后果	正确做法
需求一句话、不给边界	范围膨胀、夹带修改、难以验收	用背景/目标/约束/验收结构表达，先方案后实现
一上来就让大改全项目	误改多、难回退、测试大面积失败	拆成小而独立、可验证的任务逐步推进
陌生项目用宽松自动审批	误装依赖、越权写入、执行未预期命令	从保守审批与只读/工作区沙箱起步
不看 diff 直接接受全部改动	夹带重构、弱化测试、埋下隐患	固定走 status → diff → 测试 → 决策
不跑测试只看代码结论	把"看起来对"当完成	以可运行检查结果作为交付证据
项目不在版本控制下操作	改动无法回退，错误难以撤销	先确保 Git 基线干净、可还原
上下文过长仍在同一会话硬撑	早期约束被稀释、重复探索、质量下降	沉淀关键约定到项目指令，必要时重开聚焦会话
报错后盲目换方向重试	错误未定位、问题反复出现	先读首条报错、最小复现、定位根因再修

二、卡住时的排错顺序

1. 收窄现象：明确在哪个任务、哪一步、什么报错或异常行为，去掉无关描述。
2. 先看官方入口：用 codex --help 核对命令形态；对照当前官方文档确认用法与版本行为。
3. 给最小复现：用最小项目或最小命令复现问题，把完整错误输出回贴给代理定位。
4. 检查环境前提：终端工作目录是否正确、依赖是否安装、登录授权是否有效、项目测试命令是否可运行。
5. 回退到干净基线：思路混乱或改动偏离时，用版本控制回到可用状态，重新以小任务起步，比在脏状态里修补更高效。

三、新手安全默认配置建议

• 项目侧：始终在 Git 仓库、工作区干净时开始；优先小步、可回退的改动。
• 策略侧：起步用保守审批档；只读探索配只读沙箱；常规实现再切到工作区可写、常规审批档。
• 动作侧：安装依赖、联网、删除、提交推送等动作逐项确认；提交由人工完成。
• 验证侧：每个小改动后运行可用检查；把关键项目约定写入项目指令，减少重复口头约束。

四、FAQ

排错问题	处理建议
启动后读不到项目	确认终端当前目录即项目根目录，重新在该目录启动会话。
登录/授权失效	按官方登录流程重新完成授权；确认账号具备相应使用权限（额度与权限以官方说明为准）。
代理反复失败同一步骤	停止让其反复尝试，贴出完整报错、要求先诊断根因；必要时缩小任务范围。
产出与预期差距很大	多为任务不够结构化或缺少约束；回到任务五要素，补边界与验收后重新下达。
版本功能与教程描述不一致	以 codex --help 和当前官方文档为准；命令与界面随版本演进，方法学保持有效。

五、动手练习

• 练习：对照"高频误区表"给自己最近一次会话打分，选出两项最易犯的问题，制定对应的固定检查动作（如"先 status 再接受"），在下个任务中强制执行。