OpenAI Codex CLI 完整教程：本地运行的免费编程智能体

📅 2026-05-27 · 📄 约 3200 字

前言

在现代软件开发中，如何高效地完成代码编写、调试和自动化任务一直是开发者关注的焦点。OpenAI 于2025年推出的 Codex CLI 正是为解决这一痛点而生的命令行 AI 助手。它基于 Rust 语言开发，支持直接在终端中与 AI 交互，完成代码生成、文件编辑、命令执行等复杂任务。与传统的 GUI 工具不同，Codex CLI 完全运行在终端环境中，既适合个人开发者的日常编码，也能在 CI/CD 流程中发挥重要作用。无论是快速修复 Bug、生成项目模板，还是自动化构建测试，Codex CLI 都能显著提升效率。

OpenAI Codex CLI 使用流程图

Codex CLI 的核心设计理念是「让 AI 成为你的终端搭档」。它通过自然语言理解开发者的意图，调用代码编辑工具和命令执行工具完成复杂任务。不同于简单的代码补全工具，Codex CLI 能够理解完整的开发上下文——包括项目结构、现有代码、Git 状态——从而给出更精准的建议和操作。它的执行模式分为交互式和批量式，交互式适合探索和调试，批量式适合自动化流水线。

环境准备

在开始安装 Codex CLI 之前，需要确认本地环境满足以下要求：

  • 操作系统：macOS 12+、Ubuntu 20.04+/Debian 10+、Windows 11（需通过 WSL2）
  • 网络：能够访问 OpenAI API（chatgpt.com）或配置的 API 端点
  • 账号：ChatGPT Plus/Pro/Business 订阅，或 OpenAI API Key（含免费额度）
  • 磁盘：至少 500MB 可用空间用于程序文件和缓存

对于国内用户，建议提前配置科学上网环境，或者使用指向国内可访问端点的 API Key（如通过 OpenAI 官方渠道获取，或使用兼容 OpenAI API 格式的第三方服务）。

安装步骤

Codex CLI 提供多种安装方式，开发者可以根据自己的系统环境选择最适合的方式。

方式一：官方安装脚本（推荐，macOS/Linux）

这是官方推荐的安装方式，自动检测系统架构并下载对应版本：

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

安装完成后，终端会显示「Codex installed successfully」提示。验证安装：

codex --version

方式二：PowerShell（Windows）

Windows 用户（需 Windows 11）通过 PowerShell 安装：

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

安装后重启 PowerShell 使环境变量生效。

方式三：npm

如果你已经安装了 Node.js 18+，可以通过 npm 全局安装：

npm install -g @openai/codex

这种方式适合已经在使用 Node.js 生态的开发者。

方式四：Homebrew（macOS）

macOS 用户也可以通过 Homebrew 安装：

brew install --cask codex

方式五：直接下载二进制

访问 GitHub Releases 页面（https://github.com/openai/codex/releases/latest），下载对应平台的二进制文件并添加到 PATH 环境变量。

基础使用

认证配置

首次使用 Codex CLI 前，需要完成认证。有两种认证方式：

方式一：ChatGPT 订阅登录（推荐）

codex auth login

运行命令后，Codex CLI 会打开浏览器窗口引导你完成 OAuth 登录。登录成功后，认证信息会保存在本地配置文件中。

方式二：API Key

export OPENAI_API_KEY=sk-xxxxx

将以上内容加入 ~/.bashrc（Linux/macOS）或系统环境变量（Windows），每次开终端自动加载。也可以在项目中创建 .env 文件，通过 dotenv 加载。

交互模式

在任意项目目录运行：

codex

Codex CLI 会分析项目结构（语言类型、框架、依赖管理工具），然后进入 READY 状态等待指令。进入交互模式后，可以进行多轮对话，Codex 会记住同一会话内的上下文：

codex$ 帮我添加一个用户登录接口
codex$ 再加一个 JWT 鉴权中间件
codex$ 把这个接口的单元测试补上

单次指令模式

不需要进入交互式会话，直接在命令行传入指令：

codex exec "帮我写一个快速排序算法"

这种方式适合简单任务，或者在脚本中调用 Codex。

进阶功能

Skill 系统

Codex CLI 支持自定义 Skills，可以理解为「让 Codex 学会特定任务模式」的功能。你可以在项目根目录创建 .codex/skills/ 目录，添加自定义 Skill 定义文件。官方 Skill 文档：https://developers.openai.com/codex/skills

MCP（Model Context Protocol）

Codex CLI 支持连接 MCP 服务器，实现对外部工具和数据的扩展访问。v0.134.0 新增了 per-server 环境配置和 OAuth 选项：

codex mcp add my-server --env staging

具体支持的 MCP 服务器列表和配置方法，参考官方文档。

AGENTS.md 多 Agent 协作

