Agent harness plugins

An agent harness is the low level executor for one prepared OpenClaw agent turn. It is not a model provider, not a channel, and not a tool registry. For the user-facing mental model, see Agent runtimes.

Use this surface only for bundled or trusted native plugins. The contract is still experimental because the parameter types intentionally mirror the current embedded runner.

When to use a harness

Register an agent harness when a model family has its own native session runtime and the normal OpenClaw provider transport is the wrong abstraction.

Examples:

• a native coding-agent server that owns threads and compaction
• a local CLI or daemon that must stream native plan/reasoning/tool events
• a model runtime that needs its own resume id in addition to the OpenClaw session transcript

Do not register a harness just to add a new LLM API. For normal HTTP or WebSocket model APIs, build a provider plugin.

What core still owns

Before a harness is selected, OpenClaw has already resolved:

• provider and model
• runtime auth state
• thinking level and context budget
• the OpenClaw transcript/session file
• workspace, sandbox, and tool policy
• channel reply callbacks and streaming callbacks
• model fallback and live model switching policy

That split is intentional. A harness runs a prepared attempt; it does not pick providers, replace channel delivery, or silently switch models.

The prepared attempt also includes

, an OpenClaw-owned policy bundle for runtime decisions that must stay shared across PI and native harnesses:

• text

  Copy

  runtimePlan.tools.normalize(...)
  and
  text

  Copy

  runtimePlan.tools.logDiagnostics(...)
  for provider-aware tool schema policy
• text

  Copy

  runtimePlan.transcript.resolvePolicy(...)
  for transcript sanitization and tool-call repair policy
• text

  Copy

  runtimePlan.delivery.isSilentPayload(...)
  for shared
  text

  Copy

  NO_REPLY
  and media delivery suppression
• text

  Copy

  runtimePlan.outcome.classifyRunResult(...)
  for model fallback classification
• text

  Copy

  runtimePlan.observability
  for resolved provider/model/harness metadata

Harnesses may use the plan for decisions that need to match PI behavior, but should still treat it as host-owned attempt state. Do not mutate it or use it to switch providers/models inside a turn.

Register a harness

Import:

typescript
Copy
import type { AgentHarness } from "openclaw/plugin-sdk/agent-harness";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

