本页目录
网络环境搭建 · 独立站搭建

通过 MCP,让 Codex 读懂你的工程和知识库:从零接通只需 3 步

Codex 是 OpenAI 的编程助手,能读代码、改代码、跑命令、跑测试、审代码。但刚装好的 Codex 只认识你电脑里的文件:它不知道你们团队的文档在哪、不知道公司知识库怎么查、不知道最新的官方文档写了什么。MCP(Model Context Protocol,模型上下文协议)就是补上这块的:接一个 MCP 服务器,Codex 就多了一套工具,能去查文档、读知识库、调外部服务。本文讲 MCP 是什么、Codex 是什么、接 MCP 服务器的完整步骤,以及怎么让 Codex 真正读懂你的工程和知识库。配置格式以 OpenAI 官方文档为准。

MCP 是什么

MCP 是 Anthropic 在 2024 年推出的开放协议,现在已经是各家 AI 编程工具都在用的通用标准。它的作用一句话就能说清:让 AI 应用用同一种方式,去接外部的工具和数据源。

没有 MCP 之前,每个 AI 工具接外部服务都要单独写一套对接方法;有了 MCP,服务方只要提供一个 MCP 服务器,任何支持 MCP 的客户端都能接上。对你来说,好处是:

  • 一次配置,多处复用:接好的 MCP 服务器,Codex 命令行、编辑器扩展、桌面应用共用同一份配置。
  • 不用再复制粘贴:以前是把文档内容复制进对话框再问,现在是 Codex 自己去查。
  • 工具可插拔:不需要的服务器随时关掉,不影响别的配置。

MCP 服务器分两种,你接的时候一定会遇到,先分清:

类型是什么适合接什么
本地服务器(stdio)在你电脑上跑的一个小程序,Codex 启动它、通过标准输入输出通信本地文件、本地知识库、本地工具
远程服务器(Streamable HTTP)跑在服务商那边的服务器,Codex 通过网址连接在线文档、云端知识库、SaaS 服务

Codex 是什么,现在长什么样

Codex 是 OpenAI 的编程助手,不是聊天框里的一个模型,而是一整套工具,共享同一个账号:

  • Codex CLI:终端里的命令行工具,开源项目(Apache-2.0 协议),在终端里跑 codex 就能开始干活,也能用 codex exec 跑自动化脚本。
  • IDE 扩展:VS Code、Cursor、Windsurf 里的侧边栏助手,JetBrains 和 Xcode 有各自的 Codex 集成,改代码时 diff 就在编辑器里看。
  • 桌面应用:在 ChatGPT 桌面应用里选 Codex,能读本地文件夹、跑终端、看 diff。
  • Codex Cloud:任务跑在 OpenAI 的云端电脑上,你的电脑关机它还在跑,还能做代码评审、在 GitHub 上回应 @codex review。

Codex 要花多少钱

Codex 包含在 ChatGPT 订阅里,不单独卖,按订阅档位给不同的使用范围(2026 年 11 月核实):

套餐价格Codex 使用范围
Free / Go0 美元 / 每月 8 美元桌面应用里的有限版本
Plus每月 20 美元网页端、CLI、IDE 扩展、iOS,云端代码评审等
Pro每月 100 / 200 / 500 美元Plus 的全部内容,用量更高

也可以不用订阅、用 API 密钥登录 CLI,按 token 计费,但那样没有云端功能(云端任务、代码评审、Slack 集成等)。对大多数人来说,Plus 是最划算的起点:每月 20 美元,CLI、IDE 扩展、云端功能都有。

用量按滚动的 5 小时窗口计算,不同模型、不同任务消耗的额度不一样,超过上限要等窗口重置,具体以官网最新说明为准。

接通 MCP 的 3 步:先跑通,再谈知识库

第 1 步:装好 Codex CLI,登录账号

如果你还没装 Codex,先装好再继续。下面是官方提供的安装方式,二选一:

# 方式一:npm 安装(需要 Node.js)
npm install -g @openai/codex
# 方式二:官方安装脚本(Mac / Linux,不需要装 Node.js)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows 用户在 PowerShell 里运行同一套官方脚本:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

装好后,在你的工程目录里运行:

codex

第一次启动会让你选择登录方式,选 Sign in with ChatGPT,在浏览器里完成登录。登录成功后,Codex 就能用你订阅里的额度干活了。

验证安装成功的方法:在终端里输入 codex --version,能看到版本号就是装好了;运行 codex,能正常打开对话界面就是登录成功了。

第 2 步:给 Codex 接第一个 MCP 服务器

Codex 的 MCP 配置只有一份文件,所有客户端共用:

  • 用户级配置:~/.codex/config.toml,对所有工程生效;
  • 工程级配置:工程目录下的 .codex/config.toml,只对这个工程生效,而且只在受信任的工程里加载。

