Codex CLI 安装与上手（Windows）

▒ 目录 ▒Codex CLI 安装与上手Windows1️⃣ 准备环境2️⃣ 安装 Codex CLI2.1 方式一官方 Windows 独立安装器2.2 方式二沿用橙皮书的 npm 安装路线3️⃣ 登录与确认身份3.1 使用 ChatGPT 账号登录3.2 使用设备代码登录远程 Windows 上的 Codex3.3 使用 OpenAI API Key 登录可选4️⃣ 在项目目录中启动4.1 管理员终端报错如何处理4.2 Windows 沙箱与管理员终端的区别5️⃣ 完成第一个任务5.1 先确认工作目录5.2 创建一个计数器页面5.3 打开并验收5.4 恢复同一个会话6️⃣ 常用命令与输入位置7️⃣ 查看剩余额度和重置时间8️⃣ 用 AGENTS.md 保存项目约定9️⃣ 更新与排障9.1 更新 CLI9.2 提示找不到 codex或更新后版本不变9.3 提示 npm.ps1 或 codex.ps1 无法加载9.4 登录、权限或环境仍然异常 一次上手完成的标志 参考资料11.1 原文来源11.2 OpenAI 官方文档11.3 配套工具与查询入口Codex CLI 安装与上手Windows本文面向在 Windows 上使用 PowerShell 的开发者完成从安装、登录到第一次修改文件的全过程并介绍会话恢复、额度查询和常见故障处理。核对日期2026-09-26。本机命令帮助核对版本codex-cli 0.157.1。1️⃣ 准备环境使用 Windows 原生 PowerShell或在 Windows Terminal 中打开 PowerShell 标签页。日常启动 Codex 使用普通权限终端安装程序单独弹出的权限提示按需处理。准备以下条件项目用途PowerShell执行安装、登录和启动命令浏览器及可访问服务的网络完成账号登录、下载组件及模型请求可使用 Codex 的 ChatGPT 账号或 OpenAI API Key身份认证与用量计费项目文件夹存放 Codex 要读取、修改的文件Node.js 和 npm仅 npm 安装路线需要Git建议查看代码差异、记录修改和恢复版本Windows Terminal 是终端窗口应用PowerShell 是其中运行的命令解释器。以下powershell代码块都在 PowerShell 中执行不要把提示符PS C:\...一起复制进去。2️⃣ 安装 Codex CLI两种方式任选一种。已经通过某种方式安装成功就沿用该方式维护避免多个版本同时出现在 PATH 中。2.1 方式一官方 Windows 独立安装器没有 Node.js 环境时可以直接使用官方安装器powershell-ExecutionPolicy ByPass-cirm https://chatgpt.com/codex/install.ps1 | iex这条命令下载并执行 OpenAI 官方安装脚本。-ExecutionPolicy ByPass作用于这里启动的 PowerShell 进程不是永久修改整个系统的执行策略。安装结束后重新打开 PowerShell检查codex--version codex--help能够显示版本号和帮助内容说明终端已经能找到 CLI。官方安装说明2.2 方式二沿用橙皮书的 npm 安装路线先到 Node.js 官方下载页 选择适用于 Windows 和本机架构的 LTS 安装包按安装向导完成安装然后重新打开 PowerShell。确认 Node.js 与 npm 可用node--version npm--version两条命令都输出版本号后安装 Codexnpm install-g openai/codex codex--version-g表示把 CLI 安装到 npm 的全局命令位置方便在不同项目目录中调用。官方 npm 安装说明如果 PowerShell 提示不允许执行npm.ps1可显式调用 npm 的 Windows 命令入口npm.cmd--version npm.cmd install-g openai/codex codex.cmd--versioncodex.cmd对应 npm 安装产生的启动器独立安装方式不一定存在这个文件。3️⃣ 登录与确认身份3.1 使用 ChatGPT 账号登录在 PowerShell 执行codex login按照浏览器中的提示完成登录再回到终端检查codex login status此命令用于检查认证状态不用于查询剩余额度。账号能够登录与账号当前有可用额度是两件事。官方认证说明3.2 使用设备代码登录远程 Windows 上的 Codex设备代码登录是指在运行 Codex 的电脑上发起登录再通过自己电脑或手机上的浏览器确认授权。它仍然使用 ChatGPT 账号及其对应的 Codex 权益无需 API Key。官方认证说明例如Codex 安装在一台远程 Windows 电脑上你通过 SSH 或远程桌面打开了它的 PowerShell但不方便在远程电脑上使用浏览器就可以采用这种方式。本机浏览器无法自动打开或登录完成后终端一直等不到回调时也适用。需要先在网页上设置安全选项第一步在运行 Codex 的远程电脑上发起登录。codex login--device-auth终端会显示验证网址和一次性设备代码保持这个终端等待登录结果。第二步在自己的电脑或手机浏览器中完成授权。打开终端提供的网址登录要使用的 ChatGPT 账号并输入该终端显示的设备代码。如果提示未启用设备代码登录先到 ChatGPT 的账号安全设置中开启工作空间账号可能需要管理员在工作空间权限中启用。设备代码登录说明第三步回到远程电脑确认登录状态。codex login status显示已登录后进入远程电脑上的实际项目目录执行codex。如果遇到第 4.1 节的管理员终端报错则使用codex --no-daemon。这一步授权的是运行登录命令的那台电脑。Codex 随后读取的项目文件、执行的命令也位于那台电脑。设备代码负责账号认证后续终端操作仍通过 SSH、远程桌面等方式进行完成授权本身不会建立远程控制通道。3.3 使用 OpenAI API Key 登录可选API Key 是在 OpenAI 开发者平台创建的密钥。API 登录就是让 Codex CLI 使用这份密钥认证请求并按 OpenAI Platform 的 API 规则计费。对比项ChatGPT 账号登录含设备代码方式OpenAI API Key 登录认证凭据ChatGPT 账号授权OpenAI Platform 创建的 API Key使用额度账号对应的 Codex 权益API 平台独立计费与 Plus / Pro 的关系使用套餐提供的 Codex 额度不抵扣 Plus / Pro 的订阅额度如何开始codex login或codex login --device-authcodex login --with-api-key通过标准输入提供密钥如果已有 ChatGPT Plus / Pro目的是使用套餐包含的 Codex 额度选择 ChatGPT 账号登录即可。官方认证与计费说明本节所指的是 OpenAI 官方 API Key。第三方平台发放的 Key 通常还需要匹配服务商地址和模型配置应按该平台的接入说明处理。如果当前 PowerShell 已通过你的凭据管理方式提供OPENAI_API_KEY可以执行$env:OPENAI_API_KEY|codex login--with-api-key codex login status也可以交互输入避免把真实密钥写进可复制的命令文本$codexApiKeyRead-Host请输入 OpenAI API Key-AsSecureString$codexCredential[System.Net.NetworkCredential]::new(,$codexApiKey)try{$codexCredential.Password|codex login--with-api-key}finally{Remove-VariablecodexCredential,codexApiKey}密钥通过标准输入交给 CLI不会作为登录命令的参数出现。不要把真实密钥写入项目文件或提交到 Git。--with-api-key的含义已通过本机codex login --help核对。4️⃣ 在项目目录中启动先创建一个专门用于练习的文件夹。以下命令使用当前用户目录不依赖电脑是否有 D 盘$codexProjectJoin-Path$env:USERPROFILECodexProjects\hello-codexNew-Item-ItemType Directory-Path$codexProject-Force|Out-NullSet-Location-LiteralPath$codexProjectGet-Locationcodex如果目录已存在先确认里面的内容适合用来练习。接入已有项目时直接进入项目根目录再启动也可以指定工作目录codex-CD:\Projects\My App将示例路径换成实际项目路径路径包含空格时保留引号。-C已通过本机codex --help核对。4.1 管理员终端报错如何处理如果出现以下关键提示start the Windows daemon from a non-elevated terminal说明 CLI 检测到管理员权限拒绝在这种权限下启动共享后台服务。日常使用可重新打开普通权限 PowerShell再执行codex。如果当前确实需要使用这个管理员终端按错误提示跳过共享后台服务codex--no-daemon恢复最近会话时也保留这个参数codex--no-daemon resume--last--no-daemon只表示不使用共享后台服务不代表降低当前进程权限也不等同于关闭沙箱。上述参数已通过本机0.157.1的帮助信息核对。4.2 Windows 沙箱与管理员终端的区别Windows 原生沙箱的elevated模式使用专门的受限用户和权限边界名称中的elevated不表示日常应从管理员 PowerShell 启动 Codex。沙箱安装需要的权限与共享后台服务的启动权限属于不同环节。首次使用按 CLI 的沙箱设置提示操作即可。已有配置需要指定 Windows 沙箱实现时对应配置为[windows] sandbox elevated只有该实现无法完成设置时再根据报错考虑unelevated回退方案。官方 Windows 沙箱说明5️⃣ 完成第一个任务建议用一个不依赖框架的静态页面练习先熟悉“描述需求、检查文件、运行结果、继续修改”的过程。5.1 先确认工作目录进入 Codex 后在它的对话输入框中输入先确认当前工作目录并列出已有文件。 暂时不要修改文件。用中文说明这个目录是否适合创建一个静态页面练习。核对回答中的路径与刚才Get-Location输出一致。5.2 创建一个计数器页面如果是空的练习目录可以继续输入请在当前目录创建一个 index.html做一个中文计数器页面。 要求 - HTML、CSS、JavaScript 全部写在这个文件中。 - 不安装依赖不引用外部资源。 - 初始计数为 0提供“加一”和“重置”两个按钮。 - 页面声明 UTF-8 编码。 - 不覆盖已有文件如有同名文件先说明情况。 完成后说明创建了什么、如何打开以及需要我手动验证哪些行为。如果出现权限请求先核对要执行的命令及其目标文件。需要查看当前权限时在 Codex 中输入/permissions。官方权限命令5.3 打开并验收完成后在 Codex 中输入/quit回到 PowerShell再执行Start-Process-FilePath.\index.html检查页面初始值是否为 0点击三次“加一”是否显示 3再点击“重置”是否回到 0。同时确认中文没有乱码。如果文件未按预期生成或按钮行为错误把实际现象交给 Codex。例如index.html 中点击三次“加一”后显示 3但点击“重置”没有变化。 请检查重置按钮的事件绑定只修复这个问题并解释修改原因。5.4 恢复同一个会话在同一个项目目录中执行codex resume--last需要从历史会话中选择时用codex resume。遇到前述管理员终端限制时加上--no-daemon。项目已经使用 Git 时修改后可在 PowerShell 中检查git status--short gitdiffgit diff默认不显示未跟踪新文件的正文新文件需直接打开检查。CLI 中也可使用/diff查看改动。官方差异查看说明6️⃣ 常用命令与输入位置先分清命令输入位置以codex开头的命令通常在 PowerShell 执行以/开头的命令在 Codex 对话框输入。输入位置命令用途PowerShellcodex --version查看版本PowerShellcodex --help查看当前版本支持的参数PowerShellcodex login status查看登录状态PowerShellcodex resume --last继续最近会话PowerShellcodex doctor --summary输出环境诊断摘要Codex 对话框/model选择账号当前可用模型Codex 对话框/plan切换规划模式Codex 对话框/permissions查看或调整权限Codex 对话框/diff查看文件改动Codex 对话框/review发起代码审查Codex 对话框/status查看会话状态和可获取的额度信息Codex 对话框/init生成项目指令文件草稿Codex 对话框/quit退出 CLI终端命令以本机帮助为准斜杠命令也可以通过在 Codex 中输入/查看可选项。官方命令参考7️⃣ 查看剩余额度和重置时间使用 ChatGPT 账号登录后在 Codex 对话框输入/status额度区可能显示以下信息具体字段以版本及账号返回的数据为准字段如何理解5h limit5 小时额度窗口Weekly limit周额度窗口xx% left对应窗口的剩余比例resets ...对应窗口下一次重置时间Context ... left当前对话上下文的剩余空间不能当作账号额度判断什么时候恢复应查看对应窗口显示的重置时间不要自行假定每天零点或每周一统一恢复。CLI 没有展示完整信息时使用 Codex 用量页面。官方文档也将该页面作为查询当前限制与重置时间的入口。官方用量说明希望常驻显示额度可以在 Codex 中输入/statusline选择额度相关项目。新版还提供/usage查询账号 Token 活动Token 统计与套餐剩余额度的含义不同。官方状态栏与用量命令API Key 登录的费用和余额到 OpenAI Platform 查询第三方服务则以对应平台的统计为准。8️⃣ 用 AGENTS.md 保存项目约定当练习进入实际项目后可以在 Codex 对话框输入/init生成AGENTS.md草稿再补上项目真实的运行方式和约束。也可以手动创建该文件。官方 AGENTS.md 说明适合 Windows 项目的最小示例# 项目约定 - 使用中文解释修改。 - 本项目在 Windows PowerShell 中运行命令使用 PowerShell 语法。 - 文本文件使用 UTF-8PowerShell 读取文本显式指定 -Encoding utf8。 - 开始修改前先确认项目结构及实际运行方式。 - 修复问题时保持改动范围集中。 - 完成后说明修改内容、验证结果和未能验证的部分。然后补充真实的构建、测试和启动命令。AGENTS.md是协作指令文件不是强制执行的权限隔离机制。用户级配置默认位于%USERPROFILE%\.codex\config.toml设置了CODEX_HOME时以该目录为准。可信项目还可使用项目内的.codex\config.toml。配置是 TOML编辑已有文件时合并相关设置不要把示例覆盖到整个文件。官方配置说明9️⃣ 更新与排障9.1 更新 CLI通过 npm 安装的版本退出正在运行的 CLI 后执行npm.cmd install-g openai/codexlatest codex--version独立安装器安装的版本可以重新运行第 2.1 节的官方安装命令更新。本机0.157.1也提供codex update是否支持自更新及实际执行方式以当前安装渠道的提示为准。官方安装与更新说明9.2 提示找不到 codex或更新后版本不变先重新打开 PowerShell再检查命令来源Get-Commandcodex-All|Select-ObjectCommandType,Name,Source where.exe codex若出现多条路径可能同时安装了多个版本。结合路径判断当前执行的是哪一份再处理对应的安装渠道。npm 路线可进一步检查npm.cmd config get prefix npm.cmd list-g openai/codex--depth0如果包已安装但找不到启动命令检查 npm 全局命令目录是否位于当前用户 PATH 中。不要把某个用户名下的固定路径照抄到另一台电脑。9.3 提示 npm.ps1 或 codex.ps1 无法加载这是 PowerShell 脚本执行策略问题。对于 npm 安装的 CLI可以显式使用.cmd启动器codex.cmd--version codex.cmd如果同时遇到管理员后台服务错误组合使用codex.cmd--no-daemon9.4 登录、权限或环境仍然异常本机版本支持以下诊断命令codex login status codex doctor--summary现象下一步浏览器登录完成终端仍等待核对回调是否受阻尝试设备代码登录CLI 显示等待权限批准阅读屏幕上的操作请求在对应界面处理读取了错误项目检查启动目录或-C指定的路径已登录但无法发起任务核对账号额度、模型可用性及服务错误信息配置加载失败根据错误位置检查 TOML 格式和当前版本支持的配置键中文文件读取乱码检查文件实际编码UTF-8 文件用Get-Content -Encoding utf8读取提交问题时附上 CLI 版本、命令、错误文本和相关路径即可登录凭据无需放进诊断描述。 一次上手完成的标志完成本文后应能做到在 PowerShell 中运行codex --version并看到版本号。确认登录状态在指定项目目录启动 CLI。创建计数器页面并亲自验证按钮行为。用codex resume --last继续之前的会话。分清/status中的上下文空间与账号额度。遇到管理员终端限制时知道如何使用--no-daemon。后续把练习迁移到真实项目时从一个可复现的小问题开始给出涉及的文件、预期行为和验证方法再检查 Codex 的修改是否满足这些条件。 参考资料11.1 原文来源《ChatGPT 橙皮书》Codex CLI 安装与上手本文的主要参考章节提供安装、登录、基础命令与上手流程。bozhouDev/codex-orange-book 源码仓库查看原书 Markdown、PDF 和后续更新。该书为社区编写的非官方指南。11.2 OpenAI 官方文档资料对应本文内容Codex CLIWindows 独立安装器、npm 安装与更新、首次运行Authentication身份验证ChatGPT 登录、API Key、设备代码登录及认证方式区别Developer commands命令参考终端命令、会话恢复、斜杠命令、状态栏和用量查看Windows sandboxWindows 沙箱原生沙箱实现、设置和故障排查Config basics基础配置用户级与项目级配置、配置优先级和 Windows 设置Custom instructions with AGENTS.md项目指令文件的用途与组织方式Pricing计费与用量套餐额度、API 计费区别及用量查询入口11.3 配套工具与查询入口Node.js 官方下载npm 安装路线所需的 Node.js 环境。Codex 用量页面登录后查看自己账号的当前额度与重置时间。