USER MANUAL · SYSTEM

Connectors

Connect ClawButler to OpenClaw gateways and Runtime Hosts. OpenClaw remains the fully supported connector path; Hermes / Claude Code / Codex currently enter through runtime-host discovery and attach-mode sync.

/connectors

Overview#

The Connectors page now covers three paths: pair a Runtime Host for cloud and local-runtime discovery, add an OpenClaw connector manually for self-hosted or advanced environments, or use local scan-local as a legacy convenience for nearby OpenClaw instances.

Runtime Hosts can discover Hermes, Claude Code, Codex, and OpenClaw instances on a paired machine. After discovery, you choose which instances become connectors and, when supported, sync attach-mode sessions into ClawButler. OpenClaw remains the only fully supported provider-native connector path.

Prerequisites#

Prerequisites

A ClawButler account and access to the machine or gateway you want to govern
For Runtime Host pairing: the `/pair?kind=runtime-host&code=...` link or pair code shown in ClawButler
For manual OpenClaw connectors: gateway URL and operator token

Access Model and Support Boundary#

For cloud users, the recommended path is Runtime Host pairing. Approve the machine from the pair screen, then return to Connectors to run discovery against that paired host.

For self-hosted or advanced environments, manual OpenClaw connectors are still supported. Local `scan-local` remains a convenience path for older or nearby OpenClaw setups, not the primary onboarding path.

Current support boundary

OpenClaw is still the only fully supported connector path. Hermes / Claude Code / Codex currently support discovery, connector creation, and attach-mode session sync only. Provider-native approvals, cost attribution, timelines, and managed control are not yet shipped for those runtimes.

Setup Flow in ClawButler#

Choose the path that matches your environment: Runtime Host pairing for cloud, local scan-local for legacy nearby OpenClaw setups, or manual connector entry for self-hosted and advanced cases.

Path A: Pair a Runtime Host (recommended for Cloud)

Open the pair flow (`/pair?kind=runtime-host&code=...`) on the target machine, approve the Runtime Host, then return to Connectors and run Discover.

Path B: Local `scan-local` for legacy OpenClaw setups

Use local scan when you already run OpenClaw on the same machine or LAN and want a quick import path. This is still useful for legacy local setups, but it is not the primary cloud onboarding flow.

Path C: Manual connector for self-hosted / advanced environments

Click `Add Connector`

Use this path when you already know the gateway URL and operator token, or when scan-local cannot reach the target OpenClaw deployment.

Fill in the gateway details

Enter a descriptive name, the WebSocket URL, and the operator token.

Test and diagnose

Use Test first. If needed, run Diagnosis / Security Check before saving the connector into regular use.

Sync and verify

Run Sync to discover agents, then confirm the connector card, agent count, and any projected sessions.

Expected Results#

After pairing or adding a connector, you should see:

Runtime Host cards or connector cards showing status, last seen / last sync, and supported providers
Discovered Hermes / Claude Code / Codex / OpenClaw instances before batch-add, or synced agent counts for manual OpenClaw connectors
Selected runtime instances becoming connectors in the main connector list
Attach-mode sessions available for sync where the runtime provider supports projection

Web Operations#

Open `Connectors` from the System section. This page now contains both connector management and runtime-host operations.

Common actions on this page:

Pair / Approve — authorize a machine as a Runtime Host
Discover — scan one paired Runtime Host for Hermes / Claude Code / Codex / OpenClaw instances
Add Selected — create connectors only for chosen discovered instances
Sync Sessions — project attach-mode runtime sessions into ClawButler
Test / Diagnose — validate connector health and investigate issues
Edit / Delete — adjust stored connector details or remove an unused entry

Runtime Host workflow

The typical web loop is Pair Runtime Host → Discover → Add Selected → Sync Sessions. IM channel operations still live on connector cards for OpenClaw connectors when those channels are configured.

CLI Operations#

CLI covers both sides of the page: Runtime Host intake and traditional connector operations.

Terminal

$ ap runtime-host list

List paired runtime hosts and check which providers each host can discover

Terminal

$ ap runtime-host discover <runtime-host-id>

Run discovery on one paired host and inspect Hermes / Claude Code / Codex / OpenClaw instances

Terminal

$ ap runtime-host batch-add <runtime-host-id> --instance-key <instance-key>

Create connectors only for selected discovered runtime instances

Terminal

$ ap runtime-host sync-sessions <runtime-host-id> --instance-key <instance-key>

Project attach-mode sessions from selected runtime instances into ClawButler

Terminal

$ ap connector discovery scan-local

Discover nearby or local OpenClaw candidates for the legacy scan-local path

Terminal

$ ap connector discovery import-local --candidate-url http://127.0.0.1:8080 --name local-dev

Import one discovered OpenClaw candidate as a connector

Terminal

$ ap connector list

List all connectors created from manual entry, discovery import, or Runtime Host batch-add

Terminal

$ ap connector test <id>

Test connectivity to a specific connector

Terminal

$ ap connector sync <id>

Re-sync agents or connector state from an OpenClaw connector

Terminal

$ ap connector security-check <id>

Run security checks on a connector

Terminal

$ ap connector diagnosis <id>

Run diagnostics on a connector

Mobile Operations#

Mobile can inspect connector health and synced state, but it does not currently expose a user-facing Runtime Host pairing entry.

Use Web or CLI for Runtime Host pairing, discovery, batch-add, and session sync. Mobile remains read-oriented for connector status.

FAQ#

Q: What is the difference between a Runtime Host and a connector?

A: A Runtime Host is the paired machine that can run discovery. A connector is the governed record created after you select a discovered instance or add an OpenClaw gateway manually.

Q: What do Hermes / Claude Code / Codex support today?

A: Today they support discovery, connector creation, and attach-mode session sync. They do not yet support the full OpenClaw-native approval, cost, timeline, or managed-control surface.

Q: When should I use scan-local or manual connectors instead of Runtime Host pairing?

A: Use Runtime Host pairing for cloud and modern local-runtime discovery. Use scan-local for older nearby OpenClaw setups, and use manual connectors when you already know the remote gateway URL/token or need advanced self-hosted control.