注意一个最容易踩的坑:Codex 的配置文件是 TOML 格式,不是 JSON。从 Claude Code、Cursor 那边搬过来的 JSON 配置(mcpServers 对象)直接粘贴进来是无效的,必须改写成 TOML 的表格式。

接服务器有两种办法,效果一样,选顺手的一种:

办法 A:用命令添加(推荐新手)

接远程服务器(以 OpenAI 官方文档服务器为例):

codex mcp add openaiDocs --url https://developers.openai.com/mcp

接本地服务器(以文档查询服务器 Context7 为例):

codex mcp add context7 -- npx -y @upstash/context7-mcp

命令里的 -- 后面是启动本地服务器的命令;--url 后面是远程服务器的地址。执行后,Codex 会把配置写进 ~/.codex/config.toml。

办法 B:直接改配置文件

打开 ~/.codex/config.toml,按下面格式写:


# 远程服务器:通过网址连接
[mcp_servers.openaiDocs]
url = "https://developers.openai.com/mcp"

# 本地服务器:通过命令启动
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

关键点只有三个,错一个就接不上:

  1. 表名必须是 [mcp_servers.名字],带下划线的 mcp_servers,写成 mcpServers 或 mcp.servers 会被直接忽略,而且不报错;
  2. 远程服务器用 url,本地服务器用 command + args,不要混用;
  3. 改完配置文件要重启 Codex 才能生效。

第 3 步:验证服务器真的接上了

在 Codex 的对话界面里输入:

/mcp

能看到你刚加的服务器名字和状态,就是接上了。也可以在终端里运行:

codex mcp list

列出所有已配置的服务器。验证通过后,发一条真实任务试试,例如:

用 context7 查一下最新版 React 官方文档里关于 useEffect 的说明。

如果 Codex 能调用工具查到并回答,MCP 就正式跑通了。如果列表里没有你的服务器,按下面的排查顺序走:先确认配置文件是 TOML 格式、表名是 mcp_servers;再确认改完后重启了 Codex;工程级配置不生效时,先确认这个工程已被标记为受信任工程。

让 Codex 读懂本地工程:3 个做法

接通 MCP 只是第一步。让 Codex 真正读懂你的工程,靠的是下面三个做法,按顺序做。

做法 1:在工程根目录放一份 AGENTS.md

Codex 启动时会自动读取工程根目录下的 AGENTS.md,把它当作这个工程的说明书。在里面写清楚:

  • 这个工程是干什么的、技术栈是什么;
  • 常用命令:怎么安装依赖、怎么跑测试、怎么启动;
  • 代码规矩:命名风格、目录结构、哪些文件不要碰;
  • 遇到问题先查什么、改完要跑哪些检查。

写 AGENTS.md 的标准是:一个刚入职的程序员读完它,能不问人就上手改代码。写得越清楚,Codex 改得越准。

做法 2:把文档和知识库接成 MCP 服务器

本地工程靠 AGENTS.md,外部知识靠 MCP 服务器。常见的搭配:

  • 官方文档查询:接 Context7 这类文档服务器,Codex 查最新版官方文档不用你复制粘贴;
  • 团队知识库:如果你们的知识库服务商提供 MCP 服务器(远程 HTTP 类型),按服务商给的地址和认证方式接上,Codex 就能直接查团队文档;
  • 本地文件检索:本地有一批 Markdown 文档、笔记、规范文件时,用本地文件类的 MCP 服务器把它变成可查询的工具,Codex 不用你手动指定路径就能找到相关内容。

接知识库服务器时注意认证方式:需要 token 的远程服务器,不要把 token 明文写进配置文件。用环境变量存 token,配置里只写变量名,例如 bearer_token_env_var = "MY_API_KEY",再用 codex mcp login 名字 完成 OAuth 登录(如果服务器支持 OAuth)。密钥泄露比接不上更麻烦。

做法 3:给 Codex 划好沙箱边界

Codex 默认只能在你的工作区目录内写文件,默认不联网。这是保护你的安全设置,第一次用先别急着放开:

  • 让它先在工作区内跑任务,确认输出质量;
  • 需要联网查资料、跑外部命令时,再按任务需要逐项放开;
  • 不要在公开的、不受信任的环境里跑 Codex,也不要让它直接操作生产数据库。

沙箱边界的设置在配置文件里,改动前先想清楚这条命令如果跑错了、最坏的结果是什么。

费用明细

项目费用(2026 年 11 月核实)
Codex CLI 软件本身0 美元,开源免费
ChatGPT Plus(含 Codex 全部入口)每月 20 美元
ChatGPT Pro(含 Codex,用量更高)每月 100 / 200 / 500 美元
API 密钥方式(按量计费,无云端功能)按 token 计费,价格以 OpenAI 官方 API 定价页为准
MCP 协议本身0 美元,开放协议
Context7 等文档 MCP 服务器以各服务商官网定价为准,部分有免费额度

