企业官网建设流程全解析

1. 为什么你的 Codex 明明装了 MCP 却调不动工具

很多人第一次接触 Codex 的工具生态，都会经历一个相似的困惑：配置文件里明明写了[mcp_servers.xxx]，codex mcp list也能看到 server，但真到对话里让它去查个 GitHub Issue、跑个测试、搜个最新文档，它却像没听见一样，要么直接凭记忆瞎答，要么回一句“我无法访问外部系统”。这不是模型笨，而是工具链路上某一环没打通。

Codex 的工具能力本质上是一套“模型判断 → 宿主校验 → 工具执行 → 结果回灌”的循环。模型只负责决定下一步该不该调工具、调哪个；真正能不能调、调得动调不动，取决于当前会话实际暴露的工具列表、沙箱与审批策略、MCP server 的连接状态、以及工具 schema 是否被正确注册。任何一层断了，表现都是“工具不生效”。

这篇是 Codex 系列第五篇，聚焦工具生态的落地配置。我会把 apply_patch、Web search、MCP 这几类最常用的能力拆开，给出可直接复制的配置片段，再配上逐项的验证动作，让你能确认每个工具在自己机器上到底有没有生效。适合正在用 Codex CLI 做本地开发、或者想把它接进自动化任务流的同学。读完你应该能独立判断：一个工具没反应，到底是没配、没连、没授权，还是被策略拦了。

先说清楚一个前提：工具名称和可用性会随版本、产品表面（CLI / IDE / 桌面端）和组织策略变化。所以下面所有配置都以“当前会话实际暴露的工具列表”为准，配置只是让工具“有可能出现”，最终能不能用还得看会话里认不认。

2. TaoToken 前置：把 Base URL、Key、Model ID 三件套备齐

在折腾工具之前，得先保证 Codex 本身能正常跑起来。如果你用的是自建或第三方兼容入口，核心就是三件套：Base URL、API Key、Model ID。这三样缺一个，后面所有工具配置都是空中楼阁。

我一般建议把接入信息统一走环境变量管理，别硬编码进配置文件。原因很简单：MCP 配置里经常要引用bearer_token_env_var，如果你连主模型的 Key 都写在明文 TOML 里，安全习惯就已经歪了。

以 TaoToken 为例，它的 API 入口是https://taotoken.net/api，官网在https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=。你需要先在控制台创建一个 API Key，然后把它写进环境变量：

export TAOTOKEN_API_KEY="sk-你的key"

如果你用的是 Codex CLI，接入配置通常落在~/.codex/config.toml。一个最小可用的模型接入片段大概长这样（字段名以你当前版本codex --help和配置参考为准）：

model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY"

这里env_key指向的就是上面那个环境变量，Codex 启动时会去读它，而不是把 Key 写死在文件里。Model ID 要填你实际能调用的模型名，别照抄，去控制台的模型列表里确认。

配完之后先做一次最基础的连通性验证，别急着上 MCP：

codex --version codex --help | head -40

确认版本和帮助信息能正常输出，说明 CLI 本身没问题。然后新建一个会话，随便问一句让它读当前目录的文件，看它能不能触发本地文件工具。这一步过了，才说明模型接入 + 基础工具链路是通的。

如果你更习惯用图形界面管理 Key 和额度，可以直接进控制台的 API Keys 页面创建和轮换；接入细节和字段说明看接入文档更稳妥。这两个入口分别是：

• API Keys：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

想先纯对话验证模型是否正常，可以用模型对话页面发一条测试消息：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=。如果那边能正常回，说明 Key 和模型没问题，问题就锁定在 Codex 的本地配置或工具层了。

3. 可复制配置：apply_patch、Web search、MCP 逐项落地

这一节是全文的核心，我会按“本地文件工具 → Hosted 工具 → MCP 外部工具”的顺序，把每一类的配置片段和启用方式写清楚。你可以按需取用，不用全上。

3.1 apply_patch 与本地文件工具

apply_patch 是 Codex 修改文件的主力工具，它接收一种专用的 Patch envelope，能新增、更新、删除、移动文件。它和标准git diff格式不一样，用的是自己的标记语法：

*** Begin Patch *** Update File: src/utils/parser.py @@ -return old_parse(value) +return new_parse(value) *** End Patch

常见操作标记有四种：*** Add File: <path>、*** Update File: <path>、*** Delete File: <path>、*** Move to: <new-path>（配合 Update 使用表示移动）。

apply_patch 本身通常不需要你手动在配置里“开启”，它是宿主默认暴露的本地工具之一。但它能不能改某个路径，取决于当前会话的文件系统权限和沙箱边界。所以真正要配的是沙箱和审批策略，而不是 apply_patch 本身。

一个相对克制的审批配置片段：

approval_policy = "on-request" approvals_reviewer = "user"

on-request的意思是：只读操作一般放行，涉及写入或高风险命令时按需请求审批。这样 apply_patch 在改文件前会走一次确认，你能看到 diff 再决定放不放。

验证 apply_patch 是否生效，最直接的办法是让它做一次小改动，然后自己看 diff：

git status git diff

如果 Codex 报告“已修改某文件”，而git diff里确实出现了对应改动，说明 apply_patch 链路是通的。反过来，如果它说改了但git diff是空的，那多半是改到了沙箱外的路径，或者根本没执行成功。

3.2 Web search 的四种模式

Web search 是 Hosted tool，运行在云端，和 Shell 命令的网络访问是两套独立配置。这点特别容易踩坑：有人以为 Shell 能联网，Web search 就自动能用，其实不是。

Web search 的配置项是web_search，有四个取值：

配置片段：

web_search = "cached"

如果你需要查最新文档、版本发布说明这类时效性强的内容，用live；日常问答用cached就够，省延迟。

验证方式：在会话里问一个明显需要联网的问题，比如“某个库最新版本新增了哪些 API”，然后观察它有没有触发搜索工具、返回里有没有可追溯的来源链接。如果它直接凭记忆答且没有来源，说明 Web search 没生效，回去检查web_search是不是disabled，或者当前产品表面是否支持。

3.3 MCP 配置：STDIO 与 Streamable HTTP

MCP 是 Codex 接外部系统的网关。配置统一写在用户级~/.codex/config.toml或项目级.codex/config.toml（项目级只在可信项目中加载）。

STDIO 类型（本地进程，通过标准输入输出通信）：

[mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] enabled = true required = false startup_timeout_sec = 20 tool_timeout_sec = 60 default_tools_approval_mode = "auto"

Streamable HTTP 类型（连远程地址）：

[mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN" enabled = true startup_timeout_sec = 10 tool_timeout_sec = 60

常用字段对照：

也可以用 CLI 直接加：

codex mcp add context7 -- npx -y @upstash/context7-mcp codex mcp add my-remote --url https://example.com/mcp --bearer-token-env-var MCP_TOKEN

注意bearer_token_env_var只写变量名，真正的 token 值放环境变量里，别写进 TOML、提示词或仓库。

3.4 审批模式与工具级覆盖

MCP server 级审批可以这样配：

[mcp_servers.github] default_tools_approval_mode = "writes" [mcp_servers.github.tools.search_code] approval_mode = "approve"

支持的值有auto、prompt、writes、approve。writes会对未标记为只读的工具请求审批；工具级approval_mode能覆盖 server 默认值。如果某个工具声明了 destructive 注解，即使它同时带只读提示，也需要审批——副作用判断以工具注解和 schema 为准。

4. 验证请求：确认每个工具真的生效

配置写完不代表生效，得逐项验证。我习惯按“可见性 → 连接 → 调用 → 结果”四步走。

第一步，看工具是否可见。在 TUI 里用：

/mcp /mcp verbose

/mcp列出当前注册的 server 和状态，/mcp verbose会展开工具 schema 和参数细节。如果某个 server 压根不在这，说明配置没被加载，检查文件路径和enabled。

第二步，看 server 连接状态：

codex mcp list codex mcp get context7

list看所有 server，get看单个 server 的详细配置。如果状态是 failed 或一直 connecting，多半是启动命令、cwd、环境变量或超时的问题。

第三步，实际调用一次。让 Codex 执行一个明确依赖该工具的任务，比如“用 context7 查一下某个库的用法”，然后观察它有没有生成结构化工具调用、返回里有没有 server 命名空间前缀的工具名。

第四步，看结果是否合理。工具返回可能是文本、结构化数据、图片或错误。如果返回的是错误，别急着重试，先看错误类型。

一个成功的验证长这样：你让它查 GitHub Issue，它先调用 GitHub MCP 的搜索工具，拿到结构化结果，再总结给你，并附上 Issue 编号和链接。整个过程你能在会话里看到工具调用记录，而不是它凭空编一段。

对于 apply_patch，验证就是前面说的看git diff；对于 Web search，验证就是看有没有来源链接。每个工具都有它自己的“成功信号”，认准信号再往下走。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

工具不生效时，报错信息往往比配置本身更有信息量。下面这几个是我见过频率最高的。

401 Unauthorized：最常见于 MCP 的远程 server 或主模型接入。先确认bearer_token_env_var指向的环境变量在当前 shell 里真的存在：

echo $FIGMA_OAUTH_TOKEN

如果为空，说明环境变量没导出，或者 Codex 启动的进程没继承到。注意环境变量要在启动 Codex 的那个 shell 里 export，别在另一个终端里设。

local proxy failed / connection refused：通常出现在 STDIO MCP server 启动失败，或者远程 URL 不可达。先手动跑一遍启动命令：

npx -y @upstash/context7-mcp

看它能不能正常起来。如果手动都起不来，Codex 里更起不来。远程 URL 的话，用 curl 探一下连通性。另外startup_timeout_sec太小也会导致启动被判失败，依赖下载慢的 server 适当调大。

reading choices / 解析响应失败：这类错误多半是工具返回的 schema 和 Codex 期望的不一致，或者返回体不是合法 JSON。对照 server 实现检查 required 字段和返回结构。如果是自己写的 MCP server，重点看inputSchema和实际返回是否匹配。

OAuth 未完成：远程 MCP 用 OAuth 认证时，需要先走登录流程：

codex mcp login <name>

如果没登录就直接调工具，会返回认证失败。登录完成后重启会话再试。

排查顺序建议按层来：工具是否可见 → server 是否配置正确 → 启动是否失败 → 认证是否完成 → 工具是否被过滤 → 是否被审批或策略阻止 → schema 是否一致。整体环境健康度可以用：

codex doctor

它会给出诊断报告，省得你一层层猜。

还有一个容易忽略的点：错误恢复要区分类型。“没有结果”是正常业务结果，不用重试；“工具故障”可以尝试恢复；“临时故障”（超时、网络抖动）可以安全重试；“权限或策略阻止”千万别重试，应该提示用户或调整权限；可能产生副作用的操作（创建 Issue、发消息、部署）不要盲目重试，避免重复执行。非幂等操作要么用稳定的请求标识，要么先查后重试。

6. 长期编码与 Agent 场景：把工具链固定下来

如果你只是偶尔用 Codex 改改代码，上面这些配完就够。但如果你打算把它当成长期的编码助手，甚至跑自动化 Agent 任务，那工具链的稳定性就很重要了。

我的做法是：把常用的 MCP server 配置固化在项目级.codex/config.toml里，配合enabled_tools和disabled_tools缩小工具面，只留当前任务真正需要的。工具定义和调用历史会占上下文，server 开太多，延迟和 token 消耗都会上去。

对于需要长时间跑的编码或 Agent 任务，用 Coding Plan 这类长期方案会比按次调用更划算，入口在：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=。它更适合那种“让 Agent 持续读项目、改多个模块、跑测试直到完成”的场景，而不是一问一答。

安全上守住几条底线：从最小权限开始，按任务增加写入或网络范围；只连可信 MCP server，核对命令、包来源、URL 和认证方式；密钥放环境变量，用bearer_token_env_var引用；假设工具参数、输出和错误都可能进会话记录，别在调用里塞无关秘密；对外部写操作使用明确授权和可验证结果。

最后提醒一句：工具名和可用性随版本、产品表面、配置和会话变化。判断 Codex 能不能完成某项任务，永远先看当前会话实际暴露的工具列表，而不是照搬任何一篇教程——包括这篇。配置是让工具“有可能出现”，会话里认不认，才是最终答案。