企业官网建设流程全解析

Codex 详细使用指南

本文是关于codex的一些基本用法的入门文档。

本文会覆盖：

• Codex 的基本用法
• AGENTS.md，也就是常说的 agent 指令文件
• Skill 技能
• 自动化 Automations
• MCP、插件、子代理
• 与 Claude / Claude Code 的联动方式
• 用 CC Switch 管理多个工具的配置
• 推荐工作流和安全注意事项

1. Codex 是什么

Codex 是 OpenAI 面向软件开发的编码代理。它可以在你的项目上下文中读文件、修改文件、运行命令、解释代码、修 bug、写测试、做代码审查，也可以通过 MCP、插件、技能和自动化连接更多工具。

你可以把它理解成一个会进仓库干活的工程助手，而不是只会回答问题的聊天窗口。这个区别其实挺大的：普通聊天模型会告诉你“你可以这样改”，而 Codex 更常见的做法是“我已经改了这几个文件，跑了这些检查，还有两个风险想请你确认一下”。

Codex 常见使用界面包括：

2. 第一次打开 Codex

2.1 登录或输入 API key

第一次打开 Codex 时，你会看到登录入口。通常有两种方式：

• 用 ChatGPT 账号继续，适合大多数桌面应用和日常开发场景
• 输入 API key，适合你想用 API credits 或某些更偏工程化的环境

个人日常用可以先拿 ChatGPT 登录。等需要团队环境、自动化、CI 或者隔离配置的时候，再回头认真整理 API key、CODEX_HOME、项目配置和权限策略。

2.2 选择项目文件夹

Codex的使用一定要选对项目目录。你应该尽量从仓库根目录打开项目，因为那里通常有：

• package.json、pyproject.toml、Cargo.toml等项目入口
• .git
• README
• 测试配置
• AGENTS.md
• .codex/config.toml

如果你从很深的子目录打开，Codex 可能看不到项目全貌；如果你从太大的父目录打开，它又可能读到一堆无关文件。仓库根目录通常是最舒服的位置。

2.3 直接给它一个具体任务

选好项目后就可以直接说要它干什么。prompt不要只丢一句“帮我优化一下”或者“修个 bug”。倒不是不能这么说，但 Codex 只能靠猜，猜歪了返工更费劲。

更好的写法是：

帮我修复设置页保存失败的问题。 复现步骤： 1. npm run dev 2. 打开 /settings 3. 修改 Enable alerts 4. 点击 Save 5. 刷新后状态丢失 约束： - 不要改 API 结构 - 尽量小改 - 如果可行，补一个回归测试 完成前请运行相关测试，并说明你验证了什么。

不需要把提示词写得像合同那么严谨，但得给它足够的提示。目标、上下文、限制、验收标准，这四样都交代清楚，Codex 的发挥就会稳定很多。

3. 基本工作方式

Codex 的一次工作通常是一个 thread，也就是线程或会话。你给出目标，Codex 读取上下文、制定方案、调用工具、编辑文件、运行命令，直到任务完成或你中断它。

如上文所说，一个好的 Codex 提示词通常包含四个部分：

目标：你希望 Codex 改什么、做什么、查什么。 上下文：相关文件、目录、错误日志、截图、复现步骤、设计稿。 约束：不要改哪些接口、遵守哪些风格、是否需要兼容旧逻辑。 完成标准：测试通过、页面可用、bug 不再复现、输出某个文件。

4. 常用任务模式

4.1 解释代码

适合新接手项目、看不懂模块关系、需要梳理请求链路时使用。

阅读 @src/api/user.ts 和 @src/db/schema.ts，解释用户创建请求的完整流程。 请说明： - 每个模块的职责 - 数据在哪里校验 - 哪些地方有兼容性风险 - 如果我要新增字段，应该改哪些文件

4.2 修 bug

给 Codex 复现路径比只给一句“这里这里有问题”有效很多。如可以这样说：

这个 bug 可以这样复现： 1. ... 2. ... 请先复现，再定位原因，最后给出最小修复。 修完后运行最小相关测试，并说明验证结果。

4.3 写测试

如

为 @src/utils/parseDate.ts 的 parseDate 函数添加测试。 覆盖： - 正常 ISO 日期 - 空字符串 - 非法日期 - 时区边界 请参考现有测试风格，不要引入新测试框架。

