Codex 全景指南：配置、自定义与开发者实践

面向 Codex 新手与开发者：从基础配置、权限与沙箱，到 AGENTS.md、Skills、MCP、Hooks、SDK、App Server 和 CI/CD，提供属性说明、操作流程与完整示例。

内容依据 OpenAI 官方 Configuration 与 Developers 文档整理。最后核对：2026-08。

阅读导航

• 第一次配置：从“小白先走这条路线”和“一份安全的起步配置”开始。
• 看不懂配置格式：阅读“先认识 TOML”。
• 不知道权限怎么选：阅读“三套权限配置，实际有什么区别？”。
• 想直接照做：跳到“五个完整实战：从需求到验证”。
• 想查属性：阅读“核心 config.toml 属性”和“高级配置分组索引”。
• 想让 Codex 更懂项目：阅读 AGENTS.md、Memories 和 Skills。
• 想连接外部系统：阅读 Plugins 与 MCP。
• 想并行处理任务：阅读 Subagents。
• 想理解委派、控制权和角色流程：阅读“Agent 协作：任务委派、控制权与生命周期”。
• 想把 Codex 接入代码审查、CI、内部工具或团队协作：阅读“Part III：Developers 开发者篇”。
• 配置不生效：阅读文末“常见问题”。

Configuration 到底管什么？

Configuration 的目标是：设置默认行为、提供长期上下文，并让 ChatGPT 与 Codex 在不同聊天、仓库和机器上的工作方式尽量一致。

Codex Configuration
│
├─ 个人界面设置
│  ├─ General / Profile / Appearance / Voice
│  ├─ Configuration / Personalization
│  └─ Keyboard shortcuts / Personality
│
├─ config.toml
│  ├─ 模型、推理、表达风格
│  ├─ 审批、沙箱、文件系统、网络
│  ├─ Tools、Feature flags、TUI、日志
│  ├─ MCP、Apps、Plugins、Hooks
│  └─ Profiles、Provider、Telemetry
│
├─ 长期上下文与复用
│  ├─ AGENTS.md / Memories
│  └─ Skills / Plugins
│
├─ Agent 配置
│  ├─ Subagents / Speed
│  └─ Rules
│
└─ 平台与扩展
   ├─ MCP / Record & Replay
   ├─ Linux desktop
   └─ Windows desktop / Sandbox / WSL

最常用的四个界面配置

Configuration 页面直接展示了四项最影响 Codex 行为的设置：

界面属性	对应配置	目的	新手建议
Approval policy	approval_policy	决定 Codex 何时需要请求批准	从 on-request 开始
Sandbox settings	sandbox_mode 或 Permission Profile	决定命令能读写哪些文件、能否越出工作区	从 workspace-write 开始
Allow network access	sandbox_workspace_write.network_access	在 workspace-write 沙箱中是否允许命令访问网络	默认关闭，按需开启
Personality	personality	设置支持模型的默认沟通风格	pragmatic 或 friendly

审批策略回答“什么时候问你”，沙箱回答“即使获准前，命令能做什么”。两者是独立维度，不要混为一谈。

小白先走这条路线

如果你第一次使用 Codex，先不要阅读全部高级属性。按下面路线完成第一次配置：

打开 config.toml
      │
      ▼
粘贴“安全起步配置”
      │
      ▼
重启 Codex
      │
      ▼
用只读任务测试：解释项目结构
      │
      ▼
用写入任务测试：创建一个测试文件
      │
      ▼
观察审批提示和文件写入范围
      │
      ▼
再按需求增加 AGENTS.md / Skill / MCP / Subagents

完成后你应该看到这些效果：

• Codex 默认使用你设置的沟通风格；
• 普通命令在工作区内运行，不能随意写工作区外文件；
• 需要更高权限时 Codex 会说明原因并请求批准；
• 命令默认不能联网；
• 项目规则通过 AGENTS.md 自动生效。

如果结果与上述不一致，先跳到文末“常见问题”，不要继续堆更多配置。

先认识 TOML：只需掌握四件事

config.toml 使用 TOML 格式。小白最容易踩的坑不是 Codex，而是把配置写到了错误的表中。

顶层键

personality = "pragmatic"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

格式是 属性 = 值。字符串使用双引号，布尔值是没有引号的 true 或 false。

表

[features]
memories = true
multi_agent = true

[features] 表示后面的键属于 features。上例相当于 features.memories 和 features.multi_agent。

嵌套表

[mcp_servers.docs]
url = "MCP_SERVER_ENDPOINT"
enabled = true

这里 docs 是你给 MCP Server 起的名称，不是固定值。

对象数组

[[skills.config]]
path = "/absolute/path/to/skill/SKILL.md"
enabled = false

[[skills.config]]
path = "/absolute/path/to/another-skill/SKILL.md"
enabled = true

双中括号表示可以重复出现多项。

常见错误

错误一：把顶层键放在表后面，以为已经“回到顶层”。

[features]
memories = true

# 错误理解：这一行仍属于 [features]，不会自动回到顶层
personality = "pragmatic"

正确做法：把所有顶层键放在第一个 [table] 之前。

错误二：把布尔值写成字符串。

# 错误
enabled = "false"

# 正确
enabled = false

错误三：复制示例后忘记替换占位符，例如 <server-name>、<model-id>。尖括号内容通常只是说明，不是可以原样运行的值。

配置入口与文件位置

图形界面

• ChatGPT 桌面端：打开 Settings，在个人、Configuration、Personalization、MCP servers 等页面调整。
• Codex IDE 扩展：右上角齿轮 → Codex Settings > Open config.toml。
• MCP：桌面端或 IDE 的 Settings > MCP servers。

文件与目录

