계약 — OMX Docs

OMX 동작 계약 — 프롬프트 가이던스, team mutation, OpenClaw 이벤트 스키마

OMX는 프롬프트, interop broker, 이벤트 consumer 전반에서 세 가지 계약을 정의합니다. 프롬프트를 수정하거나 외부 통합을 만들거나 team state를 읽는 도구를 작성할 때 이 계약을 따라야 합니다.

Prompt guidance contract

GPT-5.4 guidance rollout에서 도입된 계약으로, AGENTS.md, templates/AGENTS.md, prompts/*.md, 생성된 developer_instructions 텍스트에 적용됩니다.

핵심 동작 네 가지:

Quality-first, intent-deepening output — 응답은 의도를 더 깊게 파고들고, 안전하게 행동하는 데 필요한 근거를 포함해야 합니다.
Automatic follow-through on low-risk steps — 명확하고 되돌릴 수 있는 다음 단계는 불필요한 확인 없이 자동으로 진행합니다.
Scoped overrides — 사용자의 최신 task update는 전체 프롬프트 초기화가 아닌 현재 작업에 대한 국소 override로 취급합니다. 이전의 비충돌 지시는 유지합니다.
Persistent tool use and evidence-backed completion — 답이 retrieval, diagnostics, tests, verification에 의존한다면 도구 사용을 계속합니다. 증거 없이 중단하지 않습니다.

외부 interop broker는 team state를 CLI interop 경로를 통해서만 변경해야 합니다.

omx team api <operation> --input '<json-object>' --json

.omx/state/team/...에 직접 쓰는 방식은 지원하지 않습니다. 기존 team_* MCP API는 hard-deprecated 상태이며 CLI migration hint와 함께 에러를 반환합니다.

권장 task mutation 흐름:

read-task → claim-task → transition-task-status (in_progress → completed|failed)

release-task-claim은 pending으로 롤백하는 경우에만 사용합니다.

OMX가 내보내는 훅 이벤트의 envelope 구조와 정규화 이벤트 목록을 정의합니다. 외부 consumer는 raw event 값이 아닌 context.normalized_event를 기준으로 라우팅해야 합니다.

정규화 이벤트 테이블과 전체 envelope 스키마는 Clawhip을 참고하세요.