Codex CLI 云环境部署实操指南

编写日期：2026-04-29 | 基于 Codex CLI 2026 Q1 版本（Rust 核心，npm 分发）

一、Codex CLI 概述

OpenAI Codex CLI 是一个开源（Apache-2.0）Rust 实现的终端编码 agent。核心特点：

• 本地执行：读取/修改文件、运行命令都在本机完成
• OS 级沙箱：macOS Seatbelt / Linux bubblewrap + Landlock / Windows AppContainer
• 无头模式：codex exec 适合 CI/CD 和脚本自动化
• 模型：GPT-5.3-Codex（旗舰）/ GPT-5.3-Codex-Spark（低延迟）/ GPT-5-Codex-Mini（经济）
• 安装：npm install -g @openai/codex 或直接下载 GitHub Releases 二进制

二、部署场景

场景 A：AWS Lightsail

适合低成本、固定预算的小型团队或个人 CI/CD runner。

系统要求

⚠️ 512 MB 实例不推荐：npm install 大包时可能 OOM。建议至少 2 GB。

安装步骤

# 1. 更新系统
sudo apt update && sudo apt upgrade -y

# 2. 安装 Node.js 22（LTS）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs git build-essential

# 验证
node --version  # v22.x
npm --version   # 10.x+

# 3. 安装 Codex CLI
npm install -g @openai/codex

# 4. 配置 API Key（无头模式必须）
export OPENAI_API_KEY="sk-..."
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc

# 或写入 config.toml
mkdir -p ~/.codex
cat > ~/.codex/config.toml << 'EOF'
preferred_auth_method = "apikey"
model = "gpt-5.3-codex"
approval_policy = "never"
sandbox_mode = "workspace-write"
EOF

# 5. 验证
codex --version
codex exec "echo hello world"

Sandbox 配置

Linux 上 Codex 使用 bubblewrap + Landlock 进行系统级沙箱隔离：

# ~/.codex/config.toml
sandbox_mode = "workspace-write"     # 仅项目目录可写
# 或
sandbox_mode = "read-only"           # 只读模式（code review）
# 或
sandbox_mode = "danger-full-access"  # 无限制（仅可信环境）

对于 Lightsail 上的 CI/CD： - code review：read-only（最安全） - auto-fix：workspace-write（推荐） - e2e test/部署：danger-full-access（需额外安全措施）

Lightsail 特定注意事项

1. 静态 IP：建议附加静态 IP（免费，避免重启换 IP）
2. 防火墙：出站需要开放 443 到 api.openai.com；入站仅需 SSH（22）
3. 自动启动：用 systemd 或 cron 管理定时任务
4. 磁盘清理：~/.codex/sessions/ 会累积 rollout 文件，定期清理

# 清理 30 天前的 session 文件
find ~/.codex/sessions/ -type f -mtime +30 -delete

场景 B：AWS EC2

适合需要更高性能、弹性伸缩或与 AWS 生态集成的场景。

系统要求

安装步骤

# === Ubuntu 22.04/24.04 ===
sudo apt update && sudo apt upgrade -y

# 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs git

# 安装 Codex
npm install -g @openai/codex

# 配置
mkdir -p ~/.codex
cat > ~/.codex/config.toml << 'EOF'
preferred_auth_method = "apikey"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
approval_policy = "never"
sandbox_mode = "workspace-write"
EOF

export OPENAI_API_KEY="sk-..."
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc

# === Amazon Linux 2023 ===
sudo dnf update -y
sudo dnf install -y nodejs git

# Node.js 版本可能偏旧，用 nvm 安装新版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

npm install -g @openai/codex
# 其余配置同上

Sandbox 配置

# ~/.codex/config.toml — EC2 专用配置
preferred_auth_method = "apikey"
model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

# 命名 profile，方便不同任务切换
[profiles.review]
approval_policy = "never"
sandbox_mode = "read-only"
model = "gpt-5-codex-mini"

[profiles.fix]
approval_policy = "never"
sandbox_mode = "workspace-write"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"

EC2 systemd 服务（定时/触发式）

# /etc/systemd/system/codex-agent.service
[Unit]
Description=Codex CLI Agent Runner
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=ec2-user
WorkingDirectory=/home/ec2-user/project
Environment="OPENAI_API_KEY=sk-..."
ExecStart=/home/ec2-user/.nvm/versions/node/v22.0.0/bin/codex exec \
  --profile fix \
  "Fix failing tests and create a PR with the changes"

