安装登录与第一次任务：提问、修 Bug、评审、提交

你将得到什么

• 一个能在终端直接运行的 codex 命令，并用 codex --version、codex login status、codex doctor 验证
• 已登录的 Codex（ChatGPT 账号或 OpenAI API Key 二选一）
• 一个练习用的 Python 小项目，以及 Codex 帮你读代码、修 Bug、跑测试、自我评审、提交 Git 的完整一轮

开始前准备

• 账号（二选一）：
  • ChatGPT Plus / Pro / Business / Edu / Enterprise 订阅：用「Sign in with ChatGPT」登录，用量计入套餐额度。官方定价页写明 Codex CLI 属于 Plus 起的权益；Free / Go 目前只在桌面 App 中提供 GPT-6 Luna。
  • OpenAI API Key：按标准 API 价格计费，适合脚本与 CI；云端功能（GitHub 代码评审、Slack 等）不可用。
• 地区：需位于 OpenAI 支持的国家和地区，列表见 https://developers.openai.com/api/docs/supported-countries （2026-10-07 核对，中国大陆与香港不在列表中）。
• 系统：macOS、Linux，或 Windows（原生 PowerShell 或 WSL2；官方说明自 0.115 起 WSL1 不再受支持）。
• 工具：git 与 python3。本课练习只用 Python 自带的 unittest，无需安装依赖。

核心事实（先记住）

步骤 1：安装 Codex CLI

官方推荐用独立安装脚本（standalone installer）。按你的系统任选其一。

macOS、Linux、WSL2：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows：在新打开的 PowerShell 窗口中执行（行尾的反引号是 PowerShell 换行符，整段一起粘贴）：

