claw3d/docs/integrations/custom-provider-reference.md

Custom Provider Reference

Reference implementation guide for plugging a non-OpenClaw, non-Hermes runtime into Claw3D through the upstream-safe custom provider seam.

Goal

Show how a custom orchestration stack should plug into Claw3D without requiring:

• a named built-in provider
• OpenClaw emulation
• Hermes adapter semantics

The shape should be:

• Claw3D sees custom
• the external runtime stays implementation-specific
• Claw3D core remains generic

Current Implementation Notes

The current custom branch path is deliberately conservative.

What exists today:

• provider selection and metadata flow through the Studio runtime seam
• same-origin runtime proxying through /api/runtime/custom
• health, state, and registry probing
• direct chat via /v1/chat/completions
• office/bootstrap/chat/model loading routed through the provider layer

What still needs to mature:

• true provider-native streaming
• stronger multi-session persistence semantics
• integration tests against a live custom runtime
• richer office presentation of runtime metadata, lanes, and model identity

Position

A custom runtime should sit at the Claw3D boundary as an orchestrator-backed service.

That means:

• Claw3D should talk to one stable runtime boundary
• that boundary may route work to internal worker processes, models, or lanes
• those internal details should remain mostly hidden behind the provider

This keeps the integration:

• stable
• upstream-safe
• reusable for multiple custom stacks later

Why The Custom Provider Exists

Not every useful runtime should need a named upstream provider branch.

Some stacks will be:

• internal
• experimental
• organization-specific
• built around custom orchestration

The custom provider exists so those stacks can integrate cleanly without forcing Claw3D core to absorb stack-specific assumptions.

Recommended Boundary

Claw3D should integrate with the custom runtime's orchestrator or gateway layer, not with its individual workers.

Recommended public boundary:

• POST /v1/chat/completions
• POST /v1/completions
• POST /v1/contracted-completions
• GET /health
• GET /state
• GET /registry

These do not need to be mandatory for every implementation, but they are a strong reference shape because they provide:

• chat entry points
• reachability
• runtime summary
• model or role registry visibility

Runtime Shape

Recommended mapping:

Claw3D
  -> custom provider
    -> custom orchestrator / gateway
      -> internal routing
        -> workers / roles / models / tools

This means the custom provider should not need to know:

• worker ports
• shard startup semantics
• internal runtime policy
• proprietary state heuristics

It only needs:

• request/response surfaces
• route or session metadata
• health/state/registry metadata

Provider Identity

Upstream-facing identity should remain:

• providerId: "custom"

Implementation-specific identity should appear as metadata, not provider class naming.

Suggested metadata:

type CustomRuntimeMetadata = {
  id: "custom";
  label: "Custom Runtime";
  runtimeName?: string | null;
  vendor?: string | null;
  runtimeVersion?: string | null;
  routeProfile?: string | null;
};

This gives the UI enough identity without forcing upstream Claw3D to branch on every runtime brand.

Capability Profile

Initial custom provider capability claims should be conservative and honest.

Likely V1 support for many custom runtimes:

• agents
• sessions
• chat
• streaming
• agent_roles
• config

Possible later support depending on implementation:

• files
• approvals
• skills
• cron
• session_settings

Important rule:

Do not claim support just because the backend can theoretically do something. Claim support only where the provider exposes a stable Claw3D-facing behavior.

Agent Mapping

Claw3D agents should not be modeled as one fixed backend process each unless the runtime truly behaves that way.

Instead, a custom runtime may map agents to:

• roles
• lanes
• strategies
• departments
• routed execution identities

Example office-facing identities:

• Main
• Assistant
• Coder
• Reviewer
• Professor

The exact labels are implementation-specific.

The important point is that the provider should expose office-meaningful identities rather than leaking raw backend topology.

Session Mapping

Claw3D sessions should map to runtime conversations or execution threads, not to whichever backend storage structure happens to exist internally.

Recommended session metadata:

• sessionKey
• conversation or thread id
• active role
• lane
• requested model
• resolved model
• request id

The provider should normalize these into a stable session model no matter what the backend calls them internally.

Event Mapping

The provider should translate runtime activity into the same normalized Claw3D runtime events used elsewhere.

Recommended mappings:

• runtime agent change -> presence.changed
• conversation/session update -> session.activity
• streaming token output -> chat.delta
• final assistant turn -> chat.final
• routed or backend failure -> chat.error
• request lifecycle -> run.lifecycle
• tool or workflow progress -> tool.progress

Implementation-specific metadata is allowed, but only as additive metadata.

Route Metadata

Many custom runtimes will have useful execution metadata.

The provider may expose optional metadata such as:

• selected role
• candidate roles
• lane
• routing reason
• registry profile
• resolved model id
• worker or runtime health summary

This metadata should be visible in diagnostics or advanced panels, not required for basic user flow.

State And Health Surfaces

The custom provider should prefer orchestrator-level health/state queries first.

Recommended usage:

• /health
  • basic runtime reachability
• /state
  • route profile, active roles, worker/runtime summary
• /registry
  • active model, role, or profile catalog

Worker-level status endpoints should stay behind the provider unless the UI needs a diagnostic drill-down.

Relationship To Agent State

The custom provider is the right place to map richer internal runtime signals into Claw3D's public office state model.

Public office state should remain simple:

• focused
• working
• blocked
• overloaded
• degraded

Internally, a custom stack may derive those from richer signals such as:

• route stress
• worker saturation
• runtime policy
• confidence or control signals
• proprietary orchestration heuristics

That should remain implementation-private.

Claw3D only needs the resulting office-safe state and maybe a public reason label.

Relationship To Office Systems

The custom provider should support office systems without Claw3D needing to know the backend's internals.

Examples:

• bulletin board gets agent/session/task context
• whiteboard gets planning-session context
• meetings get coordination state
• QA gets review or readiness metadata

Again, the provider should expose only what the office needs.

Suggested V1 Scope

Recommended first custom provider scope:

1. Reach the custom orchestrator over /v1/chat/completions.
2. Pull metadata from /health, /state, and /registry.
3. Map runtime roles or routes into Claw3D agent identities.
4. Surface streaming and final turns.
5. Expose route metadata in a diagnostics-friendly way.
6. Map simple public office states from observable runtime conditions.

This is enough to make a custom runtime useful in Claw3D without overexposing internals.

Suggested V2 Scope

Once the V1 provider is stable, add:

• richer session persistence
• role-aware office teams
• custom runtime diagnostics panel
• office state enrichment from internal stack signals
• hooks into bulletin board, whiteboard, QA, and meeting systems

Explicit Non-Goals

This reference should not require:

• runtime-specific branches throughout Claw3D core
• OpenClaw compatibility shims
• routing logic duplicated in the frontend
• direct worker orchestration in the browser

The provider should remain the containment layer.