Codex CLI 是什么，和普通 ChatGPT 有什么区别？

Codex CLI 是 OpenAI 开源的终端编程 Agent（核心用 Rust 编写），在本地终端读取你的代码库、执行命令、直接改文件，完成多步编码任务。它走「模型推理 + 工具调用」循环，能真正动手而不只是聊天；ChatGPT 网页版更偏对话。Codex CLI 与 Codex App、Codex Cloud 共享同一套智能体能力，登录后数据打通。

Windows 能直接用吗？

可以。2026 起 Codex CLI 已支持 Windows 原生运行：装好 Node.js 22+ 后 npm install -g @openai/codex，直接在 PowerShell / Windows Terminal 跑，不需要 WSL2、不需要虚拟机。原生走 AppContainer 沙箱（实验性，默认限制文件写入/网络）。只有项目本身依赖 Linux 工具链（如特定构建脚本、容器）时才需要 WSL2。桌面 App 的 Windows 版也已上线（Microsoft Store / 独立安装器），但企业禁用 Store 时优先用 CLI。

登录用 ChatGPT 账号还是 API Key？

推荐用 ChatGPT 账号登录（首次运行 codex 会弹浏览器授权），好处是 CLI/App/Cloud 数据打通，且 Plus/Pro 用户可领取 30 天免费 API 额度（Plus $5、Pro $50）。若没有订阅 ChatGPT、或要走程序化按 token 计费，则用 API Key（codex --api-key sk-... 或设置 OPENAI_API_KEY 环境变量）。

没有 ChatGPT 订阅、也不想用 OpenAI 官方 Key 能用吗？

可以。Codex CLI 的 Responses API 端点可配置，能指向任意兼容服务：例如 Azure OpenAI，或国内兼容 OpenAI 协议的模型服务（改一行端点即可）。也可以用 --oss 配合本地 gpt-oss 模型（ollama/LM Studio）完全离线运行。

安装或运行报错怎么排？

最常见三类：① Node 版本太低——需 Node.js 22+，用 node -v 核对，低了就升级；② npm 全局安装权限不足——用 nvm 或加 --prefix 指定用户目录，避免裸 sudo；③ 网络/代理问题——安装与登录都需访问 openai.com，国内网络可能要配置代理或用兼容端点。

OpenAI Codex CLI 安装与配置教程：终端里的 AI 编程助手

npm/brew 安装 · Node 22+ · ChatGPT 登录 · API Key · 首个任务 · 常见问题

核心结论：Codex CLI 是 OpenAI 开源的终端编程 Agent，一行 npm i -g @openai/codex 就能装上。先确认 Node.js 22+，再选「ChatGPT 账号登录」（推荐，数据打通还送额度）或「API Key」认证，就能在终端里让它读仓库、跑命令、改文件。

一、它到底是什么

Codex CLI 是 OpenAI 开源的轻量终端编程 Agent（核心用 Rust 编写），是进入「Codex 智能体家族」最轻的入口。它和 ChatGPT 里的 Codex、Codex 桌面 App、Codex Cloud 共享同一套能力——登录同一个 ChatGPT 账号后，三端数据打通。

它和网页版 ChatGPT 的最大区别是能真正动手：在本地终端读取你的代码库、执行 shell 命令、创建/修改文件，跑完多步编码任务后再把结果交给你确认。本质上就是「规划-调用-观察-反思」的 Agent 循环（详见 AI Agent 入门）。

二、环境要求

项目	要求
Node.js	22 或更新版本（部分旧文档写 18+，以当前官方为准推荐 22+）
操作系统	macOS 12+ / 主流 Linux 发行版原生；Windows 10(64位, build 19041+) / 11 可原生 PowerShell 运行，WSL2 仅当项目依赖 Linux 工具链时使用
内存	最低 4GB，推荐 8GB
网络	安装与登录需访问 openai.com（可走代理或兼容端点）

⚠ 先核对 Node：终端执行 node -v，低于 22 请先升级（推荐用 nvm：nvm install 22 && nvm use 22）。版本不够是最常见的安装失败原因。

三、三种安装方式

方式一：npm（全平台）

npm install -g @openai/codex

方式二：Homebrew（macOS / Linux）

brew install codex

方式三：官方一键脚本（macOS / Linux）

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

装完升级也只需重跑对应命令。验证是否成功：

codex --version

Windows 原生安装（无需 WSL2）

2026 起 Codex CLI 已支持在 Windows 上原生运行——装好就能直接在 PowerShell / Windows Terminal 里跑，不需要 WSL、不需要虚拟机。只有当你项目本身依赖 Linux 工具链（特定构建脚本、容器、Linux-only 命令）时才需要 WSL2。原生 Windows 走的是 AppContainer 沙箱（实验性），默认限制文件写入、默认断网，日常足够安全。

步骤一：装好 Node.js 22+

# 用 winget 一行装 LTS（已带 npm）
winget install OpenJS.NodeJS.LTS
# 或去 nodejs.org 下载官方安装包。装完【关闭并重开终端】让 node/npm 进 PATH
node -v   # 确认 ≥ 22

步骤二：安装 Codex CLI

任选其一，都不需要管理员权限：

# A. npm（与 macOS/Linux 同款）
npm install -g @openai/codex

# B. 官方 PowerShell 一键脚本
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# C. WinGet（自动更新）
winget install OpenAI.Codex

