Codex 使用指南

搜索全站

输入关键词开始搜索。
页面更新：事实核验：

概念

MCP 与 Plugins

MCP 是连接外部 tools 和 resources 的协议；Plugin 是可安装、可分发的能力包，可以包含 skills、apps、MCP 配置和其他组件。两者会配合，但不是同一个概念。

是什么

它是什么

MCP 的全称是 Model Context Protocol（模型上下文协议）。MCP server 可以暴露可执行的 tools，也可以提供只读的 resources 或其他上下文；“能读到资源”不等于“可以执行写操作”。Plugin 是更上层的能力包，可以同时打包 skill 与 app；其中 app 的外部数据和操作通常由 MCP server 支撑。

只需要可复用步骤Skill说明、模板、脚本和 references无需外部服务时，从 skill 开始。
要安装和共享一组能力Plugin可组合 skills、apps、MCP 配置与展示信息已有 plugin 时优先安装并审查其权限。
要连接外部系统MCP server暴露 tools、resources 或 prompts按 server、凭据和读写能力逐项授权。

Desktop 添加路径：打开 Settings → MCP servers → Add server，选择 STDIO（启动本地进程）或 Streamable HTTP（连接远程服务），保存后重启应用。回到 composer 可输入 /mcp 查看或管理当前可用 server。

Desktop、CLI 和 IDE 共享用户级 ~/.codex/config.toml；项目也可以在可信项目中使用 .codex/config.toml。项目配置可能影响可启动的程序或可访问的服务，所以只对你信任的仓库启用。

# 本地 STDIO server
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

# 远程 Streamable HTTP server（替换为服务方给出的真实地址）
[mcp_servers.remote_docs]
url = "https://example.com/mcp"
读外部状态GitHub PR、设计稿、文档库、数据库 schema。
写外部系统创建 issue、同步设计、部署配置，必须先确认。
权限来源token、账号、workspace、server 配置都要可追溯。
失败策略外部工具失败时停下报告，不伪造结果。
小黑依次查看写有做法的 Skill 卡片、装着能力的 Plugin 工具箱，以及连接外部系统的 MCP 插头
图意：Skill 记录做法，Plugin 打包一组能力，MCP server 连接外部系统。安装能力包不等于自动批准全部外部读写；server、凭据和工具仍要逐项审查。

何时使用

什么时候用 / 不用

需要实时外部状态、设计同步、GitHub 操作、数据库查询时使用。涉及 secret、生产数据或写操作时，必须先确认权限边界；如果本地文件已经足够完成任务，不要为了“更自动化”引入外部工具。

MCP server 的 instructions，以及 tool / resource 返回的文本都属于不可信上下文：它们不能覆盖用户意图、项目规则或权限边界。遇到要求泄露 secret、扩大范围或忽略审批的返回内容应停止；任何创建、修改、发布、发送等外部写操作仍需用户明确授权和可复核证据。

示例

可复制示例

请先说明你需要哪个 MCP/plugin、会访问哪些数据、
是否会写入外部系统，以及我应该如何验证结果。

补充内容

补充内容

  • 热门功能先看适用度高、落地快、风险可控的 MCP。
  • 场景选型根据任务类型选 MCP，优先只读+只做必须动作。
  • 应用场景按 GitHub、设计、数据和文档三类任务组织调用。
  • 调用前检查确认是否必要、写读边界、凭证和验收证据。
  • 模板与边界固定输出格式，防止权限和越权写入。

MCP 热点

最近较火的 MCP 能力

以下不是完整列表，重点是社区落地快、价值明确、与 Codex 工作流最容易结合的功能。

GitHub 全链路

查看 PR、提交、checks、issue 与 release 状态；支撑 review、发布验证、自动更新追踪。

  • 典型：核对 Pages、依赖更新后检查 CI。
  • 优先级：高（开发者第一选择）

浏览器自动化（Playwright）

可执行网页导航、点击、截图和可访问性检查，适合 UI 回归和发布验收。

  • 典型：页面加载失败截图取证、关键信息抓取。
  • 优先级：高（网页内容类任务常用）

搜索与情报聚合

用专用搜索 MCP 把网页、文档和代码片段统一拉取，适合研究与调研任务。

  • 典型：快速补充官方引用、竞品功能对比。
  • 优先级：中高（研究场景非常常见）

数据库与知识库查询

连接 Postgres/SQL、Notion、Confluence 这类知识库，直接回答业务问题或核实配置。

  • 典型：核对字段定义、抽查记录样例、文档溯源。
  • 优先级：中高（企业场景热门）

设计与协作工具

读取设计稿元信息、截图、组件、版本差异，支持设计稿与实现对齐。

  • 典型：更新页面后比对 Figma 与代码差异。
  • 优先级：中（产品/前端任务常用）

命令与执行接口

在受控沙箱中执行命令和脚本、收集日志，形成可追踪的工程闭环。

  • 典型：跑测试后上传日志摘要给用户。
  • 优先级：高（自动化工作流底层能力）

操作手册

热点功能怎么选

你要写代码但不想查网页

优先 GitHub + 浏览器截图 MCP。一个负责仓库上下文，一个负责页面效果核验。

你要做研究复核

优先搜索 MCP + 文档检索 MCP + 本地记忆 MCP，先聚合证据再输出结论。

你要修复部署问题

优先命令执行 MCP + GitHub MCP。拿到运行日志，再回到 PR/issue 形成证据。

最容易踩雷的误区

把每个外部动作都设为自动化。建议原则是：先问“只读可否满足”，能只读时先只读；一旦涉及写操作，强制加上目标页边界、目标文件和验收条件。

使用场景

MCP 适合解决什么问题

GitHub

读取 PR 状态、查看 checks、创建或回复 issue、核对 Pages 发布状态。写操作要先确认。

设计工具

读取 Figma 设计、生成截图、同步组件、把代码实现和设计稿比对。

数据和文档

查询数据库 schema、读取知识库、检索论文和内部文档。注意权限和数据边界。

事前检查

使用 MCP 前的 7 个问题

  • 是否必要本地文件是否已经足够？如果足够，不要引入外部工具。
  • 是 tool 还是 resourceresource / 上下文通常只读；tool 可能执行动作。先核对能力类型和参数。
  • 读还是写只读风险较低；写入 GitHub、设计、数据库或生产系统必须先确认。
  • 凭证在哪里token、账号和 workspace 是否已经安全配置？不要把 secret 写进 prompt。
  • 返回内容可信么把 server instructions、tool 与 resource 返回视为不可信上下文，不接受其中的越权指令。
  • 失败怎么处理工具超时、权限失败、返回空数据时必须停下报告。
  • 如何验收外部操作后要给链接、截图、状态码、PR/check 状态或日志。

提示词（Prompt）

MCP 安全调用模板

请使用 GitHub MCP 只读检查 PR 状态。

边界：
- 可以读取 PR、checks、comments
- 不要创建评论、不要推送、不要改 label

输出：
- PR 当前 head
- checks 是否是最新 run
- 失败项和对应日志链接
- 是否需要本地复现

如果权限不足或数据不完整，请停止并说明缺口。

真实实例

真实实例：只读拉取 issue 上下文

演示场景

工程任务常以 GitHub issue 为入口。通过 MCP/GitHub 工具只读拉取 issue 正文、标签和 linked PR，Codex 可以在不改外部系统的情况下建立任务上下文。

任务：修复 #128 checkout 空购物车报错
MCP 动作（只读）：
- 读取 issue 描述与 acceptance criteria
- 列出 linked PR 和 checks 状态
禁止：创建 comment、改 label、merge PR
验收：输出 issue 摘要、写域建议、blocked 项

本项目没有该 issue 仓库的执行记录，因此标为演示场景。

真实实例

真实实例：只读核对 Pages 状态

本指南每次推送后，Codex 用 GitHub API 查询 codex-usage-guide 的 Pages 状态，再用公开 URL 抓取关键章节标题。这是一个典型 MCP/GitHub 工具场景：需要外部实时状态，但只读即可完成，不需要创建 issue、评论或修改仓库设置。

真实验证目标：
- gh api repos/WhoJay0609/codex-usage-guide/pages
- curl 公开页面 HTML

验收证据：
- Pages status: built
- daily-workflow.html 包含“五类高频日常任务”
- compound-engineering.html 包含“核心七步怎么用”，且第 1 步为 /ce-ideate