Build Custom Agent Harnesses with OpenClaw

Ever felt like the standard LLM provider abstraction is just a bit too restrictive for what you’re building? Sometimes you need more control over the execution loop than a simple API call can offer, especially when you’re dealing with native session runtimes or complex local daemons.

If you’ve found yourself fighting against the framework to manage native threads or custom session states, you’re in the right place. An agent use is the low-level executor for an OpenClaw agent turn, and here is how you can use it to build more powerful native plugins.

When to use a use

Register an agent use 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
• a specialized environment requiring direct execution control

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

What core still owns

Before a use is selected, OpenClaw has already resolved:

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

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

Register a use

Import: openclaw/plugin-sdk/agent-use

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 use after provider/model resolution:

1. OPENCLAW_AGENT_RUNTIME=<id> forces a registered use with that id.
2. OPENCLAW_AGENT_RUNTIME=pi forces the built-in PI use.
3. OPENCLAW_AGENT_RUNTIME=auto asks registered harnesses if they support the resolved provider/model.
4. If no registered use matches, OpenClaw uses PI unless PI fallback is disabled.

Forced plugin use failures surface as run failures. In auto mode, OpenClaw may fall back to PI when the selected plugin use fails before a turn has produced side effects. Set OPENCLAW_AGENT_HARNESS_FALLBACK=none or embeddedHarness.fallback: "none" to make that fallback a hard failure instead.

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

Provider plus use pairing

Most harnesses should also register a provider. The provider makes model refs, auth status, model metadata, and /model selection visible to the rest of OpenClaw. The use then claims that provider in supports(...).

The bundled Codex plugin follows this pattern:

• provider id: codex
• user model refs: codex/gpt-5.4, codex/gpt-5.2, or another model returned by the Codex app server
• use id: codex
• auth: synthetic provider availability, because the Codex use owns the native Codex login/session
• app-server request: OpenClaw sends the bare model id to Codex and lets the use talk to the native app-server protocol

The Codex plugin is additive. Plain openai/gpt-* refs remain OpenAI provider refs and continue to use the normal OpenClaw provider path. Select codex/gpt-* when you want Codex-managed auth, Codex model discovery, native threads, and Codex app-server execution. /model can switch among the Codex models returned by the Codex app server without requiring OpenAI provider credentials.

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

OpenClaw requires Codex app-server 0.118.0 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.

Disable PI fallback

By default, OpenClaw runs embedded agents with agents.defaults.embeddedHarness set to { runtime: "auto", fallback: "pi" }. In auto mode, registered plugin harnesses can claim a provider/model pair. If none match, or if an auto-selected plugin use fails before producing output, OpenClaw falls back to PI.

Set fallback: "none" when you need to prove that a plugin use is the only runtime being exercised. This disables automatic PI fallback; it does not block an explicit runtime: "pi" or OPENCLAW_AGENT_RUNTIME=pi.

For Codex-only embedded runs:

{
  "agents": {
    "defaults": {
      "model": "codex/gpt-5.4",
      "embeddedHarness": {
        "runtime": "codex",
        "fallback": "none"
      }
    }
  }
}

If you want any registered plugin use to claim matching models but never want OpenClaw to silently fall back to PI, keep runtime: "auto" and disable the fallback:

{
  "agents": {
    "defaults": {
      "embeddedHarness": {
        "runtime": "auto",
        "fallback": "none"
      }
    }
  }
}

Per-agent overrides use the same shape:

{
  "agents": {
    "defaults": {
      "embeddedHarness": {
        "runtime": "auto",
        "fallback": "pi"
      }
    },
    "list": [
      {
        "id": "codex-only",
        "model": "codex/gpt-5.4",
        "embeddedHarness": {
          "runtime": "codex",
          "fallback": "none"
        }
      }
    ]
  }
}

OPENCLAW_AGENT_RUNTIME still overrides the configured runtime. Use OPENCLAW_AGENT_HARNESS_FALLBACK=none to disable PI fallback from the environment.

OPENCLAW_AGENT_RUNTIME=codex \
OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run

With fallback disabled, a session fails early when the requested use 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 use. It does not disable image, video, music, TTS, PDF, or other provider-specific model routing.

Native sessions and transcript mirror

A use 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 use on a later turn
• generic /new, /reset, and session deletion behavior

If your use stores a sidecar binding, implement reset(...) 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 use executes a flexible tool call, return the tool result back through the use 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 Pi names for compatibility.
• Third-party use installation is experimental. Prefer provider plugins until you need a native session runtime.
• use 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 use
• Model Providers

Next Steps

Ready to start building? Check out the SDK Overview to see how harnesses fit into the bigger picture, or jump straight into Provider Plugins if you realize you don’t need a full native runtime just yet.

AI Setup Assistant