用 Codex CLI
把最强推理模型装进你的终端

① 你用的是什么系统？

② 装好两样必备工具

检查 / 安装复制node -v        # 显示 v22.x.x 就 OK；若提示找不到命令，说明没装

# 没有 Node.js？两种装法（任选其一）：
# ① 官网下载安装包（最简单）：访问 https://nodejs.org 下载 LTS 版，双击安装
# ② 用 nvm 管理（推荐开发者）：
#   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
#   然后 nvm install 22

检查 / 安装复制git --version  # 有版本号就 OK

# 没有？访问 https://git-scm.com/downloads 下载安装

③ 要花钱吗？

④ 它会弄坏我电脑吗？

⑤ 新手避坑 4 条

Codex CLI 是 OpenAI 开发的开源系统级 AI 助手，用 Rust 编写，具有极高的性能与极低的内存占用。它能在终端里读取、修改、运行你的代码，是一个真正意义上的 AI Agent——定位与 Claude Code 一致，但开源、更快、可接任意模型。

核心特性

系统要求

方式一：npm 全局安装（推荐）

bash复制# 全局安装 Codex CLI
npm i -g @openai/codex

# 验证安装
codex --version    # 或 codex -V

# 查看帮助
codex --help

# 升级到最新版
npm i -g @openai/codex@latest
# 或
codex update

方式二：Homebrew 安装（macOS）

bash复制brew install --cask codex
# 升级
brew upgrade codex

方式三：从源码 / 二进制

前往 github.com/openai/codex 的 Releases 页面下载预编译二进制；或从源码编译：

bash复制git clone https://github.com/openai/codex.git
cd codex
cargo build --release

Codex CLI 支持三种认证方式，按推荐程度排序：

bash复制# 首次运行 codex 会自动触发 OAuth 登录流程
# 也可以手动登录
codex login

# 支持的订阅类型：Plus / Pro / Business / Edu / Enterprise

# 登出
codex logout
# 或在交互式会话中输入 /logout

bash复制# Git Bash / macOS / Linux
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

# 永久生效：写入 ~/.bashrc 或 ~/.zshrc
echo 'export OPENAI_API_KEY="sk-xxx"' >> ~/.zshrc
source ~/.zshrc

# 或写入 ~/.codex/auth.json
cat > ~/.codex/auth.json <<'EOF'
{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx"
}
EOF

🥚 实战：让 Codex 写一个脚本并运行

bash复制# 1. 新建一个空目录并进入
mkdir codex-hello && cd codex-hello
git init                          # 一定要初始化 git，方便回滚

# 2. 启动 Codex
codex

# 3. 在 TUI 输入框里输入这段自然语言（回车发送）：
#    用 Python 写一个猜数字小游戏，保存到 game.py，然后运行它让我试玩

bash复制# 1. 进入你的项目（强烈建议先 git init）
cd my-project
git init

# 2. 启动交互式 TUI（默认模式）
codex

# 3. 直接带任务启动
codex "解释这个项目结构"

# 指定工作目录启动
codex --cd /path/to/project

# 使用本地模型（Ollama 等）
codex --oss

🖥️ 启动后你会看到什么

第一次启动 codex，屏幕大致长这样（不用担心，照着提示走就行）：

TUI 界面示意┌─ Codex ──────────────────── model: gpt-5.4 ──┐
│                                                │
│  > 帮我写一个猜数字游戏                         │  ← 你在这输入需求
│                                                │
│  🤖 好的，我来创建 game.py ...                  │
│  ⚠️ 请求【写入文件】: game.py                    │  ← 审批提示
│     [y] 同意   [n] 拒绝   [a] 本次都同意        │
│  ✓ 已创建 game.py                              │
│  ⚠️ 请求【执行命令】: python game.py            │
│     [y] 同意   [n] 拒绝                         │
│                                                │
└────────────────────────────────────────────────┘
   [ 输入你的需求... ]                       发送 ↵

TUI 界面三大区域

图片输入（多模态）

bash复制# 分析截图中的报错
codex -i screenshot.png "Explain this error."

# 多张图片
codex --image img1.png,img2.jpg "Summarize these diagrams."

# 也可以把图片直接粘贴进编辑器

非交互式 exec 模式（脚本 / CI）

