--- read_when: - Проєктування нагляду за флотом Codex - Створення інструментів OpenClaw, які читають, скеровують або запускають сеанси Codex - Вибір між локальним розгортанням, Cloudflare і VPS для контрольованого Codex summary: План нагляду за флотом для сеансів app-server Codex, керованих OpenClaw. title: Супервізор Claw x-i18n: generated_at: "2026-06-27T18:21:15Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: ecdd58730011c94796c6df1d757606aad7112d2f36f30921541ac7f5d46ad91f source_path: specs/claw-supervisor.md workflow: 16 --- # Claw Supervisor ## Мета Claw Supervisor дає змогу одному постійно активному екземпляру OpenClaw відстежувати й керувати парком сеансів Codex, не змінюючи звичний користувацький досвід Codex. Користувач може під’єднатися до хоста через SSH, запустити Codex, працювати в TUI, і водночас супервізор зможе читати сеанс, спрямовувати його, переривати, породжувати пов’язані сеанси й приймати передавання. Сеанси Codex також можуть звертатися назад до OpenClaw через MCP. ## Модель продукту Codex залишається основною робочою поверхнею. OpenClaw здійснює супервізію Codex, а не приховує Codex усередині непрозорого субагента OpenClaw. Plugin OpenClaw має назву `codex-supervisor`. `crabfleet` залишається профілем розгортання та парку хостів для машин CRAB, а не назвою повторно використовуваного Plugin. Модель має три ролі: - Codex із під’єднаною людиною: звичайний інтерактивний Codex TUI, запущений через спільний app-server. - Автономний Codex: потік Codex app-server, породжений супервізором, до якого людина може під’єднатися пізніше. - Claw-супервізор: постійно активний агент OpenClaw з інструментами для стану парку, читання транскриптів, спрямування, переривання, породження та передавання. OpenClaw може внутрішньо використовувати наявний механізм субагентів, але зовнішній контракт — це сеанс Codex із можливістю під’єднання та ідентифікатором потоку Codex. ## Архітектура ```text 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 app-server. - Засіб запуску, який завжди запускає інтерактивний Codex з `--remote`. - Конектор, який реєструє кінцеві точки app-server і активні потоки в супервізорі. Супервізор запускає: - Реєстр кінцевих точок. - Реєстр сеансів. - Пул JSON-RPC клієнтів Codex app-server. - MCP-сервер для викликів із Codex до Claw. - Інструменти OpenClaw для керування з Claw до Codex. - Рушій політик для автономних дій, схвалень і запобігання циклам. ## Контракт Codex App-Server Використовуйте API Codex app-server як канонічну площину керування: - `initialize`, `initialized` - `thread/loaded/list` - `thread/list` - `thread/read` - `thread/resume` - `thread/start` - `turn/start` - `turn/steer` - `turn/interrupt` - `model/list` Інтерактивний Codex має запускатися з `codex --remote `, щоб TUI і супервізор під’єднувалися до того самого app-server. Окремий `codex exec` сьогодні не є сеансом зі спільним доступом у реальному часі; використовуйте API app-server для автономної роботи, доки Codex не підтримуватиме `exec --remote`. ## Реєстр сеансів Супервізор зберігає один запис на кожен спостережуваний потік Codex: ```json { "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. Розгортання парку має збагачувати записи ідентичністю хоста, станом під’єднання користувача, станом git і справністю sidecar. ## MCP-поверхня для Codex Кожен супервізований Codex отримує MCP-сервер з назвою `openclaw-codex-supervisor`. Інструменти: - `codex_sessions_list`: перелічити видимі сеанси Codex. - `codex_session_read`: прочитати один транскрипт. - `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 отримує ті самі примітиви, що й внутрішні інструменти: - перелічувати сеанси й кінцеві точки - читати транскрипти - надсилати/спрямовувати текст - переривати активну роботу - породжувати нові сеанси - підсумовувати та призначати сеанси - транслювати інструкції відфільтрованій групі - позначати сеанси як заблоковані, завершені або покинуті Поведінка інструментів: - Якщо цільовий потік неактивний, `codex_session_send` відображається на `turn/start`. - Якщо цільовий потік активний і видно ідентифікатор поточного ходу, він відображається на `turn/steer`. - Якщо активний хід не можна ідентифікувати, інструмент відмовляє у закритому режимі замість створення непов’язаного ходу. - Елементи керування записом MCP, відкриті для Codex, залишаються вимкненими, якщо їх не вмикає довірена політика лише для супервізора. - Сирі читання транскриптів залишаються вимкненими, якщо їх не вмикає довірена політика лише для супервізора. - Типові автономні схвалення забороняють схвалення інструментів/файлів, якщо явна політика не визначає інакше. ## Потік запуску Інтерактивний вхід на хост: 1. Користувач під’єднується через SSH до хоста CRAB. 2. Служба SSH запускає або перевіряє `codex app-server daemon start`. 3. Обгортка входу запускає `codex --remote unix:// --cd `. 4. Конектор хоста реєструє кінцеву точку й завантажений потік. 5. Супервізор випромінює високопріоритетну подію парку: новий сеанс Codex, робочий простір, стан під’єднання людини, попередній перегляд поточного завдання. 6. Claw-супервізор може негайно читати й спрямовувати. Автономне породження: 1. Супервізор вибирає хост і робочий простір. 2. Конектор хоста відкриває або відновлює потік Codex app-server. 3. Супервізор запускає перший хід із текстом завдання та конфігурацією MCP. 4. Реєстр сеансів позначає його як автономний і доступний для під’єднання. 5. Людина може пізніше під’єднатися за допомогою `codex --remote resume `, щойно Codex підтримуватиме саме такий UX, або через поточний потік відновлення на тому самому app-server. ## Розгортання Бажана площина керування: - Конектори хостів підтримують вихідні WebSocket-з’єднання із супервізором. - Стан супервізора зберігається у сховищі OpenClaw Gateway. - Codex app-server залишається локальним для кожного хоста; ніколи не відкривайте сирий неавтентифікований app-server у публічний інтернет. Життєздатність Cloudflare: - Добре підходить для реєстру, durable objects, агрегації WebSocket, легкого маршрутизування подій і публічних кінцевих точок MCP/Gateway. - Самого цього недостатньо для прямого керування приватними хостами, оскільки Workers не можуть набирати довільні приватні Unix-сокети або app-server на local loopback. - Використовуйте Cloudflare, коли кожен конектор хоста телефонує додому через вихідний WebSocket. Резервний варіант VPS: - Використовуйте сервіс Hetzner, коли потрібні керування довгоживучими процесами, SSH-тунелі, маршрутизація приватної мережі або доступ до локальної файлової системи. - Зберігайте той самий протокол: конектори хостів вихідні, реєстр супервізора центральний, Codex app-server локальний. ## Безпека - Типове прив’язування — локальний Unix-сокет. - Віддалений app-server використовує токен або підписану bearer-автентифікацію. - Конектор хоста автентифікується в супервізорі за допомогою scoped host token. - Інструменти супервізора застосовують політики для кожного сеансу: читання, спрямування, переривання, породження, схвалення. - Повідомлення між агентами містять `originSessionId`; самовідлуння відкидається. - Трансляція потребує явного фільтра й обмеженої кількості цілей. - Читання транскриптів редагують секрети на межі OpenClaw. - Запити на схвалення типово забороняються для ходів, ініційованих супервізором, якщо політика їх не дозволяє. ## План реалізації Фаза 1: MVP локального супервізора - Додати JSON-RPC клієнт Codex app-server для stdio-проксі та WebSocket-кінцевих точок. - Додати реєстр кінцевих точок/сеансів супервізора. - Додати інструменти MCP: перелік, читання, надсилання, переривання, probe. - Додати локальну env-конфігурацію для кінцевих точок. - Додати тести з фейковим app-server і один живий локальний smoke для app-server. Фаза 2: Інтеграція OpenClaw - Зареєструвати інструменти супервізора в Plugin `codex-supervisor`. - Впровадити MCP супервізора в конфігурацію потоку Codex. - Додати підсумки сеансів до контексту агента. - Додати сповіщення про події, коли з’являються нові потоки Codex. - Додати конфігурацію політик для автономного надсилання/переривання/породження. Фаза 3: Конектор парку - Sidecar хоста реєструє кінцеву точку app-server, метадані хоста, метадані git/робочого простору та стан під’єднання людини. - Додати вихідний WebSocket-конектор для площини керування Cloudflare або VPS. - Додати повторне під’єднання, Heartbeat і очищення застарілих сеансів. - Додати обгортку запуску CRAB SSH. Фаза 4: Автономна робота - Додати потоки породження/відновлення/перебирання керування. - Додати трансляцію й делегування. - Додати звіти про прогрес і підсумки стану завдання. - Додати запобігання циклам і обмеження частоти. - Додати подання панелі керування. Фаза 5: Multi-Claw - Шардувати сеанси за групами. - Додати leadership/lease для кожного сеансу. - Додати журнал аудиту й відтворення. - Додати ескалацію між групами Claw. ## Приймальні тести - Людина запускає Codex TUI через спільний app-server. - Супервізор перелічує активний потік через `thread/loaded/list`. - Супервізор читає транскрипт через `thread/read`. - Супервізор надсилає текст у неактивний потік через `turn/start`. - Супервізор спрямовує активний потік через `turn/steer`. - Переривання супервізора зупиняє активний хід через `turn/interrupt`. - Codex викликає MCP супервізора й перелічує peer-сеанси. - Автономний Codex породжується й пізніше під’єднується до людини. - Втрачений конектор хоста позначає сеанси як застарілі, не видаляючи історію. ## Відкриті питання - Точний UX під’єднання Codex TUI до потоку app-server, породженого без TUI. - Чи має Codex додати `exec --remote` для headless запусків зі спільним доступом у реальному часі. - Власник durable state: OpenClaw Gateway DB, Cloudflare Durable Object або база даних VPS. - Гранулярність політик схвалення для ходів, ініційованих супервізором. - Скільки підсумку транскрипту слід впроваджувати в контекст постійно активного Claw, а скільки зберігати як інструмент/ресурс.