主流 Agent 入门教程 / Codex
2. 安装Codex CLI并完成登录
原文备份 · 第 3 / 27 篇 · 查看极客时间原知识库 ↗
本篇目录 · 34 节
来源：Codex
预计阅读时间：25 分钟
本篇目标：在 Windows、macOS 或 Linux 上安装 Codex CLI，完成登录，并在一个安全的练习目录中成功启动。
这一篇会涉及不少终端命令，但不要求你有丰富的命令行经验。每一步都会告诉你在哪里操作、输入什么，以及成功后应该看到什么。
如果你的电脑由公司统一管理，安装软件、执行脚本或浏览器登录可能受到限制。遇到权限或网络策略提示时，不要反复绕过限制，先确认公司的使用规则。
一、安装之前准备什么
开始前，请确认你具备下面几个条件：
- 一台运行 Windows、macOS 或 Linux 的电脑；
- 可以打开终端或 PowerShell；
- 可以访问 ChatGPT 登录页面；
- 一个可以使用 Codex 的 ChatGPT 账号，或者一个 OpenAI API Key；
- 一个专门用于练习的空目录。
Codex CLI 的官方独立安装脚本会安装可直接运行的 codex 命令，不要求你为了安装 CLI 而单独准备 Node.js。
二、在 macOS 上安装
第 1 步：打开终端
按下 Command + 空格，输入“终端”或“Terminal”，按回车打开。
你会看到一行等待输入的提示符，末尾通常是 % 或 $。
第 2 步：运行安装命令
复制下面这条命令，粘贴到终端，然后按回车：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
安装脚本会下载 Codex，并把可执行命令放到用户级安装目录。按照终端里的提示完成安装。
第 3 步：检查安装结果
输入：
codex --version
如果安装成功，终端会输出 Codex CLI 的版本号。
如果出现 command not found: codex，先完全关闭终端，再重新打开一个终端窗口，然后再次运行 codex --version。安装程序可能刚刚更新了 PATH，而旧终端还没有重新加载。
仍然找不到命令时，可以运行：
command -v codex
正常情况下，它会输出 codex 所在的完整路径，你可以复制这条完整路径到命令行，然后再按回车。
三、在 Linux 上安装
Codex 在 Linux 上使用 Bubblewrap 和 Seccomp 提供本地沙箱能力。不同发行版的安装命令略有差异。
第 1 步：安装 Bubblewrap
Ubuntu 或 Debian 用户可以运行：
sudo apt update
sudo apt install -y bubblewrap
Fedora 用户可以运行：
sudo dnf install bubblewrap
Arch Linux 用户可以运行：
sudo pacman -S bubblewrap
如果系统提示找不到软件包，请查询当前发行版的软件仓库，确认对应包名。容器或裁剪过的 Linux 环境还可能缺少 Codex 沙箱所需的命名空间或 Seccomp 能力。
第 2 步：安装 Codex CLI
运行：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
按照安装脚本的提示完成安装。
第 3 步：验证版本
运行：
codex --version
看到版本号就说明安装成功。
如果提示找不到命令，关闭当前终端并重新打开。仍然无效时，运行 command -v codex 检查完整路径。
四、在 Windows 上安装
Windows 用户可以选择原生安装，也可以在 WSL2 中安装。
如果你的项目和开发工具都在 Windows 中，先使用原生安装。如果你平时已经把代码、Git 和开发环境放在 WSL2 中，就在 WSL2 内安装 Codex。
不要在两个环境中来回混用同一个项目路径。例如，你在 WSL2 中使用 Codex 时，项目最好放在 Linux 主目录下，而不是长期放在 /mnt/c 中。
方式一：在 Windows 原生环境中安装
第 1 步：打开 PowerShell
点击开始菜单，搜索“PowerShell”，打开 Windows PowerShell 或 PowerShell 7。
普通用户权限通常足以完成用户级安装；除非安装程序明确要求，否则不必以管理员身份运行。
第 2 步：运行安装命令
在 PowerShell 中输入：
irm https://chatgpt.com/codex/install.ps1 | iex
按照窗口中的提示完成安装。
第 3 步：检查版本
关闭当前 PowerShell 窗口，重新打开一个 PowerShell，然后运行：
codex --version
如果成功，屏幕会显示 Codex CLI 的版本号。
如果出现“无法将 codex 识别为 cmdlet、函数、脚本文件或可运行程序”，运行：
Get-Command codex
如果依然找不到，重新运行安装脚本，并注意它是否提示你重新打开终端或添加 PATH。
方式二：在 WSL2 中安装
适合下面这些情况：
- 你的代码本来就放在 WSL2 中；
- 你依赖 Linux 工具链；
- 团队开发环境以 Linux 为主。
先用管理员身份打开 PowerShell，运行：
wsl --install
按照系统提示完成安装并重启电脑。重启后打开 WSL 终端，先确认当前确实处于 WSL：
echo $WSL_DISTRO_NAME
如果输出类似 Ubuntu 的发行版名称，说明你已经进入 WSL。
接着安装 Bubblewrap 和 Codex：
sudo apt update
sudo apt install -y bubblewrap
curl -fsSL https://chatgpt.com/codex/install.sh | sh
最后运行：
codex --version
从 Codex 0.115 开始，Linux 沙箱依赖 Bubblewrap，WSL1 不再受支持。Windows 用户应使用 WSL2。
五、使用 ChatGPT 账号登录
对于个人学习和日常交互使用，如果你的 ChatGPT 订阅包含 Codex，优先使用 ChatGPT 账号登录。
在终端或 PowerShell 中运行：
codex login
接下来通常会发生这些事情：
- Codex 在浏览器中打开登录页面。
- 你登录自己的 ChatGPT 账号。
- 如果账号属于多个工作空间，选择要使用的工作空间。
- 浏览器显示登录完成。
- 回到终端，Codex 显示登录成功。
登录后运行：
codex login status
这条命令会显示当前是否已经登录，以及正在使用的身份验证方式。
浏览器没有自动打开怎么办
查看终端是否打印了一个登录地址。复制该地址，在浏览器中手动打开。
如果你在服务器、SSH 或没有图形界面的环境中使用 Codex，可以尝试设备代码登录：
codex login --device-auth
终端会显示一个网址和一次性代码。在另一台能够打开浏览器的设备上访问该网址，登录后输入代码。
设备代码登录是否可用，还取决于个人账号设置或工作空间管理员的配置。
六、使用 OpenAI API Key 登录
API Key 登录与 ChatGPT 订阅登录使用不同的计费方式。使用 API Key 时，费用计入 OpenAI Platform 账户，并按 API 实际用量结算。
先从 OpenAI Platform 创建 API Key。不要把密钥直接写进教程文件、代码仓库或聊天记录。
macOS 和 Linux
在当前终端会话中设置环境变量：
export OPENAI_API_KEY="请替换为你的API-Key"
然后通过标准输入完成登录：
printenv OPENAI_API_KEY | codex login --with-api-key
Windows PowerShell
在当前 PowerShell 会话中设置环境变量：
$env:OPENAI_API_KEY = "请替换为你的API-Key"
然后运行：
$env:OPENAI_API_KEY | codex login --with-api-key
完成后运行：
codex login status
确认 Codex 正在使用 API Key 身份验证。
上面的环境变量只对当前终端窗口有效，关闭窗口后就会消失。长期保存密钥时，优先使用操作系统的凭据管理工具或团队规定的密钥管理方案。
七、ChatGPT 登录和 API Key 登录怎么选
| 情况 | 更合适的方式 |
|---|---|
| 已有包含 Codex 的 ChatGPT 订阅，主要进行人工交互 | ChatGPT 登录 |
| 需要把 Codex 放进脚本或 CI | API Key |
| 需要使用 ChatGPT 工作空间权限和相关服务 | ChatGPT 登录 |
| 希望用 API 账户单独统计和控制费用 | API Key |
API Key 登录时，部分依赖 ChatGPT 工作空间或云服务的功能可能受到限制。教程主线默认使用 ChatGPT 登录；第三篇会讲怎样配置其他 Provider，以及如何切换回来。
八、创建专门的练习目录
不要一开始就在桌面、下载目录或存放重要项目的目录中练习。
macOS、Linux 或 WSL2
运行：
mkdir -p ~/codex-course/taskflow
cd ~/codex-course/taskflow
然后检查当前位置：
pwd
输出路径的末尾应该是 codex-course/taskflow。
Windows PowerShell
运行：
New-Item -ItemType Directory -Force "$HOME\codex-course\taskflow"
Set-Location "$HOME\codex-course\taskflow"
然后检查当前位置：
Get-Location
输出路径的末尾应该是 codex-course\taskflow。
九、第一次启动 Codex
确保终端当前位于刚才创建的 taskflow 目录，然后运行：
codex
第一次进入某个目录时，Codex 可能会询问你是否信任这个工作目录。此处是我们刚创建的空目录，可以按界面提示信任它。
进入交互界面后，先输入：
请告诉我当前工作目录中有哪些文件。不要创建或修改任何文件。
因为目录还是空的，Codex 应该告诉你没有可处理的项目文件，或者只列出系统自动生成的隐藏内容。它不应该创建新文件。
接着输入：
/status
检查当前模型、工作目录、权限策略和上下文状态。不同版本的排版可能不同，但你应该能够找到这些核心信息。
十、更新 Codex CLI
先查看当前版本：
codex --version
支持自更新的正式版本可以运行：
codex update
更新完成后再次运行 codex --version，确认版本发生变化。
如果当前安装方式不支持自更新，命令会提示你重新运行安装程序。此时使用本篇对应操作系统的官方安装命令即可。
十一、常见问题
1. 安装后提示找不到 codex
先关闭终端并重新打开，再运行 codex --version。如果仍然失败：
- macOS、Linux、WSL2：运行
command -v codex； - Windows PowerShell：运行
Get-Command codex。
没有输出通常说明安装没有完成，或者安装目录没有加入 PATH。
2. 登录后终端一直没有反应
先确认浏览器是否显示登录成功，再回到启动登录的那个终端窗口。如果网络阻止本地回调，可以改用：
codex login --device-auth
3. 登录了错误的账号
运行：
codex logout
codex login
第二次登录时，确认浏览器中选择了正确的账号和工作空间。
4. WSL 中运行很慢
检查项目是否放在 /mnt/c 等 Windows 挂载目录中。长期开发项目建议放在 WSL 的 Linux 主目录，例如 ~/code 或本教程的 ~/codex-course。
5. 公司电脑无法执行安装脚本
这通常是终端执行策略、软件安装策略、网络代理或证书配置造成的。记录终端中的完整错误信息，联系管理员确认允许的安装方式。不要为了安装 Codex 长期关闭系统安全策略。
十二、本篇完成检查
继续下一篇之前，请确认下面几项都已经完成：
codex --version能显示版本号；codex login status能显示有效登录状态；- 已经创建独立的
taskflow练习目录； - 能够从该目录启动
codex； /status中显示的工作目录正确；- Codex 能读取目录，但没有在未授权的情况下创建文件。
下一篇，我们会配置第三方模型 API 和中转平台，并建立几套可以随时切换的 Provider 配置。