Meta Ads Control
Use this skill for Meta Marketing API work. Prefer the bundled script because it gives structured JSON output, dry-run protection, retries, pagination, batch support, async Insights jobs, targeting search, and asset upload.
Before you touch spend or delivery
- 1. Discover scope.
python3 scripts/meta_ads.py accounts
python3 scripts/meta_ads.py account
- 2. Confirm the intended ad account, currency, timezone, and writable objects.
- For any change that can spend money, change delivery, or alter tracking:
- prepare a short plan,
- run
--dry-run,
- show the exact objects and fields to be changed,
- wait for explicit user approval,
- then rerun with
--confirm.
- 4. Default new campaigns, ad sets, and ads to
PAUSED unless the user explicitly asks to go live immediately. - After any write, do a read-after-write verification with
get, list, or request GET.
Authentication and environment
The script reads:
- -
META_ACCESS_TOKEN — required for live API calls - INLINECODE7 — optional default account, with or without INLINECODE8
- INLINECODE9 — defaults to INLINECODE10
- INLINECODE11 — defaults to INLINECODE12
If META_ACCESS_TOKEN is missing, help the user set it up first instead of guessing or fabricating API responses.
OpenClaw users can inject these values through skill config. See OpenClaw notes.
Fast path by task
1) Audit or diagnose an account
Start with the smallest read that answers the question.
CODEBLOCK1
Use batch when you need several small reads at once. Use minimal field sets first.
2) Performance reporting
Use insights. Start with a narrow level and date window. For large windows, many fields, or breakdowns, use --async.
CODEBLOCK2
If the user asks for conversions or ROAS, include actions and action_values. If the user asks for demographic or placement splits, use --breakdowns. If they ask for action-level splits, include actions and use --action-breakdowns.
3) Pause, resume, or archive objects
Prefer set-status for single-object changes.
CODEBLOCK3
For bulk operations, create a JSON batch file and use batch after approval.
4) Create or update campaign structure
Create in order:
- 1. campaign
- ad set
- creative
- ad
Use JSON payload files for any nested params. Start from templates in assets/.
CODEBLOCK4
If assets are local files, upload them first with upload.
5) Targeting discovery
Never invent targeting IDs. Resolve them with targeting search first.
CODEBLOCK5
Then place the returned IDs and descriptors into the ad set targeting spec.
6) Unsupported or niche endpoints
Use the low-level request subcommand.
CODEBLOCK6
For nested values, prefer --params-file or @file.json values over many inline --sets.
Script reference
Main entry point
CODEBLOCK7
Most useful subcommands
- -
accounts — list accessible ad accounts from the token - INLINECODE32 — read the default or provided account
- INLINECODE33 — list campaigns, adsets, ads, creatives, audiences, assets, pixels, and more
- INLINECODE34 — read a node or node edge
- INLINECODE35 — create campaign, adset, adcreative, ad, customaudience, or any supported account edge
- INLINECODE36 — update a node by ID
- INLINECODE37 — convenience wrapper for INLINECODE38
- INLINECODE39 — sync or async reporting
- INLINECODE40 — resolve targeting descriptors
- INLINECODE41 — upload to
adimages or INLINECODE43 - INLINECODE44 — send Graph batch requests
- INLINECODE45 — low-level escape hatch for any Graph path
Rules for good agent behaviour
- - Read before write.
- Use the smallest field set that answers the question.
- Prefer JSON payload files for nested data.
- Use
--fetch-all only when the user actually needs all pages. - Use
--async for heavy Insights jobs. - Pause on repeated 613 or 80004 rate-limit errors; reduce scope or add time between retries.
- Prefer
PAUSED or ARCHIVED over destructive delete operations. - Report money in both raw API units and human units when relevant. Budgets are usually in the smallest currency denomination.
- When writing budgets, verify account currency and timezone first.
- After any mutation, verify the live state with a follow-up read.
- If the request touches housing, employment, credit, social issues, elections, or politics, check API guide for special-category cautions before proceeding.
Examples
Quick 7-day account snapshot
CODEBLOCK8
Increase a budget safely
- 1. Inspect the current ad set.
- Prepare an update payload with the new budget.
- Dry-run it.
- Ask for confirmation.
- Apply and verify.
CODEBLOCK9
Upload an image and build a link ad
CODEBLOCK10
References
Meta Ads 控制
使用此技能进行 Meta 营销 API 相关工作。优先使用捆绑脚本，因为它提供结构化的 JSON 输出、空运行保护、重试机制、分页、批量支持、异步洞察任务、定向搜索和资产上传。
在涉及支出或投放之前
- 1. 发现范围。
bash
python3 scripts/meta_ads.py accounts
python3 scripts/meta_ads.py account
- 2. 确认目标广告账户、货币、时区和可写对象。
- 对于任何可能产生费用、改变投放或影响追踪的变更：
- 准备简短计划，
- 运行 --dry-run，
- 展示将要变更的具体对象和字段，
- 等待用户明确批准，
- 然后使用 --confirm 重新运行。
- 4. 默认将新广告系列、广告组和广告设置为 PAUSED，除非用户明确要求立即上线。
- 任何写入操作后，使用 get、list 或 request GET 进行写后读验证。
认证与环境
脚本读取：
- - METAACCESSTOKEN — 实时 API 调用必需
- METAADACCOUNTID — 可选默认账户，可带或不带 act
- METAAPIVERSION — 默认为 v25.0
- METAGRAPHBASE — 默认为 https://graph.facebook.com
如果缺少 METAACCESSTOKEN，先帮助用户设置，而不是猜测或伪造 API 响应。
OpenClaw 用户可通过技能配置注入这些值。参见 OpenClaw 说明。
按任务快速路径
1) 审计或诊断账户
从能回答问题的最小读取开始。
bash
python3 scripts/metaads.py account --fields id,name,accountstatus,currency,timezonename,amountspent,spend_cap
python3 scripts/metaads.py list campaigns --fields id,name,objective,status,effectivestatus,dailybudget,lifetimebudget
python3 scripts/metaads.py list adsets --fields id,name,campaignid,status,effectivestatus,dailybudget,lifetimebudget,optimizationgoal,bid_strategy
python3 scripts/metaads.py list ads --fields id,name,adsetid,campaignid,status,effectivestatus,creative
当需要同时进行多个小读取时使用 batch。首先使用最小字段集。
2) 效果报告
使用 insights。从较窄的层级和日期窗口开始。对于大窗口、多字段或细分，使用 --async。
bash
python3 scripts/metaads.py insights act123 --level campaign --date-preset last_7d
python3 scripts/metaads.py insights act123 --level ad --fields adid,adname,spend,impressions,clicks,ctr,cpc,actions,actionvalues,purchaseroas --date-preset last_30d --async --fetch-all
如果用户询问转化或 ROAS，包含 actions 和 action_values。如果用户询问人口统计或展示位置细分，使用 --breakdowns。如果他们询问操作级别细分，包含 actions 并使用 --action-breakdowns。
3) 暂停、恢复或归档对象
单对象变更优先使用 set-status。
bash
python3 scripts/meta_ads.py set-status 120000000000000 PAUSED --dry-run
python3 scripts/meta_ads.py set-status 120000000000000 PAUSED --confirm
对于批量操作，创建 JSON 批处理文件并在批准后使用 batch。
4) 创建或更新广告系列结构
按顺序创建：
- 1. 广告系列
- 广告组
- 创意
- 广告
对任何嵌套参数使用 JSON 负载文件。从 assets/ 中的模板开始。
bash
python3 scripts/meta_ads.py create campaign --params-file assets/campaign-create.json --dry-run
python3 scripts/meta_ads.py create campaign --params-file work/campaign.json --confirm
python3 scripts/meta_ads.py create adset --params-file work/adset.json --dry-run
python3 scripts/meta_ads.py create adset --params-file work/adset.json --confirm
python3 scripts/meta_ads.py create adcreative --params-file work/adcreative.json --dry-run
python3 scripts/meta_ads.py create adcreative --params-file work/adcreative.json --confirm
python3 scripts/meta_ads.py create ad --params-file work/ad.json --dry-run
python3 scripts/meta_ads.py create ad --params-file work/ad.json --confirm
如果资产是本地文件，先用 upload 上传。
5) 定向发现
切勿编造定向 ID。先用定向搜索解析它们。
bash
python3 scripts/meta_ads.py targeting-search --type adinterest --q running
python3 scripts/meta_ads.py targeting-search --type adgeolocation --q Munich
然后将返回的 ID 和描述符放入广告组 targeting 规范中。
6) 不支持或小众端点
使用底层 request 子命令。
bash
python3 scripts/metaads.py request GET /act123/reachestimate --set targeting_spec=@work/targeting.json
python3 scripts/metaads.py request GET /120000000000000/previews --set adformat=DESKTOPFEEDSTANDARD
对于嵌套值，优先使用 --params-file 或 @file.json 值，而不是多个内联 --set。
脚本参考
主入口点
bash
python3 scripts/meta_ads.py --help
最常用的子命令
- - accounts — 列出令牌可访问的广告账户
- account — 读取默认或提供的账户
- list — 列出广告系列、广告组、广告、创意、受众、资产、像素等
- get — 读取节点或节点边缘
- create — 创建广告系列、广告组、广告创意、广告、自定义受众或任何支持的账户边缘
- update — 按 ID 更新节点
- set-status — status 的便捷封装
- insights — 同步或异步报告
- targeting-search — 解析定向描述符
- upload — 上传到 adimages 或 advideos
- batch — 发送 Graph 批量请求
- request — 任何 Graph 路径的底层逃生出口
良好代理行为规则
- - 先读后写。
- 使用能回答问题的最小字段集。
- 嵌套数据优先使用 JSON 负载文件。
- 仅在用户确实需要所有页面时使用 --fetch-all。
- 对大型洞察任务使用 --async。
- 遇到重复的 613 或 80004 速率限制错误时暂停；减少范围或增加重试间隔。
- 优先使用 PAUSED 或 ARCHIVED，而非破坏性删除操作。
- 在相关时以原始 API 单位和人类可读单位报告金额。预算通常以最小货币面额表示。
- 写入预算时，先验证账户货币和时区。
- 任何变更后，通过后续读取验证实时状态。
- 如果请求涉及住房、就业、信贷、社会问题、选举或政治，在继续之前检查 API 指南 中的特殊类别注意事项。
示例
快速 7 天账户快照
bash
python3 scripts/meta_ads.py batch --batch-file assets/batch-read-example.json
python3 scripts/metaads.py insights act123 --level campaign --date-preset last7d --fields campaignid,campaignname,spend,impressions,clicks,ctr,cpc,actions,actionvalues,purchase_roas
安全增加预算
- 1. 检查当前广告组。
- 准备包含新预算的更新负载。
- 空运行。
- 请求确认。
- 应用并验证。
bash
python3 scripts/metaads.py get 120000000000000 --fields id,name,status,effectivestatus,dailybudget,lifetimebudget
python3 scripts/meta_ads.py update 120000000000000 --params-file work/adset-budget.json --dry-run
python3 scripts/meta_ads.py update 120000000000000 --params-file work/adset-budget.json --confirm
python3 scripts/metaads.py get 120000000000000 --fields id,name,dailybudget,lifetimebudget,updatedtime
上传图片并构建链接广告
bash
python3 scripts/meta_ads.py upload adimages --file creative.jpg --confirm
将返回的 image_hash 放入 work/adcreative.json
python3 scripts/meta_
