meta-ads-control

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: meta-ads-control
description: Use this skill when the user wants to inspect, report on, create, update, pause, resume, budget, target, upload assets for, or troubleshoot Meta, Facebook, or Instagram ads via the Marketing API. It covers ad accounts, campaigns, ad sets, ads, creatives, ad images and videos, targeting search, batch reads, and Insights reports. Helpful for requests about Meta Ads Manager, ROAS or CPA reporting, launch workflows, creative rollout, audience setup, delivery issues, budget changes, or bulk ad operations.
license: MIT. See LICENSE.txt
compatibility: Requires Python 3 and outbound HTTPS access to graph.facebook.com. Best with OpenClaw and other AgentSkills-compatible agents. Reads META_ACCESS_TOKEN, META_AD_ACCOUNT_ID, META_API_VERSION, and META_GRAPH_BASE from the environment.
metadata: {"author":"OpenAI","version":"1.0.0","openclaw":{"emoji":"📣","primaryEnv":"META_ACCESS_TOKEN","requires":{"anyBins":["python3","python"]}}}
---

# 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.
   ```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`.

## 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](references/OPENCLAW.md).

## Fast path by task

### 1) Audit or diagnose an account

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.

### 2) Performance reporting

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`.

### 3) Pause, resume, or archive objects

Prefer `set-status` for single-object changes.

```bash
python3 scripts/meta_ads.py set-status 120000000000000 PAUSED --dry-run
python3 scr