Plugin SDK reference
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:
- 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.
- What core still owns
- Native tool-policy enforcement
- Harness-owned auth bootstrap
- Bound native session ownership
- Verified setup runtime artifacts
- Request-transport contract
- Per-turn temporal context
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.
- Guarded active-run injection
- Tool-result middleware
- Terminal outcome classification
- Live output-token usage
- 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.
- Native sessions and transcript mirror
- Tool and media results
- Terminal tool outcomes
- Settled tool finalization
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.
