Codex CLI 安装与认证 —— 从零开始搭建开发环境

简介

在之前的一系列文章中，我们已经深入了解了 OpenAI Codex CLI 的核心概念、架构设计和能力边界。从本篇开始，我们进入实战操作阶段。无论你对 Codex CLI 的理论有多熟悉，如果没有正确地安装和认证，一切都是纸上谈兵。

本文将带你从零开始，一步步完成 Codex CLI 的安装、配置和认证。无论你是 npm 生态的老手，还是第一次接触命令行 AI 工具，按照本文的步骤都能顺利跑通。

一、前置环境要求

在安装 Codex CLI 之前，请确保你的开发环境满足以下基本要求：

环境项	最低版本要求	推荐版本	检查命令
Node.js	18.0.0	20 LTS	`node --version`
npm	9.0.0	10.x	`npm --version`
Git	2.30.0	2.40+	`git --version`
macOS / Linux / WSL2	-	-	`uname -a`

1.1 检查 Node.js 版本

bash

node --version
# 期望输出: v18.0.0 或更高
# 例如: v20.11.0

如果你的 Node.js 版本过低，推荐使用 nvm（Node Version Manager）来安装和切换版本：

bash

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc  # 或 source ~/.zshrc

# 安装并使用 Node.js 20 LTS
nvm install 20
nvm use 20

1.2 检查 npm 版本

bash

npm --version
# 期望输出: 9.0.0 或更高
# 例如: 10.5.0

如果 npm 版本过低，可以通过以下方式升级：

bash

npm install -g npm@latest

1.3 检查 Git 是否安装

bash

git --version
# 期望输出: git version 2.x.x

Codex CLI 的正常运行依赖 Git 环境，我们会在后面的文章详细讨论为什么。如果你尚未安装 Git：

bash

# macOS (使用 Homebrew)
brew install git

# Ubuntu / Debian
sudo apt update && sudo apt install -y git

# CentOS / RHEL
sudo yum install -y git

二、通过 npm 安装 Codex CLI

2.1 全局安装（推荐）

Codex CLI 发布在 npm 上，包名为 @openai/codex。最便捷的安装方式是全局安装：

bash

npm install -g @openai/codex

安装成功后，验证是否可用：

bash

codex --version
# 期望输出类似: 0.1.x 或更高版本

2.2 为什么全局安装？

你可能会有疑问：为什么不推荐项目级安装？原因有几点：

工具属性：Codex CLI 本质上是一个开发工具，类似于 eslint、prettier，应该在系统级别可用
版本一致性：全局安装确保你在任何项目目录下都能使用相同版本
避免依赖冲突：项目级安装可能与项目自身的依赖产生版本冲突

当然，在某些受限制的环境（如 CI/CD 流水线）中，你可能需要项目级安装：

bash

# 项目级安装
npm install @openai/codex
npx codex --version

2.3 常见安装问题排查

问题 1：权限错误 `EACCES`

text

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

解决方案（三选一）：

bash

# 方案 A：使用 sudo（不推荐，但最简单）
sudo npm install -g @openai/codex

# 方案 B：配置 npm 全局目录到用户目录（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex

# 方案 C：使用 nvm 管理 Node.js（最佳实践）
# nvm 会自动将全局包安装到用户目录，无需 sudo

问题 2：安装后找不到 `codex` 命令

bash

bash: codex: command not found

这通常是因为 npm 全局包路径不在你的 PATH 中：

bash

# 查看 npm 全局 bin 目录
npm config get prefix
# 例如输出: /usr/local 或 /home/user/.npm-global

# 确认 codex 是否已安装在该目录下
ls $(npm config get prefix)/bin/codex

# 将该路径添加到 PATH
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

问题 3：安装超时或网络错误

text

npm ERR! network request to https://registry.npmjs.org/@openai/codex failed

解决方案：

bash

# 切换到国内镜像源（如淘宝镜像）
npm config set registry https://registry.npmmirror.com

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

三、认证方式一：OAuth 登录（推荐）

Codex CLI 支持两种认证方式。第一种是 OpenAI 账号 OAuth 登录，这也是官方推荐的方式。

3.1 登录流程

在终端中执行以下命令：

bash

codex login

执行后，终端会输出类似如下信息：

text

🔐 OpenAI Codex CLI Authentication

Opening browser to complete authentication...

If the browser doesn't open automatically, visit:
https://platform.openai.com/auth?client_id=codex-cli&...

Waiting for authentication...

3.2 浏览器端操作

浏览器会自动打开 OpenAI 的授权页面。你需要：

登录 OpenAI 账号（如果没有，需要先注册）
授权 Codex CLI 访问你的账户：阅读权限范围后点击 "Authorize"
自动回调：授权成功后，浏览器会显示 "Authentication successful"，终端自动继续

3.3 验证登录状态

bash

codex whoami
# 输出示例:
# Authenticated as: your-email@example.com
# Plan: Plus
# Token usage available: Yes

3.4 查看和管理凭据

OAuth 凭据存储在本地配置文件中：

bash

# macOS
cat ~/Library/Application\ Support/codex-cli/credentials.json

# Linux
cat ~/.config/codex-cli/credentials.json

⚠️ 安全提示：凭据文件包含敏感的访问令牌。不要将其提交到 Git 仓库，也不要分享给他人。

3.5 退出登录

bash

codex logout
# 输出: Successfully logged out. Credentials cleared.

3.6 OAuth 登录的优势

