codex 中 skill 调用外部工具需通过 mcp 协议，依赖 skill.md 声明 allowed-tools、mcp 服务启动及 registry.json 注册；必须确保 mcp 进程持续运行，否则静默失败；调用后需验证日志与文件系统真实产出。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在 Codex 中让 Skill 调用外部工具，核心是通过 MCP（Model Control Protocol）打通本地或远程服务，而非直接执行命令行或调用 API。这一步必须明确：Codex 本身不运行脚本，它依赖 SKILL.md 中声明的工具权限 + MCP 服务注册来触发真实动作。
确认 MCP 服务已启用并注册
打开终端，运行 codex mcp list。若返回空或报错 “MCP server not running”，说明服务未启动。此时需先执行 codex mcp start 启动本地 MCP 代理进程。
【必须确保 MCP 进程持续运行】——一旦关闭终端或杀掉该进程，所有依赖 MCP 的 Skill 将无法调用外部工具，且不会报错，只会静默失败。
启动后，检查 ~/.codex/mcp/registry.json（macOS/Linux）或 %USERPROFILE%\.codex\mcp\registry.json（Windows）是否存在有效条目。这是 Codex 发现可用工具的唯一依据。
在 SKILL.md 中声明可调用工具
打开你的 Skill 文件夹，编辑 SKILL.md，在 YAML frontmatter 区域添加 allowed-tools 字段：
```yaml
name: pdf-to-excel
description: 提取 PDF 表格并保存为 Excel
allowed-tools:
- mcp://pdf_extractor
- mcp://excel_writer
```
注意：这里的工具名必须与 registry.json 中注册的 tool_id 完全一致，大小写敏感，多一个空格都会导致拒绝调用。
如果漏写 allowed-tools，Codex 在执行时会跳过工具调用步骤，直接走纯模型推理路径——这意味着你写的“提取表格”指令只会生成一段虚构的 Excel 内容，而非真实文件。
编写 Skill 内部调用逻辑
方法一：使用 MCP 工具调用语法（推荐）
在 SKILL.md 的主描述中，用自然语言明确写出工具调用意图，例如：
“请调用 mcp://pdf_extractor 解析用户提供的 PDF 文件，输出结构化表格数据；再将结果传给 mcp://excel_writer，保存为 output.xlsx。”
方法二：嵌入脚本调用（需 Skill 自带 scripts/ 目录）
在 scripts/extract_and_save.py 中写 Python 代码，开头必须包含：
```python
from mcp.client import get_client
client = get_client()
result = client.call_tool("mcp://pdf_extractor", {"file_path": "/path/to/input.pdf"})
```
此方式要求 Skill 的 SKILL.md 中同时声明 requires-python: true，且本地已安装对应 Python 环境。否则脚本加载失败，整个 Skill 会退化为纯文本响应。
验证外部工具是否真正生效
第一步：在 Codex 对话框中输入 $skill test-pdf-skill（假设 skill 名为 test-pdf-skill）。
第二步：观察终端日志——当 Skill 触发 MCP 调用时，MCP server 进程会打印类似 [INFO] Calling tool mcp://pdf_extractor with args {...} 的日志行。
第三步：检查目标工具是否完成实际动作。比如 mcp://pdf_extractor 应生成临时 CSV 文件，mcp://excel_writer 应在指定路径写出 .xlsx。不要只看 Codex 回复文字，【回复成功 ≠ 工具执行成功】，必须核对文件系统侧的真实产出。
