2 Codex 安装、登录与环境诊断：先让本地跑起来

查看大图

学 Codex 的第一步不是写 prompt，而是把环境跑稳。很多“AI 不会改代码”的问题，最后发现是工作目录不对、Git 没装好、终端权限不对、Node 或 Python 不在 PATH 里。

这一篇只做三件事：安装入口、登录方式、诊断环境。

安装成功只说明命令能运行，不说明它能在你的仓库里稳定工作。我会先确认登录状态、模型权限、仓库路径、依赖命令，再让它做一次只读检查。

查看大图

如果这一步跳过，后面报错时很容易分不清是 Codex 没理解任务，还是本地环境根本没跑通。把环境诊断写进第一篇实操，比多背几个命令更有用。

Windows 用户怎么开始

如果你用 Windows，官方 Windows 文档推荐从 Microsoft Store 下载 Codex App。命令行安装也可以用：

查看大图

做 Codex 安装和环境诊断时，先保存版本、登录、项目目录和可运行命令这些证据。后面遇到失败，才能判断是环境问题还是任务本身不清楚。

winget install Codex -s msstore

Codex App 在 Windows 上可以用 PowerShell 原生运行，也可以配置为在 WSL2 里运行。我的建议是：

• 项目在 Windows 文件系统里，先用 PowerShell。
• 项目本来就在 Linux/WSL 环境，或者依赖 Docker、Linux 工具链，再考虑 WSL2。
• 不要频繁在 PowerShell、Git Bash、WSL 之间来回切，同一个项目固定一个主要环境。

Windows 下还要确认 Git、Node、Python、GitHub CLI 这些基础工具是否可用。官方 Windows 文档也给了 winget install --id Git.Git、OpenJS.NodeJS.LTS、GitHub.cli 等基础安装建议。

CLI 入口要会用

装好以后，在项目根目录运行：

查看大图

看完《Codex 安装、登录与环境诊断：先让本地跑起来》后，建议用一分钟复盘：关键概念是否分清、练习步骤是否可复现、结论能不能换成自己的话。

codex

这会启动交互式终端 UI。你也可以直接带一句任务：

codex "先不要修改代码，解释这个项目的目录结构"

如果你装了 Codex App，可以用：

codex app

在 macOS 上它可以直接打开指定 workspace；在 Windows 上，官方 CLI reference 说明它会打开或引导安装桌面 App，并打印要打开的路径。

登录方式

Codex 支持用 ChatGPT 账号，也支持用 OpenAI API key。官方 pricing/manual 里也提醒：用 API key 时，某些 cloud-based 功能可能不可用。个人用户通常优先用 ChatGPT 账号登录；CI、自动化、共享环境再考虑 API key。

常用命令：

codex login
codex logout

不要把 API key 写进仓库，也不要贴进文章、日志或公开 issue。CI 里要放到 GitHub secrets 这类密钥管理位置。

用 doctor 先做体检

遇到问题前，先记住这个命令：

codex doctor

官方 CLI reference 里说明，codex doctor 会检查安装、配置、认证、运行时、Git、终端、app-server 和 thread inventory。它很适合用来排查“为什么 Codex 读不到项目”“为什么权限不对”“为什么登录状态异常”。

如果你以后向别人求助，先贴 codex doctor --summary 的摘要，比只说“不能用”有效得多。当然，涉及路径、账号、token 的敏感内容要先处理。

新手环境检查清单

第一次开始前，至少检查：

查看大图

如果想把《Codex 安装、登录与环境诊断：先让本地跑起来》用到自己的任务里，可以先缩小场景，只验证一个最关键的判断点。

查看大图

学完《Codex 安装、登录与环境诊断：先让本地跑起来》后，不妨换一个自己的场景试一次，重点观察输入、处理和输出是否能对应起来。

git --version
node --version
python --version
codex doctor --summary

如果项目是前端，再跑项目自己的安装和构建命令；如果是后端，先确认虚拟环境和测试命令。

下一篇开始进入真实仓库：让 Codex 先读代码，再做第一次低风险改动。

参考资料：

• Codex quickstart
• Codex CLI reference
• Codex for Windows