名称： google-ads
描述： "查询、审计和优化 Google Ads 广告系列。支持两种模式：(1) API 模式：使用 google-ads Python SDK 进行批量操作；(2) 浏览器自动化模式：适用于无 API 访问权限的用户——只需附加一个已登录 ads.google.com 的浏览器标签页。当用户要求检查广告效果、暂停广告系列/关键词、查找无效花费、审计转化跟踪或优化 Google Ads 账户时使用。"
元数据：
{
"openclaw":
{
"emoji": "📊",
"requires":
{
"anyBins": ["python3"],
"config": ["~/.google-ads.yaml"],
},
},
}

Google Ads 技能

通过 API 或浏览器自动化管理 Google Ads 账户。

模式选择

检查应使用哪种模式：

1. API 模式 - 如果用户已配置 google-ads.yaml 或设置了 GOOGLE_ADS_* 环境变量。
2. 浏览器模式 - 如果用户表示“我没有 API 访问权限”或仅希望快速检查。

# 检查 API 配置文件
ls ~/.google-ads.yaml 2>/dev/null || ls google-ads.yaml 2>/dev/null

如果未找到配置文件，请询问：“您有 Google Ads API 凭证吗？还是我应该使用浏览器自动化？”

浏览器自动化模式（通用）

要求： 用户已在浏览器中登录 ads.google.com。

设置

1. 用户打开 ads.google.com 并登录。
2. 用户点击 Clawdbot Browser Relay 工具栏图标（徽章显示为 ON）。
3. 使用 browser 工具，并设置 profile="chrome"。

常见工作流

获取广告系列效果

1. 导航至：ads.google.com/aw/campaigns
2. 设置日期范围（右上角日期选择器）
3. 截取广告系列表格快照
4. 解析字段：广告系列、状态、预算、花费、转化次数、单次转化费用

查找零转化关键词（无效花费）

1. 导航至：ads.google.com/aw/keywords
2. 点击“添加筛选条件” → 转化次数 → 小于 → 1
3. 点击“添加筛选条件” → 费用 → 大于 → [阈值，例如 $500]
4. 按费用降序排序
5. 截取表格快照以供分析

暂停关键词/广告系列

1. 导航至关键词或广告系列视图
2. 勾选要暂停的项目
3. 点击“修改”下拉菜单 → “暂停”
4. 确认操作

下载报告

1. 导航至目标视图（广告系列、关键词等）
2. 点击“下载”图标（表格右上角）
3. 选择格式（推荐 CSV）
4. 文件将下载到用户的“下载”文件夹

详细的浏览器选择器信息： 请参阅 references/browser-workflows.md

API 模式（高级用户）

要求： Google Ads API 开发者令牌 + OAuth 凭证。

设置检查

# 验证 google-ads SDK
python -c "from google.ads.googleads.client import GoogleAdsClient; print('OK')"

# 检查配置文件
cat ~/.google-ads.yaml

常见操作

查询广告系列效果

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()
ga_service = client.get_service("GoogleAdsService")

query = """
    SELECT campaign.name, campaign.status,
           metrics.cost_micros, metrics.conversions,
           metrics.cost_per_conversion
    FROM campaign
    WHERE segments.date DURING LAST_30_DAYS
    ORDER BY metrics.cost_micros DESC
"""

response = ga_service.search(customer_id=CUSTOMER_ID, query=query)

查找零转化关键词

query = """
    SELECT ad_group_criterion.keyword.text,
           campaign.name, metrics.cost_micros
    FROM keyword_view
    WHERE metrics.conversions = 0
      AND metrics.cost_micros > 500000000
      AND segments.date DURING LAST_90_DAYS
    ORDER BY metrics.cost_micros DESC
"""

暂停关键词

operations = []
for keyword_id in keywords_to_pause:
    operation = client.get_type("AdGroupCriterionOperation")
    operation.update.resource_name = f"customers/{customer_id}/adGroupCriteria/{ad_group_id}~{keyword_id}"
    operation.update.status = client.enums.AdGroupCriterionStatusEnum.PAUSED
    operations.append(operation)

service.mutate_ad_group_criteria(customer_id=customer_id, operations=operations)

完整的 API 参考： 请参阅 references/api-setup.md

审计清单

适用于任何 Google Ads 账户的快速健康检查：

输出格式

报告发现时，请使用表格：

## 广告系列效果（最近 30 天）
| 广告系列 | 花费 | 转化次数 | 单次转化费用 | 状态 |
| :--- | :--- | :--- | :--- | :--- |
| 品牌词 | $5K | 50 | $100 | ✅ 良好 |
| SDK 网页 | $10K | 2 | $5K | ❌ 暂停 |

## 建议操作
1.  **暂停**：SDK 网页广告系列（单次转化费用 $5K）
2.  **增加**：品牌词预算（表现良好）

故障排除

浏览器模式问题

• 看不到数据：检查用户是否选择了正确的账户（右上角账户选择器）。
• 加载缓慢：Google Ads 界面较重；请等待表格完全加载。
• 会话过期：用户需要重新登录 ads.google.com。

API 模式问题

• 身份验证失败：刷新 OAuth 令牌，检查 google-ads.yaml。
• 开发者令牌被拒绝：确保令牌已获批准（非测试模式）。
• 客户 ID 错误：使用不带连字符的 10 位数字 ID。