Beyond The Basics: Federation, Custom Runtimes, Contributing Back

You've deployed OpenClaw, instrumented it, and locked it down. The natural growth paths from here are sideways, not up: federate across machines so each soul lives where its data lives, swap the LLM provider so each soul uses the right brain for its work, and contribute the patches your real-world use produces back to the project so other people benefit and your fork doesn't drift forever.

Federation: multiple machines, one mission control

Real life rarely fits on one host. The inbox-triage soul should sit at home (private inbox, sensitive). The weather-summary soul wants the cheap VPS (public data, doesn't matter who reads). The on-call escalation soul belongs in the cloud (public webhook, must answer fast). Claworc — OpenClaw's orchestration layer — lets each soul live on its appropriate host while a single Mission Control pane shows them all.

# claworc-federation.yaml — three hosts, one control plane
federation:
  control_plane: home.example.com:8081

  nodes:
    - name: home
      address: home.example.com:8082
      souls: [inbox-triage, finance-bookkeeper]    # private data
      trust: high

    - name: vps-public
      address: vps.example.com:8082
      souls: [weather-brief, social-summary]       # public data only
      trust: low

    - name: vps-fast
      address: oncall.example.com:8082
      souls: [escalation-router]                   # latency-sensitive
      trust: medium

# Souls do NOT migrate between nodes. Data sensitivity dictates placement.

Custom runtimes: swap the brain

OpenClaw's LLM provider is a pluggable interface. Default is Ollama (local). Built-in alternates include OpenAI-compatible (any provider that speaks the OpenAI API: vLLM, llama.cpp server, Together, Groq), Anthropic, and Google. You can register a custom provider by implementing the LLMBackend trait — useful for routing through a corporate AI gateway, hitting a niche provider, or instrumenting requests for billing.

Building a custom backend

When the built-in providers don't fit — say you're routing through an internal gateway that needs custom auth — you implement the LLMBackend interface. Three methods: `chat(messages, tools)` for the model call, `embed(texts)` for embeddings, and `health()` for the readiness probe Mission Control polls. The reference implementations (ollama-backend, openai-backend) are 200-300 lines each — short enough to read end-to-end before forking.

// llm-backend.ts — the interface a custom provider must satisfy
export interface LLMBackend {
  name: string;                                    // 'mycorp-gateway'
  chat(req: ChatRequest): Promise<ChatResponse>;   // model call
  embed(req: EmbedRequest): Promise<EmbedResponse>;// optional, for memory
  health(): Promise<{ ok: boolean; latencyMs: number }>;
}

// Register at startup so souls can target it.
// openclaw.config.ts:
import { registerBackend } from '@openclaw/runtime';
import { MyCorpGatewayBackend } from './backends/mycorp.js';
registerBackend(new MyCorpGatewayBackend({
  endpoint: process.env.MYCORP_GATEWAY_URL!,
  apiKey: process.env.MYCORP_GATEWAY_KEY!,
}));

Contributing back: the etiquette

OpenClaw is open source. If you fix a real bug, harden a real edge case, or add a backend more people will want, send the PR. Maintainers' time is the bottleneck; a clean, narrow PR gets merged in days. A 4,000-line 'massive refactor' PR sits for months and helps no one. Contribute the way you'd want a stranger to contribute to your project.

1. 1Open an issue first for anything bigger than a typo. Confirm the maintainer wants the change before you write it.
2. 2Keep PRs scoped — one bug, one feature. If you found three bugs, send three PRs.
3. 3Match the project's code style and tests; don't reformat the world.
4. 4Write the test that fails without your fix and passes with it. PRs without tests linger.
5. 5Update the docs in the same PR. A feature without docs is a feature most users won't find.
6. 6Be patient on review. Maintainers have day jobs. A polite ping after two weeks is fine; nagging at day three is not.

Three good first contributions

• Documentation: the deployment / observability / security pages always lag the code. If you set up something undocumented, write the doc.
• A new built-in skill: clean, well-tested, useful to many. The skill registry has a contribution guide; follow it.
• Backend support for a provider that ships an OpenAI-compatible API: usually 50-150 lines of glue plus tests.

Apply: pick one stretch this month

1. 1Identify the one soul whose host placement is wrong (sensitive on cheap VPS, or fast soul on a Pi). Federate it.
2. 2Identify one soul that's running on the wrong-cost model (cheap soul on Opus, or quality-critical soul on a 3B). Swap.
3. 3Identify one bug or doc gap you've already worked around in your fork. Send the PR upstream.

The big idea: federation puts each soul where it belongs, custom runtimes put each soul on the right brain, and contributing back keeps your real-world experience flowing into the project everyone benefits from.