에이전트 하니스 플러그인
에이전트 하니스는 준비된 OpenClaw 에이전트 턴 하나를 실행하는 저수준 실행기입니다. 이것은 모델 제공자도, 채널도, 도구 레지스트리도 아닙니다. 이 표면은 번들되었거나 신뢰할 수 있는 네이티브 플러그인에만 사용하세요. 매개변수 타입이 의도적으로 현재 임베디드 러너를 반영하기 때문에, 이 계약은 아직 실험적입니다.하니스를 사용해야 하는 경우
모델 계열이 자체 네이티브 세션 런타임을 갖고 있고, 일반적인 OpenClaw 제공자 전송이 잘못된 추상화일 때 에이전트 하니스를 등록하세요. 예시:- 스레드와 compaction을 자체적으로 관리하는 네이티브 코딩 에이전트 서버
- 네이티브 plan/reasoning/tool 이벤트를 스트리밍해야 하는 로컬 CLI 또는 데몬
- OpenClaw 세션 transcript 외에 자체 resume id가 필요한 모델 런타임
여전히 core가 담당하는 것
하니스가 선택되기 전에 OpenClaw는 이미 다음을 결정했습니다.- provider와 model
- 런타임 인증 상태
- thinking level과 컨텍스트 예산
- OpenClaw transcript/session 파일
- workspace, sandbox, 도구 정책
- 채널 응답 콜백과 스트리밍 콜백
- 모델 폴백 및 live model switching 정책
하니스 등록
가져오기:openclaw/plugin-sdk/agent-harness
선택 정책
OpenClaw는 provider/model을 결정한 뒤 하니스를 선택합니다.OPENCLAW_AGENT_RUNTIME=<id>는 해당 id의 등록된 하니스를 강제합니다.OPENCLAW_AGENT_RUNTIME=pi는 내장 PI 하니스를 강제합니다.OPENCLAW_AGENT_RUNTIME=auto는 등록된 하니스에, 결정된 provider/model을 지원하는지 묻습니다.- 일치하는 등록된 하니스가 없으면, PI 폴백이 비활성화되지 않은 한 OpenClaw는 PI를 사용합니다.
auto 모드에서는 선택된 플러그인 하니스가 턴의 부작용을 만들기 전에 실패하면 OpenClaw가 PI로 폴백할 수 있습니다. 대신 그 폴백을 즉시 실패로 처리하려면 OPENCLAW_AGENT_HARNESS_FALLBACK=none 또는 embeddedHarness.fallback: "none"을 설정하세요.
번들된 Codex 플러그인은 codex를 하니스 id로 등록합니다. Core는 이를 일반적인 플러그인 하니스 id로 취급합니다. Codex 전용 별칭은 공유 런타임 선택기가 아니라 플러그인 또는 운영자 config에 속해야 합니다.
provider와 harness의 페어링
대부분의 하니스는 provider도 함께 등록해야 합니다. provider는 모델 ref, 인증 상태, 모델 메타데이터,/model 선택을 OpenClaw의 나머지 부분에 노출합니다. 그런 다음 하니스는 supports(...)에서 해당 provider를 주장합니다.
번들된 Codex 플러그인은 이 패턴을 따릅니다.
- provider id:
codex - 사용자 모델 ref:
codex/gpt-5.4,codex/gpt-5.2또는 Codex app server가 반환하는 다른 모델 - harness id:
codex - auth: 합성 provider 가용성, Codex 하니스가 네이티브 Codex 로그인/세션을 관리하기 때문
- app-server 요청: OpenClaw는 Codex에 순수 모델 id를 보내고, 하니스가 네이티브 app-server 프로토콜과 통신하게 합니다.
openai/gpt-* ref는 여전히 OpenAI provider ref이며 계속해서 일반 OpenClaw provider 경로를 사용합니다. Codex가 관리하는 인증, Codex 모델 탐색, 네이티브 스레드, Codex app-server 실행을 원할 때 codex/gpt-*를 선택하세요. /model은 OpenAI provider 자격 증명 없이도 Codex app server가 반환한 Codex 모델들 사이를 전환할 수 있습니다.
운영자 설정, 모델 접두사 예시, Codex 전용 config는
Codex Harness를 참조하세요.
OpenClaw는 Codex app-server 0.118.0 이상을 요구합니다. Codex 플러그인은 app-server initialize 핸드셰이크를 검사하고 더 오래되었거나 버전이 없는 서버를 차단하여, OpenClaw가 테스트된 프로토콜 표면에서만 실행되도록 합니다.
PI 폴백 비활성화
기본적으로 OpenClaw는 임베디드 에이전트를agents.defaults.embeddedHarness가 { runtime: "auto", fallback: "pi" }로 설정된 상태로 실행합니다. auto 모드에서 등록된 플러그인 하니스는 provider/model 쌍을 주장할 수 있습니다. 일치하는 것이 없거나, 자동 선택된 플러그인 하니스가 출력을 만들기 전에 실패하면 OpenClaw는 PI로 폴백합니다.
플러그인 하니스만 실행되고 있음을 증명해야 할 때는 fallback: "none"을 설정하세요. 이렇게 하면 자동 PI 폴백이 비활성화되지만, 명시적인 runtime: "pi" 또는 OPENCLAW_AGENT_RUNTIME=pi까지 막지는 않습니다.
Codex 전용 임베디드 실행의 경우:
runtime: "auto"를 유지하고 폴백을 비활성화하세요.
OPENCLAW_AGENT_RUNTIME는 여전히 구성된 런타임을 재정의합니다. 환경에서 PI 폴백을 비활성화하려면 OPENCLAW_AGENT_HARNESS_FALLBACK=none을 사용하세요.
네이티브 세션과 transcript 미러링
하니스는 네이티브 session id, thread id 또는 데몬 측 resume token을 유지할 수 있습니다. 이 바인딩을 OpenClaw 세션과 명시적으로 연결된 상태로 유지하고, 사용자에게 보이는 assistant/tool 출력을 OpenClaw transcript에도 계속 미러링하세요. OpenClaw transcript는 다음을 위한 호환성 계층으로 남아 있습니다.- 채널에 보이는 세션 기록
- transcript 검색 및 인덱싱
- 이후 턴에서 내장 PI 하니스로 다시 전환
- 일반적인
/new,/reset, 세션 삭제 동작
reset(...)을 구현하세요.
도구 및 미디어 결과
Core는 OpenClaw 도구 목록을 구성하고 이를 준비된 시도에 전달합니다. 하니스가 동적 도구 호출을 실행할 때는, 채널 미디어를 직접 보내는 대신 하니스 결과 형태를 통해 도구 결과를 반환하세요. 이렇게 하면 텍스트, image, video, music, TTS, 승인, 메시징 도구 출력이 PI 기반 실행과 동일한 전달 경로를 유지합니다.현재 제한 사항
- 공개 import 경로는 일반적이지만, 일부 시도/결과 타입 별칭은 호환성을 위해 여전히
Pi이름을 사용합니다. - 서드파티 하니스 설치는 실험적입니다. 네이티브 세션 런타임이 꼭 필요해질 때까지는 provider plugin을 우선 사용하세요.
- 턴 간 하니스 전환은 지원됩니다. 네이티브 도구, 승인, assistant 텍스트 또는 메시지 전송이 시작된 뒤 턴 중간에 하니스를 전환하지 마세요.