一文精通 Codex 的使用：从安装、插件、自动化到分支合并

Codex 不是一个简单的“代码补全工具”。

更准确地说：

1

Codex 是一个可以读代码、改代码、跑命令、做验证、写文档、做自动化任务的 AI 编程代理。

如果你只让它写几行函数，那当然也能用。

但这不是它最强的地方。

Codex 真正适合做的是：

• 读懂一个项目
• 拆解一个需求
• 修改多个文件
• 跑测试
• 做代码审查
• 创建分支
• 提交改动
• 推送到远程
• 开 PR
• 跟进自动化任务
• 把重复工作沉淀成 Skill 或插件

本文就按真实使用路径来讲：

1

安装 Codex -> 选择使用入口 -> 配置项目 -> 使用 Skill / 插件 -> 做自动化 -> 管理分支 -> 合并代码

一、先理解 Codex 有哪些入口

Codex 不是只有一种使用方式。

常见入口主要有这几类：

1
2
3
4

Codex CLI
Codex App
Codex IDE Extension
Codex Web

OpenAI 官方对 Codex 的定义很直接：

1

Codex 是帮助你编写、审查和发布代码的 AI agent。

也就是说，它不是单纯回答问题，而是可以进入开发流程。

我个人更推荐这样选：

如果你刚开始用，建议先从：

1

Codex CLI + Codex App

这两个入口最容易理解 Codex 的工作方式。

二、安装 Codex CLI

Codex CLI 是最直接的入口。

它运行在终端里，可以在当前目录读取文件、修改文件、执行命令。

官方文档里给出的 macOS / Linux 安装方式是：

1

curl -fsSL https://chatgpt.com/codex/install.sh | sh

如果是无人值守安装，可以加：

1

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

安装完成后，在项目根目录运行：

1

codex

第一次运行时，会提示你登录。

一般可以选择：

1

使用 ChatGPT 账号登录

或者：

1

使用 API Key

登录完成后，就可以开始让 Codex 读取当前项目。

比如：

1

帮我分析这个项目的结构

或者：

1

帮我找一下首页文章列表在哪里渲染

这一步不要急着让它写代码。

刚开始最好先让它看项目。

三、第一次使用 Codex，先让它读项目

很多人第一次用 Codex，就直接说：

1

帮我实现某某功能

这当然可以。

但更稳的方式是先让它建立上下文。

比如：

1
2
3
4
5
6

请先阅读这个项目结构，告诉我：
1. 这是一个什么项目
2. 入口文件在哪里
3. 主题/组件/页面分别在哪里
4. 构建命令是什么
5. 提交前应该注意哪些文件不要上传

如果是前端项目，可以问：

1

请帮我找出首页、文章页、分类页分别由哪些文件控制。

如果是后端项目，可以问：

1

请帮我梳理路由、控制器、服务层、数据库模型之间的关系。

如果是一个你不熟悉的老项目，可以问：

1

请帮我画出这个项目的核心调用链，并指出最适合开始修改的文件。

这类问题会让 Codex 先进入“理解项目”的状态。

理解之后再改，成功率会高很多。

四、Codex 的三种典型权限模式

用 Codex 时，一定要理解权限模式。

因为它不只是聊天，它可能真的会改你的文件。

常见模式可以理解为三档：

1
2
3

只建议
自动编辑
全自动

1. 只建议

这种模式最安全。

Codex 可以读文件、分析问题、提出修改方案，但真正改文件和执行命令前需要你确认。

适合：

• 学习项目
• 做代码审查
• 看改动建议
• 不确定 Codex 是否理解需求时

2. 自动编辑

这种模式下，Codex 可以自动改文件。

但执行命令通常还需要确认。

适合：

• 批量改样式
• 调整配置
• 修改多个组件
• 重构局部代码

3. 全自动

这种模式下，Codex 可以更自主地写文件、跑命令、修错误。

适合：

• 修复构建失败
• 长时间跑测试
• 原型开发
• 自动化维护任务

但要注意：

1

全自动模式一定要在 Git 仓库里使用。

因为 Git 是最后的保险。

如果改错了，你至少可以通过 diff 看清楚它改了什么。

五、插件、Skill、MCP 到底是什么

Codex 的强大，不只是模型本身。

它还可以通过不同扩展能力做事。

这里最容易混淆的是三个概念：

1
2
3

Skill
Plugin
MCP

1. Skill

Skill 可以理解为：

1