powershell -ExecutionPolicy ByPass `
  -c "irm https://chatgpt.com/codex/install.ps1 | iex"

安装脚本默认从 releases.openai.com 下载，取不到时会回退到 GitHub Releases。

其他安装方式（可选）

npm：

npm install -g @openai/codex

macOS Homebrew：

brew install --cask codex

更新时：脚本安装重新运行同一条安装命令；npm 再执行一次 npm install -g @openai/codex；Homebrew 用 brew upgrade --cask codex。

步骤 2：验证安装

安装结束后，新开一个终端窗口再执行：

codex --version

对照结果：打印 Codex CLI 的版本号（2026-10-07 官方最新为 0.160.1，以你本机为准）。

再做一次诊断：

codex doctor --summary

对照结果：按「安装、配置、认证、运行时、Git、终端」等分组列出检查项，末尾给出通过 / 警告 / 失败的计数。此时「认证」一项报未登录是正常的，下一步解决。

如果提示 codex: command not found，说明安装目录还不在 PATH 中：先重开终端；npm 安装的话，确认 npm prefix -g 下的 bin 目录在 PATH 里。

步骤 3：登录

方式 A：用 ChatGPT 账号登录（订阅用户推荐）

codex login

对照结果：浏览器自动打开 ChatGPT 登录页，完成后终端提示登录成功。

在远程服务器、SSH 会话等没有浏览器的环境里，改用设备码登录（Beta，需先在 ChatGPT 安全设置中开启设备码登录）：

codex login --device-auth

终端会给出一个链接和一次性代码，在任意有浏览器的设备上打开链接、登录并输入代码即可。

方式 B：用 API Key 登录（按量计费）

先在 OpenAI 后台创建 Key，再通过标准输入交给 Codex，避免 Key 出现在命令历史里：

export OPENAI_API_KEY="sk-...你的 Key..."
printenv OPENAI_API_KEY | codex login --with-api-key

确认登录状态

codex login status
echo $?

对照结果：第一行显示当前认证方式（ChatGPT 或 API Key），echo $? 打印 0。

凭据默认缓存在 ~/.codex/auth.json 或系统凭据库中。官方提醒：把 auth.json 当密码对待，不要提交到 Git、不要贴到工单或聊天里。要退出登录执行 codex logout。

步骤 4：准备一个练习项目

为了让后续每一步都有确定的对照结果，先建一个带「已知 Bug」的两文件 Python 项目：

mkdir -p ~/kun-codex-demo && cd ~/kun-codex-demo
git init -q
cat > calc.py <<'PY'
def average(nums):
    return sum(nums) / len(nums)
PY
cat > test_calc.py <<'PY'
import unittest
from calc import average


class TestAverage(unittest.TestCase):
    def test_basic(self):
        self.assertEqual(average([2, 4, 6]), 4)

    def test_empty(self):
        self.assertEqual(average([]), 0)


if __name__ == "__main__":
    unittest.main()
PY
git add . && git commit -qm "init demo"
python3 -m unittest

对照结果（节选）：空列表那条测试报错，这正是要让 Codex 修的 Bug。

ZeroDivisionError: division by zero
----------------------------------------------------------------------
Ran 2 tests in 0.001s

FAILED (errors=1)

官方最佳实践建议：每次任务前后都留一个 Git 检查点，需要时可以回滚。上面的 init demo 就是第一个检查点。下一课的 codex exec 也要求在 Git 仓库中运行，以防误改。

步骤 5：启动会话并认识界面

在项目目录启动 Codex：

cd ~/kun-codex-demo
codex

对照结果：首次在某个目录启动时，Codex 可能先询问是否信任该目录（版本控制下的目录默认用 Auto 权限）。进入后，欢迎框显示 当前模型和工作目录（应为 ~/kun-codex-demo），下方提示 /init、/status、/permissions、/model、/review 等命令。

输入：

/status

对照结果：显示当前会话 ID、模型、审批策略（approval policy）、可写目录（writable roots）与剩余上下文。可写目录应只包含 ~/kun-codex-demo。

步骤 6：先提问，再修 Bug

先让它理解项目（直接粘贴到输入框，回车发送）：

Tell me about this project

对照结果：Codex 自行读取 calc.py 和 test_calc.py，说明这是一个只有 average() 函数和两条单元测试的小项目，通常还会指出空列表会触发除零错误。

接着让它修复（中文提问同样可以）：

Fix the failing test with a minimal change, then rerun the tests

对照结果：

• 你能在终端实时看到它执行的命令（python3 -m unittest）和 calc.py 的 diff
• 在默认 Auto 权限下，这些都在工作区内，不需要你逐条批准
• 修改后 average([]) 返回 0，第二次运行测试输出 OK

几个顺手的操作：

• 输入 @ 可搜索文件并把路径插入提示词
• 以 ! 开头的一行会在当前沙箱和审批设置下直接跑 shell 命令，例如 !git status
• Codex 正在工作时按 Enter 可插入新指令纠偏，按 Tab 则把下一条指令排队

步骤 7：看改动、让它自我评审、提交

查看 Git 改动：

/diff

对照结果：显示已暂存、未暂存和未跟踪的改动，此处应只有 calc.py 多出一个空列表判断。

再让 Codex 做一次本地代码评审：

/review

在弹出的预设中选择 Review uncommitted changes。对照结果：Codex 按优先级列出发现的问题（如有），不会修改你的工作区。

最后让它提交：

commit my changes with a descriptive message

对照结果：默认沙箱把 .git 目录设为只读，写入提交属于越界操作，Codex 会先请求批准，你确认后才会提交。输入 /exit 退出后自行核对：

git log --oneline -2
python3 -m unittest

应看到两条提交（最新一条是 Codex 写的说明），测试输出 OK。

权限：Auto、Read Only 与「危险全开」

Codex 的边界由两样东西决定：沙箱模式（技术上能写哪里、能否联网）和审批策略（什么时候必须停下来问你）。官方常用组合：

• Auto 等价于 --sandbox workspace-write --ask-for-approval on-request：工作区内可读写和跑命令，改工作区外的文件或联网前要批准。
• 会话中输入 /permissions 可随时在 Auto 与 Read Only 之间切换。
• --yolo 是 --dangerously-bypass-approvals-and-sandbox 的别名，官方只建议在专用沙箱虚拟机里使用。
• 需要额外可写目录时，优先用 --add-dir <路径>，而不是放开整个沙箱。
• 旧配置里的 approval_policy = "untrusted" 已退役，需按官方迁移说明改写。

常用命令速查

终端命令（在 shell 中运行）：

会话命令（在 Codex 里输入）：

本课检查清单

• codex --version 能打印版本号，codex doctor --summary 没有失败项
• codex login status 退出码为 0
• 已在 ~/kun-codex-demo 完成一次提问、一次修 Bug、一次 /review、一次提交
• 知道用 /permissions 切换 Auto 与 Read Only

常见问题

型号提醒：官方公告 GPT-5.5 将于 2026-10-14 从 ChatGPT 登录的 Codex 中退役，gpt-5.4 系列已于 8-31 退役。脚本或配置里若写死了旧型号，请换成 gpt-6.1-sol 或 gpt-6-sol。

下一课：用 /init 生成 AGENTS.md 让 Codex 记住项目规矩，再用 codex exec 把它接进脚本与 CI。