优势	说明
零配置	无需手动管理 API Key
安全	使用短期访问令牌，自动刷新
计费透明	直接使用 OpenAI 账号的计费体系
多设备同步	换设备只需重新登录一次

四、认证方式二：OPENAI_API_KEY 环境变量

在某些场景下（如服务器、CI/CD、无浏览器环境），OAuth 登录不方便。这时可以使用 API Key 认证。

4.1 获取 API Key

访问 https://platform.openai.com/api-keys
登录你的 OpenAI 账号
点击 "Create new secret key"
给 Key 起一个描述性名称（如 "Codex CLI - Laptop"）
复制生成的 Key（格式类似 sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx）

⚠️ 重要：API Key 只显示一次！请立即妥善保存，丢失后无法再次查看。

4.2 设置环境变量

临时设置（仅当前终端会话有效）

bash

export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"

持久设置（推荐）

bash

# 如果你使用 bash
echo 'export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

# 如果你使用 zsh
echo 'export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

更安全的方式：使用 .env 文件

bash

# 创建 .env 文件（不要提交到 Git）
echo 'OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx' > .env

# 在运行 codex 时加载
codex --env-file .env "你的任务描述"

# 或者使用 direnv 自动加载
echo 'export OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx' > .envrc
direnv allow

4.3 验证 API Key 认证

bash

# 设置 Key 后直接运行 codex 命令即可
codex "Hello, what model are you using?"

# 或者设置后查看状态
codex whoami
# 输出示例:
# Authenticated via: OPENAI_API_KEY
# API Key prefix: sk-proj-xxxx...xxxx

4.4 API Key 认证的优势与局限

维度	说明
适用场景	服务器、CI/CD、无 GUI 环境
优势	无需浏览器、易于自动化、支持多项目不同 Key
局限	需要手动管理 Key 生命周期、安全性完全取决于使用者

4.5 安全最佳实践

bash

# ✅ 好的做法
# 1. 使用环境变量，不要硬编码在代码中
# 2. 在 .gitignore 中排除 .env 文件
echo '.env' >> .gitignore

# 3. 使用不同的 Key 用于不同环境
export OPENAI_API_KEY_DEV="sk-proj-dev-xxxxx"
export OPENAI_API_KEY_PROD="sk-proj-prod-xxxxx"

# 4. 定期轮换 Key
# 5. 如果 Key 泄露，立即在 OpenAI 平台撤销

# ❌ 不好的做法
# 1. 将 Key 写在脚本中
# 2. 将 Key 提交到 Git 仓库
# 3. 在日志中打印 Key
# 4. 与他人共享同一个 Key

五、认证方式对比

特性	OAuth 登录	API Key
设置复杂度	极低（一条命令）	中等（需手动创建和配置）
安全性	高（短期令牌，自动刷新）	取决于使用者
适合场景	个人开发、桌面环境	服务器、CI/CD、自动化
计费方式	使用 OpenAI 账号额度	使用关联账户额度
多账号支持	需要切换登录	只需切换环境变量
无头环境	不支持	完全支持

5.1 我的建议

日常开发：使用 OAuth 登录，零配置、最安全
服务器部署：使用 API Key，配合密钥管理工具
团队项目：使用 API Key，每个成员使用自己的 Key，便于追踪用量
CI/CD 流水线：使用 API Key，通过 GitHub Secrets 等安全方式注入

六、首次运行测试

完成安装和认证后，建议进行一次快速测试来确认一切正常：

bash

# 创建一个测试目录
mkdir -p ~/codex-test && cd ~/codex-test

# 初始化 Git 仓库（必须步骤，后续文章会详细解释原因）
git init

# 发送一个简单的任务
codex "用 Python 写一个计算斐波那契数列的函数"

如果一切正常，你应该会看到 Codex CLI 启动沙箱环境、执行任务并输出结果。

七、配置文件详解

Codex CLI 的配置文件位于：

bash

# macOS
~/Library/Application\ Support/codex-cli/config.json

# Linux
~/.config/codex-cli/config.json

常见配置项：

json

{
  "model": "o3",
  "sandbox_mode": "ask",
  "auto_approve": false,
  "max_tokens": 8192,
  "temperature": 0,
  "custom_instructions": "",
  "providers": [],
  "plugins": []
}

配置项	默认值	说明
`model`	o3	使用的模型
`sandbox_mode`	ask	沙箱模式：ask / full-auto / yolo
`auto_approve`	false	是否自动批准操作
`max_tokens`	8192	最大 token 数
`temperature`	0	采样温度（0 表示确定性输出）

总结

本文我们完成了 Codex CLI 的完整安装和认证流程：

环境准备：确认 Node.js ≥ 18、npm ≥ 9、Git ≥ 2.30
npm 安装：npm install -g @openai/codex，并排查了常见安装问题
OAuth 登录：通过 codex login 一键认证，适合日常开发
API Key 认证：通过 OPENAI_API_KEY 环境变量认证，适合服务器和自动化场景
首次运行测试：验证安装和认证是否成功
安全最佳实践：Key 管理和环境隔离

现在你的 Codex CLI 已经准备就绪！在接下来的文章中，我们将深入探索 Codex CLI 的核心命令和沙箱机制。

下篇预告

下一篇我们将进入 exec 命令入门。你将学习：

如何使用 codex exec 执行单次编码任务
沙箱环境中的自主编码过程是如何工作的
如何解读 Codex CLI 的输出和结果
实战案例：用一条命令完成文件创建、代码编写和测试

敬请期待！