Codex 最近风头很盛，甚至超过了 Claude Code，作为一个成熟的 AI Builder，想要像熟练使用 Claude Code 一样熟练的使用 Codex，故有了这个使用手册。不过 Codex 系列产品模式很多，这篇主要还是针对 Codex CLI 这个模式，其他的 Desktop、App、网页端暂不涉及。文章目的同样定位也是一本工具书，让我自己在使用 Codex 时遇到的一些问题或者相关使用和技巧的时候可以方便翻阅。

查了一下发现 Codex 竟然是开源的，这点比 Claude Code 优秀。由 Rust 编写，速度很快功能很丰富。

目录

• 一、Codex CLI 简介
• 二、安装与配置
• 三、配置文件详解
• 四、核心概念详解
• 五、斜杠命令详解
• 六、AGENTS.md 项目记忆文件
• 七、高级功能
• 八、实用技巧与快捷操作
• 九、最佳实践
• 十、Codex CLI vs Claude Code 对比
• 十一、总结

---

一、Codex CLI 简介

1.1 什么是 Codex CLI?

定位与 Claude Code 一样。Codex CLI 是由 OpenAI 开发的开源系统级 AI 助手，使用 Rust 语言编写，具有极高的性能和效率。它可以在终端中读取、修改和运行代码，是一个真正意义上的 AI Agent。

核心特性:

特性	说明
Rust 原生构建	极速启动和响应，内存占用极低
开源	完全开源，社区驱动，代码透明可审计
多模型支持	原生支持 OpenAI、Ollama、LM Studio、Amazon Bedrock，也可自定义接入任意兼容 API
ChatGPT 认证	支持 ChatGPT Plus/Pro/Business/Edu/Enterprise OAuth 登录，不一定要 API Key
多级 Sandbox	macOS Seatbelt、Linux bubblewrap、Windows 原生沙箱，平台级安全保障
MCP 协议	通过 Model Context Protocol 连接任意外部工具和服务
多 Agent 协作	内置 Subagent 系统，支持并行任务委派
Skills & Plugins	可复用的工作流技能包和可分发的插件系统
内置记忆系统	跨会话的 Memory 机制，自动提取和整合项目知识

---

二、安装与配置

2.1 系统要求

平台	要求
macOS	12+ (Monterey 及以上)
Linux	Ubuntu 20.04+ / Debian 10+
Windows	Windows 10/11 (原生 PowerShell 沙箱或 WSL2)
RAM	最低 4 GB，推荐 8 GB
Git	2.23+ (可选，用于版本控制功能)

2.2 安装 Codex CLI

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

npm i -g @openai/codex

方式二：Homebrew 安装（macOS）:

brew install --cask codex

方式三：从 GitHub Releases 下载二进制文件:

前往 openai/codex 的 Releases 页面，下载对应平台的预编译二进制文件。

方式四：从源码构建（Rust/Cargo）:

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

💡 仓库中还提供了 justfile，包含构建和测试的辅助命令。

验证安装:

codex --version
# 或 codex -V

# 查看帮助
codex --help

升级 Codex CLI:

npm i -g @openai/codex@latest
# 或 codex update

2.3 认证配置

Codex CLI 支持三种认证方式：

方式一：ChatGPT OAuth 登录（默认，最简单）

这是最推荐的方式，不需要 API Key，只要有 ChatGPT 订阅即可。

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

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

登录后凭证保存在本地，后续使用无需重复登录。

登出:

codex logout

# 或在交互式会话中
/logout

凭证存储方式配置（cli_auth_credentials_store）:

存储方式	说明
file	存储在本地文件
keyring	使用系统密钥链（macOS Keychain/Linux Secret Service/Windows Credential Manager）
auto	自动选择（默认）

方式二：API Key

# Linux/macOS
export OPENAI_API_KEY="sk-your-api-key"

# 永久配置
echo 'export OPENAI_API_KEY="sk-your-api-key"' >> ~/.bashrc
source ~/.bashrc

