ClawSpec + OpenSpec 入門：プロジェクトを自動かつ継続的に推進し、中断や手動介入を防ぐ方法

難易度：入門 | 所要時間：20分 | 習得内容：チャットウィンドウでOpenSpecを使用してプロジェクトの全工程を管理し、AIを立ち往生させることなく継続的に稼働させる

---

対象読者

あなたはすでにOpenClawを稼働させ、日常的なタスクの処理に活用しています。その過程で、次のような問題に直面したことがあるかもしれません：

要件は明確に伝わり、エージェントも作業開始を承諾した。しかし、しばらくして確認すると作業が止まっており、こちらが催促するまで進まない。

特に長期タスク、要件変更、対話しながら進めるシナリオにおいて、この問題は顕著です。あなたが必要としているのは、単なる「会話ができるAI」ではなく、要件を整理し、継続的に推進し、人間が監視しなくても自動復旧できる実行システムです。

本書の対象読者：

• すでにOpenClawを使用しており、チャット内でプロジェクトサイクル全体（要件 → 計画 → コード → アーカイブ）を完結させたい方
• エージェントが作業開始後に停滞した経験があり、制御可能な継続実行ソリューションを求めている方
• OpenSpecワークフローに関心があり、それをOpenClawに直接組み込みたい方

---

コア依存関係と環境

GitHub リポジトリ：https://github.com/bytegh/clawspec

---

完全なプロジェクト構造

ClawSpec プラグインのディレクトリ構造（インストール後）：

clawspec/
├── index.ts                    # プラグインのエントリポイント
├── src/                       # コアソースコード
│   ├── service/               # サービス層
│   ├── watcher/               # バックグラウンドwatcher管理
│   ├── stores/                # 状態ストレージ
│   └── hooks/                 # OpenClaw フック
├── skills/                    # OpenSpec skill テキスト（内蔵）
├── test/                      # テストケース
├── openclaw.plugin.json       # プラグイン設定
├── package.json
└── tsconfig.json

実行時、各リポジトリ（repo）の下に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  # journal スナップショット
│   ├── rollback-manifest.json # ロールバック・マニフェスト
│   ├── snapshots/             # change スナップショットのベースライン
│   │   └── <change-name>/
│   │       └── baseline/
│   └── archives/              # アーカイブ済み change
├── openspec/                  # OpenSpec 仕様ディレクトリ
│   └── changes/<change-name>/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/

---

ステップ・バイ・ステップ

Step 1：ClawSpec プラグインのインストール

ClawSpecは3つのインストール方法を提供しています。最初の方法を推奨します：

方法 A：OpenClaw プラグインインストーラー経由（推奨）

openclaw plugins install clawspec@latest

方法 B：ClawHub CLI 経由

npx clawhub@latest install clawspec

方法 C：npm パッケージによる手動インストール（予備手段）

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

@latest は常に npm 上で最後にリリースされた ClawSpec バージョンに解決されます。まだ npm にリリースされていない開発中のコミットをインストールする場合は、ローカルでのチェックアウトまたはダウンロード済みの .tgz パッケージを使用してください。

---

Step 2：OpenClaw の設定

インストール完了後、~/.openclaw/openclaw.json で ACP を有効にし、ClawSpec を設定する必要があります：

