这篇文章面向第一次在 Windows 上接触 Codex CLI 的开发者，重点讲清楚“安装客户端、登录、进入项目、首次运行、排查故障”这条链路。这里的“本地部署”指把命令行客户端安装到本机并在本地项目目录中使用，不等于把模型完全下载到电脑、断网运行。
一、先把“本地部署”这个说法讲清楚
很多教程把“下载 Codex”和“本地部署模型”混为一谈，容易让人误解。对 Codex CLI 来说，通常要区分三件事：
因此，本文不把“本地安装客户端”包装成“模型完全离线运行”。如果你的目标是断网运行模型，应另行评估本地模型、显卡、推理框架、模型文件和许可证，不能只安装 Codex CLI。
二、开始前检查 Windows 环境
建议先在 PowerShell 中检查基础环境：
node —version
npm —version
Get-Command codex –ErrorAction SilentlyContinue
如果 node 或 npm 不存在，不要先反复执行 Codex 命令。先确认 Node.js 是否已安装，以及 npm 是否在 PATH 中。
如果已经能找到 codex，再检查版本：
codex —version
版本号会随发布变化。文章只展示检查方法，不把某一次本机版本当成所有读者都相同的固定版本。
三、Windows 上的安装方式
方式一：使用官方安装脚本
官方仓库当前给出的 Windows 安装示例是 PowerShell 命令。复制前，建议先打开官方安装说明确认命令是否有变化：
powershell –ExecutionPolicy ByPass –c "irm https://chatgpt.com/codex/install.ps1 | iex"
这类“一键脚本”执行前要注意两点：
- 先阅读脚本来源和执行内容，确认网络、代理和安全策略符合自己的环境；
- 如果公司电脑禁止脚本执行，优先按组织安全要求处理，不要为了安装而绕过安全控制。
方式二：使用 npm 安装
如果本机已经有 Node.js 与 npm，也可以使用 npm：
npm install –g @openai/codex
安装后重新打开 PowerShell，再检查：
codex —version
如果出现“找不到 codex”，优先排查全局 npm bin 目录是否加入 PATH，而不是立即重复安装。
可以先查看 npm 的全局安装位置：
npm prefix –g
npm bin –g
不同 npm 版本对 npm bin -g 的支持可能不同。如果该命令不可用，可以使用 npm prefix -g 结合当前 Node.js/npm 安装方式查找全局命令目录。
方式三：直接使用发布包或其他安装方式
项目发布页可能提供不同平台的构建产物。下载前要核对系统架构、文件来源、校验信息和安装说明。不要从不明网盘、二次打包页面或来历不明的脚本安装命令行工具。
四、登录与凭证安全
安装完成后，可以先运行：
codex
根据当前界面选择可用的登录方式。官方 README 说明了使用 ChatGPT 账号登录的路径，也说明了 API key 方式需要额外配置。实际选项可能随版本变化，因此不要把旧截图中的按钮名称当成永久不变的界面。
如果使用 API key：
- 不要把密钥写进文章、截图、Git 仓库或命令历史；
- 不要把密钥直接放在项目代码中；
- 优先使用系统环境变量或官方支持的凭证存储方式；
- 分享终端截图前，检查用户名、路径、令牌和组织信息是否暴露。
可以用占位符表示环境变量，而不是写真实值：
$env:OPENAI_API_KEY = "<YOUR_API_KEY>"
上面的命令只是展示变量形式，不建议把真实密钥直接粘贴到可公开的脚本中。完成测试后，还要确认该变量是否被写入了持久化配置或 PowerShell 配置文件。
五、进入项目目录，再开始第一次运行
不要在包含大量私人文件的根目录中直接运行。先为测试准备一个明确的项目目录，并确认当前路径：
Set-Location "C:\\work\\demo-project"
Get-Location
Get-ChildItem
然后再启动：
codex
首次运行时，建议给出范围清晰的任务，例如：
请先读取项目结构，不要修改文件。列出入口文件、测试命令和可能的风险。
这个顺序比一开始就要求大范围重构更稳妥，因为你可以先观察工具是否进入了正确目录、是否理解了项目结构、是否提出了需要确认的操作。
六、常见问题与排查顺序
1. codex 不是内部或外部命令
可能原因：
- 没有安装成功；
- 全局 npm 命令目录没有加入 PATH；
- 安装后终端没有重新加载环境变量；
- 当前用户与安装命令使用的用户不同。
建议顺序：
npm prefix –g
Get-Command node
Get-Command npm
Get-Command codex –ErrorAction SilentlyContinue
确认安装位置后，重新打开终端，再次运行 codex –version。不要通过下载来历不明的 codex.exe 来“临时修复”。
2. 安装过程卡住或连接失败
先区分是 DNS、代理、证书、权限还是包管理器问题。可检查：
npm config get registry
npm config get proxy
npm config get https-proxy
如果公司网络有统一代理，应按管理员提供的配置处理。不要把代理地址、账号密码或内部域名直接写进公开文章和截图。
3. 登录后仍无法启动任务
可能是登录状态、网络连接、账户权限、工作区配置或版本差异。可以先查看登录状态：
codex login status
然后重新启动一个最小任务，记录完整错误信息中的错误码、发生阶段和当前目录。不要只截取“失败”两个字，因为没有上下文就无法判断根因。
4. 工具读取了不该读取的文件
这通常不是“安装失败”，而是启动目录和任务边界没有控制好。改进方式：
- 在项目目录中启动；
- 先要求只读检查；
- 明确允许访问的文件范围；
- 涉及删除、覆盖、提交或外部发布时先人工确认；
- 不把含有密钥、客户资料和内部文档的目录混在测试工作区中。
七、首次部署后的安全检查清单
安装成功不等于可以直接用于生产项目。至少检查以下项目：
- codex –version 能返回版本信息；
- codex login status 的状态符合预期；
- 启动目录是目标项目，而不是用户主目录；
- 项目中的密钥和隐私文件没有纳入公开截图；
- 第一次任务使用只读检查，不直接执行大范围修改；
- 重要修改前有 Git 分支或其他可回滚点；
- 当前版本的官方说明、登录方式和命令没有被旧教程替代。
八、结论
Codex 的 Windows“本地部署”可以拆成一条更可靠的路径：先检查 Node.js/npm，再选择可信安装方式；安装后用 codex –version 验证命令；登录时保护凭证；进入明确的项目目录；第一次先做只读检查；遇到问题按命令、PATH、网络、登录、目录权限的顺序排查。
最需要避免的误区，是把“客户端安装在本机”直接等同于“模型完全在本机离线运行”。写教程时把这两个概念分开，读者才不会在安装成功后对网络、账号或模型文件产生错误预期。
#Codex #本地部署 #开发工具 #命令行工具 #Windows开发环境
参考资料
- Codex CLI 官方 README：安装方式、启动方式和登录方式说明；核验日期：2026-09-16。
- 本机命令检查：node –version、npm –version、codex –version；核验日期：2026-09-16。
- 说明：本文中的版本号和命令选项可能随官方发布变化，发布前应再次打开官方文档核对。
