返回首页
上一课下一课 →
module1
20 分钟

安装与配置

学习进度

当前模块0/6 课
总进度0/36 课
学习时长0 分钟

学习目标

  • 通过 npm 全局安装 Codex CLI
  • 配置 OpenAI API 密钥完成认证
  • 运行第一个 `codex` 命令
  • 设置 codex.yaml 项目配置文件

002 安装与配置

5 分钟完成 Codex CLI 的安装与配置，开启终端 AI 编程之旅。

学习目标

完成本课程后，你将能够：

一、环境准备

系统要求

系统版本要求备注
macOS12.0+ (Monterey)推荐使用 Homebrew 管理 Node.js
LinuxUbuntu 20.04+ / Debian 11+推荐使用 nvm 管理 Node.js
Windows10/11 + WSL2必须在 WSL2 中运行，不支持原生 cmd/PowerShell

必需依赖

  • **Node.js** 18.0 或更高版本（推荐 20 LTS）
  • **npm** 9.0+（随 Node.js 一同安装）
  • **Git** 2.30+（用于代码版本管理）
  • **OpenAI API 密钥**（需在 platform.openai.com 获取）

检查环境

node -v    # 应输出 v18.x.x 或更高
npm -v     # 应输出 9.x.x 或更高
git --version  # 应输出 git version 2.x.x

如果未安装 Node.js，请前往 [nodejs.org](https://nodejs.org) 下载 LTS 版本。

二、安装 Codex CLI

第一步：全局安装

npm install -g @openai/codex

安装过程约 1-2 分钟。npm 会将 `codex` 命令注册到系统 PATH 中。

第二步：验证安装

codex --version

如果显示版本号（如 `v1.2.3`），说明安装成功。

**💡 提示：** 如果提示 `command not found`，请检查 npm 全局安装目录是否在 PATH 中。运行 `npm root -g` 查看全局目录路径。

第三步：配置 API 密钥

Codex 需要 OpenAI API 密钥才能工作。获取方式：

  1. 登录 [platform.openai.com](https://platform.openai.com)
  1. 进入 API Keys 页面，创建新密钥
  1. 将密钥设置为环境变量：
# macOS / Linux（添加到 ~/.zshrc 或 ~/.bashrc）
export OPENAI_API_KEY="sk-your-api-key-here"

# Windows WSL2（同上）
export OPENAI_API_KEY="sk-your-api-key-here"

配置完成后重新加载终端：

source ~/.zshrc   # 或 source ~/.bashrc

三、第一次启动

进入项目目录

cd ~/my-project
codex

首次启动时 Codex 会验证 API 密钥，确认连接正常后进入交互界面。

快速验证

在 Codex 提示符下输入：

帮我看看这个项目是什么技术栈

Codex 会读取项目文件，分析 package.json、目录结构等，给出技术栈总结。这表明安装配置完全正常。

四、codex.yaml 基础配置

在每个项目根目录创建 `codex.yaml`，Codex 会自动读取。这是 Codex 的核心配置文件，类似于 Cursor 的 `.cursorrules`。

最小配置示例

# codex.yaml — 项目级 Codex 配置
model: o4-mini              # 默认模型：GPT-4o 或 o4-mini
language: zh-CN             # 交互语言偏好

project:
  name: my-app
  type: web                 # web / cli / library / mobile
  framework: next.js        # 主框架
  language: typescript      # 编程语言

style:
  indent: 2                 # 缩进空格数
  quotes: single            # single / double
  semi: true                # 是否使用分号

模型选择策略

# 场景化模型配置示例
model: o4-mini              # 日常任务默认用轻量模型

# 在复杂任务中切换到 GPT-4o：
# 方式一：修改 codex.yaml，将 model 改为 GPT-4o
# 方式二：命令行临时指定
# codex --model GPT-4o
场景推荐模型原因
写单元测试o4-mini速度快，模式固定
修改变量名o4-mini简单机械操作
新功能开发GPT-4o需要深层理解
大规模重构GPT-4o跨文件复杂操作
代码审查GPT-4o需要全面分析

五、安装问题排查

常见问题与解决

问题可能原因解决方案
`codex: command not found`npm 全局目录不在 PATH`npm root -g` 查看路径，添加到 PATH
`401 Unauthorized`API 密钥无效或过期重新生成密钥，检查环境变量
`429 Too Many Requests`API 速率限制等待片刻，或升级 API 套餐
安装失败（权限错误）npm 全局目录需要 sudo使用 nvm 管理 Node.js，避免 sudo

卸载与重装

# 卸载
npm uninstall -g @openai/codex

# 清理缓存
rm -rf ~/.codex

# 重新安装
npm install -g @openai/codex

六、本课总结

**核心要点：**

  • Codex CLI 通过 npm 全局安装，一条命令搞定
  • 必须配置 `OPENAI_API_KEY` 环境变量才能使用
  • `codex.yaml` 是项目级配置文件，控制模型、风格等全局行为
  • GPT-4o 处理复杂任务，o4-mini 处理日常高频任务
  • 推荐使用 nvm 管理 Node.js 版本，避免权限问题

**下一步：** 下一课将学习 Codex 的核心指令和终端工作流，掌握 `/code`、`/review`、`/test` 等关键命令。

上一课
下一课