以下是一套去除了项目和个人相关信息的通用版总结说明：

---

Codex 项目配置与 MCP 服务问题排查记录

一、背景

在使用 OpenAI Codex 进行项目开发时，需要为特定项目配置 MCP（Model Context Protocol）服务，以便 Codex 能够调用外部服务提供的功能（如知识库检索、数据处理等）。

相关路径：

• 全局配置目录：~/.codex/
• 项目目录：/path/to/your/project/
• 项目配置：/path/to/your/project/.codex/config.toml

---

二、现象

1. 项目配置未被加载

启动 Codex 时出现警告：

⚠ Project config.toml files are disabled in the following folders. Settings in those files are ignored, but skills and exec policies still load.
      1. /path/to/your/project/.codex
         To load config.toml, add /path/to/your/project as a trusted project in /Users/username/.codex/config.toml.

2. MCP 服务未生效

在项目的 .codex/config.toml 中配置了 MCP 服务器，但 Codex 无法识别或加载该服务。

3. 配置文件语法错误

尝试信任项目时，遇到配置格式错误：

Error loading config.toml:
/Users/username/.codex/config.toml:22:52: invalid type: boolean `true`, expected struct ProjectConfig
   |
22 | "/path/to/project" = true
   |                       ^^^^

---

三、问题原因

原因1：项目信任配置格式错误

Codex 的 [projects] 配置要求使用嵌套表格格式，而非简单的键值对。

错误写法	正确写法
"/path" = true 或 "/path" = {}	[projects."/path"] + trust_level = "trusted"

原因2：MCP 配置格式错误

Codex 的 MCP 配置中，HTTP 头部应使用 headers 键，而不是 http_headers。

错误写法	正确写法
http_headers = { Authorization = "Bearer ..." }	headers = { Authorization = "Bearer ..." }

原因3：codex trust 命令不存在

当前版本的 Codex CLI 没有 trust 子命令，信任项目必须通过编辑配置文件实现。

---

四、解决过程

步骤1：修正全局配置中的项目信任格式

修改前（错误）：

[projects]
"/path/to/project1" = {}
"/path/to/project2" = {}

修改后（正确）：

[projects]
[projects."/path/to/project1"]
trust_level = "trusted"

[projects."/path/to/project2"]
trust_level = "trusted"

步骤2：修正项目配置中的 MCP 服务格式

修改前（错误）：

[mcp_servers.service_name]
url = "http://localhost:8080/mcp/"
http_headers = { Authorization = "Bearer your_token_here" }

修改后（正确）：

[mcp_servers.service_name]
url = "http://localhost:8080/mcp/"
headers = { Authorization = "Bearer your_token_here" }

或使用嵌套表格格式：

[mcp_servers.service_name]
url = "http://localhost:8080/mcp/"

[mcp_servers.service_name.headers]
Authorization = "Bearer your_token_here"

步骤3：验证配置

# 查看全局配置
cat ~/.codex/config.toml | grep -A 5 "\[projects\]"

# 进入项目目录
cd /path/to/your/project

# 启动 Codex
codex

---

五、最终正确配置

全局配置：~/.codex/config.toml

approval_policy = "on-request"
sandbox_mode    = "workspace-write"

model = "gpt-5.2-codex"
model_provider = "azure"
model_reasoning_effort = "medium"

[execution]
keep_scripts = true
scripts_dir = "/workspace/debug_scripts"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://your-azure-endpoint.openai.azure.com/openai/v1"
env_key = "AZURE_API_KEY"
wire_api = "responses"

[notice.model_migrations]
"gpt-5.2-codex" = "gpt-5.3-codex"

[projects]
[projects."/path/to/project1"]
trust_level = "trusted"

[projects."/path/to/project2"]
trust_level = "trusted"

项目配置：/path/to/project/.codex/config.toml

approval_policy = "on-request"
sandbox_mode    = "workspace-write"

model = "gpt-5.2-codex"
model_provider = "azure"
model_reasoning_effort = "medium"

[execution]
keep_scripts = true
scripts_dir = "/workspace/debug_scripts"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://your-azure-endpoint.openai.azure.com/openai/v1"
env_key = "AZURE_API_KEY"
wire_api = "responses"

[features]
multi_agent = true

# MCP 服务器配置
[mcp_servers.service_name]
url = "http://localhost:8080/mcp/"
headers = { Authorization = "Bearer your_token_here" }

---

六、关键经验总结

问题	解决方案
项目配置未加载	在全局 [projects] 中使用 [projects."/path"] + trust_level = "trusted" 格式
MCP 头部配置无效	使用 headers = { ... } 或 [mcp_servers.xxx.headers] 嵌套表格格式
codex trust 命令不存在	手动编辑 ~/.codex/config.toml 完成信任配置
路径匹配问题	使用完整绝对路径，不要使用 ~ 或 $HOME

---

七、验证命令

# 检查 MCP 服务是否运行
lsof -i :8080

# 测试 MCP 端点连通性
curl http://localhost:8080/mcp/

# 进入项目并启动 Codex
cd /path/to/your/project
codex --debug

---

八、配置格式速查表

配置项	正确格式
项目信任	[projects."/绝对路径"] trust_level = "trusted"
MCP 服务	[mcp_servers.服务名] url = "http://..." headers = { Authorization = "Bearer token" }
嵌套表格头部	[mcp_servers.服务名.headers] Authorization = "Bearer token"

更新日期： 2026-03-31
适用范围： OpenAI Codex 项目配置与 MCP 服务集成