device code登录是解决codex cli在wsl等跨系统环境登录失败的首选方案，它绕过localhost回调依赖，通过手动输入设备码完成授权，成功率接近100%。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
刚装好Codex CLI，执行codex login却卡在浏览器回调页、刷新token报错“refresh token was already used”、写个简单函数生成的代码根本跑不通——这些不是你操作错了，而是踩中了新手必经的三大认知断层。
别急着登录：先确认认证路径是否可靠
打开终端，运行codex login后浏览器弹出空白页或提示“missing_required_parameter”，本质不是账号问题，而是当前环境无法完成OAuth 2.0回调链路。Windows本地浏览器常因代理、证书拦截或企业防火墙阻断重定向；Linux工作机若用SSH远程连接，根本无法唤起本地浏览器。
此时【不要反复点击重试或强制关闭页面】，那只会让auth.json里残留半截失效凭证。
立刻切换为device code登录：在终端执行codex login --device-code，复制终端输出的code和URL，在任意能联网的设备上打开该链接，粘贴code授权。整个过程不依赖本地浏览器跳转，成功率接近100%。
这一步操作起来很简单，直接把code粘过去就行。但必须在首次登录或token异常时优先启用，否则后续所有文件操作都会因认证失败而静默中断。
项目文件夹管理：一个文件夹只做一件事
新建项目前，先在文件系统中创建独立目录，例如~/projects/user-api，而非直接扔进~/Downloads或桌面。Codex会扫描该目录下所有可读文件作为上下文源，混放PDF、日志、临时脚本会导致AI误判项目结构。
方法一：用CLI初始化专属空间
进入空目录后执行codex init，自动创建.codex/config.toml和AGENTS.md。后者相当于给AI写的README，明确告知“本项目用Express + PostgreSQL，API端口3001，用户表字段含id/name/email”。
方法二：手动建立分层结构user-api/→src/（代码）→docs/（接口文档）→test/（测试用例）。Codex在处理src/controllers/user.js时，会自动关联docs/api-spec.yaml里的字段定义，避免生成与实际接口不匹配的返回结构。
【切勿将多个项目共用同一文件夹】，比如把前端Vue和后端Node放在同一个my-app目录下。Codex会混淆技术栈，可能用Vue语法生成Node路由代码。
写提示词前先激活Plan Mode
第一步：按下快捷键Ctrl+P（macOS为Cmd+P）开启Plan Mode。
第二步：输入需求，例如“给用户注册接口添加邮箱格式校验和重复检测”。
第三步：等待Codex仅输出执行步骤，不修改任何文件，例如：
① 定位src/routes/auth.js中的POST /register路由
② 在请求体解析后插入Joi校验中间件
③ 查询数据库检查email是否已存在
④ 返回409状态码及错误消息
第四步：逐条核对计划是否符合当前代码结构。若发现它打算修改不存在的middleware/joi.js，说明上下文没加载对，需补全该文件路径再重试。
这一步不能跳过。没有Plan Mode约束的Codex可能直接重写整份路由文件，删掉你上周加的JWT续期逻辑。
编辑中文文件前必须声明编码
Codex默认以UTF-8无BOM格式输出内容，但Windows记事本、Excel导出的CSV、老旧Java项目默认用GBK编码。若直接让Codex修改readme.txt，生成的中文会变成“？？？”。
解决方法只有一条：在指令中显式声明编码要求。例如：
“请在readme.txt末尾添加一行中文说明‘版本更新至v2.1’，保持原文件GBK编码不变，输出内容必须兼容GBK字符集。”
如果Codex返回乱码，立刻用VS Code以GBK重新打开该文件，手动复制粘贴正确文字——不要尝试让Codex“修复乱码”，它无法逆向推断原始编码。
线程（Thread）不是聊天记录，是事务隔离单元
每次启动新任务，必须在Codex界面左侧点击“+ New Thread”，而不是接着上一条对话往下说。比如刚完成数据库迁移，马上要写单元测试，这两个动作必须分属不同Thread。
原因在于：Codex会将同一线程内的全部消息压缩为上下文送入模型。若混杂“改SQL”和“写测试”，模型会错误地认为“测试代码需要包含ALTER TABLE语句”，导致生成非法的测试用例。
一个Thread对应一个Git分支的生命周期。上线前合并PR时，只需归档该Thread，所有操作路径、修改记录、AI决策依据全部保留可追溯。
