Codex + XCrawl MCP 使用指南
本文档介绍如何在 OpenAI Codex 中集成 XCrawl MCP Server,让 Codex 直接获得网页抓取、搜索、URL 发现和批量爬取能力。
前置准备
获取 XCrawl API Key
- 前往 dash.xcrawl.com 注册账号
- 注册后免费获得 1000 积分
- 在 dash.xcrawl.com/api-key 获取 API Key
环境要求
- 已安装 Codex CLI 或 Codex VS Code 扩展
- 如使用 stdio 方式:Node.js >= 18
- 如使用 HTTP 方式:Codex v0.44.0 或更高版本
方式一:CLI 命令添加
stdio 方式
codex mcp add xcrawl --env XCRAWL_API_KEY={YOUR_API_KEY} -- npx -y xcrawl-mcp注
选项(--env、--url 等)放在 -- 之前,-- 之后是传给 MCP 服务器的命令和参数。
HTTP 方式
需要 Codex v0.44.0 或更高版本。
codex mcp add xcrawl --url https://mcp.xcrawl.com/{YOUR_API_KEY}/mcp方式二:直接编辑 config.toml
配置文件位置:~/.codex/config.toml
stdio 方式
[mcp_servers.xcrawl]
command = "npx"
args = ["-y", "xcrawl-mcp"]
env = { "XCRAWL_API_KEY" = "{YOUR_API_KEY}" }
startup_timeout_sec = 30
tool_timeout_sec = 120HTTP 方式
需要 Codex v0.44.0 或更高版本。
[mcp_servers.xcrawl]
url = "https://mcp.xcrawl.com/{YOUR_API_KEY}/mcp"
startup_timeout_sec = 30
tool_timeout_sec = 120Codex VS Code 扩展
Codex VS Code 扩展自动读取 ~/.codex/config.toml,无需额外配置即可使用已配置的 XCrawl MCP 工具。
注
每个 MCP 服务器在 Codex 启动时初始化,配置过多服务器可能影响启动速度。
环境变量设置
方式 A:config.toml 中显式指定
[mcp_servers.xcrawl]
command = "npx"
args = ["-y", "xcrawl-mcp"]
env = { "XCRAWL_API_KEY" = "{YOUR_API_KEY}" }方式 B:启动前设置 shell 环境变量
export XCRAWL_API_KEY={YOUR_API_KEY}
codex此时 config.toml 中无需写 env 字段:
[mcp_servers.xcrawl]
command = "npx"
args = ["-y", "xcrawl-mcp"]验证配置
# 列出所有 MCP 服务器
codex mcp list
# 查看 xcrawl 详细配置
codex mcp get xcrawl管理命令
codex mcp list # 列出所有 MCP 服务器
codex mcp get xcrawl # 查看 xcrawl 配置详情
codex mcp remove xcrawl # 移除 xcrawl可用工具
配置完成后,Codex 可使用以下 7 个 XCrawl 工具:
| 工具 | 用途 |
|---|---|
xcrawl_scrape | 单页抓取,支持 markdown/html/json/截图输出 |
xcrawl_search | Google 搜索引擎,支持地区/语言/高级 SERP 参数 |
xcrawl_map | 站点 URL 发现,支持正则过滤、子域名 |
xcrawl_crawl | 批量爬取,支持深度和路径控制 |
xcrawl_key_status | 查询 API Key 有效性和积分余额 |
xcrawl_check_status | 查询异步抓取任务状态 |
xcrawl_check_crawl_status | 查询异步批量爬取任务状态 |
使用示例
# 单页抓取
使用 xcrawl_scrape 抓取 https://example.com,同步模式,返回 markdown 和链接
# 搜索
使用 xcrawl_search 搜索 "Codex MCP integration",美国英文,返回前 10 条
# URL 发现
使用 xcrawl_map 列出 https://docs.xcrawl.com 下 /doc/ 路径的 URL,上限 2000
# 批量爬取
使用 xcrawl_crawl 从 https://docs.xcrawl.com/doc/ 开始爬取,最大深度 2,上限 100 页,完成后轮询结果常见问题
| 问题 | 解决方案 |
|---|---|
spawn npx ENOENT | 安装 Node.js LTS,确保 npx 在 PATH 中,重启终端 |
| MCP 服务器不出现 | 检查 config.toml 语法,节名必须为 [mcp_servers.xcrawl] |
| HTTP 方式不工作 | 确认 Codex 版本 >= 0.44.0 |
| 启动缓慢 | 减少 config.toml 中不必要的 MCP 服务器 |
| 环境变量未生效 | 在 config.toml 使用 env = {} 显式指定 |
| 扩展启动后工具不可用 | 重启 VS Code 或重新加载窗口 |
| 401 Unauthorized | API Key 无效,在 dash.xcrawl.com 重新获取 |
| 积分不足 | 调用 xcrawl_key_status 检查,升级套餐 |
| 健康检查 | curl https://mcp.xcrawl.com/health 应返回 OK |
| Codex 静默 MCP 错误 | 先在 Claude Code 中验证 MCP 是否正常工作,再排查 Codex 配置 |
