Codex CLI 完全使用手册：从入门到精通Codex 最近风头很盛，甚至超过了 Claude Code，作为一个成熟

Codex CLI 完全使用指南：从入门到精通

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

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

一、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"

自定义第三方供应商

注：关于第三方模型兼容性限制

有一点需要强调的是，Codex CLI 使用的 API 协议规范与 OpenAI 的行业标准 API 协议规范不一样，Codex CLI 使用的是 Responses API 协议，而非行业标准的 Chat Completions API。

所以会有小伙伴发现将 DeepSeek、Kimi 等第三方模型的官方提供 OpenAI 标准规范的接口接入 Codex CLI 仍然无法正常工作就是这个原因，API 在协议层面不兼容。

维度 Chat Completions（行业标准） Responses API（仅 Codex 支持）
端点 POST /v1/chat/completions POST /v1/responses
请求格式 messages: [...] input: [...] + tools + instructions
行业支持几乎所有供应商都实现 OpenAI 支持

从时间线上看 2026 年 2 月起 Codex CLI 就完全移除 Chat Completions 支持（wire_api 仅支持 "responses"）。所以无论怎么配置 base_url，Codex 发出的请求都是 Responses API 格式，而 DeepSeek、Kimi、GLM、Qwen 等第三方供应商官方支持的 API 只有 Chat Completions 端点，无法理解和处理这种请求。

另一方面，Claude Code 使用的是 Anthropic Messages API，第三方供应商已经实现了对该协议的兼容（例如直接提供 https://api.deepseek.com/anthropic 端点），所以 cc-switch 换个 URL 就能生效。而 Codex CLI 的问题在于协议格式对不上，供应商未支持，所以换 Chat Completions 协议的地址依旧无法使用。

**邪修方案：**如果确实需要 Codex CLI + 第三方模型，可以使用本地代理（GitHub 上有类似的开源项目，比如 codeproxy-ai/cli，但该项目我未实际试用过，仅作参考）在中间做协议转换，将 Codex 发出的 Responses API 请求转换为 Chat Completions 格式再转发给第三方供应商。

通过这种方式配置 model_providers 配置块可以接入任意兼容 OpenAI Responses API 的服务。
# 启动本地代理
npx @codeproxy/cli --upstream-format openai-chat \
--base-url https://api.deepseek.com/v1 \
--apikey sk-your-deepseek-key
# 然后在 Codex 配置中指向本地代理
[model_providers.deepseek]
name = "DeepSeek"
base_url = "http://127.0.0.1:8787/v1"  # 指向本地代理，而非 DeepSeek 官方地址
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

维度	Chat Completions（行业标准）	Responses API（仅 Codex 支持）
端点	`POST /v1/chat/completions`	`POST /v1/responses`
请求格式	`messages: [...]`	`input: [...]` + `tools` + `instructions`
行业支持	几乎所有供应商都实现	OpenAI 支持

自定义供应商完整参数:

参数	说明
`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 地址: github.com/farion1231/…

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

cc switch

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" 可以获得更深入的推理。

审批与沙箱配置

# 审批策略
# "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"

# 额外可写目录
# sandbox_workspace_write.writable_roots = ["/tmp/codex-output"]

# 工作区写入模式是否允许网络
# sandbox_workspace_write.network_access = false

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

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

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"]

人格配置

# 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 独有的功能。设置 approvals_reviewer = "auto_review" 后，Codex 会使用一个 AI 子代理来自动决定是否批准操作，而不是每次都弹窗问你。

# 启用自动审阅
approvals_reviewer = "auto_review"

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

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

自动审阅策略文件示例:

<!-- ~/.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

4.3 Subagents（子代理）

与 Claude Code 类似，Codex CLI 也支持子代理系统，但机制有所不同。

核心工具: 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"]

使用 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 文件加可选的脚本和资源。

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 配置和 Agent 定义。

管理插件:

# 浏览和安装插件
/plugins

# 从市场安装
codex plugin marketplace

与 Claude Code 的区别: Codex CLI 的 Plugins 系统与 Claude Code 类似，都是打包分发的扩展集合。两者概念一致，使用方式略有不同。

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_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 在特定事件触发时自动执行脚本，用于自定义工作流。

支持的 Hook 事件:

事件	触发时机	典型用途
`PreToolUse`	工具调用前	权限检查、参数验证
`PermissionRequest`	权限请求时	拦截危险操作
`PostToolUse`	工具调用后	自动格式化、日志记录
`SessionStart`	会话开始时	环境初始化
`UserPromptSubmit`	用户提交提示词前	验证输入
`Stop`	会话停止时	清理资源

配置 Hooks:

# 在 config.toml 中配置
# [hooks]
# 或使用独立的 hooks.json 文件

企业级 Hooks 管理:

# requirements.toml 中限制只允许管理员定义的 Hooks
allow_managed_hooks_only = true

4.8 Memories（记忆系统）

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

启用记忆:

# ~/.codex/config.toml
[features]
memories = true

记忆工作原理:

线程级提取: 每次会话结束后，使用指定的 extract_model 从对话中提取关键知识
全局整合: 使用 consolidation_model 将多个线程的知识整合为全局记忆
自动注入: 新会话启动时，相关记忆会自动注入上下文

管理记忆:

# 在交互式会话中配置记忆
/memories

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 -i screenshot.png "Explain this error"

# 多图片输入
codex --image img1.png,img2.jpg "Compare these diagrams"

图片生成（使用 gpt-image-2）:

在对话中使用自然语言请求生成图片，或在提示词中使用 $imagegen。

⚠️ 注意: 图片生成会以 3-5 倍的速度消耗使用额度。

五、斜杠命令详解

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 命令（Codex 独有）

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

命令	功能
`/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