4.4 做代码审查

如

请 review 当前未提交改动。 重点关注： - 是否有行为回归 - 是否缺少测试 - 是否有安全风险 - 是否破坏公共 API 请按严重程度排序，并给出文件和行号。

4.5 前端验证

对于前端项目，应让 Codex 启动开发服务器，用浏览器或截图验证页面。

实现这个交互后启动本地 dev server。 用浏览器打开页面，检查桌面和移动端布局，确认没有文字重叠或空白画布。 最后告诉我可访问的本地 URL。

5. Plan mode 和 Goal mode

5.1 Plan mode

复杂、模糊、风险高的任务，可以先让 Codex 计划再动手，避免造成不可挽回的错误。

适合：

• 大规模重构
• 架构调整
• 数据迁移
• 性能优化
• 多模块 bug
• 需求还不清楚的功能开发

可以这样说：

先不要改代码。请先阅读相关文件，列出实现计划、风险和需要确认的问题。

在支持的界面中，也可以用/plan或快捷键进入计划模式。

5.2 Goal mode

Goal mode 适合长任务。你给 Codex 一个持续目标，它会围绕“完成标准”推进，并在多步任务中持续检查是否达成。

示例：

/goal 将这个项目从 JavaScript 迁移到 TypeScript。 完成标准： - 所有源码文件迁移完成 - strict 模式下通过类型检查 - 不允许显式 any - 测试仍然通过

6.AGENTS.md：让 Codex 记住项目规则

codex不会同时记住不同对话的内容，但你需要它遵守一定的规则。这时你可以写一个AGENTS.md，相当于是给编码代理看的项目说明文件。它类似 README，但读者是 Codex 这类 agent。

它适合放长期稳定的规则，而不是一次性任务要求。

6.1 应该写什么

一个好的AGENTS.md通常包括：

• 项目结构
• 如何安装依赖
• 如何启动项目
• 如何运行测试、lint、typecheck
• 代码风格和架构约定
• PR 或 commit 规范
• 禁止事项
• 完成任务前必须验证什么

示例：

# AGENTS.md ## Project Overview This is a Next.js application using TypeScript, Tailwind CSS, and Vitest. ## Commands - Install: `pnpm install` - Dev server: `pnpm dev` - Test: `pnpm test` - Lint: `pnpm lint` - Type check: `pnpm typecheck` ## Engineering Rules - Prefer existing components in `src/components`. - Do not introduce new dependencies without asking. - Keep API response shapes backward compatible. - Add or update tests for behavior changes. ## Done Criteria Before finishing: - Run the smallest relevant test suite. - Run lint if frontend files changed. - Summarize changed files and verification results.

6.2 放在哪里

Codex 会按层级加载指令。越靠近当前工作目录的文件优先级越高。

常见位置：

示例结构：

repo/ AGENTS.md packages/ web/ AGENTS.md api/ AGENTS.md

如果 Codex 在packages/api/下工作，它会读取根目录规则，再读取packages/api/AGENTS.md，后者更具体。

6.3 什么时候更新AGENTS.md

当你发现 Codex 老是在同一个地方栽跟头，可以把对应规则放进AGENTS.md进行处理。

下面是一些适合更新的情况：

• 总是跑错测试命令
• 总是误改某个目录
• 总是忽略某类安全要求
• 总是没有遵守 commit 规范
• review 中反复出现相同反馈

你可以直接对 Codex 说：

请把这次纠正总结成一条简洁规则，更新到 AGENTS.md。

7. Skills：把重复工作做成技能

Skill 是 Codex 的可复用工作流。一个 skill 通常是一个目录，里面至少有SKILL.md，还可以包含脚本、参考文档、模板和资源文件。

Skill 适合比AGENTS.md更流程化、更任务化的内容。

7.1AGENTS.md和 Skill 的区别

7.2 Skill 的基本结构

.agents/ skills/ release-check/ SKILL.md scripts/ check-release.ps1 references/ release-template.md

SKILL.md示例：

--- name: release-check description: Run the project's release readiness checklist. Use when preparing a release or checking whether a branch is ready to ship. --- 1. Read `references/release-template.md`. 2. Check package version, changelog, tests, and migration notes. 3. Run the release validation script if available. 4. Return a concise release readiness report with blockers first.

