Codex 使用指南：从基础协作到插件、Skills、MCP 和电脑操控

Codex 使用指南：从基础协作到插件、Skills、MCP 和电脑操控

学习目标

这篇文章面向已经接触过 AI 编程助手，但还没有系统使用 Codex 的开发者。

读完之后，你应该能回答这些问题：

  • Codex 适合解决哪些开发任务？
  • CLI、IDE、Codex app、云端任务分别适合什么场景？
  • AGENTS.md、skills、plugins、MCP 之间有什么区别？
  • 什么时候该用插件，什么时候该用 MCP，什么时候该写一个 skill？
  • Codex 的浏览器访问和电脑操控能做什么，不能做什么？
  • 如何把 Codex 用得更稳定、更安全、更可控？

本文不会只罗列功能，而是按“实际工作流”讲：先建立心智模型，再讲配置方法，最后给出可直接套用的提示词和实践清单。

一、先理解 Codex：它不是聊天机器人，而是开发代理

普通聊天式 AI 更像一个“回答问题的人”。你问它代码怎么写，它给你一段示例。

Codex 更像一个“能进入项目现场的开发代理”。它可以读取代码、理解仓库结构、修改文件、运行命令、查看 diff、跑测试、使用浏览器验证页面，甚至在获得授权后操作桌面应用。

这意味着你使用 Codex 时，不应该只问：

帮我写一个登录接口

更好的方式是给它一个可执行任务：

阅读当前项目的认证模块，按现有风格新增手机号验证码登录接口。
要求：
1. 只修改认证相关文件
2. 复用已有响应结构
3. 补充最小必要测试
4. 修改后运行相关测试并总结风险

区别在于：后者让 Codex 有明确的上下文、边界、验收标准和验证动作。

二、Codex 的几个使用入口

Codex 不是只有一种形态。常见入口可以简单分为四类。

入口 适合场景 典型任务
CLI 终端优先、本地仓库任务 改代码、跑测试、脚本化任务
IDE 扩展 边写代码边协作 解释文件、局部重构、快速修复
Codex app 桌面端综合工作流 规划、审查、浏览器验证、电脑操控
云端任务 后台并行处理 批量修复、代码审查、较长任务

选择入口的原则很简单：

  • 你已经在终端里工作，用 CLI。
  • 你正在编辑器里看具体代码，用 IDE 扩展。
  • 你需要浏览器、桌面应用、插件和更强的交互界面，用 Codex app。
  • 你想把任务丢出去并行跑，考虑云端任务。

不要纠结哪个入口“最高级”。入口只是工作位置不同，真正重要的是任务描述是否清楚、权限是否合适、验证是否充分。

三、一个高质量 Codex 任务应该怎么写

Codex 的效果很大程度取决于任务是否可执行。一个好的任务通常包含五个要素：

  1. 背景：当前问题是什么？
  2. 范围：允许修改哪些地方？
  3. 约束：不能做什么？
  4. 验收：怎样算完成？
  5. 验证：需要运行哪些测试或检查？

示例：

修复订单取消接口在重复请求时偶发 500 的问题。

要求：
- 先阅读 order 模块相关代码
- 保持现有 API 响应格式
- 不修改数据库表结构
- 只补充与幂等取消相关的最小测试
- 修改后运行订单模块测试
- 最后按“变更文件、测试结果、风险”总结

这类提示词的优点是：Codex 不需要猜边界，也不会一上来做大范围重构。

如果需求还不清楚，可以直接要求 Codex 先分析：

先不要改代码。阅读支付模块，解释退款流程的数据流和关键风险点。
然后给出最小修改方案，等我确认后再实现。

四、AGENTS.md：给仓库写长期工作规则

如果每次都在 prompt 里重复“不要乱改文件、先跑测试、用 pnpm、不允许 git push”，很低效。

这类长期规则适合写进 AGENTS.md。

AGENTS.md 可以理解为 Codex 的项目说明书。Codex 开始工作前会读取它，并把里面的规则作为当前仓库的协作约定。

一个简单示例：

# AGENTS.md

