Skip to content

Chanlinnn/google-ads-agent-skills / skills/setup-google-ads

setup-google-ads

Verified

配置和排查 Google Ads API 到 AI Agent 的本地只读 MCP 接入。用于新电脑部署、Google Cloud 与 Ads 权限区分、服务账号或 ADC 配置、Codex MCP 注册、可访问账户验证,以及认证、网络、版本和权限错误排查。Set up or troubleshoot a local read-only Google Ads MCP connection. 不负责广告表现分析或广告修改。

references/setup.md

View on GitHub
# 安装与验证

参考:macOS / Linux、Python 3.11+、本地 STDIO。新手可以将本文交给 Agent 分步执行;浏览器里的账号授权和密钥下载由账号所有者完成。先阅读 [compatibility.md](compatibility.md),不要将旧 Token 申请流程套用到新项目。

## 1. 准备 Cloud 项目和 Ads 角色

1. 在 Google Cloud 选择专用项目,启用 Google Ads API。
2. 在该项目的 Google Ads API 概览确认 API 访问级别。测试权限不支持真实生产账户;生产访问按当前官方流程申请,不承诺审批时长。
3. 本地长期使用可选择专用服务账号。在 Google Ads 管理员界面将服务账号邮箱加入目标客户账户,赋予 **Read only**。若通过 MCC 统一访问,则在该 MCC 授权并确认目标客户在其层级内。
4. 通过 MCC 访问时,`login_customer_id` 填经理账户的十位 ID;直接授权客户账户时可留空。查询工具的 `customer_id` 始终是目标账户。身份在不同路径下的权限可能不同。
5. Google Cloud 的项目角色不会自动授予 Ads 访问权限。为管理 Cloud API 访问级别所需的管理员权限,也不应无故授给查询用服务账号。

依据:[服务账号授权](https://developers.google.com/google-ads/api/docs/oauth/service-accounts)、[访问模型](https://developers.google.com/google-ads/api/docs/oauth/access-model)、[API 访问级别](https://developers.google.com/google-ads/api/docs/api-policy/access-levels)。

## 2. 凭据留在本机

服务账号方式:按组织政策生成凭据 JSON,将它放在用户私人目录中,远离任何代码仓库和同步目录。不要放入 Skill 文件夹。macOS / Linux 对该文件设置 `chmod 600`;不要将文件正文发送给 Agent。

也可使用 OAuth 用户 ADC:按 [Google 官方 MCP 指引](https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server)申请包含 `https://www.googleapis.com/auth/adwords` 的 ADC。普通 `gcloud auth login` 不等同于为应用准备正确作用域的 ADC。本启动器支持 `service_account` 和 `authorized_user` 文件;工作负载联合身份或 impersonation ADC 应另按组织方案接入,不能假称已验证。

`project_id` 应是创建服务账号或 OAuth client 的项目,不是随意指定的计费/配额项目。服务账号类型会做项目匹配检查;OAuth client 所属项目仍需用户核对。JSON 格式检查不证明凭据有效。

## 3. 安装固定版本依赖

以下命令在**已安装的 `setup-google-ads` Skill 目录**执行。系统 Python 需为 3.11+;若系统 `python3` 过旧,使用正确版本的路径。不要在原有可用连接的虚拟环境上直接升级。

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r assets/requirements.txt
.venv/bin/python scripts/manage.py configure
.venv/bin/python scripts/manage.py check
```

配置向导仅询问项目 ID、凭据文件路径、经理账户 ID 和可选 HTTP 代理。默认配置保存在 `~/.config/google-ads-agent/local.json`,权限为 0600;该文件仍含私人元数据,不可提交。已存在时向导不会覆盖,需在本机检查并编辑现有文件。多个连接可用 `--config` 指定不同的私人配置文件,Codex 启动参数也要一致。

示例:[local.example.json](../assets/local.example.json)。占位符不是有效配置。代理留空代表直连;启动器会清除继承的代理地址,再采用配置中明确填写的 HTTP 代理。需要代理时使用当前网络实际可用的地址,不猜端口,不添加公共转换服务。

配置检查只检查文件、权限、版本和工具配置,不会向 Google 发请求,也不打印账户信息。

## 4. 注册到 Codex

打开 [codex.example.toml](../assets/codex.example.toml),将两处 `ABSOLUTE_SETUP_SKILL_PATH` 替换为该 Skill 的真实绝对路径,再把整个配置块**合并**进用户的 `~/.codex/config.toml`,或已受信任专用项目的 `.codex/config.toml`。已有 `google_ads` 连接时先核对,不创建重复表或覆盖其他 MCP。

该配置没有凭据正文,只启动本地程序。若使用自定义配置文件,在 `args` 后添加 `"--config", "PRIVATE_CONFIG_ABSOLUTE_PATH"`。不要改变宿主已有的审批策略或绕过组织策略。

重载连接或新开对话。先检查工具清单只包含:

```text
customers_list_accessible_customers
metadata_get_resource_metadata
search_search
```

服务端 `tools-readonly.json` 使用 JSON(兼容 YAML),显式关闭素材和标签工具;启动器会检查其内容,缺失或被改动时停止。Codex 的 `enabled_tools` 再限制一次工具可见性。

参考:[Codex MCP 配置](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)、[Skill 目录与安装](https://learn.chatgpt.com/docs/build-skills)。其他客户端须转换配置格式,并独立验证工具清单。

## 5. 最小线上验收

以下步骤需要用户自己的授权账户;安装者不能使用项目维护者的凭据代测。

1. 列出直接可访问账户。若列表不含子账户,不立即判定授权失败。
2. 如使用 MCC,先读取 `customer_client` 字段元数据,再查账户层级。需要下级 MCC 时递归或按已返回层级处理,去重客户 ID,标明未覆盖的分支。
3. 对选定客户读取 `customer` 的 ID、币种和时区。客户 ID 的完整值只用于私人调用,不回填开源文件。
4. 核对工具限制、实际账户角色和最小查询结果后,才开始有限日期范围的效果分析。

工具列表出现不代表认证成功;读取成功也不证明具有编辑权限。本项目不做写入校验。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall