OpenAI Codex CLI 完整教程：30分钟从终端构建部署全栈应用（2026）

TL;DR

如果你在搜「OpenAI Codex CLI 怎么用」或「Codex 终端编程agent教程」，本指南带你30分钟内从零开始在终端里构建并部署全栈应用。Codex CLI 是 OpenAI 的终端原生编程 Agent——不需要 IDE，不需要 GUI，一个 codex 命令就能读懂你的代码库、理解自然语言指令、自主编写/测试/调试代码。

你将学到

• 在 macOS/Linux 上安装并认证 Codex CLI
• 运行第一个 codex 会话，构建一个可用的应用
• 使用 Codex CLI 的沙箱模式、多文件编辑和测试循环
• 直接从 Codex CLI 部署到生产环境
• 避开5个最常见的坑（速率限制、沙箱逃逸、上下文溢出）

准备清单

• macOS 或 Linux 终端（Windows 通过 WSL2 可用）
• Node.js 18+（Codex CLI 是 npm 包）
• OpenAI API key 或 ChatGPT Plus/Pro 订阅
• Git 已安装并配置
• 基本的终端操作经验

Step 1: 安装 Codex CLI 并认证

Codex CLI 以 npm 包形式发布，全局安装：

npm install -g @openai/codex-cli

验证安装：

codex --version

# 预期输出: @openai/codex-cli/0.x.x

认证 OpenAI 账号：

codex login

这会打开浏览器进行 OAuth 认证。如果在无头服务器上，使用 --no-browser 参数：

codex login --no-browser

# → 在另一台设备上打开打印的 URL，将验证码粘贴回来

Codex CLI 将凭据存储在 ~/.codex/config.json。也可以直接使用 API key：

export OPENAI_API_KEY=*** --api-key "$OPENAI_API_KEY"

常见坑: Codex CLI 需要 ChatGPT Plus、Pro 或 Team 订阅——免费账户会报 403 authentication_required。如果使用 API key，至少需要 Tier 1 使用额度。

Step 2: 第一个 Codex 会话

进入一个空项目目录并初始化：

mkdir my-codex-app && cd my-codex-app
git init
codex init

运行第一个提示词：

codex "创建一个 Python FastAPI 服务器，包含三个端点：
1. GET /health → 返回 {'status': 'ok'}
2. POST /items → 接受 JSON body 并存入 SQLite 数据库
3. GET /items → 返回所有已存储的数据
包含 requirements.txt 和 README.md"

Codex CLI 会：

1. 规划文件结构（先展示文件树）
2. 写入所有文件（FastAPI 应用、requirements.txt、README.md）
3. 运行测试（启动服务器，请求 /health）
4. 报告结果

关键行为: Codex CLI 采用 规划 → 执行 → 验证 循环。它不会直接倾倒代码——先规划，请求确认（可配置），然后测试自己的输出。

Step 3: 多文件编辑与迭代开发

Codex CLI 真正的威力在于多文件上下文感知。在现有项目中启动会话：

cd ~/my-existing-project
codex

进入交互模式，> 提示符表示 Codex 就绪：

Codex 会读取整个代码库（遵守 .gitignore），识别所有需要修改的文件，并协调一致地应用更改。

会话管理:

# 启动命名会话（可恢复）
codex --session "add-auth"

# 恢复上一个会话
codex --resume

# 列出会话
codex sessions list

# 导出会话摘要
codex sessions export add-auth > changes.md

大型代码库技巧: 使用 .codex/context.md 为 Codex 提供跨会话的高层项目上下文：

# .codex/context.md
这是一个 Next.js 14 电商应用，使用 App Router。
后端: Supabase（PostgreSQL + Auth）。
状态管理: Zustand。
样式: Tailwind CSS。
测试: Vitest + Playwright。
CI: GitHub Actions。

Step 4: 沙箱模式与安全

Codex CLI 内置沙箱模式，阻止在项目目录外写入文件：

codex --sandbox "将所有 API 调用重构为使用共享 http 客户端"

沙箱模式限制：

• 禁止写入项目根目录之外
• 禁止网络请求到未批准的域名（在 .codex/sandbox.json 中配置）
• 禁止修改系统状态的 Shell 命令（rm -rf /、chmod 等）
• 只读访问项目外文件（仅作参考）

CI/CD 流水线中务必使用沙箱模式：

# .github/workflows/codex-review.yml
name: Codex 代码审查
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @openai/codex-cli
      - run: |
          codex --sandbox --non-interactive \
            "审查此 PR diff 中的 bug、安全问题和代码风格违规。
             将 markdown 报告输出到 codex-review.md"
      - uses: actions/upload-artifact@v4
        with:
          name: codex-review
          path: codex-review.md

常见坑: 沙箱模式默认阻止 npm install 和 pip install。在 .codex/sandbox.json 中将包管理器加入白名单：

{
  "allowed_commands": ["npm install", "npm ci", "pip install", "cargo build"],
  "allowed_domains": ["registry.npmjs.org", "pypi.org"]
}

Step 5: 从 Codex CLI 部署

Codex CLI 可以直接部署到常见平台：

Vercel（Next.js / 前端）:

codex "使用 Vercel CLI 将此应用部署到 Vercel。
从环境变量中读取 VERCEL_TOKEN。"

Railway / Fly.io（全栈）:

codex "生成 fly.toml 配置，构建 Dockerfile，部署到 Fly.io。
使用环境变量中的 FLY_API_TOKEN。"

GitHub Pages（静态站点）:

codex "构建静态输出并使用 gh-pages npm 包部署到 GitHub Pages。
从 git remote 自动检测仓库 URL。"

部署循环:

# 1. 构建并测试
codex --sandbox "运行完整测试套件并修复所有失败"

# 2. 全部通过则部署
codex "测试通过。部署到 Railway 生产环境。"

常见坑位

Codex CLI vs 其他 AI 编程工具

Codex CLI 的核心差异化优势是无头/CI 就绪操作——不需要 IDE，非常适合自动化工作流、pre-commit 钩子和 CI 流水线。

下一步

• Agent 工作流: 将 Codex CLI 与 n8n 或 Hermes Agent 串联，构建自主编程流水线
• 团队搭建: 阅读我们的 Runtime 沙箱编程 Agent 教程
• 成本优化: 查看 Claude Code + DeepSeek V4 获得 90% 更便宜的替代方案
• 移动端编程: 如果你在移动端编码，参见 Codex Mobile 教程

本教程使用的工具: OpenAI Codex CLI、Claude Code、n8n、Hermes Agent。工具提及由平台自动检测——无需手动标记。