Codex CLI 上手指南

一句话结论：装 CLI 只有一句话的事（npm install -g @openai/codex），真正值得花时间的是三件事：选对安装渠道、配好认证、学会用 worktree 并行。本文基于 0.154.0 稳定版（2026-09-09 发布），于 2026-09-16 实测更新。

一、安装渠道对比

渠道	命令	适合
npm	npm install -g @openai/codex	已有 Node.js 22+ 环境（最通用）
macOS 脚本	curl -fsSL https://chatgpt.com/codex/install.sh | sh	Mac 快速安装
Homebrew	brew install --cask codex	Mac 统一包管理
Windows	irm https://chatgpt.com/codex/install.ps1 | iex	Windows 原生
手动下载	GitHub Releases 二进制	无网/内网环境

安装脚本默认从 releases.openai.com 下载，失败时自动回退 GitHub Releases。

版本锁定建议：生产环境锁定稳定版（当前 0.154.x）。alpha 通道（0.155.0-alpha.x）几乎每日发版，与稳定版的会话数据可能不兼容，不要混装。

二、认证配置

两种方式：

1. ChatGPT 账号（推荐）：运行 codex → 选 "Sign in with ChatGPT" → 浏览器授权。Plus / Pro / Business 额度直接生效。
2. API key：按 token 计费，与订阅额度独立。适合 CI 流水线等无人值守场景，配置步骤见SDK 与自动化集成。

三、worktree 并行会话（0.154 实验特性）

这是本月最值得开发的工程能力：为每个会话创建隔离的 git checkout，多任务互不踩脚。

# 以隔离 worktree 启动新会话
codex --worktree "升级全部测试依赖到最新大版本"

# 会话中创建 / fork
/worktree

跑完后可以浏览、恢复各个 worktree 再决定合并哪个。典型用法：一个会话修 bug、一个写功能、一个跑依赖升级，三者互不干扰。

四、常用命令速查

codex                      # 交互模式（首次运行会引导登录）
codex "任务描述"           # 单任务直接执行
codex app                  # 桌面应用体验
/worktree                  # 会话内创建隔离工作区
/copy                      # 复制状态输出或会话字段

0.154 起会话内支持内联提问：Codex 工作时直接输入问题或从建议选项里选，不丢主草稿、不打断任务。

五、Windows 开发者注意

0.154 起 Windows 会话可共享后台 Codex 服务（daemon），带生命周期管理命令和托管更新。配合 PowerShell 安装脚本，Windows 已从"能用"进入"好用"区间；Vim 模式也补齐了 R replace 与 undo/dot-repeat。

常见问题 FAQ

Q1：升级到 0.154 有破坏性变更吗？ A：Python SDK 侧有（HookMetadata 的 handler 移到 .root 下），纯 CLI 用户无感。SDK 细节见SDK 与自动化集成。

Q2：IDE 扩展和 CLI 冲突吗？ A：不冲突，登录状态与额度共享，可同时使用。扩展支持 VS Code / Cursor / Windsurf。

Q3：没登录能跑吗？ A：不能。CLI 所有能力都在认证之后，先完成注册与登录。

更新时间

本文最后更新：2026-09-16 · 下次更新：2026-10-01