{
  "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 が管理するため、追加の設定は必要ありません。

設定が完了したら、gateway を再起動します：

openclaw gateway restart
openclaw gateway status

---

Step 3：ワークスペースとプロジェクトの紐付け

ClawSpec はチャットチャネル（chat channel）ごとにワークスペースを記憶します。チャネルごとに異なるプロジェクトのルートディレクトリを紐付けることができます。

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

期待される結果：

• ClawSpec が現在のチャットチャネルにワークスペースのパスを記憶する
• demo-app ディレクトリが存在しない場合、自動的に作成される
• このリポジトリを初めて選択した際、自動的に openspec init が実行される

---

Step 4：OpenSpec change の作成、プロジェクトコンテキストへの移行

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

このコマンドは以下の3つのことを行います：

1. openspec/changes/add-login-flow/ 配下に標準の足場（proposal.md、design.md、tasks.md、specs/）を作成する
2. ClawSpec が現在追跡されているファイルの快照（スナップショット）ベースラインを取得する（後のロールバック用）
3. 現在のチャットが add-login-flow というアクティブな変更コンテキストに入る

以降のすべてのチャット内容は、attached 状態である限り、自動的に planning journal に書き込まれます。

---

Step 5：チャットでの要件記述

チャットで通常通り要件を説明します。例：

メールアドレスとパスワードによるログインをサポートして。
リフレッシュトークンが必要。
アクセストークンの有効期限は15分にして。

ClawSpec はこれらの内容を自動的に planning-journal.jsonl に追記します。この時点では成果物（artifacts）は更新されず、コードの作成も始まりません。このフェーズは記録のみであり、行動は行いません。

バックグラウンドでの稼働を継続させつつ、現在のウィンドウで別の会話をしたい場合は、以下を使用します：

cs-detach

これにより、通常のチャットが planning journal から切り離されますが、watcher による進捗通知は継続されます。後で元に戻したい場合は、以下を使用します：

cs-attach

---

Step 6：cs-plan、可視化された計画の同期

要件の整理が十分にできたと感じたら、次を実行します：

cs-plan

ClawSpec は現在の表示されているチャットターン内で、以下の成果物を直接更新します：

• proposal.md — プロジェクト提案
• design.md — アーキテクチャ設計
• specs/ — 詳細仕様
• tasks.md — タスクリスト

cs-plan はバックグラウンドの ACP worker を経由せず、隠れた subagent にも依存しません。主チャットウィンドウで AI が成果物を更新していく過程を直接確認できます。

---

Step 7：cs-work、バックグラウンドでの継続実装の開始

計画の更新が完了したら、バックグラウンドでの実装を開始します：

cs-work

cs-work は主チャットウィンドウに直接コードを書き込むのではなく、以下の経路で動作します：

1. 計画（planning）の状態がクリーンであることを検証（dirty な journal はブロックされる）
2. execution-control.json に書き込み、watcher をアクティブにする
3. watcher が acpx を通じて ACP worker セッションを起動する
4. worker が tasks.md に従ってタスクを1つずつ実行し、進捗を更新して worker-progress.jsonl に書き込む
5. watcher が worker の進捗イベントを短いチャットメッセージに変換してユーザーに通知する

チャットウィンドウには、以下のようなメッセージが順次届きます：

[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.

---

Step 8：進捗追跡と復旧

これは ClawSpec の最も核心的な能力の1つです。gateway の再起動後、worker が自動的に継続されます。

gateway が再起動されると、watcher manager は以下を行います：

• すべてのアクティブなプロジェクトをスキャンする
• 生き残っている ACP worker セッションの引き継ぎを優先的に試みる
• 旧 worker が停止している場合、自動的に再武装（arm）して代替 worker を起動する
• タスクの進捗と worker progress offset を保持する

つまり、gateway 再起動後に手動で cs-work を促す必要はありません。ClawSpec が中断された作業を自動的に再開します。

実行中に worker の状態を確認するには：

/clawspec worker status

以下の情報が表示されます：

• 現在設定されている worker エージェント
• 転送層の状態（connected / disconnected）
• 起動フェーズ（loading context / ready / running）
• リアルタイム pid、ハートビート、次のアクションの提案

ACP worker が失敗した場合、ClawSpec は「復旧可能なエラー」と「真のブロッカー」を区別し、復旧可能なエラーに対してはバックオフ（待機時間）を伴う限定回数のリトライを行います。リトライ上限（デフォルト10回）を超えると、プロジェクトは blocked とマークされ、手動での介入が必要になります。

協調的な一時停止と再開：

cs-pause        # 安全な境界で worker を一時停止させる
cs-continue     # planning または implementation を再開する

---

Step 9：アーカイブと終了

すべてのタスクが完了したら、アクティブな変更をクリーンアップします：

/clawspec archive

これにより：

1. OpenSpec change の整合性を検証する
2. 完了した change を archives/ ディレクトリに移動する
3. 現在のチャットにおけるアクティブな変更状態をクリアする

現在の変更を破棄したい場合（コード変更を保持しない場合）：

/clawspec cancel

ClawSpec はリポジトリ全体を git reset --hard するのではなく、スナップショットベースラインから追跡対象のファイルを復元します。

これが一連のワークサイクルです：

要件を話す → cs-plan → cs-work → 進捗を待つ → cs-detach（任意）→ cs-attach（任意）
→ /clawspec archive（完了後）

---

よくあるトラブルシューティング

1. cs-work で「planning sync が必要」と表示される

原因：

• planning journal が dirty になった（スナップショット取得後に新しい要件を話した）
• planning 成果物が欠落しているか、古い
• OpenSpec apply state が依然として blocked である

対処法：

cs-plan
# 計画の更新完了を待つ
cs-work

---

2. Watcher が 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. 通常のチャットが planning journal を汚染した

通常の会話が journal に記録され、その後の cs-work が dirty 判定でブロックされた場合。

直ちに切り離す：

cs-detach

後で要件の議論を再開したいとき：

cs-attach

---

4. Worker は接続されているが、タスクが開始されない

これは通常、ACP worker は起動しているものの、実装プロンプトの消化中、または計画成果物の読み込み中であることを示しています。

以下の2種類のメッセージを優先的に確認してください：

• Watcher 側の状態："starting worker", "ACP worker connected..."
• Worker が出力するロード状態："Preparing <task>: loading context", "Loaded proposal.md", "Context ready..."

"Context ready for ..." が表示されていれば、worker は成果物の読み込みを終えており、間もなく最初のタスクに入ります。

/clawspec worker status を実行し、特に startup phase と startup wait フィールドを見て、worker がどのステップで止まっているか判断してください。

---

5. Worker が "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 で未完了の change（unfinished change）があると表示される

これは想定された挙動です。ClawSpec は、同じリポジトリでアクティブな変更を放置したままにすることを許可しません。

以下の3つから選択してください：

/clawspec continue      # 現在の変更を継続する
/clawspec archive       # 完了した変更をアーカイブする
/clawspec cancel        # 現在の変更を破棄する

---

補足資料 / 発展的な活用

1. OpenSpec CLI の高度な使い方

ClawSpec に内蔵されている OpenSpec CLI 自体が、完全なプロジェクト仕様管理システムです。プロジェクトディレクトリで直接以下を実行できます：

openspec status        # 現在の変更状態を確認
openspec diff          # 現在のファイルとスナップショットの差分を表示
openspec validate      # OpenSpec 仕様の整合性を検証

propose → design → spec → task → apply という OpenSpec の連鎖を深く理解することで、変更の粒度や範囲をより適切に計画できるようになります。

2. ClawSpec による複数チャネル・複数プロジェクトの並行管理

ClawSpec のワークスペースはチャネルごとに記憶されるため、以下のようなことが可能です：

• Telegram チャネルでバックエンド API プロジェクトを管理
• Discord チャネルでフロントエンドプロジェクトを管理
• 同じリポジトリであっても、異なるチャネルで異なるアクティブな変更を持つ（ただし、同一リポジトリでグローバルに許容される未完了の変更は1つだけです）

cs-detach を活用してバックグラウンド作業を継続させ、すべてのチャネルを常に監視し続ける手間を省きましょう。

3. ACP worker のカスタムエージェント設定

グローバルな acp.defaultAgent 以外に、特定のチャネル/プロジェクトごとに worker エージェントを切り替えることができます：

/clawspec worker codex    # 現在のチャネル/プロジェクトで codex を使用
/clawspec worker claude  # claude に戻す

複数のエージェント設定（能力レベルの異なるモデルなど）がある場合、この機能を使用してタスクの複雑さに応じた適切な worker を選択できます。

4. 他の OpenSpec ツールチェーンとの連携

ClawSpec が出力する tasks.md や proposal.md は、他のツール（Superpowers やカスタム CI スクリプトなど）から読み取ることができ、より完全なプロジェクト管理ループを形成できます。OpenSpec の仕様ファイルは純粋な Markdown であり、フォーマットはオープンで特定の UI に縛られません。

5. ClawSpec 設定のカスタマイズ

plugins.entries.clawspec.config には以下のような高度なオプションもあります：

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

allowedChannels フィールドを使用すると、ClawSpec が有効になるチャネルを指定のチャネルだけに制限できます。チーム内でこのワークフローを必要としないチャネルがある場合に適しています。