## 工作规则

- 不允许执行 `git add .`
- 不允许自动执行 `git commit` 或 `git push`
- 修改前先阅读相关代码
- 优先做最小改动，不做无关重构
- 修改后运行最小相关测试
- 最终总结变更文件、测试结果和风险

4.1 AGENTS.md 适合放什么

适合放：

  • 项目固定命令，比如 npm test、mvn test、make test
  • 代码风格和目录约定
  • 安全规则，比如禁止提交密钥
  • Git 操作约束
  • 测试和 review 流程
  • 特定模块的注意事项

不适合放：

  • 一次性需求
  • 临时想法
  • 过长的业务文档
  • 需要频繁变化的任务描述

一句话：稳定的协作规则写进 AGENTS.md，临时任务写进 prompt。

五、Skills：把可复用工作流封装起来

Skill 是 Codex 的“专项操作手册”。它通常是一个包含 SKILL.md 的目录，里面写明这个 skill 什么时候触发、需要遵循什么步骤、是否要使用附带脚本或参考资料。

比如你经常让 Codex 写技术文章，可以做一个 tech-article-writer skill：

---
name: tech-article-writer
description: Use when writing Chinese technical tutorial articles with examples, structure, and review checklist.
---

When writing an article:
1. Start with learning goals.
2. Explain concepts from concrete examples.
3. Include common mistakes.
4. Add a final checklist.
5. Keep code examples minimal and correct.

以后你只要说：

$tech-article-writer 写一篇关于 Redis 缓存穿透的文章

Codex 就会按这个 skill 的流程执行。

5.1 Skill 的触发方式

Skill 通常有两种触发方式：

  • 显式触发：你在 prompt 里点名 $skill-name
  • 隐式触发：Codex 根据 skill 描述判断当前任务匹配它

隐式触发依赖 description，所以 skill 描述必须清楚，不能写得太泛。

不好的描述：

Help with development.

好的描述：

Use when creating or editing Chinese backend technical blog articles with tutorial structure and runnable examples.

5.2 Skill 适合解决什么问题

适合：

  • 固定写作格式
  • 固定测试流程
  • 固定发布流程
  • 代码审查模板
  • 文档生成规范
  • 某个团队内部的排障步骤

不适合：

  • 需要实时访问外部系统的数据
  • 需要登录第三方服务
  • 需要提供大量工具调用能力

如果只是“让 Codex 按某套步骤做事”，用 skill。
如果要“给 Codex 新工具或外部数据”，看 MCP 或插件。

六、Plugins：把 skills、应用集成和 MCP 打包分发

Plugin 是更大的封装单位。一个 plugin 可以包含：

  • skills：可复用工作流
  • app integrations：外部应用连接，比如 Gmail、Slack、Google Drive
  • MCP servers：给 Codex 增加工具和上下文
  • 其他资源或配置

可以这样理解：

Skill  = 一份专项工作说明
Plugin = 一组可安装、可分发的能力包

如果你只是给自己当前项目写一个工作流，直接写 skill 就够了。
如果你想让整个团队安装同一套能力，或者把 skill、MCP、应用连接一起交付，就应该做 plugin。

6.1 插件的典型使用方式

在 Codex app 中，可以通过 Plugins 页面浏览和安装插件。

安装后，你可以直接描述任务：

总结今天 Slack 里和发布事故相关的讨论，并整理成复盘大纲。

也可以显式指定插件：

@Slack 查找今天 #incident 频道中关于订单超时的讨论。

如果插件需要连接外部应用，通常会在安装或首次使用时要求授权。

6.2 什么时候需要自己做插件

自己做插件通常有三个原因：

  1. 团队需要共享同一套工作流
  2. 需要把多个 skills 打包在一起
  3. 需要同时分发 MCP 配置、应用连接或辅助资源

例如，一个团队可以做一个 backend-review 插件，里面包含：

  • Java 代码审查 skill
  • SQL 审查 skill
  • 安全检查 skill
  • 内部文档 MCP 配置
  • 固定 review 输出模板

这样新人安装插件后，就能直接继承团队的工作方式。

