前言
OpenAI Codex 是轻量终端代码智能体，而 MCP（Model Context Protocol，模型上下文协议）是标准化扩展接口规范，二者搭配可以让代码智能体调用本地进程、云端远程服务、文档检索、浏览器控制等各类外部工具。本文基于 OpenAI 官方文档，完整覆盖 Codex CLI 安装账号认证、两类 MCP 服务（本地 stdio 进程、远程 HTTP 流式服务）配置、密钥环境变量安全传递、工具白名单与审批管控、排错调试全流程，附带可直接复制的 TOML 配置模板，同时补充生产环境落地规范。企业多模型调度场景可借助 Treerouter 统一管理各类 LLM 与 MCP 服务接入流量。
一、基础概念：Codex 与 MCP 分别承担什么职责
- Codex：执行主体，终端运行的轻量编码 Agent，负责理解开发需求、代码生成、执行 Shell、调用外部工具、输出完整工程方案；支持本地文件读写、多轮长上下文对话。
- MCP：标准化扩展中间层，分为 stdio 本地进程、streamable HTTP 远程两种传输模式。开发者搭建 MCP 服务后，Codex 通过读取
~/.codex/config.toml识别服务，在对话里直接调用服务暴露的全部工具。 二者协作逻辑：MCP 统一封装外部能力，Codex 作为上层智能体统一消费，不用为每一类工具单独适配自定义接口。
二、第一步：安装并完成 Codex 账号认证
1. 三种官方安装方式（任选其一）
# 方式1：官方一键脚本（macOS / Linux 通用）
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# 方式2：npm 全局安装
npm install -g @openai/codex
# 方式3：Homebrew（仅 macOS）
brew install --cask codex
安装完成后终端执行 codex，会弹出登录引导：
- 方案A：网页登录 ChatGPT 账号，支持 Plus、商业版、企业版、教育版；
- 方案B：API Key 直连模式，需在配置文件单独写入密钥。
三、MCP 配置文件规则：全局/项目双作用域
Codex 所有 MCP 服务配置统一存放于 TOML 文件，分两层作用域，优先级项目级 > 全局：
| 作用域 | 文件路径 | 生效范围 |
|---|---|---|
| 全局 | ~/.codex/config.toml |
本机全部代码项目 |
| 项目级 | ./.codex/config.toml |
仅当前项目，隔离私有工具、权限 |
新增 MCP 服务两种写法：
- 命令行
codex mcp add：快速新增，适合本地 stdio 简单服务； - 手动编辑 TOML：精细化管控工具白名单、超时、审批策略、环境变量，生产环境推荐。
四、第二步：接入本地 stdio 类型 MCP 服务（以 Context7 文档检索为例）
本地 MCP 以子进程形式运行，通过标准输入输出和 Codex 通信，最常用在本地文档、本地脚本工具场景。
方式A：命令行快速添加
# 语法：codex mcp add [服务名] --env 环境变量 -- 启动命令
codex mcp add context7 -- npx -y @upstash/context7-mcp
# 查看全部已加载 MCP
codex mcp --help
方式B：手写完整 TOML 配置（推荐精细化管控）
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
# 独立传递环境变量
env_vars = [
{ name = "MY_ENV_VAR", source = "local" }
]
stdio 服务核心字段说明
| 字段 | 是否必填 | 说明 |
|---|---|---|
| command | ✅ 必填 | 启动本地进程的主命令 |
| args | ❌ 可选 | 命令后置参数数组 |
| env_vars | ❌ 可选 | 从本地/远端读取的环境变量，用于传递密钥 |
| cwd | ❌ 可选 | 进程启动工作目录 |
五、第三步：接入远程 HTTP 流式 MCP 服务（云端托管服务）
云端托管的 MCP（设计工具、云端数据库、在线检索服务）采用 streamable HTTP 传输，通过 url 指向远程接口地址，示例 Figma MCP 配置：
[mcp_servers.figma]
url = "https://api.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH"
http_headers = { "X-Figma-Region" = "us-east-1" }
HTTP 远程服务核心字段
url（必填）：MCP 服务远程接口地址；bearer_token_env_var：存放鉴权 Token 的环境变量名，密钥不硬编码写入配置；http_headers：静态固定请求头；env_http_headers：从环境变量动态读取的请求头。 OAuth 类远程服务可执行codex mcp login [服务名]完成交互式授权。
六、安全规范：密钥与环境变量传递
MCP 服务所需 API Key、Token 严禁直接写死在 config.toml，统一通过环境变量中转：
- 本地 stdio 服务：依靠
env_vars读取系统本地环境变量； - 远程 HTTP 服务：使用
bearer_token_env_var指定密钥环境变量，Codex 发起请求时自动带入 Authorization 请求头； 配置文件可完整提交代码仓库，不会泄露凭证。
七、进阶管控：工具白名单、禁用列表与三层审批模式
单个 MCP 服务会暴露大量工具，可精细化限制可用工具，并设置人工确认规则，stdio、HTTP 服务通用配置字段：
[mcp_servers.chrome_devtools]
enabled = true
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled_tools = ["screenshot", "inspect"]
disabled_tools = ["process", "write_file"]
approval_mode = "prompt"
三层审批模式说明
auto：自动执行，无需人工确认，适合只读无风险工具；prompt：每次调用弹窗确认，最安全，适合文件修改、系统执行等高风险操作；approve：批量统一授权，一次性放行多次调用。
配套管控参数：
startup_timeout_sec：服务启动超时，默认10秒，远程服务建议调至20；tool_timeout_sec：单次工具调用超时；enabled_tools：工具白名单，仅列表内工具可调用；disabled_tools：工具黑名单，屏蔽指定高危操作。
八、第四步：查看、校验与调试 MCP 服务
1. 查看当前已加载服务
在 Codex 交互式 TUI 界面输入斜杠指令：
/mcp
会列出全部正常运行的 MCP 服务、可用工具、审批模式。
2. 服务启动失败排错三步
- 校验
command/url路径地址是否正确； - 核对密钥类环境变量是否正常导出；
- 延长
startup_timeout_sec超时时间，网络较差远程服务建议20秒。
九、高频FAQ
Q1：全局配置和项目级配置有什么区别？
全局 ~/.codex/config.toml 所有项目共享；项目级 ./.codex/config.toml 仅作用当前仓库，适合存放项目私有工具、内部服务，不会污染全局环境。
Q2：codex mcp add 命令行和手写 TOML 怎么选？
命令行适合快速搭建简单本地 stdio 服务；手写 TOML 可精细控制工具黑白名单、超时、审批策略、多组环境变量，生产环境推荐手写。
Q3：stdio 和 HTTP 两种传输模式怎么选？
- stdio：本地脚本、本地工具，启动独立子进程，无网络依赖；
- HTTP：云端托管、第三方在线平台，通过公网接口调用，适合跨机器远程服务。
Q4：如何安全传递 API Key 不泄露？
不写入 TOML 明文，本地服务用 env_vars、远程 HTTP 用 bearer_token_env_var，全部从系统环境变量读取。
Q5：MCP 服务加载失败如何排查？
依次检查四点：启动命令/远程地址、密钥环境变量、启动超时时长、工具黑白名单是否屏蔽核心能力。
十、完整落地总结
整套 Codex + MCP 落地流程可概括为四步：安装认证 Codex CLI → 在 config.toml 声明 stdio/HTTP 两类 MCP 服务 → 通过环境变量安全传递密钥 → 配置工具白名单与审批策略，最后通过 /mcp 指令校验可用性。
MCP 标准化接口消除了各类外部工具的适配成本，开发者可以统一一套配置规范对接本地脚本、云端检索、设计平台、数据库等能力。如果团队同时维护多套大模型与 MCP 服务集群，可借助 Treerouter 统一收拢接口流量，简化多服务权限观测与调度。
本文全部配置逻辑基于 OpenAI Codex 官方文档，配置字段会随版本迭代微调，生产环境落地前建议同步查阅官方最新手册。全文完整覆盖本地进程、远程云端两类 MCP 场景，配套可直接复制的 TOML 模板与 Shell 命令，无需额外改造即可投入开发使用。