给 Codex 的专业工作说明书。

比如：

• 前端设计 Skill
• 安全审计 Skill
• SEO Skill
• Git Skill
• 文档写作 Skill
• 表格处理 Skill
• 图片生成 Skill

它告诉 Codex：

1

遇到某类任务时，应该按什么流程做。

比如你让 Codex 写一篇文章，它可以使用写作类 Skill。

你让它改页面，它可以使用前端设计 Skill。

你让它检查登录接口，它可以使用安全审计 Skill。

2. Plugin

Plugin 可以理解为：

1

把一个或多个 Skill、工具、MCP 配置、应用集成打包在一起。

比如一个浏览器插件，可能包含：

• 浏览器自动化能力
• 截图能力
• 页面检查能力
• 对应 Skill

一个文档插件，可能包含：

• Word 文档处理能力
• 渲染验证脚本
• 文档编辑 Skill

插件的价值在于：

1

让复杂能力可以被安装、复用、共享。

在团队环境里，插件通常还会受到管理员权限控制。

3. MCP

MCP 更像是：

1

让 Codex 连接外部工具和上下文的协议。

比如连接：

• GitHub
• Slack
• Linear
• 数据库
• 浏览器
• 内部系统
• 文档系统

如果 Skill 是“怎么做事”，MCP 更像是“能接触哪些工具”。

六、如何安装和使用插件

不同 Codex 客户端的插件安装方式可能不同。

但大体流程是：

1

找到插件 -> 安装插件 -> 授权能力 -> 在任务中调用

比如在 Codex App 里，你可能会看到类似：

• Browser
• Documents
• Presentations
• Spreadsheets
• OpenAI Developers

这类插件不是装饰品。

它们会直接影响 Codex 能做什么。

例如：

1

Browser 插件

可以让 Codex 打开本地页面、检查布局、截图验证。

1

Spreadsheets 插件

可以让 Codex 创建、编辑、分析表格。

1

Documents 插件

可以处理 Word 文档和文档渲染检查。

安装插件后，使用时可以直接说：

1

请用浏览器打开 localhost:4000，检查首页是否正常。

或者：

1

请用表格插件帮我生成一个预算表。

很多时候，你不需要记住插件的内部名字。

你只要说清楚任务，Codex 会选择合适能力。

七、什么时候该把流程做成 Skill

如果你发现某件事会重复做，就应该考虑写成 Skill。

比如：

1

每次发布前都检查构建、Git 状态、未忽略文件、文章链接、图片路径。

这种任务如果每次都重新描述，会很浪费。

更好的方式是把它写成 Skill：

1

博客发布检查 Skill

里面可以规定：

• 先跑 git status
• 检查 .gitignore
• 跑构建命令
• 检查图片路径
• 检查新增文章 front matter
• 最后输出发布检查结果

以后你只要说：

1

使用博客发布检查 Skill 帮我检查一下。

Codex 就知道该怎么做。

Skill 适合沉淀：

• 固定流程
• 团队规范
• 项目约定
• 检查清单
• 常用命令
• 风格要求

八、自动化：让 Codex 定时做事

Codex 的自动化功能，适合做重复检查。

比如：

• 每天检查依赖更新
• 每周整理未处理 Issue
• 定时检查 PR 状态
• 定时跑构建
• 定时生成项目周报
• 定时检查博客链接是否失效
• 定时检查线上页面是否能访问

官方文档里提到，自动化可以在后台运行，发现结果时放进 Triage / inbox，没有内容时可以自动归档。

而且自动化可以结合 Skill。

这点非常关键。

因为自动化不是简单的“定时提醒”，而是：

1

定时让 Codex 按某个流程完成一件事。

例如：

1
2
3
4
5
6

每天早上 9 点检查 my-blog 项目：
1. 是否有未提交修改
2. 是否有新增文章没配 tags/categories
3. 是否能正常 pnpm run build
4. 如果有问题，汇总到 Triage
5. 如果没有问题，自动归档

这就是一个很适合自动化的任务。

九、线程自动化和独立自动化

自动化大致可以分成两类：

1
2

线程自动化
独立自动化

1. 线程自动化

线程自动化适合：

1

让 Codex 过一会儿回到当前对话继续做事。

比如：

• 等部署完成后回来检查
• 每 10 分钟查看一次命令是否跑完
• 过 30 分钟提醒你继续某个任务
• 持续跟进一个 PR 的状态

这种自动化会保留当前线程上下文。