# Windows PowerShell（永久配置）
[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-api-key", "User")

方式三：通过 stdin 传入 Access Token

echo "your-access-token" | codex

2.4 配置第三方模型供应商

Codex CLI 原生支持多种模型供应商。

内置供应商

内置供应商这部分没这么用过，这部分内容只做参考和资料收集整理

供应商 ID	说明	认证方式
openai	OpenAI API（默认）	OPENAI_API_KEY 环境变量
ollama	本地模型（Ollama）	无需 Key，自动连接本地 Ollama 服务
lmstudio	本地模型（LM Studio）	无需 Key，自动连接本地 LM Studio 服务
amazon-bedrock	AWS Bedrock 托管模型	AWS Profile + Region

快速接入本地开源模型

使用 --oss 标志可以一键配置本地开源模型：

# 自动检测并连接本地 Ollama 或 LM Studio
codex --oss

在配置文件中指定默认本地供应商：

# ~/.codex/config.toml
oss_provider = "ollama"  # 或 "lmstudio"

自定义第三方供应商

主要是通过这种方式配置，通过 model_providers 配置块可以接入任意兼容 OpenAI Responses API 的服务。

自定义供应商完整参数:

参数	说明
base_url	API 基础地址
env_key	存放 API Key 的环境变量名
name	供应商显示名称
wire_api	协议类型（目前仅支持 "responses"）
http_headers	静态 HTTP 请求头
env_http_headers	从环境变量读取的 HTTP 请求头
query_params	额外查询参数
request_max_retries	HTTP 重试次数（默认 4）
stream_idle_timeout_ms	SSE 空闲超时（默认 300000ms）
stream_max_retries	SSE 重试次数（默认 5）
supports_websockets	是否支持 WebSocket 传输

配置示例

一个比较完整的 ~/.codex/config.toml 配置示例，展示如何同时配置多个供应商并使用自定义供应商作为默认：

#:schema https://developers.openai.com/codex/config-schema.json

# ---- 基础配置 ----
# 使用自定义供应商（填入你在 model_providers 中定义的 ID）
model_provider = "custom"
# 默认模型
model = "gpt-4o"

# ---- 自定义供应商配置 ----

# 示例 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"

# ---- 沙箱与审批（控制 Codex 能做什么） ----
# workspace-write：只能在工作目录内写文件
sandbox_mode = "workspace-write"
# on-request：需要确认才执行
approval_policy = "on-request"

# ---- Web 搜索，控制 Codex 是否能搜索网页以及搜索方式（cached 用缓存快但可能不是最新，live 实时抓取但慢） ----
web_search = "cached"

# ---- 配置预设，给不同场景起个名字，比如 fast 用便宜模型、work 用强模型，用 --profile fast 一键切换，不用每次手动改配置。----
[profiles.work]
model = "gpt-4o"
model_provider = "custom"
web_search = "live"

[profiles.fast]
model = "gpt-4o-mini"
model_provider = "custom"
model_reasoning_effort = "low"

[profiles.backup]
model = "gpt-4o"
model_provider = "backup"

如果不想把 key 配置在 TOML 文件中，想使用更安全的 key 读取方式，则可以通过以下方式在 Shell 里配置环境变量。好处是避免密钥明文写在配置文件里被意外提交到 Git：

# 添加到 ~/.bashrc 或 ~/.zshrc
export CUSTOM_API_KEY="sk-your-custom-api-key"
export BACKUP_API_KEY="sk-your-backup-api-key"

# 使配置生效
source ~/.bashrc

配置完成后，即可通过不同方式启动：

# 使用默认配置（custom 供应商 + gpt-4o）
codex

# 切换到快速模式 Profile
codex --profile fast

# 切换到备用供应商
codex --profile backup

# 临时指定模型
codex --model gpt-4o-mini

动态 Bearer Token（命令获取）

对于需要动态刷新 Token 的供应商：

[model_providers.my-provider.auth]
command = "my-token-generator"   # 运行哪个命令来获取 Token
args = ["--refresh"]             # 命令的参数
timeout_ms = 5000                # 命令超时 5 秒
refresh_interval_ms = 300000     # 每 5 分钟自动刷新一次
cwd = "/path/to/workdir"         # 指定运行获取 Token 的命令时的工作目录

Amazon Bedrock 配置

没玩过，供参考

[model_providers.amazon-bedrock]
# AWS 认证配置
[model_providers.amazon-bedrock.aws]
profile = "default"
region = "us-east-1"

推荐配置工具：CC Switch

与手动编辑 TOML 配置文件相比，其实更推荐使用 CC Switch 这个开源配置管理工具。

GitHub 地址: https://github.com/farion1231/cc-switch

CC Switch 支持一键管理 Claude Code、Codex CLI、Gemini CLI 等多种 AI CLI 工具的供应商配置、MCP 服务器、Skills 扩展和系统提示词。跨平台。通过图形界面快速添加和切换不同的 API 供应商配置，无需手动编辑配置文件，适合需要频繁切换不同供应商或管理多个项目的场景。会比手动配置方便很多。

2.5 一些 Codex CLI 启动参数

TUI 模式（即终端模式，默认）:

# 在当前目录启动
codex

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

# 使用本地模型
codex --oss

# 指定模型
codex --model gpt-5.4

# 使用特定 Profile
codex --profile work

非交互式 exec 模式（即跑完就退出，结果直接输出，主要用于脚本/CI 集成）:

# 单次执行
codex exec "fix the CI failure"

# JSON 格式输出
codex exec --json "summarize the codebase"

# 恢复上次的 exec 会话
codex exec resume --last "Fix the race conditions"

# 恢复指定会话
codex exec resume <SESSION_ID> "Implement the plan"

完全自主模式（跳过所有确认）:

通过命令行参数：

# ⚠️ 危险：跳过所有权限确认
codex --yolo

注意: --yolo 模式会自动将 sandbox 设为 danger-full-access，web_search 设为 live。仅在你完全信任当前任务时使用。

也可以在配置文件中永久启用（等效于每次启动都带 --yolo），通过 Profile 按需切换：

# ~/.codex/config.toml
[profiles.auto]
approval_policy = "never"              # 从不询问确认
sandbox_mode = "danger-full-access"    # 无沙箱限制
web_search = "live"                    # 实时搜索

[profiles.safe]
approval_policy = "on-request"         # on-request：需要确认才执行
sandbox_mode = "workspace-write"       # workspace-write：只能在工作目录内写文件
web_search = "cached"				   # 使用 cached 可能不是最新                  # 实时搜索

# 需要自主执行时
codex --profile auto

# 回到安全模式
codex --profile safe

建议: 不要把 never + danger-full-access 写在默认配置里。推荐用 Profile 方式，需要时手动切换，避免误操作。

---

三、补充配置说明

Codex CLI 使用 TOML 格式的配置文件（不是 JSON），拥有多层级的配置体系和极其丰富的参数。这是与 Claude Code（使用 JSON）的一个显著区别。

3.1 配置文件层级

Codex 使用多层配置体系，优先级从高到低：

层级	位置	作用域
CLI 参数	命令行 --model 等	当前命令
Profile 值	--profile 指定	命名预设
项目配置	.codex/config.toml	当前仓库
用户配置	~/.codex/config.toml	个人全局
系统配置	/etc/codex/config.toml	机器级默认

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

⚠️ 重要: 项目级配置不能覆盖以下安全敏感字段：openai_base_url、chatgpt_base_url、model_provider、model_providers、notify、profile、profiles 等。这些只能在用户级或系统级配置中设置。

覆盖默认主目录:

# 使用自定义的 CODEX_HOME 目录
export CODEX_HOME=/path/to/custom/home
# 配置文件将从 /path/to/custom/home/config.toml 读取

3.2 核心配置参数

在配置文件顶部添加 schema 声明可获得 IDE 自动补全支持：

#:schema https://developers.openai.com/codex/config-schema.json

模型相关配置

# ~/.codex/config.toml

# 使用的模型名称
model = "gpt-5.5"

# 模型供应商 ID（内置: openai, ollama, lmstudio, amazon-bedrock）
model_provider = "openai"

# 推理努力程度: "minimal" | "low" | "medium" | "high" | "xhigh"
# 类似 Claude Code 的 Extended Thinking 模式
model_reasoning_effort = "medium"

# 推理摘要: "auto" | "concise" | "detailed" | "none"
model_reasoning_summary = "auto"

# 上下文窗口大小（token 数）
model_context_window = 200000

# 模型输出详细程度: "low" | "medium" | "high"
model_verbosity = "medium"

# 服务层级: "flex"（弹性） | "fast"（快速）
service_tier = "fast"

💡使用技巧: model_reasoning_effort 是一个非常影响使用体感的配置。对于简单任务设为 "low" 可以获得更快的响应，对于复杂架构设计设为 "high" 或 "xhigh" 可以获得更深入的推理。

审批与沙箱配置

Codex CLI 的安全体系由沙箱（Sandbox）和审批策略（Approval Policy）两层配合工作：沙箱定义技术边界（能做什么），审批策略决定何时需要人工确认。

# 审批策略
# "untrusted" - 不受信任，需要确认（最安全）
# "on-request" - 按需确认
# "never" - 从不确认（最自由）
approval_policy = "on-request"

# 细粒度审批策略（高级）
# approval_policy = { granular = { sandbox_approval = true, rules = true, mcp_elicitations = true, request_permissions = true, skill_approval = true } }

# 沙箱模式
# "read-only" - 只读，不能修改文件或运行命令
# "workspace-write" - 工作区写入（默认）
# "danger-full-access" - 完全访问（危险）
sandbox_mode = "workspace-write"

# 自动审批审阅者: "user"（人工） | "auto_review"（AI 自动审阅）
approvals_reviewer = "user"

# 额外可写目录（workspace-write 模式下默认只能在工作区内写文件，
# 读取不受限制——可以读机器上任意文件，只是不能在工作区外写入）
# 如果需要 Codex 往工作区外写文件，在这里添加：
# sandbox_workspace_write.writable_roots = ["/tmp/codex-output"]

# 工作区写入模式下是否允许命令联网（默认 false）
# sandbox_workspace_write.network_access = false

# 默认权限配置
# ":read-only" - 只读权限
# ":workspace" - 工作区权限
# ":danger-no-sandbox" - 无沙箱
# 或自定义权限名
default_permissions = ":workspace"

⚠️ 重要提示: sandbox_mode 直接影响 Codex 能做什么。如果你在 Windows 上使用，沙箱机制是原生 Windows 沙箱；macOS 使用 Seatbelt 框架（无需额外安装）；Linux 需要 bubblewrap (sudo apt install bubblewrap)。

关于沙箱读取和写入权限的说明:

在 workspace-write 模式下：

• 读取：不受限制，可以读取机器上任意路径的文件
• 写入：只能在工作区目录内写文件。如果需要在工作区外写入，需配置 writable_roots

关于 network_access 和 web_search 的区别（重要）:

这是两个容易混淆的配置，控制的是完全不同的层面：

配置	控制什么	默认值	举个例子
web_search	Codex 自身是否使用内置搜索工具搜索网页	"cached"	Codex 帮你查文档、搜解决方案
network_access	Codex 执行的命令是否允许联网	false	npm install、git clone、pip install 等需要下载东西的命令

network_access 不是"写入时需要网络"的意思，而是说在 workspace-write 沙箱模式下，Codex 启动的子命令（npm、git、pip、curl 等）是否被允许联网。最典型的场景就是 npm install——Codex 帮你装依赖包，但装包需要联网下载，默认是被沙箱拦截的，需要你手动确认。

不同沙箱模式下命令联网行为汇总:

场景	sandbox_mode	network_access	npm install 等命令
默认（安全）	workspace-write	false（默认）	被拦截，需要手动确认
开发推荐	workspace-write	手动设为 true	直接执行，无需确认
完全自主	danger-full-access	不需要配（无沙箱限制）	直接执行
--yolo	自动变为 danger-full-access	不需要配	直接执行

💡 使用建议: 如果觉得每次执行 npm install 都要确认很烦，可以在配置中把 network_access 设为 true，这样保持 workspace-write 的文件写入保护，同时让联网命令畅通无阻。不需要为了联网而把整个沙箱关掉。

💡 与 Claude Code 的对比: Claude Code 的 --dangerously-skip-permissions 直接跳过一切确认，没有中间层。Codex CLI 更精细——在 workspace-write 下默认拦截网络操作，你要么单独开 network_access = true，要么升到 danger-full-access。

Web 搜索配置

# Web 搜索模式
# "cached" - 使用 OpenAI 维护的缓存索引（默认，快速）
# "live" - 实时抓取最新网页数据
# "disabled" - 禁用 web 搜索
web_search = "cached"

# 细粒度 web 搜索配置
# [tools.web_search]
# context_size = "medium"
# allowed_domains = ["docs.python.org", "developer.mozilla.org"]
# location = "us"

💡 使用技巧: 日常使用 "cached" 模式即可，响应快且成本更低。只有在需要最新信息（如查看最新文档或新闻）时才切换到 "live"。使用 --yolo 模式时会自动切换为 "live"。

TUI（终端 UI）配置

# 语法高亮主题
# tui.theme = "dracula"

# 默认启用 Vim 模式
# tui.vim_mode_default = false

# 原始输出模式（不格式化）
# tui.raw_output_mode = false

# 状态栏配置
# tui.status_line = []

# 终端窗口标题
# tui.terminal_title = []

# 桌面通知
# tui.notifications = false

# 动画效果
# tui.animations = true

# 备用屏幕模式: "auto" | "always" | "never"
# tui.alternate_screen = "auto"

# 自定义键位映射
# [tui.keymap.composer]
# submit = "enter"
# newline = "shift+enter"

记忆系统配置

# 记忆系统（默认关闭，需要手动开启）
# features.memories = true

[memories]
# 注入已有记忆到上下文（默认 true）
use_memories = true
# 生成新记忆（默认 true）
generate_memories = true
# 用于单线程记忆提取的模型
# extract_model = "gpt-5.4-mini"
# 用于全局记忆整合的模型
# consolidation_model = "gpt-5.4"
# 线程最大保留天数（默认 30）
max_rollout_age_days = 30
# 每次启动最大处理的线程数（默认 16）
max_rollouts_per_startup = 16
# 线程最小空闲时间（小时，默认 6）
min_rollout_idle_hours = 6

⚠️ 重要: 记忆系统默认是关闭的。你需要在配置中显式设置 features.memories = true 才能启用。启用后，Codex 会在你使用过程中自动提取和整合项目知识。

Shell 环境策略

[shell_environment_policy]
# 环境变量继承: "all" | "core" | "none"
inherit = "all"
# 白名单模式（仅包含匹配的变量）
# include_only = ["PATH", "HOME"]
# 排除匹配的变量
# exclude = ["*_SECRET", "*_TOKEN"]
# 显式设置环境变量
# set = { MY_VAR = "value" }
# 忽略默认排除列表（保留 KEY/SECRET/TOKEN 等变量）
# ignore_default_excludes = false

Agent 配置

[agents]
# 最大并发 Agent 线程数（默认 6）
max_threads = 6
# 最大嵌套深度（默认 1）
max_depth = 1
# 每个 Worker 的超时时间（秒，默认 1800 = 30分钟）
job_max_runtime_seconds = 1800

# 定义命名 Agent 角色
# [agents.code-reviewer]
# description = "专业代码审查 Agent"
# config_file = "~/.codex/agents/reviewer.toml"
# nickname_candidates = ["Reviewer", "CodeCop", "Inspector"]

Agent 机制说明:

日常使用不需要手动配置。multi_agent 功能默认启用，max_threads = 6、max_depth = 1 这些都有内置默认值，开箱即用。Codex 在需要时会自动 spawn 子 Agent，不需要你提前定义。

• 并行多 Agent — max_threads = 6 意味着最多同时跑 6 个子 Agent 并行工作。比如你说"同时审查代码安全性、写测试、生成文档"，Codex 可能 spawn 3 个子 Agent 并行跑，结果汇总回主 Codex。
• 嵌套深度 — max_depth = 1 表示只有一层：主 Codex → 子 Agent。子 Agent 不能再往下 spawn 孙 Agent。如果设为 2，就可以 主 Codex → 子 Agent → 孙 Agent。默认 1 层足够用，避免无限套娃消耗 token。
• 主从关系 — 所有子 Agent 都是主 Codex 派出去干活的工人，干完回来汇报。Agent 之间不能互相通信，是单向的主从关系。

与 Claude Code 的 Agent Teams 对比:

维度	Codex CLI Agent	Claude Code Team
协作模式	主从派生（工具调用）	平等协作（消息传递）
通信方式	spawn_agent / wait_agent	SendMessage 双向通信
任务管理	无独立任务系统	TaskCreate / TaskList / TaskUpdate
适用场景	简单并行干活	复杂团队协作

两者是不同的设计理念。Codex 的 Agent 更轻量，适合"分头干活、汇总结果"的场景；Claude Code 的 Team 更像正式的项目团队协作。

人格配置

# AI 人格风格
# "none" - 无特殊人格（默认）
# "friendly" - 友好型
# "pragmatic" - 务实型
personality = "none"

3.3 Profiles（配置预设）

Profiles 允许你创建命名配置预设，快速切换不同的工作模式：

# ~/.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"

使用 Profile:

# 命令行指定
codex --profile work

# 或在配置文件中设置默认 Profile
# profile = "work"

3.4 requirements.toml（管理员强制约束）

这是 Codex CLI 独有的企业级安全特性（个人开发者用不到）。requirements.toml 是管理员强制执行的配置文件，用户无法覆盖其中的设置：

# /etc/codex/requirements.toml

# 限制允许的审批策略
allowed_approval_policies = ["on-request", "never"]

# 限制允许的沙箱模式
allowed_sandbox_modes = ["read-only", "workspace-write"]

# 限制 Web 搜索模式
allowed_web_search_modes = ["cached", "disabled"]

# 限制审批审阅者
allowed_approvals_reviewer = ["user"]

# 网络访问控制
# [experimental_network]
# allowed_domains = ["api.internal.com"]
# denied_domains = ["*.external.com"]

# 强制功能开关
# [features]
# memories = false
# network_proxy = false

# 允许的 MCP 服务器白名单
# mcp_servers = ["github", "postgres"]

# 文件系统读取限制
# [permissions.filesystem]
# deny_read = ["/etc/secrets/*"]

# 托管 Hooks（仅允许管理员定义的 Hooks）
# allow_managed_hooks_only = true

💡 企业场景价值: requirements.toml 让安全管理员可以统一约束所有开发者的 Codex 使用行为，防止不当操作。这是 Claude Code 所不具备的。

---

四、核心概念详解

Codex CLI 的核心概念与 Claude Code 有许多相似之处（如 MCP、Skills），也有一些独特的机制。

4.1 Approval Modes（审批模式）

Codex CLI 有三种审批模式，控制 AI 可以自主做什么：

模式	读取文件	编辑文件	运行命令	网络访问
Auto（默认）	✅ 自由	✅ 工作区内	✅ 本地命令	❌ 需确认
Read-only	✅ 自由	❌ 需确认	❌ 需确认	❌ 需确认
Full Access	✅ 自由	✅ 全局	✅ 所有命令	✅ 自由

切换审批模式:

# 在交互式会话中
/permissions

# 或使用 CLI 参数
codex --sandbox read-only
codex --full-access

# 或在配置文件中
# approval_policy = "never"
# sandbox_mode = "danger-full-access"

细粒度审批策略:

# 启用细粒度控制
approval_policy = { granular = { sandbox_approval = true, rules = true, mcp_elicitations = true, request_permissions = true, skill_approval = true } }

最佳实践:

• 日常开发使用默认的 Auto 模式
• 代码审查使用 Read-only 模式
• CI/CD 自动化使用 Full Access 模式
• 敏感项目始终使用细粒度策略

4.2 Auto-Review System（自动审阅系统）

这是 Codex CLI 独有的功能。默认情况下，当 Codex 遇到超出沙箱边界的操作（比如访问工作区外的文件、执行未知的命令），会暂停弹窗问你确认。auto_review 的作用是让一个 AI 子代理代替你做审批决策，而不是每次都打断你。

三种处理审批弹窗的方式对比:

方式	配置	谁做决策	安全性	便利性
手动确认	approvals_reviewer = "user"	你	最高	最烦（频繁打断）
自动审阅	approvals_reviewer = "auto_review"	AI 审批代理	中高（有安全过滤）	高
跳过审批	approval_policy = "never"	无人	最低	最高

# 推荐配置：保留审批机制，但交给 AI 处理
approval_policy = "on-request"          # 超出沙箱时仍需审批
approvals_reviewer = "auto_review"      # 审批交给 AI 而不是你

# 配置自动审阅策略（本地 Markdown 文件）
# auto_review.policy = "~/.codex/auto-review-policy.md"

# 或使用托管策略配置（优先级更高，企业场景）
# guardian_policy_config = { ... }

auto_review.policy 是什么:

就是给 AI 审批代理定的规则文件（Markdown 格式，用自然语言写），告诉它哪些操作直接放行、哪些必须拒绝、哪些还需要转问用户。

自动审阅策略文件示例:

<!-- ~/.codex/auto-review-policy.md -->
# Auto Review Policy

## Always Allow
- Reading any file in the project
- Running npm test, npm run lint, npm run build
- Creating new files in src/ and tests/

## Always Deny
- Deleting files outside the project directory
- Running commands with sudo
- Accessing network URLs not in allowlist

## Ask User
- Modifying configuration files (tsconfig.json, package.json)
- Running npm install or adding dependencies
- Any git push operations

关于 token 消耗:

启用 auto_review 后，每次触发审批时会额外消耗一次 API 调用的 token。但它是按需触发的——不是启动 Codex 时就常驻一个 Agent，而是只有 Codex 实际遇到需要审批的操作时，才临时调用一次 AI 做评估，评估完就结束。如果整个会话都在沙箱内工作没有触发审批，auto_review 就一次都不会被调用，零额外消耗。

使用建议:

如果用的是 workspace-write + on-request，且经常被审批弹窗打断，开 auto_review 能换来流畅的使用体验，额外 token 消耗值得。如果本身弹窗不多，开了反而多此一举。

4.3 Subagents（子代理）

与 Claude Code 类似，Codex CLI 也支持子代理系统，但机制有所不同。这里的 Subagents 和前面配置文件详解里的 Agent 配置是同一套东西——前面讲的是配置文件的写法，这里讲的是使用时的说明。

另外简单列举一下 Codex 内部用来管理 Subagents 生命周期的一套工具核心工具（Codex 内部调用，用户用不到也无法直接调用）： spawn_agent、send_input、resume_agent、wait_agent、close_agent

配置 Agent:

# ~/.codex/config.toml

[agents]
max_threads = 6    # 最大并发线程
max_depth = 1      # 最大嵌套深度

# 定义 code-reviewer Agent
[agents.code-reviewer]
description = "专业代码审查 Agent，专注于代码质量、安全漏洞和性能问题"
config_file = "~/.codex/agents/reviewer.toml"
nickname_candidates = ["Reviewer", "Inspector", "CodeCop"]

# 定义 test-writer Agent
[agents.test-writer]
description = "测试工程师 Agent，专注于编写全面的单元测试和集成测试"
nickname_candidates = ["Tester", "QA", "TestBot"]

配置字段说明:

字段	说明
description	Agent 的角色描述，告诉它应该专注做什么
config_file	给这个 Agent 单独指定一个 TOML 配置文件。全局 [agents] 的配置对所有 Agent 生效，但如果某个 Agent 需要特殊配置（比如不同的沙箱策略、不同的模型），就给它单独写一个配置文件指向这里
nickname_candidates	Agent 的显示名候选列表。Codex spawn 子 Agent 时会从中选一个作为终端里的显示名，方便你识别是哪个 Agent 在工作。纯粹显示用途，不影响功能

如何给子 Agent 指定不同模型:

agents 配置块里没有直接的 model 字段。给特定 Agent 指定模型有两种方式：

1. 通过 config_file — 给 Agent 单独写一个 TOML 文件，里面指定 model = "gpt-5.4-mini"
2. 通过自然语言 — 在对话中直接告诉 Codex "用 gpt-5.4-mini 模型来跑这个审查任务"，Codex 会自动处理

# ~/.codex/agents/reviewer.toml（单独的 Agent 配置文件）
model = "gpt-5.4-mini"
sandbox_mode = "read-only"

使用 Agent:

# 在 Codex 中请求使用特定 Agent
请使用 code-reviewer agent 审查 src/auth.ts 的代码质量

# 并行使用多个 Agent
请使用以下 agents 并行工作:
1. code-reviewer 审查代码质量
2. test-writer 编写测试用例

模型推荐（使用建议）:

用途	推荐模型	理由
复杂多步骤任务	gpt-5.5	能力最强
通用任务	gpt-5.4	平衡性能和成本
只读扫描/并行 Worker	gpt-5.4-mini	快速且便宜

💡 与 Claude Code 的区别: Claude Code 有正式的 Team 概念（TeamCreate/TaskCreate/TaskList），Codex CLI 的 Agent 系统更轻量，通过工具调用而非消息传递来协作。

4.4 Skills（技能包）

Skills 概念与 Claude Code 一致，它是预封装的可复用工作流。一个 Skill 是一个 SKILL.md 文件加可选的脚本和资源。

Skills 的概念在 Claude Code 完全指南：使用方式、技巧与最佳实践 和 从对话到协作，Skills 如何改变我们与 AI 共事的方式有更详细的说明。这里不做重复说明，只简单提及

Skill 目录结构:

my-skill/
├── SKILL.md          # 必需：指令和元数据
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：文档
└── assets/           # 可选：模板和资源

SKILL.md 格式:

---
name: commit
description: Stage and commit changes in semantic groups.
---
1. Do not run `git add .`. Stage files in logical groups.
2. Group into separate commits: feat, test, docs, refactor, chore.

Skill 存放位置:

位置	说明
$HOME/.agents/skills	全局 Skill
.agents/skills（项目目录）	项目级 Skill

使用 Skill:

# 在会话中浏览可用 Skills
/skills

在配置中启用特定 Skill：

# config.toml
# skills.config = ["commit", "frontend-design"]

4.5 Plugins（插件系统）

Plugins 是可分发的扩展包，将 Skills、应用集成和 MCP 服务器打包在一起，一键安装即可使用。

管理插件:

# 浏览和安装插件（交互式界面）
/plugins

# 从命令行添加 marketplace
codex plugin marketplace add <source>

在 /plugins 交互式界面中可以浏览、安装、卸载、启用/禁用插件。安装后通过自然语言或 @插件名 调用。

禁用已安装的插件（不改代码）:

# ~/.codex/config.toml
[plugins."gmail@openai-curated"]
enabled = false

与 Claude Code Plugins 的对比:

两者核心概念相同（可分发的扩展集合），但在插件内容、安装方式和生态上有明显区别：

1. 插件包含的内容不同:

能力	Codex CLI	Claude Code
Skills	✅	✅
Apps（预对接应用）	✅（Gmail、Google Drive、Slack 等开箱即用）	❌ 没有 Apps 概念
MCP 服务器	✅	✅
Agents	❌	✅
Hooks	❌	✅
LSP 代码智能	❌	✅（内置多语言 LSP 插件）

Codex 多了一个 Apps 概念——预对接好的外部应用（如 Gmail、Google Drive），安装后直接可用，不需要自己配 MCP。Claude Code 没有这个，外部集成全靠 MCP 手动配置。反过来，Claude Code 的插件可以携带自定义 Agent、Hook 脚本、甚至 LSP 语言服务器配置，Codex 的插件不支持这些。

2. 安装和管理方式不同:

操作	Codex CLI	Claude Code
浏览安装	/plugins 交互式界面	/plugin 交互式界面 + /plugin install 命令
添加市场	codex plugin marketplace add <source>	/plugin marketplace add <source>
禁用插件	在 config.toml 中 enabled = false，需重启	/plugin disable + /reload-plugins 热重载
安装范围	统一	User / Project / Local / Managed 四种范围
自动更新	不支持	官方市场默认自动更新

3. 生态侧重不同:

• Codex CLI 插件偏"应用集成"方向——帮你接好 Gmail、Slack、Google Drive 等外部服务，安装即用
• Claude Code 插件偏"开发工具扩展"方向——Agent、Hook、LSP 代码智能，更面向开发工作流

4.6 MCP (Model Context Protocol)

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

Codex CLI 配置 MCP:

# ~/.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 服务器
[mcp_servers.remote-server]
url = "https://mcp.example.com/sse"
# （只支持 Bearer Token）
bearer_token_env_var = "MCP_TOKEN"

MCP 高级配置:

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_xxx" }
enabled = true                          # 是否启用
# enabled_tools = ["search_repositories"]  # 工具白名单
# disabled_tools = ["delete_repository"]   # 工具黑名单
default_tools_approval_mode = "auto"    # "auto" | "prompt" | "approve"
startup_timeout_sec = 10                # 启动超时（默认 10s）
tool_timeout_sec = 60                   # 工具调用超时（默认 60s）
required = true                         # 服务不可用时是否报错

Codex 作为 MCP 服务器:

Codex CLI 自身也可以作为 MCP 服务器运行：

codex mcp-server

查看 MCP 状态:

# 在交互式会话中
/mcp

# 详细模式
/mcp verbose

4.7 Lifecycle Hooks（生命周期钩子）

Hooks 在特定生命周期事件触发时自动执行外部命令，通过 JSON stdin/stdout 协议 通信，用于实现自定义安全检查、日志记录、通知等工作流。

配置方式

支持两种格式：

格式	文件名	说明
JSON	hooks.json	独立文件，适合 hooks 较多、单独管理的场景
TOML	config.toml 中的 [hooks] 段	内联在主配置文件中，适合少量 hooks

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

层级	路径	说明
System	/etc/codex/config.toml（Windows: %ProgramData%\codex\config.toml）	系统级
User	~/.codex/config.toml 或 ~/.codex/hooks.json	用户级全局
Project	.codex/config.toml 或 .codex/hooks.json	项目级
Managed	requirements.toml 中 hooks.managed_dir 指定的目录	企业托管，自动受信

支持的 Hook 事件（8 种）

官方文档记录了 6 种，源码中还有 2 种（PreCompact / PostCompact）：

事件	触发时机	能否阻断	Matcher 匹配对象
SessionStart	会话启动时	否	无
PreToolUse	工具调用前	是（deny 阻止执行）	工具名称
PostToolUse	工具调用后	是（block 阻止继续）	工具名称
Stop	模型停止生成时	是（block 让模型继续）	无
Notification	通知触发时	否	无
SubAgentStop	子代理停止时	否	无
PreCompact	上下文压缩前	是	trigger 值（"manual" / "auto"）
PostCompact	上下文压缩后	是	trigger 值

配置字段详解

每个 hook 条目的结构：

{
  "matcher": { "group": "<正则表达式>" },
  "hooks": [
    {
      "type": "command",
      "command": "<shell 命令>",
      "command_windows": "<Windows 专用命令>",
      "timeout_sec": 60,
      "status_message": "执行时显示的状态消息"
    }
  ]
}

字段	类型	必填	默认值	说明
matcher.group	string	否	—	正则匹配，PreToolUse/PostToolUse 匹配工具名（如 "bash", "write|edit"），PreCompact/PostCompact 匹配 trigger
type	string	是	—	目前只有 "command" 生效（prompt 和 agent 类型在源码中存在但当前被跳过）
command	string	是	—	要执行的 shell 命令
command_windows	string	否	—	Windows 平台替代命令，存在时优先于 command 使用
timeout_sec	number	否	600	超时秒数（最小值 1）
status_message	string	否	—	执行时在终端显示给用户的状态消息

通信协议（stdin/stdout JSON）

Hook 命令通过 stdin 接收 JSON 输入，通过 stdout 返回 JSON 输出。

输入字段（所有事件共有）：

{
  "session_id": "uuid-string",
  "hook_event_name": "PreToolUse"
}

各事件额外输入：

事件	额外输入字段
PreToolUse	tool_name, tool_input（object）
PostToolUse	tool_name, tool_input（object）, tool_output（string）
Notification	message, title
Stop / SubAgentStop	stop_hook_active（boolean）
PreCompact / PostCompact	turn_id, cwd, transcript_path, model, trigger

输出字段（按事件类型）：

事件	输出字段	作用
PreToolUse	deny(bool), reason(string)	deny: true 阻止工具执行
PostToolUse	block(bool), reason(string)	block: true 阻止后续操作
Stop	block(bool), reason(string)	block: true 让模型继续生成
PreCompact / PostCompact	continue(bool)	continue: false 阻止/中断压缩
其他	—	仅支持通用 status_message

退出码语义：0 = 通过，2 = 阻断（stderr 内容作为 reason），其他 = 失败。

信任系统

Hook 有信任状态管理，新加的 hook 第一次运行时 Codex 会要求用户确认是否信任：

状态	说明
Managed（托管）	企业 managed_dir 中的 hook，自动受信
Trusted（已信任）	SHA-256 哈希匹配用户之前审批过的记录
Modified（已修改）	哈希不匹配，需重新审查
Untrusted（未受信）	首次遇到的 hook，需用户审批

配置示例

hooks.json 方式（推荐 hooks 较多时使用）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": { "group": "bash" },
        "hooks": [
          {
            "type": "command",
            "command": "python3 /scripts/check-bash-safety.py",
            "timeout_sec": 30,
            "status_message": "检查 bash 命令安全性..."
          }
        ]
      },
      {
        "matcher": { "group": "write|edit" },
        "hooks": [
          {
            "type": "command",
            "command": "python3 /scripts/check-file-write.py",
            "timeout_sec": 15
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": { "group": "bash" },
        "hooks": [
          {
            "type": "command",
            "command": "python3 /scripts/log-command.py"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": {},
        "hooks": [
          {
            "type": "command",
            "command": "python3 /scripts/init-session.py"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": {},
        "hooks": [
          {
            "type": "command",
            "command": "python3 /scripts/on-stop-notify.py",
            "status_message": "发送停止通知..."
          }
        ]
      }
    ]
  }
}

config.toml 内联方式：

[hooks]

[[hooks.PreToolUse]]
matcher = { group = "bash" }

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 /scripts/check-bash-safety.py"
timeout_sec = 30
status_message = "检查 bash 命令安全性..."

[[hooks.PreToolUse]]
matcher = { group = "write|edit" }

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 /scripts/check-file-write.py"
timeout_sec = 15

Hook 脚本示例（Python — 拦截危险 bash 命令）：

#!/usr/bin/env python3
import json, sys

data = json.loads(sys.stdin.read())
tool_input = data.get("tool_input", {})
command = tool_input.get("command", "")

for pattern in ["rm -rf /", "DROP TABLE"]:
    if pattern.lower() in command.lower():
        print(json.dumps({"deny": True, "reason": f"危险命令: {pattern}"}))
        sys.exit(0)

print(json.dumps({}))
sys.exit(0)

企业级 Hooks 管理

通过 requirements.toml 可以限制只允许管理员定义的 Hooks：

# requirements.toml
[requirements.hooks]
allow_managed_hooks_only = true
managed_dir = ["/etc/codex/managed-hooks"]           # Linux/macOS
windows_managed_dir = ["C:\\ProgramData\\codex\\managed-hooks"]  # Windows

4.8 Memories（记忆系统）

Codex CLI 内置了跨会话的自动记忆系统（默认关闭），这是与 Claude Code 的一个重要区别。Claude Code 的记忆是通过手动维护的 MEMORY.md 文件实现的，而 Codex 的记忆是全自动提取和整合的——无需手动编写。

核心概念

• Rollout（会话记录）: 每次对话会话（无论是 CLI、VSCode 扩展还是其他客户端）都会生成一个 Rollout，以 .jsonl 格式持久化存储在 ~/.codex/sessions/ 中
• Thread（线程）: 等同于一个对话会话，是记忆提取的基本单位
• Memory: 从 Rollout 中提取出的结构化知识，存储在 ~/.codex/memories/ 目录中

记忆的三阶段管道

Rollout (.jsonl) ──Phase 1──> Raw Memory ──Phase 2──> Consolidated Memory ──Injection──> 新会话上下文
  (会话记录)        (提取)      (原始记忆)      (整合)       (整合记忆)         (注入)      (自动注入)

Phase 1 — 线程级提取（Extraction）

每次会话结束后，使用 extract_model（默认 gpt-5.4-mini）从 Rollout 中提取关键知识，生成：

输出	说明
raw_memory	从对话中提取的原始知识片段
rollout_summary	该次会话的摘要
rollout_slug	会话的简短标识名

Phase 1 最多可并行执行 8 个提取任务，每个任务会使用模型约 70% 的上下文窗口。

Phase 2 — 全局整合（Consolidation）

使用 consolidation_model（默认 gpt-5.4）将所有原始记忆整合为全局知识库，生成：

文件	说明
MEMORY.md	完整的结构化记忆文件
memory_summary.md	截断摘要版（注入上下文时使用，上限 2500 token）
raw_memories.md	所有原始记忆的合集
rollout_summaries/	各会话的摘要目录
skills/	提取出的可复用技能
extensions/	扩展信息

Phase 2 会启动一个受限沙箱中的完整 agent 会话来执行整合。

Phase 3 — 自动注入（Injection）

新会话启动时，Codex 读取 memory_summary.md（截断到 2500 token 以内）并注入到 developer instructions 中，让模型自动获得历史知识。

存储结构

~/.codex/
├── sessions/              # 会话记录（Rollout）
│   └── *.jsonl            # 每个会话一个文件
└── memories/              # 记忆数据
    ├── MEMORY.md          # 完整结构化记忆
    ├── memory_summary.md  # 摘要（注入上下文用）
    ├── raw_memories.md    # 原始记忆合集
    ├── rollout_summaries/ # 会话摘要
    ├── skills/            # 提取的技能
    └── extensions/        # 扩展信息

记忆是用户级全局的，不按项目隔离（但每个 Rollout 会记录当时的 cwd，所以实际上可以区分不同项目的知识）。

记忆内容类型

系统会自动提取以下类型的知识：

类型	示例
用户偏好	喜欢使用 pnpm 而非 npm、偏好函数式组件
过程性知识	项目部署流程、调试步骤
任务图谱	当前项目的任务进度、待办事项
环境/工作流	项目使用的框架版本、构建工具配置
决策记录	为什么选择 X 方案而非 Y

启用与配置

# ~/.codex/config.toml

# 第一步：开启功能标志（默认关闭）
[features]
memories = true

# 第二步：配置记忆参数（均可选，有默认值）
[memories]
# 注入已有记忆到上下文（默认 true）
use_memories = true
# 生成新记忆（默认 true）
generate_memories = true
# 用于单线程记忆提取的模型（越便宜越好，默认 gpt-5.4-mini）
extract_model = "gpt-5.4-mini"
# 用于全局记忆整合的模型（需要较强能力，默认 gpt-5.4）
consolidation_model = "gpt-5.4"
# 线程最大保留天数（默认 30）
max_rollout_age_days = 30
# 每次启动最大处理的线程数（默认 16）
max_rollouts_per_startup = 16
# 线程最小空闲时间（小时，默认 6，避免频繁处理正在进行的会话）
min_rollout_idle_hours = 6

⚠️ Token 消耗提醒: 记忆系统会消耗额外的 API Token。Phase 1 每个会话会调用一次 extract_model，Phase 2 整合时会启动一个完整的 agent 会话。如果关注成本，可以将 extract_model 设为更便宜的模型。

安全与隐私机制

机制	说明
Secrets 脱敏	提取前自动移除 API Key、密码等敏感信息
Rate Limit 保护	API 配额剩余 < 25% 时跳过记忆生成
AGENTS.md 排除	Phase 1 提取时排除 AGENTS.md 的内容，避免项目配置污染全局记忆
非递归	记忆生成过程不会触发新的记忆提取
Symlink 安全检查	防止通过符号链接攻击记忆文件

管理记忆

# 在交互式会话中切换记忆开关
/memories
# 该命令会切换 use_memories 和 generate_memories 设置

也可以直接编辑 ~/.codex/memories/MEMORY.md 来手动修正或删除不需要的记忆。

与 Claude Code 记忆系统对比

维度	Codex CLI	Claude Code
生成方式	全自动（AI 提取 + 整合）	手动维护
存储位置	~/.codex/memories/	.claude/memory/ 目录下
记忆格式	AI 生成的结构化 Markdown	用户手写的 Markdown
注入方式	memory_summary.md 自动注入（2500 token 上限）	MEMORY.md 索引自动加载
粒度	用户级全局（跨项目）	支持用户级 + 项目级
与 AGENTS.md 关系	互补（AGENTS.md 不参与记忆提取）	与 CLAUDE.md 互补（均可手动编辑）

4.9 Feature Flags（功能标志）

Codex CLI 有一个完善的功能标志系统，每个功能有成熟度标记：

# 查看所有功能标志
codex features list

# 启用/禁用功能
codex features enable unified_exec
codex features disable shell_snapshot

主要功能标志:

功能	默认	成熟度	说明
multi_agent	true	Stable	多 Agent 协作
unified_exec	true (非 Windows)	Stable	统一命令执行
shell_snapshot	true	Stable	Shell 快照
fast_mode	true	Stable	快速模式
personality	true	Stable	AI 人格
hooks	false	Stable	生命周期钩子
memories	false	Stable	记忆系统
network_proxy	false	Experimental	网络代理
apps	false	Experimental	应用连接器
undo	false	Stable	撤销操作

4.10 Web Search（网络搜索）

Codex CLI 内置了三种 Web 搜索模式：

模式	说明	适用场景
"cached"	使用 OpenAI 维护的缓存索引（默认）	日常查询，速度快
"live"	实时抓取最新网页数据	需要最新信息
"disabled"	禁用搜索	离线/安全场景

4.11 Image Support（图片支持）

Codex CLI 原生支持图片输入和图片生成，无需额外配置或安装。

图片输入

支持三种方式向 Codex 传入图片：

方式一：命令行参数（-i / --image）

# 分析单张截图
codex -i screenshot.png "解释这个报错信息"

# 分析多张图片（逗号分隔）
codex --image img1.png,img2.jpg "对比这两张架构图的区别"

# 结合其他参数使用
codex -i error.png --model gpt-4o "这个错误怎么修复？"

方式二：TUI 中直接粘贴剪贴板截图

在交互式会话中，可以直接 Ctrl+V（或对应平台的粘贴快捷键）粘贴剪贴板中的图片：

剪贴板内容	处理方式
复制的图片（从浏览器截图等）	自动编码为 PNG，保存到临时文件（前缀 codex-clipboard-）
复制的文件引用（从文件管理器复制的图片）	自动解析文件路径
WSL 环境	自动调用 Windows 侧 PowerShell 提取剪贴板图片

粘贴后图片会以占位符形式显示在输入框中，提交时自动作为附件发送。

方式三：本地文件路径引用

在对话中直接提供本地图片路径，Codex 会自动识别并读取。

支持的图片格式：

格式	说明
PNG	原生支持，直接传递
JPEG/JPG	原生支持，直接传递
WebP	原生支持，直接传递
GIF	支持，但会重新编码为 PNG（动画帧不会单独保留）

所有图片在发送前会自动缩放至 2048×2048 像素以内，并编码为 base64 data URL。

图片生成

Codex CLI 内置了 imagegen 技能（skill），使用 gpt-image-2 模型生成图片，无需额外安装。

生成方式一：自然语言请求

直接用自然语言描述你想要的图片，Codex 会自动调用图片生成：

> 帮我生成一张日落山脉的图片
> Create an image of a sunset over mountains
> 画一个简洁的 Logo，蓝白配色，科技感

生成方式二：显式调用 $imagegen

在提示词中包含 $imagegen 可以直接触发图片生成技能：

> $imagegen 生成一个现代风格的网站首页设计稿

注意事项：

• 图片生成会以 3-5 倍 的速度消耗使用额度，请谨慎使用
• 生成质量取决于模型能力，复杂场景可能需要多次尝试
• 生成的图片会在对话中直接展示

常见使用场景

场景	操作方式
报错排查	Ctrl+V 粘贴报错截图，让 Codex 分析原因和修复方案
UI 审查	传入设计稿图片，让 Codex 对比实现效果
图表分析	-i chart.png 传入数据可视化图表，让 Codex 提取关键数据
代码截图	粘贴代码截图，让 Codex 提取代码并修改
设计生成	用自然语言描述需求，让 Codex 生成设计图

---

五、斜杠命令详解

Codex CLI 拥有 35+ 个内置斜杠命令，比 Claude Code 丰富得多。以下是完整列表和详细说明。

5.1 会话管理命令

命令	功能	详细说明
/clear	清空终端	清除所有对话历史，开始全新对话
/compact	压缩对话	将对话历史压缩为摘要，释放 token 空间
/new	新建会话	在同一个 CLI 窗口中开始新对话
/fork	分叉对话	将当前对话分叉到新的线程，原始对话不受影响
/side	临时对话	开启一个临时性的旁路对话，适合快速查询
/resume	恢复会话	恢复之前保存的对话
/exit	退出	退出 Codex CLI（同 /quit）

使用技巧:

# 对话太长时压缩
/compact

# 分叉当前对话进行探索性修改
/fork

# 快速旁路查询，不影响主对话
/side

# 恢复最近的会话
codex resume --last

# 查看所有历史会话
codex resume --all

# 恢复指定会话
codex resume <SESSION_ID>

5.2 Goal 命令

/goal 是 Codex CLI 最具特色的功能，用于设定、管理和控制长期任务目标

2026年5月11日，Claude Code 在 1.2.139 版本中也推出了 /goal 命令

命令	功能
/goal	设置新的任务目标
/goal status	查看当前目标执行状态
/goal pause	暂停目标执行
/goal resume	恢复暂停的目标
/goal view	查看当前目标的详细信息
/goal clear	清除当前目标

Goal 工作流程:

graph TB A[用户设定目标] --> B[Codex 分析任务] B --> C[生成执行计划] C --> D[逐步执行] D --> E[验证结果] E --> F{目标达成?} F -->|否| G[分析失败原因] G --> H[调整策略] H --> D F -->|是| I[完成任务] style A fill:#10a37f style I fill:#10a37f style F fill:#ffc107

Goal 使用示例:

# 设定目标
/goal 实现一个 RESTful API，包括：
1. 用户注册和登录（JWT 认证）
2. CRUD 操作
3. 数据验证和错误处理
4. 单元测试（覆盖率 > 80%）

# 查看进度
/goal status

# 暂停执行
/goal pause

# 恢复执行
/goal resume

# 清除目标
/goal clear

Goal vs 传统对话模式:

对比项	传统对话模式	Goal 模式
交互方式	一问一答	设定目标，自主执行
任务范围	单次操作	多步骤长期任务
用户干预	频繁	设定目标后可放手
适用场景	快速查询、简单修改	复杂功能开发、重构

最佳实践:

# ✅ 适合 Goal 模式
/goal 重构整个用户认证模块，提高安全性和性能
/goal 将项目从 JavaScript 迁移到 TypeScript
/goal 实现完整的 CI/CD 流水线

# ❌ 不适合 Goal 模式（直接对话即可）
这个函数是做什么的？
修复这个拼写错误

5.3 模型与配置命令

命令	功能
/model	切换当前使用的模型和推理努力程度
/fast	切换 Fast 服务层级
/personality	设置 AI 人格（friendly、pragmatic、none）
/permissions	设置审批模式（Auto、Read Only、Full Access）
/plan	切换到 Plan 模式（只规划不执行）

使用技巧:

# 切换到强力模型处理复杂任务
/model
# 选择 gpt-5.5 + high reasoning effort

# 快速模式处理简单任务
/fast

# 切换审批模式
/permissions
# 选择 Read Only 进行安全审查

# 进入规划模式（不执行任何修改）
/plan

5.4 工具与扩展命令

命令	功能
/mcp	列出已配置的 MCP 工具（加 verbose 查看详情）
/skills	浏览和使用可用 Skills
/plugins	浏览已安装和可发现的 Plugins
/hooks	查看生命周期 Hooks
/memories	配置记忆使用和生成
/apps	浏览应用/连接器
/agent	切换活跃的 Agent 线程

5.5 开发辅助命令

命令	功能
/review	使用审查 Agent 审查代码（支持多种预设模式）
/diff	显示 Git diff（包括未跟踪文件）
/mention	附加文件/文件夹到对话
/ide	包含 IDE 上下文（打开的文件、选择的内容）
/copy	复制最近的输出（也可用 Ctrl+O）

/review 详解:

# 四种预设审查模式:
/review
# 1. Review against a base branch（对比基准分支审查）
# 2. Review uncommitted changes（审查未提交的变更）
# 3. Review a commit（审查指定提交）
# 4. Custom review instructions（自定义审查指令）

可以在配置中指定审查使用的模型：

# config.toml
# review_model = "gpt-5.5"

5.6 系统命令

命令	功能
/status	显示会话配置和 token 使用情况
/debug-config	打印配置层级和 requirements 诊断信息
/approve	批准一次最近被自动审阅拒绝的重试
/experimental	切换实验性功能
/keymap	重新映射 TUI 键位
/vim	切换 Vim 模式
/raw	切换原始输出模式
/theme	选择语法高亮主题
/statusline	配置 TUI 底部状态栏
/title	配置终端窗口/标签标题
/ps	显示后台终端和输出
/stop	停止所有后台终端
/init	生成 AGENTS.md 骨架文件
/logout	登出 Codex
/feedback	发送日志给维护团队
/sandbox-add-read-dir	授予沙箱读取目录权限（仅 Windows）

5.7 斜杠命令使用技巧

任务运行中排队命令:

在 Codex 执行任务时，按 Tab 键可以排队后续的文本、斜杠命令或 ! Shell 命令。

# Codex 正在执行任务时...
# 按 Tab → 输入后续命令 → 按 Enter 排队
Tab
/compact    # 任务完成后自动压缩
Enter

---

六、AGENTS.md 项目记忆文件

6.1 什么是 AGENTS.md?

AGENTS.md 是 Codex CLI 的项目记忆文件，类似于 Claude Code 的 CLAUDE.md。它记录项目结构、构建命令、代码规范、架构决策等关键信息，让 Codex 快速理解项目上下文。

6.2 AGENTS.md 发现链

Codex 在启动时会按特定顺序搜索和加载 AGENTS.md 文件：

graph TD A["~/.codex/ (全局)"] --> B{"AGENTS.override.md 存在?"} B -->|是| C["读取 AGENTS.override.md"] B -->|否| D["读取 AGENTS.md"] C --> E["项目根目录"] D --> E E --> F["逐级向下到 CWD"] F --> G["每级: override > AGENTS.md > fallback"] G --> H["拼接合并，后者覆盖前者"] style A fill:#10a37f style H fill:#1a7f5a

具体规则:

1. 全局范围 (~/.codex/ 或 $CODEX_HOME): 读取 AGENTS.override.md 或 AGENTS.md
2. 项目范围 (从 Git 根目录到当前工作目录): 每个目录检查 AGENTS.override.md → AGENTS.md → fallback 文件名
3. 合并规则: 从根目录向下拼接，靠近 CWD 的文件排在后面（优先级更高）
4. 大小限制: 总大小受 project_doc_max_bytes 限制（默认 32 KiB）

6.3 Override 机制

AGENTS.override.md 优先于同级的 AGENTS.md。这允许你在不修改基础文件的情况下进行临时覆盖。

project/
├── AGENTS.md              # 基础项目配置
├── AGENTS.override.md     # 临时覆盖（优先）
└── src/
    ├── AGENTS.md          # 模块级配置
    └── AGENTS.override.md # 模块级覆盖

6.4 自定义 Fallback 文件名

Fallback 文件名就是，如果某个目录下既没有 AGENTS.override.md 也没有 AGENTS.md，Codex 还会去查找哪些替代文件作为项目说明。

默认情况下 fallback 列表可能是空的（只认 AGENTS.md），但可以通过配置让 Codex 也读取其他文件名，比如：

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

这样扫描每个目录时，查找顺序就变成：AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md。

# config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536  # 增大到 64 KiB

6.5 AGENTS.md 完整示例

# E-Commerce Platform

## 项目概述
基于 Node.js + Express + PostgreSQL 的电商平台后端服务。

## 技术栈
- **语言:** TypeScript 5.x（严格模式）
- **框架:** Express.js
- **数据库:** PostgreSQL 15 + Redis 7
- **ORM:** Prisma
- **认证:** JWT + OAuth 2.0
- **测试:** Jest + Supertest
- **部署:** Docker + Kubernetes

## 常用命令

### 开发
npm run dev          # 启动开发服务器
npm run dev:debug    # 调试模式启动

### 构建
npm run build        # 构建生产版本
npm run build:docker # Docker 构建

### 测试
npm test             # 运行所有测试
npm run test:watch   # 监听模式
npm run test:coverage # 覆盖率报告
npm run test:e2e     # E2E 测试

### 代码质量
npm run lint         # ESLint 检查
npm run format       # Prettier 格式化
npm run type-check   # TypeScript 类型检查

## 代码规范

### 命名规范
- 文件名: kebab-case (user-profile.ts)
- 组件名: PascalCase (UserProfile)
- 函数/变量: camelCase (getUserProfile)
- 常量: UPPER_SNAKE_CASE (API_BASE_URL)

### Git 提交规范
遵循 Conventional Commits:
- `feat:` 新功能
- `fix:` Bug 修复
- `refactor:` 代码重构
- `test:` 测试
- `docs:` 文档
- `chore:` 构建/工具

## 禁止事项
- ❌ 使用 any 类型
- ❌ 使用 var 声明变量
- ❌ 使用 console.log（使用 logger）
- ❌ 在代码中硬编码密钥
- ❌ 直接修改生产数据库

## 测试要求
- 单元测试覆盖率 > 80%
- 集成测试覆盖关键路径
- 所有 API 端点必须有 E2E 测试

6.6 快速生成 AGENTS.md

# 方式一：使用 /init 命令自动生成
codex
/init

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

# 方式三：使用自定义 CODEX_HOME
CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

6.7 最佳实践

• 从最重要的事情开始：不要一开始就写一个巨大的 AGENTS.md，从最关键的规范开始
• 放在最接近的目录：把规则放在它们适用的最具体的目录中
• 全局 vs 项目：个人偏好放 ~/.codex/AGENTS.md，团队规范放项目根目录
• 利用 override：用 AGENTS.override.md 做临时实验，不污染基础文件
• 让 Codex 自己更新：当纠正 Codex 的错误时，告诉它"把这个教训写入 AGENTS.md"

---

七、高级功能

7.1 Plan 模式（规划模式）

与 Claude Code 的 Plan 模式功能一致——Codex 会阅读代码、分析架构、起草计划，但绝不修改代码。

# 进入 Plan 模式
/plan

# Codex 会生成详细计划，等待你确认
# 确认后才开始执行

7.2 Remote TUI 模式（远程 TUI）

这是 Codex CLI 独有的功能。你可以在一台机器上运行 Codex 应用服务器，从另一台机器连接 TUI。

# 在服务器上启动
codex app-server --listen ws://127.0.0.1:4500

# 从客户端连接
codex --remote ws://127.0.0.1:4500

使用场景:

• 在高性能服务器上运行 Codex，从笔记本连接
• 团队共享同一个 Codex 实例
• 远程开发环境集成

认证模式: 能力 Token（capability token）或签名的 Bearer Token。

7.3 Codex Cloud 集成

# 交互式选择 Cloud 环境
codex cloud

# 直接在指定环境执行任务
codex cloud exec --env ENV_ID "task description"

# 使用 best-of-N 运行（1-4 次尝试，取最佳结果）
codex cloud exec --env ENV_ID --attempts 3 "fix the flaky test"

7.4 Network Proxy（网络代理）

实验性的网络代理功能，支持域名级别的访问控制：

[features.network_proxy]
enabled = true

[features.network_proxy.domains]
"api.example.com" = "allow"
"*.internal.com" = "deny"

7.5 Session 管理

Codex 的会话存储在 ~/.codex/sessions/ 目录下：

# 交互式选择最近的会话
codex resume

# 显示所有目录的会话
codex resume --all

# 跳到最近的会话
codex resume --last

# 恢复指定 ID 的会话
codex resume <SESSION_ID>

7.6 多根目录工作

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

7.7 Shell 集成

在对话中用 ! 前缀运行 Shell 命令：

!git status
!npm test
!ps aux | grep node

输出会被当作用户提供的命令结果。

7.8 Shell 补全

# Bash
codex completion bash >> ~/.bashrc

# Zsh
codex completion zsh >> ~/.zshrc

# Fish
codex completion fish > ~/.config/fish/completions/codex.fish

7.9 日志与追踪

# 日志位置
~/.codex/log/codex-tui.log

# 设置追踪级别
export RUST_LOG=debug

# 启动 Codex
codex

---

八、实用技巧与快捷操作

8.1 TUI 交互技巧

操作	快捷键/方式	说明
排队后续命令	Tab	在 Codex 执行中按 Tab 排队命令
搜索历史提示词	Ctrl+R	搜索之前的输入
打开外部编辑器	Ctrl+G	用编辑器编写长提示词
浏览 Draft 历史	Up/Down	在空输入框中上下翻阅历史
编辑之前的消息	Esc×2	在空输入框按两次 Esc 编辑上一条消息
复制最近输出	Ctrl+O	复制最后一段完成的输出
附加图片	-i 参数	codex -i screenshot.png "prompt"

8.2 环境准备最佳实践

在启动 Codex 之前先准备好环境，可以避免 Codex 浪费 token 去探测环境：

# ✅ 好的做法：先激活虚拟环境，再启动 Codex
source venv/bin/activate
codex

# ❌ 避免：让 Codex 自己去发现和激活环境
# 这会消耗大量 token 在环境探测上

8.3 Draft 历史

在输入框为空时用 Up/Down 浏览之前的输入。Codex 会恢复之前的草稿文本和图片占位符。

8.4 编辑之前的消息

当输入框为空时按 Esc 两次，可以编辑上一条消息。继续按 Esc 可以回溯更早的消息。

8.5 后台终端管理

# 查看后台运行的终端
/ps

# 停止所有后台终端
/stop

需要 unified_exec 功能标志启用。

---

九、最佳实践

9.1 定制化层次构建顺序

推荐按照以下顺序逐步构建你的 Codex 定制化：

1. AGENTS.md
   └── 项目规范 + pre-commit hooks/linters 强制执行
2. Plugins
   └── 安装社区可复用的工作流
3. Skills
   └── 创建自定义技能包，打包为 Plugins
4. MCP
   └── 需要外部系统集成时使用（Linear、GitHub、数据库等）
5. Subagents
   └── 委派嘈杂或专业化的任务

9.2 Goal 模式最佳实践

设定 SMART 目标:

# ✅ 具体、可衡量、可实现、相关、有时限的目标
/goal 实现用户认证模块：
1. 创建注册 API（POST /api/v1/users/register）
2. 创建登录 API（POST /api/v1/users/login）
3. 包含邮箱验证功能
4. 编写 5 个以上单元测试
5. 确保测试覆盖率 > 80%

# ❌ 模糊的目标
/goal 做个用户系统

分阶段执行:

# 阶段 1：设计
/goal 设计数据库模型和 API 接口

# 阶段 2：实现
/goal 基于上述设计实现核心 CRUD 功能

# 阶段 3：测试和优化
/goal 为已实现的功能编写测试并优化性能

实时监控:

/goal status   # 查看进度
/goal pause    # 暂停检查
/goal resume   # 确认后继续

9.3 验证闭环（Feedback Loop）

核心原则: 永远给 Codex 验证自己工作的方法。

# ❌ 盲写
/goal 实现用户认证功能

# ✅ 验证循环
/goal 实现用户认证功能，然后：
1. 运行测试套件: !npm test
2. 检查覆盖率: !npm run test:coverage
3. 运行 lint: !npm run lint
4. 类型检查: !npm run type-check
5. 如果任何检查失败，自动修复后重新验证
6. 直到所有检查通过

效果对比:

验证方式	代码质量	返工率
无验证	⭐⭐	40%
人工验证	⭐⭐⭐	20%
Codex 自动验证	⭐⭐⭐⭐⭐	5%

9.4 上下文管理优化

技巧	说明	节省效果
精确文件引用	用 /mention 指定文件而非整个目录	30-50%
定期 /compact	每 20 轮对话压缩一次	40-60%
新任务 /clear	开始新任务时清空历史	50-70%
使用 Subagents	将大任务拆分给子代理	50-70%
合理设置 context_window	在配置中设定合理的上下文窗口	避免溢出

9.5 模型选择策略

OpenAI 模型选择:

任务类型	推荐模型	推理努力	理由
快速查询	gpt-5.4-mini	low	最快最便宜
日常开发	gpt-5.4	medium	平衡性能和成本
架构设计	gpt-5.5	high	最强推理能力
代码审查	gpt-5.5	high	需要深入理解
并行 Worker	gpt-5.4-mini	low	快速且便宜

模型切换:

# 交互式切换
/model

# CLI 指定
codex --model gpt-5.4-mini

# 使用 Profile
codex --profile fast

# 使用别名
alias codex-fast="codex --model gpt-5.4-mini"
alias codex-smart="codex --model gpt-5.5"

9.6 安全最佳实践

沙箱配置:

# 日常开发
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# 代码审查
sandbox_mode = "read-only"

# CI/CD（受控环境）
sandbox_mode = "danger-full-access"
approval_policy = "never"

使用 requirements.toml 约束团队:

# /etc/codex/requirements.toml
allowed_sandbox_modes = ["read-only", "workspace-write"]
allowed_web_search_modes = ["cached", "disabled"]

9.7 项目组织最佳实践

project/
├── .codex/                    # Codex CLI 配置目录
│   └── config.toml           # 项目级配置
├── .agents/                   # Skills 和自定义 Agent
│   ├── skills/
│   │   ├── commit/
│   │   │   └── SKILL.md
│   │   └── deploy/
│   │       └── SKILL.md
│   └── agents/
│       └── reviewer.toml
├── AGENTS.md                  # 项目记忆文件
├── AGENTS.override.md         # 临时覆盖（可选）
├── src/
│   ├── AGENTS.md              # 模块级配置
│   └── ...
└── README.md

---

十、Codex CLI vs Claude Code 对比

10.1 架构与基础

维度	Codex CLI	Claude Code
编程语言	Rust	TypeScript/Node.js
开源	✅ 完全开源（OSI 许可证）	❌ 公开仓库但专有许可证（All rights reserved）
配置格式	TOML	JSON（主）+ YAML frontmatter + plist/注册表（企业部署）
安装方式	npm / Homebrew / Cargo / 二进制	curl / Homebrew / PowerShell / WinGet（npm 已弃用）
平台支持	macOS / Linux / Windows（原生 + WSL2）	macOS / Linux / Windows（原生 + WSL2）
启动速度	极快（Rust 原生）	快
内存占用	极低	较高

10.2 模型与认证

维度	Codex CLI	Claude Code
默认模型	gpt-5.5 / gpt-5.4	Claude Opus 4.7 / Sonnet 4.7
模型供应商	OpenAI + Ollama + LM Studio + Bedrock + 自定义	Anthropic + Bedrock + Vertex AI + 第三方（社区路由工具）
认证方式	ChatGPT OAuth 或 API Key	OAuth（订阅登录）或 Anthropic API Key 或 Bedrock IAM 或 Vertex
订阅使用	✅ ChatGPT Plus/Pro/Business/Enterprise 可直接用	✅ Claude Pro/Max/Team/Enterprise 可直接用
本地模型	✅ 内置支持（--oss 一键连接 Ollama/LM Studio）	❌ 不内置，需社区路由工具间接实现

10.3 沙箱与安全

维度	Codex CLI	Claude Code
macOS 沙箱	Seatbelt（系统原生）	Seatbelt（系统原生）
Linux 沙箱	bubblewrap + Landlock + seccomp	bubblewrap（bwrap）
Windows 沙箱	原生 Windows 沙箱	原生 Windows 支持（无需 WSL2）
网络控制	域名级 allow/deny（network proxy）	沙箱内可配置域名白名单
管理员约束	✅ requirements.toml（企业级，不可覆盖）	✅ managed-settings.json + MDM 部署（Intune/Jamf）
自动审阅	✅ auto_review（AI 代理审阅）	❌

10.4 多 Agent 协作

维度	Codex CLI	Claude Code
子代理	spawn_agent / send_input / wait_agent 等	Task dispatch to teammates
最大并发	6（可配置）	Team-based，动态分配
最大嵌套	1（可配置）	无限
正式 Team 概念	❌（主从关系，非对等协作）	✅ TeamCreate / TaskCreate / TaskList
Agent 间消息	通过工具调用（send_input）	SendMessage 直接通信
Worktree 隔离	❌	✅ EnterWorktree / ExitWorktree

10.5 扩展系统

维度	Codex CLI	Claude Code
项目指令	AGENTS.md（层级发现链）	CLAUDE.md（层级合并）
Override 机制	✅ AGENTS.override.md	❌
Skills	SKILL.md + scripts + references	skill.json + skill.md
Plugins	✅ marketplace	✅ marketplace
MCP 传输协议	STDIO + HTTP/SSE	STDIO + SSE + HTTP + WebSocket
MCP 服务器模式	✅ codex mcp-server	❌
Hooks	8 种生命周期事件	5 种生命周期事件（PreToolUse, PostToolUse, Stop, SessionStart, UserPromptSubmit）
记忆系统	✅ 自动提取 + 整合（opt-in，三阶段管道）	✅ CLAUDE.md 手动 + Auto Memory 自动记忆 + Dreaming（预览）

10.6 独有功能

Codex CLI 独有:

• ✅ 内置图片生成（gpt-image-2）
• ✅ 自动审阅系统（AI 代理审批）
• ✅ Remote TUI 模式（远程连接）
• ✅ 内置本地模型支持（--oss 一键连接）
• ✅ Feature Flags 系统（成熟度标记）
• ✅ Network Proxy（域名级访问控制）
• ✅ codex exec（非交互式自动化）
• ✅ Profiles（命名配置预设）
• ✅ --yolo 模式（一键全自主）

Claude Code 独有:

• ✅ 正式 Team 协作（TeamCreate、TaskCreate、SendMessage）
• ✅ Task 管理系统（TaskList、TaskGet、TaskUpdate）
• ✅ Worktree 管理（EnterWorktree、ExitWorktree）
• ✅ Agent SDK（TypeScript + Python，构建自定义智能体）
• ✅ LSP 集成（IDE 级语义代码理解，比 grep 快 900 倍）
• ✅ Dreaming（预览功能，Agent 空闲时自动回顾历史优化记忆）
• ✅ SSE MCP 内置 OAuth 2.0 自动认证
• ✅ IDE 集成（VS Code + JetBrains 原生扩展）
• ✅ Desktop App + Web 界面（claude.ai/code）
• ✅ MDM 企业部署（Jamf/Kandji/Intune）

10.7 适用场景选择

场景	推荐	理由
日常开发	两者皆可	根据个人偏好和已有订阅
复杂长期任务	Codex CLI	Goal 模式更成熟
代码审查	Codex CLI	内置 /review + auto_review
多 Agent 团队协作	Claude Code	正式 Team 系统 + Worktree 隔离
CI/CD 集成	Codex CLI	codex exec 更方便
本地/离线开发	Codex CLI	--oss 内置支持
企业安全管控	两者皆可	Codex 有 requirements.toml，Claude 有 managed-settings + MDM
跨设备使用	Codex CLI	Remote TUI
预算有限	两者皆可	Codex 用 ChatGPT 订阅，Claude 用 Pro/Max 订阅
自定义 Agent 开发	Claude Code	Agent SDK（TS + Python）
IDE 深度集成	Claude Code	VS Code + JetBrains 原生扩展 + LSP

---

十一、总结

11.1 核心能力清单

• ✅ Rust 原生构建: 极速启动和响应，内存占用极低
• ✅ Goal 模式: 任务驱动的自主执行，从规划到完成的完整闭环
• ✅ 多供应商支持: OpenAI + Ollama + LM Studio + Bedrock + 自定义
• ✅ ChatGPT 订阅使用: 不需要 API Key，订阅即可用
• ✅ AGENTS.md: 层级发现链 + Override 机制的项目记忆系统
• ✅ Skills & Plugins: 可复用的工作流和可分发的扩展
• ✅ MCP: 通过 Model Context Protocol 无限扩展能力
• ✅ Subagents: 并行任务委派，6 线程并发
• ✅ Sandbox: 多平台原生沙箱（macOS/Linux/Windows）
• ✅ Auto-Review: AI 代理自动审批操作
• ✅ Memories: 跨会话自动记忆提取和整合
• ✅ 35+ 斜杠命令: 覆盖会话管理、模型切换、代码审查等
• ✅ Remote TUI: 远程连接，跨设备工作
• ✅ Codex Cloud: 云端执行环境集成
• ✅ 图片生成: 内置 gpt-image-2 图片生成能力
• ✅ exec 模式: 非交互式自动化，CI/CD 集成
• ✅ requirements.toml: 企业级管理员强制约束

11.2 从 Claude Code 迁移指南

# 1. 安装 Codex CLI
npm i -g @openai/codex

# 2. 认证（最简单的方式）
codex login  # ChatGPT OAuth 登录

# 3. 转换记忆文件
# CLAUDE.md → AGENTS.md（调整内容格式即可，核心内容通用）

# 4. 转换 MCP 配置
# JSON 格式 → TOML 格式

# 5. 熟悉 Goal 模式
/goal 你的第一个任务

# 6. 熟悉新的斜杠命令
/help

11.3 设计哲学

Codex CLI 的设计哲学体现了 OpenAI 对 AI 编程助手的不同理解：

• 通过 Goal 模式，它强调任务自主性和执行效率
• 通过 Sandbox 和 requirements.toml，它提供了企业级的安全管控
• 通过 多供应商支持，它给了开发者选择模型的自由
• 通过 Rust 原生构建，它追求极致的性能和资源效率
• 通过 ChatGPT 订阅集成，它降低了使用门槛

Codex CLI 不仅仅是一个工具，它是一个高性能、可扩展、安全的 AI 开发环境。无论你是个人开发者还是企业团队，都能找到适合自己的使用方式。

---

附录

A. 快速参考卡

# 基础命令
codex                          # 启动 TUI
codex exec "prompt"            # 非交互式执行
codex --oss                    # 使用本地模型
codex --profile work           # 使用配置预设
codex resume --last            # 恢复上次会话

# 认证
codex login                    # OAuth 登录
codex logout                   # 登出

# 斜杠命令
/goal "任务描述"                # 设定目标
/goal status                   # 查看进度
/permissions                   # 审批模式
/model                         # 切换模型
/plan                          # Plan 模式
/clear                         # 清空对话
/compact                       # 压缩对话
/review                        # 代码审查
/mcp                           # MCP 状态
/skills                        # 可用技能
/init                          # 生成 AGENTS.md
/status                        # 会话状态
/new                           # 新建会话
/fork                          # 分叉对话
/side                          # 临时对话

# 快捷键
Tab                            # 排队后续命令
Ctrl+R                         # 搜索历史
Ctrl+G                         # 外部编辑器
Ctrl+O                         # 复制输出
Esc×2                          # 编辑上条消息
Up/Down                        # Draft 历史

B. 配置文件清单

配置文件	位置	格式	作用
config.toml	~/.codex/	TOML	用户全局配置
config.toml	.codex/	TOML	项目级配置
requirements.toml	/etc/codex/	TOML	管理员强制约束
AGENTS.md	项目目录	Markdown	项目记忆文件
AGENTS.override.md	项目目录	Markdown	临时覆盖

C. 推荐资源

官方资源

• GitHub 仓库: https://github.com/openai/codex
• 官方文档: https://developers.openai.com/codex
• Config Schema: https://developers.openai.com/codex/config-schema.json

---

🎉 如果你喜欢这篇文章，欢迎：

• ⭐ Star 我的 GitHub 和其中的项目: knqiufan
• 🐛 对感兴趣的项目提 Issue 和 PR
• 📢 分享给需要的朋友

相关文章:

• 关于完全指南： Claude Code 完全指南：使用方式、技巧与最佳实践
• 关于 Skill： 从对话到协作，Skills 如何改变我们与 AI 共事的方式
• 关于 SubAgent： 拆解 Claude Code SubAgent：隔离、专业化与权限设计