Codex CLI 支持通过 AGENTS.md 文件定义多 Agent 协作流程，适合复杂项目中多个专业角色配合工作的场景。需要在项目中启用 child_agents_md feature flag：

codex config set feature.child_agents_md true

profile 切换

v0.134.0 将 --profile 升级为主要的 profile 选择器。你可以为不同项目创建不同的 profile，每个 profile 有独立的认证信息、模型偏好、Skill 配置：

codex profile create work-project
codex profile use work-project

实际案例

案例一：快速修复 Bug

cd my-project
codex
# 进入交互模式后输入：
我在运行 npm test 时遇到一个报错：TypeError: Cannot read property 'map' of undefined
请帮我分析这个问题并给出修复方案

Codex 会分析测试日志、定位错误位置、提供修复代码。

案例二：批量重构

codex exec "把所有组件中的 console.log 替换为使用项目统一的 logger.info"

Codex 会遍历项目中所有匹配的 JavaScript/TypeScript 文件，执行统一的修改。

案例三：生成测试用例

codex exec "为 src/utils/format.ts 中的所有函数生成 Jest 测试用例"

Codex 会分析源代码结构，生成覆盖主要分支的单元测试文件。

案例四：自动化部署脚本

codex exec "写一个自动化部署脚本：构建 Docker 镜像 -> 推送到私有仓库 -> 在服务器上拉取并重启服务"

Codex 会生成完整可用的 Shell 脚本，包含错误处理和日志记录。

常见问题

Q1：安装后运行 codex 提示「command not found」

检查 PATH 环境变量是否包含安装目录。Linux/macOS 安装脚本通常将二进制文件放在 ~/.local/bin 或 /usr/local/bin。如果不在 PATH 中，手动添加：export PATH="$HOME/.local/bin:$PATH"

Q2：auth login 显示授权成功，但后续操作提示「Not authenticated」

认证文件可能损坏。尝试删除本地认证缓存（~/.config/codex/auth），然后重新运行 codex auth login。

Q3：codex exec 执行时提示「Permission denied」

Codex CLI 有内置沙箱机制，某些危险操作（如删除系统文件、执行 rm -rf /）会被阻止。如果确实需要执行特权操作，可以添加 --allow-dangerous 选项（仅在信任的环境中谨慎使用）：codex exec "危险命令" --allow-dangerous

Q4：使用 exec 模式时返回结果被截断

默认情况下 exec 模式会限制输出长度，避免生成过大的文件。可以通过 --max-output SIZE 参数调整限制。对于需要生成大文件的任务，建议使用交互模式并分段请求。

Q5：如何连接本地模型（如 ollama）？

Codex CLI 支持自定义 API 端点。在环境变量中设置 OPENAI_API_BASE 指向你的本地模型服务：export OPENAI_API_BASE=http://localhost:11434/v1，然后确保本地模型兼容 OpenAI API 格式。这样可以实现完全本地的编程智能体体验。

Q6：多 Agent 协作如何配置？

在项目根目录创建 AGENTS.md 文件，定义多个 Agent 的角色、职责和协作规则。例如：定义「前端 Agent」负责 UI 相关任务，「测试 Agent」负责验证功能。通过 child_agents_md feature flag 启用后，Codex 会自动在适当时机调度子 Agent 协作。

优缺点总结

优势

  • 完全本地运行，数据和代码不离开你的机器，隐私安全有保障
  • 支持多种安装方式和认证方式，上手门槛低
  • Rust 实现，性能优异，响应速度快
  • 支持 Skill 系统、MCP、AGENTS.md 等扩展机制，可定制性强
  • 活跃开发中，v0.134.0（2026-05-26）刚发布，功能持续迭代
  • 完全开源，可以审计代码、贡献改进

不足

  • 对中文指令的理解准确度略低于英文场景
  • 超大规模代码库的索引和检索速度仍有提升空间
  • 企业级功能（SSO、审计日志等）尚在完善中
  • 依赖外部 API，网络稳定性有要求

适用人群

个人开发者：免费工具，本地运行无数据泄露风险，适合处理私有项目。中小团队：通过 Skill 系统和 AGENTS.md 实现团队知识沉淀，提升协作效率。DevOps 工程师：在 CI/CD 流程中接入 Codex，实现自动化测试、部署脚本生成等任务。

然而，作为一款相对年轻的产品，Codex CLI 仍存在一些不足。目前对非英文指令的理解准确度略低于英文场景；大规模代码库的索引和检索速度有提升空间；企业级功能如 SSO 集成、审计日志等尚在完善中。此外，由于依赖 OpenAI API，网络稳定性和调用成本也是需要考虑的因素。

综合来看，Codex CLI 适合追求开发效率提升的个人开发者和中小团队使用。在合理配置的前提下，它能够成为日常编码工作中不可或缺的智能助手。建议新用户从基础交互模式开始体验，逐步探索 exec 自动化和 Skill 自定义等进阶功能，充分发挥这款工具的潜力。