Skip to main content
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. Core-only auxiliary-run controls are excluded: Side chat’s direct-tool and selected-session read restrictions are internal behavior, not supported plugin harness inputs.

​
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:
  • 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.

​
Where each section moved

Every section of the single-page version now lives on this page or on one of the eight child pages below. The anchors from the single-page version still resolve here.

​
Core ownership contract

Agent harness core ownership — What core prepares before runAttempt, and the tool-policy, auth-bootstrap, session-ownership, and request-transport contracts a harness can declare.

​
Harness registration

Register an agent harness — The AgentHarnessV2 registration example, plus the optional isolated-completion and delegated-execution capabilities.

​
Harness selection and provider pairing

Agent harness selection policy — How OpenClaw picks a harness after provider and model resolution, and why a harness normally ships with a provider plugin.

​
Attempt runtime helpers

Agent harness attempt runtime — Guarded input injection, tool-result middleware, terminal outcome classification, live token usage, and agent-end side effects.

​
User input and execution authority

Agent harness user input and execution authority — Blocking user-input surfaces, host tool capabilities, exec reviewer outcomes, and paired-device command authority.

​
Native inventories

Agent harness native inventories — Read-only native model rows and MCP tool catalogs reported from a harness’s own runtime.

​
Runtime configuration

Agent harness runtime configuration — Native Codex harness mode and strict provider, model, or per-agent runtime policy.

​
Sessions and results

Agent harness sessions and results — Native session bindings and the transcript mirror, plus tool, media, terminal-outcome, and settled-turn results.

​
Current limitations

  • The public import path is generic, but some attempt/result type aliases still carry legacy 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.