Google Pubsub

Name: Google Pubsub
Rating: 3.5 (1 reviews)
Author: bitnahian

By bitnahian 👁 32 views ▲ 0 votes

OpenClaw plugin for reading Google Cloud Pub/Sub pull subscriptions with gateway-side credentials.

GitHub

Install

npm install
npx

Configuration Example

{
  "plugins": {
    "entries": {
      "google-pubsub": {
        "config": {
          "defaultProjectId": "your-gcp-project-id",
          "auth": {
            "method": "service-account-json",
            "serviceAccountJsonPath": "/etc/openclaw/gcp/pubsub-reader.json"
          },
          "retry": {
            "maxAttempts": 5,
            "initialBackoffMs": 250,
            "maxBackoffMs": 8000,
            "backoffMultiplier": 2
          }
        }
      }
    }
  }
}

README

# @bitnahian/openclaw-google-pubsub-plugin

An OpenClaw plugin for reading from Google Cloud Pub/Sub pull subscriptions.
It is intentionally narrow and opinionated:

- One tool: `read_subscription`
- Pull subscriptions only
- Gateway-side credentials only
- REST transport only
- Messages are always acknowledged before the tool returns

This is designed for heartbeat or scheduled polling by sandboxed agents that
should not load cloud credentials directly.

## Authentication

Supported auth modes:

- `adc` (default): Application Default Credentials
- `service-account-json`: load credentials from `auth.serviceAccountJsonPath`

Inline service-account JSON is intentionally not supported.

Example plugin config:

```json
{
  "plugins": {
    "entries": {
      "google-pubsub": {
        "config": {
          "defaultProjectId": "your-gcp-project-id",
          "auth": {
            "method": "service-account-json",
            "serviceAccountJsonPath": "/etc/openclaw/gcp/pubsub-reader.json"
          },
          "retry": {
            "maxAttempts": 5,
            "initialBackoffMs": 250,
            "maxBackoffMs": 8000,
            "backoffMultiplier": 2
          }
        }
      }
    }
  }
}
```

For ADC, omit `auth` entirely or set `auth.method` to `adc`.

## Tool

`read_subscription` accepts:

- `subscription` (required): full `projects/{project}/subscriptions/{name}` or a short name
- `project_id` (optional): used to expand a short subscription name
- `max_messages` (optional, default `10`, max `1000`)
- `return_immediately` (optional, default `false`)
- `decode_data` (optional, default `true`)

Example result:

```json
{
  "subscription": "projects/your-gcp-project-id/subscriptions/your-subscription",
  "messageCount": 1,
  "acknowledged": true,
  "messages": [
    {
      "messageId": "12345",
      "publishTime": "2026-05-15T00:00:00Z",
      "attributes": {
        "source": "scheduler"
      },
      "data": "hello world",
      "dataEncoding": "utf8",
      "ackId": "...",
      "deliveryAttempt": 1,
      "orderingKey": ""
    }
  ]
}
```

## Acknowledgement behavior

This plugin always acknowledges successfully pulled messages before returning.
There is no unacked read mode, no ack-deadline mutation, and no separate ack
tool.

If you need different redelivery timing, configure the subscription itself:

- subscription ack deadline
- retry policy
- dead-letter topic

Those are subscription-level concerns and should stay outside the plugin.

## Resilience

The REST client retries on `408`, `429`, and `5xx` responses using exponential
backoff with full jitter.

## Development

```bash
npm install
npx tsc -p tsconfig.json --noEmit
npx vitest run
PUBSUB_TEST_PROJECT=your-gcp-project-id \
PUBSUB_TEST_TOPIC=your-topic \
PUBSUB_TEST_SUB=your-subscription \
RUN_PUBSUB_INTEGRATION=1 npx vitest run test/integration.test.ts
```

Set `PUBSUB_TEST_PROJECT`, `PUBSUB_TEST_TOPIC`, and `PUBSUB_TEST_SUB` to point
the integration test at the Pub/Sub resources you want to exercise.

tools