企业官网建设流程全解析

1. CodeX CLI 报 MCP server connection fails 的真实场景

你在终端敲下codex，想让它调用 filesystem 工具读一下项目里的配置文件，结果屏幕上直接甩出一行红字：Error: MCP server "filesystem" failed to connect，或者更让人摸不着头脑的Error: Tool not found: mcp__filesystem__read_file。这时候你打开~/.codex/mcp.json看了一遍又一遍，JSON 明明没写错，npx 也能跑，但 CodeX CLI 就是连不上 MCP server。这个场景在本地已经装好 Codex CLI、想接 MCP 工具链的开发者里非常高频，尤其是第一次从单机 CLI 往「CLI + 外部工具服务器」迁移的时候。

MCP 全称 Model Context Protocol，你可以把它理解成 CodeX CLI 和外部工具之间的一根「标准数据线」。CodeX 本身只会读写文件、跑 Bash，但通过 MCP，它可以挂载 filesystem、github、postgres 这些 server，把外部能力变成mcp__<server>__<tool>形式的工具。问题在于，这根数据线不是插上就通，它依赖三件事同时成立：MCP server 进程能起来、配置文件格式和路径正确、CodeX 启动时能完成 initialize 握手。任何一环断了，你看到的不是「工具不可用」，就是「连接被拒绝」。

我实测下来，connection refused和Tool not found这两个报错虽然长得不一样，但根因高度重叠。connection refused多半是 server 进程根本没跑起来，或者 socket 路径对不上；Tool not found则往往是 server 连上了，但工具列表没注册成功，或者 CodeX 读到的配置里 server 名字和调用时写的不一致。还有一种隐蔽情况：配置写对了，但 CodeX 启动时 MCP 初始化超时，日志里只留一句Server did not respond within 30000ms，工具列表直接为空。

这篇内容面向的就是这个排查路径。我会把 MCP endpoint 配置片段、auth.json字段示例、重启 CLI 的验证动作，以及 401、local proxy failed、reading choices、OAuth 这几类真实报错对照着讲清楚。你不需要先理解 MCP 协议的全部细节，只要跟着步骤把 server 拉起来、把配置写对、把工具列表确认加载成功，就能从「连接失败」走到「工具可用」。

需要先说明一个前提：CodeX CLI 连接 MCP server 时，如果 server 本身需要访问模型能力或远程 endpoint，建议把 Base URL 指向稳定的 API 入口。我这边用的是 TaoToken 的 API 地址https://taotoken.net/api，它兼容 OpenAI 风格的请求，配置在 MCP server 的 env 里或者 CodeX 的 auth 里都能跑通。官网入口是https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=，需要看文档的话从那里进就行。下面进入具体排查。

2. 接 MCP 前先把 TaoToken 的 Key 和 endpoint 准备好

在动 MCP 配置之前，先把「模型侧」的凭证准备好，否则你会在排查 MCP 连接时被 401 干扰，分不清到底是 server 没起来还是 Key 没设对。CodeX CLI 本身要调模型，MCP server 里如果带远程工具（比如 github、postgres 的托管版）也可能要鉴权，这两类凭证建议分开管理，但都走同一套 API 入口最省事。

第一步是拿 API Key。打开https://taotoken.net/api-keys，登录后创建一个 Key，复制出来形如sk-xxxxxxxx的字符串。这个 Key 不要直接写进会提交到 git 的配置文件里，建议放到环境变量或者~/.codex/auth.json这种本地文件。我试过把它写进 shell 的 rc 文件，配合export使用，重启终端后 CodeX 和 MCP server 都能读到。

第二步是确认 Base URL。TaoToken 的 API 根地址是https://taotoken.net/api，注意这里不加任何 UTM 参数，保持干净。CodeX CLI 的模型请求、以及部分 MCP server 内部发起的模型调用，都指向这个地址。如果你在 MCP server 的 env 里看到OPENAI_BASE_URL或API_BASE这类字段，填这个值就对了。

第三步是理解auth.json的作用。CodeX CLI 会把模型鉴权信息放在~/.codex/auth.json，MCP 的连接配置则放在~/.codex/mcp.json，两者是分开的。很多人排查 MCP 连接失败时只盯着mcp.json，结果发现是auth.json里的 Key 过期导致 CodeX 根本没启动完整，MCP 初始化自然也跟着失败。所以先把auth.json写对，再去看 MCP。

