Skip to content

README.md

Latest commit

 

History

History
147 lines (109 loc) · 7.92 KB

README.md

File metadata and controls

147 lines (109 loc) · 7.92 KB
Raw

Paso4 OpenClaw Plugins

A monorepo of reusable OpenClaw plugins, published on ClawHub so they can be installed across environments with a single command. Plugins are built and versioned here, then consumed by OpenClaw gateways.

About Paso4

Paso4 builds managed agent infrastructure on top of OpenClaw. We maintain this repository as the public home for the plugins we run in production, so the wider OpenClaw community can install the same building blocks. The plugins are free for non-commercial use; commercial use is limited to vendors and partners that Paso4 has authorized in writing. See LICENSE.

Coming from ClawHub?

ClawHub lists plugins by package. This repository is the source of truth for the Paso4-published ones. The folder layout mirrors the OpenClaw plugin shapes, so you can find a plugin by the kind of capability it adds:

OpenClaw plugin shape Directory What lives here
Provider plugin plugins/provider/ Model, media, search, fetch, speech, and realtime providers
Channel plugin plugins/channel/ Messaging-platform integrations
Tool plugin plugins/tool/ Agent tools and output contracts
CLI backend plugin plugins/cli-backend/ Local AI CLI backends exposed through model fallback
Feature plugin plugins/feature/ Typed operations, native pages, Control UI replacements

A plugin therefore lives at plugins/<shape>/<plugin-name>/.

Published plugins

Plugin Shape ClawHub package
cloudflare-unified-billing Provider @paso4/cloudflare-unified-billing

Install a plugin

Install through ClawHub (recommended):

openclaw plugins install clawhub:@paso4/cloudflare-unified-billing
openclaw plugins inspect cloudflare-unified-billing --runtime --json

Or from a local checkout while developing:

bun run --cwd plugins/provider/cloudflare-unified-billing build
openclaw plugins install "$PWD/plugins/provider/cloudflare-unified-billing" --force --accept-capabilities

Development

Requirements: Bun 1.3+, Node 24+ (the OpenClaw runtime), and the openclaw CLI when running live integration tests.

bun install                 # install workspaces
bun run list:plugins        # list discovered plugins and their versions
bun run build               # build every plugin
bun run test                # unit tests for every plugin
bun run typecheck           # tsc --noEmit per plugin
bun run verify              # format + lint + version policy + typecheck + tests

To work on one plugin:

bun run --cwd plugins/provider/cloudflare-unified-billing test
bun run --cwd plugins/provider/cloudflare-unified-billing test:watch

Live integration tests

Integration tests make real, paid calls to providers and are gated behind an explicit opt-in. They never run on pull requests.

cd plugins/provider/cloudflare-unified-billing
cp .dev.vars.example .dev.vars   # fill in Cloudflare AI Gateway credentials
PLUGIN_LIVE_TESTS=true bun run test:integration

The develop CI job sets PLUGIN_LIVE_TESTS=true and passes credentials from repository secrets. Everywhere else the suite skips itself.

Versioning policy

The repository ships one global version. Its base always matches the compatible OpenClaw version declared in the root package.json → catalog.openclaw:

catalog.openclaw = "^2026.9.6"   →   global version base = 2026.9.6

Changesets records change intent: every change to a plugin must include a .changeset/*.md entry. On release, bun run version consumes the changesets into each plugin's CHANGELOG.md and then scripts/sync-versions.mjs stamps the global version onto:

  • every plugin package.json → version
  • every plugin package.json → openclaw.minOpenclawVersion
  • every plugin openclaw.plugin.json → version

bun run verify:versions fails if any of those drift. When OpenClaw is bumped, update catalog.openclaw and run bun run sync:versions — the version and the compatibility declaration move together.

Multiple releases can ship against the same OpenClaw version by appending a build suffix (2026.9.6-2); scripts/resolve-release-version.mjs computes it from existing tags and the versions already published to ClawHub, so a manual publish can never be reused by a later release.

CI/CD

Workflow Trigger What it does
test.yml push / PR to develop Detects changed plugins, runs each plugin's unit suite, and runs live integration tests (with secrets) only on develop pushes.
release.yml manual dispatch Applies changesets, stamps the global version, commits, tags v<version>, creates the GitHub Release, then dispatches publish.yml.
publish.yml dispatch / Release Resolves the plugins affected by the release (from the consumed changesets) and publishes only those; the plugin input overrides this. Builds and packs each plugin (dist/ is not committed), then validates and publishes the ClawPack with the upstream openclaw/clawhub reusable workflow. Also runs as a workflow_dispatch dry-run.

Required repository secrets: CLAWHUB_TOKEN (ClawHub publish) and the AI Gateway credentials used by live tests. Releases and publishes use the autogenerated GITHUB_TOKEN — no PAT required. Without CLAWHUB_TOKEN, publish runs are limited to dry-runs.

Contributing

  1. Add or update a plugin under plugins/<shape>/<name>/.
  2. Keep unit tests colocated (src/*.test.ts) and live tests under tests/integration/.
  3. Add a changeset: bun run changeset.
  4. Run bun run verify and open a PR against develop.

Agent guidance lives in AGENTS.md. The OpenClaw migration playbook is available as a skill at skills/openclaw-migration and is driven by the openclaw-updater agent.

License

Source-available under the Paso4 Open Plugin License: free for non-commercial use, with commercial use reserved for Paso4-authorized vendors.