Back to Details

meta-ads-control

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Meta Ads Control

Meta Ads 控制工具

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.
此技能用于Meta Marketing API相关操作。优先使用配套脚本，因为它可提供结构化JSON输出、预演保护（dry-run）、重试机制、分页功能、批量支持、异步Insights任务、定向搜索以及素材上传能力。

Before you touch spend or delivery

涉及广告支出或投放前的注意事项

  1. Discover scope.
    bash
    python3 scripts/meta_ads.py accounts
python3 scripts/meta_ads.py account
  2. Confirm the intended ad account, currency, timezone, and writable objects.
  3. 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.
  5. After any write, do a read-after-write verification with 
    get
    , 
    list
    , or 
    request GET
    .
  1. 明确操作范围。
    bash
    python3 scripts/meta_ads.py accounts
python3 scripts/meta_ads.py account
  2. 确认目标广告账户、货币、时区以及可编辑对象。
  3. 对于任何可能产生支出、影响投放或更改追踪设置的操作：
    • 准备简短计划，
    • 运行
      --dry-run
      预演，
    • 展示将被修改的具体对象和字段，
    • 等待用户明确批准，
    • 然后使用
      --confirm
      参数重新运行。
  4. 默认情况下，新建的广告系列、广告组和广告状态设为
    PAUSED
    ，除非用户明确要求立即上线。
  5. 任何写入操作完成后，使用
    get
    、
    list
    或
    request GET
    进行写后读取验证。

Authentication and environment

身份验证与环境配置

The script reads:
  • META_ACCESS_TOKEN
    — required for live API calls
  • META_AD_ACCOUNT_ID
    — optional default account, with or without 
    act_
  • META_API_VERSION
    — defaults to 
    v25.0
  • META_GRAPH_BASE
    — defaults to 
    https://graph.facebook.com
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.
脚本会读取以下环境变量：
  • META_ACCESS_TOKEN
    — 实时API调用必填
  • META_AD_ACCOUNT_ID
    — 可选的默认账户ID，可带或不带
    act_
    前缀
  • META_API_VERSION
    — 默认值为
    v25.0
  • META_GRAPH_BASE
    — 默认值为
    https://graph.facebook.com
如果缺少
META_ACCESS_TOKEN
，请先帮助用户完成设置，而非猜测或伪造API响应。
OpenClaw用户可通过技能配置注入这些值。详情请查看OpenClaw说明文档。

Fast path by task

按任务快速操作指南

1) Audit or diagnose an account

1) 账户审计或诊断

Start with the smallest read that answers the question.
bash
python3 scripts/meta_ads.py account --fields id,name,account_status,currency,timezone_name,amount_spent,spend_cap
python3 scripts/meta_ads.py list campaigns --fields id,name,objective,status,effective_status,daily_budget,lifetime_budget
python3 scripts/meta_ads.py list adsets --fields id,name,campaign_id,status,effective_status,daily_budget,lifetime_budget,optimization_goal,bid_strategy
python3 scripts/meta_ads.py list ads --fields id,name,adset_id,campaign_id,status,effective_status,creative
Use 
batch
when you need several small reads at once. Use minimal field sets first.
从能解答问题的最小范围读取操作开始。
bash
python3 scripts/meta_ads.py account --fields id,name,account_status,currency,timezone_name,amount_spent,spend_cap
python3 scripts/meta_ads.py list campaigns --fields id,name,objective,status,effective_status,daily_budget,lifetime_budget
python3 scripts/meta_ads.py list adsets --fields id,name,campaign_id,status,effective_status,daily_budget,lifetime_budget,optimization_goal,bid_strategy
python3 scripts/meta_ads.py list ads --fields id,name,adset_id,campaign_id,status,effective_status,creative
当需要同时执行多个小型读取操作时，使用
batch
命令。优先使用最小字段集。

2) Performance reporting

2) 绩效报告