const myHarness: AgentHarness = {
  id: "my-harness",
  label: "My native agent harness",

  supports(ctx) {
    return ctx.provider === "my-provider"
      ? { supported: true, priority: 100 }
      : { supported: false };
  },

  async runAttempt(params) {
    // Start or resume your native thread.
    // Use params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent, and the other prepared attempt fields.
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "My Native Agent",
  description: "Runs selected models through a native agent daemon.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});

Selection policy

OpenClaw chooses a harness after provider/model resolution:

1. An existing session's recorded harness id wins, so config/env changes do not hot-switch that transcript to another runtime.
2. text

   Copy

   OPENCLAW_AGENT_RUNTIME=<id>
   forces a registered harness with that id for sessions that are not already pinned.
3. text

   Copy

   OPENCLAW_AGENT_RUNTIME=pi
   forces the built-in PI harness.
4. text

   Copy

   OPENCLAW_AGENT_RUNTIME=auto
   asks registered harnesses if they support the resolved provider/model.
5. If no registered harness matches, OpenClaw uses PI unless PI fallback is disabled.

Plugin harness failures surface as run failures. In

mode, PI fallback is only used when no registered plugin harness supports the resolved provider/model. Once a plugin harness has claimed a run, OpenClaw does not replay that same turn through PI because that can change auth/runtime semantics or duplicate side effects.

The selected harness id is persisted with the session id after an embedded run. Legacy sessions created before harness pins are treated as PI-pinned once they have transcript history. Use a new/reset session when changing between PI and a native plugin harness.

shows non-default harness ids such as next to ; PI stays hidden because it is the default compatibility path. If the selected harness is surprising, enable debug logging and inspect the gateway's structured record. It includes the selected harness id, selection reason, runtime/fallback policy, and, in mode, each plugin candidate's support result.

The bundled Codex plugin registers

as its harness id. Core treats that as an ordinary plugin harness id; Codex-specific aliases belong in the plugin or operator config, not in the shared runtime selector.

Provider plus harness pairing

Most harnesses should also register a provider. The provider makes model refs, auth status, model metadata, and

selection visible to the rest of OpenClaw. The harness then claims that provider in .

The bundled Codex plugin follows this pattern:

• preferred user model refs:
  text

  Copy

  openai/gpt-5.5
  plus
  text

  Copy

  agentRuntime.id: "codex"
• compatibility refs: legacy
  text

  Copy

  codex/gpt-*
  refs remain accepted, but new configs should not use them as normal provider/model refs
• harness id:
  text

  Copy

  codex
• auth: synthetic provider availability, because the Codex harness owns the native Codex login/session
• app-server request: OpenClaw sends the bare model id to Codex and lets the harness talk to the native app-server protocol

The Codex plugin is additive. Plain

refs continue to use the normal OpenClaw provider path unless you force the Codex harness with . Older refs still select the Codex provider and harness for compatibility.

For operator setup, model prefix examples, and Codex-only configs, see Codex Harness.

OpenClaw requires Codex app-server

or newer. The Codex plugin checks the app-server initialize handshake and blocks older or unversioned servers so OpenClaw only runs against the protocol surface it has been tested with. The floor includes the native MCP hook payload support that landed in Codex , while pinning OpenClaw to the newer tested stable line.

Tool-result middleware

Bundled plugins can attach runtime-neutral tool-result middleware through

when their manifest declares the targeted runtime ids in . This trusted seam is for async tool-result transforms that must run before PI or Codex feeds tool output back into the model.

Legacy bundled plugins can still use

for Codex app-server-only middleware, but new result transforms should use the runtime-neutral API. The Pi-only hook has been removed; Pi tool-result transforms must use runtime-neutral middleware.

Terminal outcome classification

Native harnesses that own their own protocol projection can use

from when a completed turn produced no visible assistant text. The helper returns , , or so OpenClaw's fallback policy can decide whether to retry on a different model. It intentionally leaves prompt errors, in-flight turns, and intentional silent replies such as unclassified.

Native Codex harness mode

The bundled

harness is the native Codex mode for embedded OpenClaw agent turns. Enable the bundled plugin first, and include in if your config uses a restrictive allowlist. Native app-server configs should use with . Use for Codex OAuth through PI instead. Legacy model refs remain compatibility aliases for the native harness.

When this mode runs, Codex owns the native thread id, resume behavior, compaction, and app-server execution. OpenClaw still owns the chat channel, visible transcript mirror, tool policy, approvals, media delivery, and session selection. Use

without a override when you need to prove that only the Codex app-server path can claim the run. Explicit plugin runtimes already fail closed by default. Set only when you intentionally want PI to handle missing harness selection. Codex app-server failures already fail directly instead of retrying through PI.

Disable PI fallback

By default, OpenClaw runs embedded agents with

set to . In mode, registered plugin harnesses can claim a provider/model pair. If none match, OpenClaw falls back to PI.

In

mode, set when you need missing plugin harness selection to fail instead of using PI. Explicit plugin runtimes such as already fail closed by default, unless is set in the same config or environment override scope. Selected plugin harness failures always fail hard. This does not block an explicit or .

For Codex-only embedded runs:

json
Copy
{
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.5",
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}

If you want any registered plugin harness to claim matching models but never want OpenClaw to silently fall back to PI, keep

and disable the fallback:

json
Copy
{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "auto",
        "fallback": "none"
      }
    }
  }
}

Per-agent overrides use the same shape:

json
Copy
{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "auto",
        "fallback": "pi"
      }
    },
    "list": [
      {
        "id": "codex-only",
        "model": "openai/gpt-5.5",
        "agentRuntime": {
          "id": "codex",
          "fallback": "none"
        }
      }
    ]
  }
}

still overrides the configured runtime. Use to disable PI fallback from the environment.

bash
Copy
OPENCLAW_AGENT_RUNTIME=codex \
OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run

With fallback disabled, a session fails early when the requested harness is not registered, does not support the resolved provider/model, or fails before producing turn side effects. That is intentional for Codex-only deployments and for live tests that must prove the Codex app-server path is actually in use.

This setting only controls the embedded agent harness. It does not disable image, video, music, TTS, PDF, or other provider-specific model routing.

Native sessions and transcript mirror

A harness may keep a native session id, thread id, or daemon-side resume token. Keep that binding explicitly associated with the OpenClaw session, and keep mirroring user-visible assistant/tool output into the OpenClaw transcript.

The OpenClaw transcript remains the compatibility layer for:

• channel-visible session history
• transcript search and indexing
• switching back to the built-in PI harness on a later turn
• generic
  text

  Copy

  /new
  ,
  text

  Copy

  /reset
  , and session deletion behavior

If your harness stores a sidecar binding, implement

so OpenClaw can clear it when the owning OpenClaw session is reset.

Tool and media results

Core constructs the OpenClaw tool list and passes it into the prepared attempt. When a harness executes a dynamic tool call, return the tool result back through the harness result shape instead of sending channel media yourself.

This keeps text, image, video, music, TTS, approval, and messaging-tool outputs on the same delivery path as PI-backed runs.

Current limitations

• The public import path is generic, but some attempt/result type aliases still carry
  text

  Copy

  Pi
  names for compatibility.
• Third-party harness installation is experimental. Prefer provider plugins until you need a native session runtime.
• Harness switching is supported across turns. Do not switch harnesses in the middle of a turn after native tools, approvals, assistant text, or message sends have started.

Related

• SDK Overview
• Runtime Helpers
• Provider Plugins
• Codex Harness
• Model Providers