容易算错的点:Codex CLI 软件免费,不等于用 Codex 免费——额度来自你的 ChatGPT 订阅或 API 账单。MCP 服务器本身也可能收费,例如某些知识库服务的 MCP 接入要另外订阅,接之前先看服务商的定价页。

实操技巧

技巧 1:一个工程一个 AGENTS.md,不要共用

每个工程的规矩不一样,共用一份说明只会让 Codex 越改越乱。新工程先花 20 分钟写 AGENTS.md,后面每次任务都能省下反复纠正的时间。

技巧 2:先接一个服务器跑通,再批量加

第一次接 MCP,只接一个最常用的服务器,跑通验证后再加第二个。一口气加五六个,出问题时根本不知道是哪一个的配置错了。

技巧 3:密钥只放环境变量,不写进配置文件

配置文件可能会被提交进代码仓库、发给别人看。token、密钥、密码一律放环境变量,配置里只写变量名。codex mcp add 命令里用 --env 直接传值会把值明文写进配置文件,不要这样用。

技巧 4:工具越多,指令要越具体

接了 MCP 之后,Codex 手里的工具变多了,含糊的指令更容易让它用错工具。任务描述里写清楚“去哪里查、查什么、输出成什么样”,例如“用 context7 查 React 官方文档,把 useEffect 的清理函数用法整理成 5 条清单”,比“帮我看看 useEffect”准得多。

技巧 5:定期检查服务器列表,关掉不用的

用 codex mcp list 看一眼现在接了哪些服务器,不用的就用 codex mcp remove 名字 删掉。接的服务器越多,Codex 每次启动加载得越慢,工具选错的概率也越高。

常见问题 FAQ

MCP 是什么?和 API 有什么区别?

MCP 是一种开放协议,规定了 AI 应用怎么去发现和调用外部工具。API 是某个服务自己的接口,MCP 是让很多服务都能用同一种方式被 AI 接入的标准。接一个 MCP 服务器,Codex 就多了一套能直接调用的工具,不用你为每个服务单独写对接代码。

Codex 一定要付费才能用吗?

CLI 软件本身免费,但使用额度要来自 ChatGPT 订阅或 API 密钥。免费版和 Go 只能在桌面应用里有限使用 Codex,CLI、IDE 扩展和云端功能从 Plus(每月 20 美元)开始。

配置文件到底是哪个?格式是什么?

用户级是 ~/.codex/config.toml,工程级是工程目录下的 .codex/config.toml。格式是 TOML,不是 JSON。每个服务器写成一个 [mcp_servers.名字] 表,远程服务器用 url,本地服务器用 command + args。

为什么我加的服务器在列表里看不到?

最常见的三个原因:表名写错了(必须是 mcp_servers,带下划线);粘贴了 JSON 格式的配置;改完配置没有重启 Codex。工程级配置不生效时,检查工程是否被标记为受信任工程。

codex mcp-server 这个命令为什么不能用了?

这个命令是把 Codex 自己当作一个 MCP 服务器、让别的工具来驱动它,2026 年 9 月 5 日已被官方移除。现在的 codex mcp 命令只用来管理 Codex 要连接的服务器,方向别搞反了。

MCP 服务器安全吗?会不会泄露我的代码?

MCP 服务器能拿到你授权范围内的内容,所以只接你信任的来源:官方的、知名服务商的、开源可查的。不要接来路不明的服务器,密钥不要明文写进配置文件,敏感工程先用沙箱默认设置跑。

Codex 怎么知道我们团队的文档在哪?

两种办法:团队知识库如果提供 MCP 服务器,直接接上;如果知识库只是一批本地文档,用本地文件类 MCP 服务器把它变成可查询的工具,再在 AGENTS.md 里写清楚“查资料先去知识库”。

网页版里能用 MCP 吗?

网页版不读你本地的 config.toml 文件,它通过另外的插件机制使用 MCP 工具。本文讲的配置方法针对的是 Codex CLI、IDE 扩展和桌面应用,这三者共用同一份配置文件。

想把本地开发环境一次配到位,可以参考这篇:Claude 专用环境怎么配。如果你想在本地跑大模型做对比,这篇讲了本地部署的完整流程:DeepSeek V4 Flash 本地跑。免费的模型和 API 入口还有不少冷门选择,都在这篇里:免费 LLM API 的 5 个冷门入口。

觉得这篇硬核干货有帮助?
网络环境搭建 · 独立站搭建
⚠️ 免责声明

本站部分内容由网友投稿,转载仅为学习交流之目的,不代表 518 PORT 立场;版权归原作者所有。如有侵权、虚假或违法内容,请联系我们删除;本站不承担因转载内容产生的任何责任。