@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:

{
  "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:

{
  "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

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.