包名看准：是 @openai/codex（带作用域），不是 npm 上那个 2012 年的同名 codex 包，装错会报一堆看不出原因的错误。

步骤三：跑起来

# 关闭并重开终端，让全局命令进 PATH
codex --version
cd C:/path/to/your-project
codex        # 首次会弹浏览器登录

原生沙箱配置（可选）

Windows 原生沙箱基于 AppContainer，默认 unelevated（标准用户权限），推荐保持。可在 ~/.codex/config.toml 调整：

# ~/.codex/config.toml
[windows]
sandbox = "unelevated"          # 标准权限（推荐）；elevated 则管理员权限
sandbox_private_desktop = true  # 子进程跑在私有桌面，隔离更干净

⚠ 沙箱局限：Windows 沙箱目前仍为实验性——AppContainer 对「Everyone 已有写权限」的目录无法阻止写入。处理敏感或他人代码时，建议用 WSL2（Landlock/seccomp 隔离更彻底）或走兼容/私有端点。

原生 vs WSL2：怎么选

场景	选哪个
.NET / Unity / 一般 Windows Web 开发，项目在 Windows 文件系统	原生 PowerShell（最简单，Node.js + 一行 npm 装）
构建链 / 脚本依赖 Linux、要更彻底的命令隔离	WSL2（项目放 Linux 文件系统，行为等同服务器）

Windows 常见坑

npm 装完找不到 codex：全局 bin 没进 PATH。运行 npm bin -g 看路径，把它加进「系统设置 → 环境变量 → 用户 PATH」，重开终端。
npm 全局安装权限报错：别裸开管理员强装。用官方 Node 安装包（全局目录默认在你用户目录下）即可；或 npm config set prefix "$env:APPDATA\npm"。
登录浏览器不弹：改用 API Key 登录（见下一节），或 WSL 里登录会给出可粘贴的验证码。

四、登录认证（两种二选一）

方式	适合谁	额度来源
Sign in with ChatGPT（推荐）	有 ChatGPT 账号的用户	走 ChatGPT / workspace 的 Codex 额度；Plus/Pro 另送 30 天免费 API 额度
API Key	无订阅、走程序化计费	platform.openai.com 申请的 Key，按 token 计费

ChatGPT 账号登录（推荐）

# 首次运行会弹出浏览器授权页，点 Allow 即可
codex
# 无图形界面的服务器/CI 环境，可显式登录：
codex login

福利用 ChatGPT 账号登录 Codex CLI 的 Plus / Pro 用户，可领取 30 天免费 API 额度（Plus $5、Pro $50），CLI/App/Cloud 三端通用。

API Key 登录

# 直接传 Key
codex --api-key sk-...
# 或写入环境变量后运行
export OPENAI_API_KEY=sk-...
codex

密钥安全：API Key 等同你的「印钞权」，切勿写进前端或提交到仓库。前端需要智能能力时，应走你自己的后端代理（详见 API Key 安全管理）。

五、跑通第一个任务

进入项目：切到任意一个 git 仓库目录，Codex 会读取当前目录的代码。
启动：运行 codex 进入交互式 TUI（带输入框、输出面板、状态栏）。
下指令：先用低风险任务试探，例如「帮我看一下这个项目的目录结构，指出最可能出 bug 的模块」。
让它改文件：明确描述改动，例如「把 src/utils/format.js 里的日期格式从 YYYY-MM-DD 改成 YYYY/MM/DD，并确认所有引用点正常」。

cd /path/to/your-git-project
codex
# 在输入框里输入：
# 帮我看一下这个项目的目录结构，并指出最可能存在 bug 的模块

⚠ 权限确认：Codex 直接改文件、跑命令，每次有副作用的操作前都会请你确认。把它当「待审副驾」，改完一定 review 再提交。

六、进阶配置

1. 用本地 / 兼容模型

Codex CLI 的推理端点可配置，能指向任意兼容 Responses API 的服务：

本地模型：codex --oss 配合 ollama 0.13.4+ 或 LM Studio 0.3.39+ 跑 gpt-oss，完全离线；
云兼容端点：如 Azure OpenAI 或国内兼容 OpenAI 协议的服务，改 ~/.codex/config.toml 里的端点即可（具体字段以官方文档为准）。

2. 接 MCP 工具

通过 MCP 让 Codex 读取外部系统（如 Figma、数据库）。示例：codex mcp add figma --url https://mcp.figma.com/mcp，按提示授权后即连。

七、常见问题

Codex CLI 默认用哪个模型？

新版 CLI 默认用 codex-mini 系列（专为 CLI 优化的低延迟代码模型），也可在配置里指定其他兼容模型。具体可用模型 id 以 OpenAI 官方文档为准。

API Key 和 ChatGPT 登录能混用吗？

同一台机器建议固定一种。ChatGPT 登录走 workspace 额度、数据打通；API Key 走按量计费。切换时清掉对应环境变量/会话即可。

公司代码会不会被拿去训练？

用 ChatGPT 账号登录走的是 Codex 工作区，按 OpenAI 的企业数据处理政策隔离；自托管/兼容端点场景下数据完全不出你的控制域。敏感行业建议走私有化或合规端点。

AI 编程助手评测 » · AI Agent 入门 » · 函数/工具调用实战 » · API Key 安全管理 » · 返回 AI 技术文档 »