~/.codex/                         # 默认 CODEX_HOME
├── config.toml                   # 用户级持久配置
├── <profile>.config.toml         # 命名 Profile
├── AGENTS.md                     # 个人全局指令
├── agents/*.toml                 # 个人自定义 Agent
├── rules/*.rules                 # 用户命令规则
├── memories/                     # 本地生成的 Memories
├── auth / logs / sessions ...    # 认证、日志和会话状态
└── ...

repo-root/
├── .codex/
│   ├── config.toml               # 项目级配置；仅可信项目加载
│   ├── agents/*.toml             # 项目自定义 Agent
│   └── rules/*.rules             # 项目命令规则
├── AGENTS.md                     # 项目指令
└── .agents/skills/               # 项目 Skills

CLI、IDE 扩展与桌面端在同一个 Codex Host 上会共享相应配置。ChatGPT Web 不读取本地 config.toml。

配置优先级

同一个属性出现在多处时，按下面顺序取值，越上面优先级越高：

高  1. CLI flags 与 -c / --config 一次性覆盖
    2. 项目 .codex/config.toml
       项目根 → 当前目录逐层加载，离当前目录最近者胜出
    3. --profile 选中的 ~/.codex/<profile>.config.toml
    4. 用户 ~/.codex/config.toml
    5. 系统 /etc/codex/config.toml（Unix）
低  6. Codex 内置默认值

项目被标记为不可信时，项目内 .codex/ 的 config、hooks 和 rules 都不会加载；用户级与系统级配置仍然加载。组织管理的设备还可能通过 requirements.toml 限制可选值，这类限制不是普通配置可以覆盖的。

出于机器本地安全边界，项目级 .codex/config.toml 不能覆盖 Provider、认证、通知、Profile 选择和 Telemetry 路由等键。下列键写在项目配置中会被忽略，应放在用户级配置：openai_base_url、chatgpt_base_url、apps_mcp_product_sku、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url、otel。

一次性覆盖

# 专用 CLI 参数
codex --model <model-id>

# 通用 TOML 值覆盖；右侧必须是合法 TOML，不是 JSON
codex -c 'personality="pragmatic"'
codex -c 'sandbox_workspace_write.network_access=true'

Profile

创建 ~/.codex/deep-review.config.toml：

model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "read-only"

使用：

codex --profile deep-review
codex exec --profile deep-review "审查当前改动"

Profile 文件直接使用顶层键，不要再套 [profiles.deep-review]。

一份安全的起步配置

只复制你理解并需要的键，不要直接启用所有实验功能：

# ~/.codex/config.toml

# 模型行为
model_reasoning_effort = "medium"
personality = "pragmatic"
web_search = "cached"

# 批准与隔离
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

# 常用稳定能力
[features]
apps = true
goals = true
hooks = true
multi_agent = true
personality = true
remote_plugin = true
shell_snapshot = true
shell_tool = true
fast_mode = true

# 子代理
[agents]
enabled = true
max_concurrent_threads_per_session = 4
interrupt_message = true

# 对 shell 环境中的 KEY / SECRET / TOKEN 等名称应用默认过滤
[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

验证流程：

1. 保存文件并重启 Codex 或新开 TUI 会话。
2. 运行 codex status 核对工作区和权限。
3. 在 TUI 中检查 /permissions、/personality、/mcp 等当前状态。
4. 先执行只读任务，再执行一次工作区内的小改动，确认审批和沙箱行为符合预期。

核心 config.toml 属性

模型、推理与回答风格

属性	类型/常见值	目的
model	string	CLI/IDE 默认模型
review_model	string，可选	/review 专用模型；未设置时使用当前会话模型
model_provider	string；默认 openai	从 model_providers 选择模型提供方
model_context_window	number	覆盖模型上下文窗口大小；通常让模型目录自动决定
model_auto_compact_token_limit	number	达到阈值时自动压缩上下文
model_reasoning_effort	string	支持模型的推理强度，如 low、medium、high
plan_mode_reasoning_effort	string	Plan mode 单独使用的推理强度
model_reasoning_summary	string	控制是否及如何生成推理摘要
model_verbosity	string	控制回答详略程度
personality	friendly / pragmatic / none	默认沟通风格；会话中可用 /personality 覆盖
service_tier	string	选择模型服务层，例如支持时使用 fast
model_catalog_json	path	使用自定义模型目录；高级用途
model_instructions_file	path	从文件加载模型基础指令；高级用途
instructions	string	附加用户指令
developer_instructions	string	附加开发者级指令；通常更适合用 AGENTS.md 管项目规范

模型可用值会变化，应以当前客户端显示的可选模型为准，不要长期复制过时模型名。

审批、沙箱与网络

属性	类型/常见值	目的
approval_policy	untrusted / on-request / never，或 granular 表	控制何时请求用户批准
approvals_reviewer	reviewer 配置	选择审批请求的审查方式
auto_review.policy	policy	控制自动审查策略
sandbox_mode	read-only / workspace-write / danger-full-access	控制命令的文件系统和网络隔离范围
sandbox_workspace_write.writable_roots	path 数组	给 workspace-write 增加明确可写根目录
sandbox_workspace_write.network_access	boolean	workspace-write 下允许或禁止命令联网
sandbox_workspace_write.exclude_tmpdir_env_var	boolean	是否排除环境变量指向的临时目录
sandbox_workspace_write.exclude_slash_tmp	boolean	是否排除 /tmp
default_permissions	Profile 名	选择内置或自定义 Permission Profile
windows.sandbox	elevated / unelevated	Windows 原生沙箱实现；官方推荐可用时选 elevated
windows.sandbox_private_desktop	boolean	Windows 沙箱是否使用私有桌面

内置 Permission Profiles：:read-only、:workspace、:danger-full-access。自定义 Profile 使用 [permissions.<name>]，可精确配置工作区根目录、文件路径/Glob 与网络策略。

Granular approval 可分别控制：

approval_policy = { granular = {
  sandbox_approval = true,
  rules = true,
  mcp_elicitations = true,
  request_permissions = false,
  skill_approval = false
} }

Granular 属性	目的
sandbox_approval	沙箱外执行是否需要批准
rules	命令规则触发时是否走批准流程
mcp_elicitations	MCP Server 向用户请求额外输入时是否批准
request_permissions	动态请求权限时是否批准
skill_approval	Skill 相关审批是否启用

三套权限配置，实际有什么区别？

场景 A：第一次使用，推荐

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

实际行为：

• Codex 可以读取项目并修改工作区中的普通文件；
• 命令不能默认联网；
• 想写工作区外目录或执行需要额外权限的动作时，会先解释原因并请求批准；
• 适合日常开发和学习。

测试方法：让 Codex“在当前项目创建 hello.txt”，应该可以在工作区内完成；再让它“下载一个在线文件”，应该遇到网络限制或请求额外权限。

场景 B：只读审查

approval_policy = "on-request"
sandbox_mode = "read-only"

实际行为：

• 适合代码审查、架构分析和排查问题；
• Codex 可以读文件，但写文件需要改变权限或请求批准；
• 可以降低“只想分析，却意外修改代码”的风险。

测试方法：要求 Codex“分析当前项目但不要修改”，随后检查文件状态应无变化。

场景 C：自动化任务

approval_policy = "never"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

实际行为：

• Codex 不会停下来向人询问；
• 超出当前沙箱权限的动作会失败，而不是自动获得更大权限；
• 适合 CI 或确定性很高的非交互流程；
• 不等于 danger-full-access。

测试方法：使用 codex exec 跑一个只需要当前工作区的任务，并确认失败时能从退出状态和输出中定位权限问题。

为什么不建议新手直接使用 Full Access？

danger-full-access 会显著放宽隔离边界。它可能是某些受控环境的合理选择，但新手容易把“少弹窗”误认为“配置成功”。正确顺序是：先用 workspace-write 找出任务真正需要的目录和网络，再只开放必要能力。

搜索、工具与 Apps

属性	类型/默认	目的
web_search	cached（默认）/ indexed / live / disabled	控制 Web Search 数据来源与是否联网
tools.view_image	boolean	启用本地图像查看工具
apps.<id>.enabled	boolean	启停指定 App/Connector
apps._default.enabled	boolean	Apps 默认启停策略
apps.<id>.destructive_enabled	boolean	是否允许该 App 暴露破坏性动作
apps.<id>.open_world_enabled	boolean	是否允许该 App 暴露开放世界/外部访问动作
apps.<id>.default_tools_enabled	boolean	该 App 工具默认是否启用
apps.<id>.tools.<tool>.enabled	boolean	单工具启停覆盖
apps.<id>.default_tools_approval_mode	auto / prompt / writes / approve	App 工具默认审批模式
apps.<id>.tools.<tool>.approval_mode	同上	单工具审批覆盖
tool_suggest.discoverables	配置集合	控制可由 Tool Search 发现的工具
tool_suggest.disabled_tools	工具列表	从 Tool Search 中排除工具

cached 使用 OpenAI 维护的预索引结果；indexed 通过搜索索引门控外部访问；live 获取最新网页；disabled 关闭搜索。无论哪种模式，网页内容都应视为不可信输入。

会话、历史、日志与通知

属性	目的
history.persistence	控制会话历史是否持久化
history.max_bytes	限制历史存储大小
log_dir	指定本地日志目录；显式设置后也启用纯文本 codex-tui.log
sqlite_home	指定 SQLite 状态目录；优先于 CODEX_SQLITE_HOME
notify	配置外部通知命令
tui.notifications	控制 TUI 内部通知
tui.notification_method	通知实现方式
tui.notification_condition	何时触发通知
check_for_update_on_startup	启动时是否检查更新
feedback.enabled	是否启用反馈入口
analytics.enabled	是否启用产品分析
tool_output_token_limit	限制工具输出进入上下文的 Token 数
background_terminal_max_timeout	后台终端最长超时

日志排错示例：

RUST_LOG=debug codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log

TUI

属性	目的
tui.notifications	TUI 通知开关或筛选
tui.animations	动画开关
tui.alternate_screen	是否使用终端 alternate screen
tui.resume_cwd	恢复会话时如何处理工作目录
tui.vim_mode_default	默认启用 Vim 模式
tui.raw_output_mode	原始输出模式
tui.show_tooltips	是否显示快捷提示
tui.status_line	状态栏内容
tui.terminal_title	是否设置终端标题
tui.theme	主题
tui.keymap.<context>.<action>	给特定上下文动作绑定快捷键；空数组表示解绑

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

Shell 环境变量转发

[shell_environment_policy] 控制 Codex 启动的命令能看到哪些环境变量：

属性	目的
inherit	控制继承范围
ignore_default_excludes	是否忽略默认秘密名称过滤；想过滤 KEY/SECRET/TOKEN 时设为 false
filters	按变量名逐项 include/exclude
exclude	旧式排除列表
include_only	旧式仅允许列表
set	给子命令固定设置变量
experimental_use_profile	实验性：是否加载 shell profile

密钥优先通过进程环境注入，并尽量只在需要的命令范围内存在。

Feature flags

写在 [features] 下；未写的键沿用默认值。

Key	默认	成熟度	作用
apps	true	Stable	App/Connector 集成
goals	true	Stable	持久目标与自动继续
hooks	true	Stable	生命周期 Hooks
fast_mode	true	Stable	Fast 服务层选择
memories	false	Experimental	本地 Memories
multi_agent	true	Stable	子代理协作工具
personality	true	Stable	Personality 选择
remote_plugin	true	Stable	远程 Plugin 目录
shell_snapshot	true	Stable	缓存 shell 环境以加速重复命令
shell_tool	true	Stable	默认 Shell 工具
unified_exec	Windows 外默认 true	Stable	PTY 支持的统一执行工具
web_search	true	Deprecated	旧开关；改用顶层 web_search
web_search_cached	false	Deprecated	旧开关；映射到 web_search = "cached"
web_search_request	false	Deprecated	旧开关；映射到 web_search = "live"

启用方式：

[features]
memories = true

codex --enable memories
codex --enable feature_a --enable feature_b

实验性与 under-development 功能可能变化；普通用户应优先使用官方列出的 Stable 功能。

环境变量

config.toml 适合持久设置；环境变量适合临时覆盖、自动化秘密、安装器行为和诊断。

变量	默认/范围	目的
CODEX_HOME	~/.codex	Codex 配置、认证、日志、会话、技能与包状态根目录；自定义目录必须已存在
CODEX_SQLITE_HOME	CODEX_HOME	SQLite 状态目录；sqlite_home 配置优先
CODEX_NON_INTERACTIVE	false	安装脚本跳过询问并采用默认答案，适合无人值守安装
CODEX_INSTALL_DIR	平台默认 bin 目录	改变 codex 命令安装目录，不改变包缓存位置
CODEX_API_KEY	仅 codex exec	给单次非交互运行提供 API Key；应内联、缩小作用域
CODEX_ACCESS_TOKEN	CLI/app-server/可信自动化	提供 ChatGPT/Codex Access Token
CODEX_CA_CERTIFICATE	PEM 路径	企业 TLS 拦截或私有 CA；优先于 SSL_CERT_FILE
SSL_CERT_FILE	PEM 路径	CA Bundle 回退路径
RUST_LOG	error 等	控制 CLI/app-server 日志级别，可用 warn、info、debug、trace

Provider API Key 的变量名由 model_providers.<id>.env_key 自行指定，不是固定 Codex 环境变量。

高级配置分组索引

以下是 Configuration Reference 中的高级配置族。普通用户通常不需要逐键修改；遇到明确需求时再进入官方 Reference 搜索属性名。

配置族	解决的问题	关键前缀/属性
自定义 Model Provider	接入兼容 Provider、Bedrock、Ollama、LM Studio	model_providers.<id>.*、oss_provider
Provider 重试与流式连接	HTTP/stream 重试、空闲超时、WebSocket	request_max_retries、stream_max_retries、stream_idle_timeout_ms
Provider 认证	外部命令生成或刷新认证	model_providers.<id>.auth.*
Named Permissions	可复用文件系统与网络策略	default_permissions、permissions.<name>.*
Hooks	在生命周期事件运行脚本	hooks.<Event>[].hooks[]
Network Proxy	沙箱网络代理与域名/Socket 控制	features.network_proxy.*
MCP	本地/远程 MCP 与工具审批	mcp_servers.<id>.*
Apps	Connector 启停、工具权限与审批	apps.<id>.*
Plugins	Plugin 内 MCP 的策略覆盖	plugins.<plugin>.mcp_servers.*
Skills	单个 Skill 启停	skills.config[]
Agents	子代理默认值与自定义角色	agents.*、.codex/agents/*.toml
Memories	提取、使用、归并和额度阈值	memories.*
OTel	日志、Trace、Metrics 导出	otel.*
Desktop file handlers	自定义打开文件的应用与参数	desktop.custom_file_handlers.<id>.*
TUI	通知、主题、状态栏、快捷键	tui.*
Project discovery	项目根和指令文件发现	project_root_markers、project_doc_*
History / State	历史、SQLite、日志目录	history.*、sqlite_home、log_dir
Managed requirements	管理员强制许可、模型、功能和来源	requirements.toml 中的 allowed_*、features.* 等

配置项较多时，应结合当前版本的配置参考核对字段名称、类型和可用范围。

五个完整实战：从需求到验证

下面的例子故意使用普通项目和安全权限。每个案例都包含目标、步骤、预期结果和失败排查。

实战一：第一次创建个人配置

目标：让 Codex 默认使用务实风格，只能写当前工作区，并在需要额外权限时询问。

第一步：打开配置文件

最简单的方法：

• IDE 扩展：右上角齿轮 → Codex Settings > Open config.toml；
• 桌面端：Configuration 中选择 Open config.toml；
• macOS/Linux 路径：~/.codex/config.toml；
• Windows 路径：%USERPROFILE%\.codex\config.toml。

如果文件不存在，先创建 .codex 目录，再用文本编辑器新建 config.toml。如果文件已有内容，只增加或修改对应键，不要整文件覆盖；同一个 TOML 表或键重复声明会导致解析问题。

第二步：写入最小配置

personality = "pragmatic"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[sandbox_workspace_write]
network_access = false

每一行的意义：

• personality：回答更直接、偏执行；
• model_reasoning_effort：使用均衡推理强度；
• approval_policy：必要时向你询问；
• sandbox_mode：允许修改工作区，限制工作区外写入；
• web_search：搜索使用预索引缓存结果；
• network_access：Shell 命令默认不直接联网。

第三步：重启并验证

新开 Codex 会话，输入：

请说明当前工作区、沙箱模式、审批策略和回答风格。不要修改任何文件。

然后输入：

请在当前工作区创建 codex-config-test.txt，写入“配置成功”，完成后告诉我文件路径。

预期结果：文件可以在当前工作区创建；如果动作需要越出权限边界，Codex 会请求批准。

失败排查：

• 完全没生效：检查是否修改了当前 CODEX_HOME 下的文件，并重启会话；
• TOML 报错：检查重复键、缺失引号或把顶层键放进了错误表；
• 无法写工作区：检查是否误设为 read-only，或项目目录不在当前工作区；
• 没有联网：这是本例预期行为，需要时再把 network_access 改为 true。

实战二：给 Node.js 项目增加团队规则

目标：无论谁使用 Codex，都优先使用 pnpm，修改后运行测试，并且不直接修改生成目录。

第一步：仓库根目录创建 AGENTS.md

# Project instructions

## 项目概况

- 这是 Node.js 项目，包管理器统一使用 pnpm。
- 源代码位于 `src/`，测试位于 `tests/`。
- `dist/` 是构建产物，不允许手工修改。

## 修改流程

1. 修改前先定位相关源码和现有测试。
2. 修改业务逻辑后运行 `pnpm test`。
3. 提交结果前运行 `pnpm lint`。
4. 如果测试失败，报告失败信息和可能原因，不要隐藏失败。

## 依赖规则

- 新增生产依赖前先说明用途、体积和替代方案，并请求确认。

第二步：可选的项目配置

创建 .codex/config.toml：

approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"

项目配置只有在项目被信任时加载。不要在项目文件中放 Token、用户认证或机器私有 Provider 配置。

第三步：验证规则来源

从仓库根目录启动 Codex，然后输入：

总结你加载的项目指令，并告诉我：包管理器、测试命令、禁止修改的目录分别是什么。不要执行命令。

预期回答应包含 pnpm、pnpm test 和 dist/。如果 Codex 没读到：

• 确认文件名精确为 AGENTS.md；
• 确认文件非空；
• 检查更近目录是否存在 AGENTS.override.md；
• 重启 Codex，因为指令链在会话开始时构建。

实战三：连接一个文档 MCP Server

目标：让 Codex 能通过 MCP 查询开发文档，并确认连接是否成功。

方法 A：CLI 添加 STDIO Server

这个官方示例依赖本机已经安装 Node.js/npm，首次通过 npx 获取包时还需要网络访问。如果你尚未安装 Node.js，可以先跳过本例，或改用已经获得 URL 的 Streamable HTTP Server。

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list

这条命令的结构：

codex mcp add  context7  --  npx -y @upstash/context7-mcp
│              │            └─ 启动 Server 的命令与参数
│              └─ 你为 Server 取的本地名字
└─ Codex MCP 管理命令

方法 B：手工写 config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "prompt"

验证

1. 重启 Codex。
2. 在 TUI 输入 /mcp，应看到 context7。
3. 提问：

请使用 context7 查询我当前使用的框架中，如何配置一个最小测试，并说明你调用了哪个 MCP 工具。

常见失败：

• Server 不出现：确认配置表名是 [mcp_servers.context7]，然后重启；
• 找不到 npx：先安装 Node.js/npm，并确认终端执行 npx --version 有输出；
• 启动超时：确认 npx 在 PATH 中，必要时增大 startup_timeout_sec；
• 工具执行超时：增大 tool_timeout_sec，同时检查 Server 自身日志；
• 需要认证：远程 OAuth Server 使用 codex mcp login <server-name>；
• Token 问题：用 bearer_token_env_var 指向环境变量，不要把秘密直接写进 TOML。

实战四：创建第一个项目 Skill

目标：把“修改 README 后检查链接和格式”变成一个可重复调用的流程。

目录：

repo-root/
└── .agents/
    └── skills/
        └── docs-check/
            └── SKILL.md

SKILL.md：

---
name: docs-check
description: 检查 Markdown 文档的结构、链接和代码块。用户要求检查 README、文档质量、Markdown 链接或文档发布前检查时使用；不要用于修改业务代码。
---

1. 找出本次修改涉及的 Markdown 文件。
2. 检查标题层级是否跳级。
3. 检查围栏代码块是否闭合。
4. 检查本地链接目标是否存在。
5. 如项目已有 Markdown lint 命令，运行该命令。
6. 只修复有明确依据的问题。
7. 输出：修改内容、验证命令、仍无法验证的外部链接。

验证：

$docs-check 请检查 README.md，但先报告问题，得到确认后再修改。

预期结果：Codex 加载 Skill 的完整步骤，检查范围限于文档，不会漂移到业务代码。

如果不能自动触发，重点改 description：同时写清用途、触发词和“不适用”的边界。更新后通常会自动检测；仍未出现时重启 Codex。

实战五：三个子代理并行审查

目标：让不同子代理分别检查安全、测试和可维护性，主线程只接收归纳后的结果。

请并行审查当前分支：
1. 一个 explorer 只读梳理受影响的调用链；
2. 一个子代理检查安全与权限风险；
3. 一个子代理检查测试缺口和边界条件。
不要让多个代理修改文件。等待全部完成后，按严重度汇总，
每条发现给出文件路径、依据和建议的验证方法。

开始前使用保守配置：

[agents]
enabled = true
max_concurrent_threads_per_session = 3
default_subagent_reasoning_effort = "medium"

预期结果：三个线程可以独立工作，主代理等待后统一汇总。若结果重复，下一次提示中把三个职责边界写得更窄；若消耗过高，减少并发数或只委派最嘈杂的探索任务。

---

Part II：Customization 与 Agent 配置

一句话理解 Codex 自定义

Codex 的自定义不是一个配置文件，而是五个互补层：

                         你的任务
                            │
                            ▼
┌──────────────────────────────────────────────────────────────┐
│ AGENTS.md  ── 每次都要遵守的项目规则、命令和约定             │
├──────────────────────────────────────────────────────────────┤
│ Memories   ── 从过去工作中提取、供未来参考的本地上下文        │
├──────────────────────────────────────────────────────────────┤
│ Skills     ── 可复用的标准作业流程、脚本、资料和模板           │
├──────────────────────────────────────────────────────────────┤
│ MCP        ── GitHub、Figma、浏览器、内部系统等外部工具与数据  │
├──────────────────────────────────────────────────────────────┤
│ Subagents  ── 把独立、并行或专业任务交给不同子代理             │
└──────────────────────────────────────────────────────────────┘
                            │
                            ▼
                    更稳定、可复用的结果

它们解决的问题不同：

配置层	核心目的	典型例子	是否应提交到仓库
AGENTS.md	约束 Codex 在项目中的长期行为	测试命令、代码规范、评审要求	项目规则建议提交
Memories	记住过去工作中的有用背景	用户偏好、近期项目上下文	否，本地生成状态
Skills	封装可重复执行的工作流	发版、修复 CI、更新文档	项目 Skill 建议提交
MCP	连接仓库以外的工具和数据	GitHub、Figma、Linear、内部文档	按团队安全策略决定
Subagents	分工、并行、隔离噪声	安全审查、测试、代码探索	自定义 Agent 可提交
Plugins	安装和分发 Skills + MCP 等能力	安装成熟工作流及连接器	通常通过插件目录安装

我应该用哪一种？

开始
 │
 ├─ 这是“每次进入仓库都必须遵守”的规则吗？
 │      └─ 是 → AGENTS.md
 │
 ├─ 这是从过去对话中自然积累、允许偶尔不完整的背景吗？
 │      └─ 是 → Memories
 │
 ├─ 这是会重复执行、步骤相对固定的流程吗？
 │      ├─ 已有成熟插件 → 安装 Plugin
 │      └─ 没有合适插件 → 创建 Skill
 │
 ├─ 执行流程需要访问外部服务或数据吗？
 │      └─ 是 → MCP；通常再配合 Skill 描述“怎么用”
 │
 └─ 任务能拆成独立并行部分，或需要不同专业角色吗？
        └─ 是 → Subagents

最重要的边界：

• 必须稳定执行的团队规范放进 AGENTS.md，不要只依赖 Memories。
• “怎么做”放进 Skill，“连接什么系统”交给 MCP。
• 能用 lint、类型检查、测试、pre-commit hook 强制执行的规则，应同时落到工程基础设施里。
• 子代理更适合读取、搜索、测试、归纳等独立工作；多个代理同时修改同一批文件容易冲突。

推荐落地顺序

官方建议按以下顺序逐层建设：

1. AGENTS.md
   写清仓库约定，并用测试、lint、hooks 强制关键规则
        │
        ▼
2. Plugin / Skill
   有现成插件先安装；没有再创建自己的可复用流程
        │
        ▼
3. MCP
   工作流需要外部系统时，再接入工具与数据
        │
        ▼
4. Subagents
   流程成熟后，把独立、嘈杂或专业工作并行委派

不要一开始就把所有能力都打开。先让最小配置跑通，再逐层增加。

---

AGENTS.md：持久项目指令

目的

AGENTS.md 是 Codex 开始工作前读取的持久指令。适合写：

• 构建、测试、lint、格式化命令；
• 目录结构和优先阅读路径；
• 代码、文档、提交和评审约定；
• 某个目录特有的限制；
• 团队反复提出的审查意见。

保持短小。发生重复错误、反复读取无关文件或多次出现相同 PR 反馈时，再补规则。

放在哪里

~/.codex/
├── AGENTS.md                 # 个人全局偏好
└── AGENTS.override.md        # 临时全局覆盖；存在时优先于 AGENTS.md

repo-root/
├── AGENTS.md                 # 全仓库规则
└── services/
    └── payments/
        ├── AGENTS.md         # 若同目录有 override，则此文件不加载
        └── AGENTS.override.md# payments 目录的覆盖规则

加载与优先级

Codex 每次启动时构建一次指令链：

全局 AGENTS.override.md（若存在）
否则读取全局 AGENTS.md
                │
                ▼
仓库根目录 AGENTS.override.md / AGENTS.md / fallback
                │
                ▼
中间目录 AGENTS.override.md / AGENTS.md / fallback
                │
                ▼
当前工作目录 AGENTS.override.md / AGENTS.md / fallback
                │
                ▼
越靠近当前目录的内容越晚合并，因此优先级越高

每个目录最多加载一个文件，检查顺序为：

1. AGENTS.override.md
2. AGENTS.md
3. project_doc_fallback_filenames 中声明的备用文件名

空文件会被忽略。合并内容默认最多为 32 KiB，达到 project_doc_max_bytes 后停止追加。

相关属性

属性	类型/默认值	作用	什么时候改
CODEX_HOME	环境变量；默认 ~/.codex	改变 Codex 配置、状态和全局 AGENTS.md 的根目录	自动化账号或隔离配置时
project_doc_fallback_filenames	字符串数组	把已有文件名也当作项目指令，如 TEAM_GUIDE.md	团队已有规范文件时
project_doc_max_bytes	字节数；默认 32 KiB	限制合并后项目指令的总大小	指令被截断时；更推荐拆分到子目录

示例 ~/.codex/config.toml：

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

最小可用示例

# AGENTS.md

## 常用命令

- 安装依赖：`pnpm install`
- 单元测试：`pnpm test`
- 静态检查：`pnpm lint`

## 修改要求

- 修改业务逻辑后必须补充或更新测试。
- 不要直接修改生成文件。
- 新增生产依赖前先说明原因并请求确认。

## Code Review Rules

- 优先报告会导致错误行为、安全风险或测试缺失的问题。
- 每条问题必须给出文件位置和可验证依据。

操作流程

1. 在仓库根目录创建 AGENTS.md，先只写最重要的命令与约束。
2. 某个子目录规则不同时，在该目录增加 AGENTS.md 或 AGENTS.override.md。
3. 重新启动 Codex；指令链在每次运行或 TUI 会话启动时重建。
4. 验证：

codex --ask-for-approval never "总结当前加载的指令"
codex --cd services/payments --ask-for-approval never "列出当前生效的指令来源"

5. 把重复犯错、重复评审意见持续沉淀进去。

复杂项目应通过目录级 AGENTS.md 控制规则的继承和覆盖范围。

---

Memories：跨会话本地记忆

目的与边界

Memories 让 Codex 从符合条件的历史对话中提取有用上下文，并在未来会话中使用。它适合“有帮助但不要求绝对可靠”的背景，不适合承载必须执行的团队规则。

• 本地 Codex Memories 与 ChatGPT Web 的 Memory 是两套不同机制。
• 本地记忆默认关闭，存放在 ~/.codex/memories/。
• 记忆在后台生成，不保证对话结束后立刻更新。
• Codex 会对生成的记忆字段做秘密信息脱敏，但仍不要主动把密钥写进记忆；分享 CODEX_HOME 前应检查相关文件。
• 记忆目录是生成状态，不建议把手工编辑当成主要控制方式。

开启与按会话控制

桌面端：Settings > Personalization > Enable memories。

配置文件方式：

[features]
memories = true

[memories]
generate_memories = true
use_memories = true
disable_on_external_context = true
min_rate_limit_remaining_percent = 25

在 ChatGPT 桌面端或 Codex TUI 中使用 /memories，可以单独决定当前会话：

• 是否读取已有本地记忆；
• 是否允许当前会话成为未来记忆的生成输入。

会话级选择不会修改全局设置。

记忆配置属性

属性	类型/默认值	目的
features.memories	boolean；默认 false	打开或关闭本地 Memories 功能总开关
memories.generate_memories	boolean；默认 true	是否让新会话成为记忆生成输入
memories.use_memories	boolean；默认 true	是否把已有记忆注入未来会话
memories.disable_on_external_context	boolean；默认 false	为 true 时，使用过 MCP、Web Search 或 Tool Search 的会话不参与记忆生成
memories.no_memories_if_mcp_or_web_search	旧别名	disable_on_external_context 的兼容名称，新配置优先用新名称
memories.max_raw_memories_for_consolidation	number；默认 256，最大 4096	全局归并时保留的近期原始记忆上限
memories.max_unused_days	number；默认 30，范围 0–365	多久未使用的记忆不再参与归并
memories.max_rollout_age_days	number；默认 30，范围 0–90	允许参与记忆生成的历史会话最大天数
memories.max_rollouts_per_startup	number；默认 16，最大 128	每次启动最多处理多少候选会话
memories.min_rollout_idle_hours	number；默认 6，范围 1–48	会话空闲多久后才可生成记忆
memories.min_rate_limit_remaining_percent	number；默认 25，范围 0–100	剩余额度低于该百分比时不启动记忆生成
memories.extract_model	string；可选	覆盖单会话记忆提取使用的模型
memories.consolidation_model	string；可选	覆盖全局记忆归并使用的模型

Memories 的生成和可用范围可能随客户端版本及账户设置变化。

---

Skills：可复用工作流

目的

Skill 把一个重复工作封装成可发现、可复用的能力。一个 Skill 通常由必需的 SKILL.md 和可选的脚本、参考资料、资产组成：

my-skill/
├── SKILL.md                 # 必需：元数据 + 操作指令
├── scripts/                 # 可选：确定性脚本或校验工具
├── references/              # 可选：按需读取的详细资料
├── assets/                  # 可选：模板、图片、资源
└── agents/
    └── openai.yaml          # 可选：UI、调用策略、工具依赖

Codex 使用渐进式加载：先读取所有 Skill 的 name 和 description；匹配任务后才加载完整 SKILL.md；引用资料和脚本只在需要时使用。因此，description 是否清晰直接影响自动触发。

SKILL.md 必需属性

---
name: release-check
description: 发布前执行构建、测试和变更日志检查。用户要求发版、发布检查或 release checklist 时使用。
---

1. 读取项目发布说明。
2. 执行测试和构建。
3. 汇总失败项，不自动发布。

属性	是否必需	目的	写法建议
name	是	Skill 的唯一名称和显式引用名	简短、稳定、表达任务
description	是	告诉 Codex 何时应该或不应该调用	前置核心用途、触发词和边界
正文 instructions	是	Skill 被选中后要执行的完整步骤	使用祈使句，明确输入、输出和验证

Skill 放置位置

范围	路径	适用场景
当前目录/仓库	$CWD/.agents/skills 及从当前目录到仓库根的各级 .agents/skills	模块或仓库专用流程
用户	$HOME/.agents/skills	个人跨仓库流程
管理员	/etc/codex/skills	共享机器或容器的统一能力
系统	Codex 内置	OpenAI 随产品提供的通用能力

同名 Skill 不会自动合并，可能同时出现在选择器中。Codex 支持指向 Skill 目录的符号链接。

调用方式

• 显式调用：CLI/IDE 输入 $skill-name，或通过 /skills 选择；ChatGPT 中可输入 @ 选择。
• 隐式调用：任务匹配 description 时，Codex 可自动选择。

agents/openai.yaml 可选属性

属性	目的
interface.display_name	UI 中展示的友好名称
interface.short_description	UI 短描述
interface.icon_small	小图标路径
interface.icon_large	大图标路径
interface.brand_color	品牌色，如 #3B82F6
interface.default_prompt	调用 Skill 时建议使用的默认提示
policy.allow_implicit_invocation	是否允许隐式触发；默认 true；设为 false 后仍可显式 $skill 调用
dependencies.tools[].type	依赖类型，例如 mcp
dependencies.tools[].value	依赖工具或 MCP Server 的标识
dependencies.tools[].description	依赖用途说明
dependencies.tools[].transport	连接方式，例如 streamable_http
dependencies.tools[].url	依赖服务地址

示例：

interface:
  display_name: "Release Check"
  short_description: "发布前检查构建、测试和变更日志"
  icon_small: "./assets/icon.svg"
  brand_color: "#3B82F6"
  default_prompt: "请执行发布前检查并汇总阻塞项"

policy:
  allow_implicit_invocation: true

dependencies:
  tools:
    - type: "mcp"
      value: "projectDocs"
      description: "项目文档 MCP Server"
      transport: "streamable_http"
      url: "PROJECT_DOCS_MCP_ENDPOINT"

启用或停用单个 Skill

不删除 Skill 也可以在 ~/.codex/config.toml 中禁用：

[[skills.config]]
path = "/absolute/path/to/my-skill/SKILL.md"
enabled = false

属性	类型	目的
skills.config	object 数组	保存逐个 Skill 的启停覆盖项
skills.config[].path	路径	指向包含定义的 SKILL.md
skills.config[].enabled	boolean	启用或禁用该 Skill

修改后重启 Codex，并重新触发一次任务验证 Skill 是否被识别。

创建流程

1. 先查插件目录；已有成熟工作流时优先安装插件。
2. 没有合适插件时，在 Codex 中调用 $skill-creator，或手工创建 Skill 目录和 SKILL.md。
3. 一开始优先写纯指令；只有需要确定性行为或外部工具时才增加脚本。
4. 用明确匹配和明确不匹配的提示测试 description。
5. 若 Skill 未出现，重启 Codex。
6. 需要跨团队分发或同时携带连接器时，把 Skill 打包成 Plugin。

---

Plugins：安装与分发单元

Plugin 不是另一种工作流语言。Skill 仍是工作流的创作格式，而 Plugin 是可安装、可分享的分发单元，可以同时打包：

• 一个或多个 Skills；
• 已注册的 MCP 连接或 MCP 配置；
• 展示资源等配套内容。

安装流程：

1. 在 ChatGPT Web 或桌面端打开 Plugins。
2. 搜索或浏览插件并打开详情。
3. 点击加号安装。
4. 如插件需要连接器，按提示登录并审查权限。
5. 新建聊天，明确要求 ChatGPT/Codex 使用该插件。

判断原则：本地编写和仓库专用工作流用 Skill；跨项目分发、组合多个 Skills 或捆绑连接器时用 Plugin。

---

MCP：连接外部工具与上下文

目的与结构

MCP（Model Context Protocol）把 Codex 连接到仓库以外的系统。

┌──────────────┐      MCP Client       ┌──────────────────────┐
│ Codex / Host │ ────────────────────► │ MCP Server           │
└──────────────┘                       │ Tools     可执行动作  │
                                       │ Resources 可读取数据  │
                                       │ Prompts   提示模板    │
                                       └──────────────────────┘

常见用法：读取内部文档、查询 issue、操作 GitHub、获取 Figma 设计、控制浏览器。MCP Server 的动作权限可能很强，应使用最小权限、工具白名单和审批策略。

两种连接类型

类型	适合场景	核心配置
STDIO	本地命令启动的 Server	command、args、env
Streamable HTTP	远程地址提供的 Server	url、OAuth/Bearer、Headers

配置默认写在 ~/.codex/config.toml；可信项目也可以写 .codex/config.toml。桌面端、CLI 和 IDE 扩展共享同一个 Codex Host 上的 MCP 配置。

STDIO 属性

每个 Server 使用 [mcp_servers.<server-name>] 表：

属性	必需	目的
command	是	启动 MCP Server 的命令
args	否	传给命令的参数数组
env	否	明确设置给 Server 的环境变量映射
env_vars	否	允许从本地或远程执行环境转发的变量名
cwd	否	启动 Server 时的工作目录
experimental_environment	否	设为 remote 时，在可用的远程执行环境启动 STDIO Server

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

env_vars 也可以声明来源：

env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

字符串和 source = "local" 从本地环境读取；source = "remote" 需要远程 MCP STDIO 支持。

Streamable HTTP 属性

属性	必需	目的
url	是	MCP Server 地址
auth	否；默认 oauth	认证方式；可信第一方来源可用 chatgpt，并以已存 OAuth 为回退
bearer_token_env_var	否	保存 Bearer Token 的环境变量名；避免把 Token 直接写进 TOML
http_headers	否	静态 HTTP Header 映射；不要在仓库配置中放秘密
env_http_headers	否	Header 名到环境变量名的映射

[mcp_servers.design]
url = "DESIGN_MCP_ENDPOINT"
bearer_token_env_var = "DESIGN_MCP_TOKEN"
http_headers = { "X-Region" = "cn-east" }

所有 Server 通用属性

属性	默认值	目的
startup_timeout_sec	10	Server 启动超时秒数
tool_timeout_sec	60	单次工具执行超时秒数
enabled	启用	不删除配置的情况下停用 Server
required	false	为 true 时，启用的 Server 初始化失败会导致启动失败
enabled_tools	未限制	工具允许列表
disabled_tools	空	工具拒绝列表；在 enabled_tools 之后应用
default_tools_approval_mode	可选	Server 内工具的默认审批模式：auto、prompt、writes、approve；writes 会对非只读工具询问
tools.<tool>.approval_mode	可选	覆盖某一个工具的审批模式
mcp_oauth_callback_port	临时端口	顶层配置；OAuth 必须固定回调端口时使用
mcp_oauth_callback_url	本地回调	顶层配置；远程 Devbox 或自定义回调地址时使用

建议从工具白名单和 prompt/writes 开始，确认工具行为后再放宽。

配置流程

CLI 快速添加 STDIO Server：

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list
codex mcp --help

OAuth Server：

codex mcp login <server-name>

桌面端：

1. Settings > MCP servers > Add server。
2. 填写名称，选择 STDIO 或 Streamable HTTP。
3. 填写命令或 URL，保存并重启。
4. 需要 OAuth 时点击 Authenticate。
5. 在输入框使用 /mcp 检查连接。

IDE 扩展流程相同，保存后选择 Restart extension。ChatGPT Web 不读取本地 config.toml，需通过 Plugin 使用远程 MCP 工具。

具体字段是否可用取决于当前 Codex 与 MCP Server 的协议版本。

---

Subagents：专业分工与并行执行

目的

子代理把探索日志、测试输出、堆栈信息等噪声留在独立线程，只把结论汇总回主线程。适合：

• 并行代码探索；
• 安全、质量、测试分别审查；
• 大文档分片归纳；
• 使用不同工具或 MCP 的专业角色。

代价是每个子代理都会独立消耗模型与工具资源，因此通常比单代理使用更多 Token。写密集型并行任务还可能产生文件冲突。

内置角色与触发方式

Codex 内置：

Agent	用途
default	通用回退角色
worker	实现和修复
explorer	以读取、搜索和代码探索为主

明确告诉 Codex 如何拆分、是否等待全部结果、最终返回什么：

并行审查这个分支：启动一个子代理检查安全风险，一个检查测试缺口，
一个检查可维护性。等待全部完成后，按类别汇总，并附文件位置。

全局属性

写入 ~/.codex/config.toml 或可信项目的 .codex/config.toml：

[agents]
enabled = true
max_concurrent_threads_per_session = 4
default_subagent_reasoning_effort = "medium"
interrupt_message = true

属性	类型/默认值	目的
agents.enabled	boolean；默认 true	启用或禁用多代理工具
agents.max_concurrent_threads_per_session	number；未设置时由 Codex 决定	限制同时打开的子代理线程数，不含主线程
agents.max_threads	number；旧别名	兼容旧配置，新配置使用上面的完整名称
agents.default_subagent_model	string；可选	子代理默认模型；显式 spawn 值优先
agents.default_subagent_reasoning_effort	string；可选	子代理默认推理强度；显式 spawn 值优先
agents.interrupt_message	boolean；默认 true	中断代理时，是否在其上下文中记录模型可见的中断消息

子代理默认继承父代理的模型、推理强度、沙箱和审批策略。显式 spawn 参数、[agents] 默认值和自定义 Agent 文件可以进一步覆盖；权限模式应在委派前确认。

自定义 Agent 文件

位置：

~/.codex/agents/*.toml       # 个人自定义 Agent
.codex/agents/*.toml         # 项目自定义 Agent

每个文件定义一个 Agent，必需属性如下：

属性	必需	目的
name	是	Codex 识别和引用 Agent 的真实名称；文件名只是惯例
description	是	告诉 Codex 什么时候应该使用它
developer_instructions	是	定义角色行为、边界和输出要求

还可使用普通 config.toml 属性，例如：

可选属性	目的
model	为该角色指定模型
model_reasoning_effort	为该角色指定推理强度
sandbox_mode	限制该角色的文件和命令权限，例如只读
mcp_servers	只给该角色配置需要的外部工具
skills.config	控制该角色可使用的 Skills

示例 .codex/agents/security-reviewer.toml：

name = "security_reviewer"
description = "只读安全审查员；在用户要求安全检查、威胁分析或权限审查时使用。"
sandbox_mode = "read-only"
model_reasoning_effort = "high"
developer_instructions = """
只进行安全审查，不修改文件。
优先检查认证、授权、秘密信息、输入校验和依赖风险。
每条发现必须给出文件位置、风险说明和验证依据。
"""

如果自定义名称与 explorer 等内置 Agent 相同，自定义版本优先。

操作流程

1. 先确认任务能否拆成互不依赖的子任务。
2. 简单分工直接写进提示词；反复使用的专业角色再创建自定义 Agent。
3. 给读取型 Agent 设置 sandbox_mode = "read-only"。
4. 限制并发数，避免资源浪费和写冲突。
5. 要求主代理等待所有结果，并只汇总证据和结论。
6. 若多个 Agent 必须写文件，让它们负责互不重叠的文件或目录。

---

Agent 协作：任务委派、控制权与生命周期

一句话理解：Spawn 是创建执行者，Dispatch 是派发工作，Delegation 是委托责任，Tool call 是调用能力，Handoff 是交接当前分支的控制权。 它们属于不同层次，不是五个同义命令。

以下是通用协作模型，不是 Codex 固定内部状态机。Codex 子代理以主线程收集结果的工作流为主；Agents SDK 的 Handoff 则是另一种编排模式，不应直接套成 Codex 的某个同名命令。官方资料见本节末尾。

五个术语：工作交出去，谁继续负责？

术语	含义	控制权与返回关系
spawn	创建子代理或新的执行线程	创建本身不等于把最终回复权交出去；是否携带初始任务取决于接口
dispatch	将任务或消息路由给工具、队列或已有 Agent	是派发动作，不一定创建 Agent，也不一定改变最终负责人
delegation	把有边界的子任务委派给其他执行者	常见主从模式中，子代理负责局部执行，主代理仍负责集成与交付；广义委派也可通过 Handoff 实现
tool call	Agent 请求运行某项工具能力	通常由运行时执行并返回结果，原 Agent 再继续；工具也可以封装另一个 Agent
handoff	将当前对话分支交给另一个 Agent 接管	接收方成为当前分支的负责人，不是默认“做完自动回到主代理”；回交需另行设计

“控制权”至少分三层：谁决定下一步、谁负责最终回复、谁有实际操作权限。Handoff 改变编排负责人，不等于提权；角色叫 architect 或 worker 也不会自动获得写文件、联网或部署权限。权限由运行环境与审批机制约束。

A. Tool call: call -> result -> continue

   Agent A --> Runtime / Tool --> result --> Agent A --> User

B. Delegation: manager retains final ownership

   User --> Manager --+--> Worker A --+--> Manager --> User
                      +--> Worker B --+
                      |
                      +--> Manager's own independent work

C. Handoff: specialist takes over this branch

   User --> Agent A --handoff--> Agent B --> User
                                  |
                                  +--> further handoff (if configured)

角色不是固定流水线，也不一定各开一个 Agent

角色	主要职责	典型交付物
manager / orchestrator	拆任务、管理依赖和预算、收集结果、最终交付	任务分配、集成结果、风险说明
architect	明确方案、接口、约束和验收标准	设计与任务边界，不只是大段设想
explorer	阅读代码、查找调用链、定位事实	文件位置、现有行为与证据
worker	在约定范围内实现或修复	补丁、改动文件、验证记录
verifier	对照验收标准验证结果，检查回归	通过/失败结论、复现步骤与日志
reviewer	审查设计、质量、安全和维护风险	按严重度排序的问题及依据

这里的 architect、verifier（不是 verifer）、reviewer、manager 是职责名称，不是在宣称它们都是 Codex 内置角色。可以由主代理兼任，也可以按上一节的方法定义自定义 Agent；简单任务无需凑齐所有角色。

从接单到收尾：一个完整逻辑流程

下图是推荐的工程流程，方框表示职责阶段，不保证每个方框都是独立线程。只有互不阻塞的工作才适合并行；验证应针对最终集成产物，不能只相信 Worker 的“已完成”。

User request
     |
     v
Manager: scope + constraints + budget + acceptance criteria
     |
     v
Architect / Explorer: inspect -> design -> split dependencies
     |
     v
Manager: execute locally OR delegate bounded tasks
     |
     +--> Worker A: implement scope A --+
     +--> Worker B: implement scope B --+  (parallel only if independent)
     |                                 |
     +---------------------------------+
     |
     v
Manager: collect evidence -> inspect changes -> integrate
     |
     v
Verifier / Reviewer: test integrated result + assess risks
     |
     +-- FAIL --> bounded repair --> integrate --> verify again
     |
     +-- BLOCKED / budget exhausted --> report limits / request decision
     |
     +-- PASS --> final answer --> close unused agent threads

每个执行者内部还会重复一个较小的循环：

Context + instructions
          |
          v
    Choose next action <--------------------+
          |                                |
          +--> Tool call --> result / error +
          +--> Need approval --> pause -----+ (resume if approved)
          +--> Final result --> completed
          +--> Cannot proceed --> blocked / failed / cancelled

这些是逻辑状态标签，不是某个 API 的枚举定义。暂停等待不等于失败，完成任务不等于线程已关闭；读取上下文、执行、等待、失败处理和资源清理需要分别考虑。

一次好的委派，至少说清六件事

1. 目标与验收：交付什么，怎样判断完成。
2. 上下文：相关文件、已知事实、依赖；不要假设子代理自动知道所有聊天内容。
3. 权限与写入范围：可以读写什么，哪些操作要审批；并行 Worker 不修改同一组文件。
4. 输出格式：结论、补丁路径、测试结果和未解决问题，而不是倾倒全部日志。
5. 预算与停止条件：时间、重试次数、遇到阻塞如何上报；避免无限返工。
6. 回收与交付责任：由谁集成、谁验证、谁最终答复；不再需要的线程及时关闭。

示例请求（职责分工，不是可执行 API）：

请使用子代理协作，主代理保留最终交付责任。
先由主代理检查依赖并确定接口和验收标准。
将两个互不依赖的模块分给 Worker A/B，分别限定写入目录。
主代理同时做不重叠的集成准备，不重复子代理的工作。
收齐结果后检查并集成补丁，再让 Verifier 验证最终产物。
失败最多返工两轮；仍失败则报告证据与阻塞，不宣称成功。
最后汇总改动、验证结果和剩余风险，关闭不再使用的线程。

截至 2026-09-08 核对的官方说明：本地 Codex 在用户明确要求，或适用的 AGENTS.md / Skill 指令要求委派时使用子代理；具体工具名称和可用性以当前客户端暴露的接口为准，不要把上面的概念词直接当作 CLI 命令。

参考：

• OpenAI Docs：Subagents：子代理触发、独立工作与主线程汇总。
• OpenAI Docs：Orchestration and handoffs：Agents as tools 保留 Manager 的回复责任，Handoff 将当前分支交给 Specialist。

---

Rules：控制哪些命令能在沙箱外运行

Rules 是实验性能力，用来给命令前缀设置沙箱外执行决策。它与 approval_policy、sandbox_mode 配合，而不是替代它们。

文件位置：

~/.codex/rules/*.rules          # 用户级
<repo>/.codex/rules/*.rules     # 项目级；仅可信项目加载

prefix_rule() 属性：

属性	必需/默认	目的
pattern	必需	非空命令参数前缀；元素可为字面量或同位置候选值集合
decision	默认 allow	allow 直接允许、prompt 每次询问、forbidden 直接阻止
justification	可选	在审批或拒绝信息中展示规则原因；禁止时建议写替代方案
match	默认 []	应当命中的内联测试样例
not_match	默认 []	不应命中的内联测试样例

多条规则命中时采用最严格结果：forbidden > prompt > allow。

# ~/.codex/rules/default.rules
prefix_rule(
    pattern = ["gh", "pr", ["view", "list"]],
    decision = "prompt",
    justification = "读取远程 PR 前请求确认",
    match = ["gh pr view 123", "gh pr list"],
    not_match = ["gh issue list"],
)

操作流程：

1. 在激活配置层旁创建 rules/ 与 .rules 文件。
2. 写 pattern、决策和正反样例。
3. 先测试规则：

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 123

4. 重启 Codex。
5. 对复合 Shell 命令保持谨慎：Codex 只会在能安全解析简单命令链时逐段检查；包含重定向、变量、通配符或控制流时，会把整段脚本作为单个调用保守匹配。

Rules 应与沙箱、审批和工程检查共同使用。

Speed：速度与成本

Fast mode 是同一受支持模型的加速服务层，不是另一个模型；速度更快，但会消耗更多 Credits。Codex-Spark 则是单独的快速模型选择，两者不要混淆。

service_tier = "fast"

[features]
fast_mode = true

会话内操作：

/fast on
/fast off
/fast status

具体支持模型、倍率、资格与价格容易变化，请始终查看 Speed 和 Pricing 当前说明。

Record & Replay：把演示变成 Skill

Record & Replay 当前用于 macOS，且需要 Computer Use 可用并启用。适合“流程固定、偏好明确、演示比文字描述容易”的操作。

你演示一次完整流程
        │
        ▼
Codex 观察必要的窗口与动作
        │
        ▼
生成 Skill：触发条件 + 输入 + 步骤 + 验证
        │
        ▼
新会话提供本次变量，复用该 Skill

操作流程：

1. 桌面端选择 ChatGPT Work 或 Codex，打开 Plugins。
2. 点击 + > Record a skill。
3. 补充目标与可变输入，提交并批准录制。
4. 在 Mac 上完整演示一次，完成后停止录制。
5. 审查生成的 Skill，补充隐藏偏好、决策点和成功标准。
6. 新建聊天，调用该 Skill 并提供本次不同的输入。

录制时避免秘密和敏感数据。需要跨团队稳定分发、捆绑多个 Skills 或连接器时，再打包为 Plugin。

Linux 与 Windows

Linux 桌面端

Linux 桌面端有独立的安装与更新流程；config.toml、Skills、MCP 和 Agent 的核心概念与其他本地 Codex Host 一致。

Windows 原生沙箱

[windows]
sandbox = "elevated"       # 官方推荐；可用管理员权限时
# sandbox = "unelevated"   # 无管理员权限或 elevated 初始化失败时回退

原生 Windows 运行时应先尝试 elevated；无法使用管理员权限或初始化失败时，再回退到 unelevated。

WSL2

WSL2 中 Codex 运行在 Linux 环境，使用 Linux 沙箱而不是 Windows 原生沙箱。适合依赖 Linux 工具链或代码本来就位于 WSL 的项目。WSL1 从 Codex 0.115 起不再受支持。

wsl --install
wsl

进入 WSL 并完成 Codex 安装后，可验证命令是否可用：

codex --version

仓库尽量放在 ~/code/...，避免 /mnt/c/... 的 I/O、符号链接和权限问题。

组合使用：Skill + MCP + Subagents

单独使用已经有价值，组合后更适合真实团队流程：

用户："审查这个 PR，并核对 Linear 需求与 Figma 设计"
                          │
                          ▼
       AGENTS.md：项目规范、测试命令、评审标准
                          │
                          ▼
       Skill：定义 PR 审查的固定步骤和输出格式
                          │
                ┌─────────┴─────────┐
                ▼                   ▼
      MCP：Linear / Figma      Subagents：并行分工
      获取外部需求和设计       ├─ 代码风险
                               ├─ 测试缺口
                               └─ 文档/API 核对
                └─────────┬─────────┘
                          ▼
                 主代理汇总最终报告

如果 Skill 依赖 MCP，应在 agents/openai.yaml 的 dependencies.tools 中声明依赖。这样 Skill 负责流程，MCP 负责能力边界，子代理负责并行执行。

Part III：Developers 开发者篇

本篇介绍如何把 Codex 从“聊天里的编程助手”扩展为开发流程、CI/CD、内部平台和团队工具的一部分。

先看选型：我到底应该用哪个入口？

这是开发者最容易混淆的地方。先按目标选入口，再看后面的具体操作。

你想让 Codex 做什么？
│
├─ 在终端或脚本里完成一次任务
│  └─ codex exec（非交互模式）
│
├─ 在 TypeScript / Python 程序中持续发起任务
│  └─ Codex SDK
│
├─ 自己开发一套完整 Codex 客户端界面
│  └─ App Server
│
├─ 让其他 Agent 把 Codex 当成一个专业工具调用
│  └─ codex mcp-server
│
├─ 在 GitHub Actions 中审查、修复或验证代码
│  └─ openai/codex-action
│
├─ 在 Codex 每次调用工具前后执行自定义检查
│  └─ Hooks
│
└─ 让团队在 GitHub / Slack / Linear 中直接派活
   └─ 对应的第三方集成

方案	最适合	调用方式	是否保留多轮线程	典型例子
交互式 Codex	人和 Codex 一起开发	桌面端、IDE、CLI	是	写代码、调试、代码审查
codex exec	Shell、CI、定时任务	一条命令	可恢复	每晚扫描技术债
Codex SDK	自己的 Node/Python 服务	程序 API	是	内部研发机器人
App Server	自己开发完整客户端	JSON-RPC 流式协议	是	自定义桌面端或 IDE 插件
Codex MCP Server	多 Agent 编排	MCP 工具调用	是	主管 Agent 把编码任务交给 Codex
GitHub Action	GitHub 工作流	Workflow YAML	单次任务为主	PR 自动审查

一句话记忆：脚本用 exec，应用用 SDK，做客户端用 App Server，给其他 Agent 调用用 MCP Server，GitHub 自动化用 Action。

1. 开发工作流：代码审查与集成终端

1.1 使用 /review 审查代码

在桌面端、IDE 扩展或 CLI 输入：

/review

然后选择审查范围：

• 当前未提交的变更：包含已暂存、未暂存和未跟踪文件，适合提交前自查。
• 相对某个基础分支的变更：例如当前分支相对 main 的全部修改，适合 PR 前检查。
• 某一个提交：适合定位一次提交引入的问题。
• 自定义审查说明：例如“重点检查鉴权绕过、并发安全和数据库事务”。

Codex 会启动专门的 reviewer，给出按优先级排列、可执行的发现；审查本身不会修改工作区。桌面端和 IDE 还可以选择把结果显示在代码行内，或作为独立任务显示。

一个适合小白直接使用的审查提示词：

请审查当前未提交的代码：
1. 先找会导致程序错误、数据丢失或安全问题的缺陷。
2. 再检查测试是否覆盖了失败路径和边界条件。
3. 每个问题说明文件位置、触发条件、影响和建议修法。
4. 不要直接修改代码，先给我审查报告。

团队可以把固定审查标准放进仓库的 AGENTS.md：

## Code Review Rules

- 所有数据库写入必须有失败路径测试。
- 新增 API 必须验证鉴权和输入边界。
- 不要把日志中的用户 Token、Cookie 或密码作为调试信息输出。

如果已安装并登录 GitHub CLI（gh），Codex 还能读取 PR 上下文。GitHub 集成中可以用 @codex review 请求云端审查。

1.2 集成终端怎样用

桌面端每个聊天都有一个与当前项目或 worktree 对应的终端。点击右上角终端按钮，或按 `Ctrl+`` 打开。Codex 可以读取当前终端输出，因此你可以先运行命令，再让它解释失败原因。

git status
npm test
npm run lint

推荐流程：

在终端运行测试
      │
      ├─ 成功 ──> 让 Codex 总结改动并准备提交说明
      │
      └─ 失败 ──> 把当前终端输出交给 Codex 分析
                       │
                       └─ 修复后重新运行同一命令

常用测试、启动、格式化命令还可以做成 Local Environment 的 Actions，在集成终端中一键运行。

2. 运行环境：Local、Worktree、Cloud 怎么选

环境	代码在哪里运行	是否隔离当前工作区	适合场景
Local	当前机器、当前项目目录	否	需要本机工具、立即查看修改
Worktree	当前机器的独立 Git worktree	是	并行任务、避免打乱当前分支
Cloud	OpenAI 配置的远程容器	是	后台运行、团队协作、GitHub/Slack/Linear 派活

2.1 Local Environment

Local Environment 是桌面端的本地项目配置。它可以声明新 worktree 创建后需要自动执行的 setup script，也可以提供常用 Actions。配置会生成在项目的 .codex 目录中；不含秘密时，可以提交到 Git，让团队共用。

适合放进 setup script 的内容：

npm ci
npm run db:generate

不要把 API Key 直接写在脚本里；使用环境变量或团队的秘密管理方式。

2.2 Git worktree：并行开发不互相踩文件

在桌面端新建任务时选择 Worktree，选定基础分支后提交任务。Codex 会在 $CODEX_HOME/worktrees 下创建独立工作区。它默认可能处于 detached HEAD，因此准备保留成果时，应创建分支，或使用 Handoff to Local 把聊天和代码带回本地工作区。

main 工作区：你正在修线上 Bug
│
├─ worktree A：Codex 重构支付模块
├─ worktree B：Codex 补 API 测试
└─ worktree C：Codex 更新开发文档

注意：同一个 Git 分支不能同时检出到两个 worktree。Git 忽略的文件默认也不会复制；确实需要 .env 等本地文件时可使用 .worktreeinclude，但复制秘密文件会扩大泄露面，应只列最少文件。

2.3 Cloud Environment

云端任务的大致流程：

创建远程容器
   ↓
检出指定分支或提交
   ↓
运行 setup script（缓存恢复时可运行 maintenance script）
   ↓
Codex 修改代码并运行检查
   ↓
返回 diff，等待人工审查或创建 PR

几个容易踩坑的点：

• setup script 与 Agent 阶段不是同一个 Bash 会话，脚本中的普通 export 不会自动保留；长期变量应通过环境设置或 shell 启动文件配置。
• 环境变量在整个云端任务可用；Secrets 会加密保存，只在 setup 阶段提供，并在 Agent 阶段开始前移除。
• setup 阶段可以联网；Agent 阶段默认关闭网络。只开放确有必要的域名和方法。
• 依赖缓存最长可保留约 12 小时；修改 setup、maintenance、环境变量或 Secrets 会使缓存失效。
• 固定 Node、Python 等运行时版本，避免“昨天能跑、今天镜像升级后失败”。

三种环境的权限、联网和生命周期不同，创建任务前应先确认运行位置。

3. Hooks：在 Agent 循环中插入团队检查

Hooks 是在 Codex 生命周期事件发生时自动运行的脚本。它适合做日志、秘密扫描、命令校验、补充上下文，以及在危险工具调用前阻止执行。它不是 Skill：Skill 描述“如何完成一类任务”，Hook 则在指定事件发生时被强制触发。

常见事件：

事件	触发时机	常见用途
SessionStart / SessionEnd	会话开始或结束	初始化、审计
UserPromptSubmit	用户提示提交后	补充项目上下文
PreToolUse	工具执行前	拦截危险命令、改写参数
PermissionRequest	请求权限时	接入审批策略
PostToolUse	工具完成后	记录结果、执行校验
PreCompact / PostCompact	上下文压缩前后	保存关键状态
SubagentStart / SubagentStop	子代理开始或结束	追踪并行任务
Stop	Agent 准备结束	检查测试或交付条件

最小配置结构如下。用户级文件可放在 ~/.codex/hooks.json，项目级可放在 .codex/hooks.json；也可以写进对应 config.toml。项目 Hook 只有在项目受信任时才会运行。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "ShellToolCall",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/check_shell.py"
          }
        ]
      }
    ]
  }
}

启用功能：

[features]
hooks = true

Hook 通过标准输入收到 JSON，通过退出码和标准输出返回决定。下面是一个 PreToolUse 拒绝执行时的概念性响应：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "命令触及生产数据库，请改用只读环境"
  }
}

操作流程：

1. 先用只记录、不阻止的 Hook 观察实际输入结构。
2. 针对明确的工具类型设置 matcher，不要一开始匹配所有工具。
3. 在 Codex 中运行 /hooks 检查并信任脚本的精确版本。
4. 用一条允许的命令和一条应被拒绝的命令分别测试。
5. 将 Hook 脚本和项目配置一起做代码审查。

多个来源中匹配的 Hooks 都会运行；同一事件的匹配项可能并发执行。PreToolUse 能阻止或改写本地工具调用，但不应被当作唯一安全边界；PostToolUse 发生在副作用之后，不能撤销已经执行的操作。

4. codex exec：脚本和 CI 的第一选择

codex exec 是非交互模式：任务完成后把最终回答写到标准输出，过程事件写到标准错误，因此可以方便地被脚本接住。

codex exec "检查当前仓库的测试失败原因，只输出结论和建议"

默认使用只读沙箱。如果任务需要改文件，要明确开放工作区写权限：

codex exec --sandbox workspace-write \
  "修复 lint 错误，运行 lint 验证，不要修改业务行为"

常用选项：

目标	命令/选项	说明
不保存会话状态	--ephemeral	适合一次性 CI 任务
机器读取事件	--json	输出 JSONL 事件流
只保存最终回答	-o result.md	等同 --output-last-message
强制结构化结果	--output-schema schema.json	让程序按 JSON Schema 消费结果
不读取用户配置	--ignore-user-config	提高 CI 可重复性
不读取 Rules	--ignore-rules	仅在工作流自己提供边界时使用
恢复上次线程	codex exec resume --last "继续"	延续最近一次任务

结构化结果示例：

{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "risk": { "type": "string", "enum": ["low", "medium", "high"] },
    "tests_passed": { "type": "boolean" }
  },
  "required": ["summary", "risk", "tests_passed"],
  "additionalProperties": false
}

codex exec \
  --sandbox read-only \
  --output-schema schema.json \
  -o review.json \
  "审查当前改动并按指定结构返回结果"

安全提醒：自动化环境应使用最小沙箱；只有确认目录安全时才用 --skip-git-repo-check。CODEX_API_KEY 可用于 codex exec，但不要把 Secret 设置成运行仓库不受信任代码的整个 Job 的全局环境变量。

5. Codex SDK：把 Codex 放进自己的程序

SDK 适合服务端程序、内部工具和 CI 平台。它提供 thread，使应用可以继续同一次对话，而不是每次从零开始。

TypeScript

要求 Node.js 18 或更高版本：

npm install @openai/codex-sdk

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

const first = await thread.run("检查仓库结构，给出重构计划，先不要改代码");
console.log(first.finalResponse);

const second = await thread.run("实施计划中的第一步并运行测试");
console.log(second.finalResponse);

保存 thread.id 后，可以在另一个进程中恢复：

const resumed = codex.resumeThread(savedThreadId);
const result = await resumed.run("继续处理上次未完成的测试失败");

Python

要求 Python 3.10 或更高版本：

pip install openai-codex

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)
    result = thread.run("为当前模块补充单元测试，并运行测试验证")
    print(result.final_response)

Python 异步程序可使用 AsyncCodex。沙箱常用预设是 read_only、workspace_write 和 full_access；优先选择能完成任务的最小权限。一次 run 指定的沙箱会应用到该次及后续轮次。

6. App Server：开发自己的 Codex 客户端

App Server 面向需要完整客户端体验的开发者，它提供认证、历史会话、审批、流式事件等底层能力。如果只是后台自动化或 CI，优先使用 SDK，不必承担协议和界面状态管理成本。

通信方式：

• 默认：通过 stdio 传输一行一个 JSON 消息。
• Unix socket：适合同机进程通信。
• WebSocket：目前是实验能力，不应默认用于生产关键链路。

协议生命周期：

客户端连接
   ↓
initialize → initialized
   ↓
thread/start（或 resume / fork）
   ↓
turn/start
   ↓
持续接收 item 事件、审批请求和增量输出
   ↓
turn/completed

生成与当前版本匹配的类型和 Schema：

codex app-server generate-ts --out ./schemas
codex app-server generate-json-schema --out ./schemas

调试远程 TUI：

codex app-server --listen LOCAL_APP_SERVER_ENDPOINT
codex --remote LOCAL_APP_SERVER_ENDPOINT

明文 WebSocket 只应用于本机或 SSH 转发；跨机器部署必须设计认证并使用 TLS 加密 WebSocket。客户端需要处理 thread、turn、item 三类核心对象，以及审批、错误、断线恢复和版本兼容。实验 API 必须显式声明能力；没有明确需求时只使用稳定接口。

7. Codex MCP Server：把 Codex 交给其他 Agent 调用

这里的方向很重要：普通 MCP 配置是“Codex 调用外部工具”；codex mcp-server 则是“Codex 自己作为 MCP 工具，被另一个 Agent 调用”。

普通 MCP：       Codex ──调用──> GitHub / Linear / 数据库

Codex MCP Server：主管 Agent ──调用──> Codex ──修改代码/运行测试

启动与检查：

codex mcp-server
npx @modelcontextprotocol/inspector codex mcp-server

它主要暴露两个工具：

工具	用途	关键参数
codex	创建新的 Codex 任务线程	必填 prompt；可传 cwd、model、sandbox、approval-policy 等
codex-reply	继续已有线程	必填 threadId 和 prompt

第一次调用后保存返回的 structuredContent.threadId，后续用它继续上下文：

调用 codex(prompt="分析支付模块", cwd="/repo")
                │
                └─ 返回 threadId
                         │
调用 codex-reply(threadId=..., prompt="现在补测试并修复问题")

Python Agents SDK 连接概念示例：

from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "codex", "args": ["mcp-server"]},
    client_session_timeout_seconds=360000,
) as codex_server:
    # 把 codex_server 传给负责总体编排的 Agent
    ...

它适用于 Codex 只是复杂系统中的“编码专家”的场景。若应用只需要直接发起 Codex 线程，SDK 通常更简单。

8. GitHub Action：让 Codex 进入 CI/CD

官方 Action 是 openai/codex-action@v1。它负责安装 Codex CLI，并在提供 API Key 时通过代理运行 codex exec。

一个最小的只读 PR 审查工作流：

name: Codex PR review

on:
  pull_request:

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          persist-credentials: false

      - id: codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/review.md
          sandbox: read-only

.github/codex/review.md 可以写：

审查本次 PR。优先报告会导致安全问题、数据错误、崩溃或兼容性破坏的问题。
每个发现必须给出文件位置、触发方式、影响和最小修复建议。
如果没有实质问题，明确输出“未发现阻断问题”。不要修改代码。

常用输入：

输入	作用
prompt / prompt-file	二选一，定义任务
codex-args	追加 CLI 参数
model / effort	选择模型和推理强度
sandbox	定义文件系统权限
output-file	保存最终消息
codex-version	固定 CLI 版本，提高可重复性

Action 的 final-message 输出可以交给后续步骤发布评论；发布 PR 评论需要单独配置写权限。对来自 fork 或外部贡献者的 PR，要把代码和提示词都视为不受信任输入，避免给 Job 过宽权限。只读沙箱本身不是全部安全措施，还应关闭 checkout 凭证、收紧 GitHub permissions、限制允许触发的用户或 Bot。

9. GitHub、Slack、Linear 团队集成

GitHub

完成 Codex cloud、GitHub 仓库和 Code review 设置后，可在 PR 中使用：

@codex review
@codex security review
@codex fix the P1 issue

还可以开启自动审查。项目专属标准继续放在 AGENTS.md 的 ## Code Review Rules 中。

Slack

先配置 Codex cloud、连接 GitHub 与环境，再安装 Slack 应用并邀请 @Codex。在频道或线程中提及它并描述任务，Codex 会创建云端任务；必要时在消息里明确仓库和环境，避免自动匹配错误。

@Codex 请在 acme/api 仓库中定位这个报错，补回归测试并准备一个 PR。

云端任务完成后仍应由人审查 diff 和测试结果。

Linear

付费计划可连接云端 Linear 集成，然后把 issue 分配给 Codex，或在评论中 @Codex。如果只是希望本地 Codex 读取和更新 Linear，可以添加它的 MCP Server：

codex mcp add linear --url LINEAR_MCP_ENDPOINT
codex mcp login linear

等价配置：

[mcp_servers.linear]
url = "LINEAR_MCP_ENDPOINT"

10. 开发者命令与 IDE 设置

排查配置和运行状态

命令	什么时候用
/status	查看当前模型、目录、权限和会话信息
/debug-config	查清某个配置最终来自哪个文件或层级
codex --strict-config	让无效或未知配置直接报错，适合 CI 验证
/model	临时切换模型和推理强度
/permissions	调整当前任务的审批与权限
/experimental	查看或切换实验功能
/memories	检查当前可用 Memories
/hooks	审查和信任项目 Hooks
/theme	选择或预览终端主题
/keymap、/vim	调整快捷键和 Vim 模式

终端补全示例：

codex completion zsh

自定义主题可以放在 $CODEX_HOME/themes 下的 .tmTheme 文件中。Ctrl+G 可用 $VISUAL 或 $EDITOR 打开外部编辑器编辑长提示词。

IDE 扩展常用设置

这些是 IDE 设置，不是 config.toml 属性：

设置	默认值	作用
chatgpt.commentCodeLensEnabled	true	在代码注释附近显示可执行入口
chatgpt.openOnStartup	false	IDE 启动时自动打开 Codex
chatgpt.followUpQueueMode	queue	后续消息排队；也可改成 steer 立即引导当前任务
chatgpt.composerEnterBehavior	enter	控制 Enter 的发送行为
chatgpt.reviewDelivery	inline	控制审查结果显示在行内还是独立任务
chatgpt.localeOverride	Auto	覆盖界面语言
chatgpt.runCodexInWindowsSubsystemForLinux	false	Windows 上改为在 WSL 中运行 Codex
chatgpt.chat.fontSize	未固定	调整聊天文字大小
chatgpt.chat.editor.fontSize	未固定	调整输入编辑器字号

chatgpt.cliExecutable 主要用于 Codex CLI 开发调试，普通用户不应修改。

11. 一个完整落地例子：从本地自查到 PR 自动审查

假设目标是：开发者提交前先自查，PR 创建后再自动做一次只读安全审查。

本地开发
   ↓
npm test / npm run lint
   ↓
/review 检查未提交改动
   ↓
开发者修复并提交
   ↓
创建 Pull Request
   ↓
GitHub Action 以 read-only 沙箱运行 Codex
   ↓
生成结构化审查结果
   ↓
人工判断是否合并

实施顺序：

1. 在 AGENTS.md 写明测试命令和 ## Code Review Rules。
2. 本地用 /review 验证规则是否清楚，修正含糊描述。
3. 把固定提示词放进 .github/codex/review.md。
4. 添加只读的 GitHub Action，并禁用持久化 checkout 凭证。
5. 先只保存审查产物，不自动改代码、不自动合并。
6. 观察误报和漏报后再决定是否允许 Action 写入分支或发布评论。
7. 固定 Codex CLI 版本，升级时在测试 PR 中验证输出和权限。

这个流程的关键不是“让 AI 自动合并”，而是把重复检查自动化，同时保留明确的权限边界和最终人工判断。

12. 开发者上线前检查表

• 已根据目标正确选择 exec、SDK、App Server、MCP Server 或 GitHub Action。
• 自动化任务使用能完成工作的最小沙箱和最小 GitHub 权限。
• 版本、模型、提示词和输出 Schema 已固定或纳入变更管理。
• 仓库代码、PR 内容、Issue 和外部网页都按不受信任输入处理。
• Secret 没有写入仓库、日志、提示词或长生命周期的 Job 环境。
• Hook 已审查、已测试允许与拒绝路径，且不是唯一安全边界。
• 云端 setup 与 Agent 阶段的变量、联网和秘密生命周期已验证。
• App Server 的客户端能处理审批、错误、断线、恢复和协议升级。
• 多轮任务保存了 threadId，并明确何时创建新线程。
• 自动修改、发布评论、推送分支和合并 PR 都有独立授权。
• 最终仍运行项目自己的测试、lint、类型检查和安全扫描。

常见场景速查

需求	推荐配置
每次修改 JS 后必须跑测试	AGENTS.md + CI
记住个人偏好和近期工作背景	Memories
每次发版都执行同一套检查	Skill
工作流需要读取 GitHub/Figma/Linear	MCP 或包含连接器的 Plugin
安全、测试、性能同时审查	Subagents
团队共享“发版流程 + GitHub 工具”	Skill + MCP，打包成 Plugin
某子目录必须使用不同测试命令	嵌套 AGENTS.override.md
临时停用一个 Skill/MCP Server	skills.config[].enabled = false / MCP 的 enabled = false

安全与维护清单

• 必须遵守的规则已经写入 AGENTS.md，而非只存在于 Memories。
• AGENTS.md 保持精简，规则离适用目录尽量近。
• 测试、lint、类型检查、hooks 能自动执行关键规则。
• Skill 的 description 写清“何时使用”和边界。
• Skill 脚本只用于需要确定性的步骤，并能独立验证。
• MCP Token 使用环境变量，不直接写入仓库 TOML。
• MCP 使用最小工具白名单和合适的审批模式。
• 外部上下文不应进入记忆时，开启 disable_on_external_context。
• 共享 CODEX_HOME 前检查 Memories、认证与会话状态。
• 子代理并发数受控，写入范围互不重叠。
• 配置修改后已重启 Codex，并实际验证加载结果。

常见问题

AGENTS.md 和 Skill 有什么区别？

AGENTS.md 是进入项目就应遵守的持续规则；Skill 是完成某类任务时才加载的完整工作流。

Skill 和 Plugin 有什么区别？

Skill 是工作流的创作格式，适合本地或仓库内迭代；Plugin 是安装和分发单位，可同时携带多个 Skills、MCP 连接及资源。

Skill 和 MCP 为什么经常一起用？

Skill 告诉 Codex“按什么步骤完成任务”，MCP 提供“访问哪个外部系统、能调用哪些动作”。

Memories 能替代 AGENTS.md 吗？

不能。Memories 是有帮助的回忆层，生成和使用都可能受设置、空闲时间、额度及会话条件影响；强制规则必须放在 AGENTS.md 或工程检查中。

为什么修改配置后没有生效？

先确认编辑的是当前 CODEX_HOME 下的配置，再重启 Codex 或新开 TUI 会话。项目级 .codex/config.toml 只在项目被信任后加载。

子代理是不是越多越快？

不是。只有能独立并行的任务才容易提速；依赖关系强或同时写相同文件时，协调和冲突成本可能更高，而且会消耗更多 Token。

文档和属性会随 Codex 更新。复制配置前，请以当前客户端和官方文档中的实际版本为准。