[Install]
WantedBy=multi-user.target

# 定时运行
cat > /etc/systemd/system/codex-agent.timer << 'EOF'
[Unit]
Description=Run Codex agent every 30 minutes

[Timer]
OnCalendar=*:0/30
Persistent=true

[Install]
WantedBy=timers.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now codex-agent.timer

Codex + Bedrock 集成（EC2 专属优势）

在 EC2 上可直接接入 Amazon Bedrock，避免 OpenAI API 依赖：

# ~/.codex/config.toml
[model_providers.bedrock]
name = "AmazonBedrock"
base_url = "https://bedrock-mantle.us-west-1.api.aws/v1"
env_key = "CODEX_OPENAI_API_KEY"

[profiles.bedrock]
model = "openai.gpt-oss-120b"
model_provider = "bedrock"
wire_api = "responses"  # Codex 默认使用 /v1/responses API

⚠️ 注意：需要先在 AWS Console 中申请 Bedrock 模型访问权限。

场景 C：GitHub Actions

Codex 提供官方 Action openai/codex-action@v1，是最简洁的 CI/CD 集成方式。

系统要求

• GitHub 任意 plan（包括 Free）
• Runner：ubuntu-latest（推荐）或自定义 runner
• 权限：contents: read（review）或 contents: write（auto-fix）

安装步骤（最小可用）

# .github/workflows/codex-review.yml
name: Codex PR Review

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - name: Codex review
        id: codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            Review this pull request diff for:
            1. Security vulnerabilities
            2. Logic errors
            3. Performance issues
            4. Adherence to project conventions
            Output a concise markdown report.
          sandbox: read-only
          safety-strategy: drop-sudo
          effort: medium
          output-file: review.md

      - name: Post review
        uses: peter-evans/create-or-update-comment@v4
        with:
          issue-number: ${{ github.event.pull_request.number }}
          body-file: review.md

Sandbox 配置

GitHub Actions 中的 sandbox 和 safety-strategy 是两层独立的防护：

GitHub Actions 工作流模式

模式 1：PR Code Review 门禁

name: Codex Quality Gate

on:
  pull_request:

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Quality scan
        id: scan
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            Analyse the diff. Output ONLY "PASS" if the code meets quality
            standards, or "FAIL: <reason>" if it does not.
          sandbox: read-only
          effort: minimal  # 低延迟 + 低成本

      - name: Enforce gate
        run: |
          RESULT="${{ steps.scan.outputs.final-message }}"
          if [[ "$RESULT" != PASS* ]]; then
            echo "::error::Quality gate failed: $RESULT"
            exit 1
          fi

模式 2：Auto-Fix 失败 CI

name: Codex Auto-Fix

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

permissions:
  contents: write
  pull-requests: write

jobs:
  fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.workflow_run.head_branch }}

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci

      - name: Codex fix
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            The CI workflow failed. Identify the minimal change needed
            to make all tests pass. Implement only that change.
          sandbox: workspace-write
          safety-strategy: drop-sudo
          effort: high

      - run: npm test

      - name: Open fix PR
        uses: peter-evans/create-pull-request@v6
        with:
          branch: codex/auto-fix-${{ github.run_id }}
          title: "fix: Codex auto-repair for CI failure"
          body: "Automated fix. Review before merging."

模式 3：矩阵并行（多服务）

name: Parallel Service Review

on:
  push:
    branches: [main]

jobs:
  review:
    strategy:
      matrix:
        service: [auth, payments, notifications, search]
      fail-fast: false  # 一个失败不影响其他
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Review ${{ matrix.service }}
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            Review the code in services/${{ matrix.service }}/.
            Focus on security, error handling, and test coverage.
            Output a structured JSON report.
          codex-args: >-
            ["--output-schema-file", ".github/codex/schemas/review.json"]
          sandbox: read-only
          effort: medium
          output-file: review-${{ matrix.service }}.json

      - uses: actions/upload-artifact@v4
        with:
          name: review-${{ matrix.service }}
          path: review-${{ matrix.service }}.json

模式 4：结构化 JSON 输出门禁

