에이전트 하네스 Plugin

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

harness를 사용해야 하는 경우

• thread와 compaction을 소유하는 네이티브 coding-agent server
• 네이티브 plan/reasoning/tool event를 스트리밍해야 하는 로컬 CLI 또는 daemon
• OpenClaw session transcript에 더해 자체 resume id가 필요한 model runtime

​

core가 계속 소유하는 것

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

• provider-aware tool schema policy를 위한 runtimePlan.tools.normalize(...) 및 runtimePlan.tools.logDiagnostics(...)
• transcript sanitization 및 tool-call repair policy를 위한 runtimePlan.transcript.resolvePolicy(...)
• 공유 NO_REPLY 및 media delivery suppression을 위한 runtimePlan.delivery.isSilentPayload(...)
• model fallback classification을 위한 runtimePlan.outcome.classifyRunResult(...)
• 해결된 provider/model/harness metadata를 위한 runtimePlan.observability

​

harness 등록

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);
  },
});

​

선택 정책

1. model 범위 runtime policy가 우선합니다.
2. provider 범위 runtime policy가 그다음입니다.
3. auto는 등록된 harness에 해결된 provider/model을 지원하는지 묻습니다.
4. 일치하는 등록 harness가 없으면 PI fallback이 비활성화되어 있지 않은 한 OpenClaw는 PI를 사용합니다.

​

provider와 harness 페어링

• 선호되는 사용자 model ref: openai/gpt-5.5
• compatibility ref: legacy codex/gpt-* ref는 계속 허용되지만, 새 config에서는 이를 일반 provider/model ref로 사용하지 않아야 합니다.
• harness id: codex
• auth: synthetic provider availability. Codex harness가 네이티브 Codex login/session을 소유하기 때문입니다.
• app-server request: OpenClaw는 bare model id를 Codex로 보내고 harness가 네이티브 app-server protocol과 통신하게 합니다.

​

tool-result middleware

​

Terminal outcome classification

​

Native Codex harness mode

​

Runtime strictness

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

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-7",
      "models": {
        "anthropic/claude-opus-4-7": {
          "agentRuntime": {
            "id": "claude-cli"
          }
        }
      }
    }
  }
}

{
  "agents": {
    "list": [
      {
        "id": "codex-only",
        "model": "openai/gpt-5.5",
        "models": {
          "openai/gpt-5.5": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    ]
  }
}

{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}

​

네이티브 session과 transcript mirror

• channel-visible session history
• transcript search 및 indexing
• 이후 턴에서 built-in PI harness로 다시 전환
• generic /new, /reset, session deletion behavior

​

tool 및 media result

​

현재 제한 사항

• public import path는 generic이지만 일부 attempt/result type alias는 compatibility를 위해 여전히 Pi 이름을 갖고 있습니다.
• third-party harness installation은 실험적입니다. 네이티브 session runtime이 필요해질 때까지는 provider Plugin을 선호하세요.
• harness switching은 턴 간에 지원됩니다. 네이티브 tool, approval, assistant text 또는 message send가 시작된 후 턴 중간에 harness를 전환하지 마세요.

​

관련

• SDK 개요
• 런타임 헬퍼
• 제공자 Plugin
• Codex 하네스
• 모델 제공자