Use 
insights
. Start with a narrow level and date window. For large windows, many fields, or breakdowns, use 
--async
.
bash
python3 scripts/meta_ads.py insights act_123 --level campaign --date-preset last_7d
python3 scripts/meta_ads.py insights act_123 --level ad --fields ad_id,ad_name,spend,impressions,clicks,ctr,cpc,actions,action_values,purchase_roas --date-preset last_30d --async --fetch-all
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
.
使用
insights
命令。从较窄的层级和日期范围开始。对于大范围日期、多字段或拆分维度的报告，使用
--async
参数。
bash
python3 scripts/meta_ads.py insights act_123 --level campaign --date-preset last_7d
python3 scripts/meta_ads.py insights act_123 --level ad --fields ad_id,ad_name,spend,impressions,clicks,ctr,cpc,actions,action_values,purchase_roas --date-preset last_30d --async --fetch-all
如果用户询问转化或ROAS相关内容，请包含
actions
和
action_values
字段。如果用户询问人群统计或版位拆分，请使用
--breakdowns
参数。如果用户询问操作层级拆分，请包含
actions
字段并使用
--action-breakdowns
参数。

3) Pause, resume, or archive objects

3) 暂停、恢复或归档对象

Prefer 
set-status
for single-object changes.
bash
python3 scripts/meta_ads.py set-status 120000000000000 PAUSED --dry-run
python3 scripts/meta_ads.py set-status 120000000000000 PAUSED --confirm
For bulk operations, create a JSON batch file and use 
batch
after approval.
单个对象状态变更优先使用
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) Create or update campaign structure

4) 创建或更新广告系列结构

Create in order:
  1. campaign
  2. ad set
  3. creative
  4. ad
Use JSON payload files for any nested params. Start from templates in 
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
If assets are local files, upload them first with 
upload
.
按以下顺序创建：
  1. 广告系列（campaign）
  2. 广告组（ad set）
  3. 创意（creative）
  4. 广告（ad）
任何嵌套参数使用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) Targeting discovery

5) 定向设置查询

Never invent targeting IDs. Resolve them with targeting search first.
bash
python3 scripts/meta_ads.py targeting-search --type adinterest --q "running"
python3 scripts/meta_ads.py targeting-search --type adgeolocation --q "Munich"
Then place the returned IDs and descriptors into the ad set 
targeting
spec.
切勿自行编造定向ID。先通过定向搜索获取正确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) Unsupported or niche endpoints

6) 不支持或小众的API端点

Use the low-level 
request
subcommand.
bash
python3 scripts/meta_ads.py request GET /act_123/reachestimate --set targeting_spec=@work/targeting.json
python3 scripts/meta_ads.py request GET /120000000000000/previews --set ad_format=DESKTOP_FEED_STANDARD
For nested values, prefer 
--params-file
or 
@file.json
values over many inline 
--set
s.
使用底层的
request
子命令。
bash
python3 scripts/meta_ads.py request GET /act_123/reachestimate --set targeting_spec=@work/targeting.json
python3 scripts/meta_ads.py request GET /120000000000000/previews --set ad_format=DESKTOP_FEED_STANDARD
对于嵌套值，优先使用
--params-file
或
@file.json
参数，而非多个内联
--set
参数。

Script reference

脚本参考

Main entry point

主入口

bash
python3 scripts/meta_ads.py --help
bash
python3 scripts/meta_ads.py --help

Most useful subcommands

