CH 01 · What Is an Agent Harness? · 06/12
Read as one pageReal code: OpenClaw treats the harness as a plugin
OpenClaw is a personal assistant that runs on your computer and meets you in chat apps. Its readme says you can swap agent harnesses, the programs that call the model and run tools, without changing the rest of the setup. Sandbox and workspace rules do not automatically come along. Every harness fills one small type, a list of fields an object must have. Only four fields are required. supports answers whether this harness can serve this request. runAttempt runs one turn.
type AgentHarnessContract<
// ... (2 type parameters)
> = {
id: string;
label: string;
// ... (24 lines: provider lists, remote placement, and context management)
/** Core must reject containment this runtime cannot implement before invoking it. */
executionEnvironment?: "host-only"; // [1]
// ... (11 lines: which tool and model policies this harness promises to enforce exactly)
supports(ctx: AgentHarnessSupportContext): AgentHarnessSupport; // [2]
// ... (42 lines: setup checks, session ownership, credentials, per-turn tool limits)
runAttempt(params: TAttemptParams): Promise<AgentHarnessAttemptResult>; // [3]
Source: openclaw/openclaw, src/agents/harness/types.ts (MIT)
What to notice
- [1]
host-onlymeans this runtime runs on the Gateway host, the machine running OpenClaw. Core always rejects it when a sandbox is required, when execution is remote, or when this run requires a workspace boundary. Workspace-only files, a sandbox that is already on, a permission mode that is not full access, and tool restrictions are rejected too, unless this agent has already consented to this harness. That consent is remembered for the agent, and it does not lift the three refusals above. The built-in harness leaves the field unset, so this check does not apply to it. - [2]
ctxis the provider, model, and route for this turn. The return,AgentHarnessSupport, is yes or no, plus an optional priority and a reason. Auto mode asks plugin harnesses only. The built-in harness is not in that list. If none can serve the request, OpenClaw uses its own. The built-in id isopenclaw, and a plugin is not allowed to register that id. - [3]
runAttemptreceives the inputs for this turn and returns one attempt result. The built-in harness implements it by callingrunEmbeddedAttempt. The Codex plugin implements it by callingrunCodexAppServerAttempt. Same method, two programs.
Read it yourself: In src/agents/harness/selection-decision.ts, read the comment that the built-in harness is not part of the plugin candidate list. Then compare runAttempt in builtin-openclaw.ts with runAttempt in extensions/codex/harness.ts.
Finished this idea?
Your learning progress stays in this browser.