OpenClaw Control Plane

Canonical markdown page for this topic. Rendered reference version: openclaw-control-plane.

Last Updated: 2026-03-22 (current-truth refresh) Status: Active architecture reference

This document describes how OpenClaw is currently controlled inside Jorvis and the boundary conditions for any separately authorized extension beyond the adopted control plane.

Use this doc for:

current request-routing truth
capability routing boundaries
bridge vs Jorvis-side responsibility
operator trust / pending-work boundary references
non-adopted control-plane surfaces

Do not use this doc as a deploy runbook or as a security implementation checklist.

For the concrete operations-facing usage model, use:

docs/operations/OPENCLAW_OPS_COPILOT.md

For the canonical operator approval / trust / pending-work boundary, use:

docs/architecture/OPENCLAW_OPERATOR_FLOW_BOUNDARY.md

Current Control Path

Today the effective control path is:

Open WebUI
  -> persisted OpenClaw Pipe (openclaw_bridge.py)
  -> secret-exfiltration guard (runs before any API call)
  -> typed Jorvis capability resolution (POST /api/v1/internal/openclaw-capabilities/resolve)
     or local keyword-heuristic fallback on failure
  -> role/memory-scope derivation
  -> optional admin snapshot enrichment
  -> OpenClaw REST gateway

Current primary source files:

analytics-platform/deploy/openwebui/functions/openclaw_bridge.py
analytics-platform/src/internal/openclaw-capabilities.types.ts
analytics-platform/src/internal/openclaw-capabilities.service.ts
analytics-platform/src/internal/openclaw-capabilities.controller.ts
analytics-platform/src/internal/admin-copilot.service.ts
analytics-platform/src/internal/openclaw-memory.*

Current Responsibilities by Layer

Open WebUI bridge (`openclaw_bridge.py`)

Current bridge responsibilities include:

extracting user role
deriving tenant namespace
enforcing secret-exfiltration guard (runs first, before any external call)
calling Jorvis typed capability resolve endpoint (POST /api/v1/internal/openclaw-capabilities/resolve)
falling back to local keyword-heuristic capability detection on endpoint failure
deriving session key and memory scope (from typed result or local fallback)
enforcing role guard
injecting non-mutating admin context
proxying requests to the OpenClaw gateway
sanitizing sensitive output patterns

Current canonical capability IDs (from Jorvis typed surface):

help_reference
jorvis_explainer
personal_work_assistant
admin_monitoring
admin_improvement
admin_change_plan

Current canonical execution modes: chat, advisory, plan_only Current canonical memory scopes: reference, user, admin

Important current-state note:

the bridge now delegates canonical capability routing to the Jorvis typed surface
the local keyword heuristic is retained as a safe fallback path only
this is the intended architecture direction from Phase 1 + Phase 2

Jorvis internal typed capability surface

