Codex CLI 国内使用教程：安装、配置与常用命令

先确认它适合什么场景

Codex CLI 适合想把 AI 接进现有开发流程的人：在终端里让它解释代码、定位问题、改文件、补测试，再由你 review diff 和跑测试。它不适合完全不想审查改动、也不做版本控制的“全自动”用法。

• Node.js 20 或更高版本，以及可用的 npm
• Git 仓库（建议先在一个干净分支上试用）
• 一个可用的模型入口：官方 API Key，或兼容接口的第三方中转
• 基本的终端操作能力，知道当前目录、环境变量和 git diff

安装与验证

Codex CLI 通过 npm 分发。先确认 Node 版本，再全局安装，最后用 --version 和 --help 验证是否装好。

node --version
npm install -g @openai/codex
codex --version
codex --help

如果 npm 全局安装报权限错误，优先检查 npm 的全局目录配置，不要长期用 sudo 安装全局包。安装完成后，建议先在一个测试仓库里运行，不要直接打开生产项目。

登录与密钥：两种常见方式

第一种是交互式登录：在终端执行 codex login，按提示在浏览器完成授权。第二种是使用 API Key：把密钥放进环境变量，再启动 Codex CLI。两种方式选一种即可。

export OPENAI_API_KEY="sk-..."
codex

如果你使用的是第三方中转，Key 和中转地址都来自该站点，不要混用官方 Key 和中转 base URL。配置完成后先发一个只读问题，确认网络和鉴权都正常，再让它改代码。

配置第三方中转（可选）

部分第三方入口兼容 OpenAI 接口，需要在 Codex CLI 的配置文件里声明 provider、base URL 和读取 Key 的环境变量名。下面是一个通用示意，字段名请以你所用版本和站点文档为准。

model_provider = "my-gateway"

[model_providers.my-gateway]
name = "My Gateway"
base_url = "https://your-gateway.example.com/v1"
env_key = "MY_GATEWAY_API_KEY"

配置完成后重新打开终端，让环境变量生效。先用“解释项目结构”这类只读任务验证连通性；如果返回 401 或模型不存在，优先检查 base URL 是否带 /v1、Key 是否属于该站点、模型名是否在站点支持列表里。

• 查看 AI 编程中转入口
• OpenAI API Key 安全使用指南

在项目里怎么用才稳

建议把使用过程拆成“只读理解 → 给计划 → 小步修改 → 自己验证”四步。第一次不要直接让它大范围重构，先让它解释入口、依赖和构建方式，确认它真的读懂了项目。

1. 01

   确认工作区干净

   先 git status，确保没有未提交的改动；在独立分支上试用，出问题可以直接丢弃。

2. 02

   先做只读任务

   让它解释目录结构、定位某个函数的调用链，或者分析报错；这一阶段不要批准写文件。

3. 03

   让它先给计划

   要求先列出要改哪些文件、为什么改、怎么验证；计划合理再批准执行。

4. 04

   小步修改并验证

   每次只改一个主题，自己看 git diff，运行测试和类型检查；不要把所有改动一次性合并。

5. 05

   提交前做安全检查

   确认没有密钥、客户数据、调试日志被带进提交；必要时让它在提交前做一次 review。

cd your-project
git status
codex "先不要改文件，解释这个项目的入口、构建方式和主要目录"
codex "为 src/parser.ts 的 parse() 补边界测试，先给计划，确认后再改"

安全边界与权限

• 不要把 API Key、密码、Session JSON、客户数据粘贴进对话或让它写进文件。
• 让它执行命令前，先看清楚命令会改什么、删什么、请求哪个地址。
• 只在需要的项目目录里启动，不要在主目录或包含多个客户项目的根目录启动。
• 改动前先提交或开分支；不要把“AI 改坏了”与“我本地本来就有改动”混在一起。
• 涉及生产环境、数据库迁移、支付配置的改动，必须人工复核，不能只依赖模型判断。

常见报错怎么排查