Harness execution contract

Interface contents

• Properties
  • id
  • version
  • mode
• Methods
  • HarnessResolver(harnessId, executionMode)

Overview

A Harness calls the model and runs Agent tools. OpenClaw Control Plane (OCC) selects the Harness from the Agent's Configuration, checks its execution mode, and records the selection in the AgentRevision. A Harness is a runtime. It has no independent OCC resource, Driver registration, or provisioning methods. Compute starts the gateway and routes traffic. A selected Sandbox can provision a dedicated Harness.

Interface

Properties

The revision descriptor records the selection at AgentRevision.harness. All three properties are required.

Methods

Supported topology

Optional sandbox provisioning

Use GET /installation to check capabilities.openclaw.executionModes. A selected Sandbox requires dedicated execution. For dedicated native OpenClaw, it must also support that mode, provision the Harness, and enforce all three containment facets: networking, filesystem, and process. Compute still owns gateway identity and routing.

IAM

Deployment requires deploy on the exact Agent and read on its Configuration in the same Namespace. OCC also authorizes the Agent's selected model credential. The worker rechecks authority and source ownership before runtime effects.

Harness authentication

An Agent draft can have an empty harnessAuth; deployment requires an explicit binding.

For embedded OpenClaw, Kubernetes projects the Secret as OPENAI_API_KEY, ANTHROPIC_API_KEY, or OCE_MODEL_API_KEY. A custom provider must reference OCE_MODEL_API_KEY in its Configuration. Dedicated Codex logs in with the key or PAT through stdin. With a selected Credential Gateway, choose a compatible credential_source; deployment rejects Secret-backed and account bindings.

The dedicated gateway does not receive the selected Harness model credential. The revision records source references, never historical Secret bytes. A managed account retains its exact credential reference and Backend ownership. See Agent credential grants and renewal and revocation.

Lifecycle

Admission and immutable execution

OCC records the admitted Configuration and generation, Harness ID, version and mode, Compute identity, and credential binding in the AgentRevision. A Sandbox can transform the runtime Configuration before admission. The stored Configuration remains the author's input.

sequenceDiagram
    actor Caller
    participant OCC
    participant Worker
    participant Compute
    participant Runtime as Gateway and Harness
    Caller->>OCC: Deploy the Agent
    OCC->>OCC: Authorize, resolve Harness, check mode and binding
    OCC-->>Caller: Return accepted AgentRevision
    Worker->>OCC: Claim deployment and recheck authority
    Worker->>Compute: Prepare the admitted revision
    Compute->>Runtime: Start workloads, using Sandbox when selected
    alt Workloads ready and activation still authorized
        Worker->>Compute: Activate the revision
        Worker->>OCC: Record the selected revision and deployment result
    else Startup fails or authority is lost
        Worker->>OCC: Record or retry work according to the failure
    end

Isolation and activation

On Kubernetes, a dedicated Harness and gateway use separate workload identities and storage. A replacement stops earlier dedicated revisions before preparing the new one. Embedded preparation can run while the predecessor serves, but gateway replacement can interrupt service before the new credentials pass the model probe. A failed replacement can leave the Agent unavailable. OCC guards activation so an older retry cannot replace a newer selected revision.

On first dedicated Codex deployment, the gateway waits for Harness plugin status. The deployment convergence deadline bounds that wait. The Agent Service publishes ready endpoints. Use the worker flow for claim, activation, and retirement order.

Startup model checks

On Kubernetes, the process that owns model access probes the primary model. OpenClaw disables tools and fallback. Ordinary dedicated Codex retries a transient failure once, at most 30 seconds per attempt within a 61-second budget including backoff. It does not retry rejected credentials or a protected profile with providerTools: "none". A protected Codex execution with no inference route skips the probe and can serve its local app protocol.

Codex logs codex.model_probe with the attempt, duration, exit status, and final code, omitting tokens and raw provider output. Its default model transport requires a Responses WebSocket upgrade; compatible endpoints use HTTPS streaming. Read the startup wrapper and Compute failure evidence for the retry conditions and terminal codes.

Runtime logging

Dedicated Codex disables native log and metrics export before startup.

For platform-owned logging, admission stamps the runtime log settings after Sandbox configuration. Kubernetes sends gateway JSON console output and Codex stderr to the Collector. Codex stdout carries protocol messages. A trusted Compute Driver can instead declare Driver-managed logging. See observability for collection settings.

Configuration

Installation settings

The Harness has no Driver registration settings. The Installation selects Compute and, optionally, Sandbox. Their capabilities determine which execution modes an Agent can use. See Driver selection and configuration discovery.

Native worker support

Dedicated native OpenClaw requires enforced worker placement and inference on the node. The bundled image supplies these capabilities. For a custom image, the operator can declare support in the Installation startup configuration. The API and worker read this setting at startup. On a qualifying Installation, GET /installation reports capabilities.nativeWorkers.support as pinned-runtime when the pinned runtime supplies support, or custom-image when OCC relies on the operator declaration.

Agent settings

Set these fields when creating or updating an Agent. Deployment saves the resolved settings in a new AgentRevision. An edit to the Agent or its Configuration takes effect on the next deployment.

Native runtime selection

Select provider/model (model IDs may contain slashes) and agentRuntime.id (openclaw or codex). Agent entries must agree on primary model and Harness. Fallbacks must use that provider and Harness; admission preserves their order.

The model policy resolver selects OpenClaw for no model or an unambiguous built-in provider. OpenAI, Codex, custom and plugin-routed providers require explicit runtime policy. Catalog entries accept full references or IDs after the first slash; each must be a selected primary or fallback. Codex accepts codex, or openai with the Codex plugin enabled for WebSocket app-server transport.