一个可用的auth.json字段示例如下，路径是~/.codex/auth.json：

{ "OPENAI_API_KEY": "sk-你的TaoTokenKey", "OPENAI_BASE_URL": "https://taotoken.net/api", "model": "gpt-4o" }

这里OPENAI_API_KEY填你在 API Keys 页面创建的那串，OPENAI_BASE_URL固定为https://taotoken.net/api，model按你实际要用的模型 ID 填。写完用python3 -m json.tool ~/.codex/auth.json验证一下格式，避免多一个逗号导致整个文件解析失败。这一步看起来简单，但我在排查时遇到过因为auth.json里混了注释导致 CodeX 静默降级、MCP 工具列表为空的情况，所以格式校验不能省。

如果你更习惯用环境变量，也可以在~/.zshrc或~/.bashrc里加：

export OPENAI_API_KEY="sk-你的TaoTokenKey" export OPENAI_BASE_URL="https://taotoken.net/api"

然后source ~/.zshrc让当前终端生效。环境变量的优先级通常高于auth.json，两者选一个即可，不要同时设成不同的值，否则排查时会互相覆盖，很难定位。

准备好 Key 和 endpoint 之后，再进入 MCP 配置环节。这样当你在第 5 节看到 401 报错时，就能明确知道是 Key 问题而不是 MCP server 问题，排查路径会清晰很多。需要看完整接入文档的话，从https://taotoken.net/doc进，里面有各语言和工具的配置示例。

3. 可复制的 MCP endpoint 配置片段与 auth.json 字段

这一节是整篇的核心，直接给你能复制粘贴的配置。CodeX CLI 的 MCP 配置默认读~/.codex/mcp.json，项目级配置可以放.codex/mcp.json，两者格式一致。下面这份配置同时挂了 filesystem 和 github 两个 server，你可以按需删减。

路径：~/.codex/mcp.json

{ "servers": { "filesystem": { "command": "/usr/local/bin/npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects" ], "env": { "OPENAI_API_KEY": "sk-你的TaoTokenKey", "OPENAI_BASE_URL": "https://taotoken.net/api" } }, "github": { "command": "/usr/local/bin/npx", "args": [ "-y", "@modelcontextprotocol/server-github" ], "env": { "GITHUB_TOKEN": "ghp_你的GitHubToken", "OPENAI_API_KEY": "sk-你的TaoTokenKey", "OPENAI_BASE_URL": "https://taotoken.net/api" } } }, "mcpTimeout": 60000 }

几个关键点必须说清楚。第一，command我写的是完整路径/usr/local/bin/npx，而不是裸npx。这是踩过的坑：CodeX CLI 启动 MCP server 时的 PATH 可能和你交互式 shell 不一样，裸npx会报command not found或者直接connection refused。用which npx查一下你的实际路径，替换掉。第二，filesystem server 的最后一个参数是允许访问的目录，写绝对路径，别写~，因为 server 进程不一定展开波浪号。第三，env里同时给了OPENAI_API_KEY和OPENAI_BASE_URL，这样即使 MCP server 内部要调模型，也走 TaoToken 的入口，不会因为找不到 Key 而初始化失败。

如果你用的是 TOML 风格的配置（部分 CodeX 版本或周边工具支持），等价写法如下：

[mcp.servers.filesystem] command = "/usr/local/bin/npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"] [mcp.servers.filesystem.env] OPENAI_API_KEY = "sk-你的TaoTokenKey" OPENAI_BASE_URL = "https://taotoken.net/api" [mcp.servers.github] command = "/usr/local/bin/npx" args = ["-y", "@modelcontextprotocol/server-github"] [mcp.servers.github.env] GITHUB_TOKEN = "ghp_你的GitHubToken" OPENAI_API_KEY = "sk-你的TaoTokenKey" OPENAI_BASE_URL = "https://taotoken.net/api" mcpTimeout = 60000

