Codex CLI 新手指南:从安装到上手

TUTORIAL

Codex CLI 新手指南：从安装到上手

OpenAI 官方出品的本地编程智能体，一行命令安装，让 AI 帮你写代码、跑测试、改 Bug。

#AI编程 #命令行工具 #OpenAI

预计阅读(分)

共 3200 字

READING PATH

阅读路线

5 个章节

认识 Codex

环境准备

安装 Codex

认证配置

实战上手

CHAPTER 01

01 认识 Codex CLI WHAT IS CODEX

想象一下：你对着终端说一句话，AI 就能帮你读懂整个项目、改代码、跑测试、提 PR。这就是 Codex CLI —— OpenAI 官方出品的本地编程智能体。

Codex CLI 是一个开源、免费、运行在你本地终端的 AI 编程助手。不同于 ChatGPT 网页版，它能直接访问你的文件系统，读代码、写代码、执行命令，甚至帮你跑测试和修 Bug。

💡 核心亮点

✅ 本地运行 — 代码不离开你的电脑，安全放心

✅ 沙箱保护 — 默认只读文件系统，不会误删代码

✅ 多种认证 — 支持 ChatGPT 账号直接登录，也支持 API Key

✅ 完全开源 — Apache-2.0 协议，代码透明可审计

简单来说，Codex CLI 就是你终端里的 AI 全栈工程师。你说需求，它来干活。

CHAPTER 02

02 环境准备 PREREQUISITES

环境	要求
操作系统	macOS 12+、Ubuntu 20.04+、Windows 11（需 WSL2）
Git	2.23+（推荐安装）
内存	4GB 起步，推荐 8GB
Node.js	仅 npm 安装方式需要，其他方式不需要

⚠️ Windows 用户注意

Codex CLI 不支持原生 Windows，必须通过 WSL2（Windows Subsystem for Linux）运行。如果你还没装 WSL，先在 PowerShell 里运行 wsl --install。

CHAPTER 03

03 安装 Codex CLI INSTALLATION

一行命令安装（推荐）

最快的方式，打开终端直接粘贴：

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

💡 小贴士

这个脚本会自动下载适合你系统的独立二进制文件，不需要 Node.js 环境。安装完成后，codex 命令就可以直接使用了。

其他安装方式

如果一行命令安装失败，还有 Plan B：

# 方式二：npm 安装（需要 Node.js）
npm install -g @openai/codex

# 方式三：Homebrew（macOS）
brew install --cask codex

也可以去 GitHub Releases 页面手动下载对应系统的二进制文件。

验证安装

codex --version

看到版本号（如 v0.135.0）说明安装成功！

CHAPTER 04

04 认证与配置 AUTHENTICATION

方式一：ChatGPT 账号登录（推荐）

如果你有 ChatGPT Plus、Pro、Business、Edu 或 Enterprise 账号，直接登录最省事：

第一步：在终端运行 codex

第二步：选择 "Sign in with ChatGPT"

第三步：浏览器会自动打开，授权后即可使用

全程不需要手动管理 API Key，用完即走。

方式二：API Key

如果你没有 ChatGPT 付费账号，可以用 API Key：

第一步：去 platform.openai.com 注册并创建 API Key

第二步：设置环境变量：

# 临时设置（当前终端有效）
export OPENAI_API_KEY="sk-你的密钥"

# 永久设置（写入 shell 配置）
echo 'export OPENAI_API_KEY="sk-你的密钥"' >> ~/.bashrc
source ~/.bashrc

🚨 安全提醒

API Key 是你的账密，千万不要提交到 Git 仓库、发到群里、或贴到公开页面。建议用环境变量管理，而不是硬编码到配置文件。

CHAPTER 05

05 实战上手 GETTING STARTED

你的第一个命令

进入你的项目目录，启动 Codex：

# 进入项目目录
cd ~/my-project

# 启动交互模式
codex

# 或者直接给它一个任务
codex "帮我看看这个项目用了什么技术栈"

Codex 会自动扫描项目文件，分析代码结构，然后给出详细回答。

常用场景示例

以下几个真实场景，感受一下 Codex 的威力：

# 🔍 读懂代码
codex "解释一下 src/main.py 的核心逻辑"

# 🐛 修复 Bug
codex "用户反馈登录页面报 500 错误，帮我排查一下"

# ✅ 跑测试
codex "跑一下单元测试，看看有没有失败的"

# 📝 写新功能
codex "给 API 加一个 /health 健康检查接口"

# 🔧 重构代码
codex "把 utils.py 里的重复代码提取成公共函数"

沙箱模式：安全第一

Codex 有三种沙箱安全级别，新手务必从最安全的开始：

模式	权限	适用场景
read-only	只读文件，不能写入或执行	代码审查、学习理解
workspace-write	可写当前目录	日常开发、写功能
danger-full-access	无限制	仅限容器/隔离环境

# 使用指定沙箱模式启动
codex --sandbox read-only "分析这段代码"
codex -s workspace-write "帮我重构这个模块"

非交互模式：自动化神器

如果你想把 Codex 集成到 CI/CD 流水线或脚本里，用 codex exec：

# 非交互执行，完成后自动退出
codex exec "修复所有 lint 错误"

# 管道输入
cat error.log | codex exec "分析这个错误日志"

# 不保存会话文件（一次性任务）
codex exec --ephemeral "给 README 加个 badges"

💡 什么时候用 exec？

codex 是交互模式，适合人来对话；codex exec 是非交互模式，适合脚本和自动化。

💡

新手避坑指南

踩过的坑就是你的经验，以下是最常见的几个：

🚨 坑 1：Windows 用户装不上

Codex CLI 不支持原生 Windows，必须在 WSL2 里装。别在 PowerShell 里折腾了，直接进 WSL。

🚨 坑 2：配置文件格式搞错

Codex CLI 已经用 Rust 重写了，配置文件是 config.toml，不是 config.json。老教程里的 JSON 配置已经过时了。

🚨 坑 3：上来就用 full-access

新手建议从 read-only 开始，等你信任它的行为后再逐步放开权限。别一上来就 danger-full-access，它真的会帮你删文件的。

🚨 坑 4：API Key 泄露

用环境变量管理 Key，不要写死在代码里。不小心提交到 GitHub 的话，Key 会在几秒内被爬虫抓走。

⚡

常用命令速查

命令	说明
`codex`	启动交互模式
`codex "任务"`	带初始提示启动
`codex exec "任务"`	非交互执行
`codex --version`	查看版本
`codex sandbox CMD`	在沙箱中测试命令
`codex app`	启动桌面应用模式

CHAPTER 06

06 写在最后 CONCLUSION

Codex CLI 是目前最成熟的本地 AI 编程工具之一。它不需要你离开终端、不需要上传代码到云端，就能让 AI 帮你完成大部分编程任务。

对于新手，记住三句话就够了：

① 一行命令安装，ChatGPT 账号直接登录

② 从 read-only 沙箱开始，逐步放开权限

③ 用 codex exec 做自动化，用 codex 做交互

现在就打开终端，输入 curl -fsSL https://chatgpt.com/codex/install.sh | sh，开始你的 AI 编程之旅吧！🚀

觉得有用？帮忙点个「在看」让更多人看到 👇

点赞 · 在看 · 转发

THANKS FOR READING