跳转到正文
中文
获取 API 密钥
浏览文档

集成

Codex 接入指南

为 Codex 添加 Google 搜索及 YouTube 工具,用于开发与研究。

本页内容

开始前

请先安装并运行 Codex CLI。此托管 MCP 配置通过 OAuth 授予 Google 搜索、YouTube 搜索、元数据与转录权限。可在登录时创建 FlashData 账户。

1. 添加 MCP 服务

将此配置合并到 ~/.codex/config.toml(或 CODEX_HOME 下的 config.toml),保留所示的已注册客户端 ID 与回调 URL。

~/.codex/config.toml
[mcp_servers.flashdata]
url = "https://data.flashdata.dev/mcp"

[mcp_servers.flashdata.oauth]
client_id = "flashdata-codex"
callback_url = "http://127.0.0.1/callback"

2. 登录

运行登录命令。在浏览器中登录,或创建并验证账户,然后批准访问。等待终端确认登录完成;查询使用该账户的 Credits。

登录
codex mcp login flashdata --scopes mcp:research

免费检查连接

开启新的 Codex 会话,通过 /mcp 查看 flashdata。发送此提示,两次调用均应成功。余额为零也表示连接有效。

粘贴到智能体
使用 flashdata MCP 连接。
以 {} 调用 get_balance,以 {"source":"google_search","request_count":1} 调用 get_pricing。
报告可用 Credits 及预估价格,不要执行搜索。

3. 运行首个任务

将此提示发送给已连接的智能体。检查免费,单次搜索消耗 Credits。

首个任务提示
使用 flashdata MCP 服务,检查我的余额及一次 Google 搜索价格。
余额足够时,调用一次 google_search,query 为 "site:docs.python.org/3/library/venv.html create virtual environment",num 为 5,mode 为 "realtime"。
根据返回来源说明如何创建 Python 虚拟环境。
引用来源并报告实际消耗的 Credits,完成后停止。

预期结果

检查 google_search 工具调用是否完成(status: done),来源链接是否来自 results[].organic,回答是否基于这些来源。用量取自 usage.credits,不是结果条数。空结果应如实报告。

可以完成哪些任务

此 OAuth 连接提供研究工具。YouTube 下载通过 API 或 CLI 使用所有者 API Key 及目标存储。

任务MCP 工具
为回答或实现查找网页来源google_search
查找相关 YouTube 视频youtube_search
读取视频标题、频道及元数据youtube_metadata
获取视频转录,用于生成摘要youtube_transcript
检查可用 Credits 及请求费用get_balance · get_pricing

复用访问执行定时任务

使用相同的 Codex 配置、系统用户与凭据存储。在智能体宿主或现有调度器中创建计划,FlashData 提供数据工具。

验证已保存访问

在调度环境的新会话中执行此免费检查;两次调用均应成功,无需再次在浏览器登录。

复用检查
复用已有 flashdata MCP 连接。
以 {} 调用 get_balance,以 {"source":"google_search","request_count":1} 调用 get_pricing。
报告两次调用是否成功,不要搜索或创建新访问。

创建定时任务

在宿主调度器中选择时间及时区,例如每天 Asia/Shanghai 时区 09:00。将下方内容作为任务正文,在该环境先执行一次并检查保存的报告,再启用定时运行。

任务正文
复用已有 flashdata MCP 连接,使用 get_balance 和 get_pricing 检查一次 Google 搜索的余额及价格。
权限与余额足够时,调用一次 google_search,查询 "site:docs.python.org/3/library/venv.html create virtual environment",num 为 5,mode 为 "realtime"。
保存带日期的报告,包含来源 URL、摘要及实际消耗的 Credits。
访问被撤销或余额不足时停止,遵守 Retry-After。不要创建试用、申请新授权或重复结果不确定的请求。

凭据保存与刷新

Codex 将 OAuth 令牌保存在已配置的凭据存储中。不同系统用户、配置或执行环境可能需要单独授权连接。

宿主使用轮换刷新令牌刷新一小时有效的 OAuth 访问令牌。90 天授权过期或被撤销后需要重新连接。每个安装实例独立保存令牌,请勿在宿主间共享刷新令牌文件。

撤销或重连

  1. 暂停定时任务,然后在 FlashData 设置 → Connected apps 撤销对应 OAuth 连接。
  2. 要求智能体用已保存连接调用一次 get_balance;应返回认证失败或要求重连。检查期间不要批准新的登录。
  3. 用下方命令移除本地 OAuth 凭据。日后重连时,由所有者批准重复第 2 步,再执行免费连接检查。
移除已保存的 OAuth 凭据
codex mcp logout flashdata

更多配置方式

为 MCP 连接添加工作流技能,或选择 CLI 访问、本地 MCP 服务。

添加 MCP 技能

