# openclaw-adspirer

OpenClaw plugin for [Adspirer](https://adspirer.com) — manage Google, Meta, TikTok & LinkedIn ads via natural language.

## Features

- **143 ad management tools** across 5 platforms (Google Ads, Meta Ads, TikTok Ads, LinkedIn Ads, Audit)
- **Complete parameter schemas** — every tool ships with full `inputSchema` so AI agents construct valid arguments
- **OAuth 2.1 + PKCE** authentication
- **API Key authentication** — for headless servers, Docker, and CI/CD (`--token` flag or `ADSPIRER_API_KEY` env var)
- **Zero runtime dependencies** — uses Node.js built-in `fetch` and `crypto`
- **Read/Write safety** — write tools require user confirmation before execution

## Installation

```bash
openclaw plugins install openclaw-adspirer
```

## Setup

**Browser-based (local machine):**

```bash
# Authenticate with Adspirer via OAuth
openclaw adspirer login

# Verify connection
openclaw adspirer status
```

**Headless / Remote server (VPS, Docker, CI/CD):**

```bash
# Generate an API key at https://adspirer.ai/keys
# Then authenticate with the key:
openclaw adspirer login --token sk_live_your_token_here

# Or set as environment variable (no login needed):
export ADSPIRER_API_KEY=sk_live_your_token_here
```

## Configuration

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `serverUrl` | string | `https://mcp.adspirer.com` | MCP server URL |
| `accessToken` | string | — | OAuth access token (set by login) |
| `refreshToken` | string | — | OAuth refresh token (set by login) |
| `apiKey` | string | — | Personal access token for headless auth (or use `ADSPIRER_API_KEY` env var) |
| `tokenExpiresAt` | number | — | Token expiry timestamp (set by login) |
| `defaultAccountId` | string | — | Default ad account ID |
| `enabledGroups` | string[] | all groups | Platform groups to enable |
| `enabledTools` | string[] | `[]` | Cherry-pick specific tools (overrides groups) |
| `requestTimeoutMs` | number | `60000` | HTTP request timeout in ms |

## CLI Commands

| Command | Description |
|---------|-------------|
| `openclaw adspirer login` | Authenticate via OAuth PKCE |
| `openclaw adspirer login --token <key>` | Authenticate with API key (headless servers) |
| `openclaw adspirer logout` | Clear stored tokens and API key |
| `openclaw adspirer status` | Show auth status, connections, tool count |
| `openclaw adspirer accounts` | List connected ad accounts |
| `openclaw adspirer tools` | List registered tools by platform |
| `openclaw adspirer connect` | Open Adspirer to connect ad platforms |

## Tool Groups

| Group | Platform | Tools |
|-------|----------|-------|
| `google_ads` | Google Ads | 40 |
| `meta_ads` | Meta Ads | 20 |
| `tiktok_ads` | TikTok Ads | 4 |
| `linkedin_ads` | LinkedIn Ads | 28 |
| `manus` | Automation | 8 |
| `system` | Cross-Platform | 4 |

### Filtering

Enable only specific platforms:

```yaml
config:
  enabledGroups: ["google_ads", "meta_ads"]
```

Or cherry-pick individual tools:

```yaml
config:
  enabledTools: ["echo_test", "get_campaign_performance", "list_campaigns"]
```

## Tool Safety Model

- **Read tools** (`get_*`, `list_*`, `analyze_*`, etc.) — auto-execute, no confirmation needed
- **Write tools** (`create_*`, `update_*`, `pause_*`, etc.) — agent MUST ask user before executing

## Updating

When a new version is published:

```bash
# Update to latest
openclaw plugins update openclaw-adspirer

# Or update all plugins
openclaw plugins update --all

# Preview changes without applying
openclaw plugins update openclaw-adspirer --dry-run
```

Then restart the gateway to load the new version.

## Uninstalling

> `plugins uninstall` is not yet available in OpenClaw. Manual removal required:

**Step 1: Remove plugin files**

```bash
rm -rf ~/.openclaw/extensions/openclaw-adspirer
```

**Step 2: Remove from config**

Edit `~/.openclaw/openclaw.json` and remove these entries:

```diff
  "plugins": {
    "entries": {
-     "openclaw-adspirer": {
-       "enabled": true
-     }
    },
    "installs": {
-     "openclaw-adspirer": { ... }
    }
  }
```

**Step 3: Clear stored credentials (optional)**

```bash
# If you want to remove OAuth tokens too
openclaw adspirer logout
```

**Step 4: Restart gateway**

```bash
openclaw gateway restart
```

## Reinstalling

If you need a fresh install:

```bash
# Remove existing (see Uninstalling above), then:
openclaw plugins install openclaw-adspirer
```

> `plugins install` doesn't overwrite existing installs. Remove first, then reinstall.

## Troubleshooting

| Issue | Solution |
|-------|---------|
| "Please run login" | Run `openclaw adspirer login` |
| "Cannot reach server" | Check network / server URL |
| "Session expired" | Token auto-refreshes; if persistent, re-login |
| "Invalid or expired API key" | Generate a new key at [adspirer.ai/keys](https://adspirer.ai/keys) |
| "No platform account connected" | Connect ad platforms at [adspirer.ai/connections](https://adspirer.ai/connections) — API keys require connected accounts |
| "Rate limit hit" | Wait and retry |
| Tools not showing | Restart gateway after config changes |

## License

MIT