TOML 和 JSON 选一种就行，别两个文件都放，否则 CodeX 读哪个不确定，排查时会怀疑人生。写完配置后，务必用python3 -m json.tool ~/.codex/mcp.json或python3 -c "import tomllib; tomllib.load(open('/Users/yourname/.codex/config.toml','rb'))"验证格式。JSON 里最常见的错误是尾随逗号、中文引号、以及args数组里漏了逗号，这些都会让整个配置解析失败，表现就是 MCP 工具一个都不加载。

关于auth.json和mcp.json的分工，再强调一次：auth.json管 CodeX 自己调模型的凭证，mcp.json管 MCP server 的启动命令、参数和环境变量。两者里的OPENAI_API_KEY可以是同一个 Key，但作用域不同。如果你在 MCP server 里也需要模型能力，就把 Key 写进mcp.json的env；如果只是 CodeX 主进程用，写auth.json就够。三件套记牢：Base URL 是https://taotoken.net/api，Key 是sk-开头那串，Model ID 按你实际用的填，比如gpt-4o或claude-3-5-sonnet。

配置写完后不要急着跑复杂任务，先做第 4 节的验证请求，确认工具列表能加载出来，再进入实际使用。

4. 重启 CLI 并验证 MCP 工具列表加载成功

配置改完，第一件事是彻底重启 CodeX CLI。不是新开一个终端窗口就行，而是确保旧的 codex 进程已经退出。用ps aux | grep codex看一下，如果有残留进程，kill掉再启动。MCP 配置是在 CLI 启动时读取的，热更新基本不生效，所以每次改mcp.json都要重启。

重启后，先用 debug 模式看 MCP 加载日志：

codex --debug 2>&1 | tee /tmp/codex-debug.log

然后在另一个终端里 grep 关键信息：

grep -i "mcp\|server\|tool" /tmp/codex-debug.log

如果配置正确、server 能起来，你会看到类似MCP server "filesystem" connected和Loaded tools: mcp__filesystem__read_file, mcp__filesystem__write_file这样的行。这一步是判断「工具列表是否加载成功」最直接的证据。如果只看到MCP server "filesystem" failed to connect，就回到第 5 节对照报错排查。

接下来做一次手动连通性测试，不依赖 CodeX，直接和 MCP server 对话。以 filesystem 为例：

echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' | /usr/local/bin/npx -y @modelcontextprotocol/server-filesystem /Users/yourname/projects

如果 server 正常，会返回一段 JSON，包含result和serverInfo。这一步能排除「server 本身起不来」的问题。如果这里就报错，那 CodeX 连不上是必然的，先修 server。

手动测试通过后，回到 CodeX 里发一条会触发 MCP 工具的指令，比如：

codex "使用 filesystem 工具列出 /Users/yourname/projects 下的文件"

观察返回。如果工具列表加载成功，CodeX 会调用mcp__filesystem__list_directory之类的工具并返回文件列表。如果仍然报Tool not found，说明工具注册环节有问题，重点检查 server 名字是否和调用时一致，以及mcp.json里servers下的 key 是否拼写正确。

还有一个验证动作是查看已加载工具清单。部分 CodeX 版本支持：

codex --debug 2>&1 | grep "mcp__"

输出里应该能看到所有mcp__<server>__<tool>形式的工具名。如果这个列表是空的，但 server 显示 connected，那多半是 server 的 capabilities 没声明工具，或者协议版本不匹配。这时候检查 server 版本，必要时升级@modelcontextprotocol/server-filesystem到最新。

验证通过后，建议把这次成功的配置和日志留一份备份。MCP 生态更新快，下次升级 CodeX 或 server 后如果又出问题，有基线配置能快速对比。需要长期跑编码任务或 Agent 的话，可以考虑用 Coding Plan 把模型调用和工具链统一管理，入口在https://taotoken.net/coding-plan，配置方式和上面一致，只是额度和管理更集中。

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

这一节把排查过程中最常撞见的几类报错逐一对照。你不需要全部记住，遇到哪个查哪个。

