codex cli 是集成于终端的开发代理，自动感知项目结构并支持交互式编码、自动修复、命令执行与错误分析。需 node.js ≥18，通过浏览器或 api key 认证，启动后进入项目根目录运行 codex 即可绑定上下文。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在终端里直接让 AI 读项目、改代码、跑测试、写文档，而不是切到浏览器或桌面 App 去问问题——这才是 Codex CLI 真正该用的方式。它不是聊天框的替代品，而是你当前工作目录里的开发代理，一启动就自动感知 src/、tests/、package.json 和 Git 状态。
安装与环境准备
先确认 Node.js 版本不低于 18：【codex 要求 node -v 输出 ≥ v18.0.0】。低于这个版本会静默失败，不报错但后续所有命令都卡在 loading 状态。
运行 npm install -g @openai/codex 完成安装。macOS 用户若用 Homebrew，可改用 brew install --cask codex，它会自动处理 shell 初始化路径，避免手动配置 PATH。
国内用户如果 npm 卡在 download stage，不要反复重试，直接加镜像源：npm install -g @openai/codex --registry=https://registry.npmmirror.com。
登录认证：两种方式必须选对场景
方法一：浏览器登录（推荐本地开发）
在项目根目录下执行 codex，它会自动打开默认浏览器跳转至 ChatGPT 授权页，完成登录后终端显示 “✅ Authenticated as your@email.com”。这一步成功后，auth.json 不会落地到磁盘，凭证由 OpenAI OAuth 流程托管，更安全。
方法二：API Key 手动注入（适合 CI/服务器）
执行 echo '{"OPENAI_API_KEY":"sk-abc123"}' > ~/.codex/auth.json。注意：文件路径必须是 ~/.codex/auth.json，少一个点或换到其他位置，codex 启动时完全无视。
验证是否生效：运行 codex --version && codex "hi"。如果返回版本号且第二条命令有流式响应，说明认证链路已通。
进入交互模式并绑定项目上下文
第一步：cd 进入你的项目根目录，确保里面有 git init 或 package.json / pyproject.toml 等标识文件。
第二步：运行 codex 启动交互式会话。你会看到提示符从 $ 变成 >，说明已进入 Codex 内部环境。
第三步：输入 /context 查看当前上下文摘要。Codex 会自动扫描 .gitignore、读取顶层目录结构、识别语言类型，并告诉你“已加载 42 个 TypeScript 文件，忽略 node_modules 和 dist”。【没看到这行输出，说明它根本没读进项目】，此时要检查是否在正确目录、是否有权限读取子目录、.gitignore 是否误删了关键路径。
第四步：现在才开始提需求，比如 > 给 login.ts 加上 JWT 过期自动刷新逻辑。它会基于刚载入的上下文生成符合你项目风格的补丁，而不是通用模板。
执行命令式任务：绕过交互，直出结果
在系统终端（非 Codex 交互环境）中运行：
codex -a "修复 src/utils/date.ts 中 formatDuration 的负数输入崩溃问题"
加 -a 参数表示全自动模式：Codex 会自己读文件 → 修改 → 写回 → 显示 diff。不加则只输出建议代码，不落盘。
如果你只想让它执行 shell 命令而不碰代码，用 codex exec："npm run build && ls -lh dist/"。它会真实执行并把 stdout/stderr 原样返回，适合集成进 Makefile 或 pre-commit 钩子。
用自然语言调试报错信息
把终端里刚弹出的错误粘贴进去，开头加上“分析这个错误”四个字：
> 分析这个错误
TypeError: Cannot read property 'map' of undefined at UserList.render (src/components/UserList.tsx:12:30)
Codex 会定位到 src/components/UserList.tsx 第 12 行，指出 this.props.users 是 undefined，并给出三种修复方向：加 defaultProps、加空值判断、或追溯父组件传参逻辑。它不会瞎猜，而是严格基于你当前目录下真实存在的文件内容推理。
这一步操作起来很简单，直接把报错文本拖进终端回车就行，不用截图、不用重打、不用删堆栈。
