如何在 Codex 中运行 Apify Actor 并按需选择同步或异步方式获取数据集
【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills
本文章解决一个具体的集成任务：把 awesome-codex-skills 仓库中的apify-automation技能接入 Codex，通过 Composio MCP 网关调用 Apify 工具，运行一个 Actor 爬虫并把它的结构化数据取回来。运行方式有两套：同步调用（一次调用直接拿到数据集条目）和异步调用（先触发运行，稍后用datasetId轮询取数），选哪一套取决于你的爬虫跑多久。前提是 Codex 已安装、拥有 Composio 账号可用的 MCP 服务地址，以及一个可授权的 Apify 账号。
准备条件与技能安装
先确认三件事都在文档要求范围内：
- MCP 服务端：
apify-automation技能的 frontmatter 声明requires.mcp: rube，即必须先把 Composio MCP server 加入配置，文档给出的服务端点是https://rube.app/mcp。 - Apify 账号授权：配置 MCP 后按提示连接 Apify 账号，agent 会提供一个认证链接完成授权。
- 技能本身已装入 Codex：Codex 的技能存放在
$CODEX_HOME/skills（默认~/.codex/skills），每个技能是一个含SKILL.md的目录，且SKILL.md需要带name和descriptionfrontmatter。
技能安装二选一：
- 手动安装：把仓库中的
composio-skills/apify-automation/目录整体复制到$CODEX_HOME/skills/下，重启 Codex 使其重新加载元数据。 - 安装脚本：在 awesome-codex-skills 仓库中运行（README Quickstart 给出的入口，路径参数指向本技能）：
python skill-installer/scripts/install-skill-from-github.py \ --repo ComposioHQ/awesome-codex-skills \ --path composio-skills/apify-automation安装后按 README「Using Skills in Codex」一节验证：
ls ~/.codex/skills head ~/.codex/skills/apify-automation/SKILL.md能看到目录、且 frontmatter 中description写明"Automate web scraping and data extraction with Apify"即安装成功。注意：技能装好只代表 Codex 知道如何调度这些工具，真正发起调用还需要上面第 1、2 条的 MCP 与 Apify 授权就绪。
在 Codex 会话中描述抓取任务（或直接提及技能名）即可触发该技能；技能文档中的示例提示词如"Run the Google Places scraper for 'restaurants in New York' and return the first 50 results"就是会话里可以直接说的话（文档示例）。
运行前先核对 Actor 的输入结构
每个 Actor 的输入字段名各不相同，技能文档的 Known Pitfalls 明确警告：通用字段名如queries、search_terms会被拒绝，必须先查该 Actor 的确切 schema（文档举例：Google Maps 用searchStringsArray，web scraper 用startUrls）。在运行前用：
- 工具：
APIFY_GET_ACTOR - 参数：
actorId（必填）——格式为username/actor-name，也可以是 hex ID
文档示例提示词："Show me the details and input schema for the apify/web-scraper Actor"。
两条硬性输入规则，构造input/body时必须遵守：
- URL 必须带完整协议（
https://或http://），且很多 Actor 要求 URL 以对象形式传入，形如：
{"startUrls": [{"url": "https://example.com"}]}- 枚举值用小写：多数 Actor 期望
relevance而不是RELEVANCE、all而不是ALL。
同步方式：一次调用跑完并取回数据集
适合较快的抓取任务。用：
- 工具：
APIFY_RUN_ACTOR_SYNC_GET_DATASET_ITEMS——执行 Actor 并在同一次调用中立即返回数据集条目。
关键参数（来自技能文档）：
| 参数 | 说明 |
|---|---|
actorId（必填） | Actor ID，格式username/actor-name，例如compass/crawler-google-places |
input | 匹配该 Actor schema 的 JSON 输入对象，字段名以 Actor 页面文档为准 |
limit | 最多返回条目数 |
offset | 跳过的条目数，用于分页 |
format | json（默认）、csv、jsonl、html、xlsx、xml |
timeout | 运行超时（秒） |
waitForFinish | 最大等待时间，0–300 秒 |
fields | 只返回指定字段，逗号分隔 |
omit | 排除指定字段，逗号分隔 |
边界限制：waitForFinish上限 300 秒（文档 Known Pitfalls 中称为 "Sync timeout at 5 minutes"）。如果你的 Actor 可能超过 5 分钟还没跑完，同步方式不适用，应改用下面一节的异步方式。
异步方式：触发长任务后轮询数据集
适合长时间运行的抓取任务。分两步：
第一步，触发运行：
- 工具：
APIFY_RUN_ACTOR——不等待完成，触发后立即返回。
关键参数：
| 参数 | 说明 |
|---|---|
actorId（必填） | Actor slug 或 ID |
body | 传给 Actor 的 JSON 输入对象 |
memory | 内存限制（MB），必须是 2 的幂，最小 128 |
timeout | 运行超时（秒） |
maxItems | 返回条目上限 |
build | 指定构建标签，例如latest、beta |
文档示例提示词："Start the web scraper Actor for example.com asynchronously with 1024MB memory"。
第二步，用运行返回的datasetId取回数据：
- 工具：
APIFY_GET_DATASET_ITEMS——按分页、字段选择和过滤条件拉取指定数据集。
关键参数：
| 参数 | 说明 |
|---|---|
datasetId（必填） | 数据集标识符，取自异步运行的返回结果 |
limit | 每页条目数，默认最大 1000 |
offset | 分页偏移，默认 0 |
format | json（文档标注 recommended）、csv、xlsx |
fields/omit | 只包含 / 排除指定字段 |
clean | 移除 Apify 专有元数据 |
desc | 反序排列（最新在前） |
大 dataset 不能一次取完：APIFY_GET_DATASET_ITEMS单次limit上限 1000，文档给出的做法是循环递增offset收集全部条目。文档示例提示词："Get the first 500 items from dataset myDatasetId in JSON format"。
同步还是异步：按运行时长判断
文档对两条路径的定位是明确的：
- 同步调用标注为 "Best for quick scraping jobs"，前提是任务能在
waitForFinish的 300 秒窗口内完成； - 异步调用标注为 "Use for long-running scraping jobs"，触发后轮询
APIFY_GET_DATASET_ITEMS取数。
也就是说，判断依据只有一个可核对的事实：你的 Actor 典型运行时长是否可能超过 5 分钟。超过就用APIFY_RUN_ACTOR+APIFY_GET_DATASET_ITEMS的两步流程；没有超过则同步调用省一步。格式选择上，文档建议下游自动化处理优先用 JSON（"the most reliable for automated processing"），CSV/XLSX 虽然可用但不建议用于自动化管道。
结果验证与运行排查
取到数据后，或怀疑运行出问题时，用文档「Manage Runs and Datasets」一节的工具核对：
APIFY_GET_LIST_OF_RUNS——列出某 Actor 的运行记录，可按 Actor 和状态过滤；从运行详情中取得datasetId用于取数。APIFY_DATASET_GET——查看指定 dataset 的元数据（如条目数量），可用来确认数据集是否已写入、条目量是否符合预期。APIFY_DATASETS_GET——分页列出账号下所有 dataset。APIFY_GET_LOG——拉取某次 run 或 build 的执行日志，用于调试失败原因。
文档示例提示词："List the last 10 runs for the web scraper Actor and show logs for the most recent one"。如果APIFY_DATASET_GET显示的条目数为 0，而运行状态正常结束，先查该次 run 的日志（APIFY_GET_LOG）再检查输入字段名是否与该 Actor 的 schema 一致。
限制与提醒
- 数据量成本：文档指出大 dataset 拉取可能带来费用与超时、内存压力，建议用适中的
limit和增量处理，而不是一次性拉全量。 - 输入 schema 是每个 Actor 独立的，换 Actor 时必须重新核对字段名，不能复用上一个 Actor 的字段。
composio-skills/apify-automation/SKILL.md的 Quick Reference 表还列有APIFY_RUN_ACTOR_SYNC（同步运行并返回 output record）和APIFY_CREATE_TASK（创建可复用的预设任务）等工具；如果后续要把同一套抓取参数做成周期性任务，可在文档中查阅APIFY_CREATE_TASK与APIFY_GET_TASK_INPUT。
【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
