@civic/openclaw-google

An OpenClaw plugin that gives AI agents access to Google Workspace (Gmail, Calendar, etc.) using Civic for OAuth. No Google Cloud project, no local credentials, no token management.

What this replaces

Without this plugin, giving an agent access to Google APIs via gog requires:

1. Creating a Google Cloud project, enabling APIs, and configuring the OAuth consent screen
2. Generating OAuth client credentials (credentials.json)
3. Running gog auth credentials set credentials.json then gog auth add [email protected] — which opens a browser and stores a refresh token in your local keyring
4. Dealing with token expiry, revocation, and refresh failures yourself
5. Accepting that gog requests broad scopes by default — e.g., gmail.modify + gmail.settings.basic + gmail.settings.sharing even if your agent only reads email

Every user who runs the agent has to do this themselves.

With this plugin, the setup is:

openclaw plugins install @civic/openclaw-google

Civic provides the OAuth client, stores tokens encrypted server-side, refreshes them automatically, and the plugin requests only the scope each command actually needs.

How it works

Agent calls "gog gmail search ..."
        │
        ▼
Plugin intercepts (before_tool_call hook)
        │
        ▼
Matches "gog gmail" → needs google-gmail-read (gmail.readonly)
        │
        ▼
Fetches token from Civic  ──→  Token ready? → Inject GOG_ACCESS_TOKEN → gog runs
                           └→  Not authorized? → Block with auth URL for user
                           └→  Token expired? → Civic already refreshed it → inject and run

The agent and gog never see OAuth client credentials or refresh tokens. They get a short-lived access token injected via environment variable.

On first use for a given scope, the agent surfaces an authorization URL. The user clicks it, consents once, and all future calls for that scope work automatically.

Least-privilege scope mapping

gog's native auth requests broad scopes per service. This plugin maps each subcommand to the minimum scope needed:

| Agent action | Scope via this plugin | Scope via native gog auth | |---|---|---| | Read/search email | gmail.readonly | gmail.modify + gmail.settings.basic + gmail.settings.sharing | | Send email | gmail.send | (same broad set) | | Create/edit drafts | gmail.compose | (same broad set) | | Trash/archive email | gmail.modify | (same broad set) | | Read calendar | calendar.readonly | calendar (full read/write) | | Create/update/delete events | calendar.events | calendar (full read/write) |

Each scope requires separate user consent. An agent that only reads email cannot send or delete it.

Quick start

1. Install the plugin

openclaw plugins install @civic/openclaw-google

2. Install gog

brew install gog

3. Set your Civic token

Add to the OpenClaw gateway environment:

NEXUS_TOKEN=<your-civic-api-token>

Get your token from nexus.civic.com → Settings → API Keys.

4. Use it

Ask your agent to read email, check your calendar, draft a reply. On first use per scope, you'll see an authorization link to click.

Default credential mappings

| Command | Credential ID | Scope | |---|---|---| | gog gmail send | google-gmail-send | gmail.send | | gog gmail drafts / draft | google-gmail-draft | gmail.compose | | gog gmail trash / archive / read / unread / batch | google-gmail-modify | gmail.modify | | gog gmail (everything else) | google-gmail-read | gmail.readonly | | gog calendar create / update / delete / respond / subscribe | google-calendar-write | calendar.events | | gog calendar (everything else) | google-calendar-read | calendar.readonly |

Mappings are evaluated most-specific first — gog gmail send matches before the gog gmail catch-all.

Configuration

The plugin works out of the box after install. To customize, edit ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "civic-google": {
        "enabled": true
      }
    }
  }
}

Custom credential mappings

To add mappings for additional Google services (e.g., Drive):

{
  "plugins": {
    "entries": {
      "civic-google": {
        "enabled": true,
        "config": {
          "credentialMappings": [
            {
              "credentialId": "google-drive-read",
              "envVar": "GOG_ACCESS_TOKEN",
              "toolMatch": "exec:gog drive"
            }
          ]
        }
      }
    }
  }
}

Custom proxy URL

Default: https://nexus.civic.com/ext/openclaw. For local development:

OPENCLAW_PROXY_URL=http://localhost:3013/openclaw

Security

• Tokens are stored in Civic's encrypted store (AES-256), not on the agent's machine
• Access tokens are short-lived (~1 hour) and refreshed automatically server-side
• Each subcommand gets only the scope it needs, with separate user consent per scope
• Revoking access in Civic invalidates all tokens immediately
• The agent never sees OAuth client secrets or refresh tokens

License

MIT