401 Unauthorized。这个报错通常出现在 CodeX 主进程调模型时，或者 MCP server 内部发起模型请求时。根因是 Key 无效、过期，或者 Base URL 写错。检查~/.codex/auth.json里的OPENAI_API_KEY是否是sk-开头且没有多余空格，OPENAI_BASE_URL是否是https://taotoken.net/api。如果 Key 刚创建，确认没有复制漏字符。改完重启 CLI。注意 401 和 MCP 连接失败可能同时出现，先修 401，否则 MCP 初始化也会被拖累。

local proxy failed。这个报错一般和网络层有关，常见于 MCP server 尝试访问远程 endpoint 但本地代理配置干扰。检查你的 shell 里有没有设置HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这类环境变量，如果有，临时unset掉再试。MCP server 的 env 里也不要传代理相关字段。另外确认OPENAI_BASE_URL没有被错误地拼成带路径的形式，保持https://taotoken.net/api这个根地址。

reading choices 相关报错。这类报错通常出现在模型返回体解析阶段，比如error reading choices或invalid response format。根因可能是 Base URL 指向了一个不兼容 OpenAI 响应格式的 endpoint，或者模型 ID 写错导致返回了错误结构。确认model字段填的是实际可用的模型 ID，Base URL 用https://taotoken.net/api。如果 MCP server 内部也调模型，同样检查它的 env。

OAuth 相关报错。github MCP server 这类需要 OAuth 或 Token 的 server，如果GITHUB_TOKEN没设、设错、或者权限不足，会报 OAuth 失败或 403。检查mcp.json里 github server 的env.GITHUB_TOKEN是否是有效 token，scope 是否包含你要操作的内容。Token 不要写进会提交到仓库的文件，用环境变量或本地配置。

connection refused。回到第 3 节，检查command是否用了完整路径，server 进程是否能手动启动，socket 路径是否存在。ps aux | grep mcp看进程，手动跑一遍 npx 命令看报错。

Tool not found。server 连上了但工具没注册。检查mcp.json里 server 的 key 和调用时mcp__<server>__<tool>里的<server>是否一致，检查 server 版本是否支持你要的工具，用codex --debug 2>&1 | grep "mcp__"看实际加载了哪些工具。

timeout / Server did not respond within 30000ms。MCP server 启动慢，或者初始化卡住。在mcp.json里加"mcpTimeout": 60000，或者设环境变量export CODEX_MCP_TIMEOUT=60000。同时检查 server 是否有网络依赖导致启动慢，必要时换更轻量的 server。

排查顺序建议固定成：先python3 -m json.tool验证配置格式，再手动跑 npx 确认 server 能起，再codex --debug看加载日志，最后对照具体报错修。这个顺序能避免你在多个变量之间反复横跳。需要查 API 细节或重新生成 Key 的话，从https://taotoken.net/api-keys进；想看模型对话能力做对照测试，用https://taotoken.net/chat。

6. 把 MCP endpoint 改对之后，CodeX CLI 的工具链才算真正接上

回到最初那个报错：MCP server connection fails和Tool not found。走到这里你应该已经清楚，这两个报错不是玄学，而是三个可检查的环节——server 进程、配置格式与路径、工具注册与超时。把mcp.json里的command换成完整路径，把env里的OPENAI_API_KEY和OPENAI_BASE_URL补上，把mcpTimeout调到 60000，再用codex --debug 2>&1 | grep "mcp__"确认工具列表非空，基本就能从连接失败走到工具可用。

我自己的习惯是每次改完 MCP 配置，先跑一遍手动 initialize 测试，再重启 CLI 看 debug 日志，最后发一条会触发工具的最小指令。这三步走完，问题定位范围就缩得很小。MCP 生态还在快速迭代，server 版本、协议版本、CodeX 版本之间偶尔会有兼容性摩擦，遇到新报错时，优先看 debug 日志里的第一行错误，而不是最后一行。

如果你打算把 CodeX CLI 长期用在编码或 Agent 场景，建议把模型调用和工具链配置统一到一套凭证体系里，减少 Key 散落各处带来的排查成本。Coding Plan 的入口在https://taotoken.net/coding-plan，接入文档在https://taotoken.net/doc，API Keys 在https://taotoken.net/api-keys，模型对话测试在https://taotoken.net/chat。配置片段和字段示例这篇里都能直接复制，剩下的就是动手改一遍、重启、验证。