Current internal typed capability surface (PR #407):

GET /api/v1/internal/openclaw-capabilities — list all capability descriptors
POST /api/v1/internal/openclaw-capabilities/resolve — resolve capability from role + text input
Returns: capabilityId, executionMode, memoryScope, requiresAdmin, optional matchedSignals
Non-admin requests cannot receive admin-only capabilities (enforced server-side)

Jorvis internal admin-copilot

Current internal admin-copilot surface provides (PR #415 + #416):

non-mutating snapshot with memory, capabilities, and bridgeIntegration fields
non-mutating recommendations with structured findings
plan-only change-plan endpoint

bridgeIntegration snapshot fields (server-side truth, PR #416):

capabilityResolveEnabled — whether ENABLE_CAPABILITY_RESOLVE is not explicitly false
capabilityResolveAvailable — whether the capability registry has entries (server-side endpoint functional)
mode — derived: 'effective' | 'disabled' | 'no_capabilities'

Note: capabilityResolveConfigured (old field, was a false positive) is removed as of PR #416. On healthy prod: mode='effective', recommendations return [SYSTEM_HEALTHY_BASELINE] only.

Current boundary:

OpenClaw consumes admin snapshot enrichment and typed capability resolution
OpenClaw does not yet execute approved mutation tools through a gateway
plugin trust and pending-work ownership remain outside bridge/admin-copilot runtime authority

OpenClaw gateway

The OpenClaw gateway remains the model/runtime execution surface. It is not the canonical place for Jorvis governance policy.

Agent Scratchpad and Write Isolation

The OpenClaw execution environment includes an Agent Scratchpad. Agents are now permitted to write final reports using the write_agent_report tool into the dedicated jorvis.agent_reports table. The rest of the database remains strictly Read-Only, enforced by SqlGuard.

Current Control Truth

What is true now

OpenClaw is exposed to users through openclaw_agent.
Role-aware behavior exists today.
Admin behavior is still advisory/non-mutating in practice.
Secret and role guardrails are enforced in the bridge; secret guard runs before the typed capability call.
The Jorvis-side typed capability registry exists and the bridge already consumes it (PR #407 + #410 + #414).
Canonical capability resolution is now Jorvis-side; the local keyword heuristic is a fallback path only.
Admin-copilot snapshot includes memory, capabilities, and bridgeIntegration fields (PR #415 + #416); mode='effective' on healthy prod.
The persisted openclaw_agent function in OpenWebUI DB has been manually synced to repo source; canonical capability IDs, secret guard, and typed resolve path are live.
Bridge sync is a manual operation: openclaw_bridge.py changes must be synced to the OpenWebUI SQLite DB and jorvis-webui restarted. Not automated by post-merge-prod-sync.sh.
False-positive BRIDGE_CAPABILITY_RESOLVE_NOT_CONFIGURED removed as of PR #416; replaced with accurate BRIDGE_CAPABILITY_RESOLVE_DISABLED (fires only when explicitly disabled).

What is not true yet

There is no approved mutation tool gateway.
There is no multi-agent OpenClaw binding model enabled for Jorvis runtime.
There is no channel expansion control plane beyond the current WebUI surface.

Control-Plane Boundary Rule

The adopted control-plane rule is:

keep the bridge thin
move canonical capability/policy truth into Jorvis-side typed surfaces
preserve OpenClaw as assistant/copilot, not governance authority
keep guarded operator tooling outside the current runtime unless explicit approval and rollback contracts exist

If additional operator tooling is separately approved, it should preserve the same layering:

Open WebUI bridge
  -> Jorvis-side typed capability/control surface
  -> Jorvis-side guarded tool gateway
  -> OpenClaw runtime execution

Why This Matters

If capability truth stays only in the bridge:

policy is harder to audit
behavior is harder to evolve safely
admin/operator expansion becomes riskier
multi-agent/channel expansion will duplicate logic instead of centralizing it

Ops-Copilot Implication

Because the bridge still owns effective runtime capability decisions today:

OpenClaw is useful in ops as a non-mutating/advisory copilot
OpenClaw is not yet a trustworthy execution authority
dry-run/apply/rollback behavior remains outside the adopted current runtime

Non-Adopted Surfaces

Phase 1 (typed capability surface) and Phase 2 (bridge consumption) are complete.

The following are outside the adopted current runtime:

guarded tool gateway for dry-run/apply/rollback:
- read_only
- dry_run
- approved_apply
- rollback
narrower separation between assistant modes through structured tool classes
multi-agent or channel expansion building on the typed capability surface
any later operator-tooling work must remain consistent with OPENCLAW_OPERATOR_FLOW_BOUNDARY.md

Do not document these as current runtime truth unless runtime and internal surfaces actually exist.

docs/security/OPENCLAW_SECURITY_MODEL.md
docs/architecture/OPENCLAW_OPERATOR_FLOW_BOUNDARY.md
docs/architecture/ROLE_AND_CAPABILITY_MATRIX.md
docs/operations/OPENCLAW_OPS_COPILOT.md
docs/operations/OPENWEBUI_MODEL_SETUP.md
docs/architecture/MULTI_AGENT_ARCHITECTURE.md