夜雨聆风winget 安装、Git/Python/Node.js 配置、config.toml 推荐模板、沙箱权限设置、基础验证流程，以及 WSL2 使用和常见问题排查。文末附官方资料入口；关注后回复「Codex」，可领取基础配置、常用提示词和科研项目 AGENTS.md 模板。本文更新于 2026 年 6 月 30 日。Codex 更新较快，安装前建议对照文末官方资料确认最新变化。
过去使用 AI 写代码，常见流程是把代码复制进聊天框、等待回答、再把修改复制回项目。遇到报错时，还要继续复制错误信息。
Codex 的工作方式不同：它可以直接读取项目文件、修改代码、运行命令、检查测试结果，并把修改内容交给你审核。
这篇教程将带你完成：
在 Windows 上安装 Codex App
登录并打开第一个项目
安装常用开发工具
配置安全的默认权限
验证 Codex 是否可以正常工作
解决常见安装问题
如果你只想尽快用起来，按照本文的 Windows App 主线操作即可。
一、Codex App、CLI 和 IDE 扩展应该选哪个？
Codex 提供多种使用方式：
本文以Codex Windows App为主，并在后面补充 WSL2 和 CLI 的安装方式。
如果你是科研代码、Linux 工具链或服务器环境重度用户，建议优先考虑 WSL2 或 CLI；如果你只是想先跑通 Codex 的完整体验，Windows App 是最低摩擦的入口。
二、安装前需要准备什么？
1. 系统要求
官方推荐使用 Windows 11。较新的 Windows 10 也可以使用，但稳定性可能不如 Windows 11。
建议提前确认系统中可以使用 winget：
winget --version如果命令能够输出版本号，说明 Windows 包管理器已经可用。
2. 登录方式
Codex 支持两种常见登录方式：
官方说明中，每个 ChatGPT 计划都包含 Codex。新手建议直接使用 ChatGPT 账号登录。API Key 更适合后续自动化、脚本或 CI/CD 场景。
不过，免费版 ChatGPT 的使用额度相对有限，而 Plus 订阅流程也让不少朋友感到困惑。对于订阅方式、支付渠道或 Codex 账号验证等问题还不太了解的朋友，欢迎点赞、关注并在评论区留言。后续我会专门整理一期ChatGPT Plus 订阅指南及Codex 常见账号验证问题排查教程，把流程和注意事项讲清楚。
注意：使用 API Key 登录时，Codex 按 OpenAI Platform API 计费，不使用 ChatGPT 套餐内的 Codex 权益。
3. 推荐安装的开发工具
Codex 本身可以安装并启动，但如果缺少 Git、Python 或 Node.js，很多项目任务无法完整运行。
推荐至少安装：
winget install --id Git.Gitwinget install --id OpenJS.NodeJS.LTSwinget install --id Python.Python.3.14
如果你需要 GitHub 或 Windows 原生开发功能，还可以安装：
winget install --id Microsoft.DotNet.SDK.10winget install --id GitHub.cligh auth login
安装后重新打开终端，分别检查：
git --versionnode --versionpython --versiongh --version
三、安装 Codex Windows App
方法一：Microsoft Store 安装
Microsoft Store 有时候打开会很卡，可以直接在浏览器搜索codex，然后找到Microsoft Store的官方下载链接（注意一定要找官方下载链接）：
打开官方 Codex Windows App 下载页面：
点击下载 Codex Windows App 即可，下载完成之后找到你下载的安装包，按照 Microsoft Store 的提示完成安装即可。
方法二：使用 winget 安装
打开 PowerShell 或 Windows Terminal，运行：
winget install Codex -s msstore安装完成后，在 Windows 开始菜单中搜索并打开 Codex。
四、登录并打开第一个项目
第一次启动 Codex 时，按照界面提示使用 ChatGPT 账号或 API Key 登录。
想要接入第三方api的用户，为了跳过手机号验证，可以在“使用其他方式登录”里面选择用 API Key 登录，登录进去之后再利用其他工具（如CC Switch、ccx、Codex++、EchoBirds等）切换到第三方的api即可。
Open ai的API Key可以在platform.openai.com注册，点进去登录之后在最左边找到 API Key即可申请，很简单，不用充值，后续切换到自己的api key就可以。第一次点击platform.openai.com会提示需要登录。这个登录很简单，随便找个邮箱都可以登录，QQ邮箱都可以。
使用 ChatGPT 登录时，Codex 会打开浏览器完成授权。登录完成后，返回 Codex App 即可。
接下来创建一个专门用于测试的文件夹，例如：
New-Item -ItemType Directory -Path ”$HOME\Desktop\codex-demo”Set-Location ”$HOME\Desktop\codex-demo”git init
在 Codex App 中选择Add new project，打开刚刚创建的 codex-demo 文件夹。
第一次测试时，不要直接打开包含重要数据、未备份代码或敏感信息的项目。
五、设置安全的默认权限
Codex 可以读取文件、修改代码并运行命令，因此权限配置非常重要。
新手建议使用：
沙箱模式：仅允许写入当前工作区
审批策略：需要额外权限时询问
不要直接开启 Full Access
Codex 的用户级配置文件一般位于：
C:\Users\<你的用户名>\.codex\.codex\config.toml可以从 Codex 设置中打开配置文件，也可以手动创建。推荐的基础配置如下：
approval_policy = ”on-request”sandbox_mode = ”workspace-write”web_search = ”cached”model_reasoning_effort = ”high”[windows]sandbox = ”elevated”
配置含义：
approval_policy = "on-request" | |
sandbox_mode = "workspace-write" | |
web_search = "cached" | |
model_reasoning_effort = "high" | |
[windows] sandbox = "elevated" |
如果你想固定当前官方推荐模型，可以额外加入：
model = ”gpt-5.5”如果你不确定模型选择，建议先不要写 model，让 Codex 使用默认推荐模型。轻量任务或子代理任务可以考虑 gpt-5.4-mini，但第一篇新手教程不建议展开太多模型选择细节。
如果你的设备无法完成管理员批准的沙箱设置，可以暂时改为：
[windows]sandbox = ”unelevated”
unelevated 是兼容性方案，隔离能力弱于 elevated。
如果遇到反复弹出的codex-windows-sandbox-setup.exe“找不到指定的模块”，可以参考我的上一篇推文，里面详细讲解了怎么解决这个问题。
安全提醒：不要为了减少确认弹窗，直接使用
danger-full-access或--yolo。这些模式会显著扩大 Codex 可以操作的范围。
另一个容易忽略的点：Codex 会缓存登录信息。文件型缓存通常位于 ~/.codex/auth.json 或系统凭据存储中。不要把这个文件提交到 Git，也不要截图或发给别人。
六、验证 Codex 是否安装成功
打开测试项目后，先发送一个只读任务：
请检查当前项目目录，告诉我：1. 当前有哪些文件2. 是否已经初始化 Git3. 当前环境能否使用 Python、Node.js 和 Git4. 不要修改任何文件
如果 Codex 可以正确列出目录并检查工具版本，说明基础环境已经可用。
接着让它创建一个测试文件：
请创建 README.md，写明这是一个 Codex 测试项目。完成后告诉我修改了哪些文件，不要执行其他操作。
检查文件确实生成后，再让 Codex 删除这个测试文件，或者保留它用于下一篇使用教程。
如果你使用 CLI，可以运行以下命令检查安装和环境：
codex --versioncodex doctor --summary
codex doctor 会检查安装、配置、登录、运行环境、Git 和终端等常见问题。
如果你使用 Codex CLI，也可以用下面这个低风险启动方式：
codex --sandbox workspace-write --ask-for-approval on-request含义是：允许 Codex 修改当前工作区，但需要额外权限时先询问你。
七、可选：在 WSL2 中使用 Codex CLI
如果你的研究代码主要运行在 Linux、服务器或容器环境中，WSL2 通常更合适。
1. 安装 WSL2
使用管理员权限打开 PowerShell：
wsl --installwsl
2. 在 WSL2 中安装 Codex CLI
进入 WSL2 终端后运行：
curl -fsSL https://chatgpt.com/codex/install.sh | shcodex
建议把项目放在 Linux 主目录中，例如：
mkdir -p ~/codecd ~/code
相比 /mnt/c/...，Linux 主目录通常具有更好的文件读写性能，也更少遇到权限和软链接问题。
需要注意：Windows App 默认使用 %USERPROFILE%\.codex，WSL2 CLI 默认使用 Linux 中的 ~/.codex。两者不会自动共享配置、登录状态和会话记录。
如果你希望 Windows App 的 agent 本身运行在 WSL2 中，可以在 Codex App 设置里把 agent 从 Windows native 切换到 WSL，然后重启 App。注意：集成终端和 agent 环境是两个独立设置，可以一个用 PowerShell、另一个用 WSL。
八、常见问题与解决方法
1. PowerShell 提示 npm.ps1 cannot be loaded
这通常是 PowerShell 执行策略阻止脚本运行。
在理解执行策略影响后，可以为当前用户设置：
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned修改后重新打开终端。
2. Codex 找不到 Git
安装 Git：
winget install --id Git.Git安装完成后重新启动 Codex，再运行：
git --version3. Codex 无法读取某个目录
先确认目录确实存在。如果你使用 Windows CLI，可以在当前会话中授予额外的只读访问：
/sandbox-add-read-dir C:\需要读取的目录不要为了读取一个目录而直接开启完全访问权限。
4. 浏览器登录无法完成
远程机器或无图形界面的环境可以尝试设备码登录：
codex login --device-auth如果设备码登录不可用，也可以在有浏览器的机器完成登录后，把认证缓存复制到可信的远程机器。但认证缓存等同于敏感凭据，只能用于你信任的私有环境。
5. 配置修改后没有生效
确认编辑的是正确的配置文件：
%USERPROFILE%\.codex\config.toml修改后重新启动 Codex 或新建会话。项目中的 .codex/config.toml 也可能覆盖用户级配置。
九、安装完成后，下一步做什么？
完成安装只是第一步。真正决定 Codex 是否好用的，是你能否给它明确任务，并让它在修改后主动检查结果。
建议下一步完成三个动作：
用 Codex 阅读一个真实项目并解释结构
在项目根目录创建 AGENTS.md
让 Codex 修改一个小功能、运行测试并审查差异
感兴趣的朋友可以关注一下，后续会出教程完整演示这套工作流。
关注后回复「Codex」，获取基础配置模板、常用提示词和科研项目
AGENTS.md模板。