flashdata-mcp 技能指导智能体使用已连接的工具,复用上方连接。

在项目目录运行。选择 FlashData 原生 CLI v1.2.1,或需要 Node.js 22.20+ 及 npm 的技能安装器。开启新 Codex 会话,要求使用 flashdata-mcp。

在项目中运行
flashdata skills install --agent codex --skill flashdata-mcp
flashdata skills verify --agent codex --skill flashdata-mcp

使用 CLI 技能或开始试用

安装 FlashData CLI v1.2.1,在项目目录运行,并选择一种访问方式。示例使用默认 CLI 配置档,独立于 MCP OAuth;若已有自定义 --profile 和 --state-dir,请在所有命令中保持一致。

Setup 将 CLI 技能安装到 .agents/skills。安装后开启新 Codex 会话,要求使用 google-search。

在隐藏提示中粘贴具有 google_search 权限的密钥。无人值守导入时,从密钥管理器通过管道传给 auth login --api-key-stdin --non-interactive。

1. 导入并验证密钥
flashdata auth login
flashdata setup --agent codex --skip-auth --non-interactive
flashdata auth status --json --non-interactive
2. 检查余额及费用,不执行搜索
flashdata account balance --json --non-interactive
flashdata search "site:docs.python.org/3/library/venv.html create virtual environment" --num 5 --dry-run --json --non-interactive

# 仅在 accessVerified 和 estimateAvailable 均为 true,
# 具有 google_search 权限,且 availableCredits 足以支付 estimatedCredits 时继续。
3. 执行一次 → ./codex-first-search.json
flashdata search "site:docs.python.org/3/library/venv.html create virtual environment" --num 5 --run-id codex-first-search-001 --output codex-first-search.json --json --non-interactive

# 读取保存的文件:status、results[].organic、usage.credits。
# 终端 JSON 报告输出路径;保留运行 ID 以便恢复。

通过 API Key 运行本地 MCP

需要 Node.js 22.18+、npm 及具有 google_search 权限的 API Key 来完成首个任务。此方式运行 @flashdata-dev/mcp 0.2.0,不读取 FlashData CLI 保存的密钥或 MCP OAuth 令牌。

在终端设置密钥,将此前完整的 flashdata 配置(含 OAuth 子配置)替换为下方内容,然后从该终端启动 Codex。智能体可使用已注入的环境变量,无需隐藏输入提示。

配置完成后,在新智能体会话中运行上方免费连接检查提示。两项检查通过后,再使用首个任务提示。API Key 访问无需 mcp login。

1. 设置密钥,不输出密钥内容
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
2. 替换 ~/.codex/config.toml 中的条目
[mcp_servers.flashdata]
command = "npx"
args = ["--yes", "--package=@flashdata-dev/[email protected]", "flashdata-mcp"]
env_vars = ["FLASHDATA_API_KEY"]
3. 在此终端开启新会话
codex

故障排查

问题处理方式
没有 FlashData 工具运行 codex mcp list,再在新会话运行 /mcp。检查配置文件并完成登录。
技能缺失检查当前项目的 .agents/skills。原生 MCP 技能安装可运行 flashdata skills verify --agent codex --skill flashdata-mcp,再重启会话。
invalid_client / callback逐项核对第 1 步,在可访问发起宿主回调的浏览器中完成授权。
401检查连接或密钥是否已撤销、过期。OAuth 由所有者批准重新登录;CLI 运行 flashdata auth status。充值不能修复认证。
403检查所请求来源的权限。研究 OAuth 不包含 YouTube 下载,下载须使用 API Key 配置。修复权限后再试。
402通过 get_balance 或 flashdata account balance 检查余额。在 Billing 增加 Credits 或停止任务;重新登录不会增加额度。
429遵守 Retry-After 并降低并发。保留当前配置档及注册凭据,不要创建替代试用。
本地 MCP 无法读取密钥在宿主进程启动环境设置 FLASHDATA_API_KEY 并重启。flashdata auth login 保存的密钥不会自动导出给本地 MCP。
CLI 输出文件已存在读取 ./codex-first-search.json。若需再次导出已保存的成功结果,在原配置档执行 flashdata runs show codex-first-search-001 --result --output codex-first-search-copy.json。仅在有意执行新搜索时使用新的运行 ID。
定时任务失败在该环境执行免费复用检查,核对系统用户、宿主配置、凭据存储和工具权限。
超时或结果不确定保留请求或任务 ID,再次提交前检查历史。对返回的续读 ID 使用 get_result。

OAuth 验证记录

2026-10-21 在 Windows 上使用 Codex 0.163.0-alpha.10.2 验证了 OAuth 登录、回调、凭据保存、免费价格查询、刷新和撤销。该次验证不包含付费查询或定时执行。配置指引于 2026-11-05 对照宿主文档复核。