Claw 감독자

목표

Claw 감독자는 항상 켜져 있는 하나의 OpenClaw 인스턴스가 일반적인 Codex 사용자 경험을 바꾸지 않고 Codex 세션 플릿을 모니터링하고 구동할 수 있게 합니다. 사용자는 호스트에 SSH로 접속하고, Codex를 시작하고, TUI에서 작업하면서도 감독자가 세션을 읽고, 조정하고, 중단하고, 관련 세션을 생성하고, 핸드오프를 수락하게 할 수 있습니다. Codex 세션은 MCP를 통해 OpenClaw로 다시 호출할 수도 있습니다.

제품 모델

Codex는 기본 작업 표면으로 유지됩니다. OpenClaw는 Codex를 불투명한 OpenClaw 하위 에이전트 안에 숨기는 대신 Codex를 감독합니다.

OpenClaw Plugin의 이름은 codex-supervisor입니다. crabfleet는 재사용 가능한 Plugin 이름이 아니라 CRAB 머신의 배포 및 호스트 플릿 프로필로 유지됩니다.

이 모델에는 세 가지 역할이 있습니다.

• 사람이 붙어 있는 Codex: 공유 앱 서버를 통해 시작되는 일반 대화형 Codex TUI입니다.
• 자율 Codex: 감독자가 생성하고 사람이 나중에 연결할 수 있는 Codex 앱 서버 스레드입니다.
• 감독자 Claw: 플릿 상태, transcript 읽기, 조정, 중단, 생성, 핸드오프를 위한 도구를 갖춘 항상 켜져 있는 OpenClaw 에이전트입니다.

OpenClaw는 내부적으로 기존 하위 에이전트 장치를 사용할 수 있지만, 외부 계약은 Codex 스레드 ID가 있는 연결 가능한 Codex 세션입니다.

아키텍처

user SSH session  -> codex --remote unix://... or ws://...      -> local codex app-server daemon          <-> host sidecar / supervisor connector              <-> OpenClaw fleet supervisor                  <-> supervisor MCP exposed back to Codex

각 Codex 지원 호스트는 다음을 실행합니다.

• Codex 앱 서버 데몬.
• 항상 --remote로 대화형 Codex를 시작하는 런처.
• 앱 서버 엔드포인트와 라이브 스레드를 감독자에 등록하는 커넥터.

감독자는 다음을 실행합니다.

• 엔드포인트 레지스트리.
• 세션 레지스트리.
• Codex 앱 서버 JSON-RPC 클라이언트 풀.
• Codex에서 Claw로 호출하기 위한 MCP 서버.
• Claw에서 Codex를 제어하기 위한 OpenClaw 도구.
• 자율 동작, 승인, 루프 방지를 위한 정책 엔진.

Codex 앱 서버 계약

Codex 앱 서버 API를 표준 제어 평면으로 사용합니다.

• initialize, initialized
• thread/loaded/list
• thread/list
• thread/read
• thread/resume
• thread/start
• turn/start
• turn/steer
• turn/interrupt
• model/list

대화형 Codex는 TUI와 감독자가 같은 앱 서버에 연결되도록 codex --remote <endpoint>로 시작해야 합니다. 독립 실행형 codex exec는 현재 라이브 공유 세션이 아닙니다. Codex가 exec --remote를 지원할 때까지는 자율 작업에 앱 서버 API를 사용하세요.

세션 레지스트리

감독자는 관찰된 Codex 스레드마다 하나의 레코드를 저장합니다.

{  "sessionId": "codex-thread-id",  "endpointId": "host-a",  "host": "host-a.example",  "workspace": "/workspace/repo",  "repo": "owner/repo",  "branch": "feature/example",  "source": "vscode",  "status": "idle",  "humanAttached": true,  "lastSeenAt": "2026-05-28T10:00:00.000Z",  "summary": "Short working-state summary"}

로컬 구현은 대부분의 필드를 Codex 스레드 메타데이터에서 파생할 수 있습니다. 플릿 배포는 호스트 ID, 사용자 연결 상태, git 상태, 사이드카 상태로 레코드를 보강해야 합니다.

Codex용 MCP 표면

감독되는 모든 Codex에는 openclaw-codex-supervisor라는 MCP 서버가 제공됩니다.

도구:

• codex_sessions_list: 보이는 Codex 세션을 나열합니다.
• codex_session_read: 하나의 transcript를 읽습니다.
• codex_session_send: 유휴 스레드에 메시지를 보내거나 활성 스레드를 조정합니다.
• codex_session_interrupt: 활성 턴을 중단합니다.
• codex_endpoint_probe: 엔드포인트 연결을 확인합니다.
• claw_report_progress: 현재 작업 상태를 감독자에 게시합니다.
• claw_ask: 감독자에게 도움이나 위임을 요청합니다.
• codex_spawn: 새 자율 Codex 세션을 생성합니다.
• codex_handoff: 사람 또는 피어 인계를 요청합니다.

리소스:

• codex://sessions
• codex://sessions/{sessionId}
• codex://sessions/{sessionId}/transcript

Claw 제어 표면

항상 켜져 있는 Claw는 내부 도구와 동일한 프리미티브를 받습니다.

• 세션 및 엔드포인트 나열
• transcript 읽기
• 텍스트 보내기/조정
• 활성 작업 중단
• 새 세션 생성
• 세션 요약 및 할당
• 필터링된 그룹에 지시 브로드캐스트
• 세션을 차단됨, 완료됨, 또는 폐기됨으로 표시

도구 동작:

• 대상 스레드가 유휴 상태이면 codex_session_send는 turn/start로 매핑됩니다.
• 대상 스레드가 활성 상태이고 진행 중인 턴 ID가 보이면 turn/steer로 매핑됩니다.
• 활성 턴을 식별할 수 없으면 도구는 관련 없는 턴을 생성하는 대신 닫힌 상태로 실패합니다.
• Codex에 노출된 MCP 쓰기 제어는 신뢰할 수 있는 감독자 전용 정책이 활성화하지 않는 한 비활성화 상태로 유지됩니다.
• 원시 transcript 읽기는 신뢰할 수 있는 감독자 전용 정책이 활성화하지 않는 한 비활성화 상태로 유지됩니다.
• 자율 승인 기본값은 명시적 정책이 달리 지정하지 않는 한 도구/파일 승인을 거부합니다.

시작 흐름

대화형 호스트 로그인:

1. 사용자가 CRAB 호스트에 SSH로 접속합니다.
2. SSH 서비스가 codex app-server daemon start를 시작하거나 확인합니다.
3. 로그인 래퍼가 codex --remote unix:// --cd <workspace>를 시작합니다.
4. 호스트 커넥터가 엔드포인트와 로드된 스레드를 등록합니다.
5. 감독자가 높은 우선순위의 플릿 이벤트를 내보냅니다: 새 Codex 세션, 작업공간, 사람이 붙어 있는 상태, 현재 작업 미리보기.
6. 감독자 Claw는 즉시 읽고 조정할 수 있습니다.

자율 생성:

1. 감독자가 호스트와 작업공간을 선택합니다.
2. 호스트 커넥터가 Codex 앱 서버 스레드를 열거나 재개합니다.
3. 감독자가 작업 텍스트와 MCP 구성으로 첫 번째 턴을 시작합니다.
4. 세션 레지스트리가 이를 자율 및 연결 가능으로 표시합니다.
5. Codex가 해당 정확한 UX를 지원하면 사람은 나중에 codex --remote <endpoint> resume <threadId>로 연결할 수 있으며, 또는 같은 앱 서버의 현재 재개 흐름을 통해 연결할 수 있습니다.

배포

권장 제어 평면:

• 호스트 커넥터는 감독자로 나가는 WebSocket 연결을 유지합니다.
• 감독자 상태는 OpenClaw Gateway 저장소에 저장됩니다.
• Codex 앱 서버는 각 호스트에 로컬로 유지됩니다. 인증되지 않은 원시 앱 서버를 공개 인터넷에 절대 노출하지 마세요.

Cloudflare 적합성:

• 레지스트리, Durable Objects, WebSocket 팬인, 경량 이벤트 라우팅, 공개 MCP/Gateway 엔드포인트에 적합합니다.
• Workers는 임의의 사설 Unix 소켓이나 local loopback 앱 서버로 다이얼할 수 없기 때문에 직접적인 사설 호스트 제어에는 그 자체만으로 충분하지 않습니다.
• 모든 호스트 커넥터가 아웃바운드 WebSocket으로 홈에 연결할 때 Cloudflare를 사용하세요.

VPS 폴백:

• 장기 실행 프로세스 제어, SSH 터널, 사설 네트워크 라우팅, 또는 로컬 파일시스템 접근이 필요할 때 Hetzner 서비스를 사용하세요.
• 동일한 프로토콜을 유지합니다: 호스트 커넥터는 아웃바운드, 감독자 레지스트리는 중앙, Codex 앱 서버는 로컬.