适合短周期跟进。

2. 独立自动化

独立自动化适合：

1

每次都从一个固定任务开始，独立运行。

比如：

• 每天检查项目构建
• 每周生成报告
• 每天检查 GitHub Issue
• 每周检查依赖版本

这种更像一个定时任务。

每次运行都是新的任务。

十、自动化最好跑在 Worktree 里

如果项目是 Git 仓库，自动化最好跑在：

1

worktree

Worktree 可以理解成：

1

同一个 Git 仓库的另一个独立工作目录。

这样 Codex 可以在后台跑任务，不影响你当前正在写的代码。

官方文档也明确说明：

1

worktree 可以让 Codex 在同一个项目里并行处理多个独立任务，避免互相干扰。

举个例子：

你本地正在修改首页样式。

同时你想让 Codex 去检查所有文章链接。

如果它直接在当前目录运行，可能会影响你的未完成修改。

如果放到 worktree 里，它就在另一个工作目录里跑。

这就干净很多。

十一、Codex 和 Git 分支的正确配合方式

用 Codex 改代码时，必须把 Git 分支管理好。

推荐流程是：

1
2
3
4

git status
git checkout main
git pull
git checkout -b codex/feature-name

然后让 Codex 在这个分支上工作。

分支命名建议：

1
2
3
4

codex/页面调整
codex/fix-build-error
codex/add-tools-page
codex/write-codex-guide

我更推荐英文和短横线：

1

git checkout -b codex/add-tools-page

这样远程仓库、CI、PR 页面都更清楚。

十二、让 Codex 改代码前，先说清楚边界

不要只说：

1

帮我优化一下。

这句话太宽。

更好的说法是：

1
2
3
4
5
6
7

请只修改首页样式相关文件，不要改文章内容。
要求：
1. PC 端文章列表一行显示 2 个
2. 移动端保持 1 个
3. 所有分类和标签完整显示
4. 修改后运行 pnpm run build
5. 最后告诉我改了哪些文件

这类提示词很重要。

因为 Codex 的能力很强，但边界不清楚时，它可能会做太多。

真实项目里，最好的 Codex 提示词应该包含：

• 要改什么
• 不要改什么
• 验证方式
• 成功标准
• 输出结果

十三、提交前一定要看 diff

Codex 改完后，不要马上提交。

先看：

1
2

git status
git diff

你要确认：

• 有没有改错文件
• 有没有生成文件被加入
• 有没有 .DS_Store
• 有没有 node_modules
• 有没有 public
• 有没有敏感信息
• 有没有不相关修改

如果是博客项目，尤其要注意：

1
2
3
4

public/
db.json
.DS_Store
node_modules/

这些一般不该提交。

如果 .gitignore 没写好，先修 .gitignore。

不要把脏东西带到 GitHub。

十四、让 Codex 帮你写 commit 信息

确认 diff 没问题后，可以让 Codex 生成 commit 信息。

比如：

1

请根据当前 git diff，帮我写一个简洁的 commit message。

常见格式：

1
2
3
4

feat: add tools page entries
style: polish blog homepage layout
fix: ignore local generated files
docs: add codex usage guide

然后提交：

1
2

git add .
git commit -m "docs: add codex usage guide"

如果改动比较多，可以不要直接 git add .。

更稳的方式是：

1
2
3

git add source/_posts/xxx.md
git add source/images/xxx.png
git add themes/keep/xxx

这样更可控。

十五、推送分支并创建 PR

提交完成后，推送到远程：

1

git push -u origin codex/add-tools-page

然后创建 PR。

如果你使用 GitHub，可以在网页上打开 PR。

也可以让 Codex 帮你生成 PR 描述：

1
2
3
4
5

请根据当前分支的 diff，帮我写一个 GitHub PR 描述：
1. 改了什么
2. 为什么改
3. 怎么验证
4. 是否有风险

一个好的 PR 描述应该长这样：

1
2
3
4
5
6
7
8
9
10
11

## Summary
- Added category chips to the homepage
- Expanded the tools page entries
- Updated Codex article content

## Verification
- pnpm run build
- Checked /tools page preview

## Risk
- Low, mostly content and theme template changes

PR 不是形式。

PR 是你和未来的自己交代清楚：

1

为什么这次改动是安全的。

十六、分支合并：merge 和 rebase 怎么选

分支合并常见有两种方式：

1
2

merge
rebase

1. merge

适合团队协作。