bash复制# 单次执行任务
codex exec "fix the CI failure"

# 输出到文件
codex exec "生成 README" -o README.md

# 指定模型 + 全自动
codex exec -m gpt-5.4-mini --full-auto "运行测试并修复失败项"

三种审批模式对比

切换审批模式

bash复制# 在交互式会话中切换
/permissions

# 用 CLI 参数启动
codex --sandbox read-only       # 只读
codex --sandbox workspace-write # 工作区写入（推荐日常）
codex --sandbox danger-full-access # 完全访问（危险）
codex --full-access             # 等同于 full-auto

# ⚠️ 完全自主：跳过所有确认（危险）
codex --yolo

各平台沙箱机制

~/.codex/config.toml · 最小可用复制model = "gpt-5.4"                  # 用哪个模型
approval_policy = "on-request"     # 改文件 / 跑命令前问你一句
sandbox_mode = "workspace-write"   # 只允许在工作目录内写

👇 下面是完整参数参考，按需查阅，不用全记。

配置文件层级（优先级从高到低）

优先级：CLI 参数 > Profile > 项目配置 > 用户配置 > 系统配置 > 内置默认值

核心参数完整示例

~/.codex/config.toml复制# 顶部声明可获得 IDE 自动补全
#:schema https://developers.openai.com/codex/config-schema.json

# ---- 模型相关 ----
model = "gpt-5.4"
model_provider = "openai"
# 推理努力：minimal | low | medium | high | xhigh
model_reasoning_effort = "medium"
# 推理摘要：auto | concise | detailed | none
model_reasoning_summary = "auto"
model_context_window = 200000
model_verbosity = "medium"
service_tier = "fast"

# ---- 审批与沙箱 ----
# approval_policy: untrusted | on-request | never
approval_policy = "on-request"
# sandbox_mode: read-only | workspace-write | danger-full-access
sandbox_mode = "workspace-write"
approvals_reviewer = "user"

# ---- Web 搜索 ----
# cached（默认快） | live（实时） | disabled
web_search = "cached"

requirements.toml（管理员强制约束，企业级）

Codex 独有的企业级安全特性。管理员可强制约束所有开发者的行为，用户无法覆盖：

/etc/codex/requirements.toml复制allowed_approval_policies = ["on-request", "never"]
allowed_sandbox_modes = ["read-only", "workspace-write"]
allowed_web_search_modes = ["cached", "disabled"]
allowed_approvals_reviewer = ["user"]
# mcp_servers = ["github", "postgres"]  # MCP 白名单

自定义供应商完整示例

~/.codex/config.toml复制# 使用自定义供应商作为默认
model_provider = "custom"
model = "gpt-5-codex"

# 示例 1：自定义 API 中转
[model_providers.custom]
name = "服务名"
base_url = "https://api.your-proxy.com/v1"
env_key = "CUSTOM_API_KEY"
wire_api = "responses"
request_max_retries = 3
stream_idle_timeout_ms = 300000

# 示例 2：备用供应商
[model_providers.backup]
name = "备用供应商"
base_url = "https://api.backup-provider.com/v1"
env_key = "BACKUP_API_KEY"
wire_api = "responses"

供应商参数说明

把 Key 配在环境变量里更安全（避免明文进 Git）：

bash复制echo 'export CUSTOM_API_KEY="sk-your-key"' >> ~/.zshrc
source ~/.zshrc

# 启动时用默认供应商
codex
# 切换到备用
codex --model-provider backup

~/.codex/config.toml复制# 工作模式：最强模型 + 实时搜索
[profiles.work]
model = "gpt-5.5"
web_search = "live"
approval_policy = "on-request"

# 快速模式：轻量模型 + 低推理
[profiles.fast]
model = "gpt-5.4-mini"
web_search = "cached"
model_reasoning_effort = "low"

# 审查模式：只读 + 详细推理
[profiles.review]
model = "gpt-5.5"
sandbox_mode = "read-only"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"

# 自主模式（危险，按需切换）
[profiles.auto]
approval_policy = "never"
sandbox_mode = "danger-full-access"
web_search = "live"

bash复制codex --profile work     # 工作模式
codex --profile fast     # 快速模式
codex --profile auto     # 自主模式
codex --profile review   # 只读审查