7.3 如何调用 Skill

显式调用：

$release-check 检查当前分支是否可以发版。

隐式调用：

帮我检查这个分支是否具备发版条件。

如果 skill 的description写得足够清楚，Codex 可以自动判断该用它。

7.4 Skill 放在哪里

建议：

• 项目专属流程放.agents/skills
• 个人常用流程放$HOME/.agents/skills
• 要分发给团队时打包成 plugin

7.5 写 Skill 的建议

• 一个 skill 只做一类事
• description要写清楚什么时候触发、什么时候不触发
• 优先写步骤说明，只有需要确定性工具时才加脚本
• 引用资料放references/
• 自动化或外部工具依赖写清楚
• 如果依赖 MCP，在agents/openai.yaml中声明

8. Automations：让 Codex 定时或后台工作

Automations 是 Codex 应用中的自动化能力，可以让 Codex 在后台按计划运行任务，并把结果放到 Triage / inbox 中。

适合：

• 每天检查 CI 或 PR 状态
• 定时扫描项目中的 TODO 或 flaky test
• 轮询部署是否完成
• 定期检查依赖升级
• 定期生成代码健康报告
• 每隔几分钟回来继续某个长任务

8.1 两类常见自动化

8.2 Thread automation 示例

创建一个线程自动化：每 10 分钟检查一次这个部署是否完成。 如果部署成功，总结结果并停止提醒。 如果失败，说明失败原因。 如果还在进行中，只保留简短状态。

适合：

• 等待 CI
• 等待部署
• 追踪 PR review
• 跟进一个正在进行的排查

8.3 Standalone automation 示例

创建一个独立自动化：每个工作日上午 9 点检查这个项目的测试健康状况。 任务： - 查看最近一次测试结果 - 找出新出现的失败 - 如果没有问题，自动归档 - 如果有问题，放入 Triage 并给出修复建议

8.4 自动化和 Skill 组合

自动化适合“什么时候运行”，Skill 适合“怎么运行”。

示例：

每天早上 9 点运行 $release-check。 如果发现 blocker，把结果放到 Triage。 如果没有发现问题，自动归档。

8.5 自动化的安全边界

自动化是无人值守执行，所以权限要保守。

注意：

• read-only沙箱下，自动化不能改文件、访问网络或操作应用
• workspace-write可以改工作区文件，但不能随意访问工作区外部
• full access风险最高，不建议长期默认使用
• Git 仓库中优先使用 worktree 隔离自动化改动
• 高频自动化可能产生很多 worktree，要定期归档无用 run

9. MCP：连接外部工具

MCP，即 Model Context Protocol，是 Codex 连接外部工具和上下文的标准方式。

可以连接的对象包括：

• GitHub
• Linear
• Slack
• Notion
• Figma
• Sentry
• 浏览器
• 内部文档系统
• 数据库或日志系统
• OpenAI Docs
• Context7 等开发文档服务

9.1 MCP 能提供什么

MCP server 通常可以提供：

• Tools：让 Codex 执行动作
• Resources：让 Codex 读取资源
• Prompts：提供可复用提示模板

9.2 配置方式

一般通过~/.codex/config.toml或项目级.codex/config.toml配置。

示例：

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

HTTP MCP 示例：

[mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

CLI 中也可以使用：

codex mcpaddcontext7 -- npx-y@upstash/context7-mcp codex mcp--help

9.3 MCP 和 Skill 的关系

推荐组合方式是：

• Skill 定义流程
• MCP 提供外部能力
• Automation 定时触发

例如：

Skill：review-pr MCP：GitHub MCP Automation：每 30 分钟检查 PR 是否有新 review

10. Plugins：打包和分发能力

Plugin 是可安装的扩展包，通常可以包含：

• 一个或多个 skills
• MCP server 配置
• hooks
• 应用映射
• 图标、资源、展示信息
• marketplace 元数据

如果你只是给当前项目写一个流程，用 skill 就够了。

如果你想分发给团队、跨项目安装、绑定 MCP 或 UI 元数据，就适合做 plugin。

一个最简单的plugin 结构如下：

my-plugin/ .codex-plugin/ plugin.json skills/ hello/ SKILL.md

plugin.json示例：

{"name":"my-plugin","version":"1.0.0","description":"Reusable workflows for this team","skills":"./skills/"}

11. Subagents：并行代理

Subagents 是让 Codex 同时启动多个专门代理去处理不同子任务，可以提高任务效率。

适合：

• 大型代码审查
• 多方向排查
• 安全、测试、性能分别分析
• 大文档分块总结
• 并行探索多个模块

示例：

请使用 3 个 subagents 并行 review 当前分支： 1. 一个关注安全风险 2. 一个关注测试缺口 3. 一个关注可维护性 等待三个代理全部完成后，按严重程度汇总结果，附文件引用。

注意：

• 读多写少的任务更适合 subagents
• 多个代理同时改代码容易冲突
• subagents 会消耗更多 token 和时间
• 主线程应负责整合决策，不要让中间日志淹没上下文

12. Rules、Sandbox 和权限

Codex 可以运行命令，也可能修改文件。权限模型决定它能做什么。

常见沙箱模式：

常见审批策略：

Rules 可以控制哪些命令允许、提示或禁止。

示例思路：

允许 gh pr view 提示 npm install 禁止 rm -rf

建议：

• 默认使用workspace-write
• 对网络、安装依赖、写工作区外文件保持审批
• 不要让无人值守自动化长期使用 full access
• 对删除、reset、清理类命令保持人工确认

13. 与 Claude / Claude Code 联动

官方 Codex 手册没有把 Claude 作为 Codex 内置的一键集成来描述。因此实际联动通常走工程协作模式，而不是期待两个产品天然共享上下文。

常见可落地方式如下。

13.1 通过 Git 分工

这是最稳的方式。

推荐流程：

1. Claude 负责方案设计、需求澄清、文案或大方向分析
2. Codex 负责在仓库中落地修改、跑测试、修复失败
3. 双方通过 Git diff、commit、PR 描述交接

示例：

Claude 产出设计方案 DESIGN.md Codex 根据 DESIGN.md 实现代码，并运行测试 Claude 再阅读 diff 给出 review Codex 修复 review 反馈

13.2 通过 Markdown 交接上下文

创建一个共享交接文件，例如：

docs/agent-handoff.md

内容可以包括：

# Agent Handoff ## Goal ## Current State ## Decisions Made ## Files Touched ## Open Questions ## Verification ## Next Agent Should Do

用法：

请阅读 docs/agent-handoff.md，接着完成 Next Agent Should Do 中的任务。 完成后更新这个文件。

这种方式适合 Codex、Claude Code、Cursor、人工开发者之间协作。

13.3 通过 MCP 或外部系统共享

如果 Claude 和 Codex 都能访问同一个外部系统，可以把协作状态放在那里：

• GitHub issue / PR
• Linear ticket
• Notion 文档
• Slack thread
• Google Docs
• 内部任务系统

Codex 侧通常通过 MCP、插件或连接器读取这些系统。

Claude 侧如果也有对应连接能力，就可以围绕同一个任务源协作。

推荐结构：

Linear issue：需求和验收标准 GitHub PR：代码 diff 和 review Notion/Docs：设计说明 Codex：实现、测试、修复 Claude：需求推敲、方案比较、二次审查

13.4 Claude Code 与 Codex CLI 分工

如果本机同时使用 Claude Code 和 Codex CLI，建议避免两个 agent 同时改同一批文件。

推荐模式：

Claude Code: - 生成设计方案 - 找风险点 - 做第二视角 review Codex: - 实际编辑文件 - 运行命令 - 启动浏览器验证 - 整理最终 diff

如果确实要同时工作：

• 使用不同 Git 分支
• 或使用不同 worktree
• 或明确文件边界
• 每次交接前先提交或保存 diff

13.5 通过命令行桥接

如果某个 Claude 工具提供 CLI，你可以让 Codex 在受控情况下调用它。但要注意：

• 这可能涉及外部网络和 API key
• Codex 不应读取或暴露密钥
• 输出应保存为文件或摘要
• 需要人工批准安装、登录和高权限命令

建议把桥接做成脚本或 skill，而不是每次临时拼命令。

示例 skill 思路：

--- name: claude-review-handoff description: Prepare a review handoff package for Claude or consume Claude review notes and apply fixes. --- 1. Generate a concise diff summary. 2. Write `docs/claude-review-request.md`. 3. If `docs/claude-review-notes.md` exists, read it and classify feedback. 4. Apply only concrete, testable fixes. 5. Run relevant verification commands.

13.6 不建议的联动方式

• 两个 agent 同时在同一目录随意改代码
• 把 API key、cookie、token 写入交接文件
• 让一个 agent 无限制执行另一个 agent 生成的 shell 命令
• 没有 diff / commit / handoff 文档就来回切换
• 让双方都“自动修复全部问题”，最后难以追踪责任边界

14. 用 CC Switch 管理多个工具的配置

如果你只用 Codex，这一节可以跳过。但只要你同时装了 Codex、Claude Code、Gemini CLI 里的两个以上，迟早会碰到一件烦人的事：想换个 API 供应商（比如从官方 API 换成中转、DeepSeek、阿里百炼），得挨个去改配置文件。而且每个工具的格式还不一样——Claude 用 JSON，Codex 用 TOML 加 auth.json，Gemini 又是另一套。改错一个字符，整个工具就起不来了。

CC Switch 就是专门解决这个的。它是个跨平台桌面小工具，把各个 CLI 的供应商配置集中管起来，切换的时候一键写入对应的配置文件，不用你手动碰那些 JSON 和 TOML。仓库在github.com/farion1231/cc-switch，官网是 ccswitch.io。

14.1 它到底帮你做了什么

说白了就三件事：把配置存在一个地方、切换时帮你写对文件、写的时候不会写坏。

第三点比听起来重要。CC Switch 用 SQLite 存所有供应商信息，每次写配置文件都走"先写临时文件再改名"的原子操作，所以哪怕切换到一半出问题，你原来的配置也不会被写成半截的坏文件。这对经常手滑改坏config.toml的人来说是真的省心。

现在它支持的工具比一开始多了不少，除了 Claude Code、Codex、Gemini CLI，还覆盖了 Claude Desktop、OpenCode 等好几个，每个都带自己的一套供应商预设。

14.2 装起来

macOS 用 Homebrew 最省事：

brew tap farion1231/ccswitch brewinstall--caskcc-switch

Windows 下载.msi装就行，Linux 有.deb/.rpm/.AppImage，Arch 用户可以paru -S cc-switch-bin。

第一次打开时，它会自己扫一遍你机器上装了哪些 CLI，把现有配置尽量导入进来，然后在系统托盘挂一个图标。

14.3 日常用法

主界面顶上是一排工具图标，点哪个就是在管哪个工具的配置。加供应商点右上角的+，可以从内置预设里选（官方 Anthropic、DeepSeek、阿里百炼这些都有），也可以自己手填。填好之后在列表里点一下想用的那个，再点「启用」，它就把配置写进对应工具的实际配置文件了。

具体写到哪：Claude 是settings.json，Codex 是auth.json加config.toml。

如果你切换很频繁，不用每次都开主界面——直接从系统托盘的菜单里点就能换。

14.4 生效时间

这个不同工具不一样，得记一下：

所以你在 CC Switch 里点了「启用」，Codex 却还在用旧供应商，多半不是没切成功，而是终端没重开。

14.5 几个顺手的功能

真正装了之后，你可能会用到这几个：

• MCP 统一管理：在 CC Switch 里加一个 MCP Server，能一键同步到 Claude Code、Codex、Gemini CLI 等，不用在每个工具里各配一遍。
• 自动故障转移：内置一个本地代理，配了多个供应商的话，一个挂了会自动切到下一个，带断路器逻辑。跑长任务不容易被单个供应商拖死。
• 自动备份：数据库在~/.cc-switch/cc-switch.db，会自动留最近 10 个版本，配置切乱了还能回退。

14.6 和前面那套联动怎么搭

CC Switch 管的是"配置层"，前面第 13 章讲的 Git 分支、handoff 文档管的是"协作层"，两者不冲突，配一块用挺舒服：Codex 和 Claude Code 各自的供应商、API key 交给 CC Switch 统一切换，具体谁改哪些文件、怎么交接还是走分支和 handoff。这样你既不用记一堆配置文件路径，也不会让两个 agent 在同一批文件上打架。

一个小提醒：官方 README 里说过这工具还要大改一轮，所以你装的版本界面可能和网上的截图对不上，以自己装的实际版本为准就行。

15. 推荐个人工作流

15.1 新项目初始化

1. 让 Codex 阅读项目结构
2. 生成或更新AGENTS.md
3. 明确测试、lint、构建命令
4. 配置常用 MCP
5. 把重复流程做成 skill
6. 对稳定流程设置 automation

提示词：

请阅读当前项目，生成一个简洁实用的 AGENTS.md。 重点包括： - 项目结构 - 安装、启动、测试、lint、构建命令 - 代码风格 - 完成任务前的验证要求 不要写空泛规则。

15.2 日常开发

实现 X 功能。 参考 @docs/spec.md。 约束： - 不要改数据库 schema - 保持现有 API 兼容 - 修改后运行相关测试

15.3 提交前

请 review 当前 diff。 如果发现问题，先列出来，不要直接改。 重点看 bug、测试缺口、边界条件和不必要的复杂度。

15.4 PR 后

读取 PR review 反馈，按优先级分类。 先处理 P0/P1 问题。 每修一类问题后运行相关测试。

15.5 长期维护

可以设置自动化：

• 每天检查失败测试
• 每周检查依赖更新
• 每周总结技术债
• 每次 PR 自动做 focused review
• 定期检查AGENTS.md是否需要更新

16. 常见问题

16.1 Codex 没有按项目规则做

检查：

• AGENTS.md是否在正确目录
• 当前工作目录是否正确
• 是否有更近的AGENTS.override.md
• 文件是否过长导致部分指令未加载
• 规则是否过于抽象

建议让 Codex 自查：

请列出你当前加载到了哪些项目指令文件，并总结其中和本任务相关的规则。

16.2 Skill 没触发

检查：

• skill 是否在.agents/skills或$HOME/.agents/skills
• SKILL.md是否有 frontmatter
• name是否唯一且好记
• description是否写清楚触发条件
• 是否需要重启 Codex

可以显式调用：

$skill-name 执行这个任务

16.3 自动化没跑

检查：

• Codex app 是否在运行
• 项目路径是否还存在
• 沙箱权限是否允许该任务
• 是否被组织策略限制
• 是否使用了 worktree，结果是否在 automation run 中
• prompt 是否能在普通线程中先跑通

16.4 Codex 和 Claude 如何避免互相覆盖

最佳实践：

• 使用 Git 分支或 worktree 隔离
• 明确每个 agent 负责的文件范围
• 用 handoff 文档交接
• 每轮交接前查看 diff
• 一个 agent 实现，另一个 agent review

19. 总结

• 给 Codex 明确目标、上下文、约束和完成标准
• 对复杂任务先 plan，再 implement
• 把长期规则写进AGENTS.md
• 把重复流程做成 skill
• 用 MCP 连接外部系统
• 用 automation 处理稳定的周期性任务
• 用 worktree 隔离后台任务或并行任务
• 用 subagents 做并行分析，谨慎并行写代码
• 与 Claude 联动时，通过 Git、handoff 文档、PR 和外部任务系统交接
• 不要让多个 agent 无边界地同时修改同一批文件
• 始终要求验证：测试、lint、typecheck、浏览器检查或人工可审查 diff

20. 资料来源

本文参考了当前 Codex 本地手册缓存中的官方内容，主要对应以下主题：

• Codex Quickstart
• Execution Model and Workflows
• Prompting
• Goal mode
• Automations
• Agent Skills
• Custom instructions withAGENTS.md
• Model Context Protocol
• Plugins
• Subagents
• Rules, sandboxing, permissions

本地手册缓存路径：

C:\Users\Hilbe\AppData\Local\Temp\openai-docs-cache\codex-manual.md

文中的三张界面截图来自 OpenAI 官方 Codex 入门页面，并已保存到当前文件夹的assets/目录，方便离线查看 Markdown。

第 14 章关于 CC Switch 的内容，主要参考了以下来源：

• CC Switch 官方仓库
• CC Switch 中文说明
• CC Switch 官网