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, attach-mode sync, and experimental managed inspection.

/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, sync attach-mode sessions into ClawButler, and inspect experimental managed projections where supported. 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, attach-mode session sync, and experimental managed host-first APIs with read-only managed inspection. Provider-native approvals, cost attribution, timelines, and full 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. Web now includes runtime-host governance summaries and managed write boundary previews directly on host cards, while 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 and combine them with managed inspection where supported

Terminal

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

Read decision, activity, and trace summaries for one runtime host

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 now exposes a user-facing Runtime Hosts tab for pair approval, discovery, batch-add, session sync, and managed session inspection.

Use Web when you need the broadest runtime-host surface and deeper investigation. Mobile is intentionally slimmer, but it is no longer limited to connector-status viewing.

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, attach-mode session sync, and experimental managed inspection. 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.