简体中文

English

简体中文

English

Codex + XCrawl MCP 使用指南

本文档介绍如何在 OpenAI Codex 中集成 XCrawl MCP Server，让 Codex 直接获得网页抓取、搜索、URL 发现和批量爬取能力。

前置准备

获取 XCrawl API Key

  1. 前往 dash.xcrawl.com 注册账号
  2. 注册后免费获得 1000 积分
  3. 在 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 = 120

HTTP 方式

需要 Codex v0.44.0 或更高版本。

[mcp_servers.xcrawl]
url = "https://mcp.xcrawl.com/{YOUR_API_KEY}/mcp"
startup_timeout_sec = 30
tool_timeout_sec = 120

Codex 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_searchGoogle 搜索引擎，支持地区/语言/高级 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 UnauthorizedAPI Key 无效，在 dash.xcrawl.com 重新获取
积分不足调用 xcrawl_key_status 检查，升级套餐
健康检查curl https://mcp.xcrawl.com/health 应返回 OK
Codex 静默 MCP 错误先在 Claude Code 中验证 MCP 是否正常工作，再排查 Codex 配置