Meta Ads 报告

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install ent-meta-ads-report
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 ent-meta-ads-report。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Meta Ads Report 是一款只读的 Openclaw Skills 工具，可通过 HTTP 和 curl 使用 Meta 官方 Graph API 查询 Facebook 和 Instagram 广告数据，无需 SDK。它可获取账户详情、广告系列列表，以及账户级、广告系列级或每日级的效果洞察，并支持自定义日期范围和受众细分。
该技能旨在保护广告账户：它只读取数据，绝不会创建、编辑、暂停或删除广告。它还提供有关安全处理令牌、解读转化指标、排查 API 错误以及生成清晰报告的实用指导，并帮助区分 Meta 报告的数据与 ROAS 等计算指标。

应用场景

查看所选时间段的花费、展示次数、点击次数、覆盖人数、CPC、CPM、CTR 和转化结果。
比较广告系列效果，并结合报告结果检查广告系列目标。
按日期、年龄或性别细分洞察，以调查效果模式。
检查广告账户状态、货币、时区、余额和花费上限。
在安排报告或分析之前，验证令牌权限和有效期。
生成清晰的报告，注明报告层级、货币及任何计算指标。

工作原理

从环境变量读取 META_ACCESS_TOKEN 和 META_AD_ACCOUNT_ID；绝不要在技能或脚本中硬编码凭据。
使用 curl -G 和 --data-urlencode 为查询参数（包括访问令牌）编码，并向 Meta Graph API 发出 HTTPS GET 请求。
查询相关端点：令牌调试、账户详情、广告系列列表、账户级洞察或广告系列级洞察。
使用 last_7d 等预设值或自定义 time_range 设置报告时间段；也可选择请求每日增量或受支持的受众细分。
如果响应经过分页，则继续请求 paging.next；遇到速率限制时，逐步延长等待时间后重试，最多尝试五次。
结合上下文解读返回的指标，将操作类型映射到广告系列目标，并将 ROAS 等派生值标注为计算值，而非 Meta 报告值。
如实报告缺失数据，并注明数据的来源层级和货币。

配置指南

在 Meta for Developers 中创建或选择 Business 应用，并生成具有 ads_read 权限的访问令牌。个人短期令牌通常约两小时后失效；可将其兑换为有效期约 60 天的长期令牌。正确配置后，也可以使用 System User 令牌。
在 OpenClaw 网关环境中设置令牌和数字格式的广告账户 ID。账户 ID 不应包含 act_ 前缀；该技能会为账户端点添加此类前缀。
不要将机密信息提交到源代码管理中；应将令牌作为经过编码的查询参数传递，而不是直接插入 URL。
export META_ACCESS_TOKEN="your_meta_access_token"
export META_AD_ACCOUNT_ID="123456789"
curl -s -G "https://graph.facebook.com/v21.0/act_$META_AD_ACCOUNT_ID/insights" \ --data-urlencode "fields=spend,impressions,clicks,reach,cpc,cpm,ctr,actions,action_values" \ --data-urlencode "date_preset=last_7d" \ --data-urlencode "access_token=$META_ACCESS_TOKEN" 兑换短期令牌时，请安全使用应用凭据，并避免将应用密钥保存在已提交的脚本中：
curl -G "https://graph.facebook.com/v21.0/oauth/access_token" \ --data-urlencode "grant_type=fb_exchange_token" \ --data-urlencode "client_id=$APP_ID" \ --data-urlencode "client_secret=$APP_SECRET" \ --data-urlencode "fb_exchange_token=$SHORT_LIVED_TOKEN" 使用 debug_token 端点检查令牌的有效性和到期时间。如果令牌将在不到 14 天内到期，请提醒用户登录并获取新令牌；个人长期令牌若没有登录会话，无法无限期续期。

数据架构