七、MCP：给 Codex 接入外部工具和上下文

MCP，全称 Model Context Protocol，可以理解为“让模型连接工具和上下文的协议”。

如果说 skill 是“告诉 Codex 怎么做”，那么 MCP 是“给 Codex 新工具去做”。

典型 MCP 能力包括：

  • 搜索和读取开发文档
  • 查询内部知识库
  • 操作浏览器或设计工具
  • 访问 GitHub issue、PR、CI 状态
  • 读取 Sentry 日志
  • 调用你自己写的内部系统接口

7.1 MCP 的两种常见形态

第一种是本地 STDIO server。

它由 Codex 启动一个本地进程，通过标准输入输出通信。例如：

[mcp_servers.cnblogs]
command = "D:\\1\\work\\cnblogs-mcp\\.venv\\Scripts\\python.exe"
args = ["D:\\1\\work\\cnblogs-mcp\\cnblogs_mcp.py"]
startup_timeout_sec = 30

[mcp_servers.cnblogs.env]
DOTENV_PATH = "D:\\1\\work\\cnblogs-mcp\\.env"

这个例子表示：Codex 启动一个本地 Python MCP 服务，然后通过它调用博客园发布接口。

第二种是 Streamable HTTP server。

它通过 URL 访问远程 MCP 服务，常见于在线文档、设计工具、云服务等场景。

7.2 MCP 和普通 API 调用有什么区别

普通 API 是你写代码去调用系统。
MCP 是把系统能力描述成 Codex 可理解、可选择、可审批的工具。

这带来几个好处：

  • Codex 能看到工具名称、参数结构和说明
  • 工具调用可以进入 Codex 的权限与审批体系
  • 多个客户端可以复用同一个 MCP server
  • 外部系统的细节被封装在 server 内部

比如“发布博客”这件事，不需要每次都让 Codex 重新理解博客园 API。你只要提供一个 create_post MCP 工具，Codex 负责组织标题、正文和标签，然后调用工具。

7.3 MCP 适合什么场景

适合：

  • 有明确输入输出的外部操作
  • 需要实时读取外部数据
  • 需要访问私有系统
  • 需要可控地执行动作，比如发文、查日志、建 issue

不适合：

  • 只是一段写作规范
  • 只是项目内长期协作规则
  • 不需要工具调用的简单任务

简单判断：

要改变 Codex 的工作流程 -> skill
要打包分发能力 -> plugin
要接入工具或数据源 -> MCP
要固定仓库规则 -> AGENTS.md

八、浏览器访问：用页面验证，而不是只看代码

前端和 Web 应用开发里，代码正确不代表页面正确。

按钮可能溢出，弹窗可能遮挡内容，移动端布局可能错位，接口可能在浏览器里跨域失败。这些问题单靠 npm test 不一定能发现。

Codex app 的 in-app browser 提供了一个你和 Codex 共享的浏览器视图。安装并启用 Browser 插件后，Codex 可以使用 @Browser 打开页面、点击、输入、截图、检查渲染状态，并验证修改结果。

示例：

使用 @Browser 打开  http://localhost:3000/settings 。
复现移动端按钮溢出问题，只修复这个页面的布局。
修改后重新打开该页面截图验证。

8.1 In-app browser 适合什么

适合：

  • 本地开发服务器页面
  • 不需要登录的公开页面
  • 文件预览页面
  • UI 布局验证
  • 截图检查
  • 轻量 DOM、样式、网络问题排查

不适合：

  • 依赖你个人登录状态的网站
  • 依赖浏览器插件的页面
  • 依赖你常用 Chrome profile、cookies、历史标签页的任务

如果任务需要你已经登录的网站，通常应该使用普通浏览器或 Chrome 扩展能力，而不是 in-app browser。

8.2 浏览器任务要写得具体

不推荐：

帮我看看页面有没有问题

推荐：

使用 @Browser 打开  http://localhost:3000/orders 。
检查 375px 宽度下订单表格是否横向溢出。
如果溢出，只调整表格容器和列宽策略，不改接口逻辑。
修复后再次验证空状态、加载状态和有数据状态。

