ECC
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
- 309k
- JavaScript
- MIT
- 3 d ago
1,面向 Codex 新手与开发者:从基础配置、权限与沙箱,到 AGENTS.md、Skills、MCP、Hooks、SDK、App Server 和 CI/CD,提供属性说明、操作流程与完整示例。2,专业术语手册,2026 实用版|面向 AI 技术交流、Agent 工程、AI 编程与项目评审
Repo funsanity/learn_codex, read from GitHub 16 min ago. funsanity has not joined Take My Repo.
funsanity/learn_codex is a public repo on GitHub by funsanity. 1,面向 Codex 新手与开发者:从基础配置、权限与沙箱,到 AGENTS.md、Skills、MCP、Hooks、SDK、App Server 和 CI/CD,提供属性说明、操作流程与完整示例。2,专业术语手册,2026 实用版|面向 AI 技术交流、Agent 工程、AI 编程与项目评审. It declares no license on GitHub. Public does not mean open source: without a license, nobody is granted the right to reuse it. It has 0 stars and last changed on 2026-10-23. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
面向 Codex 新手与开发者:从基础配置、权限与沙箱,到
AGENTS.md、Skills、MCP、Hooks、SDK、App Server 和 CI/CD,提供属性说明、操作流程与完整示例。内容依据 OpenAI 官方 Configuration 与 Developers 文档整理。最后核对:2026-08。
config.toml 属性”和“高级配置分组索引”。AGENTS.md、Memories 和 Skills。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
完成后你应该看到这些效果:
AGENTS.md 自动生效。如果结果与上述不一致,先跳到文末“常见问题”,不要继续堆更多配置。
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>。尖括号内容通常只是说明,不是可以原样运行的值。
~/.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'
创建 ~/.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"
验证流程:
codex status 核对工作区和权限。/permissions、/personality、/mcp 等当前状态。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 相关审批是否启用 |
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false
实际行为:
测试方法:让 Codex“在当前项目创建 hello.txt”,应该可以在工作区内完成;再让它“下载一个在线文件”,应该遇到网络限制或请求额外权限。
approval_policy = "on-request"
sandbox_mode = "read-only"
实际行为:
测试方法:要求 Codex“分析当前项目但不要修改”,随后检查文件状态应无变化。
approval_policy = "never"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false
实际行为:
danger-full-access。测试方法:使用 codex exec 跑一个只需要当前工作区的任务,并确认失败时能从退出状态和输出中定位权限问题。
danger-full-access 会显著放宽隔离边界。它可能是某些受控环境的合理选择,但新手容易把“少弹窗”误认为“配置成功”。正确顺序是:先用 workspace-write 找出任务真正需要的目录和网络,再只开放必要能力。
| 属性 | 类型/默认 | 目的 |
|---|---|---|
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.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_environment_policy] 控制 Codex 启动的命令能看到哪些环境变量:
| 属性 | 目的 |
|---|---|
inherit |
控制继承范围 |
ignore_default_excludes |
是否忽略默认秘密名称过滤;想过滤 KEY/SECRET/TOKEN 时设为 false |
filters |
按变量名逐项 include/exclude |
exclude |
旧式排除列表 |
include_only |
旧式仅允许列表 |
set |
给子命令固定设置变量 |
experimental_use_profile |
实验性:是否加载 shell profile |
密钥优先通过进程环境注入,并尽量只在需要的命令范围内存在。
写在 [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 默认使用务实风格,只能写当前工作区,并在需要额外权限时询问。
最简单的方法:
~/.codex/config.toml;%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 下的文件,并重启会话;read-only,或项目目录不在当前工作区;network_access 改为 true。目标:无论谁使用 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 查询开发文档,并确认连接是否成功。
这个官方示例依赖本机已经安装 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 管理命令
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"
/mcp,应看到 context7。请使用 context7 查询我当前使用的框架中,如何配置一个最小测试,并说明你调用了哪个 MCP 工具。
常见失败:
[mcp_servers.context7],然后重启;npx:先安装 Node.js/npm,并确认终端执行 npx --version 有输出;npx 在 PATH 中,必要时增大 startup_timeout_sec;tool_timeout_sec,同时检查 Server 自身日志;codex mcp login <server-name>;bearer_token_env_var 指向环境变量,不要把秘密直接写进 TOML。目标:把“修改 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"
预期结果:三个线程可以独立工作,主代理等待后统一汇总。若结果重复,下一次提示中把三个职责边界写得更窄;若消耗过高,减少并发数或只委派最嘈杂的探索任务。
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。官方建议按以下顺序逐层建设:
1. AGENTS.md
写清仓库约定,并用测试、lint、hooks 强制关键规则
│
▼
2. Plugin / Skill
有现成插件先安装;没有再创建自己的可复用流程
│
▼
3. MCP
工作流需要外部系统时,再接入工具与数据
│
▼
4. Subagents
流程成熟后,把独立、嘈杂或专业工作并行委派
不要一开始就把所有能力都打开。先让最小配置跑通,再逐层增加。
AGENTS.md:持久项目指令AGENTS.md 是 Codex 开始工作前读取的持久指令。适合写:
保持短小。发生重复错误、反复读取无关文件或多次出现相同 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
│
▼
越靠近当前目录的内容越晚合并,因此优先级越高
每个目录最多加载一个文件,检查顺序为:
AGENTS.override.mdAGENTS.mdproject_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
- 优先报告会导致错误行为、安全风险或测试缺失的问题。
- 每条问题必须给出文件位置和可验证依据。
AGENTS.md,先只写最重要的命令与约束。AGENTS.md 或 AGENTS.override.md。codex --ask-for-approval never "总结当前加载的指令"
codex --cd services/payments --ask-for-approval never "列出当前生效的指令来源"
复杂项目应通过目录级 AGENTS.md 控制规则的继承和覆盖范围。
Memories 让 Codex 从符合条件的历史对话中提取有用上下文,并在未来会话中使用。它适合“有帮助但不要求绝对可靠”的背景,不适合承载必须执行的团队规则。
~/.codex/memories/。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 的生成和可用范围可能随客户端版本及账户设置变化。
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 被选中后要执行的完整步骤 | 使用祈使句,明确输入、输出和验证 |
| 范围 | 路径 | 适用场景 |
|---|---|---|
| 当前目录/仓库 | $CWD/.agents/skills 及从当前目录到仓库根的各级 .agents/skills |
模块或仓库专用流程 |
| 用户 | $HOME/.agents/skills |
个人跨仓库流程 |
| 管理员 | /etc/codex/skills |
共享机器或容器的统一能力 |
| 系统 | Codex 内置 | OpenAI 随产品提供的通用能力 |
同名 Skill 不会自动合并,可能同时出现在选择器中。Codex 支持指向 Skill 目录的符号链接。
$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 也可以在 ~/.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 是否被识别。
$skill-creator,或手工创建 Skill 目录和 SKILL.md。description。Plugin 不是另一种工作流语言。Skill 仍是工作流的创作格式,而 Plugin 是可安装、可分享的分发单元,可以同时打包:
安装流程:
判断原则:本地编写和仓库专用工作流用 Skill;跨项目分发、组合多个 Skills 或捆绑连接器时用 Plugin。
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 配置。
每个 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 支持。
| 属性 | 必需 | 目的 |
|---|---|---|
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" }
| 属性 | 默认值 | 目的 |
|---|---|---|
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>
桌面端:
Settings > MCP servers > Add server。/mcp 检查连接。IDE 扩展流程相同,保存后选择 Restart extension。ChatGPT Web 不读取本地 config.toml,需通过 Plugin 使用远程 MCP 工具。
具体字段是否可用取决于当前 Codex 与 MCP Server 的协议版本。
子代理把探索日志、测试输出、堆栈信息等噪声留在独立线程,只把结论汇总回主线程。适合:
代价是每个子代理都会独立消耗模型与工具资源,因此通常比单代理使用更多 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 文件可以进一步覆盖;权限模式应在委派前确认。
位置:
~/.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 相同,自定义版本优先。
sandbox_mode = "read-only"。一句话理解: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)
| 角色 | 主要职责 | 典型交付物 |
|---|---|---|
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 的枚举定义。暂停等待不等于失败,完成任务不等于线程已关闭;读取上下文、执行、等待、失败处理和资源清理需要分别考虑。
示例请求(职责分工,不是可执行 API):
请使用子代理协作,主代理保留最终交付责任。
先由主代理检查依赖并确定接口和验收标准。
将两个互不依赖的模块分给 Worker A/B,分别限定写入目录。
主代理同时做不重叠的集成准备,不重复子代理的工作。
收齐结果后检查并集成补丁,再让 Verifier 验证最终产物。
失败最多返工两轮;仍失败则报告证据与阻塞,不宣称成功。
最后汇总改动、验证结果和剩余风险,关闭不再使用的线程。
截至 2026-09-08 核对的官方说明:本地 Codex 在用户明确要求,或适用的 AGENTS.md / Skill 指令要求委派时使用子代理;具体工具名称和可用性以当前客户端暴露的接口为准,不要把上面的概念词直接当作 CLI 命令。
参考:
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"],
)
操作流程:
rules/ 与 .rules 文件。pattern、决策和正反样例。codex execpolicy check --pretty \
--rules ~/.codex/rules/default.rules \
-- gh pr view 123
Rules 应与沙箱、审批和工程检查共同使用。
Fast mode 是同一受支持模型的加速服务层,不是另一个模型;速度更快,但会消耗更多 Credits。Codex-Spark 则是单独的快速模型选择,两者不要混淆。
service_tier = "fast"
[features]
fast_mode = true
会话内操作:
/fast on
/fast off
/fast status
具体支持模型、倍率、资格与价格容易变化,请始终查看 Speed 和 Pricing 当前说明。
Record & Replay 当前用于 macOS,且需要 Computer Use 可用并启用。适合“流程固定、偏好明确、演示比文字描述容易”的操作。
你演示一次完整流程
│
▼
Codex 观察必要的窗口与动作
│
▼
生成 Skill:触发条件 + 输入 + 步骤 + 验证
│
▼
新会话提供本次变量,复用该 Skill
操作流程:
录制时避免秘密和敏感数据。需要跨团队稳定分发、捆绑多个 Skills 或连接器时,再打包为 Plugin。
Linux 桌面端有独立的安装与更新流程;config.toml、Skills、MCP 和 Agent 的核心概念与其他本地 Codex Host 一致。
[windows]
sandbox = "elevated" # 官方推荐;可用管理员权限时
# sandbox = "unelevated" # 无管理员权限或 elevated 初始化失败时回退
原生 Windows 运行时应先尝试 elevated;无法使用管理员权限或初始化失败时,再回退到 unelevated。
WSL2 中 Codex 运行在 Linux 环境,使用 Linux 沙箱而不是 Windows 原生沙箱。适合依赖 Linux 工具链或代码本来就位于 WSL 的项目。WSL1 从 Codex 0.115 起不再受支持。
wsl --install
wsl
进入 WSL 并完成 Codex 安装后,可验证命令是否可用:
codex --version
仓库尽量放在 ~/code/...,避免 /mnt/c/... 的 I/O、符号链接和权限问题。
单独使用已经有价值,组合后更适合真实团队流程:
用户:"审查这个 PR,并核对 Linear 需求与 Figma 设计"
│
▼
AGENTS.md:项目规范、测试命令、评审标准
│
▼
Skill:定义 PR 审查的固定步骤和输出格式
│
┌─────────┴─────────┐
▼ ▼
MCP:Linear / Figma Subagents:并行分工
获取外部需求和设计 ├─ 代码风险
├─ 测试缺口
└─ 文档/API 核对
└─────────┬─────────┘
▼
主代理汇总最终报告
如果 Skill 依赖 MCP,应在 agents/openai.yaml 的 dependencies.tools 中声明依赖。这样 Skill 负责流程,MCP 负责能力边界,子代理负责并行执行。
本篇介绍如何把 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。
/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 请求云端审查。
桌面端每个聊天都有一个与当前项目或 worktree 对应的终端。点击右上角终端按钮,或按 `Ctrl+`` 打开。Codex 可以读取当前终端输出,因此你可以先运行命令,再让它解释失败原因。
git status
npm test
npm run lint
推荐流程:
在终端运行测试
│
├─ 成功 ──> 让 Codex 总结改动并准备提交说明
│
└─ 失败 ──> 把当前终端输出交给 Codex 分析
│
└─ 修复后重新运行同一命令
常用测试、启动、格式化命令还可以做成 Local Environment 的 Actions,在集成终端中一键运行。
| 环境 | 代码在哪里运行 | 是否隔离当前工作区 | 适合场景 |
|---|---|---|---|
| Local | 当前机器、当前项目目录 | 否 | 需要本机工具、立即查看修改 |
| Worktree | 当前机器的独立 Git worktree | 是 | 并行任务、避免打乱当前分支 |
| Cloud | OpenAI 配置的远程容器 | 是 | 后台运行、团队协作、GitHub/Slack/Linear 派活 |
Local Environment 是桌面端的本地项目配置。它可以声明新 worktree 创建后需要自动执行的 setup script,也可以提供常用 Actions。配置会生成在项目的 .codex 目录中;不含秘密时,可以提交到 Git,让团队共用。
适合放进 setup script 的内容:
npm ci
npm run db:generate
不要把 API Key 直接写在脚本里;使用环境变量或团队的秘密管理方式。
在桌面端新建任务时选择 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,但复制秘密文件会扩大泄露面,应只列最少文件。
云端任务的大致流程:
创建远程容器
↓
检出指定分支或提交
↓
运行 setup script(缓存恢复时可运行 maintenance script)
↓
Codex 修改代码并运行检查
↓
返回 diff,等待人工审查或创建 PR
几个容易踩坑的点:
export 不会自动保留;长期变量应通过环境设置或 shell 启动文件配置。三种环境的权限、联网和生命周期不同,创建任务前应先确认运行位置。
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": "命令触及生产数据库,请改用只读环境"
}
}
操作流程:
matcher,不要一开始匹配所有工具。/hooks 检查并信任脚本的精确版本。多个来源中匹配的 Hooks 都会运行;同一事件的匹配项可能并发执行。PreToolUse 能阻止或改写本地工具调用,但不应被当作唯一安全边界;PostToolUse 发生在副作用之后,不能撤销已经执行的操作。
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 的全局环境变量。
SDK 适合服务端程序、内部工具和 CI 平台。它提供 thread,使应用可以继续同一次对话,而不是每次从零开始。
要求 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 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 指定的沙箱会应用到该次及后续轮次。
App Server 面向需要完整客户端体验的开发者,它提供认证、历史会话、审批、流式事件等底层能力。如果只是后台自动化或 CI,优先使用 SDK,不必承担协议和界面状态管理成本。
通信方式:
stdio 传输一行一个 JSON 消息。协议生命周期:
客户端连接
↓
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 必须显式声明能力;没有明确需求时只使用稳定接口。
这里的方向很重要:普通 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 通常更简单。
官方 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。
完成 Codex cloud、GitHub 仓库和 Code review 设置后,可在 PR 中使用:
@codex review
@codex security review
@codex fix the P1 issue
还可以开启自动审查。项目专属标准继续放在 AGENTS.md 的 ## Code Review Rules 中。
先配置 Codex cloud、连接 GitHub 与环境,再安装 Slack 应用并邀请 @Codex。在频道或线程中提及它并描述任务,Codex 会创建云端任务;必要时在消息里明确仓库和环境,避免自动匹配错误。
@Codex 请在 acme/api 仓库中定位这个报错,补回归测试并准备一个 PR。
云端任务完成后仍应由人审查 diff 和测试结果。
付费计划可连接云端 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"
| 命令 | 什么时候用 |
|---|---|
/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 设置,不是 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 开发调试,普通用户不应修改。
假设目标是:开发者提交前先自查,PR 创建后再自动做一次只读安全审查。
本地开发
↓
npm test / npm run lint
↓
/review 检查未提交改动
↓
开发者修复并提交
↓
创建 Pull Request
↓
GitHub Action 以 read-only 沙箱运行 Codex
↓
生成结构化审查结果
↓
人工判断是否合并
实施顺序:
AGENTS.md 写明测试命令和 ## Code Review Rules。/review 验证规则是否清楚,修正含糊描述。.github/codex/review.md。这个流程的关键不是“让 AI 自动合并”,而是把重复检查自动化,同时保留明确的权限边界和最终人工判断。
exec、SDK、App Server、MCP Server 或 GitHub Action。threadId,并明确何时创建新线程。| 需求 | 推荐配置 |
|---|---|
| 每次修改 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 保持精简,规则离适用目录尽量近。description 写清“何时使用”和边界。disable_on_external_context。CODEX_HOME 前检查 Memories、认证与会话状态。AGENTS.md 和 Skill 有什么区别?AGENTS.md 是进入项目就应遵守的持续规则;Skill 是完成某类任务时才加载的完整工作流。
Skill 是工作流的创作格式,适合本地或仓库内迭代;Plugin 是安装和分发单位,可同时携带多个 Skills、MCP 连接及资源。
Skill 告诉 Codex“按什么步骤完成任务”,MCP 提供“访问哪个外部系统、能调用哪些动作”。
AGENTS.md 吗?不能。Memories 是有帮助的回忆层,生成和使用都可能受设置、空闲时间、额度及会话条件影响;强制规则必须放在 AGENTS.md 或工程检查中。
先确认编辑的是当前 CODEX_HOME 下的配置,再重启 Codex 或新开 TUI 会话。项目级 .codex/config.toml 只在项目被信任后加载。
不是。只有能独立并行的任务才容易提速;依赖关系强或同时写相同文件时,协调和冲突成本可能更高,而且会消耗更多 Token。
文档和属性会随 Codex 更新。复制配置前,请以当前客户端和官方文档中的实际版本为准。
funsanity/learn_codex is a public repo on GitHub by funsanity. 1,面向 Codex 新手与开发者:从基础配置、权限与沙箱,到 AGENTS.md、Skills、MCP、Hooks、SDK、App Server 和 CI/CD,提供属性说明、操作流程与完整示例。2,专业术语手册,2026 实用版|面向 AI 技术交流、Agent 工程、AI 编程与项目评审.
It declares no license on GitHub. Public does not mean open source: without a license, nobody is granted the right to reuse it.
Its maker has not tagged a system, so it is unknown here. Its README says what it needs.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-10-23. Take My Repo does not judge from that whether it is maintained.

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
Reverse engineer anything with agents, from app behavior down to native binaries.
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
Knowledge infrastructure to make your agents smarter. Search, scrape and access 550+ data providers through one API.

把一张 2D 立绘自动拆成部件、生成骨骼层级与网格权重,一键导出 Cocos Creator / Unity (spine-unity) / LayaAir/Phaser/Spine 编辑器各版本可直接使用的 Spine 资源。

Harness 认证、Cocos CLI 项目实践测试和 Codex 开发流程验证的最小 Cocos Creator 3.8.8 + TypeScript 工程。它同时用来验证 Cocos MCP、文档级 RAG 检索链路、Agent 分层协作和大型游戏开发模型,但客户端运行时仍保持最小可启动范围