Codex 安装与初始配置：Windows、macOS、Linux

Codex CLI 可以在终端中读取项目、编辑文件、运行命令。这篇从安装开始，直到它能在指定文件夹里完成一次小任务。

资料核对日期：2026 年 9 月 8 日。桌面应用、IDE 和手机入口见 Codex 多端使用教程。

先选登录方式

Codex 支持使用 ChatGPT 账号登录，也支持 API 密钥登录。两者的权限和计费方式不同：

ChatGPT 登录：使用账号和工作区当前提供的 Codex 权限与额度。
API 密钥登录：使用 OpenAI Platform 的 API 计费，一些依赖 ChatGPT 工作区或云服务的功能可能不可用。

初次使用，可以先走客户端提供的 ChatGPT 登录流程。本文不要求创建 API 密钥。

macOS / Linux：官方原生安装

打开终端，运行官方 CLI 页面提供的命令：

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

按安装器提示完成后，重新打开终端，检查：

codex --version

看到版本号，说明终端已经能找到 Codex。

官方也提供 npm 和 Homebrew 安装选项。如果已经选了原生安装，后续使用同一种方式更新，便于确定当前运行的是哪一个版本。

Windows：在 PowerShell 中安装

官方 CLI 页面提供 Windows 原生安装选项。另一种适合已有 JavaScript 开发环境的方式是 npm，下面给出完整步骤。

先从 Node.js 官网安装 LTS 版本，重新打开 PowerShell，检查：

node --version
npm.cmd --version

然后安装 Codex：

npm.cmd install -g @openai/codex
codex.cmd --version

这里显式使用 .cmd，可以避开 PowerShell 将 npm 命令解析到 npm.ps1 时出现的脚本执行策略问题。后续进入项目后，也可以使用 codex.cmd 启动。

如果终端能正常运行 npm 和 codex，可直接使用不带后缀的命令。

已经在使用 WSL 2

在 WSL 的 Linux 终端内部运行前面的 macOS / Linux 原生安装命令。项目优先放在 WSL 的 ~/code/ 或 ~/projects/ 中，并在同一环境安装项目依赖。

Windows 和 WSL 默认使用各自的用户目录，登录状态和配置不会因为装在同一台电脑上就自动共用。当前官方文档要求使用 WSL 2；WSL 1 已不在新版 Codex 的支持范围内。

登录并开始第一次会话

先进入项目目录：

cd "你的项目路径"
codex

Windows 使用 npm 方式安装且遇到脚本策略提示时，把最后一行改成 codex.cmd。

第一次运行时选择 Sign in with ChatGPT，在浏览器完成登录，返回终端。也可以单独运行：

codex login
codex login status

确认当前登录方式和账号符合预期后，再发出任务。

配置一：项目的 AGENTS.md

在项目根目录创建 AGENTS.md，记录工具需要遵守的项目约定：

# 项目说明

使用简体中文交流。
先阅读 README，再修改项目。
按照项目已有的结构和命名方式工作。
修改后运行与本次改动相关的检查，并说明结果。
无法运行某项检查时，写清楚原因。

如果项目已有 AGENTS.md，先阅读并合并需要补充的内容。实际项目里还应写清启动命令、测试命令、主要目录的作用。

配置二：个人 config.toml

用户配置文件通常位于：

环境	路径
macOS、Linux、WSL	`~/.codex/config.toml`
Windows	`%USERPROFILE%\.codex\config.toml`

初次使用可以保留默认设置。如果需要明确工作目录内的修改权限，可在个人配置里合并：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

这表示允许工具在工作区内进行日常修改，同时按照权限规则处理需要额外授权的操作。配置会受到组织策略和启动参数影响，可以在会话中输入 /status、/permissions 核对实际状态。

原生 Windows 的沙盒配置，官方推荐使用：

[windows]
sandbox = "elevated"

按客户端的安装提示完成沙盒设置；如果无法获得相应权限，参考 Windows 沙盒文档的可用方案。

模型通过 /model 选择当前账号可用的选项。初次配置不必把教程里的某个型号写死到配置文件中。

做一次可检查的练习

在练习目录里准备一个 README.md，然后发送：

阅读 README.md，说明这个目录的用途。把缺少的“如何开始”和“如何验证”补成两个简短段落，只使用项目里能确认的信息。

完成后，用编辑器打开文件检查。项目已经使用 Git 的话，还可以在终端查看：

git diff

成功的标志是：Codex 在正确的目录操作，文件出现了对应修改，修改结果能由你自己检查。

更新与排错

原生安装按官方文档重新运行对应安装命令更新。npm 安装可以使用：

npm install -g @openai/codex@latest

Windows PowerShell 可写成 npm.cmd install -g @openai/codex@latest。

现象	处理方向
找不到 `codex`	重开终端，检查安装器提示的 PATH 和当前系统环境
`npm.ps1` 被执行策略阻止	使用 `npm.cmd`，安装后按需要使用 `codex.cmd`
登录后仍提示不可用	检查账号、工作区和 Codex 权限；用 `codex login status` 查看状态
API 余额不足	检查是否正在使用 API 密钥登录；API 账单独立计算
项目文件找不到	检查启动目录，区分 Windows 路径与 WSL 路径
配置似乎被忽略	检查 TOML 语法、实际加载的配置层和组织限制

下一步：Codex 桌面、IDE、云端和手机怎么配合使用。