命令：

1
2
3
4

git checkout main
git pull
git merge codex/add-tools-page
git push

优点：

• 保留完整分支历史
• 不改变已有提交
• 对团队更安全

缺点：

• 历史可能会多一个 merge commit

2. rebase

适合个人分支整理历史。

命令：

1
2
3

git checkout codex/add-tools-page
git fetch origin
git rebase origin/main

如果没有冲突，再推送：

1

git push --force-with-lease

注意：

1

不要随便对别人也在用的分支 rebase。

因为 rebase 会改写提交历史。

个人分支可以用。

共享分支慎用。

十七、遇到冲突时，让 Codex 辅助解决

合并分支时，最常见的问题就是冲突。

比如：

1

git merge codex/add-tools-page

出现：

1

CONFLICT

这时不要慌。

可以让 Codex 做三件事：

1
2
3

1. 解释冲突原因
2. 给出保留哪一边的建议
3. 修改冲突文件并跑测试

提示词可以这样写：

1
2
3
4
5

当前 Git merge 有冲突。
请先读取冲突文件，解释每个冲突的原因。
然后给出解决方案。
不要直接删除任何一边的逻辑，除非你能说明原因。
解决后运行 pnpm run build。

这个时候 Codex 非常有用。

因为它不只是机械解决冲突，还能看上下文。

十八、合并后要做最后验证

分支合并后，不要直接完事。

至少跑一次：

1

pnpm run build

如果是前端项目，还应该打开页面看：

1
2
3
4
5
6

首页
文章页
分类页
工具页
移动端
暗色模式

如果是后端项目，至少跑：

1

npm test

或者项目自己的测试命令。

如果没有测试，也要让 Codex 帮你做基本检查：

1

请帮我检查这次合并后是否有明显的类型错误、路径错误、配置错误。

十九、一个完整 Codex 工作流示例

下面是一套我认为比较实用的 Codex 工作流：

1
2
3
4
5
6
7
8
9

# 1. 更新主分支
git checkout main
git pull

# 2. 创建 Codex 工作分支
git checkout -b codex/add-codex-guide

# 3. 启动 Codex
codex

然后告诉 Codex：

1
2
3
4
5
6
7
8

请为我的 Hexo 博客新增一篇文章：
主题：一文精通 Codex 的使用
要求：
1. 使用现有文章风格
2. 包含安装、插件、Skill、自动化、分支、合并
3. 文章放到 source/_posts
4. 写完后运行 pnpm run build
5. 最后告诉我新增了哪些文件

Codex 完成后：

1
2
3
4
5
6

git status
git diff
pnpm run build
git add source/_posts/mastering-codex-from-install-to-automation-and-branch-merge.md
git commit -m "docs: add codex usage guide"
git push -u origin codex/add-codex-guide

然后创建 PR。

PR 合并后：

1
2
3

git checkout main
git pull
git branch -d codex/add-codex-guide

如果远程分支也要删：

1

git push origin --delete codex/add-codex-guide

二十、Codex 使用时最容易犯的错误

1. 一次性让它改太多

比如：

1

帮我重构整个项目。

这很危险。

更好的方式是拆成：

1
2
3
4
5

先分析
再写计划
再改一个模块
再验证
最后合并

2. 不看 diff

Codex 再强，也不能替你承担最终责任。

提交前一定要看 diff。

3. 没有 Git 分支

直接在 main 上让 Codex 改代码，是新手最常见的问题。

一定要建分支。

4. 不跑测试

页面看着没问题，不代表构建没问题。

构建通过，也不代表逻辑没问题。

能跑测试就跑测试。

5. 把自动化权限开得太大

自动化是无人值守任务。

权限越大，风险越大。

能用只读就不要给写权限。

能用 worktree 就不要直接改本地目录。

二十一、我推荐的 Codex 使用口诀

最后总结成一句话：

1

小任务直接做，大任务先计划；写代码用分支，自动化用 worktree；提交前看 diff，合并后跑验证。

如果再压缩一点：

1

先读懂，再动手；先隔离，再合并。

Codex 的价值，不是让你完全不看代码。

它真正的价值是：

1

把重复、繁琐、容易遗漏的工程流程交给 AI，但关键决策仍然由你把关。

这样使用 Codex，才是比较稳的方式。

参考资料

• Using Codex with your ChatGPT plan
• Codex CLI
• Codex Automations
• Codex Worktrees
• Codex Use Cases