浏览器能力最适合“可视化验收”。你要告诉 Codex 看哪一页、哪个状态、什么算问题、改动边界在哪里。

九、电脑操控：当命令行和结构化工具不够时

电脑操控，也就是 Computer Use，是 Codex app 中更强的一类能力。它允许 Codex 在获得权限后查看并操作图形界面，例如点击窗口、输入文字、检查桌面应用、操作浏览器页面。

它适合处理命令行和 MCP 难以覆盖的场景：

  • 测试桌面应用
  • 复现只在 GUI 中出现的 bug
  • 修改某个必须点击 UI 才能改的设置
  • 操作没有 API、没有插件、没有 MCP 的工具
  • 跨多个桌面应用完成一个流程

示例：

使用 @Computer 打开目标桌面应用。
复现“导入 CSV 后预览表格错位”的问题。
记录复现步骤，然后回到代码里修复最小相关逻辑。
修复后再次用同一流程验证。

9.1 电脑操控的边界

电脑操控很强，但不能滥用。

需要注意：

  • 它可能影响项目目录之外的系统状态。
  • 在 Windows 上，它使用当前活动桌面，可能会移动鼠标、输入文字，占用前台。
  • 它不能绕过 Codex 的文件、命令、审批和沙箱规则。
  • 它不应该用于需要你不在场输入敏感信息的流程。
  • 如果有结构化插件或 MCP，优先使用结构化集成。

例如，读取 Slack 消息时，如果有 Slack 插件，优先用插件；只有插件不可用、必须看图形界面时，再考虑电脑操控。

9.2 电脑操控任务怎么写

好的电脑操控任务要限制目标应用和动作范围：

使用 @Computer 只操作 Excel。
打开当前项目中的 report.xlsx，检查第二个工作表的图表是否显示为空。
不要修改文件。如果需要修改代码，先回到项目文件中说明原因。

不要写：

你自己看着操作电脑，把问题解决掉

电脑操控应该是精确工具，不是无限授权。

十、权限、沙箱和审批：让 Codex 可控地做事

Codex 能做很多事，但真正用于开发时，关键不是“让它什么都能做”，而是“让它在正确边界内做事”。

常见权限层次包括：

  • 文件读写权限
  • shell 命令权限
  • 网络访问权限
  • MCP 工具权限
  • 插件和外部应用授权
  • 浏览器站点授权
  • 电脑操控应用授权

你应该把高风险动作显式收紧：

  • 不允许自动提交和推送
  • 发布、删除、支付、改权限等动作需要确认
  • 涉及密钥、账号、后台配置时保持人工在场
  • 外部网站页面内容当作不可信输入处理

一个实用规则：

读和分析可以放宽，写和发布要审批；项目内操作可以放宽，项目外操作要收紧。

十一、把这些能力串成一个真实工作流

假设你要让 Codex 修复一个后台管理页面的布局问题，并发布一篇修复说明。

可以这样组织：

第一步：用 AGENTS.md 固定项目规则

- 修改前先阅读相关代码
- 不允许自动 git commit
- 前端改动后运行 npm test
- 视觉问题必须用浏览器验证

第二步：用 prompt 描述当前任务

修复用户管理页在移动端筛选栏换行错乱的问题。
只修改用户管理页相关组件和样式。
不要改接口逻辑。

第三步：用 Browser 验证页面

使用 @Browser 打开  http://localhost:3000/users 。
分别检查 375px 和 1440px 宽度下筛选栏布局。
修复后重新验证。

第四步：用 skill 固定发布说明格式

$release-note-writer 根据本次 diff 写一份发布说明。

第五步：用 MCP 发布到外部平台

使用 cnblogs MCP 把发布说明发到博客园，标签为前端、Codex、工程效率。

这个流程里，每个能力都有清晰位置：

  • AGENTS.md 管长期规则
  • prompt 管当前任务
  • Browser 管页面验证
  • skill 管固定写作格式
  • MCP 管外部发布动作

十二、常见错误用法

