第五篇：《Codex CLI 安装与快速上手：从零到第一个任务》

Codex 的桌面应用提供了直观的图形界面但如果你想在终端中直接委托任务或者需要在 CI/CD 流水线中集成 AI 编码能力Codex CLI 才是真正的起点。它是 OpenAI 官方开源的终端 AI 编程智能体用 Rust 实现能在你的项目目录中自主读取代码、执行命令、修改文件完成多步骤的工程任务。本文从安装讲起覆盖四种安装方式、两种认证方法、自定义 Provider 配置并通过一个完整的首个任务带你跑通 Codex CLI 的核心流程。一、安装 Codex CLI四种方式按场景选择Codex CLI 支持四种安装方式你可以根据环境选择最合适的一种。方式 A官方安装脚本推荐无需 Node.js官方安装脚本会自动下载最新版、校验 checksum并将 codex 命令加入 PATH# macOS / Linuxcurl-fsSLhttps://chatgpt.com/codex/install.sh|sh# WindowsPowerShellpowershell-ExecutionPolicyByPass-cirm https://chatgpt.com/codex/install.ps1 | iex方式 Bnpm已有 Node 环境时npminstall-gopenai/codex要求 Node.js 22 或更高版本。安装后升级npminstall-gopenai/codexlatest方式 CHomebrewmacOSbrewinstall--caskcodex方式 D二进制直接下载网络受限时从 GitHub Releases 下载对应平台的压缩包解压后将可执行文件重命名为 codex 并放入 PATH。验证安装codex--version# 输出codex 0.131.0或更高版本二、Windows 环境的特殊处理Windows 原生支持目前是实验性的WSL2 是目前最稳的方案。powershell第一步安装 WSL2wsl --install第二步在 WSL 里安装 Node.js 22用 nvmnvm install 22第三步安装 Codex CLInpm i -g openai/codex关键提醒项目要放在 Linux 文件系统里不要放在 /mnt/c/ 下。跨文件系统 IO 会非常慢# ✅ 好的做法项目放在 Linux home 下mkdir-p~/codecd~/codegitclone your-repo# ❌ 不好的做法从 Windows 盘符访问cd/mnt/c/Users/xxx/project# 别这么干会很慢如果不想折腾 WSL也可以在 PowerShell 中直接运行。原生 Windows 下 Codex 使用实验性的沙盒——通过 Restricted Token 文件系统 ACL 限制写入范围创建专用的 Windows Sandbox User 执行命令。三、登录与认证两种方式Codex CLI 支持两种认证方式。3.1 Sign in with ChatGPT推荐适合已有 ChatGPT Plus / Pro / Business / Edu / Enterprise 套餐的用户在订阅额度内使用 Codex无额外按量计费。codex login执行后自动打开浏览器完成 OAuth 授权。凭据缓存在 ~/.codex/auth.json等同密码不要提交到 Git。无头设备服务器/CI使用设备码流程codex login --device-auth查看当前登录状态codex login status3.2 API Key 登录按量计费适合不使用 ChatGPT 订阅、需要在 CI/CD 中编程化调用的场景。# 推荐方式不暴露密钥在 shell historyprintenvOPENAI_API_KEY|codex login --with-api-key⚠️ 出于安全原因Codex 不接受 API Key 作为命令行参数必须通过 stdin 管道传入。四、自定义 Provider接入 DeepSeek、Qwen、GLM 等第三方模型Codex CLI 一直支持接入第三方模型——只要你的接口是 OpenAI 兼容的改个 base_url 就能把 DeepSeek、Claude、GLM、Gemini 都接进来。4.1 配置文件结构Codex CLI 启动时按这个顺序加载配置~/.codex/config.toml — 用户级全局生效项目根目录 .codex/config.toml — 项目级优先级更高命令行参数 — 最高优先级4.2 接入 DeepSeekDeepSeek API 完全兼容 OpenAI 协议只需要一个 Provider 块toml~/.codex/config.tomlmodel “deepseek-chat”model_provider “deepseek”[model_providers.deepseek]name “DeepSeek”base_url “https://api.deepseek.com/v1”env_key “DEEPSEEK_API_KEY”然后设置环境变量echoexport DEEPSEEK_API_KEY你的 DeepSeek API Key~/.zshrcsource~/.zshrc使用命令行参数切换 Provider 和模型codex--providerdeepseek--modeldeepseek-chat4.3 接入国内兼容端点对于国内用户可以将 openai_base_url 指向国内兼容 API 端点替代默认的 api.openai.com从而无需翻墙、无需境外账号完成配置toml~/.codex/config.tomlopenai_base_url “https://api.qnaigc.com/v1”model “deepseek-v4-pro”sandbox_mode “workspace-write”approval_policy “on-request”web_search “disabled”4.4 使用 codex-relay 解决 Responses API 兼容问题Codex CLI 使用 OpenAI 专有的 Responses API有状态协议而大多数第三方 Provider 只暴露标准的 Chat Completions API。codex-relay 是一个轻量级 Rust 代理在 Codex 和你选择的 Provider 之间进行实时翻译——无需修改 Codex 代码。# 安装pipinstallcodex-relay# 启动 relay以 DeepSeek 为例CODEX_RELAY_UPSTREAMhttps://api.deepseek.com/v1\CODEX_RELAY_API_KEY$DEEPSEEK_API_KEY\CODEX_RELAY_PORT4446\codex-relay# 生成 Codex 配置codex-relay --print-config--upstreamhttps://api.deepseek.com/v1 --api-key$DEEPSEEK_API_KEY生成的配置片段会包含 model_properties让 Codex 知道模型的能力上下文窗口、是否支持并行工具调用等避免出现“Model metadata not found”警告。五、第一个任务从零到跑通安装和配置完成后就可以开始你的第一个 Codex 任务了。5.1 进入项目目录cd~/code/my-project5.2 创建 AGENTS.md推荐在项目根目录创建 AGENTS.md帮助 Codex 理解项目上下文。这是 Codex 的项目约定文件类似于 Claude Code 的 CLAUDE.mdmarkdown项目说明这是一个 Rust Web 服务使用 Axum sqlx PostgreSQL。编码规范使用 Rust 2021 edition错误处理使用 thiserror anyhow测试使用 #[tokio::test]常用命令构建cargo build测试cargo test运行cargo run5.3 发起第一个任务codex帮我看看这个项目的结构然后为 src/handlers/order.rs 添加单元测试Codex 会读取项目结构ls、find、cat阅读 order.rs 的代码阅读 AGENTS.md 了解项目规范生成测试代码并写入文件运行 cargo test 验证返回结果摘要5.4 常用命令速查六、小结安装四种方式——官方脚本推荐、npm、Homebrew、二进制下载。Windows推荐 WSL2项目放在 Linux 文件系统下。登录ChatGPT 订阅登录推荐或 API Key 登录CI/CD 场景。自定义 Provider通过 config.toml 接入 DeepSeek、Qwen、GLM 等任何 OpenAI 兼容的模型。codex-relay解决 Responses API 与 Chat Completions API 的协议差异。第一个任务进入项目目录 → 创建 AGENTS.md → codex “任务描述” → 观察执行过程。