보안

• 기본 바인드는 로컬 Unix 소켓입니다.
• 원격 앱 서버는 토큰 또는 서명된 bearer 인증을 사용합니다.
• 호스트 커넥터는 범위가 지정된 호스트 토큰으로 감독자에 인증합니다.
• 감독자 도구는 세션별 정책을 적용합니다: 읽기, 조정, 중단, 생성, 승인.
• 에이전트 간 메시지에는 originSessionId가 포함되며, 자기 에코는 삭제됩니다.
• 브로드캐스트에는 명시적 필터와 제한된 대상 수가 필요합니다.
• transcript 읽기는 OpenClaw 경계에서 비밀을 마스킹합니다.
• 승인 요청은 정책이 허용하지 않는 한 감독자에서 시작된 턴에 대해 기본적으로 거부됩니다.

구현 계획

1단계: 로컬 감독자 MVP

• stdio 프록시와 WebSocket 엔드포인트를 위한 Codex 앱 서버 JSON-RPC 클라이언트를 추가합니다.
• 감독자 엔드포인트/세션 레지스트리를 추가합니다.
• MCP 도구를 추가합니다: 나열, 읽기, 보내기, 중단, 프로브.
• 엔드포인트용 로컬 환경 구성을 추가합니다.
• 가짜 앱 서버 테스트와 하나의 라이브 로컬 앱 서버 스모크를 추가합니다.

2단계: OpenClaw 통합

• codex-supervisor Plugin에 감독자 도구를 등록합니다.
• Codex 스레드 구성에 감독자 MCP를 주입합니다.
• 에이전트 컨텍스트에 세션 요약을 추가합니다.
• 새 Codex 스레드가 나타나면 이벤트 알림을 추가합니다.
• 자율 보내기/중단/생성을 위한 정책 구성을 추가합니다.

3단계: 플릿 커넥터

• 호스트 사이드카가 앱 서버 엔드포인트, 호스트 메타데이터, git/작업공간 메타데이터, 사람 연결 상태를 등록합니다.
• Cloudflare 또는 VPS 제어 평면을 위한 아웃바운드 WebSocket 커넥터를 추가합니다.
• 재연결, Heartbeat, 오래된 세션 정리를 추가합니다.
• CRAB SSH 런처 래퍼를 추가합니다.

4단계: 자율 운영

• 생성/재개/인수 흐름을 추가합니다.
• 브로드캐스트와 위임을 추가합니다.
• 진행 보고와 작업 상태 요약을 추가합니다.
• 루프 방지와 속도 제한을 추가합니다.
• 대시보드 보기를 추가합니다.

5단계: 다중 Claw

• 그룹별로 세션을 샤딩합니다.
• 각 세션에 대한 리더십/리스을 추가합니다.
• 감사 로그와 재생을 추가합니다.
• Claw 그룹 간 에스컬레이션을 추가합니다.

인수 테스트

• 사람이 공유 앱 서버를 통해 Codex TUI를 시작합니다.
• 감독자가 thread/loaded/list를 통해 라이브 스레드를 나열합니다.
• 감독자가 thread/read를 통해 transcript를 읽습니다.
• 감독자가 turn/start를 통해 유휴 스레드에 텍스트를 보냅니다.
• 감독자가 turn/steer를 통해 활성 스레드를 조정합니다.
• 감독자 중단이 turn/interrupt를 통해 활성 턴을 중지합니다.
• Codex가 감독자 MCP를 호출하고 피어 세션을 나열합니다.
• 자율 Codex가 생성되고 나중에 사람이 연결됩니다.
• 손실된 호스트 커넥터는 기록을 삭제하지 않고 세션을 오래됨으로 표시합니다.

미해결 질문

• TUI 없이 생성된 앱 서버 스레드에 대한 정확한 Codex TUI 연결 UX.
• 헤드리스 라이브 공유 실행을 위해 Codex가 exec --remote를 추가해야 하는지 여부.
• 영속 상태 소유자: OpenClaw Gateway DB, Cloudflare Durable Object, 또는 VPS 데이터베이스.
• 감독자에서 시작된 턴에 대한 승인 정책 세분성.
• 얼마나 많은 transcript 요약을 항상 켜져 있는 Claw 컨텍스트에 주입하고, 얼마나 도구/리소스로 유지할지.