该技能读取 Meta Graph API v21.0 返回的 JSON 响应。它不定义或生成本地数据库、报告文件或持久化数据架构。
数据区域 端点或响应字段 用途
令牌状态 /debug_token；data.is_valid、data.expires_at 验证令牌有效性和到期时间（Unix 纪元秒）。
广告账户 /act_{ID}；name、account_status、currency、timezone_name、amount_spent、balance、spend_cap 查看账户详情和账单相关数值。
广告系列 /act_{ID}/campaigns；id、name、status、objective、daily_budget、lifetime_budget 列出广告系列及其配置元数据。
洞察 /act_{ID}/insights；spend、impressions、clicks、reach、frequency、cpc、cpm、ctr、actions、action_values 获取账户级或广告系列级效果指标。
报告维度 date_preset、time_range、time_increment、level、breakdowns 指定日期、每日行、汇总层级和受支持的维度。
分页和错误 paging.next；error.code 继续分页读取并诊断 API 故障。
actions 和 action_values 包含特定操作类型的结果。应根据广告系列目标选择相关操作类型，例如购买、潜在客户、链接点击、消息对话或直播评论。ROAS 可通过 action_values / spend 计算；请将其标注为派生指标。展示货币金额时应使用账户货币，不要虚构缺失的结果。

高级特性

严格只读：请求仅用于检索数据；该技能不会创建、修改、暂停或删除广告，也不会调用 Graph API POST 或 DELETE 操作。
灵活报告：支持账户和广告系列洞察、预设或自定义日期范围、每日报告，以及可用时的年龄/性别细分。
令牌生命周期检查：使用
debug_token
检查有效性和到期时间，并指导在令牌过期前提醒用户。
安全构造请求：从环境变量读取凭据，并使用
curl -G --data-urlencode
，避免 shell 截断 URL 和产生误导性的身份验证错误。
根据目标解读指标：将广告系列目标映射到合适的操作类型，而不是假设每个广告系列的结果都是潜在客户。
可靠处理 API：说明如何通过
paging.next
翻页、如何处理身份验证错误代码 190 和 200，以及如何对速率限制进行类似指数退避的重试，最多重试五次。
透明的报告规范：区分账户级和广告系列级数值，注明货币，标记计算指标，并说明数据缺失情况。

name: "meta-ads-report" description: "Kéo báo cáo chỉ số Meta Ads (Facebook/Instagram) qua Graph API. READ-ONLY: insights, campaign, account, kiểm tra hạn token."

Meta Ads Report (READ-ONLY)

Kéo chỉ số báo cáo quảng cáo Meta qua Graph API chính thức bằng HTTP (curl) — không cần SDK.

⚠️ Tuyệt đối READ-ONLY. Skill này CHỈ đọc dữ liệu (insights + danh sách campaign/account). KHÔNG có bất kỳ lệnh tạo/sửa/tắt/xóa ads nào. Không bao giờ gọi POST/DELETE tới Graph API.

1. Cấu hình (environment variables) Biến Bắt buộc Mô tả
   META_ACCESS_TOKEN ✅ Meta access token (User token hoặc System User token), quyền ads_read
   META_AD_ACCOUNT_ID ✅ Ad account ID dạng số (không có prefix act_), ví dụ 123456789

Lưu ý bảo mật:

Token đọc từ environment variable, KHÔNG hardcode trong file/skill.
Đặt token trong config env của gateway (instance OpenClaw của bạn), không commit vào script.
KHÔNG bao giờ nhét token trực tiếp vào URL bằng dấu ngoặc kép → shell cắt chuỗi → lỗi 4xx GIẢ (trông như token hỏng nhưng thật ra URL bị cắt). Luôn dùng curl -G --data-urlencode "access_token=$META_ACCESS_TOKEN". 2. Lấy token (tài khoản cá nhân) Vào developers.facebook.com/tools/explorer
Chọn app loại "Business" (tạo mới nếu chưa có)
Thêm quyền ads_read (+ ads_management nếu cần)
Generate Access Token → đăng nhập → cho phép
Copy token test (ngắn hạn ~2h)

Chuyển sang long-lived (~60 ngày):

curl -G "https://graph.facebook.com/v21.0/oauth/access_token" \

--data-urlencode "grant_type=fb_exchange_token"
--data-urlencode "client_id={APP_ID}"
--data-urlencode "client_secret={APP_SECRET}"
--data-urlencode "fb_exchange_token={SHORT_LIVED_TOKEN}"

Token cá nhân long-lived hết hạn sau ~60 ngày → phải đăng nhập lại lấy token mới (không tự gia hạn hoàn toàn được vì cần phiên đăng nhập). Nên tự kiểm tra hạn bằng debug_token và cảnh báo trước