Начало работы с ClawSpec + OpenSpec: автоматическое и непрерывное продвижение проектов без прерываний и ручного вмешательства

Сложность: Начальный уровень | Время: 20 минут | Результат: управление полным циклом проекта через OpenSpec в окне чата, обеспечивая непрерывную работу ИИ без остановок

---

Целевая аудитория

Вы уже запустили OpenClaw и начали использовать его для повседневных задач. В процессе работы вы могли столкнуться со следующей проблемой:

Требования обсуждены ясно, агент согласился приступить к работе, но через некоторое время вы замечаете, что он остановился, не продвигается дальше и ждет вашего напоминания.

Эта проблема особенно заметна в долгосрочных задачах, при изменении требований или в сценариях «обсуждаем и делаем на ходу». Вам нужен не просто чат-бот, а система исполнения, способная структурировать требования, стабильно продвигать работу, функционировать без надзора и автоматически восстанавливаться.

Эта статья для вас, если вы:

• Уже используете OpenClaw и хотите проходить полный цикл проекта (требования → планирование → код → архивация) прямо в чате.
• Сталкивались с остановкой работы агента и ищете контролируемое решение для непрерывного выполнения.
• Интересуетесь рабочим процессом OpenSpec и хотите интегрировать его непосредственно в OpenClaw.

---

Основные зависимости и окружение

Репозиторий GitHub: https://github.com/bytegh/clawspec

---

Полная структура проекта

Структура каталога плагина ClawSpec (после установки):

clawspec/
├── index.ts                    # Точка входа плагина
├── src/                       # Исходный код ядра
│   ├── service/               # Слой сервисов
│   ├── watcher/               # Управление фоновым вотчером
│   ├── stores/                # Хранилище состояний
│   └── hooks/                 # Хуки OpenClaw
├── skills/                    # Тексты навыков OpenSpec (встроенные)
├── test/                      # Тесты
├── openclaw.plugin.json       # Конфигурация плагина
├── package.json
└── tsconfig.json

Во время выполнения в каждом репозитории создаются файлы управления OpenClaw:

<repo>/
├── .openclaw/clawspec/        # Состояние выполнения ClawSpec
│   ├── state.json             # Текущее состояние проекта
│   ├── execution-control.json # Управление выполнением cs-work
│   ├── execution-result.json  # Результат выполнения
│   ├── worker-progress.jsonl  # Логи фонового прогресса
│   ├── planning-journal.jsonl  # Записи обсуждения требований
│   ├── planning-journal.snapshot.json  # Снапшот журнала
│   ├── rollback-manifest.json # Манифест отката
│   ├── snapshots/             # Базовые линии снимков изменений
│   │   └── <change-name>/
│   │       └── baseline/
│   └── archives/              # Архивы завершенных изменений
├── openspec/                  # Директория спецификаций OpenSpec
│   └── changes/<change-name>/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/

---

Пошаговое руководство

Шаг 1: Установка плагина ClawSpec

ClawSpec предлагает три способа установки, рекомендуется первый:

Способ А: Через установщик плагинов OpenClaw (рекомендуется)

openclaw plugins install clawspec@latest

Способ Б: Через ClawHub CLI

npx clawhub@latest install clawspec

Способ В: Ручная установка npm-пакета (резервный)

$pkg = npm pack clawspec@latest
openclaw plugins install $pkg

@latest всегда указывает на последнюю опубликованную версию в npm. Если вам нужно установить версию в разработке, используйте локальный checkout или скачанный .tgz архив.

---

Шаг 2: Настройка OpenClaw

После установки необходимо включить ACP и настроить ClawSpec в файле ~/.openclaw/openclaw.json:

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "claude"
  },
  "plugins": {
    "entries": {
      "clawspec": {
        "enabled": true,
        "config": {
          "defaultWorkspace": "~/clawspec/workspace",
          "openSpecTimeoutMs": 120000,
          "watcherPollIntervalMs": 4000
        }
      }
    }
  }
}

Описание ключевых параметров:

Если в вашем OpenClaw нет встроенного ACPX, ClawSpec автоматически установит локальную копию. Пути к командам ACPX управляются самим ClawSpec.

После настройки перезапустите шлюз:

openclaw gateway restart
openclaw gateway status

---

Шаг 3: Привязка рабочего пространства и проекта

ClawSpec запоминает рабочее пространство для каждого канала чата. Каждый канал можно привязать к своему корневому каталогу проекта.

/clawspec workspace "D:\clawspec\workspace"
/clawspec use "demo-app"

Ожидаемый результат:

• ClawSpec сохраняет путь к рабочему пространству для текущего канала чата.
• Если каталог demo-app не существует, он будет создан автоматически.
• При первом выборе репозитория автоматически выполнится openspec init.

---

Шаг 4: Создание изменения OpenSpec и вход в контекст проекта

