OpenClaw連携

OpenClaw は、会話型AIエージェントを構築するためのオープンソースフレームワークです。 名前付きスロットを持つモジュラープラグインシステムを採用しており、 各スロットはエージェントパイプラインの特定の部分を制御します。

最も重要なスロットはcontextEngineです。 これはLLM呼び出しの前にシステムプロンプトに注入されるコンテキストを決定するプラグインです。 エージェントが何を記憶し、何を知り、何を感じるかを制御します。

OpenClawのプラグインシステムはミドルウェアのように動作します。 各プラグインは会話ターンの特定のポイントで発火するライフサイクルフックを実装します：

デフォルトでは、OpenClawはローカルのMarkdownファイルとして記憶を保存する基本的なコンテキストエンジンを搭載しています。 Sonzaiプラグインはこれをmind Layerに置き換え、追加コードなしで永続的な記憶、パーソナリティの進化、 感情追跡、関係性モデリングをエージェントに提供します。

プラグイン登録の仕組み

@sonzai-labs/openclaw-contextをインストールすると、パッケージはデフォルトエクスポートとしてregister()関数を公開します。起動時にOpenClawはインストール済みの すべてのプラグインをロードし、register関数を呼び出します。 このプラグインは"sonzai"という名前でコンテキストエンジンファクトリを登録します：

// @sonzai-labs/openclaw-context の内部（開発者が書くコードではありません）
export default function register(api) {
  api.registerContextEngine("sonzai", () => {
    return new SonzaiContextEngine(client, config);
  });
}

次にopenclaw.jsonで、contextEngineスロットにどの登録済みエンジンを使用するかをOpenClawに指示します。"sonzai"という名前はプラグインが登録したものと一致する必要があります：

{
  "plugins": {
    "slots": {
      "contextEngine": "sonzai"    // ← register() で登録した名前と一致
    },
    "entries": {
      "sonzai": {                  // ← プラグインに渡される設定
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "your-agent-uuid"
      }
    }
  }
}

フローは次の通りです：npmパッケージをインストール → OpenClawがregister()を検出・呼び出し → プラグインが"sonzai"として登録 → 設定がcontextEngineスロットに割り当て。

1. APIキーの取得

Sonzaiプロジェクト設定からAPIキーを取得してください。セットアップウィザード中に入力すると、openclaw.jsonに保存されます。

2. プラグインのインストール

# OpenClaw CLIでインストール
openclaw plugins install @sonzai-labs/openclaw-context

# またはパッケージマネージャーで直接インストール
npm install @sonzai-labs/openclaw-context
# bun add @sonzai-labs/openclaw-context

3. セットアップウィザードの実行

セットアップウィザードがOpenClawプロジェクトとMind Layerの接続をガイドします：

npx @sonzai-labs/openclaw-context setup

ウィザードの流れ：

• APIキーの入力を求めます（または環境からSONZAI_API_KEYを検出）
• 既存のエージェントIDがあるか、新しいエージェント名を選んで作成するかを確認
• Mind LayerでAPIキーを検証
• APIキーとプラグイン設定をopenclaw.jsonに保存

セットアップ後のopenclaw.jsonは次のようになります：

{
  "plugins": {
    "slots": {
      "contextEngine": "sonzai"
    },
    "entries": {
      "sonzai": {
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "a1b2c3d4-..."
      }
    }
  }
}

4. チャットを開始

通常通りOpenClawを起動してください。プラグインはsonzaiコンテキストエンジンとして登録され、コンテキスト組み立てを自動的に引き継ぎます：

openclaw chat

これで完了です。すべての会話がMind Layerを通過し、 エージェントは最初のメッセージから永続的な記憶、パーソナリティ、感情を持ちます。

すべての設定はopenclaw.jsonのplugins.entries.sonzaiに記述します。 環境変数はオーバーライドとして使用できます。

disableマップを使用して、特定のコンテキストソースを選択的に無効化できます。 Mind Layerをメモリとして使用したいが感情追跡は不要な場合や、 トークン使用量を削減したい場合に便利です：

{
  "plugins": {
    "entries": {
      "sonzai": {
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "your-agent-uuid",
        "disable": {
          "mood": true,
          "personality": false,
          "relationships": true,
          "memory": false,
          "goals": true,
          "interests": true,
          "habits": true
        }
      }
    }
  }
}

上記の設定では、パーソナリティとメモリのコンテキストのみが注入されます。 Mind Layerを純粋な記憶・パーソナリティストアとして使用する場合に最適です。

各ターンで、プラグインは構造化された<sonzai-context>ブロックをシステムプロンプトに注入します。 セクションは優先度順に並べられ、トークンバジェットを超過した場合は優先度の低いものから削除されます：

プラグインはOpenClawのセッションキー形式からユーザーIDを自動的に抽出します。 これにより、設定なしでユーザーごとの記憶と関係性が可能になります：

マルチテナントデプロイメントでエージェントをプログラマティックにプロビジョニングする場合は、setup()関数を直接使用します：

import { setup } from "@sonzai-labs/openclaw-context";

const result = await setup({
  apiKey: "sk-project-key",
  agentName: "customer-support-bot",
  configPath: "/path/to/openclaw.json",
});

console.log(result.agentId);   // 決定論的UUID（tenantID + agentName の SHA1）
console.log(result.written);   // true — 設定ファイルが更新された

SonzaiコンテキストエンジンはOpenClawのライフサイクルフックに接続します。 1回の会話ターンのフローは次の通りです：

OpenClaw Runtime                SonzaiContextEngine              Sonzai Mind Layer
      |                                    |                                |
      |-- bootstrap(sessionId) ----------->|                                |
      |                                    |-- resolve agent + session ---->|
      |                                    |<-- session state cached -------|
      |                                    |                                |
      |-- assemble(messages, budget) ----->|                                |
      |                                    |-- fetch context (memory,       |
      |                                    |   personality, mood,           |
      |                                    |   relationships) ------------>|
      |                                    |<-- ranked context blocks ------|
      |                                    |                                |
      |<-- systemPromptAddition -----------|   (priority-ordered,           |
      |                                    |    budget-trimmed)             |
      |                                    |                                |
      |  [LLM call with enriched prompt]   |                                |
      |                                    |                                |
      |-- afterTurn(sessionId) ----------->|                                |
      |                                    |-- send conversation ---------> |
      |                                    |   Mind Layer extracts facts,   |
      |                                    |   updates mood, evolves        |
      |                                    |   personality automatically    |
      |                                    |                                |
      |-- compact(sessionId) ------------->|                                |
      |                                    |-- merge short-term → long-term>|
      |                                    |<-- compacted ------------------|

コンテキストエンジンはMind Layerとのすべての通信を処理します。assemble中に、コンテキストソース（記憶、パーソナリティ、感情、関係性、目標、興味、習慣）を取得し、 優先度順にランク付けして、トークンバジェットに合わせてトリミングします。afterTurn中に、事実抽出と状態更新のために会話をMind Layerに送信します。 エンジンはローカルでLLM呼び出しを実行しません。すべてのインテリジェンスはSonzai側にあります。

パッケージは以下の高度な使用向けエクスポートを提供します：