最常用的子命令

  • accounts
    — list accessible ad accounts from the token
  • account
    — read the default or provided account
  • list
    — list campaigns, adsets, ads, creatives, audiences, assets, pixels, and more
  • get
    — read a node or node edge
  • create
    — create campaign, adset, adcreative, ad, customaudience, or any supported account edge
  • update
    — update a node by ID
  • set-status
    — convenience wrapper for 
    status
  • insights
    — sync or async reporting
  • targeting-search
    — resolve targeting descriptors
  • upload
    — upload to 
    adimages
    or 
    advideos
  • batch
    — send Graph batch requests
  • request
    — low-level escape hatch for any Graph path
  • accounts
    — 列出令牌可访问的广告账户
  • account
    — 读取默认或指定的账户信息
  • list
    — 列出广告系列、广告组、广告、创意、受众、素材、像素等内容
  • get
    — 读取节点或节点边缘信息
  • create
    — 创建广告系列、广告组、广告创意、广告、自定义受众或任何支持的账户边缘对象
  • update
    — 通过ID更新节点信息
  • set-status
    — 
    status
    操作的便捷封装命令
  • insights
    — 同步或异步报告生成
  • targeting-search
    — 解析定向描述信息
  • upload
    — 上传素材至
    adimages
    或
    advideos
  • batch
    — 发送Graph批量请求
  • request
    — 针对任何Graph路径的底层应急命令

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.
  • 先读取后写入。
  • 使用能解答问题的最小字段集。
  • 嵌套数据优先使用JSON负载文件。
  • 仅当用户确实需要所有页面数据时才使用
    --fetch-all
    参数。
  • 大型Insights任务使用
    --async
    参数。
  • 遇到重复的613或80004限流错误时暂停操作；缩小范围或增加重试间隔。
  • 优先使用
    PAUSED
    或
    ARCHIVED
    状态，而非破坏性删除操作。
  • 相关情况下，同时以原始API单位和人类可读单位报告金额。预算通常使用最小货币单位。
  • 设置预算时，先验证账户货币和时区。
  • 任何变更操作后，通过后续读取验证实时状态。
  • 如果请求涉及住房、就业、信贷、社会问题、选举或政治内容，操作前请查看API指南中的特殊类别注意事项。

Examples

示例

Quick 7-day account snapshot

快速生成7天账户快照

bash
python3 scripts/meta_ads.py batch --batch-file assets/batch-read-example.json
python3 scripts/meta_ads.py insights act_123 --level campaign --date-preset last_7d --fields campaign_id,campaign_name,spend,impressions,clicks,ctr,cpc,actions,action_values,purchase_roas
bash
python3 scripts/meta_ads.py batch --batch-file assets/batch-read-example.json
python3 scripts/meta_ads.py insights act_123 --level campaign --date-preset last_7d --fields campaign_id,campaign_name,spend,impressions,clicks,ctr,cpc,actions,action_values,purchase_roas

Increase a budget safely

安全提升预算

  1. Inspect the current ad set.
  2. Prepare an update payload with the new budget.
  3. Dry-run it.
  4. Ask for confirmation.
  5. Apply and verify.
bash
python3 scripts/meta_ads.py get 120000000000000 --fields id,name,status,effective_status,daily_budget,lifetime_budget
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/meta_ads.py get 120000000000000 --fields id,name,daily_budget,lifetime_budget,updated_time
  1. 检查当前广告组信息。
  2. 准备包含新预算的更新负载文件。
  3. 执行预演。
  4. 请求用户确认。
  5. 应用变更并验证。
bash
python3 scripts/meta_ads.py get 120000000000000 --fields id,name,status,effective_status,daily_budget,lifetime_budget
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/meta_ads.py get 120000000000000 --fields id,name,daily_budget,lifetime_budget,updated_time

Upload an image and build a link ad

上传图片并创建链接广告

bash
python3 scripts/meta_ads.py upload adimages --file creative.jpg --confirm
bash
python3 scripts/meta_ads.py upload adimages --file creative.jpg --confirm

Put the returned image_hash into work/adcreative.json

将返回的image_hash填入work/adcreative.json

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 --confirm
undefined
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 --confirm
undefined

References

参考资料

  • API guide
  • Field sets and reporting defaults
  • Workflow playbook
  • Troubleshooting
  • OpenClaw notes
  • Asset templates in 
    assets/
  • Example evals in 
    evals/evals.json
  • API指南
  • 字段集与报告默认值
  • 工作流手册
  • 故障排查
  • OpenClaw说明文档
  • assets/
    目录下的素材模板
  • evals/evals.json
    中的示例评估