具体规则:

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

# 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

## 常用命令

### 开发
```bash
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

```bash
# 方式一：使用 /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 对比

作为从 Claude Code 转到 Codex CLI 的用户，以下是两者的全面对比。

10.1 架构与基础

维度	Codex CLI	Claude Code
编程语言	Rust	TypeScript/Node.js
开源	✅ 完全开源	✅ 完全开源
配置格式	TOML	JSON
安装方式	npm / Homebrew / Cargo / 二进制	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 / Sonnet 4
模型供应商	OpenAI + Ollama + LM Studio + Bedrock + 自定义	Anthropic + 第三方（通过环境变量）
认证方式	ChatGPT OAuth 或 API Key	Anthropic API Key
订阅使用	✅ ChatGPT Plus/Pro 可直接用	❌ 仅 API 付费
本地模型	✅ 内置支持（`--oss`）	❌ 需要手动配置

10.3 沙箱与安全

维度	Codex CLI	Claude Code
macOS 沙箱	Seatbelt（系统原生）	无原生沙箱
Linux 沙箱	bubblewrap + Landlock + seccomp	Docker（可选）
Windows 沙箱	原生 Windows 沙箱	仅 WSL2
网络控制	域名级 allow/deny（network proxy）	有限
管理员约束	✅ requirements.toml（企业级）	有限
自动审阅	✅ 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 间消息	通过工具调用	SendMessage 直接通信

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
MCP 服务器模式	✅ codex mcp-server	❌
Hooks	6 种生命周期事件	类似
记忆系统	✅ 自动提取+整合（opt-in）	✅ MEMORY.md 手动维护

10.6 独有功能

Codex CLI 独有:

✅ /goal 命令（长期任务自主执行）
✅ 内置图片生成（gpt-image-2）
✅ 原生 Windows 沙箱（不需要 WSL2）
✅ 自动审阅系统（AI 代理审批）
✅ Remote TUI 模式（远程连接）
✅ 内置本地模型支持（--oss）
✅ Amazon Bedrock 内置支持
✅ Feature Flags 系统（成熟度标记）
✅ Network Proxy（域名级访问控制）
✅ requirements.toml（企业级管理员约束）
✅ codex exec（非交互式自动化）
✅ Profiles（命名配置预设）
✅ ChatGPT 订阅直接使用

Claude Code 独有:

✅ 正式 Team 协作（TeamCreate、TaskCreate、SendMessage）
✅ Task 管理系统（TaskList、TaskGet、TaskUpdate）
✅ Worktree 管理（EnterWorktree、ExitWorktree）
✅ 更简单、更有主见的配置
✅ Agent SDK（构建自定义智能体）
✅ LSP 集成（IDE 级代码理解）
✅ 更广泛的模型路由支持

10.7 适用场景选择

场景	推荐	理由
日常开发	两者皆可	根据个人偏好
复杂长期任务	Codex CLI	Goal 模式更成熟
代码审查	Codex CLI	内置 /review + auto_review
团队协作	Claude Code	正式 Team 系统
CI/CD 集成	Codex CLI	`codex exec` 更方便
本地/离线开发	Codex CLI	`--oss` 内置支持
企业安全管控	Codex CLI	requirements.toml
跨设备使用	Codex CLI	Remote TUI
预算有限	Codex CLI	ChatGPT 订阅即可用
自定义 Agent 开发	Claude Code	Agent SDK

十一、总结

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 仓库: github.com/openai/code…
官方文档: developers.openai.com/codex
Config Schema: developers.openai.com/codex/confi…

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

⭐ Star 我的 GitHub: knqiufan

🐛 提 Issue 和 PR，一起完善这篇指南

📢 分享给需要的朋友

相关文章:

Claude Code 完全指南：使用方式、技巧与最佳实践

本文采用 CC BY-NC-SA 4.0 协议授权