에이전트 하네스 플러그인

​

하니스를 사용해야 하는 경우

• 스레드와 Compaction을 소유하는 네이티브 코딩 에이전트 서버
• 네이티브 계획/추론/도구 이벤트를 스트리밍해야 하는 로컬 CLI 또는 데몬
• OpenClaw 세션 트랜스크립트 외에 자체 재개 ID가 필요한 모델 런타임

​

코어가 계속 소유하는 항목

• 제공자 및 모델
• 하니스가 인증 부트스트랩을 소유한다고 선언하지 않는 한 런타임 인증 상태
• 사고 수준 및 컨텍스트 예산
• OpenClaw 트랜스크립트/세션 파일
• 워크스페이스, 샌드박스 및 도구 정책
• 채널 응답 콜백 및 스트리밍 콜백
• 모델 폴백 및 실시간 모델 전환 정책

​

하니스 소유 인증 부트스트랩

​

검증된 설정 런타임 아티팩트

• 제공자 인식 도구 스키마 정책을 위한 runtimePlan.tools.normalize(...) 및 runtimePlan.tools.logDiagnostics(...)
• 트랜스크립트 정리 및 도구 호출 복구 정책을 위한 runtimePlan.transcript.resolvePolicy(...)
• 공유 NO_REPLY 및 미디어 전달 억제를 위한 runtimePlan.delivery.isSilentPayload(...)
• 모델 폴백 분류를 위한 runtimePlan.outcome.classifyRunResult(...)
• 확인된 제공자/모델/하니스 메타데이터를 위한 runtimePlan.observability

​

요청 전송 계약

• runtimePolicy.compatibleIds은 제공자가 해당 구체적인 경로와 호환된다고 선언한 런타임 ID를 나열합니다. 정책이 없다는 것은 제공자가 경로 수준 호환성을 선언하지 않았다는 의미이며, 지원을 가정해도 된다는 허가는 아닙니다.
• requestTransportOverrides: "none"은 작성된 제공자/모델 요청 재정의를 재현할 필요가 없음을 의미합니다. "present"은 작성된 헤더, 인증 전송, 프록시, TLS, 로컬 서비스, 사설 네트워크 동작 또는 요청 매개변수가 존재함을 의미합니다. 이 정보는 해당 값을 노출하지 않습니다.

​

하니스 등록

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) {
    const routeSupportsHarness =
      ctx.modelProvider?.runtimePolicy?.compatibleIds.includes("my-harness") === true;
    const canReproduceRequest = ctx.modelProvider?.requestTransportOverrides !== "present";
    return ctx.provider === "my-provider" && routeSupportsHarness && canReproduceRequest
      ? { supported: true, priority: 100 }
      : { supported: false, reason: "effective route is not harness-compatible" };
  },

  async runAttempt(params) {
    // 네이티브 스레드를 시작하거나 재개합니다.
    // params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent 및 준비된 시도의 기타 필드를 사용합니다.
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "My Native Agent",
  description: "선택한 모델을 네이티브 에이전트 데몬을 통해 실행합니다.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});

​

위임 실행

​

선택 정책

1. 모델 범위 런타임 정책이 우선합니다.
2. 그다음으로 제공자 범위 런타임 정책이 적용됩니다.
3. auto은 등록된 하니스에 확인된 유효 경로를 지원하는지 묻습니다. 제공자/모델 접두사만으로는 하니스가 선택되지 않습니다.
4. 일치하는 등록 하니스가 없으면 OpenClaw는 임베디드 런타임을 사용합니다.

​

제공자와 하니스 페어링

• 권장 사용자 모델 참조: openai/gpt-5.6-sol
• 호환성 참조: 레거시 codex/gpt-* 참조는 계속 허용되지만 새 구성에서는 일반 제공자/모델 참조로 사용하지 않아야 합니다.
• 하니스 ID: codex
• 인증: Codex 하니스가 네이티브 Codex 로그인/세션을 소유하므로 합성 제공자 가용성을 사용합니다.
• 앱 서버 요청: OpenClaw는 기본 모델 ID를 Codex에 전송하고 하니스가 네이티브 앱 서버 프로토콜과 통신하도록 합니다.

​

도구 결과 미들웨어

​

터미널 결과 분류

​

에이전트 종료 부수 효과

​

사용자 입력 및 도구 표면

​

네이티브 Codex 하네스 모드

​

런타임 엄격성

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

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

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

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

​

네이티브 세션 및 트랜스크립트 미러

• 채널에 표시되는 세션 기록
• 트랜스크립트 검색 및 인덱싱
• 이후 턴에서 내장 OpenClaw 하네스로 다시 전환
• 일반적인 /new, /reset 및 세션 삭제 동작

​

도구 및 미디어 결과

​

터미널 도구 결과

• 프로토콜 호출 ID가 있으면 해당 ID, 정식 도구 이름, 그리고 준비 또는 훅 재작성 후 실제로 도구에 전달된 인수를 전달하십시오.
• 검증, 승인 또는 다른 가드가 도구 구현 시작 전에 호출을 중단했다면 executionStarted: false을 설정하십시오. 디스패치가 발생했을 가능성이 있다면 보수적으로 true을 보고하십시오.
• outcome: "success" 또는 outcome: "failure"을 보고하십시오. 표시 텍스트에서 실패를 추론하지 말고 런타임에서 제공하는 구조화된 실패 필드를 포함하십시오.
• OpenClaw 도구 정의를 사용하지 않는 네이티브 도구에만 nativeMutation을 사용하십시오. 여기에 프로토콜이 소유하는 변경 및 재실행 관련 사실을 제공하십시오. OpenClaw의 변경 분류기를 하네스에 복사하지 마십시오.

​

현재 제한 사항

• 공개 임포트 경로는 일반적이지만, 일부 시도/결과 타입 별칭에는 호환성을 위해 여전히 레거시 이름이 사용됩니다.
• 서드 파티 하네스 설치는 실험적입니다. 네이티브 세션 런타임이 필요해질 때까지는 공급자 Plugin을 우선 사용하십시오.
• 턴 간 하네스 전환은 지원됩니다. 네이티브 도구, 승인, 어시스턴트 텍스트 또는 메시지 전송이 시작된 후에는 턴 도중 하네스를 전환하지 마십시오.

​

관련 항목

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