On Kubernetes, a dedicated Codex Gateway with a workspace-node ID or binding path preserves reasoning, thinkingLevelMap, and nonempty compat.supportedReasoningEfforts containing only minimal, low, medium, high, xhigh, max, or ultra. Verify against the runtime/model. Other compat fields, including thinkingLevels, are dropped. No capabilities are inferred.

An embedded or dedicated Gateway cannot start when an active plugin's startup secret input reads an unset variable: Codex appServer.authToken or appServer.headers, or Google webSearch.headers. Kubernetes sets the APP_SERVER_ variables only in a dedicated Codex Gateway, so deployment and Agent save refuse them for other Agents. Deployment also refuses another variable that no Secret binding sets (for ${NAME}, nor an env value OpenClaw applies), unless an Installation Driver adds launch variables. Bind a Secret, or remove or disable the entry. OpenClaw reads these inputs only in an entry keyed by the exact plugin ID, such as google, not Google. Saves and deployment refuse another spelling of a codex or acpx key, such as Codex, and on Kubernetes of file-transfer or a managed plugin: OpenClaw merges it into that entry, which OCE checks only at the exact key. For the same reason, saves, Agent save and deployment refuse a models.providers key with surrounding whitespace, or another spelling of openai, anthropic or codex, such as OpenAI. On Kubernetes, Configuration save, Agent save and deployment also refuse a reference OpenClaw cannot read in any active plugin's secret input, including an enabled Beam or IMAP entry: a SecretRef without a provider, a provider that secrets.providers does not configure (the default env alias needs no entry), an env id that does not start with a letter and use only A-Z, 0-9 and _ (at most 128 characters), or an id that the env provider's allowlist omits. The allowlist applies to $NAME and SecretRef objects. OpenClaw substitutes a set ${NAME} first, so the allowlist applies to it only when the variable is unset. Deployment then refuses an unbound ${NAME} that the allowlist omits at an enabled Beam or IMAP entry. Deployment and Agent save refuse such a ${APP_SERVER_*} there for Agents other than dedicated Codex, where it is always unset. On every Compute, Configuration save, Agent save and deployment apply the same provider and allowlist rules to a gateway.auth.password SecretRef. They also refuse one with keys other than source, provider and id, because OpenClaw's configuration check then fails. The same check fails on a secrets.defaults that is not an object, that holds a key other than env, file, exec or store, or that holds an alias outside OpenClaw's alias grammar, such as " custom " or "BAD", so the same steps refuse these too. OpenClaw substitutes an alias written as ${NAME} or ${NAME:-fallback} before that check, so OCE leaves such an alias, and any SecretRef rule that depends on it, to OpenClaw.

Configuration writes run these rules in deployment's order and refuse conflicting settings with deployment's message: an entry primary that differs, selectable models on another provider or runtime, an unselected catalog entry, conflicting runtime policies, an unsupported runtime ID, or Codex on another provider. Each message names the settings to change and, for a runtime, the allowed values openclaw and codex. A draft without a model, or a model without its required runtime, still saves; deployment refuses it and names the setting to add: agents.defaults.models["<ref>"].agentRuntime.id for a missing runtime, and on Kubernetes Compute agents.defaults.model for a missing model. A missing runtime names a setting that keeps the selectable rule: the entry's agents.entries.<id>.models policy when it lists the model or sets the primary's runtime, or the model's provider catalog entry or provider when the primary's runtime comes from there. A missing or conflicting runtime offers only values that deployment accepts: codex only where Codex accepts the model, and the runtime that the other selected models, the listed models, or another policy already select. Deployment and Agent provisioning also check the Agent: for a dedicated Agent where the Installation does not list dedicated OpenClaw, the refusal offers only codex where Codex accepts the model. Deployment of an embedded Agent, where the Installation approves Codex only for dedicated execution, offers only openclaw. Embedded OpenClaw cannot run a codex/<model> model either, so that refusal says to set codex on a dedicated Agent or to select another provider's model. For Codex on another provider, the refusal offers only the step that the Agent can take: a codex/<model> model or openclaw. Configuration save can serve any Agent, so it offers both values. A Preset is checked when a launch creates its Configuration.

Limits

• One dedicated Harness serves all sessions for an AgentRevision. OpenShell contains the revision. The native OpenClaw node defaults to eight retained session workers on Kubernetes. Set runtime.nativeOpenClawSessionCapacity to an integer from 1 to 1024 to change the limit. At capacity the node refuses additional sessions until a hosted session stops. Codex has no separate OCE session-count limit. OpenClaw's agents.defaults.maxConcurrent bounds active turns.
• A startup model probe can incur charges. A successful probe establishes model access at startup only. SSH checks process readiness. Neither establishes that a fallback model works.
• Retained gateway state does not guarantee recovery of an interrupted turn. Dedicated restart acceptance remains incomplete. For the workload and storage boundaries, see runtime isolation.
• Docker Compute rejects all current Harness authentication bindings and cannot deploy a new Agent. See Docker Compute.

Troubleshooting

Implementations

• OpenClaw runs embedded in the gateway or as the dedicated native node. See Kubernetes execution modes, SSH Compute, and the OpenShell qualification contract.
• Codex runs as a dedicated app-server. See remote Harness execution and split storage for deployment and workspace placement.

Related

• Harness execution and shared storage flow
• ComputeDriver contract and SandboxDriver contract
• Agent identity and deployment
• ServiceAccount credentials