Codex CLI 全平台安装

Codex CLI 是 OpenAI 的终端编程代理，可在本地项目中阅读代码、修改文件和执行命令。大多数用户使用原生安装器即可，不需要先安装 Node.js。

1. 官方安装

1.1 macOS、Linux 与 WSL

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

无人值守环境可使用：

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

1.2 Windows PowerShell

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

也可以通过 WinGet 安装：

winget install OpenAI.CodexCLI

项目依赖 Linux 工具链或 bash 脚本时，优先在 WSL 2 中安装和使用。

2. 验证环境

codex --version
codex doctor

codex doctor 可检查安装、认证、配置和运行环境，遇到 PATH、登录或网络异常时优先运行。

3. 登录与认证

3.1 ChatGPT 登录

首次运行即可开始登录：

codex

也可以显式登录：

codex login

远程或无浏览器环境使用设备授权：

codex login --device-auth

3.2 API Key

API Key 适合按量计费、脚本和 CI：

codex login --api-key

自动化任务中可通过环境变量调用：

CODEX_API_KEY=sk-xxxxxxxx codex exec "检查项目并给出改进建议"

真实密钥只能放在本机安全的环境变量或密钥管理系统中。

4. 常用命令

codex                    # 启动交互式会话
codex "解释这个项目的目录结构"
codex doctor             # 诊断环境
codex resume             # 恢复历史会话
codex logout             # 移除本地认证
codex exec "..."         # 非交互执行任务

日常使用建议保留默认权限模式。只有在明确理解风险、且当前目录不含敏感文件时，才考虑在全局配置中调整审批策略和沙箱模式；更稳妥的做法是仅为单次任务临时覆盖。

5. npm 与受限网络备用方案

只有需要 npm 工作流或官方安装器无法稳定下载时，才使用 npm：

npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex

正确包名是 @openai/codex。如已误装无关的 codex 包，先卸载后重新安装：

npm uninstall -g codex
npm install -g @openai/codex

没有 Node.js 时，可先安装 fnm：

curl -fsSL https://fnm.vercel.app/install | bash
fnm install --lts
fnm use lts-latest

6. 项目指令与配置

Codex 会读取项目根目录的 AGENTS.md，用于保存项目约定、测试命令和不能修改的边界。一个最小示例：

# AGENTS.md

## 项目约定
- 使用 TypeScript strict 模式
- 测试框架：Vitest

## 禁止操作
- 不要修改 src/legacy/ 目录

全局配置文件位于 ~/.codex/config.toml，可配置模型、审批策略和 MCP 服务。

6.1 临时使用 full access

如果确实需要 full access，编辑全局配置文件 ~/.codex/config.toml，在文件顶部添加：

approval_policy = "never"
sandbox_mode = "danger-full-access"

保存后重新启动 Codex，新会话会默认使用 full access：不再请求审批，并允许命令访问完整文件系统。Windows 用户可在 PowerShell 中打开同一路径下的文件：

notepad $HOME\.codex\config.toml

macOS、Linux 或 WSL 可使用：

mkdir -p ~/.codex
nano ~/.codex/config.toml

启动会话后，可运行 codex doctor 检查配置是否被读取；也可以在单次运行时用命令行参数临时覆盖全局设置。

任务完成后建议删除这两项，恢复默认审批和沙箱设置。不要在包含密钥、生产数据或个人文件的目录中长期启用 full access。

7. 使用 STJAPI 与 CC Switch

需要多供应商切换时，请先完成 Codex 安装和登录，再根据 CC Switch 对接 STJAPI 导入 STJAPI 令牌。使用 GPT 模型时无需开启路由；保存后在终端运行 codex 验证配置。

8. 更新与故障排查

8.1 更新

codex update
# 或 npm 用户
npm install -g @openai/codex@latest

8.2 codex: command not found

重开终端并运行 codex doctor。npm 用户还应检查 npm config get prefix 指向的 bin 目录是否在 PATH 中。

8.3 浏览器登录未完成

远程机器使用 codex login --device-auth，或通过 codex login --api-key 使用 API Key。

8.4 模型繁忙

出现容量提示时，进入 Codex 模型繁忙处理 查看重试方法。

9. 官方资料

• Codex CLI 文档
• Codex 认证
• Codex 配置
• Codex AGENTS.md 指南

AGENTS.md 该写什么、怎么随项目迭代，见《通用 AI 编程方法论》第 1 节。