发现链与合并规则

Codex 启动时会按特定顺序搜索并加载 AGENTS.md：

1. 全局（~/.codex/）：读取 AGENTS.override.md 或 AGENTS.md
2. 项目（Git 根目录到当前工作目录）：每级检查 AGENTS.override.md → AGENTS.md
3. 合并：从根目录向下拼接，靠近 CWD 的文件优先级更高
4. 大小限制：默认 32 KiB（project_doc_max_bytes 可调）

Override 机制

AGENTS.override.md 优先于同级 AGENTS.md，方便临时覆盖而不污染基础文件。

快速生成

bash复制# 方式一：用 /init 命令自动生成骨架
codex
> /init

# 方式二：让 Codex 根据项目结构生成
> 请根据当前项目结构生成 AGENTS.md 文件

会话管理

模型与配置

工具与扩展

开发辅助

系统与诊断

Goal 命令

Goal 工作流程

使用示例

交互式复制# ✅ 具体、可衡量的 SMART 目标
/goal 实现一个 RESTful API，包括：
1. 用户注册和登录（JWT 认证）
2. CRUD 操作
3. 数据验证和错误处理
4. 单元测试（覆盖率 > 80%）

# 查看进度
/goal status

# ✅ 带验证闭环（强烈推荐）
/goal 实现用户认证功能，然后：
1. 运行测试: !npm test
2. 检查覆盖率: !npm run test:coverage
3. 运行 lint: !npm run lint
4. 如果失败，自动修复后重新验证，直到全部通过

MCP（Model Context Protocol）

通过标准协议连接外部工具和服务，概念与 Claude Code 一致。

~/.codex/config.toml复制# STDIO 类型 MCP 服务器
[mcp_servers.my-server]
command = "npx"
args = ["-y", "my-mcp-server"]
env = { API_KEY = "your-api-key" }

# HTTP/SSE 类型
[mcp_servers.remote-server]
url = "https://mcp.example.com/sse"
bearer_token_env_var = "MCP_TOKEN"

# Codex 自身也可作为 MCP 服务器
# 命令行：codex mcp-server

# 会话中查看 MCP 状态
# > /mcp verbose

Subagents（子代理）

内置并行任务委派系统，最多 6 线程并发（可配置）。

~/.codex/config.toml复制[agents]
max_threads = 6        # 最大并发
max_depth = 1          # 最大嵌套深度
job_max_runtime_seconds = 1800  # 每个 Worker 超时

[agents.code-reviewer]
description = "专业代码审查 Agent"
nickname_candidates = ["Reviewer", "Inspector"]

[agents.test-writer]
description = "测试工程师 Agent"
nickname_candidates = ["Tester", "QA"]

使用：请使用 code-reviewer agent 审查 src/auth.ts 的代码质量，可并行调用多个 Agent。

Skills 与 Plugins

存放位置：全局 $HOME/.agents/skills 或项目级 .agents/skills。会话中用 /skills 浏览，/plugins 管理可分发插件。

记忆系统（Memories）

Codex 内置跨会话自动记忆（默认关闭，与 Claude Code 手动维护 MEMORY.md 不同）：

~/.codex/config.toml复制[features]
memories = true   # 显式开启

[memories]
use_memories = true          # 注入已有记忆
generate_memories = true     # 生成新记忆
extract_model = "gpt-5.4-mini"      # 提取用模型
consolidation_model = "gpt-5.4"     # 全局整合用模型

工作原理：① 会话结束后自动提取关键知识 → ② 多线程知识整合为全局记忆 → ③ 新会话自动注入相关记忆。

其他进阶能力

TUI 交互技巧

Shell 集成

交互式复制# 用 ! 前缀直接运行 Shell 命令，输出作为上下文
!git status
!npm test
!ps aux | grep node

多根目录工作

bash复制# 在 frontend 启动，同时引入 backend 和 shared
codex --cd apps/frontend --add-dir ../backend --add-dir ../shared

会话管理

bash复制codex resume            # 交互式选择最近会话
codex resume --all      # 显示所有目录的会话
codex resume --last     # 跳到最近会话
codex resume <id>       # 恢复指定会话

定制化构建顺序

模型选择策略

上下文管理优化

基础架构

场景选择