误区 1：把所有规则都塞进一次 prompt

一次性 prompt 适合临时需求，不适合长期规则。长期规则应该沉淀到 AGENTS.md 或 skill。

误区 2：把 skill 当成插件

Skill 只是工作流说明。它可以有脚本和参考资料，但它不是完整分发机制。需要团队共享、应用连接、MCP 配置时，应该考虑 plugin。

误区 3：把 MCP 当成万能插件

MCP 解决的是工具和上下文接入，不负责定义所有协作规范。不要为了几条写作规则去做 MCP。

误区 4：只让 Codex 改代码，不让它验证

更好的任务应该包含验证步骤：

修改后运行相关测试，并解释失败原因。如果测试无法运行，说明阻塞点。

对于前端，还应该加上：

使用浏览器打开相关页面，验证修复后的视觉状态。

误区 5：给电脑操控过大权限

电脑操控应该针对明确应用和明确流程。不要让 Codex 在没有边界的情况下随意操作桌面。

十三、推荐学习路线

如果你刚开始使用 Codex，可以按这个顺序学习：

第 1 阶段：基础协作

目标：让 Codex 会读代码、改代码、跑测试。

练习：

阅读当前项目结构，说明启动命令、测试命令和主要模块划分。不要修改文件。

修复一个小 bug，只修改相关文件，修改后运行最小测试。

第 2 阶段：项目规则

目标：用 AGENTS.md 固化团队协作方式。

练习：

根据当前项目，生成一个 AGENTS.md，包含构建、测试、代码风格和 Git 操作约束。
先给草稿，不要直接写入。

第 3 阶段：Skills

目标：把重复工作流变成可复用 skill。

练习：

创建一个 code-review skill，要求输出风险、边界条件、测试缺口和建议修复优先级。

第 4 阶段：Plugins

目标：把多个 skills 或集成能力打包给团队使用。

练习：

设计一个 backend-productivity plugin，包含 code review、SQL review、release note 三个 skills。
先给目录结构和 manifest 草案。

第 5 阶段：MCP

目标：接入真实工具和外部系统。

练习：

设计一个内部文档 MCP，提供 search_docs 和 read_doc 两个工具。
说明输入输出 schema、鉴权方式和安全边界。

第 6 阶段：浏览器和电脑操控

目标：让 Codex 能验证真实界面。

练习：

使用 @Browser 打开本地页面，检查移动端布局问题，修复后截图验证。

使用 @Computer 操作指定桌面应用，复现一个 GUI bug，只记录步骤，不修改系统设置。

十四、一张决策表

最后用一张表总结：

需求 推荐能力 原因
一次性开发任务 Prompt 简单直接
仓库长期规则 AGENTS.md 自动随项目加载
重复工作流 Skill 可复用、可触发
团队分发能力包 Plugin 可安装、可共享
接入外部工具或数据 MCP 标准化工具调用
验证网页效果 In-app browser / Browser plugin 能看到真实渲染
操作桌面应用 Computer Use 能处理 GUI 流程
涉及账号和敏感操作 人工确认 + 最小权限 降低风险

总结

Codex 的关键不是“会不会生成代码”，而是能否进入真实工程流程：

  • 它能读仓库、理解上下文、修改文件、运行测试。
  • AGENTS.md 让项目规则长期生效。
  • Skills 让重复工作流可复用。
  • Plugins 让能力可以安装、组合和分发。
  • MCP 让 Codex 接入外部工具和私有上下文。
  • Browser 能验证真实网页。
  • Computer Use 能处理 GUI 场景。
  • 权限、沙箱和审批保证这些能力不会失控。

真正高效的用法，是把 Codex 当作一个需要明确任务、边界和验收标准的工程协作者，而不是一个只负责补全代码的聊天窗口。

如果你只记住一个原则：让 Codex 做事之前，先定义清楚上下文、边界、工具和验收方式。

这样它才能从“能回答问题”变成“能交付结果”。

参考资料

posted @ 2026-06-18 10:34  松鼠航  阅读(79)  评论(0)    收藏  举报