OpenClaw 에이전트 하니스 개발: 커스텀 런타임 구현 가이드
에이전트를 개발하다 보면 단순히 LLM API를 호출하는 것만으로는 부족할 때가 있어요. 특히 특정 런타임 환경을 직접 제어해야 하거나, 네이티브 세션을 유지해야 하는 복잡한 상황에서는 더 깊은 수준의 실행 제어가 필요하죠. 이럴 때 유용하게 사용할 수 있는 것이 바로 Agent Harness Plugins입니다.
Agent Harness Plugins
섹션 제목: “Agent Harness Plugins”agent harness는 준비된 OpenClaw 에이전트의 한 턴(turn)을 실행하는 로우 레벨 실행기예요. 모델 Provider도 아니고, 채널이나 도구 레지스트리도 아니랍니다.
이 기능은 번들로 제공되거나 신뢰할 수 있는 네이티브 플러그인에만 사용해 주세요. 파라미터 타입이 현재 임베디드 러너를 의도적으로 반영하고 있기 때문에, 이 컨트랙트는 아직 실험적인 단계예요.
Harness를 사용해야 할 때
섹션 제목: “Harness를 사용해야 할 때”모델 패밀리가 자체적인 네이티브 세션 런타임을 가지고 있고, 일반적인 OpenClaw provider transport가 적절한 추상화 계층이 아닐 때 agent harness를 등록하세요.
예시:
- 스레드와 압축(compaction)을 직접 관리하는 네이티브 코딩 에이전트 서버
- 네이티브 plan/reasoning/tool 이벤트를 스트리밍해야 하는 로컬 CLI 또는 데몬
- OpenClaw 세션 기록 외에 자체적인 resume id가 필요한 모델 런타임
단순히 새로운 LLM API를 추가하기 위해 harness를 등록하지는 마세요. 일반적인 HTTP 또는 WebSocket 모델 API의 경우에는 provider plugin을 만드시면 돼요.
Core가 여전히 관리하는 부분
섹션 제목: “Core가 여전히 관리하는 부분”Harness가 선택되기 전에 OpenClaw는 이미 다음 사항들을 해결해 둡니다:
- provider 및 모델
- 런타임 인증 상태
- thinking level 및 컨텍스트 예산
- OpenClaw transcript/세션 파일
- workspace, sandbox, 도구 정책
- 채널 응답 콜백 및 스트리밍 콜백
- 모델 fallback 및 라이브 모델 전환 정책
이러한 분리는 의도된 것이에요. Harness는 준비된 시도를 실행할 뿐이며, provider를 선택하거나 채널 전달을 대체하거나 모델을 임의로 전환하지 않아요.
Harness 등록하기
섹션 제목: “Harness 등록하기”Import: openclaw/plugin-sdk/agent-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); },});선택 정책
섹션 제목: “선택 정책”OpenClaw는 provider/모델이 결정된 후 harness를 선택해요:
OPENCLAW_AGENT_RUNTIME=<id>는 해당 id를 가진 등록된 harness를 강제로 사용하게 해요.OPENCLAW_AGENT_RUNTIME=pi는 내장된 PI harness를 강제로 사용해요.OPENCLAW_AGENT_RUNTIME=auto는 등록된 harness들에게 결정된 provider/모델을 지원하는지 물어봐요.- 매칭되는 등록된 harness가 없으면, PI fallback이 비활성화되지 않은 한 OpenClaw는 PI를 사용해요.
강제된 플러그인 harness가 실패하면 실행 실패로 처리돼요. auto 모드에서 선택된 플러그인 harness가 턴의 부수 효과(side effects)를 생성하기 전에 실패하면 OpenClaw가 PI로 fallback할 수 있어요. 이 fallback을 엄격한 실패로 바꾸려면 OPENCLAW_AGENT_HARNESS_FALLBACK=none 또는 embeddedHarness.fallback: "none"으로 설정하세요.
번들로 제공되는 Codex 플러그인은 codex를 harness id로 등록해요. Core는 이를 일반적인 플러그인 harness id로 취급하며, Codex 전용 별칭은 공유 런타임 선택기가 아닌 플러그인이나 운영자 설정에 속해요.
Provider와 Harness 조합하기
섹션 제목: “Provider와 Harness 조합하기”대부분의 harness는 provider도 함께 등록해야 해요. Provider는 모델 참조, 인증 상태, 모델 메타데이터 및 /model 선택을 OpenClaw의 나머지 부분에서 볼 수 있게 해줘요. 그 다음 harness가 supports(...)에서 해당 provider를 소유한다고 선언하는 방식이죠.
번들 Codex 플러그인이 이 패턴을 따르고 있어요:
- provider id:
codex - 사용자 모델 참조:
codex/gpt-5.4,codex/gpt-5.2또는 Codex 앱 서버가 반환하는 다른 모델 - harness id:
codex - 인증: Codex harness가 네이티브 Codex 로그인/세션을 소유하므로 가상의 provider 가용성을 사용
- 앱 서버 요청: OpenClaw는 순수 모델 id를 Codex에 보내고 harness가 네이티브 앱 서버 프로토콜과 통신하도록 함
Codex 플러그인은 추가적인 기능이에요. 일반적인 openai/gpt-* 참조는 여전히 OpenAI provider 참조로 남아서 일반적인 OpenClaw provider 경로를 사용해요. Codex가 관리하는 인증, Codex 모델 탐색, 네이티브 스레드 및 Codex 앱 서버 실행을 원할 때 codex/gpt-*를 선택하세요. /model 명령을 통해 OpenAI provider 자격 증명 없이도 Codex 앱 서버가 반환하는 모델들 사이를 전환할 수 있어요.
운영자 설정, 모델 접두사 예시 및 Codex 전용 설정에 대해서는 Codex Harness를 참고하세요.
OpenClaw는 Codex 앱 서버 0.118.0 이상 버전이 필요해요. Codex 플러그인은 앱 서버 초기화 핸드셰이크를 확인하고 이전 버전이나 버전이 없는 서버를 차단하여, 테스트가 완료된 프로토콜 환경에서만 OpenClaw가 실행되도록 보장해요.
PI Fallback 비활성화하기
섹션 제목: “PI Fallback 비활성화하기”기본적으로 OpenClaw는 agents.defaults.embeddedHarness가 { runtime: "auto", fallback: "pi" }로 설정된 상태에서 임베디드 에이전트를 실행해요. auto 모드에서는 등록된 플러그인 harness가 provider/모델 쌍을 소유할 수 있어요. 매칭되는 것이 없거나, 자동 선택된 플러그인 harness가 출력을 생성하기 전에 실패하면 OpenClaw는 PI로 fallback해요.
플러그인 harness가 사용되는 유일한 런타임임을 증명해야 할 때는 fallback: "none"으로 설정하세요. 이렇게 하면 자동 PI fallback은 비활성화되지만, 명시적인 runtime: "pi"나 OPENCLAW_AGENT_RUNTIME=pi 설정이 차단되지는 않아요.
Codex 전용 임베디드 실행을 위한 설정 예시예요:
{ "agents": { "defaults": { "model": "codex/gpt-5.4", "embeddedHarness": { "runtime": "codex", "fallback": "none" } } }}등록된 어떤 플러그인 harness라도 매칭되는 모델을 가져가되, OpenClaw가 자동으로 PI로 fallback하는 것을 원치 않는다면 runtime: "auto"를 유지하고 fallback만 비활성화하세요:
{ "agents": { "defaults": { "embeddedHarness": { "runtime": "auto", "fallback": "none" } } }}에이전트별 오버라이드도 동일한 구조를 사용해요:
{ "agents": { "defaults": { "embeddedHarness": { "runtime": "auto", "fallback": "pi" } }, "list": [ { "id": "codex-only", "model": "codex/gpt-5.4", "embeddedHarness": { "runtime": "codex", "fallback": "none" } } ] }}OPENCLAW_AGENT_RUNTIME은 여전히 설정된 런타임을 덮어써요. 환경 변수에서 PI fallback을 비활성화하려면 OPENCLAW_AGENT_HARNESS_FALLBACK=none을 사용하세요.
OPENCLAW_AGENT_RUNTIME=codex \OPENCLAW_AGENT_HARNESS_FALLBACK=none \openclaw gateway runFallback이 비활성화되면 요청된 harness가 등록되지 않았거나, 결정된 provider/모델을 지원하지 않거나, 턴의 부수 효과를 생성하기 전에 실패할 경우 세션이 조기에 종료돼요. 이는 Codex 전용 배포나 Codex 앱 서버 경로가 실제로 사용되고 있는지 증명해야 하는 라이브 테스트에서 의도된 동작이에요.
이 설정은 임베디드 에이전트 harness만 제어해요. 이미지, 비디오, 음악, TTS, PDF 또는 기타 provider 전용 모델 라우팅을 비활성화하지는 않아요.
Native 세션 및 Transcript 미러링
섹션 제목: “Native 세션 및 Transcript 미러링”Harness는 네이티브 세션 id, 스레드 id 또는 데몬 측의 resume token을 유지할 수 있어요. 이러한 바인딩을 OpenClaw 세션과 명시적으로 연결하고, 사용자가 볼 수 있는 assistant/tool 출력을 OpenClaw transcript에 계속 미러링해 주세요.
OpenClaw transcript는 다음 기능들을 위한 호환성 레이어 역할을 해요:
- 채널에서 볼 수 있는 세션 히스토리
- transcript 검색 및 인덱싱
- 나중에 다른 턴에서 내장 PI harness로 다시 전환
- 일반적인
/new,/reset및 세션 삭제 동작
Harness가 사이드카 바인딩을 저장한다면, 소유하고 있는 OpenClaw 세션이 리셋될 때 이를 정리할 수 있도록 reset(...)을 구현해 주세요.
도구 및 미디어 결과
섹션 제목: “도구 및 미디어 결과”Core는 OpenClaw 도구 목록을 구성하여 준비된 시도(attempt)에 전달해요. Harness가 동적 도구 호출을 실행할 때, 직접 채널 미디어를 보내는 대신 harness 결과 형태를 통해 도구 결과를 반환하세요.
이렇게 하면 텍스트, 이미지, 비디오, 음악, TTS, 승인 및 메시징 도구 출력이 PI 기반 실행과 동일한 전달 경로를 유지할 수 있어요.
현재 제한 사항
섹션 제목: “현재 제한 사항”- 공개 import 경로는 일반적이지만, 일부 attempt/result 타입 별칭은 호환성을 위해 여전히
Pi라는 이름을 포함하고 있어요. - 서드파티 harness 설치는 실험적이에요. 네이티브 세션 런타임이 꼭 필요한 경우가 아니라면 provider 플러그인을 우선적으로 사용하세요.
- 턴 사이의 harness 전환은 지원돼요. 하지만 네이티브 도구, 승인, assistant 텍스트 또는 메시지 전송이 시작된 후 턴 중간에 harness를 전환하지는 마세요.
관련 문서
섹션 제목: “관련 문서”더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요!
OpenClaw Expert
아직 막혀 있나요?
이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.