/clawspec proposal add-login-flow "Build login and session handling"

Эта команда выполняет три действия:

1. Создает стандартную структуру папок в openspec/changes/add-login-flow/ (proposal.md, design.md, tasks.md, specs/).
2. ClawSpec создает базовый снимок отслеживаемых файлов (для последующего отката).
3. Текущий чат входит в контекст активного изменения add-login-flow.

Все последующие сообщения в чате (пока статус attached) будут автоматически записываться в журнал планирования (planning journal).

---

Шаг 5: Описание требований в чате

Описывайте ваши требования обычным языком, например:

Поддерживать вход по почте и паролю.
Нужен refresh token.
Срок действия access token — 15 минут.

ClawSpec автоматически добавит это содержимое в planning-journal.jsonl. На этом этапе артефакты не обновляются и код не пишется — это фаза записи, а не действия.

Если вы хотите, чтобы фоновый процесс продолжался, но вы могли обсудить в этом окне другие дела, используйте:

cs-detach

Это отделит обычный чат от журнала планирования, но уведомления от вотчера о прогрессе будут приходить. Чтобы вернуться к записи, используйте:

cs-attach

---

Шаг 6: cs-plan, синхронизация визуального планирования

Когда вы закончите обсуждение требований, выполните:

cs-plan

ClawSpec прямо в текущем видимом окне чата обновит следующие артефакты:

• proposal.md — предложение проекта
• design.md — архитектурный дизайн
• specs/ — подробные спецификации
• tasks.md — список задач

Команда cs-plan не использует фоновый ACP-воркер и не зависит от скрытых субагентов — вы видите процесс обновления артефактов ИИ в основном окне чата.

---

Шаг 7: cs-work, запуск непрерывной фоновой реализации

После того как планирование обновлено, запустите фоновую реализацию:

cs-work

cs-work не пишет код непосредственно в окне чата. Процесс выглядит так:

1. Проверяется чистота состояния планирования (грязный журнал блокируется).
2. Данные записываются в execution-control.json, активируя вотчер.
3. Вотчер через acpx запускает сессию ACP-воркера.
4. Воркер выполняет задачи из tasks.md одну за другой, обновляет прогресс и пишет в worker-progress.jsonl.
5. Вотчер транслирует события прогресса воркера в короткие сообщения чата для вас.

Вы будете получать сообщения вида:

[Watcher] ACP worker connected...
[Worker] Preparing login-flow: loading context
[Worker] Loaded proposal.md
[Worker] Context ready for Task 1
[Worker] Task 1/5 complete: Модуль аутентификации пользователей
[Worker] Task 2/5 complete: Логика обновления токенов
...
[Worker] All tasks complete.

---

Шаг 8: Отслеживание прогресса и восстановление

Это одна из ключевых возможностей ClawSpec — автоматическое возобновление работы воркера после перезапуска шлюза.

При перезапуске шлюза менеджер вотчеров:

• Сканирует все активные проекты.
• Пытается перехватить управление у все еще живых сессий ACP-воркеров.
• Если старый воркер мертв, автоматически подготавливает и запускает нового.
• Сохраняет прогресс задач и смещение логов воркера.

То есть вам не нужно вручную перезапускать cs-work после перезагрузки шлюза. ClawSpec сам подхватит прерванную работу.

Просмотр статуса воркера во время работы:

/clawspec worker status

Это покажет:

• Настроенного агента воркера.
• Статус транспортного уровня (connected / disconnected).
• Фазу запуска (loading context / ready / running).
• Реальный PID, heartbeat и рекомендации по следующим шагам.

При сбое ACP-воркера ClawSpec различает «исправимые ошибки» и «критические блокировки». Для исправимых ошибок применяются повторные попытки с экспоненциальной задержкой. При превышении лимита попыток (по умолчанию 10) проект помечается как blocked, требуя ручного вмешательства.

Совместная пауза и продолжение:

cs-pause        # Приостановить воркера на безопасной границе
cs-continue     # Возобновить планирование или реализацию

---

Шаг 9: Архивация и завершение

Когда все задачи выполнены, очистите активное изменение:

/clawspec archive

Это действие:

1. Проверит целостность изменения OpenSpec.
2. Переместит завершенное изменение в папку archives/.
3. Сбросит статус активного изменения в текущем чате.

Если вы хотите отменить текущее изменение (без сохранения правок в коде):

/clawspec cancel

ClawSpec восстановит отслеживаемые файлы из базового снимка, не выполняя git reset --hard для всего репозитория.

Полный цикл работы:

Обсуждение требований → cs-plan → cs-work → Ожидание прогресса → cs-detach (опц.) → cs-attach (опц.)
→ /clawspec archive (по завершении)

---

Устранение распространенных проблем

1. cs-work сообщает: "Требуется синхронизация планирования" (planning sync required)

