Integration
Connections
By RAW Labs OpenClaw Connections plugin
Install
npm install --frozen-lockfileConfiguration Example
{
"plugins": {
"entries": {
"openclaw-connections": {
"enabled": true,
"config": {
"apiKey": {
"source": "env",
"provider": "default",
"id": "COMPOSIO_API_KEY"
}
}
}
}
}
}README
# OpenClaw Connections
A standalone native OpenClaw plugin with a Connections page and three agent tools:
`connections_search`, `connections_describe` and `connections_call`.
By [RAW Labs SA](https://www.raw-labs.com), distributed under the [MIT license](LICENSE).
Experimental software: host compatibility is narrowly qualified and live provider
acceptance remains unverified. Review the installation requirements and limits below.
The existing OpenClaw Codex harness can expose these tools through its dynamic-tool
bridge when native tool policy allows them; no separate MCP adapter is required.
Use your own Composio project. No separate web server or PostgreSQL database is
required. OpenClaw owns authentication, administrator
roles, agents and tool policy. Composio hosts provider authentication and execution.
The Connections page provides a searchable service picker,
category filters, account status, connect/reconnect, names, agent grants and disconnect.
Usage shows local call activity; billing and quotas belong to your Composio project.
The bundled catalog contains 44 services. Tool definitions are fetched from Composio
when needed; execution uses the exact described version and account generation.
## Install and configure
Requires Node `24.16+` within Node 24, or `26.1+`. The primary OpenClaw target is
source commit `90d30a1178a79dddd92e6190b66b95d89dfb3ca8`, labelled `2026.9.8`,
the revision selected by OCE. The previously qualified published `2026.10.2` host
also remains admitted. Version labels alone are insufficient: the published npm
`2026.9.8` package is an older snapshot that refuses private-plugin state and is
**not supported**. Use the specified source-built host, not that npm package.
The host must provide runtime-bound `openKeyedStore` with `retention: "retained"`,
`registerIfAbsent`, `observe`/`compareAndApply`, `entriesInKeyRange` and action-bound
`withCurrent`. Missing capabilities, denied state access and failed reads stop startup
or the operation; there is no custom-file or bounded-cache fallback. Other revisions
need compatibility verification before use. The source commit and archive checksum
are recorded in [openclaw-host.json](openclaw-host.json).
Download the `raw-labs-openclaw-connections-VERSION.tgz` asset from
[GitHub Releases](https://github.com/raw-labs/openclaw-connections/releases), then install
it into a compatible host:
```sh
openclaw plugins install npm-pack:/absolute/path/to/raw-labs-openclaw-connections-VERSION.tgz --force --accept-capabilities
```
Replace `VERSION` with the selected exact release. Release downloads and source are
public. The `@raw-labs/openclaw-connections` package in GitHub Packages remains private
for existing consumers; no registry credential is needed for the release download.
See [releases and package access](RELEASING.md).
To build the plugin from a source checkout instead:
```sh
pnpm install --frozen-lockfile
pnpm prepare:host
pnpm exec playwright install chromium
pnpm check
pnpm build
pnpm test:native
pnpm artifact
openclaw plugins install npm-pack:/absolute/path/to/package.tgz --force --accept-capabilities
```
Review the package before accepting its native plugin capabilities. Configure
`plugins.entries.openclaw-connections` through native Settings or your OpenClaw config:
```json
{
"plugins": {
"entries": {
"openclaw-connections": {
"enabled": true,
"config": {
"apiKey": {
"source": "env",
"provider": "default",
"id": "COMPOSIO_API_KEY"
}
}
}
}
}
}
```
Supply `COMPOSIO_API_KEY` to the Gateway's environment, then restart it. A terminal
export does not affect an already-running service. Native file/exec SecretRefs are
also supported. Declare their providers in OpenClaw's secrets configuration.
The key is never delivered to the Connections page or agent tool arguments.
With no key configured, Connections stays available and shows configuration guidance.
When OpenClaw isolates an unavailable authored SecretRef, the page and management RPC
remain registered and report its native capability-secret diagnostic. Provider tools stay inactive;
no Connections database is opened and no provider requests are made. Fix the native
secret binding and restart the Gateway. A resolved key enables the capability but does
not prove provider acceptance or account consent; those failures remain visible during use.
Native startup rejection for secret-provider policy or contract violations still applies.
If a configured registration has no running Gateway service, requests report
`runtime_unavailable`, rather than missing-key guidance. Check the Gateway's plugin
lifecycle diagnostics and restart it; re-entering or rotating the key does not resolve
service availability. This diagnostic does not restore an unavailable service. Do not
repeat an external operation to recover an unknown outcome.
Enable custom native Control UI plugins using the pinned OpenClaw build's
`gateway.controlUi.experimental.customPlugins` setting, and accept its native UI consent
when requested. Keep your existing Gateway authentication and tool policy. Installing
this plugin does not enable its tools for restricted agents or widen their policy.
Use a dedicated Composio project with permissions to manage auth configs/accounts and
execute tools. **Its callback identity verifier must be unset** for this standalone
linking flow. The plugin does not host a public verifier callback. Projects requiring
one are unsupported and cannot activate an account through this page.
`userId` is optional: a stable installation identity is created and retained locally.
To use a preselected Composio identity, set it before first activation. Changing it on
retained state fails visibly. This plugin's user ID is an account namespace, not a team
login or proof of a person. Existing project accounts are not imported automatically.
Services with custom auth require an existing configured auth config in Composio:
```json
{
"authConfigIds": {
"your-service-id": "ac_your_existing_configuration"
}
}
```
Merge this map into the plugin config. Managed-auth services resolve or create their
auth config automatically. Provider-specific auth settings remain in Composio.
## Link and use accounts
An OpenClaw administrator opens **Connections**, chooses **Add connection**, selects a
service and opens **Open sign-in**. Approve access in the separate Composio tab, return
to the original OpenClaw browser and choose **Finish connecting**. Only this explicit
confirmation activates the plugin's local grant. Completion checks the exact provider
account, user, toolkit and auth config, plus its originating administrator/browser ticket.
Closing the dialog leaves **Continue** available. Losing the browser ticket requires
cancelling the setup and starting again.
Edit a connection to rename it or restrict it to selected native agents. Reconnecting
disables the old generation before contacting Composio and retires the previous account.
Disconnect blocks execution locally before requesting provider cleanup. A cleanup error
remains visible; access stays disabled. Refresh and retry Disconnect explicitly.
Successful Cancel setup clears the setup's cleanup binding. Remove deletes an inactive
local entry in one action, including any retained account cleanup. Connected Disconnect
keeps a reusable disconnected entry. Failed or uncertain cleanup retains the account
binding and recovery guidance until an explicit retry succeeds. Confirmation here means
Composio account deletion or absence; upstream token revocation may run asynchronously
and is not verified by this plugin.
The three tools perform search, schema description and exact-account execution. Call
lookup and paged results use the same `connections_call` tool. See the bundled
[Connections skill](skills/connections/SKILL.md).
## State and trust
Connections uses OpenClaw's public plugin-scoped retained state SDK. The host owns
`<resolved OpenClaw state directory>/state/openclaw.sqlite` and its SQLite lifecycle.
Persist and back up the canonical OpenClaw state directory using the host's supported
backup procedure; no separate Connections directory or mount is required. State is
scoped by the runtime-bound plugin ID, with versioned identity, registry and receipt
and result namespaces. Each Gateway state directory retains one Composio user identity; selected
agent grants and exact agent/session/call receipt bindings enforce application access.
Do not run multiple Connections service instances or Gateways against the same state:
startup recovery treats unfinished dispatch and setup as interrupted work.
Records include account references, names, grants, pending setup links/ticket hashes
and call receipts/results; they never contain the Composio project key or service
OAuth tokens. Treat backups as sensitive: results can contain connected-service data.
All authoritative namespaces use retained storage without SDK TTL or eviction.
Connection revisions and the 1,000-connection limit share one atomic CAS registry;
the SDK's 1 MiB JSON value limit bounds that registry and each receipt. Result payloads
(up to 8 MiB of serialized JSON) use immutable retained chunks; one receipt CAS
publishes the chunk count, byte length and digest only after every chunk is saved.
A payload write failure records the known outcome without its result and surfaces
the storage error. Pruning removes payload references before deleting expired chunks,
and also removes orphan chunks from interrupted writes. A large
registry can reach the byte limit before 1,000 entries; failed writes are surfaced.
Receipt identities remain indefinitely after payload pruning, so disk use grows with
call history. Receipt scans use bounded SDK pages, but recovery/pruning and result-ID
lookup still scan retained history.
This storage cutover starts fresh: there is no import of an old custom SQLite file,
migration or dual write. E
... (truncated)
integration
Comments
Sign in to leave a comment