// .github/codex/schemas/review.json
{
  "type": "object",
  "required": ["severity", "issues", "recommendation"],
  "properties": {
    "severity": {
      "type": "string",
      "enum": ["low", "medium", "high", "critical"]
    },
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "file": { "type": "string" },
          "line": { "type": "integer" },
          "description": { "type": "string" }
        }
      }
    },
    "recommendation": { "type": "string" }
  }
}

- name: Security Scan
  id: scan
  uses: openai/codex-action@v1
  with:
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
    prompt-file: .github/codex/prompts/security-scan.md
    codex-args: '["--output-schema-file", ".github/codex/schemas/review.json"]'
    sandbox: read-only

- name: Fail on critical
  run: |
    SEVERITY=$(echo '${{ steps.scan.outputs.final-message }}' | jq -r '.severity')
    if [ "$SEVERITY" = "critical" ]; then
      echo "::error::Critical security issue found"
      exit 1
    fi

三、无头模式使用指南

codex exec 命令详解

# 基本用法
codex exec "Update the changelog for next release"

# 短别名
codex e "Fix all failing tests"

# 关键参数
codex exec \
  --model gpt-5.3-codex \          # 指定模型
  --sandbox workspace-write \       # 沙箱模式
  --approval-policy never \         # 无需确认（CI 必须）
  --json \                          # JSON 行输出（CI 友好）
  --output-last-message result.md \ # 最终消息写入文件
  --ephemeral \                     # 不持久化 session
  --skip-git-repo-check \           # 允许非 git 仓库
  --profile ci \                    # 加载命名配置
  "Your prompt here"

审批策略

# CI/CD 中必须设置 never + workspace-write
codex exec --approval-policy never --sandbox workspace-write "..."

# 或使用 --full-auto 快捷方式（= on-request + workspace-write）
codex --full-auto "refactor auth module"

无头模式与交互模式的差异

从 exec 恢复 session

# 恢复最近 session
codex exec resume --last

# 恢复指定 session
codex exec resume thr_abc123

# 带新 prompt 恢复
codex exec resume --last "Continue the refactoring from where we left off"

四、成本估算

订阅模式

5 小时滚动窗口：从首次消息起算，5 小时后重置。不是每日/每月。

API Key 按量计费

API 价格（2026 Q1）：

典型任务成本估算

订阅 vs API Break-even 分析

每月 session 数 < 10-15  → API Key 更便宜
每月 session 数 > 15    → Plus ($20/mo) 更划算
每天长 session > 3-4    → Pro ($200/mo) 或考虑 API
仅 CI/CD 不自己写代码    → API Key 更灵活

基础设施成本

总成本示例

五、已知坑点 & 故障排查

5.1 安装相关

5.2 认证相关

5.3 Sandbox 相关

5.4 运行相关

5.5 GitHub Actions 专属

5.6 成本相关

六、安全最佳实践

1. API Key 管理
   ├── 永远不硬编码在代码/配置文件中
   ├── 使用环境变量或 GitHub Secrets
   └── 不同环境用不同 Key（生产/开发分离）

2. Sandbox 原则
   ├── 默认使用 read-only
   ├── 需要写时才用 workspace-write
   └── danger-full-access 仅在隔离临时环境使用

3. GitHub Actions
   ├── safety-strategy: drop-sudo（默认）
   ├── 公开仓库限制 allow-users
   └── fork PR 用 pull_request_target 时额外审计

4. 成本控制
   ├── CI 高频任务用 gpt-5-codex-mini
   ├── 定时清理 session 数据
   └── 设置 OpenAI 使用上限（usage limits）

七、快速参考卡片

# 安装
npm install -g @openai/codex

# 交互模式
codex                              # 启动 TUI
codex "explain this code"         # 直接提问
codex -m gpt-5.3-codex            # 指定模型

# 无头模式
codex exec "fix failing tests"
codex exec --json --ephemeral "analyze this repo"
codex exec --approval-policy never --sandbox workspace-write "..."

# 恢复会话
codex resume --last
codex resume thr_abc123

# 模型
/mode             # 切换模型（交互模式中）
/model gpt-5.3-codex-spark

# 状态
/status           # 查看当前配置和用量
/usage            # 查看 token 消耗
/compact          # 压缩上下文

# 配置
~/.codex/config.toml    # 主配置文件
AGENTS.md               # 项目指令（项目根目录）

指南完成。数据来源：OpenAI 官方文档、DeepWiki、社区指南、GitHub openai/codex、实测反馈。