Причины:

• Журнал планирования стал грязным (обсуждались новые требования после создания снимка).
• Артефакты планирования отсутствуют или устарели.
• Состояние применения OpenSpec все еще заблокировано.

Решение:

cs-plan
# Дождитесь завершения планирования
cs-work

---

2. Вотчер сообщает, что ACPX недоступен

Причины:

• acp.enabled не включен.
• acp.backend не установлен в acpx.
• acp.defaultAgent не настроен.
• В OpenClaw нет встроенного ACPX, и ClawSpec не нашел доступную копию.

Быстрое исправление:

openclaw config set acp.backend acpx
openclaw config set acp.defaultAgent claude
openclaw gateway restart
cs-work

Если ACPX все еще недоступен, ClawSpec попытается установить локальную копию плагина. Первая установка может занять время и потребовать доступа к сети.

---

3. Обычный чат «загрязнил» журнал планирования

Обычный разговор попал в журнал, из-за чего cs-work блокируется из-за «грязного» статуса.

Немедленное отделение:

cs-detach

Когда захотите снова обсуждать требования:

cs-attach

---

4. Воркер подключен, но не начинает задачи

Обычно это означает, что ACP-воркер запущен, но все еще обрабатывает промпт реализации или считывает артефакты планирования.

Проверьте сообщения:

• Со стороны вотчера: "starting worker", "ACP worker connected...".
• Статус загрузки от воркера: "Preparing <task>: loading context", "Loaded proposal.md", "Context ready...".

Если вы видите "Context ready for ...", значит воркер прочитал артефакты и скоро перейдет к первой задаче.

Запустите /clawspec worker status и обратите внимание на поля startup phase и startup wait, чтобы понять, на каком этапе застрял воркер.

---

5. Ошибка воркера "stdin is not a terminal" или сессия не создается

Причины:

• В ~/.acpx/config.json есть пользовательские настройки агентов (например, agents.codex указывает на локальный путь CLI).
• ACPX не может запустить агента через raw CLI в неинтерактивной среде.

Запустите диагностику:

/clawspec doctor

Если обнаружены проблемы в конфиге, используйте автоисправление:

/clawspec doctor fix

Ручное исправление: отредактируйте ~/.acpx/config.json, установив "agents" как пустой объект:

{
  "agents": {}
}

---

6. /clawspec use сообщает о незавершенном изменении

Это ожидаемое поведение. ClawSpec не позволяет молча оставить активное изменение в том же репозитории.

Выберите одно из трех:

/clawspec continue      # Продолжить текущее изменение
/clawspec archive       # Архивовать завершенное изменение
/clawspec cancel        # Отменить текущее изменение

---

Дополнительное чтение / Продвинутые темы

1. Продвинутое использование OpenSpec CLI

Встроенный в ClawSpec OpenSpec CLI сам по себе является полноценной системой управления спецификациями. Вы можете запускать его прямо в каталоге проекта:

openspec status        # Проверить статус текущего изменения
openspec diff          # Сравнить текущие файлы с базовым снимком
openspec validate      # Проверить целостность спецификаций OpenSpec

Понимание цепочки propose → design → spec → task → apply позволит вам лучше планировать объем и детализацию изменений.

2. Параллельное управление проектами в разных каналах

Рабочие пространства ClawSpec привязаны к каналам, что позволяет:

• В Telegram управлять проектом Backend API.
• В Discord управлять проектом Frontend.
• В одном репозитории могут быть разные активные изменения в разных каналах (но глобально для одного репо разрешено только одно незавершенное изменение одновременно).

Используйте cs-detach, чтобы фоновая работа продолжалась, не требуя вашего внимания в каждом канале.

3. Настройка пользовательских агентов ACP-воркеров

Помимо глобального acp.defaultAgent, вы можете переключать агента воркера для конкретного канала или проекта:

/clawspec worker codex    # Использовать codex для текущего канала/проекта
/clawspec worker claude  # Переключиться обратно на claude

Это полезно для выбора подходящего воркера в зависимости от сложности задачи.

4. Совместная работа с другими инструментами OpenSpec

Файлы tasks.md и proposal.md, созданные ClawSpec, могут считываться другими инструментами (например, Superpowers или кастомными CI-скриптами), формируя замкнутый цикл управления проектом. Формат OpenSpec — это чистый Markdown, он открыт и не привязан к конкретному интерфейсу.

5. Кастомизация конфигурации ClawSpec

В plugins.entries.clawspec.config доступны расширенные опции:

{
  "clawspec": {
    "enabled": true,
    "config": {
      "archiveDirName": "archives",
      "allowedChannels": ["ch_xxx", "ch_yyy"]
    }
  }
}

Поле allowedChannels позволяет ограничить работу ClawSpec только определенными каналами, что удобно для команд, где этот рабочий процесс нужен не везде.